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

FromToReachable
A service in a stackAnother service in the same stackYes
An appAnother app in the same environment, same serverYes
An appA database in the same environment, same serverYes
An appAnything in the same environment on another server of its clusterYes - see Private network
An appAnything in the same environment on another server, outside a clusterNo
An app in ProductionAn app in Staging, same projectNo
An appAn app in another projectNo
An appAnything of another teamNo
A pull request previewAnything at allNo
An appA published port on the same serverYes - 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, deplo and 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: true

Two 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 known

The 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:

  1. 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.
  2. A managed database created in the environment that needs it. Deplo writes the connection string.
  3. 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?

On this page