CDNFoundry

CDNFoundry is an open-source, production-oriented private CDN platform for companies, hosting providers, and large ISPs that want to operate their own authoritative DNS, edge proxy, cache, TLS, security, and analytics infrastructure.

It combines a Laravel and Filament control plane with PowerDNS, DNSdist, OpenResty, a Go edge agent, Vector, ClickHouse, Prometheus, and bounded role-based Docker Compose deployments.

Important

PostgreSQL owns desired state, but customer DNS and HTTP traffic never pass through Laravel. Existing data planes continue from their last valid state during a control-plane or telemetry outage.

Why CDNFoundry

• Private ownership: run DNS, edge, certificates, cache, telemetry, and operational data on infrastructure you control.
• Authoritative DNS: DNSdist-only public ingress, private PowerDNS, deterministic zones, Geo-DNS, import/export, reconciliation, and drift visibility.
• Data-driven edge: shared, quarantine, and exceptional dedicated pools use bounded OpenResty cells instead of a process or server block per domain.
• Safe origins: every proxied hostname has one explicit origin; unsafe loopback, link-local, metadata, internal-service, and proxy-loop destinations fail closed.
• TLS lifecycle: managed DNS-01 issuance, encrypted custom certificates, bounded renewal, validation, and last-valid certificate preservation.
• Deterministic cache: one lookup/purge key, bounded objects, development mode, stale policy, URL purge tasks, and epoch-based full purge.
• Application security: ordered IP/CIDR/geography rules, bounded profiles, target readiness, quarantine, and expiring emergency controls.
• Direct telemetry: Vector sends redacted DNS and edge events directly to ClickHouse; analytics failure cannot block serving.
• Operational recovery: explicit migrations, immutable images, health and readiness, four queue lanes, Restic backup, restore preflight, runbooks, and canary upgrade guidance.
• Predictable mutation: external effects are asynchronous, revisioned, idempotent, coalesced, verified, and last-valid-state preserving.

Architecture

flowchart TB
    Operator["Administrators and domain users"] -->|"HTTPS"| Control["Laravel + Filament<br/>API, Horizon, Scheduler"]
    Control --> State[("PostgreSQL<br/>desired state")]
    Control --> Queue[("Valkey<br/>queues and sessions")]

    Resolver["Recursive resolvers"] -->|"UDP/TCP 53"| DNSdist["DNSdist"]
    DNSdist --> PowerDNS["Private PowerDNS"]
    PowerDNS --> PDNSDB[("Derived DNS data")]

    Visitors["Internet users"] -->|"HTTP/HTTPS"| Edge["Bounded OpenResty cells"]
    Edge --> Origins["Validated customer origins"]

    Control -->|"asynchronous DNS reconciliation"| PowerDNS
    Control -->|"signed revisioned artifacts"| Agent["Go edge agent"]
    Agent -->|"atomic activation"| Edge

    DNSdist -. "dnstap" .-> Vector["Vector"]
    Edge -. "redacted JSON events" .-> Vector
    Vector --> ClickHouse[("ClickHouse analytics")]
    Metrics["Prometheus"] --> Alerts["Alertmanager"]

Loading

Plane	Source of truth	Runtime behavior
Management	Laravel policies and PostgreSQL	Authorizes and records intent
DNS	PostgreSQL desired records	DNSdist and PowerDNS answer independently
Edge	Domain revisions and placements	Agents validate and atomically activate snapshots
TLS/cache/security	Typed domain state	OpenResty applies data without per-domain reload
Telemetry	Runtime events	Vector buffers and ClickHouse stores bounded analytics

Read the architecture overview and data-flow diagrams for component and failure boundaries.

Production deployment

The minimum recommended topology is one control/telemetry host and two combined DNS/edge hosts in separate failure domains.

Caution

Production uses immutable images, explicit Laravel and PowerDNS migrations, private PKI, exact-source firewalls, persistent named volumes, and off-host backups. Do not promote the development stack.

Follow the detailed Production quick start. It covers bootstrap DNS, registrar glue, .env.prod, private certificates, control startup, DNS qualification, edge enrollment, the first customer domain, acceptance checks, IPv6, scaling, and rollback.

Local development

Requirements are Docker Engine, Docker Compose, GNU Make, and enough capacity for the complete development topology.

make dev-up
make dev-migrate
make dev-test

Create the first administrator interactively:

docker compose -f compose.dev.yml exec core \
  php artisan cdnf:admin:create \
  --name="Local Administrator" \
  --email="admin@example.test"

Open:

• administrator panel: http://localhost:8080/admin
• domain-user panel: http://localhost:8080/app
• Horizon: http://localhost:8080/admin/horizon
• development mail: http://localhost:8025
• PowerAdmin diagnostics: http://localhost:9191

See Installation and Development before changing the stack.

Implemented feature map

Area	Capabilities
Identity	Administrators, assigned domain users, sessions, Sanctum tokens, audit, account disablement
Domains	Normalization, delegation verification, activation, delayed deprovision, tombstones, reclaim cooldown
DNS	A, AAAA, CNAME, MX, TXT, NS, CAA, SRV, reverse PTR, BIND import/export, Geo-DNS
Edge	Pools, cells, enrollment, mTLS identity, signed artifacts, recovery snapshots, placement and drain
Proxy	Explicit safe origins, host/SNI policy, bounded timeouts/retries, WebSocket policy, health tests
TLS	Managed ACME DNS-01, custom uploads, renewal, reissue, validation, encrypted private keys
Cache	TTL policy, admission, query policy, stale grace, development mode, URL/full purge
Security	Ordered rules, trusted-client parsing, profiles, quarantine, emergency controls
Analytics	Raw logs, aggregates, status/cache/origin/geography views, stable usage exports
Operations	Health, readiness, metrics, alerts, reconciliation, failed jobs, backups, restore, upgrades

API

The JSON API uses Sanctum bearer tokens, policy-aware nested binding, stable machine-readable errors, cursor pagination, UUID idempotency keys, and operation receipts for asynchronous work.

• API conventions
• Generated endpoint catalog
• OpenAPI 3.1 contract
• Edge-agent protocol

Documentation

Browse the production CDNFoundry documentation website for full navigation, local search, rendered architecture diagrams, and light/dark modes. The Markdown links below also work directly on GitHub.

Audience	Start here
Evaluators	Product overview
Production operators	Production quick start
Administrators	Operations
Domain users	Feature guides
API clients	API reference
Developers	Development environment
Security teams	Security model
Incident responders	Troubleshooting

Build and validate the documentation:

npm ci --prefix docs
make docs-check

Safety and contribution

Read AGENTS.md before modifying behavior. In particular:

• never remove persistent development or production volumes;
• never run destructive Laravel migration tests against PostgreSQL;
• use the isolated SQLite test target;
• keep DNS and HTTP request paths independent from Laravel;
• do not introduce a default per-domain process, container, timer, cache directory, or Nginx server block;
• preserve previous valid runtime state when a candidate fails;

See Contributing, Security, Code of conduct, and MIT license.