Full docker DDI.
  • TypeScript 89.4%
  • Python 4.7%
  • Shell 2.6%
  • PLpgSQL 1.4%
  • Go 0.7%
  • Other 1.1%
Find a file
cdaoust 1a19c6d423
Some checks failed
build-images / build-push (push) Failing after 1h30m6s
Merge fix/lattice-aux-address-reserve-sidecar-ip: reserve lattice .2 via --ip-range
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>
2026-10-22 16:33:16 +00:00
.claude chore(lint): adopt Biome formatter + targeted rule disables to bring CI green 2026-04-28 12:58:19 +00:00
.gitea/workflows fix(ci): fingerprint octet-coordinator against the octet-api metafile (was stale) 2026-08-25 15:59:30 +00:00
.github/workflows wip(recovery): checkpoint shell+CI+agent+sidecar+ui fixes after concurrent-git incident 2026-07-14 02:56:05 +00:00
containers fix(sidecar): reserve lattice .2 via --ip-range, not aux-address 2026-10-05 20:46:19 +00:00
docs docs(plan): W1 — resolver-fed pgbouncer (drop db1 IP pin) 2026-08-30 18:24:34 +00:00
integrations/lego-dns-octet feat(dns): OCI cloud zone publish, managed lists, and zone NS UX 2026-04-20 01:55:42 +00:00
migrations Revert "Merge fix/ip-permutation-livelock-revive: self-heal docker_bridge_ip permutation after reshuffled reboot" 2026-10-22 16:32:35 +00:00
packages Merge fix/ip-refresh-two-phase-converge: two-phase converge member-IP-refresh so permutations don't livelock 2026-10-22 16:32:43 +00:00
scripts fix(coordinator): provision OCTET_HOST_BOOTSTRAP_TOKEN so log-ingest starts 2026-09-18 05:26:20 +00:00
tests/e2e chore(lint): adopt Biome formatter + targeted rule disables to bring CI green 2026-04-28 12:58:19 +00:00
.dockerignore feat(ddi): grid stack, mesh DDNS, co-located install host LAN 2026-03-20 13:44:49 +00:00
.gitignore wip(recovery): checkpoint shell+CI+agent+sidecar+ui fixes after concurrent-git incident 2026-07-14 02:56:05 +00:00
biome.json chore: lint/type hygiene baseline (scoped biome, unified tsconfig, enforced) — zero behavior change (#48) 2026-06-08 21:58:32 -04:00
build-version.txt fix(ui): usability sweep — readable errors, keyboard rows, labeled buttons, AA contrast (#88) 2026-06-12 13:42:07 -04:00
bun.lock feat(agent): network sweep engine (icmp/arp/snmp/ptr) 2026-07-26 08:07:01 +00:00
bunfig.toml test(api): integration suite fixes, migrations 033–036 ts, jsonb materializers 2026-03-21 16:26:50 +00:00
CLAUDE.md docs: correct hook-scope claim and clarify current enforcement scope 2026-04-28 11:14:01 +00:00
compose.env.example DHCP domain-search (119), mesh bridge ifname, DHCID guardrails 2026-04-16 01:11:15 +00:00
docker-compose.dhcp-macvlan.example.yml feat(dhcp,grid): member bind host, Kea runtime, Infoblox import 2026-04-09 20:24:23 +00:00
docker-compose.dhcp-macvlan.yml feat(dhcp,grid): member bind host, Kea runtime, Infoblox import 2026-04-09 20:24:23 +00:00
docker-compose.ha.yml refactor: rename database-node to database (compose service + octet-database image) 2026-03-22 09:28:04 +00:00
docker-compose.prebuilt.yml chore: lint/type hygiene baseline (scoped biome, unified tsconfig, enforced) — zero behavior change (#48) 2026-06-08 21:58:32 -04:00
docker-compose.yml chore: lint/type hygiene baseline (scoped biome, unified tsconfig, enforced) — zero behavior change (#48) 2026-06-08 21:58:32 -04:00
host-metrics-preview.mjs feat: per-host cards with same-scale CPU/Memory service stacks 2026-07-24 05:12:56 +00:00
package.json chore: lint/type hygiene baseline (scoped biome, unified tsconfig, enforced) — zero behavior change (#48) 2026-06-08 21:58:32 -04:00
playwright.config.ts test(e2e): Playwright tests for auth, DNS, DHCP, and IPAM flows 2026-04-22 13:33:13 +00:00
progress.md Merge remote-tracking branch 'origin/main' into feat/cheap-liveness 2026-08-27 15:11:06 +00:00
README.md docs: sidecar-driven host-install flow in README + progress.md 2026-04-23 19:57:36 +00:00
tsconfig.base.json chore: lint/type hygiene baseline (scoped biome, unified tsconfig, enforced) — zero behavior change (#48) 2026-06-08 21:58:32 -04:00
tsconfig.json chore: lint/type hygiene baseline (scoped biome, unified tsconfig, enforced) — zero behavior change (#48) 2026-06-08 21:58:32 -04:00

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

Sign-in

Dashboard

Dashboard overview

Dashboard — Client & resolver (24h)

Resolver activity, blocklist, and recursor sections use the 24h range (see privacy note above for table blur).

Client and resolver over 24h

DNS — zones

DNS zones

DNS — views

DNS views

IPAM — networks

IPAM networks

DHCP — scopes

DHCP scopes

DHCP — active leases

Active only tab; README capture blurs IP, MAC, hostname, and scope columns only (see privacy note above).

DHCP active leases

Lattice — members

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-write for 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

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:

  1. In the UI, Members page → Add Host. Copy the generated curl …/host-install?token=… | sudo bash command.
  2. Run it as root on the fresh host. The mesh-sidecar container is the only thing installed; it registers with the coordinator, receives a /28 CGNAT block, and starts polling.
  3. 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 | bash SSH dance, which also installed a mesh-sidecar if absent, leading to subtle drift between the per-member docker run line 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-state payload. 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.