Appendices
This chapter collects reference tables for environment variables, Redis key schema, API endpoints, and common commands. Use it as a quick lookup during onboarding and day-to-day operations.
Environment Variables
| Variable | Description | Default / Example |
|---|---|---|
ALLOW_ORIGINS | Comma-separated list for CORS. | Empty (CORS disabled). |
ENABLE_TEST_ENDPOINTS | Expose /__test__ helpers. | false (enabled in docker-compose). |
MASTER_API_TOKEN | Master bearer token for privileged operations. | dev-master-token (docker-compose). |
SESSION_COOKIE_NAME | Session cookie identifier. | cirrus_session. |
SESSION_TTL_SECONDS | Session lifespan in seconds. | 604800 (7 days). |
COOKIE_SECURE | Set Secure attribute on session cookie. | false. |
COOKIE_DOMAIN | Domain scope for cookie. | Empty (host-only). |
COOKIE_SAMESITE | SameSite policy (lax, none, strict). | lax. |
ENABLE_PASSWORD_AUTH | Toggle password login endpoints. | true. |
REDIS_HOST / REDIS_PORT / REDIS_PASSWORD | Redis connection parameters shared across components. | redis / 6379 / empty. |
ACMEDNS_BASE_URL | Base URL for acme-dns service. | http://acmedns. |
ACME_DIRECTORY | ACME directory URL (e.g., Caddy internal CA). | https://caddy:4431/acme/local/directory. |
ACME_RENEW_CRON | Cron expression for renewal scans. | 0 * * * *. |
ACME_RENEW_BEFORE_DAYS | Renewal threshold in days. | 30. |
ACME_RENEW_MAX_PER_SCAN | Max domains queued per scan. | 10. |
ACME_LOCK_TTL | Lock TTL for issuance tasks. | 900. |
ACME_CERT_KEY_TYPE | Sewer key type (rsa2048, ecdsa256, etc.). | rsa2048. |
ENFORCE_ACME_CNAME_CHECK | Require _acme-challenge CNAME before issuing. | true (non-local CA) / false. |
WAIT_FOR_CNAME | Poll for CNAME propagation before issuing. | true. |
CNAME_WAIT_SECS | Wait duration for CNAME readiness. | 10. |
CNAME_BASE_DOMAIN | Root domain for access FQDNs. | cdn.local.test. |
CNAME_REPLICAS_PER_SITE | Number of nodes per domain. | 2. |
CNAME_DEFAULT_TTL | TTL for generated DNS records. | 60. |
DNS_MASTER_BIND_ADDR / DNS_MASTER_PORT | Hidden master listener address/port. | 0.0.0.0 / 10053. |
DNS_SOA_MNAME / DNS_SOA_RNAME / DNS_SOA_REFRESH / DNS_SOA_RETRY / DNS_SOA_EXPIRE / DNS_SOA_MINIMUM | Zone SOA parameters. | Derived defaults based on base domain. |
DNS_NS1_A / DNS_NS1_AAAA | Glue records for authoritative nameserver. | 127.0.0.1 / empty. |
CNAME_DNS_SLAVES | Comma-separated slave endpoints (host:port). | 172.28.0.12:10054. |
NODE_HEALTH_PORT / NODE_HEALTH_INTERVAL_SECS / NODE_HEALTH_TIMEOUT_SECS / NODE_HEALTH_FAILS_TO_DOWN / NODE_HEALTH_SUCCS_TO_UP | Health check configuration. | 9145 / 5 / 1 / 3 / 1. |
CDN_PURGE_CHANNEL | Redis channel for purge messages. | cdn:purge. |
FRONTEND_STATIC_DIR | Directory for static frontend assets. | /app/static. |
INTERNAL_PURGE_BASE_URL | Base URL used by Redis subscriber to issue PURGE requests. | http://127.0.0.1:8080. |
NGX_METRICS_ALLOW (build arg) | CIDR for metrics access beyond loopback. | 172.28.0.0/16 (dev). |
Redis Key Reference
| Key | Type | Description |
|---|---|---|
cdn:domains | Set | All managed domain names. |
cdn:dom:{domain} | String (JSON) | Domain configuration (DomainConf). |
cdn:nodes | Set | Registered node IDs. |
cdn:node:{id} | Hash | Node metadata (IP addresses, active flag, health counters). |
cdn:cert:{domain} | Hash | TLS certificate fullchain, key, issued timestamp. |
cdn:acme:{domain} | Hash | ACME registration state (username, password, fulldomain, status). |
cdn:acme:lock:{domain} | String | Domain-specific issuance lock (value is task token). |
cdn:acme:task:{domain} | String | Tracks queueing/running task ID. |
cdn:acmeacct:global | Hash | Global ACME account key material (PEM, KID). |
cdn:acmecertkey:{domain} | String | Stored PEM for domain certificate private key. |
cdn:acme:renew:scan_lock | String | Renewal scan lock. |
cdn:user:{username} | Hash | User metadata (password hash, email, status, last_login). |
cdn:users | Set | Usernames. |
cdn:tokens | Set | Service token IDs. |
cdn:token:{id} | Hash | Token metadata (label, created_at, hash, suffix). |
cdn:token_hash:{hash} | String | Reverse lookup from token hash to ID. |
cdn:cname:dirty | Pub/Sub channel | DNS rebuild notifications. |
cdn:purge | Pub/Sub channel | Cache purge notifications. |
Core API Endpoints (Summary)
| Method & Path | Description |
|---|---|
POST /api/v1/auth/login | Authenticate user (password-based). |
POST /api/v1/auth/logout | Terminate session. |
GET /api/v1/auth/me | Inspect current user context. |
POST /api/v1/auth/change-password | Update own password. |
GET /api/v1/domains | List managed domains. |
POST /api/v1/domains/{domain} | Create domain configuration. |
GET /api/v1/domains/{domain} | Retrieve configuration. |
PUT /api/v1/domains/{domain} | Update configuration. |
DELETE /api/v1/domains/{domain} | Remove domain. |
GET /api/v1/domains/{domain}/cname | Return assigned edge nodes and TTL. |
PUT /api/v1/domains/{domain}/upstreams | Update origin list. |
PUT /api/v1/domains/{domain}/cache-rules | Update cache settings. |
PUT /api/v1/domains/{domain}/upstream-headers | Update headers forwarded to origin. |
PUT /api/v1/domains/{domain}/cert | Upload manual certificate. |
GET /api/v1/domains/{domain}/acme | Inspect ACME state. |
POST /api/v1/domains/{domain}/acme | Queue ACME issuance. |
DELETE /api/v1/domains/{domain}/acme | Clear ACME state. |
PUT /api/v1/nodes | Update node inventory. |
POST /api/v1/purge | Enqueue cache purge event. |
GET /api/v1/users | List users. |
POST /api/v1/users | Create user. |
PUT /api/v1/users/{username} | Update user. |
DELETE /api/v1/users/{username} | Delete user. |
GET /api/v1/auth/tokens | List service tokens (master token required). |
POST /api/v1/auth/tokens | Create service token. |
DELETE /api/v1/auth/tokens/{id} | Delete service token. |
Command Cheat Sheet
| Command | Purpose |
|---|---|
just up | Build and start entire stack (Docker compose). |
just down | Stop stack and remove resources (including volumes). |
just down-no-volumes | Stop stack but preserve volumes. |
just pytest | Run backend test suite. |
just quicktest | Run expedited test subset. |
just fresh-test | Rebuild containers and run full test suite. |
just fmt | Auto-format Python sources. |
just deploy | Execute Ansible deployment (requires INVENTORY/PLAYBOOK). |
Documentation Maintenance
Keep this white paper synchronized with the codebase:
- Update chapter references when modules move or APIs change.
- Record new environment variables and Redis keys here.
- Capture significant architectural shifts (e.g., migration to Kubernetes) as new subsections or appendices.
Cirrus CDN is engineered for extensibility and operational clarity. With a shared understanding of architecture, security, automation, and operational practices, teams can evolve the platform confidently while meeting performance and compliance targets.