Fabricator

Self-hosted web dashboard for managing Minecraft servers.

Website | Documentation | MCP server for AI clients

Features & Roadmap

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.

# 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

Requirements

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

/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.