Felis

A Kubernetes-driven Minecraft server hosting platform
One command to deploy, with automatic lifecycle, backup, and security

简体中文 | English
Website | Documentation

Caution

THIS PROJECT IS STILL WIP, YOU SHOULD DO NOT USE THIS PROJECT IN ANY PRODUCTION USAGE. WE ARE NOT RESPOND FOR ANY LEGAL OR HUMANLY PROBLEM.

Table of Contents

• Features
• Getting Started
• Build from Source
• License
• Acknowledgements

Features

• On-demand Start and Stop: A server starts when a player connects to the proxy. The player waits in a queue during start-up and is transferred once the server is ready. Idle servers stop automatically to free memory.

• Web Dashboard: Monitor server status, online players, and resource usage from your browser.

  • Console (RCON), whitelist, bans, OPs and LuckPerms permissions
  • File manager: create, delete, rename, chunked upload, download, and unzip while the server is stopped; also used to import worlds
  • Schedules: run commands, restart, stop, start or back up by weekday and time zone, with an in-game warning to players beforehand

• Backup & Restore: Enabled by default; the installer renders the archive PVC and its path.

  • Manual backups: archive a server's entire data volume (/data, including worlds, configuration, plugins and mods) to the cluster's archive store, with rollback to any backup point
  • Daily restore points: a server played that day gets a restore point once it stops; by default 7 are kept for up to 90 days, rotated separately from manual backups
  • Download and export: download a single backup (with sha256 verification), delete a single backup, or export a whole world
  • Off-site copy (optional): backups are encrypted on the host and synced to S3-compatible storage (AWS S3, Cloudflare R2, Backblaze B2, MinIO and others)
  • Control-plane database: the database holding accounts, server ownership, quotas and the archive index is backed up daily and snapshotted before every upgrade migration; felis db restore rolls it back atomically, and the panel's Maintenance & Backups page shows the age of the latest backup (see troubleshooting §16)

• Diagnostics

  • sudo felis status: a summary of the node, control plane, game proxy, each server, backups and open alerts
  • sudo felis doctor: runs all health checks and lists problems by area with troubleshooting pointers; sends no email
  • sudo felis support-bundle: generates a redacted diagnostics archive to attach to support requests (see troubleshooting §0)
  • Watchdog: runs a check every 2 minutes and emails the platform owners when a problem persists; supports an external heartbeat monitor

• World Reaper (optional): Worlds idle for more than 15 days are backed up and then removed to free disk space. Enable it by setting FELIS_WORLDS_HOST_PATH at install time (on k3s: /var/lib/rancher/k3s/storage); without it, no world is deleted. Expired backups are cleaned up daily regardless of this setting.

• Multi-core Support: Compatible with Paper, Fabric, Forge, and NeoForge, accessed through a single Velocity proxy.

• Modpack Submission: Players can upload modpacks. After admin approval, each modpack is built automatically and scanned with Trivy; the result is added to the image whitelist and can be selected as a server image.

• Security

  • Passkey login: passwordless authentication via fingerprint, face recognition, or hardware security keys
  • Zero-trust access: panel traffic is protected by Cloudflare Access, and the internal API is not exposed to the internet

• Multi-node Deployment (experimental, off by default): a single controller node issues all commands, the other nodes run game servers only, and a stopped server can be migrated to another node. Currently available only on the main branch; three-node acceptance testing is not yet complete (see distributed mode, in Chinese).

Getting Started

On a prepared Linux host, run:

curl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/main/deploy/bootstrap.sh | sudo bash

The script installs K3s, deploys PostgreSQL and the control plane inside it, and launches a setup wizard. When setup completes, open the configured domain in a browser to reach the control panel.

