diff --git a/README.md b/README.md index 0bc443c..df5d078 100644 --- a/README.md +++ b/README.md @@ -211,18 +211,15 @@ Each directory contains a `docker-compose.yml` and a `README.md` explaining the | Guide | Description | |-------|-------------| -| [Why certctl?](docs/why-certctl.md) | How certctl compares to open-source and enterprise certificate management platforms | +| [Why certctl?](docs/why-certctl.md) | How certctl compares to ACME clients, agent-based SaaS, and enterprise platforms | | [Concepts](docs/concepts.md) | TLS certificates explained from scratch — for beginners who know nothing about certs | -| [Quick Start](docs/quickstart.md) | Extended quickstart — dashboard, API, CLI, discovery, stakeholder demo flow | +| [Quick Start](docs/quickstart.md) | 5-minute setup — dashboard, API, CLI, discovery, stakeholder demo flow | +| [Deployment Examples](docs/examples.md) | 5 turnkey scenarios (ACME+NGINX, wildcard DNS-01, private CA, step-ca, multi-issuer) with migration guides | | [Advanced Demo](docs/demo-advanced.md) | Issue a certificate end-to-end with technical deep-dives | | [Architecture](docs/architecture.md) | System design, data flow diagrams, security model | | [Feature Inventory](docs/features.md) | Complete reference of all V2 capabilities, API endpoints, and configuration | -| [Configuration Reference](docs/features.md) | All 39 environment variables across server, agent, and connector config | -| [Connectors](docs/connectors.md) | Build custom issuer, target, and notifier connectors | +| [Connector Reference](docs/connectors.md) | Configuration for all 7 issuers, 10 targets, and 5 notifier connectors | | [Compliance Mapping](docs/compliance.md) | SOC 2 Type II, PCI-DSS 4.0, NIST SP 800-57 alignment guides | -| [Migrate from Certbot](docs/migrate-from-certbot.md) | Step-by-step migration from Certbot/Let's Encrypt cron jobs | -| [Migrate from acme.sh](docs/migrate-from-acmesh.md) | Migration guide for acme.sh users with DNS-01 scripts | -| [certctl for cert-manager Users](docs/certctl-for-cert-manager-users.md) | Using certctl alongside cert-manager for non-Kubernetes infrastructure | | [OpenAPI 3.1 Spec](api/openapi.yaml) | 97 operations, full request/response schemas | ## CLI diff --git a/docs/certctl-for-cert-manager-users.md b/docs/certctl-for-cert-manager-users.md index ea02b8d..43a2091 100644 --- a/docs/certctl-for-cert-manager-users.md +++ b/docs/certctl-for-cert-manager-users.md @@ -82,7 +82,7 @@ Agents scan configured directories and report back all existing certs. In the da Set up the same issuer certctl uses for non-Kubernetes certs: - **ACME** (Let's Encrypt, for public certs) - **step-ca** (Smallstep, for internal certs) -- **Vault PKI** (planned) (HashiCorp Vault, for enterprise PKI) +- **Vault PKI** (HashiCorp Vault, for enterprise PKI) - **Private CA** (your own internal root CA) No new CA infrastructure needed. If cert-manager already uses your CA, certctl points to the same one. @@ -115,7 +115,7 @@ Certificates are linked to issuers and profiles when created or claimed from dis If cert-manager and certctl both use the same CA: - **ACME**: cert-manager uses ClusterIssuer + certctl uses ACME connector → same Let's Encrypt account, transparent coexistence - **step-ca**: cert-manager uses external issuer CRD + certctl uses step-ca connector → same provisioner, shared certificate inventory -- **Vault PKI** (planned): cert-manager uses external issuer CRD + certctl uses Vault connector → same mount, same audit trail +- **Vault PKI**: cert-manager uses external issuer CRD + certctl uses Vault connector → same mount, same audit trail No conflict. They just issue certs through the same CA. certctl's discovery scanning finds cert-manager-issued certs and shows them alongside certctl-managed ones. @@ -138,7 +138,7 @@ For now: cert-manager handles Kubernetes, certctl handles everything else. They ## Next Steps -1. Review [Quick Start](./quickstart.md) for a 5-minute demo -2. Explore [Architecture](./architecture.md#agents) for deployment architecture -3. Read about [Discovery Scanning](./quickstart.md#certificate-discovery) to auto-find certs -4. Check [Helm Chart](../deploy/helm/certctl/) for production Kubernetes deployment +1. Run through the [Quick Start](./quickstart.md) for a 5-minute demo +2. Try the [Multi-Issuer example](../examples/multi-issuer/multi-issuer.md) — manages public and internal certs from one dashboard +3. Explore [Architecture](./architecture.md#agents) for deployment patterns +4. Check the [Helm Chart](../deploy/helm/certctl/) for production Kubernetes deployment diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..08aad18 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,120 @@ +# Deployment Examples + +Five turnkey docker-compose scenarios, each runnable in under 5 minutes. Pick the one closest to your setup. + +## Which Example Should I Use? + +| I need to... | Example | Issuer | Target | +|--------------|---------|--------|--------| +| Get Let's Encrypt certs for NGINX on a public server | [ACME + NGINX](#acme--nginx) | ACME (HTTP-01) | NGINX | +| Issue wildcard certs without opening port 80 | [Wildcard DNS-01](#wildcard-dns-01) | ACME (DNS-01) | Any | +| Run an internal CA for services behind a firewall | [Private CA + Traefik](#private-ca--traefik) | Local CA | Traefik | +| Use Smallstep step-ca as my PKI backend | [step-ca + HAProxy](#step-ca--haproxy) | step-ca | HAProxy | +| Manage both public and internal certs from one dashboard | [Multi-Issuer](#multi-issuer) | ACME + Local CA | Mixed | + +**Already using another tool?** See the migration sections below each example for Certbot, acme.sh, and cert-manager users. + +--- + +## ACME + NGINX + +**Scenario:** You have one or more public-facing domains, NGINX as the reverse proxy, and want automated Let's Encrypt certificates with HTTP-01 challenges. + +**What it deploys:** certctl server + PostgreSQL + certctl agent + NGINX, all on one Docker network. The agent generates keys locally (ECDSA P-256), submits CSRs to the server, receives signed certs from Let's Encrypt, and deploys them to NGINX with automatic reload. + +**Prerequisites:** A domain pointing to your server, ports 80 and 443 open, Docker Compose v20.10+. + +```bash +cd examples/acme-nginx +cp .env.example .env # Edit with your domain and email +docker compose up -d +``` + +The full walkthrough — including how HTTP-01 challenges work, adding multiple domains, switching to staging for testing, and a production checklist — is in the [example README](../examples/acme-nginx/acme-nginx.md). + +**Migrating from Certbot?** certctl discovers your existing `/etc/letsencrypt/live/` certificates automatically. You keep your ACME account, disable the Certbot cron, and certctl takes over renewal with centralized visibility and deployment verification. The step-by-step process is in [Migrating from Certbot](migrate-from-certbot.md). + +--- + +## Wildcard DNS-01 + +**Scenario:** You need wildcard certificates (`*.example.com`) or your servers aren't reachable from the internet (no port 80). DNS-01 validates ownership by creating a TXT record at your DNS provider. + +**What it deploys:** certctl server + PostgreSQL + certctl agent. Includes a Cloudflare DNS hook script as a working reference — swap in your own DNS provider (Route53, Azure DNS, Google Cloud DNS, or any provider with an API). + +**Prerequisites:** A domain, API credentials for your DNS provider, Docker Compose. + +```bash +cd examples/acme-wildcard-dns01 +cp .env.example .env # Edit with domain, email, DNS provider credentials +docker compose up -d +``` + +The full walkthrough — including DNS-PERSIST-01 (set a TXT record once, never touch DNS again on renewals), adapting scripts for other providers, and propagation troubleshooting — is in the [example README](../examples/acme-wildcard-dns01/acme-wildcard-dns01.md). + +**Migrating from acme.sh?** Your existing `dns_*` hook scripts are compatible with certctl's DNS-01 — they use the same pattern (shell scripts creating TXT records). The migration guide covers script adaptation, discovery of existing acme.sh certificates, and phasing out the acme.sh cron. See [Migrating from acme.sh](migrate-from-acmesh.md). + +--- + +## Private CA + Traefik + +**Scenario:** Internal services that don't need public CA validation. You run your own certificate authority — either a self-signed root for development, or a subordinate CA chained to your enterprise root (e.g., Active Directory Certificate Services). + +**What it deploys:** certctl server + PostgreSQL + certctl agent + Traefik. The Local CA issuer signs certificates directly. Traefik watches a cert directory and auto-reloads when new files appear. + +**Prerequisites:** Docker Compose. For sub-CA mode, you'll need a CA certificate and key signed by your enterprise root. + +```bash +cd examples/private-ca-traefik +docker compose up -d # Self-signed mode (no .env needed for demo) +``` + +The full walkthrough — including sub-CA setup with `CERTCTL_CA_CERT_PATH` and `CERTCTL_CA_KEY_PATH`, creating certificates via the API, monitoring deployments, and production hardening — is in the [example README](../examples/private-ca-traefik/private-ca-traefik.md). + +--- + +## step-ca + HAProxy + +**Scenario:** You use Smallstep's step-ca as your private PKI and want automated lifecycle management for certificates deployed to HAProxy load balancers. + +**What it deploys:** certctl server + PostgreSQL + certctl agent + step-ca (with JWK provisioner) + HAProxy. certctl issues certs via step-ca's native `/sign` API, combines them into HAProxy's expected PEM format (cert + chain + key in one file), and reloads HAProxy. + +**Prerequisites:** Docker Compose. + +```bash +cd examples/step-ca-haproxy +docker compose up -d +``` + +The full walkthrough — including step-ca provisioner configuration, integrating with an existing step-ca instance, HAProxy PEM format details, and advanced features (approval workflows, policy-based renewal, multi-instance HAProxy) — is in the [example README](../examples/step-ca-haproxy/step-ca-haproxy.md). + +--- + +## Multi-Issuer + +**Scenario:** You manage both public-facing services (needing Let's Encrypt or another public CA) and internal services (using a private CA) and want a single dashboard for everything. + +**What it deploys:** certctl server + PostgreSQL + certctl agent configured with both an ACME issuer and a Local CA issuer. Demonstrates issuer assignment via profiles — public services get ACME certs, internal services get Local CA certs, all visible in one inventory. + +**Prerequisites:** Docker Compose. For real ACME certs, a public domain and port 80 access. + +```bash +cd examples/multi-issuer +docker compose up -d +``` + +The full walkthrough — including profile-based issuer assignment, testing with ACME staging, Local CA enterprise sub-CA mode, and scaling beyond Docker Compose — is in the [example README](../examples/multi-issuer/multi-issuer.md). + +**Using cert-manager for Kubernetes?** certctl complements cert-manager — cert-manager handles in-cluster certs, certctl handles everything outside: VMs, bare metal, network appliances, Windows servers. They can share the same CA (ACME, step-ca, Vault PKI). See [certctl for cert-manager Users](certctl-for-cert-manager-users.md). + +--- + +## Beyond These Examples + +These 5 scenarios cover the most common deployment patterns, but certctl supports 7 issuer backends and 10 target connectors. Once you have the basics running, you can mix and match: + +**Issuers:** ACME (Let's Encrypt, ZeroSSL, Buypass, Google Trust Services), Local CA (self-signed or sub-CA), step-ca, Vault PKI, DigiCert CertCentral, OpenSSL/Custom CA script, Sectigo (coming soon). + +**Targets:** NGINX, Apache, HAProxy, Traefik, Caddy, Envoy, IIS (local PowerShell or WinRM proxy), Postfix, Dovecot, F5 BIG-IP (coming soon). + +See [Connector Reference](connectors.md) for configuration details on every issuer and target. diff --git a/docs/migrate-from-acmesh.md b/docs/migrate-from-acmesh.md index 5585135..9771ec4 100644 --- a/docs/migrate-from-acmesh.md +++ b/docs/migrate-from-acmesh.md @@ -267,8 +267,9 @@ export CERTCTL_ACME_DNS_PRESENT_SCRIPT=/etc/certctl/dns/cloudflare-present.sh certctl automatically falls back to DNS-01 if the CA doesn't support dns-persist-01 yet. -## Support +## Next Steps -See [Connector Configuration](connectors.md) for advanced ACME options (EAB, ARI, custom timeouts). - -See [Discovery Guide](concepts.md#certificate-discovery) for managing discovered certificates at scale. +- Try the [Wildcard DNS-01 example](../examples/acme-wildcard-dns01/acme-wildcard-dns01.md) — a working docker-compose with Cloudflare hooks you can adapt for your DNS provider +- See [Connector Reference](connectors.md) for advanced ACME options (EAB, ARI, custom timeouts) +- See [Discovery Guide](concepts.md#certificate-discovery) for managing discovered certificates at scale +- See all [Deployment Examples](./examples.md) for other scenarios (ACME+NGINX, private CA, step-ca, multi-issuer) diff --git a/docs/migrate-from-certbot.md b/docs/migrate-from-certbot.md index 0a0319b..192979b 100644 --- a/docs/migrate-from-certbot.md +++ b/docs/migrate-from-certbot.md @@ -166,6 +166,7 @@ certctl will stop renewing that cert when the policy is disabled. Certbot resume ## Next Steps +- Try the [ACME + NGINX example](../examples/acme-nginx/acme-nginx.md) — a working docker-compose you can run locally before deploying to production - Review the [Concepts Guide](./concepts.md) for terminology (profiles, policies, agents, jobs) - Explore [Network Discovery](./quickstart.md#network-discovery-agentless) to find certificates you didn't know about -- Set up [Kubernetes cert-manager integration](./certctl-for-cert-manager-users.md) if you manage in-cluster certs too +- See all [Deployment Examples](./examples.md) for other scenarios (wildcard DNS-01, private CA, step-ca, multi-issuer) diff --git a/docs/quickstart.md b/docs/quickstart.md index 03bb5ed..cf35048 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -461,7 +461,10 @@ The `-v` flag removes the PostgreSQL data volume for a clean slate. ## What's Next +**Ready to deploy with your stack?** The [Deployment Examples](examples.md) page has 5 turnkey docker-compose scenarios — pick the one closest to your setup and have it running in minutes. It also covers migration paths from Certbot, acme.sh, and cert-manager. + +- **[Deployment Examples](examples.md)** — ACME+NGINX, wildcard DNS-01, private CA+Traefik, step-ca+HAProxy, multi-issuer - **[Advanced Demo](demo-advanced.md)** — Issue a real certificate via the Local CA end-to-end - **[Architecture](architecture.md)** — How the control plane, agents, and connectors work together -- **[Connector Guide](connectors.md)** — Build custom connectors for your infrastructure +- **[Connector Reference](connectors.md)** — Configuration for all 7 issuers and 10 targets - **[Concepts Guide](concepts.md)** — TLS certificates, CAs, and private keys explained from scratch