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.
- One image? Deploy a Docker image is simpler.
- The file is in your repository? Deploy the repository and Deplo reads the file on every deploy: see the Docker Compose build method.
Create a Compose app
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
- KEYentries. The values ride in a0600env 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 ($NETor${NET}). Any value butnoneanddefault,bridgeincluded, needs host access.- A network
name:or ahostname: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 orhostname:, 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:andlabel_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
| Field | What changes |
|---|---|
| Domains name a service | A domain routes to one Compose service, by default on the first port your file lists for it. |
| No rollbacks | Deplo built no image, so there is nothing to re-run. The header shows Stop and Reload instead. |
| No build server | Same reason. |
| Storage names a service | A service your file does not contain fails the deploy, never a silent remount. |
| Cron jobs name a service | Blank means the routed service, or the first one. |
| Redeploy pulls every image | Each tag is pulled again, so a stack on :latest updates on Redeploy. Nothing watches the registry for you. |
| Ports live in the file | Write 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
- Anchors and merge keys work:
x-common: &commonwith<<: *common, and the tagged!!merge <<: *commontoo. - An
environment:value keeps its text.UMASK: 022reaches the container as022, andVERSION: 1.10stays1.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, andbasicauth/digestauthwithusers. - Dropped:
forwardauth,errors,chain,plugin, ausersfileand a Redis-backedratelimit. Each one makes the proxy reach outside your app. - The name belongs to the stack. Deplo renames
gzon 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
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-fileand--project-directory. They are how Deplo finds your stack again. --pull alwaysis Deplo's default, which is what makes a redeploy pick up a moved tag. A--pullof your own replaces it:--pull missingkeeps an image that exists only on the server.--waitmakes 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 deniedon 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.
Still stuck? See Deploys and builds troubleshooting.
See also
Did this page help you?
