Deploy
Single binary + systemd, no containers. One host runs three units: the HTTP API, the scheduler and the queue worker. Prefer containers? The same binary runs from one image, see Docker.
Layout
/opt/ims/ims-go-api/ releases/<timestamp>-<version>/ims # immutable release binaries current -> releases/<...> # atomic symlink, what units run/etc/ims/ims-go-api/.env # environment (root:ims, 0640)/var/lib/ims/ims-go-api/ # writable state (uploads/exports)/var/log/ims/ims-go-api/ # optional file logs (else journald)Nothing writable lives inside a release directory. Logs go to journald unless APP_LOG_DIR is set.
First install (fresh host)
sudo deploy/scripts/install.sh # user, dirs, systemd units, seeds .envsudoedit /etc/ims/ims-go-api/.env # DATABASE_DSN, APP_URL, APP_TIMEZONE, ...sudo deploy/scripts/release.sh --source /srv/src/ims-go-api-starterinstall.sh creates the ims user, the directory layout (release tree owned by root — the service
can run the binary but never rewrite it; state under /var/lib/ims/ims-go-api), installs and
enables the three units, and seeds /etc/ims/ims-go-api/.env from deploy/.env.production
(APP_ENV=production, state paths under /var/lib, no default secrets). Fill in every
MUST SET value; the app refuses to boot with unsafe production settings.
Build with the latest Go 1.26 patch (CI does): older patches carry standard-library CVEs. To
check a build yourself, run go run golang.org/x/vuln/cmd/govulncheck@latest ./....
Upgrade
# from a local checkout (build-on-server):sudo deploy/scripts/release.sh --source /srv/src/ims-go-api-starter
# from git (clones the ref on the host):sudo deploy/scripts/release.sh --repo git@github.com:your-org/ims-go-api-starter.git --ref v1.4.0The script: builds a static binary → runs ims migrate (gated) → atomically switches current →
restarts units → health-checks /api/health?fresh=1 (readiness: database, migrations, cache,
queue) → prunes old releases (keep --keep, default 5). If the health check fails, the previous
release is restored and restarted automatically; migrations stay applied, so keep them
backward compatible (add columns before using them, drop them a release later).
Useful flags: --dry-run (print the plan, validate prerequisites), --skip-migrate,
--no-restart, --health-url, --keep.
Units
| Unit | Command |
|---|---|
ims-go-api |
ims serve |
ims-go-api-scheduler |
ims schedule |
ims-go-api-worker |
ims queue:work --queues=critical,default,heavy |
Exactly one scheduler must run per deployment — enforced: a second ims schedule exits
because another process holds the scheduler’s Postgres advisory lock. The queue worker may be scaled (add more
ims-go-api-worker@.service instances or run ims queue:work elsewhere).
systemctl status ims-go-api ims-go-api-scheduler ims-go-api-workerjournalctl -u ims-go-api -fReverse proxy & client IPs
If you terminate TLS at nginx/Caddy, set the proxy’s address so forwarded client IPs are honoured:
HTTP_TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8Only requests whose immediate peer is in this list have X-Forwarded-For / X-Real-IP trusted;
everything else uses the socket address. This drives login throttling, rate limiting and logs.
Troubleshooting
- Health:
curl -fsS http://127.0.0.1:8080/api/health?fresh=1 | jq. - Config echo:
sudo -u ims /opt/ims/ims-go-api/current/ims config:show(DSN password masked). - Contract check:
ims openapi:check(needs the DB up). - A release that fails its health check is not marked good — roll back (see
rollback.md).

