Skip to content

getting-started.md

Latest commit

 

History

History
197 lines (130 loc) · 9.82 KB

getting-started.md

File metadata and controls

197 lines (130 loc) · 9.82 KB

Note

This file is maintained by the foundry-python template and will be updated when you run mise run update_from_template.

Getting Started: Foundry Python Core

This getting started guide covers everything needed to get this project fully operational.

Toolchain

This project was scaffolded using foundry-python:

Category Tools
Code Quality Ruff (linting), PyRight (type checking)
Git Hooks pre-commit, detect-secrets, pygrep, Commitizen
Testing pytest (parallel execution), Nox (matrix testing), Codecov (coverage)
CI/CD GitHub Actions (workflows), act (local testing)
Security SonarQube, pip-audit, trivy, Dependabot
Dependencies Renovate (updates), pip-licenses (compliance)
Observability Sentry (errors, tracing, profiling), BetterStack (uptime monitoring)
Documentation SBOM generation (CycloneDX, SPDX), auto-generated attributions, dynamic badges
AI Assistance GitHub Copilot (custom instructions), Claude Code (PR reviews)

Verify Installation

Before configuring services, confirm the local environment is working:

mise run install
mise run test

All tests should pass. If not, run mise run install first.

Service Connections

Service Purpose Status
GitHub Repository Settings Security alerts, Dependabot
Google Artifact Registry Package publishing
SonarCloud Code quality analysis
Renovate Dependency updates
CodeCov Badge Coverage badge
Sentry Error monitoring
Repository Polish Discoverability
Slack Release Notifications Release notifications
Background Worker Chancy job queue

GitHub Repository Settings

Why: Ensures dependency vulnerability scanning is active.

  1. Go to https://github.com/aignostics/foundry-python-core/settings/security_analysis
  2. Verify Dependabot alerts is enabled (on by default via enterprise policy)
  3. Verify Dependabot security updates is enabled (on by default via enterprise policy)
  4. Do NOT enable Dependabot version updates — Renovate handles this
  5. (Public repos only) Enable Private vulnerability reporting

Google Artifact Registry

Why: Allows CI to access our private Python registry.

  1. Add your repository to the github_repositories list in this file; follow the usual process to apply the Terragrunt changes
  2. Go to https://github.com/aignostics/foundry-python-core/settings/secrets/actions/new and create a new repository secret called GCP_WORKLOAD_IDENTITY_PROVIDER with value projects/359433074524/locations/global/workloadIdentityPools/github-python-library-repos/providers/github-provider

Verify: the Setup Dev Environment action succeeds in lint, test or audit workflow

SonarCloud

Note: Requires SonarCloud admin access. Your team lead should have admin access; if not, ask in #topic-foundry.

  1. Go to https://sonarcloud.io/projects/create, select your new repo and click "Set Up"
  2. Select Previous Code when prompted
  3. Go to https://sonarcloud.io/project/settings?id=aignostics_foundry-python-core → Administration > Analysis Method → disable Automatic Analysis
  4. For private repositories — update the quality badge in README.md:

CodeCov Badge

For private repositories, the badge URL requires a token:

  1. Go to https://app.codecov.io/gh/aignostics/foundry-python-core/config/badge
  2. Under "Embed via API", copy the token value from the URL
  3. In your README.md, replace CODECOV_BADGE_TOKEN with the copied token

After Merging — Complete the Setup

The following do not block this PR. Complete them after merge to finish the project setup.

Automated — No Action Required

These services are active automatically at the organisation level:

Service Purpose Notes
SonarCloud Code quality & security analysis SONAR_TOKEN is org-wide; quality gate runs on every PR
Sentry Error monitoring Org-level integration; scans PRs automatically
Ox Security Supply chain security Org-level integration; scans PRs automatically
CodeQL Static security analysis Runs weekly (Tuesdays 3:22 AM UTC) via included workflow
CodeCov Coverage tracking & PR comments Org-level; coverage uploads automatic
Dependabot Dependency vulnerability alerts Enabled by default via enterprise policy
Claude Code AI-powered PR reviews (claude label) ANTHROPIC_API_KEY is org-wide; no setup required

Renovate

Why: Automated dependency updates with smart grouping and scheduling (complements Dependabot which handles security patches).

  1. Go to https://developer.mend.io and sign in with your GitHub account
  2. Go to https://developer.mend.io/github/aignostics/foundry-python-core and click Action > Run Renovate scan
  3. Renovate creates a Dependency Dashboard issue in your repository

Verify: Dependency Dashboard issue appears in your repository

Sentry — Advanced Setup

For error tracking, performance profiling, and release tracking, configure the Sentry DSN in your application code. Basic PR scanning is already active at the org level.

Repository Polish

  1. Go to https://github.com/aignostics/foundry-python-core
  2. Click the cogs icon next to "About"
  3. Copy the description from pyproject.toml into the description field
  4. Copy up to 20 tags from pyproject.toml into the topics field
  5. Go to https://github.com/aignostics/foundry-python-core/settings and upload a social preview image (e.g. logo.png)

Slack Release Notifications

Why: Notifies #announce-foundry when a new version is published.

No secrets needed — the Slack webhook is configured at the org level. No action required; verify by publishing a release.

Background Worker

This project includes a Chancy background worker powered by PostgreSQL.

What was scaffolded

  • src/foundry_python_core/scheduler/ — the scheduler module (service, CLI, API, settings)
  • src/foundry_python_core/hello_world/_jobs.py and src/foundry_python_core/system/_jobs.py — example job definitions
  • migrations/versions/0002_add_scheduler_heartbeats.py — database migration for the heartbeat table
  • deployment/cloudrun/service-worker.template.yaml — Cloud Run worker service definition

Run the worker locally

Start everything with Docker Compose (the worker service starts alongside the API and PostgreSQL):

docker compose up

Or run the worker directly:

# Apply the scheduler database migration first
uv run foundry-python-core scheduler db migrate

# Register job definitions
uv run foundry-python-core scheduler joblets register

# Start the worker
uv run foundry-python-core scheduler execute

The Chancy web UI is available at http://127.0.0.1:8001 by default (configurable via FOUNDRY_PYTHON_CORE_SCHEDULER_API_HOST and FOUNDRY_PYTHON_CORE_SCHEDULER_API_PORT).

Database migration

The scheduler requires its own migration to create the heartbeat table. This runs automatically at startup in production (see deployment/cloudrun/service.template.yaml). Locally, run:

uv run foundry-python-core scheduler db migrate

Further Reading