Deploy by project type
Container Apps (Docker Compose)
When to use a Container App#
- Frontend and backend in one repository, deployed together.
- Your app needs its own database, Redis, or message queue.
- A background worker or scheduler runs next to the API.
- A monorepo, where the code lives in sub-folders rather than at the root.
- Anything that must keep files on disk (uploads, a database) — Compose volumes persist.
A single stateless API is simpler as a Web service.
1. Name and place the file#
The Compose file must be at the root of the repository. If several exist, the first of these is used:
1. docker-compose.prod.yml
2. docker-compose.prod.yaml
3. docker-compose.production.yml
4. docker-compose.production.yaml
5. compose.prod.yml
6. compose.prod.yaml
7. compose.production.yml
8. compose.production.yaml
9. compose.yaml
10. compose.yml
11. docker-compose.yaml
12. docker-compose.ymlKeep your dev file — add a production one
Most repositories already have a docker-compose.yml for local development, with source folders mounted in for hot reload. Leave it as it is and add a docker-compose.prod.yml next to it: production names are always picked first, so developers keep their setup and the platform never sees it. Only the one file is read — docker-compose.override.yml is not merged in.
You don't choose "Container App" anywhere: create the service with New → Web service and the Compose file is detected when the build runs. The log says Found docker-compose.prod.yml — building it as a Container App (3 services).
2. What a Compose file may contain#
The file is checked before anything is built, and every problem is listed in the build log at once. These are refused because they would give a container access to the server itself:
| Not allowed | Use instead |
|---|---|
Bind mounts — ./src:/app, /var/data:/data | A named volume (app_data:/data). Bind mounts point at folders that don't exist on the server, and would hide the code built into your image. |
privileged: true, cap_add, devices, security_opt | Nothing — not available to apps. |
network_mode: host, pid: host, ipc: host, and the same for uts, userns_mode, cgroup | The app's private network — services reach each other by name. |
runtime, cgroup_parent | Nothing. |
External volumes or networks, non-local volume drivers, driver_opts | Plain named volumes and the default network. |
File-based or external secrets: and configs: | Environment variables (below). |
build with dockerfile_inline, additional_contexts, ssh or secrets; a context that is a URL or outside the repository | A normal build: { context, dockerfile, args, target } pointing at a folder in the repository. |
What is supported:
build:withcontext,dockerfile,argsandtarget— each service built from its own folder.image:— public images (Docker Hubmongo:7,postgres:16,redis:7…) are pulled on the server.- Named volumes and
tmpfs. environment,healthcheck,depends_on(includingcondition: service_healthy),command,entrypoint,expose,restart, resource limits.
ports: are ignored — and that's fine
Published ports: are removed (nothing is exposed on the server directly — all traffic comes through the HTTPS router). They are still read as a hint for which service is public. Private images from other registries can't be pulled; build them from source in the Compose file instead.
3. Which service gets the public address#
One service receives the HTTPS address — usually your frontend or API gateway. It is chosen in this order:
A service labelled crowther.public: "true"
The clearest option. Always use it when more than one service declares a port.
Otherwise, the only service with ports:
If exactly one service publishes ports, it is public.
Otherwise, the only service with expose:
Same rule for
expose.
The port traffic is sent to comes from a crowther.port label, otherwise the service's first ports / expose entry — the container side, so "8080:80" means 80.
services:
web:
build: ./frontend
labels:
crowther.public: "true"
crowther.port: "80"Two services with ports and no label → no public address
The build log says Several services declare ports (…), so none is made public automatically. Add the label. An app with no public service at all (only workers) is valid — it simply gets no URL.
4. Environment variables and secrets#
Put secrets in the service's Environment tab in the dashboard, and reference them in the Compose file with ${NAME}. At deploy time they are written to a protected file on the server that Compose reads — they never appear in your repository or in the stored configuration.
services:
api:
build: ./backend
environment:
NODE_ENV: production # fixed value, fine to commit
DATABASE_URL: ${DATABASE_URL:?DATABASE_URL is required} # must be set, or the build stops
LOG_LEVEL: ${LOG_LEVEL:-info} # optional, with a default
STRIPE_SECRET_KEY: ${STRIPE_SECRET_KEY}| Syntax | Meaning |
|---|---|
${NAME} | The dashboard value, or empty if unset. |
${NAME:-default} | The dashboard value, or default if unset or empty. |
${NAME:?message} | Required. If unset, the build fails with your message — better than an app that starts half-configured. |
A variable must be referenced to reach a container
Setting API_KEY in the dashboard does nothing unless some service has API_KEY: ${API_KEY} in its environment. The build log lists any dashboard variables the Compose file never uses.
Don't use env_file for secrets
env_file: is read from your repository while building, so its contents become part of the stored app definition. Keep secrets in the dashboard and reference them with ${…}.
5. Build arguments (build-time values)#
Frontend builds bake values like the API URL into the JavaScript. A Container App can pass dashboard variables into the build through args — the one place build-time values come from the dashboard:
services:
web:
build:
context: ./frontend
args:
VITE_API_URL: ${VITE_API_URL:-} # empty = same origin, see belowFROM node:20-alpine AS build
WORKDIR /app
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run buildChanging a build argument needs a new build: Settings → Redeploy (or Builds → Trigger build), or simply your next push. Deployments → Redeploy isn't enough, because it restarts the existing image without rebuilding it.
6. Data that must survive: named volumes#
A named volume keeps its data across deploys and restarts. Declare it at the top level and mount it:
services:
db:
image: postgres:16-alpine
volumes:
- db_data:/var/lib/postgresql/data
volumes:
db_data:- Backed up every night at 02:00 UTC to separate storage, kept 7 days (Sunday's backup: 21 days).
- The app stays on its server. Its volumes live on that machine, so a Container App with data is never moved to another server automatically.
- Deleting the app keeps its backups for the same 7/21 days, so a mistaken delete can still be recovered.
- Renaming a volume in the file creates a new, empty one. Keep volume names stable.
7. How services find each other#
The service overview's Architecture card shows each container and the connections inferred from depends_on, links, and environment values naming another container as a host. Arrows point from the caller to the container it uses. Hover or keyboard-focus a box or line to see the reasons; only variable names are shown, never their values. The public container has an Internet connection.
Moving dots illustrate the app's running status, with slower motion during a deployment. They do not measure traffic or individual container health. Inactive apps keep grey, still connections. Motion respects reduced-motion preferences and pauses while the tab is hidden. On small screens, scroll inside the card.
Every service in the file shares a private network and is reachable by its service name. The database above is db:5432 from the API; nothing outside the app can reach it.
DATABASE_URL=postgresql://app:secret@db:5432/app
REDIS_URL=redis://cache:6379
MONGO_URL=mongodb://mongo:270178. Health checks and start-up order#
A deploy waits until every container is running, and every container with a healthcheck is healthy — for up to 15 minutes. Give databases a healthcheck and make your API wait for it, so the API never starts against a database that isn't ready:
services:
db:
image: postgres:16-alpine
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
interval: 5s
timeout: 5s
retries: 12
api:
build: ./backend
depends_on:
db:
condition: service_healthyThe healthcheck command runs inside the container, so use a tool the image has: wget on Alpine, python -c on slim Python images, mongosh for MongoDB, pg_isready for Postgres, redis-cli ping for Redis.
Example: React + FastAPI + MongoDB#
A frontend served by nginx, which also forwards /api to the backend — so the browser only ever talks to one address and no API URL has to be baked in. Repository layout:
.
├── docker-compose.yml # local development (bind mounts, hot reload)
├── docker-compose.prod.yml # what the platform deploys
├── backend/
│ ├── Dockerfile
│ ├── requirements.txt
│ └── app/main.py
└── frontend/
├── Dockerfile
├── nginx.conf
└── src/…services:
mongo:
image: mongo:7
restart: unless-stopped
volumes:
- mongo_data:/data/db
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
interval: 10s
timeout: 5s
retries: 12
start_period: 20s
backend:
build:
context: ./backend
restart: unless-stopped
depends_on:
mongo:
condition: service_healthy
environment:
MONGO_URL: mongodb://mongo:27017
DB_NAME: ${DB_NAME:-app}
JWT_SECRET: ${JWT_SECRET:?JWT_SECRET is required}
CORS_ORIGINS: ${CORS_ORIGINS:-}
volumes:
- uploads:/app/uploads
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/health', timeout=4)"]
interval: 15s
timeout: 5s
retries: 8
start_period: 30s
frontend:
build:
context: ./frontend
restart: unless-stopped
depends_on:
backend:
condition: service_healthy
labels:
crowther.public: "true"
crowther.port: "80"
volumes:
mongo_data:
uploads:server {
listen 80;
root /usr/share/nginx/html;
# The API, on the same address — no CORS, no API URL to configure.
location /api/ {
proxy_pass http://backend:8000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 300s;
client_max_body_size 25m;
}
# Client-side routing: unknown paths get the app.
location / {
try_files $uri $uri/ /index.html;
}
}FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM nginx:1.27-alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80FROM python:3.12-slim
WORKDIR /app
ENV PYTHONUNBUFFERED=1
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--proxy-headers", "--forwarded-allow-ips", "*"]Inside a Container App, services can use any port they like (8000 here) — only the public service's port matters, and the label says it is 80. Dashboard variables for this app: JWT_SECRET, and optionally DB_NAME and CORS_ORIGINS.
Server-Sent Events and WebSockets through nginx
For streaming endpoints add proxy_buffering off; (SSE) or the Upgrade / Connection headers (WebSockets) to that location, or long-lived connections stall.
Example: Node API + worker + PostgreSQL + Redis#
services:
db:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER:-app}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
POSTGRES_DB: ${POSTGRES_DB:-app}
volumes:
- pg_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-app}"]
interval: 5s
timeout: 5s
retries: 12
cache:
image: redis:7-alpine
restart: unless-stopped
command: ["redis-server", "--appendonly", "yes"]
volumes:
- redis_data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
retries: 10
api:
build: .
restart: unless-stopped
depends_on:
db: { condition: service_healthy }
cache: { condition: service_healthy }
environment: &app-env
NODE_ENV: production
PORT: "3000"
DATABASE_URL: postgresql://${POSTGRES_USER:-app}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB:-app}
REDIS_URL: redis://cache:6379
JWT_SECRET: ${JWT_SECRET:?JWT_SECRET is required}
expose:
- "3000"
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/health"]
interval: 15s
retries: 5
start_period: 20s
worker:
build: . # same image as the API…
command: ["node", "dist/worker.js"] # …different process
restart: unless-stopped
depends_on:
db: { condition: service_healthy }
cache: { condition: service_healthy }
environment: *app-env
volumes:
pg_data:
redis_data:Only api declares expose, so it becomes public on port 3000 without a label. The worker reuses the same build with a different command, and the YAML anchor (&app-env / *app-env) keeps their environment identical.
Database migrations
Run migrations when the API container starts (for example an entrypoint that runs prisma migrate deploy or alembic upgrade head before starting the server), not during the image build — the database is not reachable while building.
Monorepos and code in sub-folders#
Single services only look at the repository root. With code in sub-folders, a root Compose file whose build.context points into each folder deploys them all — even if you only need one:
services:
api:
build:
context: ./services/api # the folder the Dockerfile's COPY paths are relative to
dockerfile: Dockerfile # relative to the context
expose: ["3000"]A Dockerfile that needs files from outside its folder (a shared packages/ directory) should use the repository root as the context and name the Dockerfile explicitly:
build:
context: .
dockerfile: services/api/DockerfileDeploy it#
Test the production file locally
bashdocker compose -f docker-compose.prod.yml config # validates and shows the resolved file docker compose -f docker-compose.prod.yml up --buildNew → Web service
Pick the repository and branch. Add every variable the file references with
${…}.Deploy and read the first lines of the log
They confirm the Compose file found, the images to build, the public service and port, and any variables the file doesn't use. If the file is refused, every reason is listed there.
Before you deploy#
- A production Compose file at the repository root, with no bind mounts.
- Exactly one public service — or a
crowther.publiclabel saying which. - Every secret referenced as
${NAME}and set in the dashboard; required ones use${NAME:?…}. - Every database or file store on a named volume.
- Healthchecks on databases, and
depends_on: condition: service_healthyon what uses them. - Images the platform doesn't build are public.
- No secrets in the file itself or in env_file.