# 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.

```mermaid
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.

![Dependency landscape with synthetic root-cause evidence](docs/screenshots/demo-landscape.png)

![Synthetic incident and monitoring-coverage overview](docs/screenshots/demo-health.png)

## Deploy with Docker Compose

```bash
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.

## Move from demo to live coverage

Exit the synthetic demo, define one real service and its dependency, then select the probe appropriate to that component. Check the observation timestamp and supporting evidence before expanding the topology. Review discovered candidates before importing them into the canonical map.

If a component stays unmonitored or unknown, check its probe configuration, reachability and freshness. A dependency edge describes impact relationships; it does not prove that both endpoints are healthy. Keep topology configuration and persisted incident history in your backup plan.

## 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

```bash
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:

```bash
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](docs/ARCHITECTURE.md) 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.