Upgrade
Update the control plane and server agents, and know what changes on each side.
What it is
Moving Deplo to a newer version. Two things version independently:
- The control plane (this panel)
- The server agents, one binary per host
How it works
- The control plane is a container image,
ghcr.io/deplocloud/deplo. Upgrading it means pulling a newer tag and restarting the stack. - Database migrations apply themselves at boot. There's no separate migration step.
- Agents update one server at a time, from the servers page.
- The control plane and the agents tolerate a version gap: new capabilities are announced in the handshake, so an older agent simply doesn't offer a newer feature rather than failing.
Agent updates only ever move forward. There is no downgrade path.
Release history
Settings -> Deplo -> Updates is the panel's own changelog, so "what changed" has an answer without leaving Deplo.
- The version this instance runs, and whether a newer one is published.
- Check now re-asks the repository instead of waiting out the hourly cache.
- Every published release with its notes, newest first. The one you are running is marked Installed.
- How much of the fleet is on the agent release Deplo expects, with a link to the servers page.
A newer release also raises a banner across the dashboard and a dot on the Deplo entry in the sidebar. Dismissing the banner silences it for that version; the dot stays until you upgrade.
Nothing updates itself. The list says what a release contains, the two sections below are how it gets applied.
Upgrade the control plane
Re-run the installer on the machine that runs it:
curl -fsSL https://deplo.build/install.sh | bashIt detects the existing /opt/deplo/.env, switches to update mode, pulls the image, and restarts. Secrets are never rotated.
To pin a version rather than take latest:
curl -fsSL https://deplo.build/install.sh | \
DEPLO_VERSION=0.4.1 bashThe panel checks for releases on its own. Nothing updates itself.
Your apps keep running throughout
They are containers on hosts, not part of the control plane. A panel that's down means you can't deploy or read logs for a minute, it does not mean your sites are down.
Update the agents
Refresh
Click Refresh: it re-checks every agent and the latest agent release.
Update each server that's behind
Click Update agent on it.
Sensible order, especially on a fleet:
- One canary server that runs something you can afford to break.
- Watch it: readiness, a deploy, logs streaming.
- The rest.
- The machine running Deplo itself, last. If an agent update goes wrong there, you want the panel already proven on the new version.
Don't update an agent while a deploy is in flight on that host.
Limits and gotchas
- Agents cannot be downgraded. Test on a canary.
- Some features need a newer agent. When one is missing, Deplo says so rather than silently doing something else.
- Re-running the installer is safe and idempotent. It's the intended update path, not a workaround.
- Read the release notes for a minor bump. During
0.x, minor means something you notice: a feature, changed behavior, a database migration, or a newer agent required. - Back up before a big jump. Migrations apply at boot and aren't reversed by rolling the image back.
If it does not work
If it does not work
Panel that won't come back after an upgrade, an image that won't pull, or an agent update that fails: see Servers and agents troubleshooting.
See also
Did this page help you?