Getting started

Requirements

Component	Version / notes
Linux server	Debian/Ubuntu x86_64 (amd64), root access. Tested on Debian 12.
Docker Engine + Compose plugin	docker compose version must work.
nginx	Sites in /etc/nginx/sites-available + sites-enabled (Debian layout).
certbot	With the nginx plugin (python3-certbot-nginx); an account already registered (certbot register).
PostgreSQL	15+; the provided compose file runs postgres:17-alpine on 127.0.0.1:5450.
DNS provider	IONOS DNS API (built in). Your domain's zone must be hosted there.
Authentik	Optional but recommended: 2025.x, with the embedded outpost. Needed for SSO.
A wildcard of free subdomains	Deployer gives each app <name>.<your domain>.

Why on the host and not in a container

Deployer writes nginx sites, runs nginx -t, reloads nginx, runs certbot and docker compose for every app. Running it as a host service keeps those operations simple and visible; it listens on 127.0.0.1 only and is reached through nginx.

1. Build the binary

The production artifact is one static binary that embeds the web interface.

git clone https://git.example.com/you/deployer.git && cd deployer
cd web && pnpm install --frozen-lockfile && pnpm build && cd ..
rm -rf api/internal/webui/dist/* && cp -r web/build/. api/internal/webui/dist/
cd api && CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o ../dist/deployer ./cmd/deployer

Toolchain: Go 1.26+, Node 22+ with pnpm. The repository's scripts/build.sh does the same inside a development container and also runs the type check, go vet and the test suite.

2. Database

sudo mkdir -p /opt/deployer/{bin,data,backups,secrets}
openssl rand -base64 32 | tr -d '\n' | sudo tee /opt/deployer/secrets/db_password >/dev/null
sudo chmod 600 /opt/deployer/secrets/db_password
sudo cp deploy/docker-compose.yml /opt/deployer/
cd /opt/deployer && sudo docker compose up -d

This starts deployer-db (PostgreSQL on 127.0.0.1:5450) and deployer-backup (a daily compressed pg_dump kept 14 days in /opt/deployer/backups). Adjust the network subnet in the compose file if 10.250.5.0/24 is used on your host.

3. Configuration and service

sudo install -m 0755 dist/deployer /opt/deployer/bin/deployer
sudo mkdir -p /etc/deployer && sudo chmod 700 /etc/deployer
sudo tee /etc/deployer/env >/dev/null <<'EOF'
DEPLOYER_DATABASE_URL=postgres://deployer:<password>@127.0.0.1:5450/deployer?sslmode=disable
DEPLOYER_PUBLIC_URL=https://deploy.example.com
DEPLOYER_LISTEN=127.0.0.1:8150
DEPLOYER_DOMAIN=example.com
DEPLOYER_SERVER_IP=203.0.113.10
DEPLOYER_IONOS_ZONE=<your zone id>
DEPLOYER_IONOS_KEY_FILE=/etc/deployer/ionos.key
DEPLOYER_IONOS_NS=<authoritative name server>:53
DEPLOYER_AUTHENTIK_PUBLIC_URL=https://auth.example.com
EOF
sudo chmod 600 /etc/deployer/env
sudo cp deploy/deployer.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now deployer

Every variable is described in Configuration. The IONOS key file contains prefix.secret on one line, mode 600.

On first start Deployer:

• creates /etc/deployer/master.key (AES-256, mode 600): back it up, it decrypts the secrets stored in the database;
• applies the database migrations;
• prints a one-time setup token in the journal and writes it to /etc/deployer/setup_token.

4. Publish it with nginx

sudo cp deploy/nginx.conf /etc/nginx/sites-available/deploy.example.com   # edit server_name
sudo ln -s ../sites-available/deploy.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d deploy.example.com

The provided site disables buffering for /api/runs/<id>/events (live run logs use Server-Sent Events).

5. First login

1. Open https://deploy.example.com: the setup wizard appears.
2. Enter the setup token (sudo cat /etc/deployer/setup_token).
3. Create the first administrator (email, name, password of at least 10 characters).
4. Optional, recommended: enable two-factor on the Account page; set DEPLOYER_REQUIRE_MFA=1 to make it mandatory for every action.
5. Optional: Settings → Authentik → Connect automatically creates a service account and API token in Authentik (or paste an admin API token), then choose the outpost and flows.
6. System shows whether the DNS API and Authentik answer and which tool versions are found.

You are ready to create your first app: New app on the dashboard. See Using Deployer.