Fabricator

Self-hosted web dashboard for managing Minecraft servers.

Website | Documentation

---

---

Features & Roadmap

	Feature	Status
🧩	Loaders: Fabric, Quilt, NeoForge, Forge, Paper, Purpur, Folia, Pufferfish, Vanilla	✅ Available
📦	Mod & plugin management: install, remove, and browse Modrinth mods and plugins	✅ Available
📋	Logs & monitoring: live log stream, TPS and RAM graphs	✅ Available
👥	Player management: online players, player heads, custom actions	✅ Available
💾	Backups & restore: manual snapshots, restore from any backup	✅ Available
🌍	World import: upload a world archive and swap it in	✅ Available
🖥️	Multiple servers: manage several instances from one dashboard	✅ Available
▶️	Auto-start: always, never, or last-state restore	✅ Available
☕	Managed Java runtimes: downloaded and pinned per server	✅ Available
🌐	playit.gg tunnels: public access without port forwarding	✅ Available
🐳	Docker: single multi-arch (amd64/arm64) image, runs non-root	✅ Available
⌨️	CLI (fabricator): status, start/stop, update, version, uninstall	✅ Available
⬆️	Self-update: from the web UI, or via the CLI or install script	✅ Available
⌨️	CLI: expanded server and mod management commands	📋 Planned
⏰	Scheduled commands	📋 Planned
🔄	One-click Minecraft / Fabric server upgrades	📋 Planned
📊	Metrics tab: CPU, RAM, and usage over time	📋 Planned
🔐	User roles and permissions	📋 Planned
✏️	Editor & files: better text editor, view archived logs	📋 Planned
📥	More install targets: Proxmox VE, CasaOS, Umbrel, Unraid, Coolify/Dokploy	📋 Planned

---

Quick Start

Docker (recommended)

A single multi-arch image is published to GHCR for every release. It runs as a non-root user and keeps all state on one /data volume.

# Grab the compose file and start
curl -fsSL https://raw.githubusercontent.com/philderks/Fabricator/main/docker-compose.yml -o docker-compose.yml
docker compose up -d

The packaged docker-compose.yml publishes the panel to host loopback only (127.0.0.1:5000). On first use you'll be prompted to create the operator password. Minecraft server ports aren't published by default; use the built-in playit.gg tunnel, or map each server's port explicitly (e.g. 25565:25565).

To update, pull the new image and recreate the container — your data persists in the named volume:

docker compose pull && docker compose up -d

Docker is the simplest way to run Fabricator on Linux, macOS, or Windows (via Docker Desktop / WSL2).

One-line installer

The script downloads a release tarball from GitHub Releases, installs dependencies, creates a fabricator user and systemd unit, and starts the app. Supported distros: Debian/Ubuntu (and derivatives), Arch, Fedora/RHEL family. systemd and curl are required.

curl -fsSL https://fabricator.site/install.sh | bash

By default this installs the latest published release.

Updating. The easiest way is from the panel itself: Fabricator checks GitHub Releases and you can update from the sidebar. You can also re-run the installer, which detects an existing install and updates in place (backing up servers.json and fabricator.env, keeping your data under /var/lib/fabricator):

curl -fsSL https://fabricator.site/install.sh | bash

Or update from the CLI:

fabricator update

After install, open http://<host>:5000 (the default packaged config binds to all interfaces — use a firewall or reverse proxy if the host is reachable from untrusted networks).

For local development, the app defaults to loopback-only; see .env.example.

Manual installation

# Clone
git clone https://github.com/philderks/Fabricator.git
cd Fabricator

# Backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Frontend
cd frontend
npm install
npm run build
cd ..

# Run (development — serves API + built frontend from frontend/dist)
python3 run.py

Environment variables are documented in .env.example. For production-like paths, set FLASK_ENV=production, SERVER_ROOT, and SERVER_INDEX_FILE (see Configuration).

---

Requirements

	Requirement
Docker	Any OS with Docker Engine or Docker Desktop (recommended path)
OS	Linux (Debian/Ubuntu, Arch, or Fedora/RHEL, systemd) for the native installer
Python	3.11+ (manual/native install)
Node.js	20.x (frontend build only)

The native installer targets Linux. On macOS and Windows, run Fabricator via Docker.

---

Configuration

