gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 16:01:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Phase 2 mechanical file moves to subdirectory structure

Browse Source 
Pure git mv operations; no content edits. Internal links remain pointing
at old paths and will be fixed in Phase 11. Per the Phase 1 audit
recommendations at cowork/docs-overhaul-phase-1-audit-2026-05-04/.

35 files moved across 8 audience-organized subdirectories:

  docs/getting-started/ (5):
    quickstart.md, concepts.md, examples.md, advanced-demo.md (was
    demo-advanced.md), why-certctl.md

  docs/reference/ (6):
    architecture.md, api.md (was openapi.md), mcp.md,
    intermediate-ca-hierarchy.md, deployment-model.md (was
    deployment-atomicity.md), vendor-matrix.md (was
    deployment-vendor-matrix.md)

  docs/reference/protocols/ (6):
    acme-server.md, acme-server-threat-model.md, scep-intune.md,
    est.md, crl-ocsp.md, async-ca-polling.md (was async-polling.md)

  docs/operator/ (4):
    security.md, tls.md, database-tls.md, approval-workflow.md

  docs/operator/runbooks/ (3):
    cloud-targets.md (was runbook-cloud-targets.md), expiry-alerts.md
    (was runbook-expiry-alerts.md), disaster-recovery.md

  docs/migration/ (3):
    from-certbot.md (was migrate-from-certbot.md), from-acmesh.md
    (was migrate-from-acmesh.md), cert-manager-coexistence.md (was
    certctl-for-cert-manager-users.md)

  docs/compliance/ (4):
    index.md (was compliance.md), soc2.md (was compliance-soc2.md),
    pci-dss.md (was compliance-pci-dss.md), nist-sp-800-57.md (was
    compliance-nist.md)

  docs/contributor/ (4):
    testing-strategy.md, test-environment.md (was test-env.md),
    ci-pipeline.md, qa-test-suite.md (was qa-test-guide.md)

Deferred to later Phase 2 sub-phases:
  - connectors.md split (Phase 4): docs/connectors.md +
    docs/connector-{apache,f5,iis,k8s,nginx}.md still at top level
  - testing-guide.md prune (Phase 5): docs/testing-guide.md still
    at top level
  - features.md disperse (Phase 6): docs/features.md still at top
    level
  - legacy-est-scep.md split (Phase 7): docs/legacy-est-scep.md
    still at top level
  - ACME walkthrough re-homing (Phase 8): three
    docs/acme-*-walkthrough.md still at top level
  - Upgrade docs archive (Phase 3): two docs/upgrade-*.md still
    at top level

