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

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