Skip to main content

Standalone deployment

Single-binary install for one Linux host. Bundles nginx, sets up a local MongoDB, and bootstraps secrets. The fastest path to a production-shaped instance for a single project.

Supported distros​

  • Ubuntu 22.04, 24.04 LTS
  • Debian 12 (bookworm) and 13 (trixie)
  • RHEL / Oracle / Rocky / Alma 9 and 10
  • Amazon Linux 2023

Older distros may work but are not tested. The installer is glibc-only — Alpine is supported via the Docker path.

The installer does not check CPU, memory or disk. For host floors and capacity planning by certificate and discovery volume, see Requirements & sizing.

Install​

curl -fsSL https://raw.githubusercontent.com/CloudNativeWorks/certautopilot-archive/main/get.sh \
  | sudo bash -s -- \
      --version=1.5.18 \
      --mongo=local \
      --tls=self-signed \
      --port=443

Flags are positional-style; everything has a sensible default.

FlagDefaultEffect
--versionrequiredPinned semver. There is no latest resolution — omitting it aborts the install.
--mongolocallocal installs Mongo. external uses --mongo-uri.
--tlsself-signedself-signed or provided. There is no letsencrypt mode — any other value aborts.
--cert / --key—Required for --tls=provided.
--port443Public HTTPS port.
--enable-backupoffInstalls the nightly backup timer. Without it there is no automatic backup.
--secrets-from—Adopt an existing secrets.env — the only correct way to add a node to an existing install without losing decryption.
--mongo-versionautoResolved per OS (7.0 on jammy/focal/EL9, 8.0 on noble/EL10, 8.2 on newer kernels). Replica-set installs always use 8.0.
--backend-port18181Loopback port the backend binds.
--bind-host / --extra-hostnames—Hostnames baked into the self-signed certificate.
--kek-providerenvenv or pkcs11. Immutable after install.
--no-firewall / --non-interactiveoffSkip firewall rules / suppress prompts.
--nodes—Multi-node: comma-separated host list, THIS machine first. 3+ nodes build a MongoDB replica set on the first three; see High availability.
--ssh-user / --ssh-port / --ssh-key / --ssh-bootstraproot / 22 / — / autoSSH access to the other --nodes hosts (--ssh-bootstrap mints and pushes a key with one password prompt per node).

Single-node behaviour is unchanged by the multi-node feature — without --nodes the installer runs exactly the classic sequence.

Filesystem layout​

/etc/certautopilot/            config.yaml, secrets.env, tls/, mongo-root.env, topology.yaml
/usr/local/bin/certautopilot   the backend binary (plus the cap, cap-kek, cap-cluster wrappers)
/usr/share/certautopilot/web/  the React bundle nginx serves
/var/lib/certautopilot/        runtime state (the service's working directory)
/var/backups/certautopilot/    nightly archives — only with --enable-backup
/etc/nginx/conf.d/certautopilot.conf

MongoDB's data lives where the distribution package puts it (/var/lib/mongodb on Debian/Ubuntu, /var/lib/mongo on RHEL), not under /var/lib/certautopilot. The backend logs to the journal — journalctl -u certautopilot; there is no application log file.

systemd services​

  • certautopilot.service — the all-mode application.
  • mongod.service — the distribution's own unit, only when --mongo=local.
  • certautopilot-backup.timer — only with --enable-backup.
  • nginx.service — TLS terminator.
sudo systemctl status certautopilot
sudo journalctl -u certautopilot -f

Upgrade​

Re-run the installer with the new --version. It stops the service, swaps the binary, re-renders the systemd unit, nginx site and TLS material, refreshes the cap / cap-kek / cap-cluster wrappers, and starts again. There are no schema migrations — indexes are ensured idempotently at startup and the few backfills are additive.

Take a backup first

For any upgrade that crosses a minor version (e.g. 1.4.x → 1.5.x), take a backup first. Rollback is "run the previous binary" — there is no migration to reverse — but a backup is still the only protection against a defect that writes bad data.

On a multi-node (--nodes) fleet, run the upgrade on every node: hosts with no local mongod and replica-set secondaries first, the primary last. upgrade.sh prints this reminder but upgrades only the host it runs on.

TLS​

Two install-time options:

  1. --tls=self-signed (default) — generated locally. Useful for setup; replace before exposing to users. nginx reads it from /etc/certautopilot/tls/server.{crt,key}.
  2. --tls=provided --cert=<pem> --key=<pem> — your own material. The installer copies the files into nginx's path (/etc/certautopilot/tls/server.{crt,key}) and reloads.

Once installed and running, CertAutoPilot can also manage its own TLS — issue a certificate from any configured CA, distribute it to its own nginx via the SSH module, and let renewal keep it fresh (the dog-food pattern). Exact paths and the reload action are in Manage CAP's own TLS certificate.

Uninstall​

Run uninstall.sh from an extracted release tarball (it is not installed onto the host):

sudo ./uninstall.sh                    # remove the service and binary; keep data, config and KEK
sudo ./uninstall.sh --purge            # ALSO wipe /etc/certautopilot (config + secrets.env = the KEK)
sudo ./uninstall.sh --purge-db         # implies --purge, and removes the local MongoDB package + data
sudo ./uninstall.sh --purge-nginx      # implies --purge, and force-purges the nginx package
sudo ./uninstall.sh --yes-i-mean-it    # skip the confirmation prompts
danger
--purge-db and --purge-nginx both imply --purge

They are not additive options on top of the plain uninstall — each one turns on --purge as well, so both wipe /etc/certautopilot including secrets.env, and that file is your KEK. Without it the existing database cannot be decrypted. If you want to remove MongoDB or nginx while keeping the KEK, back up /etc/certautopilot/secrets.env first.

Without --purge, /etc/certautopilot — including secrets.env and therefore your KEK — is preserved for a reinstall. Keep it: without that file the existing database cannot be decrypted.

See also​