Skip to content

README.md

Latest commit

 

History

History
271 lines (194 loc) · 10.9 KB

README.md

File metadata and controls

271 lines (194 loc) · 10.9 KB
Raw
Fabricator Logo

Fabricator

Self-hosted web dashboard for managing Minecraft servers.

License: AGPL-3.0 Stars Platform Docker

Website | Documentation

Overview

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