# FlareLens — Complete Platform & Schema Reference (llms-full.txt) Canonical URLs: - Website: https://flarelens.dev/ - Docs: https://flarelens.dev/docs/ - Compare: https://flarelens.dev/compare/ - JSON Schema: https://flarelens.dev/schemas/fleet.schema.json - Installer: https://flarelens.dev/install.sh --- # FlareLens **Open-Source Infrastructure Operations · Serverless Infrastructure Control Plane** ### Your infrastructure. Under your control. Manage servers, deploy applications, connect private networks, secure secrets, and observe your infrastructure from one open-source control plane, deployed in your own Cloudflare account. [Website](https://flarelens.dev/) · [Documentation](https://flarelens.dev/docs/) · [Deploy to Cloudflare](https://deploy.workers.cloudflare.com/?url=https://github.com/antwig2/flarelens) · [Host Agent (`flarelensd`)](https://github.com/antwig2/flarelensd) · [Releases](https://github.com/antwig2/flarelens/releases) [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/antwig2/flarelens) [![Latest release](https://img.shields.io/github/v/release/antwig2/flarelens?label=release&color=f38020)](https://github.com/antwig2/flarelens/releases/latest) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-555)](LICENSE) FlareLens brings infrastructure management, declarative deployments, private networking, secrets, and observability together without requiring dedicated control-plane servers or a Kubernetes cluster. Built with a serverless Cloudflare Workers + D1 + KV + R2 control plane and a lightweight Go host daemon ([`flarelensd`](https://github.com/antwig2/flarelensd)), your applications continue running on your own machines while one control plane coordinates everything. --- ## Key Capabilities - **Zero-Git Declarative Fleet Engine & Immutable Revisions** — Create, edit, enable/suspend, and reconcile Blue/Green web services or stateful singletons (`postgres`, `dragonfly`, `traefik`, `cloudflared`) directly from the Dashboard UI. Every change is saved as an immutable numbered revision (`rev-1`, `rev-2`, …) in Cloudflare D1 + R2 (`state/revisions/rev-N.json`) with **1-click UAT → Prod promotion**, **1-click rollback** (even for deleted services), portable JSON export/import, and optional CI/Git sync (`POST /api/v1/control/fleet/sync`). - **Multi-Server Placement, Hard Cgroup Isolation, Dynamic Mesh DNS (`TTL 5s`) & Auto-Failover** — Schedule multi-replica stateless apps across a server pool (`placement_strategy`: `spread` HA anti-affinity, `binpack` RAM consolidation, or `pinned` host affinity) with hard kernel cgroup RAM/CPU limits (`memory_mb`, `cpu_cores` — including zero-restart live singleton updates and automatic 72h Docker image pruning) and `required_tags`. `flarelensd` binds deterministic WireGuard overlay ports (`100.64.0.x:`), runs an embedded UDP+TCP split-horizon `MagicDNSServer` on `:53` (`HostConfig.Dns` + `DnsSearch: [".mesh", "mesh"]`, round-robin `A` records, `TTL = 5s` with automatic `ExtraHosts` fallback), configures multi-node Traefik HTTP load-balancing with health checks, cordons/drains hosts cleanly (`POST /api/v1/control/nodes/:id/drain`), **fences stateful DB volumes** so persistent data is never auto-wiped, and automatically reschedules stateless replicas off dead nodes with zero container restarts. - **`$0` Cloudflare D1 + Piggybacked 15s Control Plane** — Stores node state, placement leases, command queues, mesh peers, feature flags, and fleet revisions in Cloudflare D1 free tier (`5M` reads/day, `100K` writes/day). Pending commands, WireGuard mesh peers, cluster service endpoints, and flag version hashes piggyback directly onto the 15-second `/api/v1/ingest` heartbeat (`0` R2 `list()` Class A polling calls). - **Zero-SSH Over-The-Air (`self_update`) & Host Maintenance** — SHA-256 verified binary upgrades, allowlisted systemd unit retirement (`retire_systemd_units`), and drain-locked graceful OS reboots (`reboot_node`) with pre-reboot command `ACK` verification so reboot loops cannot occur. - **Zero-Plaintext Secrets Vault & RAM Secret Files** — AES-256-GCM encrypted secrets in Cloudflare KV injected strictly in memory (`-e KEY=VAL`) or materialized into ephemeral `/dev/shm` `tmpfs` directories (`__FLARELENS_FILE__`) for TLS/JWT/SAML certificates. - **Direct Peer-to-Peer WireGuard Mesh** — Coordinates Curve25519 peer discovery at the edge while keeping all private server-to-server and operator traffic 100% P2P over UDP (`100.64.0.0/10` / `10.42.0.0/16`) — private data never traverses Cloudflare. - **Parquet Log Lakehouse & Zero-Disk R2 Database Backups** — Compacts telemetry into Hive-partitioned Apache Parquet in Cloudflare R2 (queryable in-browser via DuckDB-WASM with `$0` egress) and streams `pg_dump` snapshots directly to R2 via `io.Pipe`. --- ## Do I Need a Git Repository or `cloudflared`? - **No Git repository required** — You can manage your entire fleet natively in the FlareLens Dashboard (`+ New Service`, 1-click presets, `Promote UAT → Prod`, and `Rollback to rev-N`) backed by Cloudflare D1 + R2 state snapshots. If your team also uses CI/CD, push webhooks (`/api/v1/control/deploy/webhook`) and optional `fleet//*.yml` syncs (`/api/v1/control/fleet/sync`) plug right into the same revision timeline. - **No `cloudflared` required** — FlareLens supports both **Direct Edge Ingress** (`A`/`AAAA` DNS records pointed directly at your VM with Traefik/Caddy Let's Encrypt TLS) and **Optional Zero-Inbound-Port Tunnels** (`cloudflared` singleton with ports `22`/`80`/`443` closed on your cloud firewall). --- ## Quick Start ### 1. Deploy the Control Plane (`$0` Cloudflare Free Tier) **Option A — 1-Click Deploy Button (Auto-Provisions D1, KV & R2):** Click [**Deploy to Cloudflare Workers**](https://deploy.workers.cloudflare.com/?url=https://github.com/antwig2/flarelens) — Wrangler v4 automatically provisions `CONTROL_DB` (`flarelens-control`), `FLEET_KV`, `LOGS_BUCKET`, and `BACKUP_BUCKET`, and applies the D1 schema migrations. Then set `INGEST_SECRET`, `DASHBOARD_PASSWORD`, and `VAULT_MASTER_KEY` in your Worker settings. **Option B — Wrangler CLI:** ```sh git clone https://github.com/antwig2/flarelens.git cd flarelens npm install # Configure control-plane secrets npx wrangler secret put INGEST_SECRET npx wrangler secret put DASHBOARD_PASSWORD npx wrangler secret put VAULT_MASTER_KEY # Deploy Worker (Wrangler v4 auto-provisions D1, KV, and R2 bindings from wrangler.toml) npm run deploy npx wrangler d1 migrations apply flarelens-control --remote ``` ### 2. Enroll a Server Node (`flarelensd`) ```sh curl -fsSL "https://flarelens.dev/install.sh" | sudo bash -s -- \ --control "https://" \ --token "" ``` ### 3. Add Services in the Dashboard (or Optional CI Push) Open **Declarative Fleet** in your FlareLens Dashboard and click **`+ New Service`** to pick a 1-click template (**Blue/Green App**, **PostgreSQL 18**, **Dragonfly**, **Traefik v3**, or **Cloudflared**), save `rev-1`, promote `uat → prod`, or roll back to any historical revision in 1 click. Want IDE validation or optional CI sync? Every FlareLens Worker serves its canonical JSON Schema at `GET /schemas/fleet.schema.json`: ```json { "$schema": "https://flarelens.dev/schemas/fleet.schema.json", "service": "billing-api", "env": "prod", "domains": ["api.example.com", "auth.example.com"], "image": "ghcr.io/acme/billing-api:1.4.0", "replicas": 2, "memory_mb": 512, "placement_strategy": "spread", "container_port": 8080, "host_port_blue": 9080, "host_port_green": 9081, "health_path": "/health", "networks": ["app-prod", "flarelens-edge"], "aliases": ["billing-api"] } ``` ### 4. Connect an Operator Workstation (Optional WireGuard Mesh) ```sh sudo flarelens-agent login --control=https:// ``` --- ## Architecture - **Control Plane (`antwig2/flarelens`)** — Cloudflare Worker + D1 + KV + R2 handling authentication, zero-Git fleet revisions & rollbacks, encrypted Vault secrets, OTA binary distribution, and DuckDB-WASM Parquet observability. - **Host Agent (`antwig2/flarelensd`)** — Single static Go daemon running on Linux/macOS/Windows hosts; executes zero-downtime Blue/Green & singleton Docker reconciliation, Traefik dynamic route flips, streaming R2 backups, and P2P WireGuard networking. - **Sovereign Resilience** — Workloads continue serving live traffic independently even if control-plane connectivity is interrupted. ## Components | Component | Description | Repository | |-----------|-------------|------------| | **Control Plane** | Dashboard, Zero-Git Fleet Engine, D1 revisions, Vault, and Parquet Lakehouse | [antwig2/flarelens](https://github.com/antwig2/flarelens) | | **Host Agent** | Static Go daemon for Blue/Green & singleton orchestration, mesh, and backups | [antwig2/flarelensd](https://github.com/antwig2/flarelensd) | ## Contributing & Security Contributions are welcome. See [CONTRIBUTING.md](https://github.com/antwig2/flarelens/blob/main/CONTRIBUTING.md) and [SECURITY.md](https://github.com/antwig2/flarelens/blob/main/SECURITY.md). ## License FlareLens is licensed under [Apache License 2.0](https://github.com/antwig2/flarelens/blob/main/LICENSE). --- ## Control Plane HTTP Endpoints - `POST /api/v1/ingest` — 15s host heartbeat; returns piggybacked `commands`, `mesh_peers`, `cluster_endpoints`, and `flags_version`. - `POST /api/v1/control/fleet/sync` — Sync declarative manifests via Bearer token or keyless GitHub Actions OIDC (`id-token: write`). - `POST /api/v1/control/fleet/promote` — Promote manifests across environments (`uat -> prod`) with immutable D1+R2 revision (`rev-N`). - `POST /api/v1/control/fleet/rollback` — Roll back fleet state to any historical `rev-N` snapshot. - `POST /api/v1/control/nodes/:id/drain` & `/uncordon` — Drain stateless replicas off a node while fencing stateful DB volumes. - `POST /api/v1/control/nodes/:id/prune-images` — Trigger two-pass Docker image garbage collection (dangling >24h, unused >72h). - `POST /api/v1/control/agent/releases` — Publish SHA-256 verified `flarelensd` OTA binary release. --- ## Canonical Fleet Manifest JSON Schema (`https://flarelens.dev/schemas/fleet.schema.json`) ```json { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://flarelens.dev/schemas/fleet.schema.json", "title": "FlareLens Fleet Resource Manifest", "description": "Declarative schema for FlareLens fleet service workloads, supporting Blue/Green rolling deployments, host infrastructure adoption, and stateful foundation services.", "type": "object", "required": [ "service", "env", "image" ], "properties": { "$schema": { "type": "string" }, "service": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "env": { "type": "string", "enum": [ "infra", "uat", "prod", "staging", "dev" ] }, "mode": { "type": "string", "enum": [ "blue_green", "singleton" ] }, "image": { "type": "string" }, "enabled": { "type": "boolean", "default": true }, "adopt_only": { "type": "boolean", "default": false }, "node_id": { "type": "string" }, "replicas": { "type": "integer", "minimum": 1, "maximum": 32, "default": 1 }, "memory_mb": { "type": "integer", "minimum": 32, "maximum": 262144, "default": 256 }, "cpu_cores": { "type": "number", "minimum": 0.05, "maximum": 256 }, "placement_strategy": { "type": "string", "enum": [ "spread", "binpack", "pinned" ], "default": "spread" }, "required_tags": { "type": "array", "items": { "type": "string" } }, "container_name": { "type": "string" }, "restart": { "type": "string", "enum": [ "always", "unless-stopped", "on-failure", "no" ], "default": "unless-stopped" }, "runtime": { "type": "string", "enum": [ "runc", "runsc" ], "default": "runc" }, "domain": { "type": "string", "format": "hostname" }, "domains": { "type": "array", "items": { "type": "string", "format": "hostname" } }, "container_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "host_port_blue": { "type": "integer", "minimum": 1, "maximum": 65535 }, "host_port_green": { "type": "integer", "minimum": 1, "maximum": 65535 }, "health_path": { "type": "string", "default": "/health" }, "timeout_seconds": { "type": "integer", "minimum": 1, "default": 90 }, "drain_seconds": { "type": "integer", "minimum": 0, "default": 15 }, "pre_deploy_snapshot": { "type": "boolean", "default": false }, "run_migrations": { "type": "boolean", "default": false }, "migration_cmd": { "type": "string" }, "canary_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0 }, "canary_duration": { "type": "integer", "minimum": 0, "default": 0 }, "networks": { "type": "array", "items": { "type": "string" } }, "aliases": { "type": "array", "items": { "type": "string" } }, "volumes": { "type": "array", "items": { "type": "string" } }, "ports": { "type": "array", "items": { "type": "string" } }, "command": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "entrypoint": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "healthcheck": { "type": "object", "required": [ "test" ], "properties": { "test": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "interval": { "type": "string" }, "timeout": { "type": "string" }, "retries": { "type": "integer", "minimum": 1 }, "start_period": { "type": "string" } } }, "workers": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "command": { "type": "array", "items": { "type": "string" } }, "entrypoint": { "type": "array", "items": { "type": "string" } }, "volumes": { "type": "array", "items": { "type": "string" } }, "networks": { "type": "array", "items": { "type": "string" } }, "memory_mb": { "type": "integer", "minimum": 32, "maximum": 262144 }, "cpu_cores": { "type": "number", "minimum": 0.05, "maximum": 256 } } } }, "env_vars": { "type": "object", "additionalProperties": { "type": "string" } }, "secrets": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } ```