How Deplo works
The two parts of Deplo and the one rule between them.
Deplo is two programs with one rule between them. This explains most of what you see in the product, including why a deploy fails when a server is unreachable and why the dashboard cannot show you a secret.
The two parts
The control plane decides. It is the dashboard you log into. It stores the data, signs people in, prepares the Compose file and the routing rules, and decrypts the environment variables. Then it hands the result to a server.
The server agent executes. One small program per server, deplo-agent. It is the only thing
that runs Docker, touches the filesystem or opens a shell. Builds, deploys, logs, the web console,
metrics, backups, restores and disk cleanup all go through it.
The rule
The control plane never touches Docker or a server directly.
Every action on a server goes through the agent, over an encrypted connection (mutual TLS). The agent's certificate is pinned when the server is added.
What this means for you:
- The machine running Deplo is a normal server. It runs the agent like every other server.
- An unreachable agent is an error. Every deploy starts by contacting the agent. If it does not answer, the deploy fails and says so. It never builds somewhere else instead.
- The control plane never gets the Docker socket. It is the part reachable from the internet, so for security reasons it cannot run Docker. Traefik reads container information through a read-only proxy instead.
What Traefik does
One reverse proxy per server, in a container called deplo-traefik, on ports 80 and 443.
Deplo writes its routing rules.
Every hostname you add becomes a route with its rule, its entry point (HTTP or HTTPS), its certificate provider, and its extras: basic auth, path stripping, redirects. Certificates come from Let's Encrypt and Traefik renews them itself.
Deplo edits the proxy's configuration file in place, so changes an operator made by hand survive.
Where the data lives
Postgres stores all control plane data. Apps, teams, domains, deployment history, encrypted secrets and activity. There is no other store.
Your application data lives on the servers, in Docker volumes the agent manages. It is never copied into the control plane. The only exception is an encrypted backup passing through on its way to a destination on another server.
How secrets move
Secrets are encrypted at rest with a key derived from DEPLO_SECRET. They are write-only:
the dashboard and the API never return them, and a rendered stack shows them masked.
Only four values can be read back, each behind the reveal_secrets capability and each recorded
in Activity: a basic-auth password, a backup recovery key, a managed database's connection string,
and an app's deploy hook URL. An environment variable never can.
The agent never holds the encryption key. The control plane decrypts at deploy time and sends the values inside the encrypted connection.
What this means day to day
| If you see | It is because |
|---|---|
| A deploy failed with "agent unreachable" | The rule. Deplo never builds somewhere else instead. |
| A server card says warning | The agent answers, but Docker does not, so nothing can deploy. |
| A secret you set cannot be read back | Secrets are write-only. Delete and set it again to change one. |
The rendered Compose file shows *** | Secrets are masked, including the basic-auth hash. |
| Two apps reach each other by name | They are in the same Environment, so they share its network. Two apps in different Environments cannot, even on one server. |
Next steps
Did this page help you?