FlareLens v2.0 Reference

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:

Deploy Control Plane via Wrangler CLI sh
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):

Linux / macOS one-line enrollment sh
curl -fsSL https://flarelens.dev/install.sh | sudo bash -s -- \
  --control "https://your-plane.workers.dev" \
  --token ""
Zero-SSH OTA Upgrades: Once enrolled, 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 and state/revisions/rev-N.json in R2.
  • 1-Click Promotion & Rollback: Promote validated staging/UAT images to prod or roll back the entire fleet—including deleted workloads—to any historical revision.
  • Suspended Staging Gate (enabled: false): Stage production manifests in a Suspended state while pre-populating Vault secrets, then launch in 1 click.
  • Optional Keyless GitHub OIDC Sync: Teams using GitOps can push fleet/<env>/*.yml manifests via POST /api/v1/control/fleet/sync authenticated 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) or singleton (stateful engines such as PostgreSQL, Dragonfly, Redis, or Cloudflared).
  • placement_strategy: spread (HA anti-affinity across nodes), binpack (RAM consolidation), or pinned (host affinity), combined with replicas (1..32) and required_tags.
  • memory_mb & cpu_cores: Enforces hard Linux kernel cgroup ceilings (HostConfig.Memory and NanoCPUs) on Blue/Green slots, companion workers, and singletons. Updating resource budgets on a running stateful singleton applies live via Docker's ContainerUpdate API 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 as fenced so 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):

  1. WireGuard Service Router: Deterministic <overlay_ip>:<mesh_port> TCP forwarders proxy cross-node requests directly to active local Blue/Green slots.
  2. Split-Horizon MagicDNSServer (<overlay_ip>:53 over UDP + TCP): Containers are configured with HostConfig.Dns: [<overlay_ip>, "1.1.1.1"] and DnsSearch: ["<env>.mesh", "mesh"]. Queries for <service>.<env>.mesh return lock-free round-robin A records with TTL = 5s, strict environment isolation, RFC 4074 NODATA on AAAA, and automatic ExtraHosts fallback 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 .env files 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 RAM tmpfs under /dev/shm/flarelens-secrets (0700 root directory, 0600 on 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: true or run_migrations: true streams a gzip-compressed pg_dump via an in-memory io.Pipe directly 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 $0 egress fees.

8. Control Plane REST API Summary

Core FlareLens Control Plane HTTP endpoints
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