Skip to content

Quickstart

This section describes how to get started with this project: how to clone or create your own copy, and how to launch the app in different ways (locally, with Docker, or in Codespaces).

How to Get the Project

!

If you want to start your own project based on this boilerplate, use GitHub’s “Use this template” button:

workflow

  1. Go to the repository page.
  2. Click Use this template (top right).
  3. Create a new repository under your GitHub account.
  4. Clone your new repository: 
    git clone https://github.com/<your-username>/<your-new-repo>.git
cd <your-new-repo>

If you want to contribute here or just try the boilerplate as-is:

workflow

  1. Go to the repository page.
  2. Click Code > Download ZIP (or clone the repo).
  3. Extract the ZIP file (if used).
  4. Navigate into the project directory: 
    cd uv-template

How to Run the Project

!

workflow

  1. On GitHub, click Code > Codespaces > Create codespace on main.
  2. Or, open the project in VS Code with the Dev Containers extension.
  3. Choose “Reopen in Container” when prompted.
  4. Wait while all dependencies and tools are installed automatically.
  5. You can now use all make commands, run the app, tests, etc.

Requirements: Python 3.10+, uv (or pip if you know what you’re doing).

workflow

  1. Install uv (recommended): 
    curl -LsSf https://astral.sh/uv/install.sh | sh
  2. Install dependencies & set up pre-commit hooks: 
    make init
  3. Run the app: 
    make run
  4. Run tests, linter, formatter as needed: 
    make test
make lint
make format

Best for: Consistent dev environment, works anywhere Docker runs.

workflow

  1. Build the development Docker image: 
    make dev-build
  2. Start the dev container (in background): 
    make dev-up
  3. Enter a shell in the container (if needed): 
    make dev-exec
  4. View logs, stop, or remove the container as needed: 
    make dev-logs
make dev-stop
make dev-down

Dev Docker specifics

  • Uses dev.Dockerfile and dev.dockerignore
    • Before building it runs cp dev.dockerignore .dockerignore to specify files to ignore
  • Loads environment from .env.development
  • Supports hot reload and development tools

Best for: Testing production-like runs or deployment.

workflow

  1. Build the production image: 
    make prod-build
  2. Run the production container: 
    make prod-run
  3. Enter a shell in the container (if needed): 
    make prod-exec
  4. Run container with bash or view logs: 
    make prod-bash # temporary, with .env.production and with --rm flag
make prod-logs

Prod Docker specifics

  • Uses prod.Dockerfile and prod.dockerignore
    • Before building it runs cp prod.dockerignore .dockerignore to specify files to ignore
  • Loads environment from .env.production
  • Optimized for minimal size and performance

Useful Tips

  • All common tasks (init, test, lint, format, docs, etc.) are available as simple make commands.
  • See docs/usage/commands.md for the full list.
  • Environments and secrets are configured via .env.* files (see .env.example).
  • The project is ready for CI/CD with GitHub Actions and GitLab CI out of the box.

Troubleshooting

  • If you have permission errors with git hooks, run: 
    chmod +x .git/hooks/*
  • For Docker issues, ensure Docker is running and you have permissions (try sudo if needed).
  • For Codespaces/Dev Containers, see the Dev Containers docs.

More Info