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.

00What 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.

PREPrerequisites

• 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.
• sudo access.
• 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 TXT records in your zone.

01Install 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.4.0 --mongo=local

When the installer finishes you will see the URL and a one-time setup token. Browse to https://<your-host>/, accept the self-signed certificate warning, and paste the token.

02First login & admin user

1. Open https://<host>/setup in your browser.
2. Paste the setup token from the installer output.
3. Create the initial admin user: display name, email, a strong password.
4. You are redirected to the dashboard. The first user is the organization owner; it can invite every other user.

03Create a project

Almost everything in CertAutoPilot is scoped to a project — ACME accounts, DNS credentials, certificates, distribution targets. The owner role can create as many projects as you need.

1. Top-left Project selector → New project.
2. Give it a name (e.g. production), a short description, and save.
3. The selector now shows the new project as active; all subsequent configuration lands inside it.

04Add 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.

1. Go to Settings → ACME Accounts → New.
2. Pick Let's Encrypt (Staging) from the provider list.
3. Email: the address you want certificate expiry notices sent to.
4. Key type: ECDSA P-256 (default, smallest + fastest).
5. 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).

05Add a DNS credential

DNS-01 validation needs write access to your DNS zone. CertAutoPilot supports 12 providers out of the box; this walkthrough uses Cloudflare.

1. Create an API Token in the Cloudflare dashboard with Zone → DNS → Edit scoped to your zone.
2. In CertAutoPilot: Settings → DNS Credentials → New.
3. Provider: Cloudflare; Name: cloudflare-production; API Token: paste the token.
4. Click Test connectivity. Success → Save.

Per-provider auth fields and required permissions: DNS providers overview.

06Register your zone

1. Settings → Zones → New.
2. Zone apex: example.com; DNS credential: cloudflare-production.
3. Save. The scheduler verifies the zone is reachable and the credential has write access.

07Issue your first certificate

1. Certificates → New.
2. Issuer: select the ACME account you created in step 4.
3. Common name: api.example.com. Add SANs (Subject Alternative Names) if you need them.
4. Key type: ECDSA P-256.
5. Auto-renew: enabled. (The scheduler renews 30 days before expiry by default.)
6. 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.

08Verify

Open the certificate's detail page and confirm:

• Status: active.
• Issuer: (STAGING) Let's Encrypt.
• Expires: ~90 days out.
• Timeline: events for cert.requested, cert.issued, and cert.downloaded.

→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.

I lost the setup token

The token is single-use and only valid while the system has no admin users. On the install host run sudo journalctl -u certautopilot --since "10 minutes ago" | grep "setup token". If the token has already been consumed, you must reset via sudo certautopilot setup --reset on the host.

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.