iowap-server

IOWAP Relay Server — API, Scheduler, Auth, Dashboard, Metrics

The relay server is the central coordinator in the IOWAP ecosystem. Nodes register their capabilities via heartbeat, and the relay matches tasks to capable nodes. It is a purpose-agnostic scheduler — it knows nothing about the work itself, only who can do what.

Features

• Capability Registry — nodes heartbeat their capabilities, relay maintains a live registry
• Task Scheduler — match tasks to capable nodes, claim/release lifecycle with retry
• Auth & Security — token-based node auth, CSRF-protected dashboard, TLS support
• Dashboard — web UI for node overview, task monitoring, capability browsing, metrics
• SSE Events — real-time event stream for connected nodes
• Status System — node/task/stage status registry with valid transitions
• Event Bus — publish/subscribe internal events for monitoring & extensibility
• PostgreSQL + SQLite — production (Postgres) and dev (SQLite) backends
• Docker — docker compose up for one-command deployment
• Observability — /metrics (Prometheus), /ready health checks, structured JSON logs

Quick Start (Linux)

curl -fsSL https://raw.githubusercontent.com/iowap-org/iowap-server/main/install.sh | bash

The installer asks native (systemd) vs. Docker (GHCR image), configures the database (SQLite default, PostgreSQL local/remote) and environment (homelab HTTP / internet TLS), creates the master admin seed, and prints the dashboard login URL.

Docker (manual) — pre-built image on GHCR:

docker volume create relay-data
docker run -d --name iowap-server --restart unless-stopped \
  -p 8788:8788 \
  -e RELAY_MASTER_SEED="$(openssl rand -hex 24)" \
  -e RELAY_SESSION_SECRET="$(openssl rand -base64 32)" \
  -e RELAY_SESSION_COOKIE_SECURE=false \
  -v relay-data:/app/.relay \
  ghcr.io/iowap-org/iowap-server:latest

Compose files live in iowap-org/iowap-docker (server/docker-compose.yml).

Manual (source):

git clone --recursive https://github.com/iowap-org/iowap-server.git
cd iowap-server
pip install -e .            # or: pip install -e ".[postgres]"
relay-server --host 0.0.0.0 --port 8788

Server starts on http://localhost:8788 — the dashboard login is under /relay/v2/dashboard/login (master seed acts as the bootstrap admin until the first human admin exists).

Configuration

See iowap-docs → server/setup.md for full reference.

Architecture

┌──────────┐   heartbeat + capabilities    ┌───────────┐
│  Nodes   │ ◄─────────────────────────►   │   Relay   │
│ (any)    │   claim + complete tasks      │   Server  │
└──────────┘                               └─────┬─────┘
                                                  │
                                          ┌───────┴───────┐
                                          │   Dashboard   │
                                          │  (HTMX/HTML)  │
                                          └───────────────┘

Docs

Full documentation in iowap-org/iowap-docs:

• getting-started.md — first steps
• server/setup.md — full setup guide
• server/docker.md — Docker deployment
• reference/api.md — API reference
• server/dashboard.md — dashboard usage
• server/admin.md — administration

License

MIT — see LICENSE.