JARVIS web UI

The dashboard for jarvis-bot: sign in with Discord, manage your reminders and data, and manage the servers you look after. It runs alongside the bot and jarvis-tasks against the same MongoDB.

The design and roadmap are in docs/PLAN.md.

Versions

jarvis-bot, jarvis-tasks, jarvis-core and jarvis-webui share a version number: 3.x of each work with 3.x of the others.

What it does today

Public	Landing page with the invite link, features, privacy policy and terms (rendered from PRIVACY.md / TERMS.md)
Sign in	Discord OAuth2 (identify guilds); the access token is dropped right after sign-in
You	Servers you share with the bot, edit and delete your reminders, delete your data
Server managers	Settings (log channels, reports, verified roles, invites, mass-mention, notifications, ignored channels, lockdown exclusions), escalation rules
Moderators	Action log (bans, warnings, mutes, kicks, unbans); warn, kick, mute, unmute, ban and unban from the Actions page, carried out by the bot

Actions are queued in MongoDB (web_requests) and the bot carries them out within a couple of seconds, so the web UI needs the matching bot version running. Not built yet: cases, filters, tags, rolegiver, pinboards, temp roles, purge, lock and role menus. See the phases in the plan.

Run it

Add the service from compose.example.yaml to the compose file that already runs bot and tasks; it uses the same .env and MongoDB.

1. In the Discord developer portal, open the bot's application, go to OAuth2 and add <WEBUI_PUBLIC_URL>/callback as a redirect. Copy the client secret.

2. Put these in .env (see sample.env):

   Variable
   WEBUI_CLIENT_ID	The application ID of the bot. Use the dev bot's in the dev deployment and the prod bot's in prod
   WEBUI_CLIENT_SECRET	The OAuth2 client secret
   TOKEN	The bot token (lookups only)
   WEBUI_PUBLIC_URL	Where users reach the site, e.g. https://jarvis.example.com
   WEBUI_INVITE_PERMISSIONS	Optional. Leave blank and the invite link uses the application's Default Install Settings from the developer portal; set an integer to override
   WEBUI_OFFLINE	Optional. true shows "Systems Offline, Waiting for Initialization" (HTTP 503) on every page except /healthz, without touching MongoDB or Discord
   WEBUI_SESSION_DAYS	Optional, default 7
   WEBUI_SOURCE_URL	Optional. Where the footer's "Source code" link goes (default: this repository)
   MONGO_*, ENVIRONMENT	Same as the bot (ENVIRONMENT=develop uses jarvis_dev)

   Run one instance per bot (dev and prod), each with its own client ID, secret, token, URL and database.

3. docker compose up -d webui. It listens on port 8080; put a TLS-terminating reverse proxy in front of it. /healthz answers ok.

The image runs as a non-root user and needs no writable disk.

Develop

uv sync
cp sample.env .env   # fill it in
uv run python run.py

Tests use a real MongoDB and a fake Discord:

JARVIS_TEST_MONGO_URI=mongodb://localhost:27017 uv run pytest

Every collection in the test database is dropped, so give it a database of its own (JARVIS_TEST_MONGO_DB).

Layout

Path
webui/app.py	Application factory, security headers, error pages
webui/auth.py	Sign in and out
webui/deps.py, webui/perms.py	Sessions, CSRF, and working out what someone may do in a server
webui/discord.py	Small Discord REST client with caching
webui/routes/	Pages
webui/templates/, webui/static/	The HUD theme (htmx and fonts are vendored; nothing loads from third parties)