diverdale/atlas repository overview

⁠Atlas

Lightweight network IPAM — NetBox without the DCIM bloat. Track sites, VLANs, subnets, and hosts. Scan your network, detect conflicts, get alerts, and visualise everything on a live canvas map.

⁠Features

• Sites & VLANs — organise subnets by location or function
• Subnet hierarchy — parent/child prefix tree (10.0.0.0/8 → 10.1.0.0/16 → 10.1.1.0/24)
• Host tracking — IP addresses with hostname, MAC, device type, DNS name, notes, custom fields
• Network scanning — ping-scan any prefix on demand or on a schedule
• Conflict detection — duplicate MACs and hostnames flagged automatically
• Alerts — webhook and Prowl notifications for new devices, offline devices, and subnet utilization thresholds
• Utilization history — daily snapshots with trend chart per prefix
• Network map — interactive force-directed canvas graph; zoom, pan, click to drill in
• Audit log — every create/update/delete recorded with before/after JSON
• Custom fields — user-defined fields on prefixes and addresses

⁠Quickstart

⁠Docker Compose (recommended)

services:
  atlas:
    image: diverdale/atlas:latest
    container_name: atlas
    restart: unless-stopped
    network_mode: host          # needed for scan to reach LAN
    volumes:
      - ./config:/config        # database lives at /config/atlas.db

docker compose up -d

Open http://<host>:8080 in your browser.

⁠Environment variables

⁠Run from source

Requires Go 1.21+ and Node 20+.

# Build the frontend
cd web && npm ci && npm run build && cd ..

# Run the server
ATLAS_DB=./atlas.db go run .

⁠Usage overview

1. Create a site — Sites are the top-level container (e.g. "Corp HQ", "Lab", "DMZ").
2. Add prefixes — Add your address blocks. Nested prefixes are detected automatically.
3. Add VLANs — Optionally tag prefixes with a VLAN.
4. Scan — Open a prefix and hit Scan to discover hosts. Schedule recurring scans from the same page.
5. Explore — Use Map for a visual overview, Search to find any IP or hostname, Conflicts to catch duplicate MACs.
6. Alerts — Configure webhook or Prowl delivery under Notifications.

⁠Network map

The /map page renders a live force-directed graph of your entire network:

• Solid circles = sites (one colour per site)
• Outlined circles = prefixes (border colour = utilization: green < 60%, amber 60–80%, red > 80%)
• Scroll to zoom, drag to pan, click a prefix to open its detail page

⁠Notifications

Atlas can send alerts via:

• Webhook — HTTP POST with a JSON body; compatible with Slack, Discord, n8n, Home Assistant, etc.
• Prowl — iOS push notifications

Configurable events: new device discovered, device went offline, subnet utilization threshold crossed.

⁠API

All data is available via the REST API at /api/v1. Example endpoints:

GET  /api/v1/sites
GET  /api/v1/prefixes
GET  /api/v1/prefixes/{id}/addresses
POST /api/v1/prefixes/{id}/scan
GET  /api/v1/conflicts
GET  /api/v1/audit

Full API key auth and webhook events are planned for Phase 4.

⁠Docker image

diverdale/atlas:latest

Multi-arch manifest — supports linux/amd64 and linux/arm64 (Synology, Raspberry Pi, etc.).

To build locally:

docker buildx build --platform linux/amd64,linux/arm64 -t diverdale/atlas:latest --push .