# Docker Compose in production

Docker Compose in production: from the compose file to running services, with health checks, volumes, and a place for data.

Canonical URL: https://unbroker.cloud/blog/docker-compose-to-production
Published: 2026-11-02
Reviewed: 2026-11-02
Author: Timoteo Borgobello

## The short answer

Docker Compose in production, on Docker's own terms, is a single server. The same docs say that scaling that setup means Swarm. The compose file still describes the stack. What changes is the inventory: what is public, where the data lives, and what happens when a container is replaced.

Separate the web process, the workers, and the data. Remove bind mounts of application code. Add healthchecks. Keep secrets out of the image. Decide whether each database stays a container you operate. To deploy a Docker Compose app on a platform, create one service per piece. A single container is [Docker on Unbroker](https://unbroker.cloud/deploy/docker). A frontend and an API in one project is [frontend and API](https://unbroker.cloud/solutions/frontend-and-api). If the stack has to stay one machine you patch, [run Compose on a Linux server you operate](https://unbroker.cloud/cloud-servers). If you are leaving Railway, the [Railway alternative](https://unbroker.cloud/alternatives/railway) is the comparison.

## What Docker recommends for production

Docker's production note lists the changes that usually matter. Remove volume bindings for application code, so the code stays inside the image and cannot be changed from outside. Bind different ports on the host. Set environment variables differently. Set a restart policy such as `restart: always`. You can add a service such as a log aggregator.

Put the differences in a second file, `compose.production.yaml`. It only needs the changes. Apply it over the base file:

```bash
docker compose -f compose.yaml -f compose.production.yaml up -d
```

```yaml
services:
  web:
    ports:
      - "80:3000"
    environment:
      LOG_LEVEL: info
    restart: always
```

That file is the shape of three changes Docker names: a different host port, different environment variables, and `restart: always`. Removing the code bind mount is the other change, and it has to be true of the configuration you run. Docker's merge rules decide whether a key in the second file replaces the base file or combines with it. Read them before you depend on a port or a volume change. The source is [Use Compose in production](https://docs.docker.com/compose/how-tos/production/) and [multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/).

To redeploy one service named `web`, rebuild it and recreate only that service:

```bash
docker compose build web
docker compose up --no-deps -d web
```

`--no-deps` leaves the services `web` depends on alone.

## Map each service to what it is

The file is a list. Production is a decision per line. This is the map from a compose element to what it means when something else is running it, and to the Unbroker service that matches.

| Compose element | In production | On Unbroker |
| --- | --- | --- |
| HTTP service with `build` | The code stays in the image. Drop the source bind mount. | Repository service: Railpack, or a Dockerfile in the repo. |
| `image` | Run a known artifact you can name later. | Image service. Unbroker pulls it and does not rebuild the source. Prefer a release tag or a digest. One replica. |
| Process with no published ports | No inbound HTTP. | Worker. No public URL. One replica. |
| Postgres, Redis, MySQL, MongoDB | Someone owns upgrades, backups, and restores. | Apps database node, or a managed database. |
| nginx or another reverse proxy | On one host it often publishes the app and terminates TLS. | A public service already has a URL. Keep a proxy only if you still need its routing. |
| `ports` | The host publishes that port. | Only a public service has a URL. The rest stay private. |
| Code volume | Remove it. | The image holds the code. |
| Data volume | A path that survives a new container. | One volume, one absolute path, up to 50 GB, cannot shrink. One replica. Deleting the service deletes the volume. |
| `environment` or `env_file` | Different values per environment. Secrets stay out of the image. | Production, Preview, or All. A pasted `.env` imports variables. New previews copy All and Preview, never Production. |
| `depends_on` | Running is not ready. Use `service_healthy` and a healthcheck. | The app still retries after the first start. |
| `restart` | `restart: always` on a single server. | A down service or a crash-loop raises a built-in alert. Metrics include restarts. |
| `networks` | Containers on that host share a network. | Same environment: private host and port. Previews cannot reach production. |

A frontend that is only HTML, CSS, and JavaScript, with no server process, is a static upload. That is a different service from a container. The types are in the [services guide](https://docs.unbroker.cloud/apps/services).

An nginx row is a criterion, not a rule. If the proxy only exists to publish the app and terminate TLS, a public service already has a URL. Custom domains and managed TLS require Pro. If the proxy still routes in a way you need, keep that as its own decision.

## depends_on is not a readiness check

Compose waits until a dependency is running. It does not wait until that dependency can accept work. A database process can be up and still be starting.

`depends_on` takes one of three conditions:

- `service_started` means the container is running.
- `service_healthy` means the healthcheck passes. The service needs a `healthcheck`.
- `service_completed_successfully` means a one-shot dependency exited with success.

Docker's startup-order page uses Postgres and `pg_isready` for the healthy case. `$$` is Compose escaping, so the shell inside the container sees `$POSTGRES_USER`. The page also sets `restart: true` on that dependency, which restarts `web` when a Compose operation restarts `db`, and it shows Redis with `service_started`. The block below is that healthcheck, kept to the database:

```yaml
services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s
```

The source is [Control startup and shutdown order](https://docs.docker.com/compose/how-tos/startup-order/). `postgres:18` is the tag in that example. It is not an Unbroker image pin.

A healthcheck gates the first start. The application still retries connections, because the database can go away later.

## Ports and private networking

`ports` publishes a container port on the host. On one server, that is how traffic reaches the process. Other containers on the Compose network use the service name.

Publish only what should have a URL. A private service has no public URL, no Ingress, and no certificate. Another service in the same environment connects with the private host and port:

```text
${{services.api.host}}:${{services.api.port}}
```

A preview environment cannot reach production. A worker already has no public URL, and it cannot be marked private on top of that. Do not create a public web service just to satisfy an HTTP health check for a process that has no listener. The start command should launch the consumer. Dockerfile workers run without a public URL, an inbound service, or an HTTP readiness probe. See [background workers](https://unbroker.cloud/solutions/background-worker) and the [worker guide](https://docs.unbroker.cloud/guides/background-worker).

## Volumes: code mounts out, data decided

A bind mount of the source tree is a development convenience. Docker's production note says to remove it, so the running code is the code in the image.

A data volume is a separate choice. On Unbroker a volume belongs to one service and mounts at one absolute path. It can grow, up to 50 GB, and it cannot shrink. Growing it does not restart the service. Deleting the service deletes the volume and its data. Reset and detach remove that data too. Files written outside the volume are temporary: a deploy, a restart, or a reschedule can replace the container.

A service with a persistent volume always runs one replica. Image services and workers always run one replica. Repository and upload services can run several, up to 3 on the shared cell. Dedicated cells allow more. How to set the minimum, the maximum, and the trigger is in [replica autoscaling](https://unbroker.cloud/blog/replica-autoscaling).

Backups go to an S3-compatible destination you control. A volume is not itself a backup. The path is on [persistent storage](https://unbroker.cloud/solutions/persistent-files) and in the [storage guide](https://docs.unbroker.cloud/apps/storage). Confirming a test record after a redeploy is [Persistent storage volumes](https://unbroker.cloud/blog/persistent-storage-volumes).

<aside class="plan-box">
<p><strong>On Unbroker.</strong> Persistent volumes require Pro. Free does not include them. Put only files that must survive a new container on a volume.</p>
</aside>

## Environment variables and secrets

`env_file` and a `.env` on a laptop are not the production store. Set runtime values on the service. A secret copied into an image layer stays in the artifact even if a later layer deletes the file. Add `.env`, local credentials, and other files you do not want in the build to `.dockerignore` when the Dockerfile copies a broad path. For an image service, prefer a release tag or a digest, so you can name the artifact you pulled. Both points are in the [Docker guide](https://docs.unbroker.cloud/guides/deploy-docker).

On Unbroker a variable is Production, Preview, or All. Pasting a `.env` file imports those variables into the environment you selected. A new preview copies All and Preview, and it never receives Production. Put a production database password in Production unless you mean for previews to see it. The longer note is [pull request preview environments](https://unbroker.cloud/blog/pull-request-preview-environments). The rules are in the [environment variables guide](https://docs.unbroker.cloud/deployments/environment-variables).

## Databases: the container or a managed one

A database service in the compose file is an engine you operate: the image, the volume, upgrades, backups, and restores. High availability is not part of declaring a container.

Unbroker has two models. [Choose a database](https://docs.unbroker.cloud/databases/choose) is the source of this split.

| | Managed database | Database node in Apps |
| --- | --- | --- |
| Runs as | Provider-operated cluster | Private service from a database image |
| Operations | The provider handles the host and the cluster lifecycle | You upgrade the image, test backups, and restore |
| Backups | Depend on the engine and the plan | Volume backups to an S3-compatible destination you control |
| Fits | Important production data | The image, the version, and the volume stay in the project |

Use a managed database for important production data unless you have a reason to operate the engine as an application service. "Managed" does not mean every recovery feature is on the plan. Confirm the engine and the plan. You still own the schema, the queries, the credentials, and a restore you have tested. Operating Postgres is the separate note [Postgres in production](https://unbroker.cloud/blog/postgres-in-production).

Apps database nodes are PostgreSQL, Redis, MongoDB, and MySQL. Each one is private by default, with the official image, a volume, and a generated password. You choose when to upgrade, you test backups, and you perform restores. High availability is not implied. Details are on [database nodes](https://docs.unbroker.cloud/databases/app-databases).

The managed database API supports PostgreSQL, MySQL, Redis, Valkey, MongoDB, Kafka, and OpenSearch. Availability varies by provider and region. The create flow shows the combinations that provider and region offer. Managed PostgreSQL and MySQL start at $21.21 per month on [pricing](https://unbroker.cloud/pricing). The smallest managed Postgres plan in the current catalogue is 1 vCPU, 1 GB of RAM, and 10 GB of storage. That price is separate from Pro. Pro is $25 per month with $25 of usage credit. Managed databases are not on Free. The plan pages are [managed databases](https://unbroker.cloud/managed-databases), [managed Postgres](https://unbroker.cloud/managed-databases/postgres), and [pricing](https://unbroker.cloud/pricing).

## Restarts, health, and logs

On a single server, `restart: always` is how Docker starts a stopped container again. The policy does not tell you the process is crash-looping.

On Unbroker, a service that goes down or starts crash-looping raises a built-in alert. You do not add a rule for it. It is active while alerts are enabled for the organization. Metrics include CPU, memory, restarts, and ready replicas. Resource metrics are part of Pro. The list is the [monitoring guide](https://docs.unbroker.cloud/apps/monitoring).

Docker's production note also includes adding a service such as a log aggregator. Runtime logs on Unbroker are what the service writes to stdout and stderr, kept for 7 days. That is the log you read on the service. It is a different thing from a log-aggregator container in the compose file.

## A migration checklist

Work down the file once. One line is one decision.

1. List every service and mark it: HTTP app, worker, database, or files.
2. Remove bind mounts of application code. Keep data on a volume or in a database.
3. Add a healthcheck and `condition: service_healthy` where startup order matters. Keep retries in the app.
4. Publish only the services that should have a URL. Point the rest at a private host and port.
5. Put secrets in environment variables. Keep Production values out of Preview.
6. Choose each database: a node you operate, or a managed cluster. Restore a backup once.
7. On a single server, set a restart policy such as `restart: always`. Where the platform runs the process, watch restarts and crash-loops.
8. Pin each image service to a release tag or a digest.
9. Create one service per piece in a project. If you paste the compose file, review every service it created against this list.
10. Check the plan. Dockerfiles, container images, workers, persistent volumes, and managed databases require Pro.

## How it maps on Unbroker

Create a project and add one service for each piece. A repository service builds the HTTP app with Railpack or a Dockerfile. A FastAPI service built from that Dockerfile is one container running Uvicorn. What changes after `fastapi dev` is [FastAPI in production](https://unbroker.cloud/blog/fastapi-in-production). An image service pulls an OCI image and is not rebuilt. A worker runs a process with no inbound HTTP. A database is an Apps node or a [managed database](https://unbroker.cloud/managed-databases). A volume is only for files that must survive a new container.

Services in the same environment reach a private service at `${{services.api.host}}:${{services.api.port}}`. Previews cannot reach production.

The compose file is the inventory. When you create a project you can paste it, and Unbroker creates one service per entry for images, repository builds, environment, `depends_on`, ports, commands, and one persistent volume per service. That is the [Compose import note](https://unbroker.cloud/changelog/2026-08-01-compose-hooks-registries). Review each service after that: a paste does not decide what is public, where the data lives, or whether the database is a managed cluster. A file from another platform, such as `render.yaml`, is not an Unbroker import format. The [Render migration guide](https://docs.unbroker.cloud/guides/migrate-from-render) says so for that file.

Free does not include persistent volumes, managed databases, Dockerfiles, or container images. Pro is $25 per month with $25 of usage credit. The credit resets each cycle and does not roll over. Usage past the credit is billed separately. A single container starts at [Docker on Unbroker](https://unbroker.cloud/deploy/docker). Plan limits are on [pricing](https://unbroker.cloud/pricing).

<aside class="plan-box">
<p><strong>On Unbroker.</strong> One project, one service per piece, a private address inside the environment, and a decision per database. The compose file stays with you as the list.</p>
</aside>

## FAQ

### Can I run Docker Compose in production?

Yes, on a single server. Docker documents that as the easiest deploy, and says that scaling that setup means running Compose apps on Swarm. The limit is that one host. A platform deploy is a different layout: one service per piece of the file.

### Does depends_on wait for the database to be ready?

No. Compose waits until a dependency is running, not ready. condition: service_healthy waits for a healthcheck. The other conditions are service_started and service_completed_successfully. The app should still retry connections, because the database can restart later. Docker's example checks Postgres with pg_isready.

### Should my database run in Compose in production?

It depends on who operates it. A database container is an engine you upgrade, back up, and restore. A managed database is a cluster the provider operates. You still own the schema, the queries, the credentials, and a restore you have tested. Use a managed database for important production data unless you have a reason to operate the engine. This is not a price comparison.

### Can I upload my docker-compose.yml to Unbroker?

You can paste a compose file when you create a project. Unbroker then creates one service per entry. That path supports images, repository builds, environment, depends_on, ports, commands, and one persistent volume per service. It does not choose what is public, where the data lives, or whether a database should be a managed cluster. A file from another platform, such as render.yaml, is not an Unbroker import format.

### What happens to my volumes?

On Unbroker a volume belongs to one service and mounts at one absolute path. It can grow up to 50 GB and it cannot shrink. Deleting the service deletes the volume. Files outside the volume are temporary, because a deploy, restart, or reschedule can replace the container. Backups go to an S3-compatible destination you control. Free does not include persistent volumes.

## Related reading

- [Docker on Unbroker](https://unbroker.cloud/deploy/docker)
- [Frontend and API](https://unbroker.cloud/solutions/frontend-and-api)
- [Background worker](https://unbroker.cloud/solutions/background-worker)
- [Managed databases](https://unbroker.cloud/managed-databases)
- [Postgres in production](https://unbroker.cloud/blog/postgres-in-production)
- [FastAPI in production](https://unbroker.cloud/blog/fastapi-in-production)
- [Pricing](https://unbroker.cloud/pricing)
