# ServerDash

A lightweight, self-hosted server monitoring dashboard: it discovers Docker
containers directly through the Docker socket and shows host resource stats
(CPU, memory, disk, load, uptime). The frontend is a small static single-page
app served by a Flask backend.

- **No external services** — no database, no reverse-engine Docker Python
  package. It talks to the Docker Engine API over the Unix socket using only
  the standard library, and collects host metrics with `psutil`.
- Live-updating cards + per-container status, CPU/mem gauges, filters, and a
  running/stopped/dead breakdown.

![](docs/screenshot.png)

## Features

- Discovers ~all Docker containers via `/var/run/docker.sock` (all states).
- Per-card: running/starting/paused/stopped/dead counts.
- Per-container: name, image, status, ports, restart policy, health, CPU/mem.
- Host cards: CPU %, memory %, disk %, load average, uptime.
- Filter containers by state pill; auto-refresh every 3s.

## Quick start (local, no Docker)

```bash
cd app
python3 -m venv .venv
source .venv/bin/activate
pip install -r ../requirements.txt

export DOCKER_SOCKET=/var/run/docker.sock   # must be readable by this user
export PORT=8787
python main.py
# open http://localhost:8787
```

The `docker.sock` must be accessible by the user running the app (add yourself
to the `docker` group, or run with sudo) — otherwise container discovery fails.

## Running inside Docker

```bash
docker build -t serverdash .
docker run --rm -p 8787:8787 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  serverdash
```

Access the dashboard at <http://localhost:8787>.

## Configuration

All through environment variables:

| Variable | Default | Description |
|---|---|---|
| `DOCKER_SOCKET` | `/var/run/docker.sock` | Path to the Docker socket. |
| `DOCKER_API_VERSION` | `1.43` | Docker Engine API version. |
| `PORT` | `8787` | HTTP port for the web UI. |
| `HOST_BIND` | `0.0.0.0` | Bind address. |
| `REFRESH_INTERVAL` | `3` | Background container refresh interval (seconds). |

## API

| Endpoint | Description |
|---|---|
| `GET /api/v1/containers` | Normalized container list (`?refresh=1` forces a pull). |
| `GET /api/v1/containers/summary` | Counts by state class. |
| `GET /api/v1/host` | Host CPU / memory / disk / load / uptime stats. |
| `GET /api/v1/healthz` | Liveness check. |

## Project layout

```
serverdash/
├── app/
│   ├── main.py            # Flask app + REST API + refresh loop
│   ├── docker_monitor.py  # Docker socket discovery (stdlib only)
│   ├── host_stats.py      # psutil host metrics
│   ├── templates/index.html
│   └── static/
│       ├── css/style.css
│       └── js/app.js
├── requirements.txt
├── Dockerfile
├── .gitignore
└── README.md
```

## Notes

- Container CPU/memory percentages are surfaced by the backend when available;
  values above ~80% render as "high" (red) for quick scanning.
- The app is intentionally dependency-light: no DB, no build step, no config
  files to manage. Edit env vars to tune it.