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.

On the RHEL family the installer takes nginx and its helper tools from the distro's own BaseOS/AppStream repositories, so the host must be able to reach them — a Red Hat subscription, a Satellite/mirror, or the installation DVD configured as a local dnf repository all work; an unregistered RHEL with no repository fails at the nginx step. MongoDB comes from MongoDB's own repository. The installer switches SELinux to permissive (runtime and /etc/selinux/config). When firewalld or ufw is active it opens the HTTPS port (--port, default 443) and, on replica-set members, 27017 from the other cluster nodes only. No plain-HTTP port is opened. The full list of what installation and the running cluster need is on Installation and inbound network access.

Linux kernel 6.19 through 7.0.13 cannot run a local MongoDB. MongoDB's memory allocator is incompatible with those kernels on every MongoDB version: some builds refuse to start, others start and crash within minutes. Kernel 7.0.14 fixes it. With --mongo=local the installer stops in its first checks, before anything is installed, and names the fix: upgrade the kernel to 7.0.14 or later and reboot (on Ubuntu sudo apt update && sudo apt full-upgrade; uname -r shows only 7.0.0-<n>-generic, the upstream version is the last field of cat /proc/version_signature), boot a 6.18 or older kernel, or use --mongo=external. On a replica-set install every one of the first three nodes is checked.

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.52 \
--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). On Linux kernel 7.0.14 or newer (for example Ubuntu 26.04) 8.2 is used instead, because 8.0 refuses to start there. Replica-set installs use 8.0 on every member, or 8.2 on every member when any of the first three nodes runs such a kernel.
--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.

Release signature​

Each release publishes, next to the tarball, certautopilot_<version>_checksums.txt and a detached signature of it, certautopilot_<version>_checksums.txt.asc, made with the CertAutoPilot release key (fingerprint 68FA 9CAD B2C0 5E10 4AE0 B1BB ECEF 4DC4 BC8D B41C; the public key is deploy/keys/release-signing.asc in the repository). To check a download by hand:

gpg --import release-signing.asc
gpg --verify certautopilot_<version>_checksums.txt.asc certautopilot_<version>_checksums.txt
sha256sum -c --ignore-missing certautopilot_<version>_checksums.txt

Both files are attached to the GitHub release and carried in the release's GHCR bundle. install.sh and upgrade.sh verify the SHA-256 checksums of what they download, but not the signature — run the check above yourself when you need the checksums file proven to come from the release key.

The CertAutoPilot OS appliance performs the same check before it installs an application update and refuses a release without a valid signature from this key. Releases published before signing was introduced carry no .asc file.

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​

Upgrade with update.sh / upgrade.sh (Upgrade): it swaps the binary and frontend, refreshes the systemd unit and the cap / cap-kek / cap-cluster wrappers, and restarts — config.yaml, secrets.env, TLS material and MongoDB are left untouched, and the nginx site is changed in one way only: since 1.7.0 the old public /metrics location is removed (both by the upgrade and by a re-run of the installer). A copy of the site file is kept next to it as certautopilot.conf.bak.<timestamp>; if nginx -t refuses the edited file, that copy is put back unchanged and the log asks you to remove the block by hand. Re-running the installer (get.sh, to change install flags) reuses the existing TLS material and preserves the nginx site when /etc/nginx/conf.d/certautopilot.conf still validates (so rate limits, extra headers or mTLS you added survive); the release's version is dropped next to it as certautopilot.conf.example for you to diff and merge, and a file that no longer passes nginx -t is moved aside and re-rendered. Delete the file before re-running to force a fresh render — for example to take the security-header set 1.5.54 added. There are no schema migrations — indexes are ensured idempotently at startup and the few backfills are additive. The one exception so far: 1.5.54 replaces the AD CS workflow records' expiry index at startup (the old index on expires_at is dropped, a purge_at date is backfilled a week past each deadline, and the new index is built on it); nothing needs to be done by hand.

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​