FlareLens Documentation
Deploy a self-hosted serverless control plane on Cloudflare's free tier, enroll Linux or Windows hosts with flarelensd, and orchestrate resilient multi-node workloads.
1. Deploy the Control Plane ($0 Free Tier)
You can launch your own isolated FlareLens Control Plane in one click using the Deploy to Cloudflare Workers button—Wrangler v4 automatically provisions CONTROL_DB (D1), FLEET_KV (KV), LOGS_BUCKET (R2), and BACKUP_BUCKET (R2)—or deploy from the CLI:
git clone https://github.com/antwig2/flarelens.git
cd flarelens
npm install
npx wrangler secret put INGEST_SECRET
npx wrangler secret put DASHBOARD_PASSWORD
npx wrangler secret put VAULT_MASTER_KEY
npm run deploy
npx wrangler d1 migrations apply flarelens-control --remote
2. Enroll Host Nodes (flarelensd)
Install the static Go host agent (antwig2/flarelensd) using the vanity installer hosted at https://flarelens.dev/install.sh (Linux/macOS) or https://flarelens.dev/install.ps1 (Windows):
curl -fsSL https://flarelens.dev/install.sh | sudo bash -s -- \
--control "https://your-plane.workers.dev" \
--token ""
flarelensd verifies SHA-256 digests and upgrades itself atomically via self_update commands piggybacked onto its 15-second heartbeat—draining active deployments or backups before swapping binaries.
3. Zero-Git Declarative Fleet & Revisions
Open the Declarative Fleet tab in your dashboard to manage services directly in Cloudflare D1 + R2 without needing a Git repository:
- Immutable Revisions: Every create, edit, promotion, or delete writes an immutable numbered snapshot (
rev-1,rev-2, …) to D1 andstate/revisions/rev-N.jsonin R2. - 1-Click Promotion & Rollback: Promote validated staging/UAT images to
prodor roll back the entire fleet—including deleted workloads—to any historical revision. - Suspended Staging Gate (
enabled: false): Stage production manifests in aSuspendedstate while pre-populating Vault secrets, then launch in 1 click. - Optional Keyless GitHub OIDC Sync: Teams using GitOps can push
fleet/<env>/*.ymlmanifests viaPOST /api/v1/control/fleet/syncauthenticated with short-lived GitHub Actions OIDC tokens.
4. Manifest Schema, Placement & Hard Cgroup Limits
Point YAML Language Server or JSON editors to https://flarelens.dev/schemas/fleet.schema.json for strict validation:
mode:blue_green(zero-downtime slot swap + Traefik health-checked flip) orsingleton(stateful engines such as PostgreSQL, Dragonfly, Redis, or Cloudflared).placement_strategy:spread(HA anti-affinity across nodes),binpack(RAM consolidation), orpinned(host affinity), combined withreplicas(1..32) andrequired_tags.memory_mb&cpu_cores: Enforces hard Linux kernel cgroup ceilings (HostConfig.MemoryandNanoCPUs) on Blue/Green slots, companionworkers, and singletons. Updating resource budgets on a running stateful singleton applies live via Docker'sContainerUpdateAPI with zero container restarts.- Stateful Volume Fencing: Draining a node (
POST /api/v1/control/nodes/:id/drain) or detecting a dead host reschedules stateless replicas onto healthy peers while marking local-disk singletons asfencedso persistent database volumes are never wiped automatically.
5. Direct P2P WireGuard Mesh & MagicDNS (TTL 5s)
Every enrolled host joins a peer-to-peer WireGuard overlay (100.64.0.0/10) and binds two local mesh subsystems solely on its private WireGuard IP (zero public port exposure):
- WireGuard Service Router: Deterministic
<overlay_ip>:<mesh_port>TCP forwarders proxy cross-node requests directly to active local Blue/Green slots. - Split-Horizon MagicDNSServer (
<overlay_ip>:53over UDP + TCP): Containers are configured withHostConfig.Dns: [<overlay_ip>, "1.1.1.1"]andDnsSearch: ["<env>.mesh", "mesh"]. Queries for<service>.<env>.meshreturn lock-free round-robinArecords withTTL = 5s, strict environment isolation, RFC 4074NODATAonAAAA, and automaticExtraHostsfallback on unprivileged hosts.
6. Zero-Plaintext Vault & RAM tmpfs Secret Files
Secrets uploaded via the Dashboard or CLI are encrypted at the edge using Web Crypto AES-256-GCM. At deployment time:
- Standard keys inject straight into container process memory (
EnvVars)—never writing.envfiles to disk. - Keys prefixed with
__FLARELENS_FILE__/container/path(such as TLS/JWT/SAML PEM keys, PostgreSQL/docker-entrypoint-initdb.d/01-init.sql, or CDC YAML configs) are materialized into ephemeral RAMtmpfsunder/dev/shm/flarelens-secrets(0700root directory,0600on private keys) and bind-mounted read-only into Blue/Green containers, workers, migration runners, and singletons.
7. Streaming R2 Backups & Parquet Log Lakehouse
- Zero-Disk Database Guardrails: Setting
pre_deploy_snapshot: trueorrun_migrations: truestreams a gzip-compressedpg_dumpvia an in-memoryio.Pipedirectly to Cloudflare R2 before running schema migrations, restoring automatically if migrations fail. - DuckDB-WASM Log Analytics: Container logs compact into Snappy-compressed Apache Parquet partitions in R2 and execute SQL queries directly in the browser via HTTP Range requests with
$0egress fees.
8. Control Plane REST API Summary
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| POST | /api/v1/ingest |
Bearer Ingest Token | 15s host telemetry ingest + piggybacked commands, mesh peers, and endpoints |
| POST | /api/v1/control/fleet/sync |
Bearer / GitHub OIDC | Validate & reconcile declarative fleet manifests, creating a new rev-N |
| POST | /api/v1/control/fleet/promote |
Admin Session / Token | Promote verified service image tags from uat to prod |
| POST | /api/v1/control/fleet/rollback |
Admin Session / Token | Atomically restore fleet manifests (including deleted services) to rev-N |
| POST | /api/v1/control/nodes/:id/drain |
Admin Session / Token | Cordon host, reschedule stateless replicas, and fence stateful DB volumes |
| POST | /api/v1/control/nodes/:id/prune-images |
Admin Session / Token | Trigger two-pass Docker image garbage collection (preserving 72h rollback cache) |
| GET | /schemas/fleet.schema.json |
Public | Canonical JSON Schema Draft-07 for IDE autocomplete & CI validation |