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.
| Flag | Default | Effect |
|---|---|---|
--version | required | Pinned semver. There is no latest resolution — omitting it aborts the install. |
--mongo | local | local installs Mongo. external uses --mongo-uri. |
--tls | self-signed | self-signed or provided. There is no letsencrypt mode — any other value aborts. |
--cert / --key | — | Required for --tls=provided. |
--port | 443 | Public HTTPS port. |
--enable-backup | off | Installs 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-version | auto | Resolved 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-port | 18181 | Loopback port the backend binds. |
--bind-host / --extra-hostnames | — | Hostnames baked into the self-signed certificate. |
--kek-provider | env | env or pkcs11. Immutable after install. |
--no-firewall / --non-interactive | off | Skip 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-bootstrap | root / 22 / — / auto | SSH 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— theall-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.
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:
--tls=self-signed(default) — generated locally. Useful for setup; replace before exposing to users. nginx reads it from/etc/certautopilot/tls/server.{crt,key}.--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
--purge-db and --purge-nginx both imply --purgeThey 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
- Requirements & sizing — host requirements, topology choice, and capacity planning
- Manage CAP's own TLS certificate — replace the self-signed cert with a CAP-issued, auto-renewed one
- Docker Compose
- Helm chart
- High availability
- Encryption & KEK — how the
secrets.envKEK is used, and KEK rotation - Backup & restore