Installation
How to install, configure and update.
The easiest way: a partner hosting provider
Answer three questions and pick one of our partner hosting providers. They install Deplo for you: no terminal, no code, you get a link and create your account. Deplo earns a commission from the partner, and your price stays the same.
Install it yourself
Deplo installs from a single shell script on a fresh Linux server.
As root, on the server:
curl -fsSL https://deplo.build/install.sh | bashThe dashboard will be automatically deployed on a generated address like https://deplo-cb00710a.deplo.site (check the output of the installer for the correct url)
An IPv6-only server needs nothing extra: the installer sees it and sets
Docker up for IPv6 on its own. On a server with both, IPv4 is the default and
bash -s -- --ipv6 picks IPv6 instead. See
IPv6.
Already have Deplo running?
Don't run this script on a second machine. To add a server for your apps, a build server or a backup host, paste the command from Settings -> Servers on it instead. See Add a server and Server roles.
What you need
We encourage you to start from a clean environment to prevent configurations that can interfere with Deplo
| What | Requirement |
|---|---|
| A server | Ubuntu 24.04 LTS or newer, Debian 12 or 13, or one of the other supported distributions, x86-64 or arm64, compatible with Docker. systemd is needed for the agent. |
| Size | 2 cores, 4 GB of RAM, 30 GB of disk is the minimum, 4 cores and 8 GB the comfortable size. Both are about your apps: the platform itself fits in about 1 GB. The installer warns below the minimum and refuses below 8 GB free on /, where Docker images alone do not fit. |
| Ports | 80 and 443 reachable from the internet, 9443 for every agent host. |
| Outbound HTTPS | To ghcr.io for the image, to get.docker.com when Docker is missing, and to Let's Encrypt for the certificate. The first two are checked before anything is installed. |
| A domain | Optional: The generated deplo.site hostname works from the first deploy. |
| Docker knowledge | Optional: Only when you are ready for the best Deplo experience. |
To check a machine without touching it, run the preflight and exit:
curl -fsSL https://deplo.build/install.sh | bash -s -- --checkIt changes nothing on the host and prints every blocking problem and every warning, so a server that cannot finish the install says so in ten seconds instead of halfway through.
Create your first account
The installer prints a setup link at the end, next to the dashboard address:
Set up https://deplo-cb00710a.deplo.site/setup?key=4f9c2a7e1b8d3f60a5e2c9d4b7f1e083The setup will create the first account with the Owner role.
Installed by your hosting provider?
Sign in with the email and temporary password from their welcome email. Deplo then asks for a password of your own. Hosting providers, see Offer Deplo to your customers.
What the installer does
On the host itself, four things change:
| Change | Why |
|---|---|
| Docker is installed if absent | Via get.docker.com, then the service is enabled |
default-address-pools is rewritten in /etc/docker/daemon.json | Docker's defaults allow about 31 networks and Deplo uses one per Environment, so an untouched host runs out. An existing pool config is never clobbered, the old file is kept as daemon.json.deplo-bak, and the new one is validated with dockerd --validate first |
The deplo Docker network is created | It carries Traefik and the control plane. No app ever joins it: a stack gets its own Environment network |
| This machine is enrolled as a server | The installer waits for /api/health, then runs the agent installer against the panel on 127.0.0.1 |
Then, four Docker's containers come up:
| Image | Purpose | Exposed ports |
|---|---|---|
postgres:16-alpine | The internal database of the control-plane | Nothing |
ghcr.io/deplocloud/deplo:latest | The control-plane itself | 3000 only localhost |
traefik:v3.7 | To serve the web apps to a domain | 80, 443 |
tecnativa/docker-socket-proxy:v0.5.0 | A secure way for Traefik to know which web apps to serve | Nothing |
Running it again when already installed it will just update Deplo and its services.
Neither Traefik nor the control plane ever gets the Docker socket itself. See How Deplo works.
How to update
From the dashboard: Settings -> Deplo -> Updates, and the button there installs the new version. The panel always notifies you for new versions available.
See Update for the full procedure, including the server agents, and how to pin a specific version.
Run it with Compose instead
docker-compose.yml in the repository runs the control plane and its Postgres. It is a readable,
hand-editable starting point, not a copy of what the installer writes: it brings up no Traefik of
its own and joins the external deplo network by labels, while the installer routes the panel
through Traefik's file provider so the panel's own route can be changed from the panel later. Example usage:
docker network create deplo
export DEPLO_DOMAIN=deplo.example.com # required: it is the only address it serves
export DEPLO_SECRET=$(openssl rand -base64 48)
export DEPLO_DB_PASSWORD=$(openssl rand -base64 24)
export DEPLO_SETUP_KEY=$(openssl rand -hex 16) # then open /setup?key=<xxx>
docker compose up -dGoing this way, you enroll the host as a server yourself from Settings -> Servers, exactly like any other machine. Four things are worth knowing before you do:
DEPLO_SETUP_KEYis yours to set. The installer generates one; Compose does not. Leave it unset and Deplo derives one fromDEPLO_SECRETand prints the setup link in its log at boot:docker compose logs deplo | grep setup.DEPLO_SECRETis not rotatable. It derives every encryption key, every session signature and the agent certificate authority. Change it and every stored secret becomes unreadable, every session ends, and every agent certificate is created again. Back it up with the rest of/opt/deplo/.env.- The domain must resolve before the certificate can issue. Let's Encrypt validates over HTTP on port 80, so point the A record first. The generated address answers meanwhile.
localhost,*.local,*.localdomain, a bare IP and any name without a dot are rejected asDEPLO_DOMAIN. The panel needs a hostname a certificate can be issued for; the installer says so and falls back to the generateddeplo.siteaddress.
Troubleshooting
| Symptom | What to check |
|---|---|
docker compose not found | The script requires Compose v2. Install Docker's own packages rather than a distribution's docker.io. |
| The dashboard does not answer | From the server, curl http://127.0.0.1:3000/api/health. If that works, the proxy is the problem. If it does not, check docker ps shows the deplo container and read docker logs deplo; a failure to reach Postgres is the usual cause. |
| The domain shows a certificate warning | The A record is not resolving to this server yet, or port 80 is closed. |
| Agent enrollment failed | Not fatal. The dashboard still comes up and the script says so; re-running the installer retries it. |
More in Servers and agents and Domains and TLS.
Next steps
Did this page help you?