With Docker, set these as environment: entries in docker-compose.yml; the image already pins every data path onto the /data volume. For the native install, the installer writes /etc/fabricator/fabricator.env (group fabricator, mode 0640). Common variables:

# Listen address — packaged default is all interfaces; use a reverse proxy in production
HOST=0.0.0.0
PORT=5000
FLASK_ENV=production

# Server instances and index (paths must be writable by the fabricator user)
SERVER_ROOT=/var/lib/fabricator/servers
SERVER_INDEX_FILE=/var/lib/fabricator/servers.json

# Optional: comma-separated origins for a separate dev UI or external frontends (no *)
# CORS_ORIGINS=https://dashboard.example.com

# playit.gg tunnel agent — set to "true" to start the agent automatically on boot.
# The agent creates a public tunnel so the server is reachable without port-forwarding.
PLAYIT_ENABLED=false

The playit.gg tunnel makes a server reachable without port forwarding. The installer provisions the pinned, sha256-verified playit and playit-cli binaries automatically — no separate step. Turn the tunnel on per server under Server → Settings → Network (or Overview → Public access), which walks you through the one-time playit.gg account claim. Set PLAYIT_ENABLED=true above only if you want it to auto-start on boot.

Managed Java runtimes are stored under /var/lib/fabricator/java by default when FLASK_ENV=production.

After editing, restart the service:

sudo systemctl restart fabricator

Filesystem layout

/opt/fabricator/app              # Application code (fabricator:fabricator)
/opt/fabricator/venv             # Python virtualenv (fabricator:fabricator)
/var/lib/fabricator              # Server data, backups, managed Java
/etc/fabricator/fabricator.env   # Config (root:fabricator, 0640)
/etc/systemd/system/fabricator.service

Authentication

The management panel requires a login by default. On first boot (no credential configured yet) it starts in a locked setup mode: open the panel and you'll be taken to a one-time page to create the operator password — in the browser, the same on Linux and Docker (no terminal needed). Until a password is set, only that page is reachable.

The session signing key is generated and persisted automatically on first boot; the password is stored, hashed, in a 0600 auth.json in the data directory next to servers.json (/var/lib/fabricator under systemd, /data in Docker).

Advanced / declarative setup. You can skip the setup page by providing the credential up front — useful for Docker/automation and recommended on untrusted networks (see the security note):

1. Optionally pin SECRET_KEY to a fixed value (otherwise auto-generated): python -c "import secrets; print(secrets.token_hex(32))"
2. Generate a password hash and set FABRICATOR_AUTH_PASSWORD_HASH:
   • systemd install: fabricator hash-password
   • Docker / source: python -m backend.auth hash

Precedence: env hash > persisted file > setup mode (and for the signing key: env > file > auto-generated).

To run without the built-in login (only if you front Fabricator with your own reverse-proxy authentication), set FABRICATOR_DISABLE_AUTH=1. This is the only supported way to disable it.

Change or reset the password. Once logged in, change it from the panel header (Change password). Forgot it / locked out? Delete auth.json from the data directory and restart — the app drops back into setup mode so you can set a new one. The file lives next to servers.json: /var/lib/fabricator/auth.json under systemd, /data/auth.json in Docker. (Deleting it only resets the password/key; your servers are untouched.)

Security note (trust-on-first-use). The first-boot setup page is reachable by anyone who can reach the panel until the password is set. On an untrusted network, set FABRICATOR_AUTH_PASSWORD_HASH before first exposure instead of relying on the open setup page.

When Fabricator is served behind TLS, also set FABRICATOR_SESSION_COOKIE_SECURE=1 so the session cookie carries the Secure flag.

---

CLI

The native (systemd) install ships a fabricator command for managing the service from the shell:

fabricator status            # systemd state + Flask/Minecraft API reachability (--json available)
fabricator start | stop      # control the systemd service
fabricator update            # update to the latest GitHub release (runs the installer)
fabricator version           # show the installed version
fabricator hash-password     # generate a password hash for FABRICATOR_AUTH_PASSWORD_HASH
fabricator uninstall         # remove app, data, config, systemd unit, and service user
fabricator help              # list all commands

The read commands (status, version, help) accept --json for scripting. The CLI is currently minimal and will grow to cover server and mod management.

---

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for development setup and guidelines. For larger changes, open an issue first.

---

License

AGPL-3.0