Quickstart
Install CertAutoPilot, create your first admin user, onboard an ACME account and a DNS credential, then issue your first certificate — all on a single host, in under 15 minutes.
What you will have at the end
- A running CertAutoPilot instance serving HTTPS on port 443.
- A local MongoDB with SCRAM-SHA-256 auth, managed for you.
- An admin user, one organization, one project.
- An ACME account at Let's Encrypt staging, a Cloudflare DNS credential, and a DV certificate issued via DNS-01.
Prerequisites
- A 64-bit Linux host (Ubuntu 22.04+, Debian 12, RHEL/Oracle/Rocky/Alma 9, or newer). 2 vCPU / 2 GiB RAM is the practical minimum.
sudoaccess.- A public DNS name you control (for the DNS-01 challenge) — for this walkthrough we use
example.com. - An API token for your DNS provider with permission to create and delete
TXTrecords in your zone.
Use the Docker Compose path on macOS / Windows for development, or deploy via Helm on Kubernetes. The concepts below still apply.
Install the server
The standalone installer drops a single binary, sets up nginx as the TLS terminator, provisions a local MongoDB with authentication, and generates all secrets on first run. No manual config editing required.
curl -fsSL https://raw.githubusercontent.com/CloudNativeWorks/certautopilot-archive/main/get.sh \
| sudo bash -s -- --version=1.5.52 --mongo=local
Pin --version to the latest release — the installer downloads that exact build.
When the installer finishes you will see the URL. Browse to https://<your-host>/, accept the self-signed certificate warning, and complete the setup wizard.
The quickstart installer uses a self-signed TLS cert so you can reach the UI on first boot. Replace with your own CA-signed material via --tls=provided --cert=... --key=... before exposing to users. See Standalone install → TLS.
First login & admin user
- Open
https://<host>/setupin your browser. - Create the initial admin user: username, email and a password (at least 10 characters).
- Name the first project (a name plus a slug — lowercase letters, numbers and hyphens).
- You are redirected to the dashboard. The first user is the organization owner; it can invite every other user.
Create a project
Almost everything in CertAutoPilot is scoped to a project — ACME accounts, DNS credentials, certificates, distribution targets. The setup wizard already created your first project, so you can skip this step; the owner role can create as many more as you need.
- Settings → Projects → New.
- Give it a name (e.g.
production), a slug, an optional description, and save. - Pick it in the top-bar Project selector; all subsequent configuration lands inside the selected project.
Add an ACME account
An ACME account holds the registration with a CA. For first-time use we recommend Let's Encrypt staging — it has generous rate limits and issues identical-format certs (not browser-trusted). Switch to production once the flow works end-to-end.
- Go to Settings → Certificate Authorities → ACME Accounts tab → Add Account.
- Give it a name, then pick Let's Encrypt as the CA provider and Staging as the environment.
- Email: the address you want certificate expiry notices sent to.
- Save. The server registers with the CA; you will see a green "active" badge within seconds.
See ACME accounts for EAB-bound CAs (Google Trust Services, ZeroSSL, SSL.com).
Add a DNS credential
DNS-01 validation needs write access to your DNS zone. CertAutoPilot supports 19 providers out of the box; this walkthrough uses Cloudflare.
- Create an API Token in the Cloudflare dashboard with Zone → DNS → Edit scoped to your zone.
- In CertAutoPilot: Settings → DNS Credentials → New.
- Provider: Cloudflare; Name:
cloudflare-production; API Token: paste the token. - Click Test connectivity. Success → Save.
Per-provider auth fields and required permissions: DNS providers overview.
Register your zone
- Settings → Zones → Add Zone.
- Domains:
example.com(list more, one per line, when the same DNS account serves them); DNS credential:cloudflare-production. - Save. The credential must belong to the same project; it is exercised for real the first time a DNS-01 challenge is published, so use Test connectivity on the credential beforehand.
Issue your first certificate
- Certificates → New.
- Issuer: select the ACME account you created in step 4.
- Common name:
api.example.com. Add SANs (Subject Alternative Names) if you need them. - Key type: ECDSA P-256.
- Auto-renew: enabled. (The scheduler renews 30 days before expiry by default.)
- Review and submit. A background job starts; its progress shows on the certificate's detail page.
You will see the workflow move through four stages: ACME order created → DNS challenge published → CA validated → Certificate issued. For DNS-01 this typically takes 20–90 seconds depending on your DNS provider's propagation.
Verify
Open the certificate's detail page and confirm:
- Status:
active. - Issuer:
(STAGING) Let's Encrypt. - Expires: ~90 days out.
- Timeline: a
cert.issuedevent (downloads are recorded in the audit log, not on the timeline).
Next steps
- Issuance walkthrough — every form field explained, including key types, policy enforcement, and manual DNS.
- Distribution — push the issued certificate to SSH servers, Kubernetes secrets, F5, NetScaler, IIS, Vault, or a webhook.
- KEK rotation — rotate the key-encryption-key on a schedule for compliance (SOC 2 / ISO 27001).
- Notifications — wire Slack, Teams, or email alerts for renewal events.
Troubleshooting
The installer exits with "port 443 in use"
Another web server is already bound. Stop it (sudo systemctl stop apache2 or nginx) or re-run the installer with --port=8443.
Where is the setup token?
There is no setup token: /setup is open until the first admin account is created, and then permanently closed (a second submission gets setup already completed). If you lost the admin password rather than a token, reset it on the host with cap user reset-password.
ACME account registration fails
Usually an outbound-network issue — the backend must reach the ACME directory (acme-staging-v02.api.letsencrypt.org for staging). Confirm from the host: curl -sI https://acme-staging-v02.api.letsencrypt.org/directory. If you are behind an outbound proxy, export HTTPS_PROXY in /etc/certautopilot/secrets.env and restart.
DNS challenge never resolves
The job sits in validating for several minutes. Check Jobs → click the job → Logs — propagation errors appear there. Likely causes: insufficient API token scope, a CNAME on the challenge record that points elsewhere, or a very long TTL on a pre-existing _acme-challenge record. Delete stale records manually and retry.
See also
Video tutorials
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →