Skip to main content
2 video tutorials

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.
  • 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.
Not running on Linux?

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.

Self-signed TLS

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​

  1. Open https://<host>/setup in your browser.
  2. Create the initial admin user: username, email and a password (at least 10 characters).
  3. Name the first project (a name plus a slug — lowercase letters, numbers and hyphens).
  4. 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.

  1. Settings → Projects → New.
  2. Give it a name (e.g. production), a slug, an optional description, and save.
  3. 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.

  1. Go to Settings → Certificate Authorities → ACME Accounts tab → Add Account.
  2. Give it a name, then pick Let's Encrypt as the CA provider and Staging as the environment.
  3. Email: the address you want certificate expiry notices sent to.
  4. 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.

  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.

Register your zone​

  1. Settings → Zones → Add Zone.
  2. Domains: example.com (list more, one per line, when the same DNS account serves them); DNS credential: cloudflare-production.
  3. 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​

  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.

Verify​

Open the certificate's detail page and confirm:

  • Status: active.
  • Issuer: (STAGING) Let's Encrypt.
  • Expires: ~90 days out.
  • Timeline: a cert.issued event (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 →

Get Started — First Admin, Let’s Encrypt and Google Cloud DNSYouTube ↗
Issue Your First Certificate with Let’s Encrypt and DNS-01YouTube ↗