Add a server
Bring another machine into the fleet with one command pasted on that machine. Deplo never connects to it.
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.
Open the dialog
Click Add. The dialog is titled Add a server.
Name it and set the address
Give it a Name, then 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, which builds for other servers. Beta
- Backups, for a storage box that holds backup files and runs nothing
Once enrolled, the server card shows these as the badges Build only and Backups only.
Choose which teams may use it
Team access defaults to All teams. Picking Specific teams and ticking none is refused.
Add it
Click Add server. Deplo prints the command.
Run the command
Paste it on the server, as root:
curl -fsSL 'https://deplo.example.com/install-agent.sh' --output '/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, open the server, then Advanced -> Install command, for 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.
Good to know
- 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.
Troubleshooting
- 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 Advanced tab, under Install command.
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.
Next steps
Did this page help you?