{"id":48916822,"url":"https://github.com/spatiumddi/spatiumddi","last_synced_at":"2026-04-25T00:00:47.047Z","repository":{"id":351674324,"uuid":"1208994172","full_name":"spatiumddi/spatiumddi","owner":"spatiumddi","description":"Open-source DDI platform — unified DNS, DHCP, and IP Address Management. Runs its own BIND9 + Kea service containers, with a FastAPI control plane and React UI. Alpha.","archived":false,"fork":false,"pushed_at":"2026-04-19T17:39:01.000Z","size":2483,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-19T19:33:41.500Z","etag":null,"topics":["bind9","ddi","dhcp","dns","dns-management","docker","fastapi","infrastructure","ip-address-management","ipam","kubernetes","netops","network-automation","open-source","react","self-hosted"],"latest_commit_sha":null,"homepage":"https://spatiumddi.github.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatiumddi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T01:49:40.000Z","updated_at":"2026-04-19T17:35:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/spatiumddi/spatiumddi","commit_stats":null,"previous_names":["spatiumddi/spatiumddi"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/spatiumddi/spatiumddi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatiumddi%2Fspatiumddi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatiumddi%2Fspatiumddi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatiumddi%2Fspatiumddi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatiumddi%2Fspatiumddi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatiumddi","download_url":"https://codeload.github.com/spatiumddi/spatiumddi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatiumddi%2Fspatiumddi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32245151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bind9","ddi","dhcp","dns","dns-management","docker","fastapi","infrastructure","ip-address-management","ipam","kubernetes","netops","network-automation","open-source","react","self-hosted"],"created_at":"2026-04-17T03:06:41.621Z","updated_at":"2026-04-25T00:00:47.040Z","avatar_url":"https://github.com/spatiumddi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.svg\" alt=\"SpatiumDDI Logo\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSpatiumDDI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eSelf-hosted DNS, DHCP, and IPAM — one control plane, real servers underneath.\u003c/strong\u003e\u003cbr/\u003e\n  A modern, open-source alternative to commercial DDI platforms.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/spatiumddi/spatiumddi/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/spatiumddi/spatiumddi/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/spatiumddi/spatiumddi\" alt=\"Issues\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://spatiumddi.github.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-github.io-informational\" alt=\"Docs\"/\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/status-alpha-orange\" alt=\"Status\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.12+-green\" alt=\"Python\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/react-18+-61DAFB\" alt=\"React\"/\u003e\n\u003c/p\u003e\n\n---\n\n\u003e ⚠️ **Alpha software.** SpatiumDDI is under active development and has not yet been battle-tested in production. Expect rough edges, breaking schema changes between releases (Phase 1), and features listed in the roadmap that are still in flight. Run it in a lab, file bugs, and please don't put it in front of DHCP clients you care about until Phase 2 is complete. Early adopter feedback is very welcome — open an issue or start a discussion on GitHub.\n\n---\n\n## Why SpatiumDDI\n\n**It runs DNS and DHCP — not just configures them.** A modern alternative to Infoblox and EfficientIP: most open-source IPAM tools are pretty dashboards over someone else's `/etc/bind/named.conf`. SpatiumDDI bundles BIND9 and Kea as first-class service containers; the control plane owns their config, they auto-register, and they keep serving if the control plane is down.\n\n**One platform, three surfaces.** IPAM tree, DNS zones, DHCP scopes — one UI, one REST API, one source of truth. Hostname changes in IPAM propagate to DNS; reservations propagate to DHCP. No more three-tab reconciliation.\n\n**Bring your own servers — or ours.** Use the bundled Kea and BIND9, or point SpatiumDDI at your existing Windows DCs and DHCP servers via WinRM. Agentless in both directions — nothing installed on the Windows side.\n\n**Built for delegation.** Group-based RBAC with LDAP, OIDC, SAML, RADIUS, and TACACS+ (with backup-server failover). Hand a subnet or a zone to a department without handing over root.\n\n**API-first.** Every UI action is a REST call. Terraform, Ansible, and ad-hoc scripts all speak the same surface. If you can click it, you can automate it.\n\n## What's in the box\n\n- 🗂 **Hierarchical IP management** — spaces, blocks, subnets, addresses in a visual tree; IPv4 + full IPv6 auto-allocation (EUI-64 + random /128 + sequential)\n- 🌐 **Built-in DNS server** — BIND9 container that auto-registers, syncs via RFC 2136, and reports per-server zone serial drift\n- 🔄 **DHCP server management** — Kea container + agent with lease tracking; group-centric HA (hot-standby + load-balancing) with live state reporting, self-healing peer-IP drift, and supervised daemons for crash-loop-safe restarts\n- 🪟 **Windows Server DNS + DHCP** — agentless management of existing Windows DCs (RFC 2136 + WinRM for DNS; near-real-time WinRM lease-mirroring for DHCP). No software installed on the Windows side.\n- 🧩 **Read-only integrations** — auto-mirror **Kubernetes** clusters (CIDRs, nodes, LoadBalancer VIPs, Ingress → DNS), **Docker** hosts (networks, optional container IPs), and **Proxmox VE** endpoints (bridges, SDN VNets + subnets, VMs, LXC guests — runtime IPs via QEMU guest-agent, one row per cluster) into IPAM with one-click setup guides. Opt-in VNet-CIDR inference from guest NICs for SDN deployments where PVE is L2-only. Per-endpoint \"Discovery\" modal shows which VMs aren't reporting IPs + why, with copy-ready fix hints. Settings toggle gates each; per-target sync interval + on-demand Sync Now. Supernet auto-creation for RFC 1918 / CGNAT ranges keeps the tree tidy.\n- 🎨 **Dashboard-at-a-glance** — platform health card (API / Postgres / Redis / workers / beat), live DNS query rate + DHCP traffic charts (BIND9 statistics-channels + Kea `statistic-get-all`, self-contained — no Prometheus needed), subnet utilization heatmap, and live activity feed\n- 🔒 **Group-based RBAC + external identity** — LDAP, OIDC, SAML, RADIUS, TACACS+ with backup-server failover; delegate IP ranges and zones by role; API tokens with auto-expiry\n- 🔔 **Alerts + audit forwarding** — rule-based alerts framework (subnet utilization, server unreachable) + multi-target syslog (UDP / TCP / TLS) + HTTP webhook forwarding with pluggable wire formats (RFC 5424 JSON / CEF / LEEF / RFC 3164 / JSON lines) and per-target filters\n- 🔐 **ACME DNS-01 provider** — `acme-dns`-compatible HTTP surface so certbot / lego / acme.sh can issue public certs (wildcards included) for names delegated to a SpatiumDDI-managed zone\n- 🏷 **IEEE OUI vendor lookup** — opt-in display of MAC vendor names in IP tables and DHCP leases, with filter-by-vendor support\n- 📋 **Full audit trail** — every mutation logged, append-only, viewable in the UI with per-column filters\n- 🚀 **Flexible deployment** — Docker Compose, Kubernetes (Helm umbrella chart + OCI publishing), bare metal, or OS appliance\n\n---\n\n## Screenshots\n\n_Click any image to open the full-size version._\n\n| [Dashboard](docs/assets/screenshots/dashboard.png) | [IPAM](docs/assets/screenshots/ipam.png) |\n| :---: | :---: |\n| [\u003cimg src=\"docs/assets/screenshots/dashboard.png\" alt=\"Dashboard\" width=\"450\"/\u003e](docs/assets/screenshots/dashboard.png) | [\u003cimg src=\"docs/assets/screenshots/ipam.png\" alt=\"IPAM\" width=\"450\"/\u003e](docs/assets/screenshots/ipam.png) |\n| Utilisation, VLAN, DNS \u0026amp; DHCP status at a glance | Hierarchical space / block / subnet tree with per-IP DNS sync |\n\n| [DNS](docs/assets/screenshots/dns.png) | [DHCP](docs/assets/screenshots/dhcp.png) | [VLANs](docs/assets/screenshots/vlans.png) |\n| :---: | :---: | :---: |\n| [\u003cimg src=\"docs/assets/screenshots/dns.png\" alt=\"DNS\" width=\"300\"/\u003e](docs/assets/screenshots/dns.png) | [\u003cimg src=\"docs/assets/screenshots/dhcp.png\" alt=\"DHCP\" width=\"300\"/\u003e](docs/assets/screenshots/dhcp.png) | [\u003cimg src=\"docs/assets/screenshots/vlans.png\" alt=\"VLANs\" width=\"300\"/\u003e](docs/assets/screenshots/vlans.png) |\n| Zones, records, server groups | Scopes, pools, static reservations | Routers \u0026amp; VLANs linked to subnets |\n\n---\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/architecture.svg\" alt=\"SpatiumDDI architecture\" width=\"900\"/\u003e\n\u003c/p\u003e\n\n**Control plane** — FastAPI + PostgreSQL + Redis + Celery. Single source of truth for everything (IPAM tree, DNS records, auth, audit log). Exposes a REST API; the web UI and any Terraform / Ansible / CLI integration all speak the same API.\n\n**Data plane — two shapes:**\n\n- **Agented** (BIND9, Kea) — one container per service. Each bakes in a sidecar agent (`spatium-dns-agent` / `spatium-dhcp-agent`) that (1) bootstraps with a PSK → rotating JWT, (2) long-polls `/config` with an ETag, (3) caches the last-known-good bundle on disk so the service keeps serving if the control plane is unreachable, (4) drains record / config ops over loopback (nsupdate + TSIG for BIND9; Kea Control Agent API for Kea). Structural changes reload named / kea-dhcp4; record changes do not.\n\n- **Agentless** (Windows DNS, Windows DHCP) — no software on the Windows side. The control plane speaks directly: RFC 2136 over UDP/TCP 53 (DNS record writes + AXFR), WinRM + PowerShell over 5985/5986 (DNS zone CRUD, DHCP lease / scope reads). Credentials are Fernet-encrypted on the server row.\n\nThe driver abstraction is backend-neutral — services speak to `DNSDriver` / `DHCPDriver`, never to BIND9 / Kea / PowerShell specifics.\n\n**Tech stack**: Python 3.12 · FastAPI · SQLAlchemy 2.x (async) · PostgreSQL 16 · Redis 7 · Celery · React 18 · TypeScript · Tailwind · shadcn/ui · pywinrm · dnspython · Docker · Kubernetes + Helm\n\n---\n\n## Getting Started\n\n\u003e ⚠️ SpatiumDDI is **alpha** (first release: `2026.04.16-1`). Commands and APIs may still shift between releases.\n\n\u003e 📘 For the full setup order (servers → zones/scopes → subnets → addresses) see **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)**. For Windows DC integration see **[docs/deployment/WINDOWS.md](docs/deployment/WINDOWS.md)**.\n\n### Quick start with Docker Compose\n\n```bash\ngit clone https://github.com/spatiumddi/spatiumddi.git\ncd spatiumddi\ncp .env.example .env\n# Required env vars in .env:\n#   POSTGRES_PASSWORD=\u003cset this\u003e\n#   SECRET_KEY=$(openssl rand -hex 32)\n#   DNS_AGENT_KEY=$(openssl rand -hex 32)   # needed if running the DNS container\ndocker compose build\ndocker compose run --rm migrate\ndocker compose up -d\n```\n\nOpen `http://localhost:8077` and log in with `admin` / `admin` (you're forced to change the password on first login).\n\n### Running the built-in BIND9 / Kea containers\n\nThe managed-service containers ship under Compose profiles — opt in when you want them:\n\n```bash\ndocker compose --profile dns up -d                 # DNS only\ndocker compose --profile dns --profile dhcp up -d  # DNS + DHCP\n```\n\nOr set `COMPOSE_PROFILES=dns,dhcp` in your `.env` so plain `docker compose up -d` enables both automatically.\n\nThat starts `dns-bind9` bound to host port `5353` (udp + tcp). The agent registers with the control plane automatically using `DNS_AGENT_KEY` from your `.env` and appears in the UI under **DNS → Server Groups → default**.\n\nCreate a zone + record in the UI, then verify with `dig`:\n\n```bash\ndig @127.0.0.1 -p 5353 \u003cyour-record\u003e.\u003cyour-zone\u003e A +short\ndig @127.0.0.1 -p 5353 -x \u003cyour-ip\u003e +short    # reverse (PTR)\n```\n\nRecord changes propagate to BIND9 via RFC 2136 — typically sub-second, no daemon restart. Zone / ACL / view changes trigger a config reload.\n\n**Production**: point the agent at your real control plane, expose `53/udp` + `53/tcp`, and run one container per DNS server you want in the cluster. All servers in a group share the same TSIG key for dynamic updates.\n\n### API \u0026 interactive docs\n\nThe FastAPI backend auto-generates OpenAPI / Swagger:\n\n| Path | What |\n|---|---|\n| `http://localhost:8077/api/docs` | Swagger UI — try endpoints directly from the browser |\n| `http://localhost:8077/api/redoc` | ReDoc — cleaner reference layout |\n| `http://localhost:8077/api/openapi.json` | Raw OpenAPI 3 spec (for code generators) |\n\nEvery UI action is a REST call, so anything you do in the UI you can do via `curl`, Terraform, or your own client. Log in to the UI first to obtain a bearer token, then use `Authorization: Bearer \u003ctoken\u003e`.\n\n### Reset the admin password\n\n```bash\ndocker compose exec api python - \u003c\u003c'EOF'\nimport asyncio\nfrom sqlalchemy import update\nfrom app.core.security import hash_password\nfrom app.db import AsyncSessionLocal\nfrom app.models.auth import User\n\nasync def reset():\n    async with AsyncSessionLocal() as db:\n        await db.execute(update(User).where(User.username == \"admin\")\n            .values(hashed_password=hash_password(\"NewPass!\"), force_password_change=True))\n        await db.commit()\n\nasyncio.run(reset())\nEOF\n```\n\n### Requirements\n\n- Docker 24+ and Docker Compose v2, **or**\n- Kubernetes 1.27+ with Helm 3, **or**\n- Ubuntu 22.04 / Debian 12 / Alpine 3.20+ for bare metal\n\n---\n\n## Deployment Options\n\n| Method | Use case | Status |\n|---|---|---|\n| **Docker Compose** | Dev, small single-host production | ✅ Supported |\n| **Kubernetes + Helm** | Multi-node production, scalable | ✅ Umbrella chart (`charts/spatiumddi`, published OCI to `ghcr.io/spatiumddi/charts/spatiumddi`) |\n| **Bare metal / VM (Ansible)** | On-prem without containers | 📋 Planned |\n| **OS Appliance (ISO / qcow2)** | Air-gapped, zero-dependency | 📋 Planned |\n\n---\n\n## Documentation\n\nFull docs at **[spatiumddi.github.io](https://spatiumddi.github.io)** (coming soon).\n\n| Document | Description |\n|---|---|\n| [Getting Started](docs/GETTING_STARTED.md) | Recommended setup order — from server groups down to allocating an IP |\n| [IPAM Features](docs/features/IPAM.md) | IP space, block, subnet, address management |\n| [DHCP Features](docs/features/DHCP.md) | DHCP server management — Kea, Windows DHCP |\n| [DNS Features](docs/features/DNS.md) | DNS zones, views, server groups, blocking lists, Windows DNS |\n| [Auth \u0026 Permissions](docs/features/AUTH.md) | LDAP, OIDC, SAML, RADIUS, TACACS+, roles, scoped permissions |\n| [System Admin](docs/features/SYSTEM_ADMIN.md) | Health dashboard, backup, notifications |\n| [Observability](docs/OBSERVABILITY.md) | Logging, metrics, alerting |\n| [Windows Server Setup](docs/deployment/WINDOWS.md) | WinRM, service accounts, firewall — Windows-side checklist |\n| [DNS Agent Design](docs/deployment/DNS_AGENT.md) | Agent protocol, auto-registration, config sync |\n| [DNS Driver Spec](docs/drivers/DNS_DRIVERS.md) | BIND9 + Windows DNS driver internals |\n| [DHCP Driver Spec](docs/drivers/DHCP_DRIVERS.md) | Kea + Windows DHCP driver internals |\n| [Appliance Deployment](docs/deployment/APPLIANCE.md) | OS image build and licensing |\n\n---\n\n## Project Status\n\n| Phase | Focus | Status |\n|---|---|---|\n| Phase 1 | Core IPAM, auth, user management, audit log, Docker Compose | ✅ Done — LDAP/OIDC/SAML + RADIUS/TACACS+, group-based RBAC, bulk-edit, inheritance, mobile-responsive UI, and full IPv6 `/next-address` (EUI-64 + random /128 + sequential) all shipped |\n| Phase 2 | DHCP (Kea), DNS (BIND9), DDNS, zone/subnet tree UI | ✅ Done — DNS, Kea DHCPv4, subnet-level DDNS, agent-side Kea DDNS, block/space DDNS inheritance, per-server zone serial reporting all shipped |\n| Phase 3 | DNS views, server groups, blocking lists, VLAN/VXLAN, system admin, Kea HA | 🔄 DNS features + health dashboard + alerts framework + group-centric Kea HA (self-healing peer-IP drift + supervised daemons) landed; DNS Views end-to-end + HA state-transition actions still pending |\n| Phase 4 | OS appliance, Terraform provider, SAML, backup/restore, ACME | 🔄 SAML landed; appliance + providers + backup + ACME (DNS-01 provider + embedded client) pending |\n| Phase 5 | Multi-tenancy, IP request workflows, advanced reporting | 📋 Planned |\n\nSee [CHANGELOG.md](CHANGELOG.md) for the per-release feature list and\n[CLAUDE.md](CLAUDE.md) for the authoritative spec.\n\n---\n\n## Contributing\n\nContributions are welcome.\n\n- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR\n- Good first tasks are tagged on the [issue tracker](https://github.com/spatiumddi/spatiumddi/issues)\n- Design discussion happens in [GitHub Discussions](https://github.com/spatiumddi/spatiumddi/discussions)\n\n---\n\n## License\n\nReleased under the [Apache 2.0 License](LICENSE).\n\nBundled components (BIND9, ISC Kea) are distributed under their own licenses. See [NOTICE](NOTICE) for the full list.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built with ❤️ by the SpatiumDDI community · \u003ca href=\"https://spatiumddi.github.io\"\u003espatiumddi.github.io\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatiumddi%2Fspatiumddi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatiumddi%2Fspatiumddi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatiumddi%2Fspatiumddi/lists"}