Skip to content

ubuntu.md

Latest commit

 

History

History
115 lines (74 loc) · 3.33 KB

ubuntu.md

File metadata and controls

115 lines (74 loc) · 3.33 KB
Raw
title Install on Ubuntu / Debian
description Install SimpleDeploy on Ubuntu or Debian via the official APT repository. Includes systemd setup, firewall config, and verification.

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

  1. 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

  2. Verify:

    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.

  1. Generate the config:

    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.

  2. Enable and start:

    sudo systemctl enable --now simpledeploy
sudo systemctl status simpledeploy

  3. Tail the logs while it boots:

    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.