Installation

Development requirements

• Docker Engine with the Compose plugin
• GNU Make
• Python 3 for real-runtime qualification
• at least 8 GiB RAM for the complete local topology
• free ports 8080, 8081, 8082, 8444, 8445, 9443, 9191, 1053/tcp, 1053/udp, 9090, and 9093

The normal workflow builds PHP, Composer, Node, Go, PostgreSQL, Valkey, PowerDNS, OpenResty, and ClickHouse dependencies inside containers.

Install the development stack

git clone https://github.com/vaheed/CDNFoundry.git cdnfoundry
cd cdnfoundry
make dev-up
make dev-migrate

make dev-up builds frontend assets, builds the development images, starts services, and initializes persistent development PKI and GeoIP data. It does not run Laravel or PowerDNS migrations.

Create the first administrator:

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

The command prompts twice for a password and rejects a duplicate email or mismatch. Open http://localhost:8080/admin.

Verify the installation

curl --fail http://localhost:8080/api/health
curl --fail http://localhost:8080/api/ready
docker compose -f compose.dev.yml ps

Run isolated application tests:

make dev-test

The target sets the only supported destructive-test database combination: APP_ENV=testing, DB_CONNECTION=sqlite, and DB_DATABASE=:memory:.

Run non-browser real-runtime qualification only after the stack and migrations are healthy:

make dev-e2e

This job uses real HTTP APIs, PostgreSQL, queues, DNSdist, PowerDNS, OpenResty, mutual TLS, Pebble, Vector, and ClickHouse. It does not inspect the rendered UI.

Enroll the bundled edge agents

The two OpenResty hosts run before the agents because edge IDs and one-time tokens must come from administrator-created edge rows.

1. In Edge network → Edges, create edge A and edge B.
2. Copy the displayed UUID and bootstrap token for each.
3. Create the ignored local environment:

cp .env.dev.example .env.dev
chmod 600 .env.dev

1. Set CDNF_DEV_EDGE_A_ID, CDNF_DEV_EDGE_A_BOOTSTRAP_TOKEN, CDNF_DEV_EDGE_B_ID, and CDNF_DEV_EDGE_B_BOOTSTRAP_TOKEN.
2. Start and inspect the agents:

make dev-edge-up
make dev-edge-status

1. After both identities are registered and heartbeats are fresh, remove both bootstrap-token values from .env.dev.

Named agent volumes retain issued identities. Losing the volume requires the administrator Rotate identity action and a new token.

Production

Do not promote the development environment. Production uses published images, host-private .env.prod files, explicit PKI, explicit Laravel and PowerDNS migrations, firewalls, off-host backups, and the profiles described in Production deployment.