Add a server
Bring another machine into the fleet with one command pasted on that machine. Deplo never connects to it.
How it works
The control plane prints a command containing a one-time bootstrap token. On the server, that command:
- Installs Docker if it is missing, and sets Docker's address pools so the host does not run out of networks at about 31 apps.
- Downloads the agent binary for that architecture and verifies its SHA-256. A mismatch refuses to run rather than warning.
- Installs it as a systemd unit listening on
9443, with its credentials in a0600environment file rather than on the command line, where any user could read them from/proc. - Installs Traefik on that host, unless one is already running or ports 80 and 443 are taken.
- Starts the agent, which generates its own key, sends a certificate signing request and calls home with the token.
- Checks whether
ufworfirewalldis holding port 9443 and prints the command to open it. It never edits the firewall itself.
The control plane signs the certificate and pins its fingerprint. The server flips to online, and from then on everything is mutual TLS on port 9443.
What the machine needs
| What | Requirement |
|---|---|
| A server | linux/amd64 or arm64, systemd, and root for the length of one command. Docker is installed for you if it is missing, except for a migration source, which needs the Docker it is importing from. |
| Tools | curl and sha256sum, to download the agent and verify it. |
| Disk | 30 GB free on / is the recommended minimum. The installer refuses below 5 GB, since images and build caches grow fast. |
| Network | The control plane must reach this host on 9443, and this host must reach the control plane's URL to call home. |
Nothing here checks memory or CPU: the agent is a small Go binary, and what needs them is whatever you deploy on this machine. Size it like the first one, 2 cores and 4 GB at the least, unless it is a storage-only server, which does nothing but hold backups.
Add one
You need to be an instance admin.
Open servers settings
Open Settings -> Servers.
Connect a remote server
Click Connect a remote server.
Set the address
Fill in Host or IP: the address this control plane will dial. It must be reachable from here on the agent port.
Choose what it's for
Choose What this server is for:
- Everything for a normal deploy target
- Build only to compile for other hosts. Beta
- Backups only for a storage box that runs nothing. Beta
Add it
Click Add. Deplo prints the command.
Run the command
Paste it on the server, as root:
curl -fsSL https://deplo.example.com/install-agent.sh -o /tmp/deplo-agent-install.sh && sudo bash /tmp/deplo-agent-install.sh <TOKEN> <URL> [FINGERPRINT]It downloads the script first and runs it second, so an address that does not answer fails out loud instead of running an empty script.
Watch the card. It goes from provisioning to online on its own.
The token is single-use and expires in about an hour. If enrollment fails, the server's menu can issue a fresh one.
Deplo pins its own certificate in that command
Over https, the command carries the fingerprint of the certificate your panel serves, and the agent refuses to start without it. If Deplo cannot read that certificate from its own address, Add is refused with the reason instead of printing a command that could never work. Make the panel's address reachable from the panel itself, then add the server again.
Open the right ports
| Port | Direction | Why |
|---|---|---|
9443 | Control plane to server | The agent. Nothing works without it |
80, 443 | Internet to server | Traefik, and the HTTP certificate challenge |
No installer opens a firewall for you. The agent installer checks ufw
and firewalld on its last lines and prints the command to run when one
of them is holding 9443, so read what it prints. A rule written by hand
in nftables or iptables is not detected.
Check it before you trust it
The server's menu has Check readiness. It dials once and reports rows
grouped as agent, docker, routing, capacity, build methods and Deplo
configuration, each pass, info, warn, fail or skip.
skip means it could not be evaluated, which is deliberately different
from pass. Nothing gates on this report: it is for you.
Let teams use it
New servers are usable by every team by default. Narrowing that is a separate setting. See Access.
Limits and gotchas
- Only
linux/amd64andlinux/arm64. Nothing else is published. - An app and its database must be on the same server to reach each
other by name. The shared
deplonetwork is per host. - A build server needs the same CPU architecture as the machine that will run the image. Mismatched pairs are shown but disabled.
- The address is what the control plane dials. A private IP works only if this instance can route to it.
- If containers are already running when the address pools change, the installer skips the Docker restart and tells you to do it in a maintenance window.
If it does not work
- Stuck on provisioning: the agent never called home. On the server,
check
systemctl status deplo-agentandjournalctl -u deplo-agent -f. - Offline, or online with every deploy failing: inbound
9443is blocked. Whenufworfirewalldis the cause, the install command printed the fix. Refusing to run an unverified binary: the download did not match its checksum. Retry; if it persists, something is intercepting the download.- The token is expired: issue a new one from the server's menu.
Deplo could not read the certificate its own address serves: the panel cannot dial its own public address, so it has no fingerprint to pin. Check DNS and egress from the panel's machine to that address.
See Servers and agents for more.
See also
Did this page help you?