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

docs: fix stale references, seed data case bugs, and convert ASCII diagrams to Mermaid

Browse Source 
Audit all docs and examples against current codebase state. Fix seed_demo.sql
domain constant casing (IssuerType, TargetType, AgentStatus) that would cause
agent dispatch failures. Fix example docker-compose health endpoints (/health
not /api/v1/health) and env var names (CERTCTL_DATABASE_URL). Update connector
counts, test numbers, and planned→implemented status across docs. Convert 3
ASCII flow diagrams to Mermaid.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shankar0123
2026-04-03 16:11:42 -04:00
parent e8c64b47dd
commit 4c3b7cbb16
16 changed files with 102 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/acme-nginx/acme-nginx.md
+12 -10
View File
@@ -13,16 +13,18 @@ This example demonstrates certctl's core use case: **automatically manage TLS ce
## Architecture
```
Your Domain (example.com)
↓ [HTTP-01 validation, port 80]
Let's Encrypt ACME
↓ [CSR submission]
certctl Server (control plane)
↓ [API polling]
certctl Agent (on NGINX server)
↓ [deploy cert+key]
NGINX Reverse Proxy
```mermaid
flowchart TD
A["Your Domain (example.com)"]
B["Let's Encrypt ACME"]
C["certctl Server (control plane)"]
D["certctl Agent (on NGINX server)"]
E["NGINX Reverse Proxy"]
A -->|HTTP-01 validation<br/>port 80| B
B -->|CSR submission| C
C -->|API polling| D
D -->|deploy cert+key| E
```
## Prerequisites
examples/acme-nginx/docker-compose.yml
+2 -2
View File
@@ -26,7 +26,7 @@ services:
container_name: certctl-server-acme-nginx
environment:
# Database
DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
CERTCTL_DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
# Server settings
CERTCTL_SERVER_PORT: 8443
@@ -61,7 +61,7 @@ services:
networks:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/api/v1/health || exit 1']
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/acme-wildcard-dns01/docker-compose.yml
+2 -2
View File
@@ -50,7 +50,7 @@ services:
container_name: certctl-server-dns01
environment:
# Database
DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
CERTCTL_DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
# Server settings
CERTCTL_SERVER_PORT: 8443
@@ -113,7 +113,7 @@ services:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/api/v1/health || exit 1']
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/multi-issuer/docker-compose.yml
+2 -2
View File
@@ -27,7 +27,7 @@ services:
container_name: certctl-server-multi-issuer
environment:
# Database
DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
CERTCTL_DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
# Server settings
CERTCTL_SERVER_PORT: 8443
@@ -64,7 +64,7 @@ services:
networks:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/api/v1/health || exit 1']
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/multi-issuer/multi-issuer.md
+24 -22
View File
@@ -13,27 +13,29 @@ With certctl, both issuer types are configured and available. You assign each ce
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ certctl Server (Control Plane) │
│ - Let's Encrypt ACME issuer (HTTP-01 challenges) │
│ - Local CA issuer (self-signed or sub-CA mode) │
│ - PostgreSQL database (cert inventory, audit, jobs) │
└─────────────────────────────────────────────────────────────────┘
▲
│ API polling
│
┌─────────────────────────────────────────────────────────────────┐
│ certctl Agent │
│ - Discovers existing certs in /etc/nginx/ssl and /etc/app/ssl │
│ - Polls server for renewal/issuance/deployment jobs │
│ - Generates keys locally (agent-side crypto) │
│ - Deploys certs to NGINX and app service directories │
└─────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
NGINX (public TLS) App Services (internal TLS)
(Let's Encrypt certs) (Local CA certs)
```mermaid
flowchart TD
subgraph Server ["certctl Server (Control Plane)"]
A["Let's Encrypt ACME issuer<br/>(HTTP-01 challenges)"]
B["Local CA issuer<br/>(self-signed or sub-CA mode)"]
C["PostgreSQL database<br/>(cert inventory, audit, jobs)"]
end
subgraph Agent ["certctl Agent"]
D["Discovers existing certs<br/>(/etc/nginx/ssl, /etc/app/ssl)"]
E["Polls server for<br/>renewal/issuance/deployment jobs"]
F["Generates keys locally<br/>(agent-side crypto)"]
G["Deploys certs to NGINX<br/>and app service directories"]
end
subgraph Targets ["Target Services"]
H["NGINX (public TLS)<br/>(Let's Encrypt certs)"]
I["App Services (internal TLS)<br/>(Local CA certs)"]
end
Server -->|API polling| Agent
Agent -->|Deploy| H
Agent -->|Deploy| I
```
## Prerequisites
@@ -212,7 +214,7 @@ Each agent independently manages its local cert inventory and deployments. The s
- For ACME, ensure ports 80/443 are open and your domain resolves
### Agent can't reach server
- Check network: `docker compose exec certctl-agent curl http://certctl-server:8443/api/v1/health`
- Check network: `docker compose exec certctl-agent curl http://certctl-server:8443/health`
- Verify `CERTCTL_SERVER_URL` environment variable
### No issuers showing up
examples/private-ca-traefik/docker-compose.yml
+2 -2
View File
@@ -26,7 +26,7 @@ services:
container_name: certctl-server-private-ca
environment:
# Database
DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
CERTCTL_DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
# Server settings
CERTCTL_SERVER_PORT: 8443
@@ -77,7 +77,7 @@ services:
networks:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/api/v1/health || exit 1']
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/private-ca-traefik/private-ca-traefik.md
+10 -23
View File
@@ -17,29 +17,16 @@ This example demonstrates certctl managing certificates for **internal services
## Architecture
```
┌──────────────────┐
│ certctl-server │ (Local CA issuer)
│ (control │
│ plane) │
└────────┬─────────┘
│
│ REST API (job polling)
│
┌────────▼──────────┐
│ certctl-agent │ (certificate deployer)
└────────┬──────────┘
│
│ Write cert/key files
│
┌────────▼──────────────────────┐
│ Traefik │
│ (watches cert directory) │
└────────────────────────────────┘
│
│ TLS handshakes
│
[Internal Services]
```mermaid
flowchart TD
A["certctl-server<br/>(control plane)<br/>(Local CA issuer)"]
B["certctl-agent<br/>(certificate deployer)"]
C["Traefik<br/>(watches cert directory)"]
D["[Internal Services]"]
A -->|REST API<br/>job polling| B
B -->|Write cert/key files| C
C -->|TLS handshakes| D
```
## Quick Start (Self-Signed CA)
examples/step-ca-haproxy/docker-compose.yml
+2 -2
View File
@@ -81,7 +81,7 @@ services:
container_name: certctl-server-stepca-haproxy
environment:
# Database
DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
CERTCTL_DATABASE_URL: postgres://certctl:${DB_PASSWORD:-certctl-dev-password}@postgres:5432/certctl?sslmode=disable
# Server settings
CERTCTL_SERVER_PORT: 8443
@@ -119,7 +119,7 @@ services:
networks:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/api/v1/health || exit 1']
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/step-ca-haproxy/step-ca-haproxy.md
+1 -1
View File
@@ -315,7 +315,7 @@ Common issues:
Verify network:
```bash
docker compose exec certctl-agent curl http://certctl-server:8443/api/v1/health
docker compose exec certctl-agent curl http://certctl-server:8443/health
```
### HAProxy config validation fails