Installation
This page explains how to install Felis on a Linux host: choose a release channel, run the install command, complete the setup wizard, create the first Owner and check the result. It is written for the operators who deploy the host.
Development snapshots only
Only development snapshots are available; public releases have been withdrawn. Install them only on isolated test hosts, never in production.
Before you begin
Make sure that:
- The host runs a supported Linux distribution and architecture and meets the resource requirements. See Supported hosts and Sizing.
- You have root access or can run
sudo. - The host has a fixed IPv4 address (a static address or a DHCP reservation) and can reach the download sources over HTTPS. See Network.
- If you use your own domain,
<root>,console.<root>,op.console.<root>and*.<root>all resolve to the host. The wildcard record does not cover the third-level nameop.console.<root>, so give it its own record. Without a domain, the installer uses<host-address>.nip.io, or<public-address>.nip.ioon a cloud host whose own address is private. See Public address.
Before it changes anything, the installer runs its preflight checks. If any check fails, it lists every problem at once and exits, leaving the host unchanged. The checks are listed under Preflight checks.
Release channels
The installer chooses its source with FELIS_VERSION_BOOTSTRAP:
| Channel | Value | Source |
|---|---|---|
| Release | release (default) | Downloads the assets of the newest release: the felis binary (panel included), every image and the Velocity plugin, each verified against SHA256SUMS before use. The host needs neither Docker nor access to Docker Hub. If an asset is missing or fails verification, only that piece is built on the host, and the installer prints a notice. |
| Development | dev | Follows the main branch: clones the source and builds it on the host. The installer installs Docker for the build and stops it once the images are in the in-cluster registry. |
These variables select a version more precisely:
FELIS_REF=<branch, tag or commit>: builds that version from source. It takes precedence over the channel.FELIS_RELEASE=<tag>: on the release channel, installs an earlier published release instead of the newest, for example to roll back. Use the installer script of the same tag.
INFO
Only development snapshots exist at present, so select the dev channel explicitly.
Install
Sign in to the host as a user with sudo rights.
Run the install command (development channel):
bashcurl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/main/deploy/bootstrap.sh | sudo FELIS_VERSION_BOOTSTRAP=dev bashWhen the installer asks what to install, choose
[1] Felis, the full control plane (a fresh standard installation on an interactive terminal also asks whether to start the lobby server now, defaulting to off, which can be changed later in the panel).[2] Felis-nanoinstalls login control only, for a Velocity network whose servers you manage yourself; see Felis-nano.Wait for the installation to finish. After printing its summary, the installer starts the setup wizard when it runs on an interactive terminal. See Setup wizard.
sudo resets the environment. Put installer variables between sudo and bash, or export them and run sudo -E bash:
curl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/main/deploy/bootstrap.sh | sudo FELIS_VERSION_BOOTSTRAP=dev FELIS_ROOT_DOMAIN=mc.example.com bashThe install command can be run again. A rerun converges the host to the desired state, and the generated secrets kept in /etc/felis/secrets.env are reused. A rerun keeps the installed root domain. The release channel, the game port, the panel port and the world cleanup directory are recorded in /etc/felis/install.env; reruns and updates started from the panel reuse them, and a variable set explicitly for a run replaces the recorded value. For upgrades, see Upgrading.
Common installer variables
| Variable | Default | Description |
|---|---|---|
FELIS_VERSION_BOOTSTRAP | release | Release channel: release or dev. Recorded for later runs. |
FELIS_REF | empty | Builds the named branch, tag or commit from source. |
FELIS_RELEASE | newest release | Installs the named release. |
FELIS_ARTIFACT_DIR | empty | Installs release assets from a local directory. See Installing from downloaded release assets. |
FELIS_INSTALL_MODE | interactive prompt | Installation type: full or nano. |
FELIS_NO_SETUP | empty | 1 ends the installation without starting the setup wizard. |
FELIS_ROOT_DOMAIN | <host-address>.nip.io; <public-address>.nip.io on a cloud host | Root domain, applied on the first installation only. To change it later, see Changing the root domain. |
FELIS_PUBLIC_IP | Looked up when needed | Public IPv4 address given to players and browsers: in the default root domain, the panel certificate and the addresses the installer prints. When empty and the host's own address is private, the installer looks the address up over HTTPS; none keeps the host's own address. See Public address. |
FELIS_PANEL_NODEPORT | 30443 | Local HTTPS port of the panel and API. Recorded for later runs. |
FELIS_GAME_PORT | 25565 | Port on which the game proxy accepts players. Recorded for later runs. |
FELIS_PREFLIGHT | strict | warn reports preflight problems as warnings and installs anyway. |
FELIS_WORLDS_HOST_PATH | empty | Node directory that holds the world volumes (/var/lib/rancher/k3s/storage on k3s). Setting it enables idle world cleanup. Recorded for later runs; an empty value set explicitly turns cleanup off again. See World cleanup. |
FELIS_VELOCITY_XMX | 1G, 256M on the small-host profile | Maximum heap of the game proxy, at least 256M. |
FELIS_HOST_PROFILE | auto | Host profile: auto, small or standard (Small hosts). |
FELIS_WITH_LOBBY | auto | Whether to enable the lobby at install time: auto (off by default on fresh installs, asks on an interactive standard install; reruns keep the recorded choice), 0 or 1. Can be changed later under Player entry policy. |
FELIS_DB_BACKUP_TIME | *-*-* 03:30:00 | Time of the daily database backup, as a systemd calendar expression. |
FELIS_DB_BACKUP_KEEP | 14 | Number of daily database backups kept. |
FELIS_OFFSITE_BUCKET, FELIS_OFFSITE_ENDPOINT | empty | Bucket and endpoint of the off-site copy, together with FELIS_OFFSITE_ACCESS_KEY and FELIS_OFFSITE_SECRET_KEY. Setting them enables the off-site copy. See Off-site copy. |
FELIS_WATCHDOG_HEARTBEAT_URL | empty | Heartbeat URL of an external monitoring service. See External heartbeat. |
FELIS_RESTORE_FROM_OFFSITE | 0 | 1 rebuilds this host from the old installation's off-site copy once it is installed. See Rebuilding a host. |
The database backup schedule and the game proxy heap, when changed in the panel, are kept in /etc/felis/host-settings.env and serve as defaults for later installer runs; a variable set explicitly for a run takes precedence. For the full list of variables, see Installer variables.
What gets installed
A full installation sets up these components on the host:
- A single-node k3s cluster running PostgreSQL (
felis-postgres, with its data in/var/lib/felis/postgres), the Felis API, the operator and the in-cluster registry. - The game proxy (Velocity), which runs on the host as the systemd service
felis-velocityon a Temurin JRE the installer downloads, and listens on game port 25565. - Two system servers, the login space (
login) and the lobby (lobby), created by the setup wizard (lobbyis created stopped when left off at install time; the small-host profile creates the login space only). - The host node operations service
felis-node-control.service, through which the panel runs host operations. - systemd timers: the daily database backup (
felis-db-backup.timer), the watchdog check (felis-watchdog.timer, every 2 minutes), the version check (felis-update-check.timer, daily) and, once configured, the off-site copy (felis-offsite.timer, hourly). - Rules that open the required ports in an active host firewall (firewalld or ufw), NTP time synchronization, and a persistent system journal (capped at 1G by default).
On hosts with little memory, the installer also creates a swap file. The admin kubeconfig /etc/rancher/k3s/k3s.yaml is readable by root only; use sudo k3s kubectl to reach the cluster. For what each component does and where its data lives, see Operations overview.
Setup wizard
The setup wizard, felis setup, configures how the panel is reached and the mail relay, and creates the first Owner. The installer starts it automatically only on an interactive terminal. When the output goes to a log file or the installation runs under cloud-init, run it after the installation finishes:
sudo felis setupWith FELIS_NO_SETUP=1, the installer ends after its summary.
The wizard runs these steps in order; you can review completed steps with the arrow keys:
| Step | Purpose |
|---|---|
| Preflight | Confirms that the control plane is ready. |
| Connection | Chooses how the panel is reached. See Access method. |
| Configures the mail relay (SMTP). The step can be skipped. See Mail. | |
| Panel login | Creates the Owner account and a one-time setup link. See Creating the first Owner. |
When the wizard finishes, it creates the login space and the lobby (kept stopped when left off at install time). A failure of either does not block panel initialization; you can investigate it from the panel.
Access method
| Option | Description |
|---|---|
| Local only | Installs nothing more. The panel is reached at the host's address and the panel port. |
| Cloudflare Tunnel + Access | Creates a Cloudflare tunnel, routes the hostnames, puts Cloudflare Access in front of the admin console, and then closes the panel port to the public. You authorize cloudflared in a browser and supply an API token that can edit Access applications. |
| Reverse proxy | Your own reverse proxy (for example Caddy, nginx or Traefik) terminates TLS; the wizard prints the proxy configuration guide. |
When the host moves off Cloudflare Tunnel, the wizard stops the tunnel and reopens the panel port; with Local only, the panel addresses shown in game carry the panel port. During the first installation, pressing Esc at this step selects Local only; when you choose the access method again with n on the summary screen, Esc returns to the summary and leaves the access method unchanged. With Local only or a reverse proxy, the admin console is protected by the Owner's sign-in alone (passkey or email code); Cloudflare Access adds an edge check in front of it. You can change the access method later in the panel under Platform settings → Access and security → Access and domain. See Access methods.
Mail
Felis sends email sign-in codes, the Owner's email verification, account recovery codes and alerts through an SMTP relay. Enter the relay host, port, sender address and, when the relay requires it, a username and password. The password is stored in a Kubernetes Secret. Before saving, the wizard sends one test message to the sender address, and it saves nothing unless that message is delivered.
Press Esc to skip the step. Without mail, Felis sends no email codes and no alerts, and the Owner must create a passkey, which requires a trusted certificate. You can configure mail later with e on the summary screen of sudo felis setup, or under Platform settings → Notifications and retention → Mail delivery.
Upload storage
The build contexts of modpacks that players submit are stored on this host's disk by default, which suits a single-node installation. To use an S3-compatible bucket instead (for example AWS S3, MinIO or Cloudflare R2), press s on the summary screen and enter the endpoint, bucket, optional region and access keys; the keys are stored in a Kubernetes Secret. Esc on that screen leaves the current location unchanged.
You can also change the location under Platform settings → Access and security → Upload storage. See Upload storage.
Creating the first Owner
- At the Panel login step, the wizard creates the Owner account (passwordless) and prints a one-time setup link in the terminal. The link is valid for 30 minutes.
- Open the link in a browser.
- Complete the sign-in setup:
- With mail delivery configured, enter an email address, select Send code, enter the code from the email and select Verify and finish. A passkey can be added later on the Account page.
- Without mail delivery, enter an email address and select Save & continue, then select Create passkey and register a passkey with a fingerprint, face recognition or device PIN.
- You enter the operator console. Minecraft is not needed at any point.
You can link a Minecraft profile later on the Account page. See Account linking.
If the link has expired or the browser setup is unfinished, run sudo felis setup again for a new link; accounts that already have a sign-in method are never reset. Once the Owner exists, running sudo felis setup again lets you change the mail relay, the access method and upload storage. If no Owner can sign in, see Emergency access.
TIP
Passkeys are bound to the panel hostname, and browsers create them only under a trusted certificate. When the panel is opened by IP address or with the installer's default self-signed certificate, no passkey can be created: configure mail delivery and finish setup with an email code, or serve a trusted certificate through a reverse proxy or Cloudflare Tunnel. See Access methods.
Installing from downloaded release assets
When the host cannot download GitHub release assets, download them on another machine, copy them to the host and install with FELIS_ARTIFACT_DIR. The Felis binary, images and plugin are then read from that directory; the installer neither downloads nor builds them.
On a machine with access to GitHub, download the release assets for the host's architecture:
bashgh release download <tag> --repo FelisMC/Felis --dir felis-<tag> \ --pattern 'felis-*linux-amd64*' --pattern felis-velocity.jar --pattern SHA256SUMSFor an ARM64 host, replace
amd64witharm64.SHA256SUMSlists both architectures; the files of the other architecture may be left out.Download the installer script of the same tag from
https://raw.githubusercontent.com/FelisMC/Felis/<tag>/deploy/bootstrap.sh.Copy the asset directory and the script to the host, for example to
/root/felis-<tag>.On the host, run the installer with the absolute path of the asset directory:
bashsudo FELIS_ARTIFACT_DIR=/root/felis-<tag> bash bootstrap.sh
If an asset is missing from the directory or fails verification, the installation stops. FELIS_ARTIFACT_DIR cannot be combined with FELIS_REF or FELIS_SKIP_FETCH.
The rest of the host's software is still downloaded: k3s and its images, the JRE, cloudflared, Velocity and the Via plugins come from GitHub and PaperMC; hosts of the Red Hat and SUSE families with SELinux enabled also install k3s-selinux from rpm.rancher.io; system packages come from the distribution's repositories. A host with restricted outbound access must allow HTTPS to these addresses or set https_proxy. Fully offline installation is not supported yet. For the address list, see Network.
Checking the installation
After installation and setup, confirm that Felis is running:
Show the overall status. The command summarizes the node, control plane, game proxy, each server, backups and open alerts:
bashsudo felis statusRun the health check. The command lists problems by area with pointers for investigation, and sends no email:
bashsudo felis doctorConfirm that the control-plane pods are
Runningand the game proxy service is active:bashsudo k3s kubectl -n felis get pods sudo systemctl status felis-velocityOpen the operator console in a browser and sign in as the Owner with your passkey.
Connect to the game address with Minecraft Java Edition and confirm that you arrive in the login space. Follow the proxy log with
sudo journalctl -u felis-velocity -f.
After installation, Felis is reached at these addresses:
| Purpose | Address |
|---|---|
| Operator console (Owner, Admin) | https://op.console.<root>; with Local only, https://op.console.<root>:30443 |
| Player console | https://console.<root>; with Local only, https://console.<root>:30443 |
| Direct access by IP | https://<address the installer prints>:30443, with a self-signed certificate the browser asks you to confirm on the first visit; passkeys cannot be used here |
| Game address | <public-address>:25565; point mc.<root> at it. Each server is reached at <subdomain>.<root> |
The Account page shows the join address and the Minecraft Java Edition client version that the login space and the lobby require. The installer records the version it built in [velocity].game_version of felis.toml; custom login space or lobby images must set it themselves, otherwise the panel reports the version as not configured.
If something is wrong, see Troubleshooting.
Next steps
- If you skipped the Mail step, configure mail delivery under Platform settings → Notifications and retention → Mail delivery, for sign-in codes and alerts. See Platform settings.
- Configure the off-site copy so that backups are kept away from the host. See Off-site copy.
- Set up authentication sources and the player entry policy. See Authentication sources and Player entry policy.
- Create your first server. See Creating a server.