- TypeScript 89.4%
- Python 4.7%
- Shell 2.6%
- PLpgSQL 1.4%
- Go 0.7%
- Other 1.1%
|
Some checks failed
build-images / build-push (push) Failing after 1h30m6s
Keeps the pinned mesh-sidecar from being squatted by a floating member after a cold boot. Uses --ip-range (floaters get .128/25) rather than aux-address, which rejects the explicit sidecar pin. Completes the cold-boot self-recovery set alongside two-phase IP-refresh and the agent /32 reconcile (already on main). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .claude | ||
| .gitea/workflows | ||
| .github/workflows | ||
| containers | ||
| docs | ||
| integrations/lego-dns-octet | ||
| migrations | ||
| packages | ||
| scripts | ||
| tests/e2e | ||
| .dockerignore | ||
| .gitignore | ||
| biome.json | ||
| build-version.txt | ||
| bun.lock | ||
| bunfig.toml | ||
| CLAUDE.md | ||
| compose.env.example | ||
| docker-compose.dhcp-macvlan.example.yml | ||
| docker-compose.dhcp-macvlan.yml | ||
| docker-compose.ha.yml | ||
| docker-compose.prebuilt.yml | ||
| docker-compose.yml | ||
| host-metrics-preview.mjs | ||
| package.json | ||
| playwright.config.ts | ||
| progress.md | ||
| README.md | ||
| tsconfig.base.json | ||
| tsconfig.json | ||
ProjectOctet
Enterprise-style DDI (DNS, DHCP, IPAM) control plane and grid operations for distributed sites: multi-tenant views and zones, DHCP scopes and leases, IPAM networks, WireGuard mesh between members, and multi-site event-sourced sync.
The management UI (packages/ui) and API (packages/api) are separate processes; members run a lightweight agent (packages/agent) that applies pushed configs (PowerDNS, Kea, dnsdist, WireGuard).
Product name in the UI: project.octet
Interface
Screenshots below are captured from a running stack (default: UI at http://127.0.0.1 with /api proxied). To regenerate them locally:
bun install
bunx playwright install chromium # first time only; Linux may need NSS/ATK libs — see Playwright docs
bun run readme:capture-screenshots
Linux (minimal images / servers): Headless Chromium needs real font files or label and button text can render as empty boxes. Install e.g. fonts-liberation (or fonts-dejavu-core) and fontconfig before capture (apt install fonts-liberation fontconfig on Debian/Ubuntu).
Optional environment variables: OCTET_README_UI_BASE, OCTET_README_USER, OCTET_README_PASSWORD.
Privacy: Most captures apply a blur to every <table> in the frame so row data is not legible in the repo. The DHCP active leases shot blurs only columns 1–3 (IP, MAC, hostname) and column 8 (scope); other columns stay sharp. Chrome outside those cells stays sharp.
Git hook (optional): After a one-time bun run git-hooks:install, git push runs readme:capture-screenshots when OCTET_README_UI_BASE/login responds (default http://127.0.0.1). If PNGs change, they are staged and the push is blocked until you commit them (avoids pushing stale README images). If the UI is down, the hook skips capture. To push without running the hook: SKIP_README_SCREENSHOTS=1 git push.
Sign-in
Dashboard
Dashboard — Client & resolver (24h)
Resolver activity, blocklist, and recursor sections use the 24h range (see privacy note above for table blur).
DNS — zones
DNS — views
IPAM — networks
DHCP — scopes
DHCP — active leases
Active only tab; README capture blurs IP, MAC, hostname, and scope columns only (see privacy note above).
Lattice — members
Features (high level)
- DNS — Views, zones, records (including shared hosts, imports, published NS), resolver activity and security/blocklist tooling aligned with PowerDNS and dnsdist on members.
- DHCP — Scopes, reservations, classes, leases; Kea config generation and optional control-agent
config-set/config-writefor runtime subnet updates without routine daemon restarts. - IPAM — Networks, subnets, addresses, maps, and history-style enrichment.
- Lattice — Members, topology, sync conflicts, VPN/mesh peer catalog; config push to roles (DNS, DHCP, dist, WireGuard).
- Multi-site — Ed25519-signed sync, merge rules, conflict resolution, and origin metadata on materialized entities.
Tech stack
Bun, Hono, React, Vite, Tailwind / shadcn-style UI, PostgreSQL, Kysely, PowerDNS, Kea, dnsdist, WireGuard, Docker.
Documentation and status
| Resource | Purpose |
|---|---|
| CLAUDE.md | How to run the project, Docker/slim images, list-page UI rules, DB bootstrap policy |
| progress.md | Implementation status and completed milestones |
| docs/plans/2026-03-18-ddi-design.md | DDI platform design |
| docs/plans/2026-03-18-ddi-implementation.md | Implementation plan |
Quick start (development)
From the repo root:
bun install
# Coordinator API + UI (API needs PostgreSQL for full features — see CLAUDE.md)
bun run dev
API defaults to http://127.0.0.1:3000; Vite UI defaults to http://127.0.0.1:5173 with /api proxied to the API.
Production-style layout (database node + static UI + members) is described in CLAUDE.md and progress.md (split UI, octet-database, octet-ui, registry, etc.).
Bootstrap with pre-built images (GitHub Container Registry)
CI publishes slim role images to GHCR on pushes to main and on version tags (v*). Workflow: .github/workflows/docker-publish.yml.
Published coordinator image (database/API + embedded Postgres): ghcr.io/chdao/projectoctet/octet-database:latest. The UI and members use the same prefix: ghcr.io/chdao/projectoctet/octet-ui, octet-dns, etc.
Replace chdao with your org on a fork. Private GHCR: docker login ghcr.io first (read:packages).
Registry bootstrap (choose one path)
On Linux (iproute2), derive HOST_LAN_IP from the IPv4 used for outbound traffic (same idea as scripts/host-lan-ip-for-compose.sh). Override manually if this resolves to a Docker bridge address.
REGISTRY=ghcr.io/chdao/projectoctet
HOST_LAN_IP="$(ip -4 route get 8.8.8.8 2>/dev/null | awk '{ for (i = 1; i < NF; i++) if ($i == "src") { print $(i + 1); exit } }' || true)"
# If empty or wrong (e.g. multihomed / bridge): HOST_LAN_IP=192.168.1.50
From a git checkout (recommended; works for private repos)
Anonymous curl https://raw.githubusercontent.com/... only works for public repositories. If the repo is private, clone (or unpack a source tarball you trust), cd to the repo root, then run the same flow the remote helper would have downloaded:
bash scripts/bootstrap-from-registry.sh --host-lan-ip "$HOST_LAN_IP" --registry "$REGISTRY"
By default bootstrap-from-registry.sh installs the coordinator only: it pulls the coordinator image, creates octet_lattice if needed, starts octet-database-1 (override OCTET_DB_CONTAINER), optionally restores a snapshot if one sits at .octet-coordinator-db-snapshot/pre-redeploy.dump (no-op on a fresh install — nothing is seeded), then prints the octet-print-ui-bootstrap block to stdout and exits. octet-ui-1 is not started, and no lattice member containers are deployed. Run the printed docker run block on whichever host will serve the UI (same host is fine). Add members later through the UI — it emits a per-member install script you run on the host each member will live on. Pass --full to also auto-run UI bootstrap and start member containers from existing grid_members rows (that is what redeploy-octet-database.sh does locally). It uses the copies of scripts/lib/octet-coordinator-db-snapshot.sh in your checkout.
Without a clone (remote-bootstrap.sh) — public repo, or authenticated curl
scripts/remote-bootstrap.sh downloads scripts/bootstrap-from-registry.sh plus scripts/lib/octet-coordinator-db-snapshot.sh into ~/.octet-remote-bootstrap (override OCTET_REMOTE_BOOTSTRAP_HOME), then **exec**s the same bootstrap-from-registry.sh as above (coordinator-only default — pass --full if you really want UI + members auto-started from this path).
Public repo (no token): raw.githubusercontent.com serves public files anonymously.
curl -fsSL "https://raw.githubusercontent.com/chdao/projectoctet/main/scripts/remote-bootstrap.sh" | bash -s -- \
--host-lan-ip "$HOST_LAN_IP" --registry "$REGISTRY"
Private GitHub repo: raw.githubusercontent.com does not accept Authorization: Bearer headers and returns 404 for private paths even with a valid token. Use the REST contents API (api.github.com/repos/<owner>/<repo>/contents/<path>?ref=<ref>) with Accept: application/vnd.github.raw+json — that endpoint authenticates correctly. Create a read-only token with Contents: Read (classic PAT or fine-grained). Export GITHUB_TOKEN or GH_TOKEN before the pipe so remote-bootstrap.sh can also authenticate its internal downloads of the two helper scripts:
export GITHUB_TOKEN=ghp_… # or fine-grained PAT, Contents: Read on chdao/projectoctet
curl -fsSL \
-H "Authorization: Bearer ${GITHUB_TOKEN}" \
-H "Accept: application/vnd.github.raw+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
"https://api.github.com/repos/chdao/projectoctet/contents/scripts/remote-bootstrap.sh?ref=main" | bash -s -- \
--host-lan-ip "$HOST_LAN_IP" --registry "$REGISTRY"
Forks and version pins: the curl URL picks which copy of remote-bootstrap.sh runs; that script then re-downloads the two helpers. By default those helpers come from chdao/projectoctet @ main. For a fork, set OCTET_REMOTE_BOOTSTRAP_REPO=owner/projectoctet on the bash that consumes the pipe so the helpers match your repo. For a tag or branch, set OCTET_REMOTE_BOOTSTRAP_REF to the same ref you trust (for example the tag in your curl URL):
# Public fork — raw.githubusercontent.com
curl -fsSL "https://raw.githubusercontent.com/chdao/projectoctet/v1.2.3/scripts/remote-bootstrap.sh" | \
env OCTET_REMOTE_BOOTSTRAP_REF=v1.2.3 bash -s -- --host-lan-ip "$HOST_LAN_IP" --registry "$REGISTRY"
# Private fork — REST contents API, token exported above
curl -fsSL \
-H "Authorization: Bearer ${GITHUB_TOKEN}" \
-H "Accept: application/vnd.github.raw+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
"https://api.github.com/repos/chdao/projectoctet/contents/scripts/remote-bootstrap.sh?ref=v1.2.3" | \
env OCTET_REMOTE_BOOTSTRAP_REF=v1.2.3 bash -s -- --host-lan-ip "$HOST_LAN_IP" --registry "$REGISTRY"
Examples match the script header: --registry localhost:5000 after a local build/push, or any host:port/path registry prefix (no trailing slash).
Optional environment variables (see script and docker-compose.yml): OCTET_COORDINATOR_MESH_SIDECAR_ENABLED=1 to start the coordinator mesh sidecar (WireGuard UDP published on WIREGUARD_PORT, default 51820); OCTET_SKIP_COORDINATOR_DB_RESTORE, OCTET_COORDINATOR_DATA_VOLUME_NAME, etc.
Rebuild images locally and push to your registry, then bootstrap the same way:
sudo bash scripts/redeploy-octet-database.sh --host-lan-ip "$HOST_LAN_IP" --registry localhost:5000
That script snapshots the coordinator DB (unless skipped), rebuilds role images, pushes, and runs bootstrap-from-registry.sh --full so UI and lattice member containers are deployed automatically (different from the GitHub install default above, which is coordinator-only).
Fresh coordinator data: remove octet-database-1 (or your OCTET_DB_CONTAINER) and docker volume rm octet_octet_data (destructive — only when a data snapshot round-trip is safe per CLAUDE.md).
Print UI bootstrap (manual copy-paste)
When the coordinator is already running, print the export lines and docker run … octet-ui … snippet:
docker exec octet-database-1 octet-print-ui-bootstrap
Use the container name you chose (octet-database-1 is the default in compose and bootstrap-from-registry.sh). If octet-print-ui-bootstrap errors with WIREGUARD_MASTER_PUBLIC_KEY missing, wait a few seconds and run it again.
Use stdout as the copy-paste block: run the **export**s and docker run yourself on the machine that will host the UI (see comments in the output). Do not pipe this command to bash unless you intend to execute everything it prints.
The helper also syncs the split-UI grid member in Postgres (see containers/database/ui-bootstrap.sh).
Image names (under your registry prefix)
| Role | Image (after ${REGISTRY}/) |
|---|---|
| Coordinator | octet-database:latest |
| Static UI | octet-ui:latest |
| Members | octet-dns, octet-recursor, octet-dhcp, octet-dist |
The coordinator image runs PostgreSQL inside the same container (embedded DB) for typical single-node bootstrap. CI also publishes octet-postgres:latest for an optional topology: a separate database grid member that joins over WireGuard using the Setup flow in the UI (/setup). You do not need that image for the commands above.
Compose without bind-mounting the repo
The default docker-compose.yml bind-mounts .:/app for development, which replaces the baked /app in pre-built images. docker-compose.prebuilt.yml keeps only octet_data → /var/lib/octet (same volume name pattern octet_octet_data as bootstrap-from-registry.sh). After pull / up, use docker exec octet-database-1 octet-print-ui-bootstrap the same way (or ${OCTET_DB_CONTAINER:-octet-database-1}).
Member images
Install scripts expect member images under the same OCTET_DOCKER_REGISTRY the coordinator was started with. DHCP defaults to Docker macvlan on network octet_dhcp_lan (create it on the host first; see docker-compose.dhcp-macvlan.example.yml). Override with OCTET_MEMBER_DHCP_DOCKER_NETWORK=bridge (no LAN L2) or host. Optional OCTET_MEMBER_DHCP_MACVLAN_NETWORK / OCTET_MEMBER_DHCP_MACVLAN_IPV4 customize the install script.
Adding a new host (sidecar-driven provisioning)
After the lattice exists, bringing in a new host is a single curl on the target machine — no per-member install script anymore:
- In the UI, Members page → Add Host. Copy the generated
curl …/host-install?token=… | sudo bashcommand. - Run it as root on the fresh host. The mesh-sidecar container is the only thing installed; it registers with the coordinator, receives a
/28CGNAT block, and starts polling. - Within ~30 s the host appears on the Members page. Add members to it via Add Member — the coordinator assigns their CGNAT in the new host's block and its sidecar pulls the image and starts the container on the next reconcile tick.
What this replaces:
- Before: each member required its own
curl …/members/:id/install | bashSSH dance, which also installed a mesh-sidecar if absent, leading to subtle drift between the per-memberdocker runline and what the coordinator thought a member should look like. - After: exactly one shell command per new host. Every subsequent member on that host is managed from the UI; the sidecar holds the Docker socket and reconciles from the coordinator's
GET /api/v1/mesh-hosts/:id/desired-statepayload. See docs/superpowers/specs/2026-04-23-sidecar-driven-member-provisioning-design.md.
The legacy per-member install flow is still served (GET /api/v1/members/:id/install) for hosts that joined the lattice before this change. They continue to work unchanged; their containers are unlabeled and the host sidecar on those machines ignores them.
Lattice bootstrap (the very first coordinator host) is unchanged — it still uses scripts/bootstrap-from-registry.sh / scripts/redeploy-octet-database.sh.
License and branding
See packages/ui/src/lib/brand.ts for product name and copyright line shown in the app.








