Compose apps

Run a docker-compose.yml stack on Deplo, with routing, TLS, variables, volumes and backups layered on top.

Paste a docker-compose.yml to run several containers as one app. Deplo adds routing, TLS, variables, volumes and backups on top.

Create a Compose app

Pick Compose

Add New -> Application, then the Compose tile and Next.

The Compose source step of the wizard

Paste and lint

Click Write compose and paste your file. The editor lints as you type: what Deplo will rewrite, what needs a permission, what it refuses.

Pick what gets a domain

The service Deplo picked as the front door is ticked and marked Primary. Tick any other service that needs an address of its own.

Deploy

App name comes from the first service. The server and extra docker compose up flags are under Advanced. Click Deploy. Edit the file later in Settings -> Deployments.

What Deplo changes in your file

It adds:

  • Your environment's network on every service, next to your own networks, so it reaches that environment's apps and databases by name. Some services stay off it.
  • Traefik labels for each domain, pointing at the service the domain names.
  • Your variables, as bare - KEY entries. The values ride in a 0600 env file next to the stack, never in the YAML.
  • Your storage rows, mounted into the service each row names.

It removes version:, container_name:, and aliases: on a network Deplo owns (aliases on your own networks stay). A network key that points at a network Deplo manages, deplo and default included, is rewritten onto your environment's. So never call your own network deplo: it is replaced, internal: true and all.

It refuses:

  • network_mode: container:<name>, one naming a network Deplo manages, and one filled in from a variable ($NET or ${NET}). Any value but none and default, bridge included, needs host access.
  • A network name: or a hostname: from a variable. Write the value.
  • A platform name joining Deplo's network: deplo, postgres, traefik, deplo-traefik, deplo-socket-proxy, docker-socket-proxy, as a service name or hostname:, in any case. A service with one of these names that does not ask for the network is just kept off it.
  • A name another stack or database already answers to in that environment, on that server. See Two stacks, one name.
  • An image under deplo/ (deplo/shop:dpl_0a1b2c3d), where Deplo tags the apps it builds, or named by a variable (image: ${IMAGE}). A variable in the tag (nginx:${TAG}) is fine.
  • extends: from another file, include: and label_file:. Inline what they bring in.
  • A file over 256 KiB, or with more than 20,000 entries.

Which service gets the address

Deplo picks the front door when you save the file:

  • Only services that publish or expose a port qualify. If none does, nothing is picked.
  • Among those, the one nothing else waits on in depends_on.
  • Never a database (the official Postgres, MySQL, MariaDB, MongoDB, Redis and ClickHouse images), unless the stack has nothing else, and never a platform name.

Change it in Domains, where each row names the service it routes to.

One address, two services

For a UI on / and its API on /api of the same hostname, add a second row in Domains with the same hostname and a Path of /api.

How Compose apps differ

FieldWhat changes
Domains name a serviceA domain routes to one Compose service, by default on the first port your file lists for it.
No rollbacksDeplo built no image, so there is nothing to re-run. The header shows Stop and Reload instead.
No build serverSame reason.
Storage names a serviceA service your file does not contain fails the deploy, never a silent remount.
Cron jobs name a serviceBlank means the routed service, or the first one.
Redeploy pulls every imageEach tag is pulled again, so a stack on :latest updates on Redeploy. Nothing watches the registry for you.
Ports live in the fileWrite ports:, which needs the Publish ports grant. The Published ports section is not offered.

Publish a port on an address

- "53:53/udp" claims every address on the machine, its own DNS resolver included, and every other app stops resolving names. Write - "203.0.113.10:53:53/udp". The editor warns about 53.

Your file is read as you wrote it

Settings -> Deployment of a running Compose app, with 'View full compose'
  • Anchors and merge keys work: x-common: &common with <<: *common, and the tagged !!merge <<: *common too.
  • An environment: value keeps its text. UMASK: 022 reaches the container as 022, and VERSION: 1.10 stays 1.10.
  • A ./ mount lands in the app's own files directory on the server, created if missing.
  • The rendered stack is masked when shown back to you: values and the basic-auth hash.

Middlewares in a compose file

Routes come from Domains. Saving a pasted file with any traefik.* label needs the Configure Traefik grant, which instance admins hold. Your labels then go on top of Deplo's routing:

  • A key Deplo also writes takes your value. A middleware attaches to the service's domains.
  • A complete router (a rule and a service with its port) replaces Deplo's routes for that container.
  • Values are literal: no variables, $$ for a $. At most 256 labels and 64 KiB per service.
  • If the author loses the grant, the next deploy fails until someone who holds it saves the file again.

A Compose file read from a repository, and every pull request preview, keep only a middleware of a supported kind, applied to every domain of its service in the order written. Router and service labels are dropped, and the deploy log names them.

services:
  web:
    image: nginx:1.27
    labels:
      - traefik.http.middlewares.cache.headers.customresponseheaders.Cache-Control=public, max-age=3600
      - traefik.http.middlewares.gz.compress=true
  • Kept: headers, compress, ratelimit, inflightreq, ipallowlist, redirectscheme, redirectregex, addprefix, stripprefix, stripprefixregex, replacepath, replacepathregex, buffering, retry, circuitbreaker, contenttype, grpcweb, and basicauth / digestauth with users.
  • Dropped: forwardauth, errors, chain, plugin, a usersfile and a Redis-backed ratelimit. Each one makes the proxy reach outside your app.
  • The name belongs to the stack. Deplo renames gz on deploy, so another app can neither collide with it nor use it.
  • The common security headers need no YAML. Turn on a domain's Security headers.

Extra flags

Extra compose flags and the exact command Deplo runs

Settings -> Advanced -> Extra compose flags adds flags to docker compose up. The page shows the whole command the server will run.

  • Only compose up's own flags, written in full (--wait, --timeout=60), at most 24, no quotes and no shell syntax.
  • Refused: -p / --project-name, -f / --file, --env-file and --project-directory. They are how Deplo finds your stack again.
  • --pull always is Deplo's default, which is what makes a redeploy pick up a moved tag. A --pull of your own replaces it: --pull missing keeps an image that exists only on the server.
  • --wait makes the deploy wait for every service's health check.

Troubleshooting

  • The editor refuses a service name: a platform name, or one another stack or database there already answers to. Rename the service, or its hostname:.
  • cannot resolve host, and the name is another app: it is in another environment or on another server. See Network isolation.
  • A domain points at a service and nothing answers: it sets network_mode (host, service:vpn), so Traefik cannot reach it. Route a service with its own network; with a VPN sidecar, a small proxy in front of it.
  • pull access denied on a redeploy, for an image that was never in a registry: add --pull missing. A private image needs a registry credential.
  • The account that saved these Traefik labels no longer has permission: someone with Configure Traefik saves the file again.
  • Domains show no service to pick: the file did not parse. Fix the lint errors first.

See also

Did this page help you?

On this page