Cross-reference updates (Phase 11) will happen after all moves and
content edits land. Internal links to docs/* paths are temporarily
broken until that phase completes.
This commit is contained in:
shankar0123
2026-05-05 02:49:28 +00:00
parent cda957f302
commit 3a807ae37e
35 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/migration/cert-manager-coexistence.md
+145
View File
@@ -0,0 +1,145 @@
# certctl for cert-manager Users
You run cert-manager inside Kubernetes and it works well for in-cluster certificates. But you also have VMs, bare-metal servers, network appliances, and legacy systems outside the cluster. cert-manager can't reach those. This guide shows how certctl complements cert-manager to give you unified certificate visibility and automation across your entire infrastructure.
## Not a Replacement
cert-manager is the right tool for in-cluster certs. It's tightly integrated with Kubernetes:
- Native CRDs (Certificate, ClusterIssuer, Issuer)
- Automatic cert injection into Ingress and Service objects
- Controller-driven renewal within the cluster
**certctl does not replace this.** Instead, it extends your certificate management to everything outside Kubernetes: VMs, bare metal, network appliances, Windows servers, and legacy systems.
## The Problem
Your setup:
- **cert-manager**: handles all certs in Kubernetes (TLS for Ingress, service-to-service, internal services)
- **Everything else**: NGINX/Apache on VMs, HAProxy load balancers on bare metal, network appliances, Windows servers with IIS — these are managed inconsistently. Maybe Certbot cron jobs, maybe manual renewal, maybe deprecated cert files sitting around.
Result:
- No unified visibility — you don't know when non-Kubernetes certs expire
- Renewal failures go unnoticed until the cert is already expired
- Audit trail fragmented across multiple tools
- Scaling to hundreds of machines becomes impossible
## The Solution
Deploy certctl control plane once (Docker Compose, Kubernetes Helm chart, or self-hosted). Deploy agents on your VMs, bare metal, and network appliances. One dashboard shows:
- **All cert-manager certs** via discovery scanning (agents find cert-manager-issued certs copied to target machines, or scan the cluster directly)
- **All certctl-managed certs** issued by shared issuers (ACME, step-ca, Vault PKI (planned), private CA)
- **Unified renewal and deployment** across both worlds
- **Single pane of glass** with expiration timeline, renewal status, deployment verification, audit trail
## How to Set Up
### 1. Install certctl Control Plane
**Option A: Docker Compose** (quickest for evaluation)
```bash
cd /opt/certctl
docker compose up -d
# Dashboard & API: https://localhost:8443 (self-signed cert — pin with --cacert ./deploy/test/certs/ca.crt)
```
**Option B: Kubernetes** (recommended for prod)
```bash
helm install certctl deploy/helm/certctl/ \
--set auth.apiKey=YOUR_SECURE_KEY
```
### 2. Deploy Agents to Non-Kubernetes Infrastructure
On each VM, bare-metal server, or appliance (via proxy agent):
```bash
# Linux amd64
curl -sSL https://github.com/certctl-io/certctl/releases/download/v2.1.0/certctl-agent-linux-amd64 \
-o /usr/local/bin/certctl-agent
chmod +x /usr/local/bin/certctl-agent
# Config
sudo tee /etc/certctl/agent.env > /dev/null <<EOF
CERTCTL_SERVER_URL=https://certctl-control-plane:8443
CERTCTL_SERVER_CA_BUNDLE_PATH=/etc/certctl/tls/ca.crt
CERTCTL_API_KEY=your-api-key
CERTCTL_DISCOVERY_DIRS=/etc/nginx/certs,/etc/ssl,/etc/letsencrypt/live
CERTCTL_KEY_DIR=/var/lib/certctl/keys
EOF
sudo chmod 600 /etc/certctl/agent.env
# Start
sudo systemctl start certctl-agent
```
### 3. Enable Discovery Scanning
Agents scan configured directories and report back all existing certs. In the dashboard:
- **Discovery** page: all found certs grouped by agent
- Claim cert-manager certs to link them with Kubernetes metadata
- Dismiss obsolete certs
### 4. Configure Shared Issuers
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** (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.
### 5. Create Policies for Non-Kubernetes Certs
Go to **Policies** → **+ New Policy** to create enforcement rules:
- **Name:** e.g., "VM Certificate Policy"
- **Type:** `expiration_window` or `key_algorithm` (enforce renewal thresholds or crypto requirements)
- **Severity:** `high`
- **Config:** set your enforcement parameters
Certificates are linked to issuers and profiles when created or claimed from discovery. Policies add guardrails — enforcing key algorithm requirements, expiration windows, and other compliance rules across your fleet.
### 6. View Unified Inventory
**Dashboard** shows:
- Certificate status heatmap (all 1000 certs: cert-manager + certctl)
- Renewal job trends (both types)
- Expiration timeline (30/60/90 days)
- Agent fleet status (all infrastructure)
**Certificates** page filters by issuer (show me all ACME certs, or all step-ca certs):
- cert-manager certs discovered from Kubernetes nodes
- certctl-managed certs on VMs
- Network appliance certs auto-discovered
## Shared Infrastructure
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**: 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.
## Key Differences from cert-manager
| Feature | cert-manager | certctl |
|---------|--------------|---------|
| Target | In-cluster (Kubernetes) | Out-of-cluster (VMs, bare metal, appliances) |
| Configuration | CRDs (Certificate, ClusterIssuer, Issuer) | API + Dashboard (JSON REST) |
| Deployment | Injected into Secret objects, mounted by pods | Agent pulls work, deploys via target-specific API (file, service restart, proxy agent) |
| Renewal | Controller watches Certificate CRDs, triggers renewal when needed | Scheduler checks thresholds, agents poll for work |
| Audit | Kubernetes event log | Immutable append-only audit trail |
| Visibility | Per-namespace, per-resource | Fleet-wide, unified inventory |
## Future Integration
On the roadmap (V4): **cert-manager external issuer** — certctl acts as a ClusterIssuer backend for Kubernetes. This would allow cert-manager to request certificates from certctl, which could issue them via any of its connectors (step-ca, Vault, private CA, etc.). Pure integration play; no breaking changes.
For now: cert-manager handles Kubernetes, certctl handles everything else. They coexist seamlessly.
## Next Steps
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
docs/migration/from-acmesh.md
+275
View File
@@ -0,0 +1,275 @@
# Migrate from acme.sh to certctl
You use acme.sh to automate Let's Encrypt renewal across multiple servers. It works — but without centralized visibility, deployment verification, or policy enforcement.
This guide walks through moving your acme.sh workload to certctl while keeping your existing DNS provider setup.
## Why Migrate
**acme.sh strength:** Lightweight agent, works everywhere, integrates with any DNS provider via shell script hooks.
**acme.sh limitations:**
- No inventory visibility — certificates scattered across servers, no unified view of expiry dates or renewal status
- No deployment verification — cron job succeeds even if cert doesn't actually take effect on the service
- No policy enforcement — no way to require approval, audit who renewed what, or prevent misconfigurations
- No multi-server orchestration — each server manages its own renewals; no way to batch test or rollback
certctl adds a control plane that sees all your certificates, deploys with verification, enforces policy, and provides a complete audit trail. You keep the DNS-01 challenge scripts you already have.
## What You Keep
- **Existing certificates** — discovered automatically during migration, claimed in the dashboard
- **DNS provider scripts** — acme.sh's `dns_*` hooks are shell-script compatible with certctl's DNS-01 implementation
- **Same Let's Encrypt account** — ACME issuer in certctl uses the same account and email
## Migration Steps
### 1. Deploy certctl Server
Start with Docker Compose (5 minutes):
```bash
git clone https://github.com/certctl-io/certctl.git
cd certctl/deploy
docker compose up -d
```
Access the dashboard at `https://localhost:8443` with the API key from `.env`. The default compose stack ships a self-signed cert; pin with `--cacert ./deploy/test/certs/ca.crt` when calling the API from the host.
### 2. Deploy Agents
On each server running acme.sh certs, install the certctl agent:
```bash
curl -sSL https://raw.githubusercontent.com/certctl-io/certctl/master/install-agent.sh | bash
# Prompted for server URL and API key
```
Or manually:
```bash
# Download and install agent binary
wget https://github.com/certctl-io/certctl/releases/download/v2.1.0/certctl-agent-linux-amd64
chmod +x certctl-agent-linux-amd64
sudo mv certctl-agent-linux-amd64 /usr/local/bin/certctl-agent
# Create systemd unit
sudo tee /etc/systemd/system/certctl-agent.service > /dev/null <<EOF
[Unit]
Description=certctl Agent
After=network-online.target
[Service]
Type=simple
ExecStart=/usr/local/bin/certctl-agent
Environment="CERTCTL_SERVER_URL=https://certctl.internal:8443"
Environment="CERTCTL_API_KEY=your-api-key-here"
Environment="CERTCTL_DISCOVERY_DIRS=~/.acme.sh"
Restart=always
RestartSec=10s
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now certctl-agent
```
### 3. Discover Existing acme.sh Certificates
acme.sh stores certificates in `~/.acme.sh/<domain>/` (or `/etc/acme.sh/` if installed system-wide).
When you start the agent with `CERTCTL_DISCOVERY_DIRS` pointing to those directories, it scans for existing PEM/DER certificates and reports fingerprints to the control plane. The dashboard's **Discovery** page shows what was found.
Example agent systemd service (using home directory):
```bash
Environment="CERTCTL_DISCOVERY_DIRS=/home/user/.acme.sh"
```
Or for system-wide acme.sh:
```bash
Environment="CERTCTL_DISCOVERY_DIRS=/etc/acme.sh"
```
### 4. Claim Discovered Certificates
In the **Discovery** page:
1. Review the "Unmanaged" certificates found by the agent
2. Click **Claim** on each acme.sh certificate
3. Enter the managed certificate ID to link it (e.g., `mc-api-prod`)
Once claimed, the certificate appears in the main **Certificates** page with ownership, renewal history, and deployment status.
### 5. Create an ACME Issuer
In **Issuers** → **+ New Issuer:**
1. Select **ACME** from the issuer type grid
2. Fill in the type-specific fields: name, directory URL (`https://acme-v02.api.letsencrypt.org/directory`), and config
Or configure via environment variables:
```bash
export CERTCTL_ACME_DIRECTORY_URL=https://acme-v02.api.letsencrypt.org/directory
export CERTCTL_ACME_EMAIL=your-email@example.com # same as your acme.sh account
export CERTCTL_ACME_CHALLENGE_TYPE=dns-01
```
### 6. Adapt Your DNS Provider Scripts
acme.sh uses `dns_*` hooks (e.g., `dns_cloudflare`) with predictable argument patterns. certctl's DNS-01 uses the same pattern, so your scripts often work with zero changes.
**acme.sh pattern:**
```bash
# acme.sh invokes: dns_cloudflare_add "domain" "record" "value"
dns_cloudflare_add() {
local full_domain=$1
local record_name=$2
local record_value=$3
# ... DNS API call to create TXT record ...
}
```
**certctl pattern:**
```bash
# certctl invokes: /path/to/dns-present-script
# Scripts receive environment variables:
#!/bin/bash
# CERTCTL_DNS_DOMAIN — domain name (e.g., "example.com")
# CERTCTL_DNS_FQDN — full record name (e.g., "_acme-challenge.example.com")
# CERTCTL_DNS_VALUE — TXT record value (key authorization digest)
# CERTCTL_DNS_TOKEN — ACME challenge token
# Create TXT record at "${CERTCTL_DNS_FQDN}" with value "${CERTCTL_DNS_VALUE}"
```
**Example: Cloudflare DNS-01 adapter**
If you have an acme.sh Cloudflare hook, adapt it:
```bash
#!/bin/bash
# /etc/certctl/dns/cloudflare-present.sh
set -e
# certctl passes these environment variables:
# CERTCTL_DNS_DOMAIN — domain name
# CERTCTL_DNS_FQDN — full record name (e.g., "_acme-challenge.example.com")
# CERTCTL_DNS_VALUE — TXT record value
# CERTCTL_DNS_TOKEN — ACME challenge token
# Call your existing Cloudflare API (example using curl)
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records" \
-H "X-Auth-Email: ${CF_EMAIL}" \
-H "X-Auth-Key: ${CF_KEY}" \
-H "Content-Type: application/json" \
-d "{\"type\":\"TXT\",\"name\":\"${CERTCTL_DNS_FQDN}\",\"content\":\"${CERTCTL_DNS_VALUE}\"}"
echo "Created ${CERTCTL_DNS_FQDN}"
```
DNS cleanup:
```bash
#!/bin/bash
# /etc/certctl/dns/cloudflare-cleanup.sh
# certctl passes these environment variables:
# CERTCTL_DNS_DOMAIN — domain name
# CERTCTL_DNS_FQDN — full record name (e.g., "_acme-challenge.example.com")
# CERTCTL_DNS_VALUE — TXT record value
# CERTCTL_DNS_TOKEN — ACME challenge token
# Query and delete the TXT record
curl -X DELETE "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records/${RECORD_ID}" \
-H "X-Auth-Email: ${CF_EMAIL}" \
-H "X-Auth-Key: ${CF_KEY}"
```
Configure the ACME issuer via environment variables:
```bash
export CERTCTL_ACME_DIRECTORY_URL=https://acme-v02.api.letsencrypt.org/directory
export CERTCTL_ACME_EMAIL=your-email@example.com
export CERTCTL_ACME_CHALLENGE_TYPE=dns-01
export CERTCTL_ACME_DNS_PRESENT_SCRIPT=/etc/certctl/dns/cloudflare-present.sh
export CERTCTL_ACME_DNS_CLEANUP_SCRIPT=/etc/certctl/dns/cloudflare-cleanup.sh
```
Or create the issuer through the dashboard: **Issuers** → **+ New Issuer** → select **ACME** → fill in the config fields.
### 7. Create Renewal Policies
In **Policies** → **+ New Policy:**
- **Name:** e.g., "ACME DNS-01 Policy"
- **Type:** `expiration_window` (enforces renewal thresholds)
- **Severity:** `high`
- **Config:** set your renewal window (default: 30 days before expiry)
Renewal scheduling is driven by the certificate's assigned profile and issuer. Policies add enforcement guardrails on top.
### 8. Phase Out acme.sh Cron
Once you verify renewals work via certctl (manually trigger one in the dashboard first), remove the acme.sh cron job:
```bash
# Remove acme.sh from crontab
crontab -e
# Delete the line: "0 0 * * * /home/user/.acme.sh/acme.sh --cron --home /home/user/.acme.sh"
# OR disable the cron service if installed
sudo systemctl disable acme-renew.timer
```
## DNS Script Compatibility
Most acme.sh DNS provider hooks need only minor changes:
| acme.sh | certctl |
|---------|---------|
| Called on every renewal | Called once per challenge window |
| Receives: domain, record name, record value as arguments | Receives: `CERTCTL_DNS_DOMAIN`, `CERTCTL_DNS_FQDN`, `CERTCTL_DNS_VALUE`, `CERTCTL_DNS_TOKEN` as environment variables |
| Must support multiple concurrent records | Same — cleanup removes the specific token |
| Environment variables for credentials | Same — pass via agent systemd `Environment=` or `.env` file |
**Real example:** If you use Route53, acme.sh's `dns_aws` hook submits via AWS CLI. Adapt it to use `${CERTCTL_DNS_FQDN}` and `${CERTCTL_DNS_VALUE}` environment variables instead of positional arguments, and it works with certctl's DNS-01.
## Coexistence Period
During migration, run both acme.sh and certctl in parallel:
1. Keep acme.sh cron running (low overhead, serves as fallback)
2. Configure certctl policies and test renewal on 1-2 non-critical domains
3. Monitor certctl's audit trail and deployment logs
4. Once confident, disable acme.sh cron on those domains
5. Roll out to remaining domains
This way, if certctl renewal fails, acme.sh's cron still renews the cert (you'll see duplicate renewals in the audit trail, but no gap).
## Next: DNS-PERSIST-01 (Zero-Touch Renewals)
After migrating to certctl + DNS-01, consider upgrading to **DNS-PERSIST-01**. Instead of creating/deleting DNS records on every renewal, you create one persistent TXT record at `_validation-persist.<domain>` that never changes. Let's Encrypt then validates against that standing record forever.
Benefits:
- **Zero operational overhead per renewal** — no DNS API calls during renewal
- **Auditable** — DNS record created once, visible to the team, never modified
- **Vendor-agnostic** — works with any DNS provider that supports TXT records
To enable:
```bash
export CERTCTL_ACME_CHALLENGE_TYPE=dns-persist-01
export CERTCTL_ACME_DNS_PERSIST_ISSUER_DOMAIN=letsencrypt.org
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.
## Next Steps
- 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)
docs/migration/from-certbot.md
+173
View File
@@ -0,0 +1,173 @@
# Migrating from Certbot to certctl
You have 50 Let's Encrypt certificates across 10 servers, managed by a mix of Certbot cron jobs and manual renewals. Certbot handles issuance, but you lack inventory visibility, centralized alerting, and audit trails. This guide walks you through moving to certctl while keeping your existing certificates and ACME account.
## Why Migrate
Certbot renews certs in isolation. If a renewal fails on one server, you don't know until the cert expires. certctl gives you a single pane of glass: see all certs across all servers, get alerts 30/14/7 days before expiry, track who renewed what when, and verify each deployment succeeded via TLS fingerprint validation.
## What You Keep
- Your existing Certbot ACME account key and Let's Encrypt account
- All issued certificates in `/etc/letsencrypt/live/`
- Certbot's renewal history and hooks
You will not re-issue any certificates. certctl discovers them and takes over renewal scheduling.
## Step-by-Step Migration
### 1. Deploy certctl Control Plane
Option A: Docker Compose (quickest for evaluation)
```bash
cd /opt/certctl
docker compose up -d
# Dashboard & API: https://localhost:8443 (self-signed cert — use --cacert ./deploy/test/certs/ca.crt for the default compose stack)
# Default API key in logs (grep CERTCTL_API_KEY docker logs certctl-server)
```
Option B: Kubernetes (Helm)
```bash
helm install certctl deploy/helm/certctl/ \
--set auth.apiKey=YOUR_SECURE_KEY
```
### 2. Deploy Agents to Each Server
On each of your 10 servers running Certbot:
```bash
# Linux amd64 (adjust for your architecture)
curl -sSL https://github.com/certctl-io/certctl/releases/download/v2.1.0/certctl-agent-linux-amd64 \
-o /usr/local/bin/certctl-agent
chmod +x /usr/local/bin/certctl-agent
# Create config
sudo mkdir -p /etc/certctl /var/lib/certctl/keys
sudo tee /etc/certctl/agent.env > /dev/null <<EOF
CERTCTL_SERVER_URL=https://certctl-control-plane.example.com:8443
CERTCTL_SERVER_CA_BUNDLE_PATH=/etc/certctl/tls/ca.crt
CERTCTL_API_KEY=your-api-key-here
CERTCTL_DISCOVERY_DIRS=/etc/letsencrypt/live
CERTCTL_KEY_DIR=/var/lib/certctl/keys
EOF
sudo chmod 600 /etc/certctl/agent.env
# Start agent
sudo systemctl start certctl-agent # if installed via script
# OR manually:
sudo certctl-agent --server https://... --api-key ... --discovery-dirs /etc/letsencrypt/live
```
The agent will scan `/etc/letsencrypt/live/` and report all discovered certificates to the control plane.
### 3. Triage Discovered Certificates
In the certctl dashboard, go to **Discovery**:
- See all discovered certs grouped by agent
- Status shows "Unmanaged" for certificates not yet claimed
- For each Certbot cert, click **Claim** and link it to managed inventory
The control plane now knows about all 50 certs and where they live.
### 4. Configure ACME Issuer
Go to **Issuers** → **+ New Issuer**:
1. Select **ACME** from the issuer type grid
2. Fill in the type-specific fields: name, directory URL (`https://acme-v02.api.letsencrypt.org/directory`), and any required config
Alternatively, configure via environment variables before starting the server:
```bash
export CERTCTL_ACME_DIRECTORY_URL=https://acme-v02.api.letsencrypt.org/directory
export CERTCTL_ACME_EMAIL=your-email@example.com
export CERTCTL_ACME_CHALLENGE_TYPE=http-01 # or dns-01 for wildcard certs
```
For DNS-01, also set:
```bash
export CERTCTL_ACME_DNS_PRESENT_SCRIPT=/etc/certctl/dns/present.sh
export CERTCTL_ACME_DNS_CLEANUP_SCRIPT=/etc/certctl/dns/cleanup.sh
```
certctl uses the same Let's Encrypt account; no new credentials needed.
### 5. Create Renewal Policies
Go to **Policies** → **+ New Policy** to create enforcement rules:
- Name: e.g., "ACME Renewal Policy"
- Type: `expiration_window` (to enforce renewal thresholds)
- Severity: `high`
- Config: set your renewal threshold (default: 30 days before expiry)
Renewal scheduling is driven by the certificate's assigned profile and issuer. Policies add enforcement guardrails (key algorithm requirements, expiration windows, etc.).
### 6. Disable Certbot Cron, One Server at a Time
On the first server (start with a low-traffic one):
```bash
# Stop Certbot renewal
sudo systemctl disable certbot.timer
sudo systemctl stop certbot.timer
# Or remove the cron job
sudo rm /etc/cron.d/certbot # if managed by cron
```
Monitor that server in the certctl dashboard. Certctl will renew the cert ~30 days before expiry.
### 7. Verify First Renewal Succeeds
Wait for the renewal to trigger (or manually trigger it in **Certificates** → select cert → **Renew**). Check the dashboard:
- **Certificates** page: status transitions from `Active` to `Renewing` to `Active`
- **Jobs** page: renewal job shows `Completed` status
- **Verification** tab: TLS check confirms the new cert is deployed and live
After verifying, disable Certbot on the remaining 9 servers.
### 8. Enable Alerting
Configure notifiers via environment variables before starting the server:
```bash
# Example: Slack alerting
export CERTCTL_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
docker compose up -d
# Or email alerting
export CERTCTL_SMTP_HOST=smtp.gmail.com
export CERTCTL_SMTP_PORT=587
export CERTCTL_SMTP_USERNAME=your-email@gmail.com
export CERTCTL_SMTP_PASSWORD=your-app-password
export CERTCTL_SMTP_FROM_ADDRESS=certctl@example.com
docker compose up -d
# Other options: CERTCTL_TEAMS_WEBHOOK_URL, CERTCTL_PAGERDUTY_ROUTING_KEY, CERTCTL_OPSGENIE_API_KEY
```
Now you get 30/14/7-day warnings before any cert expires, across all 10 servers, in one place.
## What Changes
- **Renewal**: Agent polls certctl for work instead of Certbot cron triggering locally. Faster failure detection (agent heartbeat every 60 seconds vs. cron running once a day).
- **Deployment**: certctl verifies post-deployment by probing the live TLS endpoint and comparing SHA-256 fingerprints. Catches reload failures silently.
- **Audit Trail**: Every renewal, deployment, and alert is logged immutably. Answer "who renewed cert X when and why" within seconds.
- **Alerting**: Threshold-based alerts to Slack/email/webhook 30/14/7 days before expiry, not when cert expires.
## Coexistence and Rollback
During migration, certctl and Certbot can run simultaneously. The agent will discover Certbot certs even while Certbot continues renewing them. Run both for a week to build confidence.
**If you need to rollback**: Re-enable Certbot cron on any server:
```bash
sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer
```
certctl will stop renewing that cert when the policy is disabled. Certbot resumes as before. Your certificates and ACME account remain untouched.
## 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
- See all [Deployment Examples](./examples.md) for other scenarios (wildcard DNS-01, private CA, step-ca, multi-issuer)