Install on Ubuntu / Debian

The recommended path for production. The .deb package ships a systemd unit and pulls updates through normal apt upgrade.

Prefer containers or on a non-Debian distro? See Install via Docker.

Prerequisites

Ubuntu 22.04+ or Debian 12+, x86_64 or arm64.
Docker Engine with the Compose plugin. Install via docs.docker.com/engine/install if missing.
A DNS A record for the management domain (and any app domains) pointing at the server.

Install

Add the repo and install:

curl -fsSL https://vazra.github.io/apt-repo/gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/vazra.gpg

echo "deb [signed-by=/usr/share/keyrings/vazra.gpg arch=$(dpkg --print-architecture)] https://vazra.github.io/apt-repo stable main" \
  | sudo tee /etc/apt/sources.list.d/vazra.list

sudo apt update && sudo apt install simpledeploy

Verify:
Terminal window
```
simpledeploy version
```

Open the firewall

SimpleDeploy needs ports 80 and 443 reachable from the internet (Let’s Encrypt validates over 80, traffic flows over 443). Keep 22 open for SSH.

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

If you run a cloud firewall (AWS SG, Hetzner Cloud, DigitalOcean), open the same ports there too.

Configure and start

The .deb installs a systemd unit at /etc/systemd/system/simpledeploy.service, but does not start the service until you generate a config.

Generate the config:
Terminal window
```
sudo simpledeploy init --config /etc/simpledeploy/config.yaml
sudo vim /etc/simpledeploy/config.yaml
```
Set domain, tls.email, and master_secret (generate via openssl rand -hex 32). See Configure SimpleDeploy for the full walkthrough.

Enable and start:

sudo systemctl enable --now simpledeploy
sudo systemctl status simpledeploy

Tail the logs while it boots:
Terminal window
```
sudo journalctl -u simpledeploy -f
```

Verify

Hit the management UI:

https://manage.your-domain.com/

You should land on the setup wizard. If you get a TLS error, give Let’s Encrypt 30-60 seconds and reload.

Upgrading

sudo apt update && sudo apt upgrade simpledeploy

Schema migrations run automatically on the next start. See Upgrading for rollback notes.

Troubleshooting

`status=226/NAMESPACE` or `Failed to set up mount namespacing`

Old releases (< the systemd unit fix) listed a path in ReadWritePaths that the package never created, and let Caddy’s ACME state fall under /root/.local/share/caddy, which the unit’s ProtectHome=true blocks. Both are fixed in current releases. If you hit this on an existing host:

sudo apt update && sudo apt upgrade simpledeploy
sudo systemctl daemon-reload
sudo systemctl restart simpledeploy

ACME state now lives under /var/lib/simpledeploy/caddy/. If you previously had certs under /root/.local/share/caddy/, you can copy them over to skip a re-issue, or just let Let’s Encrypt re-issue on next request.

Next: First deploy.