FastAPI + Docker + GitHub Actions + GHCR + GitHub Pages (Jekyll)

1) Run locally

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
pytest -q
uvicorn app.main:app --reload

2) Run with Docker

# Run tests during build (multi-stage target)
docker build --target test -t fastapi-starter:test .

# Build runtime image
docker build --target runtime -t fastapi-starter:latest .

# Run
docker run --rm -p 8000:8000 fastapi-starter:latest

3) CI: GitHub Actions + GHCR

Workflow: .github/workflows/ci.yml

• PRs: build test stage (runs pytest)
• main branch pushes: build runtime stage and push to ghcr.io/<owner>/<repo>

To pull after push:

docker pull ghcr.io/<owner>/<repo>:latest

Ensure your repo has Packages enabled. The workflow uses secrets.GITHUB_TOKEN.

4) Docs: GitHub Pages (Jekyll)

Docs live in /docs. Workflow: .github/workflows/pages.yml

In GitHub:

• Settings → Pages
• Source: GitHub Actions

5) Run GitHub Actions locally (nektos/act)

Install act, then:

# Run the CI workflow locally
act -W .github/workflows/ci.yml

# Run pages build locally (deploy step is skipped unless you provide tokens)
act -W .github/workflows/pages.yml

If you use Apple Silicon and hit platform issues:

act --container-architecture linux/amd64 -W .github/workflows/ci.yml