SunetMC

SunetMC is a self-hosted Minecraft server management panel. It wraps the excellent itzg/minecraft-server Docker image in a polished web interface that anyone — from admins to players — can use.

Version: 0.0.1 · Image: git.sunet.uk/malasaur/sunetmc:0.0.1

---

Features

Area	What's included
Users	Admins, Server Owners (with RAM/CPU/storage limits), Operators, Players
Servers	Full lifecycle management via Docker Compose — create, start, stop, restart, delete
Console	Live streaming console over WebSocket, send commands, command history
Mods	Modrinth search & install, direct URLs, datapacks, Packwiz support
Modpacks	Modrinth modpack picker, exclude specific mods, custom .mrpack URL
Whitelist	Public / Minecraft whitelist / SunetMC whitelist with invite link flow
OIDC	Multiple IdP support, auto-provision, auto-takeover, group → role mapping
Admin panel	User management, running server overview, OIDC config, app settings
API	Full RESTful API + interactive Swagger UI at /api/docs

---

Quick start

# 1. Copy docker-compose.yml to your server
# 2. Edit SUNETMC_SECRET_KEY
docker compose up -d

# Open http://localhost:8000
# Default credentials: admin / admin  ← change immediately!

Or build locally:

docker build -t git.sunet.uk/malasaur/sunetmc:0.0.1 .
docker compose up -d

---

Development setup

Requirements

• Python 3.12+
• Node 20+
• Docker + Docker Compose plugin

Backend

cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend

cd frontend
npm install
npm run dev      # Vite dev server on :5173, proxies /api → :8000

---

Configuration

All settings use the SUNETMC_ prefix (or a .env file in the backend directory).

Variable	Default	Description
SUNETMC_SECRET_KEY	change-me	JWT signing secret — change this!
SUNETMC_DATABASE_URL	SQLite /data/sunetmc.db	SQLAlchemy connection string
SUNETMC_SERVERS_PATH	/servers	Root directory for Minecraft server folders
SUNETMC_BASE_URL	http://localhost:8000	Public URL (used in OIDC callbacks + invites)
SUNETMC_ALLOW_REGISTRATION	true	Allow username/password sign-up
SUNETMC_STATIC_DIR	/app/static	Path to the built frontend assets

---

Architecture

Monorepo layout

backend/     Python 3.12 + FastAPI — API, models, services, WebSocket
frontend/    Vite + React 18 + TypeScript + ShadCN UI
docs/        API reference and deployment notes
Dockerfile   Multi-stage build (Node → Python slim)
docker-compose.yml  Deployment configuration

Backend highlights

• FastAPI with async SQLAlchemy (aiosqlite / SQLite by default)
• Server Options DSL (app/core/server_options.py) — every Minecraft setting is a ServerOptionDef dataclass. Adding a new option is a single line; compose generation, API schema, and UI all update automatically.
• Docker service wraps docker compose CLI for container lifecycle and log streaming
• WebSocket console streams docker compose logs -f in real time
• OIDC service implements full authorization_code flow with group → role mapping

Frontend highlights

• ShadCN UI with a custom Minecraft-inspired dark theme (forest green + Minecraft gold)
• Server creation wizard — 7-step form with live slug preview, RAM constraint enforcement, and automatic Java version recommendation
• ConsoleViewer — WebSocket-driven, ANSI color rendering, command history (↑/↓), auto-scroll
• ModPicker — Modrinth search with debounce, infinite scroll, version type filter
• Admin panel — full OIDC provider management including callback URL display + copy

---

API

Interactive docs: /api/docs (Swagger UI) · /api/redoc

Manual reference: docs/API.md

The WebSocket console endpoint:

ws://host/api/servers/{id}/console?token=<access_token>

Send {"type":"command","data":"say hello"}, receive {"type":"log","data":"..."}.

---

Contributing

1. Branch off master.
2. Keep commits small and descriptive (see existing history for style).
3. Validate before pushing:

   python3 -m py_compile $(find backend/app -name '*.py')
   cd frontend && npm run build
   

4. Update docs/API.md for any endpoint changes.

---

Notes

• Requires Docker socket access (/var/run/docker.sock) to manage Minecraft containers.
• Each server lives in its own directory under SUNETMC_SERVERS_PATH with a generated docker-compose.yml.
• The project is structured as a monorepo to support a future Android client.
• Default admin password (admin) must be changed before any public exposure.