80 lines
4.6 KiB
Markdown
80 lines
4.6 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
|
|
|
|
## 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.
|