• Setup wizard: Configure panel access and storage first. The host administrator then initializes the first Owner and receives a one-time browser setup link (valid for 30 minutes). Open it, record an email, and create a passkey to enter the panel; Minecraft is not required. Later, link a game role from Account by selecting an authentication source, entering a role name or UUID, and confirming it. Players retain the in-game bind-code flow. Rerun sudo felis setup if login setup is unfinished or the link expires; accounts with an established login factor are never reset. Login/lobby failures do not block panel initialization. Account explains Yggdrasil authentication and shows the join address and Java client version for the login/lobby servers. Bootstrap records the built protocol in [velocity].game_version; set it yourself for custom images, otherwise the panel reports it as unknown. Standard Yggdrasil endpoints support role lookup directly; sources with a nonstandard hasJoined path can set [[auth_source]].api_url to their API root, with game-code linking still available as a fallback. The installer launches the wizard automatically only on an interactive terminal; when output is redirected to a log or the install runs under cloud-init, run sudo felis setup after it finishes. Setting FELIS_NO_SETUP=1 makes the installer end at its summary.

• Supported hosts: CentOS Stream 9 (aarch64) is verified on physical hardware; Ubuntu 24.04 (x86_64) is tested in CI on every push with a fresh install, a rerun, an upgrade and the install command above (see operations §1).

• Preflight checks: Before modifying the host, the installer checks memory, disk, ports, network range conflicts, existing Kubernetes installations and outbound connectivity. If any check fails, it lists all problems and exits, leaving the host unchanged (see operations §1 for the checks).

• Upgrading: Rerun the install command to upgrade felis-api to a newer version; felis setup only uses the binary already installed on the host and cannot upgrade it. A rerun keeps the installed root domain, and the release channel must be specified again: hosts that follow the main branch must also set export FELIS_VERSION_BOOTSTRAP=dev. A PostgreSQL instance installed on the host by an earlier release is migrated into K3s during the rerun; the original instance on the host is stopped and retained for rollback (see operations §4).

Installation sources and restricted networks

A release installation takes the binary, all images and the Velocity plugin from the release assets prebuilt in CI, verifying each against SHA256SUMS before import. The host requires no Docker, Gradle or Go, and no access to Docker Hub. If an asset is missing or fails verification, only that image falls back to a local build, and the installer prints a notice (see troubleshooting §15c).

The assets can also be copied to the host in advance and installed with FELIS_ARTIFACT_DIR=<absolute path>; the Felis binary, images and plugin are then read from that directory. k3s and its images, the JRE, cloudflared, Velocity and the Via plugins are still downloaded from GitHub and PaperMC; hosts with SELinux enabled, such as RHEL, Fedora and openSUSE Leap, additionally install k3s-selinux from rpm.rancher.io; system packages come from the distribution's repositories.

A host with restricted outbound access must therefore allow HTTPS to these addresses or set https_proxy. Preflight probes each address before changing the host. Fully offline installation is not yet supported (see operations §1 for the address list).

Build from Source

Felis is built with Go and Node.js:

# Backend (Go 1.26+)
go build -o felis ./cmd/felis

# Frontend (Node.js 22+)
cd panel
npm ci
npm run build

# Docker image
docker build -t felis:custom .

License

This project is licensed under AGPL-3.0-only.

License Notes

1. Derivative works must use AGPL: Any distribution of this project or of software derived from it must be released under AGPL-3.0 and must include the original copyright notice and license statement.
2. Network services must also provide source (AGPL section 13): anyone who offers a modified Felis to others over a network must provide those users with the complete source of the modified version, even without distributing any binary. This is the only substantive difference between AGPL and GPL; as Felis is a hosting platform accessed over a network, this clause applies to virtually every deployment.
3. Disclaimer: This project is provided "as is", without warranty of any kind.

Acknowledgements

• Kubernetes: Container orchestration engine
• K3s: Lightweight Kubernetes distribution
• Cloudflare Zero Trust: Zero trust security infrastructure
• PostgreSQL: Data persistence
• React: User interface framework
• Vite: Frontend build tool
• TailwindCSS: CSS framework
• Bubble Tea: TUI framework
• Minecraft: The game this project serves