Network isolation
Every environment gets its own private network, so a service name means one container and nothing crosses an environment boundary.
Every environment gets a private Docker network, deplo-env-<environment id>. Apps and
managed databases in it reach each other by name.
- Apps outside any project share the team's
deplo-team-<team id>network. - A pull request preview gets its own
deplo-preview-<key>network. - Folders change nothing. They are about permissions, not isolation. To separate workloads, use different environments.
Deplo derives the network from where the app lives. You never create or pick one.
What sees what
| From | To | Reachable |
|---|---|---|
| A service in a stack | Another service in the same stack | Yes |
| An app | Another app in the same environment, same server | Yes |
| An app | A database in the same environment, same server | Yes |
| An app | Anything in the same environment on another server of its cluster | Yes - see Private network |
| An app | Anything in the same environment on another server, outside a cluster | No |
| An app in Production | An app in Staging, same project | No |
| An app | An app in another project | No |
| An app | Anything of another team | No |
| A pull request preview | Anything at all | No |
| An app | A published port on the same server | Yes - see below |
A preview cannot reach your database
A preview has its own network, so it cannot reach the managed database of its environment, and it can never join an environment network. Put a database in the Compose file, or use one with a published port.
What crosses the boundary anyway:
- A published port answers every container on that server, whatever its team or environment. A firewall does not help: the traffic never leaves the host. Use one only when that is the point; app to app, use the name.
- The proxy sits on every network. A container can request any hostname that server serves, other teams' domains included, and a domain is reachable from the internet anyway. Keep a private service without a domain.
What does not cross:
- A network does not span servers. Same environment on two servers: the names do not resolve. Put both on one server, or publish a port and use the server's address.
- Moving an app out of an environment (into a folder at the top level, for example) puts it on the team network, away from that environment's databases. Deplo redeploys it on the new network before the move completes. Moving between folders changes nothing.
Services that stay off the network
Every service of a stack joins the environment network, not only the routed ones: a worker
with no domain still has to reach your database. Networks you declare yourself (frontend,
backend) are kept, and the environment's is added. Four kinds stay off:
- A service with
network_mode:. It joins no network at all, so a domain pointed at it does not answer. - A service whose name or
hostname:is a platform name (postgres,traefik,deploand three more). It keeps a private network with the rest of the stack, so your app still reaches it by name. - A service whose networks are all
internal: true. That is a deliberate seal. A domain still wins: a routed service joins, or the proxy could not reach it. - A service whose name another stack there already answers to. It is left off with a warning rather than taking half the traffic.
services:
web:
image: my/app
networks: [backend] # on backend AND the environment's network
worker:
image: my/app # names nothing: on the environment's network
vault:
image: vault
networks: [sealed] # sealed off on purpose: stays private
networks:
backend: {}
sealed:
internal: trueTwo stacks, one name
Inside one environment, on one server, a name has to mean one container. Two stacks that both
answer to web split the lookups, and half your requests reach the wrong container.
Saving a Compose file that takes a name already answered there is refused, and the message names a free one:
`web` is already answered by Shop on that network, and Docker would split the
connections between the two. Rename it on this app (the service, or its
`hostname:`) - `web-2` is free - or pick another environment.An overlap that already exists, from before the check or from another route, is reported by the deploy instead:
`web` is also answered by a stack in Shop / Production, on the same network as
this one. Docker splits the lookups between them, so half will reach the wrong
container. Rename the service, or its `hostname:`.Deplo also refuses a move that would create an overlap, for an app or a database.
A stack Deplo wrote is renamed, not refused. A template deployed twice into one
environment gets db-2 for its second db; an app a migration brings over gets its own name
in front (shop-db). The route, variables and config files follow the new name, and the app's
Activity (or the migration report) says what changed.
Database placement
- In an environment: its apps on the same server reach it at
db-<name>. Almost always what you want. - No environment: it sits on the team network, for apps outside every project.
Pick it in the Environment field of Storage -> New Database. Change it later in the database's Connection card, or with Move to environment in its menu on Storage. Deplo restarts it on the new network before the action completes; a stopped database moves the next time you start it.
A database's Host port takes it outside all of this: every container on that server can reach it, and only the password is in the way. Leave it off unless something outside the server needs it.
cannot resolve host
The one thing that breaks: an app pointing at another one by name, from another environment.
could not translate host name "gamewatcher-db" to address:
Name or service not knownThe deploy log says so before the container tries:
DATABASE_URL points at `gamewatcher-db`, which lives in GW / Production and is
not reachable from here. Move this app into the same environment, or use a
managed database placed there.Or, when the placement is right and the machine is not:
DB_HOST points at `orders-db`, which is in Shop / Production with this app but
runs on ANOTHER SERVER. A network only spans one machine, so the name will not
resolve. Put both on the same server, or publish a port and use the server's
address.The ways out, best first:
- Same environment, same server. Move the app or the database. Or put both servers in a cluster: its servers share one network, and names reach across them.
- A managed database created in the environment that needs it. Deplo writes the connection string.
- A published port, only if the two must stay apart. Point at the server's address, and treat the port as public: it answers every container on that server.
Out of Docker networks
Every environment with apps on a server is one Docker network there. An older server can run
out, at about 31 by default, and the deploy says so. Set default-address-pools in
/etc/docker/daemon.json and restart Docker, or remove unused networks with
Docker cleanup.
Migrate existing instances
The first start of a Deplo with network isolation moves every app and database onto its environment's network, one server at a time.
- A stack it cannot reach stays where it is and keeps running: a delay, not an outage. The Overview counts them and Activity says which and why. Try again re-runs the sweep, Dismiss hides the notice for good.
- Stopped and mid-deploy stacks wait, and are not counted. They move on their next start or deploy, like any stack you deploy.
- A database with no placement gets the environment that uses it, when exactly one place does. One used from two places stays at the team level for you to decide.
What does not change
Domains, HTTPS, certificates, redirects, basic auth and published ports. Logs, console, backups, cron, metrics and migrations reach a container through the server agent, never through the Docker network.
Did this page help you?