ServiceMap

Understand what runs, what depends on it, and why a service is unhealthy.

ServiceMap is a self-hosted service intelligence workspace for homelabs and small environments. It combines explicit dependencies, bounded probes, reviewable discovery and durable incident evidence in a navigable topology.

flowchart LR
  A[Define / discover] --> B[Review topology]
  B --> C[Probe and observe]
  C --> D[Resolve health evidence]
  D --> E[Trace impact and incidents]

What you can do

Probe HTTP(S), TCP, DNS and TLS certificate expiry with configurable thresholds and retries.
Navigate Domain → Application → Component with search, filters, focus and blast-radius views.
Inspect provider, confidence, scope, freshness and conflicts behind each health decision.
Review Docker discovery and optional AppOps enrichment before importing canonical topology.
Track incident acknowledgement, resolution, availability, maintenance and retained event history.
Compare canonical topology snapshots and retain relationship provenance.
Use SSE updates and deterministic ELK topology layout with reduced-motion support.
Import/export validated YAML or JSON configuration atomically.

Explore safely

Choose Explore demo to open the fictional Northstar Platform: nine services, synthetic observations and a seeded PostgreSQL failure. The same incident and dependency logic identifies downstream impact. The demo contacts no fictional endpoints; Exit demo restores the saved topology, and Reset demo restores its synthetic starting state.

Demo preview

Captured from the real application with its synthetic Northstar demo. No private infrastructure or live monitoring inventory is shown.

Deploy with Docker Compose

git clone https://gitea.itworx.tech/Jens/ServiceMap-Public.git
cd ServiceMap-Public
cp .env.example .env
docker compose up --build

Open http://localhost:1253. Standard Compose runs the Python API and React frontend separately and persists SQLite under ./data. Preserve this directory during upgrades. Set SERVICEMAP_PROBE_INTERVAL=0 to disable scheduled probes. Define targets and dependencies in the UI or import a configuration before expecting live coverage.

The single-container Unraid build is provided by Dockerfile.unraid and docker-compose.yml. Review the socket/network mounts before enabling discovery. A read-only Docker socket mount still exposes a powerful Docker API boundary. Broker mode requires a dedicated registered identity and token file and deliberately has no socket fallback. AppOps enrichment is optional; configure your own endpoint.

Security and health semantics

Protect the UI/API with network restrictions or tested OIDC configuration. Authentication is disabled by default; do not expose an unprotected deployment to the Internet. OIDC supports viewer/operator/admin roles when its issuer, audience and groups are provisioned. Discovery uses deployment-configured targets, not arbitrary browser-supplied targets.

Health distinguishes unmonitored, unknown, healthy, degraded, down, recovering and maintenance. A runtime observation is not automatically a successful endpoint probe. Application-scoped AppOps evidence does not silently establish component health. Expired evidence and ambiguous relationships remain visible instead of inventing certainty.

Development

python -m venv .venv
# Activate .venv for your shell.
pip install -r requirements.txt
uvicorn app.main:app --app-dir backend --reload --port 8000

In another terminal:

npm --prefix frontend ci
npm --prefix frontend run dev

Vite proxies the API to port 8000. Validate changes with python -m pytest, npm --prefix frontend test, npm --prefix frontend run typecheck, npm --prefix frontend run lint and npm --prefix frontend run build. Browser tests exercise the synthetic demo. See architecture for the data and observation model.

Source distribution and licensing

This is the curated public source edition of ServiceMap 1.6.2. Reviewed updates flow from the private canonical repository after merges to main; private history, production evidence and internal CI/deployment workflows are excluded. Deployment examples use generic addresses and must be configured for your environment.

No project-wide license is included. Public source visibility does not grant reuse or redistribution rights; obtain the owner's terms and review third-party dependencies before redistribution.

4.6 KiB Raw Blame History