shankar0123 / certctl

certctl — Self-Hosted Certificate Lifecycle Platform A self-hosted certificate lifecycle platform. Track, renew, and deploy TLS certificates across your infrastructure with a web dashboard, REST API, and agent-based architecture where private keys never leave your servers. What It Does certctl gives you a single pane of glass for every TLS certificate in your organization. The **web dashboard** shows your full certificate inventory — what's healthy, what's expiring, what's already expired, and who owns each one. The **REST API** (55 endpoints) lets you automate everything. **Agents** deployed on your infrastructure generate private keys locally and submit CSRs — private keys never leave your servers. Screenshots | | | |---|---| | | | | **Dashboard** — certificate stats, expiry timeline, recent jobs | **Certificates** — full inventory with status, environment, owner filters | | | | | **Agents** — fleet health, hostname, heartbeat tracking | **Jobs** — issuance, renewal, deployment job queue | | | | | **Notifications** — threshold alerts grouped by certificate | **Policies** — enforcement rules with enable/disable and delete | | | | | **Issuers** — CA connectors with test connectivity | **Targets** — deployment targets (NGINX, F5, IIS) | | | | | **Audit Trail** — immutable log of every action | | Quick Start Docker Compose (Recommended) Wait ~30 seconds, then open **http://localhost:8443** in your browser. The dashboard comes pre-loaded with 15 demo certificates, 5 agents, policy rules, audit events, and notifications — a realistic snapshot of a certificate inventory so you can explore immediately. Verify the API: Manual Build Documentation | Guide | Description | |-------|-------------| | Concepts | TLS certificates explained from scratch — for beginners who know nothing about certs | | Quick Start | Get running in 5 minutes with accurate API examples | | Demo Walkthrough | 5-7 minute guided stakeholder presentation | | Advanced Demo | Issue a certificate end-to-end with technical deep-dives | | Architecture | System design, data flow diagrams, security model | | Connectors | Build custom issuer, target, and notifier connectors | Architecture Key Design Decisions • **Private keys isolated from the control plane.** Agents generate ECDSA P-256 keys locally and submit CSRs (public key only). The server signs the CSR and returns the certificate — private keys never touch the control plane. Server-side keygen is available via for demo/development only. • **TEXT primary keys, not UUIDs.** IDs are human-readable prefixed strings ( , , ) so you can identify resource types at a glance in logs and queries. • **Handler → Service → Repository layering.** Handlers define their own service interfaces for clean dependency inversion. No global service singletons. • **Idempotent migrations.** All schema uses and seed data uses , safe for repeated execution. Database Schema | Table | Purpose | |-------|---------| | | Certificate records with metadata, status, expiry, tags | | | Historical versions with PEM chains and CSRs | | | Renewal window, auto-renew settings, retry config, alert thresholds | | | CA configurations (Local CA, ACME, etc.) | | | Target systems (NGINX, F5, IIS) with agent assignments | | | Registered agents with heartbeat tracking | | | Issuance, renewal, deployment, and validation jobs | | | Organizational groups for certificate ownership | | | Individual owners with email for notifications | | | Enforcement rules (allowed issuers, environments, metadata) | | | Flagged non-compliance with severity levels | | | Immutable action log (append-only, no update/delete) | | | Email and webhook notification records | | | Many-to-many cert ↔ target relationships | Configuration All server environment variables use the prefix: | Variable | Default | Description | |----------|---------|-------------| | | | Server bind address | | | | Server listen port | | | | PostgreSQL connection string | | | | Connection pool size | | | | Log level: , , , | | | | Log format: or | | | | Auth mode: , , or | | | — | Required for and auth types | | | | Key generation mode: (production) or (demo only) | | | — | ACME directory URL (e.g., Let's Encrypt staging) | | | — | Contact email for ACME account registration | Agent environment variables: | Variable | Default | Description | |----------|---------|-------------| | | | Control plane URL | | | — | Agent API key | | | | Agent display name | | | — | Registered agent ID (required) | | | | Directory for storing private keys (agent keygen mode) | Docker Compose overrides these for the demo stack (see ): port , auth type , database pointing to the postgres container. API Overview All endpoints are under and return JSON. List endpoints support pagination ( ). Certificates Agents Infrastructure Organization Operations Auth Health Supported Integrations Certificate Issuers | Issuer | Status | Type | |--------|--------|------| | Local CA (self-signed) | Implemented | | | ACME v2 (Let's Encrypt, Sectigo) | Implemented (HTTP-01) | | | step-ca | Planned (V2) | — | | OpenSSL / Custom CA | Planned (V2) | — | | ADCS (Active Directory CS) | Planned (V2) | — | | Vault PKI | Planned | — | | DigiCert | Planned | — | Deployment Targets | Target | Status | Type | |--------|--------|------| | NGINX | Implemented | | | F5 BIG-IP | Interface only (V2) | | | Microsoft IIS | Interface only (V2) | | | Kubernetes Secrets | Planned | — | Notifiers | Notifier | Status | Type | |----------|--------|------| | Email (SMTP) | Implemented | | | Webhooks | Implemented | | | Slack | Planned | — | Development Docker Compose Security Private Key Management • **Agent keygen mode (default)**: Agents generate ECDSA P-256 keys locally and store them with 0600 permissions in (default ). Only the CSR (public key) is sent to the control plane. Private keys never leave agent infrastructure. • **Server keygen mode (demo only)**: Set for development/demo with Local CA. The cont…