Docker

Every Codabra project is scaffolded with a ready-to-use Docker setup. All configuration lives under the docker/ directory at your project root.

Generated files

my-app/
├── docker/
│   ├── <provider>/
│   │   └── Dockerfile          ← provider-specific multi-stage image
│   ├── docker-compose.dev.yml  ← database services only (app runs locally)
│   └── docker-compose.prod.yml ← full stack: app + databases
└── Makefile                    ← shorthand commands for both environments

Each provider gets its own Dockerfile inside docker/<provider>/. This lets every framework define its own build steps while sharing the same compose infrastructure.

The Docker config is regenerated automatically whenever you run:

• codabra create — initial scaffold
• codabra add-provider — adds a new provider's Dockerfile and updates compose services
• codabra upgrade — syncs config to the latest Codabra conventions

Development environment

In dev mode only the database services run in Docker. The app itself runs locally (via codabra dev) for instant hot-reload.

SQLite

SQLite is a local file — no Docker service is needed. docker-compose.dev.yml will be empty and make dev-up is a no-op.

PostgreSQL / MySQL

# Start database containers
make dev-up

# Then start the dev server (also starts containers automatically)
pnpm codabra dev

codabra dev automatically runs docker compose -f docker/docker-compose.dev.yml up -d before starting the app, so you rarely need to call make dev-up manually.

The generated .env.local in your app directory contains a pre-filled DATABASE_URL that matches the Docker service credentials:

Database	.env.local value (default)
PostgreSQL	postgresql://postgres:postgres@localhost:5432/<project>_dev
MySQL	mysql://root:root@localhost:3306/<project>_dev

Production environment

The production compose file runs the full stack — app container(s) plus database(s).

# Build and start everything
make prod-up

# Or just build images without starting
make prod-build

Sensitive values (POSTGRES_PASSWORD, DATABASE_URL, etc.) must be provided via environment variables or a .env file at the project root — they are intentionally left unset in the generated config and will cause an explicit error if missing.

Example .env for production:

DATABASE_URL=postgresql://postgres:s3cr3t@postgres:5432/myapp_prod
POSTGRES_PASSWORD=s3cr3t
PORT=3000

Makefile reference

Target	Description
make dev-up	Start database containers in the background (dev)
make dev-down	Stop and remove database containers (dev)
make dev-restart	Restart database containers (dev)
make dev-build	Rebuild database images (dev)
make prod-up	Start the full stack in the background (prod)
make prod-down	Stop and remove all containers (prod)
make prod-restart	Restart all containers (prod)
make prod-build	Build all images (prod)

Docker installation

When you create a project or add a provider that requires a database service, Codabra checks whether Docker is installed:

• If Docker is found: setup continues automatically.
• If Docker is missing on Linux: you are prompted to install it via the official script (curl -fsSL https://get.docker.com | sh).
• If Docker is missing on macOS: the CLI suggests brew install --cask docker or Docker Desktop.
• If Docker is missing on Windows: the CLI points to the Docker Desktop installer.

You can always skip the install and run make dev-up manually later once Docker is available.

Adding a new provider

Running codabra add-provider and selecting a new framework regenerates all Docker files. The new provider gets its own docker/<provider>/Dockerfile and — if it uses a different database — its corresponding service is added to both compose files.

Customising the Dockerfile

The Dockerfile at docker/<provider>/Dockerfile is generated by Codabra but is yours to edit. It is overwritten on every codabra upgrade to stay in sync with new conventions — if you need project-specific customisations, add them after the last FROM stage or use a multi-stage ONBUILD approach.