Skip to content

Requirements ​

This page is for operators planning a Felis host. It lists the supported operating systems, how much CPU, memory and disk to provide, the ports, network ranges and DNS records Felis uses, the address and clock requirements, and the checks the installer runs before it changes the host. Installation itself is described in Installation.

Supported hosts ​

Felis installs on a single Linux host by default. Spreading game servers over several machines is optional and described in Multi-node and high availability.

The host needs:

  • a 64-bit x86 (x86_64) or ARM (aarch64) processor. 32-bit hosts are not supported;
  • systemd as the init system, with the memory cgroup controller enabled;
  • root access;
  • one of the package managers in the table below.
DistributionPackage managerArchitectures
CentOS Stream 9, RHEL 9, Rocky Linux 9, AlmaLinux 9, Fedoradnfx86_64, aarch64
Ubuntu 24.04 LTS and other Ubuntu releases, Debian 12aptx86_64, aarch64
openSUSE Leap, openSUSE Tumbleweedzypperx86_64, aarch64
Arch Linuxpacmanx86_64, aarch64

CentOS Stream 9 (aarch64, with firewalld active and SELinux enforcing) and Ubuntu 24.04 LTS (x86_64) are the reference platforms. The other distributions use the same installation path.

The installer brings everything else: k3s, the Java runtime for the game proxy, cloudflared, and Docker when an image has to be built on the host. PostgreSQL runs inside k3s as the felis-postgres Deployment, with its data on the host in /var/lib/felis/postgres. A k3s server already installed on the host is reused, and Felis adds its namespaces to that cluster. Another Kubernetes distribution (kubelet, RKE2, k0s, MicroK8s) or a k3s agent on the host is refused. The component versions a fresh installation receives are listed in Component versions.

Sizing ​

What the platform uses ​

Approximate memory use of an idle platform:

ComponentMemory
k3s (API server, controllers, scheduler, kubelet)about 370 MiB
k3s's containerd and the pods' shimsabout 170 MiB
CoreDNS and the local-path volume provisionerabout 105 MiB
Velocity, the game proxy (idle; grows with players)about 175 MiB
felis-api, felis-operator, registry gateabout 85 MiB together
Image registryabout 25 MiB
PostgreSQLabout 40 MiB, plus page cache
Infrastructure totalabout 1 GB

The system servers come on top: the login space (Limbo, pod limit 512 MiB, about 0.16 GB in use) and the optional lobby (Paper, pod limit 1 GiB, about 0.7–0.85 GB in use when enabled). A fresh installation leaves the lobby stopped by default (enable it at install time with FELIS_WITH_LOBBY=1, or at any time afterwards under Player entry policy); the small-host profile has no lobby and limits the login space's pod to 320 MiB. Every game server adds the memory its owner assigned to it: the pod's limit equals its request, and the Java heap is derived from it. Quotas cap the memory per user (Quotas).

A release installation builds nothing on the host. When the installer does build images on the host, its peak is the image builds (Docker and a Gradle container); afterwards it stops Docker, so that memory returns to the servers. On a node without swap, the installer creates a /swapfile as large as physical memory (at least 2 GiB) to hold the memory of hibernated servers; it skips the file when the root filesystem would have less than 10% free after the installation. Existing swap is left as it is, and the installer warns when it is smaller than physical memory. Some cloud images set vm.swappiness to 0, which keeps the kernel from swapping until memory runs out, so the host stalls reclaiming its page cache; when swap is active and the value is 0, the installer restores the kernel default of 60, writes it to /etc/sysctl.d/99-zz-felis-swappiness.conf and reports the change.

Recommendations ​

Concurrent playersGame servers runningCPURAMFELIS_VELOCITY_XMX
up to 201–2 small2 vCPU4 GB + 2 GB swap1G (default)
up to 1003–54 vCPU8–16 GB1G
up to 3005–108 vCPU16–32 GB2G
over 300more8+ vCPU32 GB or more3G–4G

The player counts are planning figures: a Minecraft server's cost depends mostly on what its players do (view distance, redstone, mods). Size RAM as follows: about 1 GB for the infrastructure, about 0.2 GB for the login space (about 1 GB together with the lobby when enabled), plus the sum of the servers expected to run at the same time, then add a quarter for the page cache and PostgreSQL.

Small hosts ​

A host with less than 3.5 GiB of memory gets the small-host profile on its first installation, which lowers the platform's own memory use:

  • No lobby is deployed. Players authenticate in the login space and then enter their destination server directly, waiting in the login space while it starts (Player entry policy);
  • The login space's pod is limited to 320 MiB;
  • The game proxy's heap ceiling defaults to 256M (Game proxy memory);
  • k3s runs without the Helm controller, which Felis does not use, and with a 400 MiB soft limit on its Go heap.

On a "2 GB" cloud host that reports about 1.6 GiB, the idle platform takes about 0.6 GB on the small-host profile and the components shipped with the system image another 0.4 GB, which leaves too little for a Paper server: starting one keeps the host paging, and the platform stops responding. A single-node installation whose host has less than 3.5 GiB of memory therefore runs only the platform: the panel and the API refuse new game servers (error code host_too_small), and existing servers are unaffected. Game servers need a host with at least 4 GB of memory (see Recommendations), or a worker node in a multi-node deployment. The check uses the host's actual memory, whatever the profile: a small-profile host can create servers once it has more memory.

The installer variable FELIS_HOST_PROFILE selects the profile:

ValueBehavior
auto (default)small for a fresh installation with less than 3.5 GiB of memory, otherwise standard. Later runs keep the profile recorded in /etc/felis/host-profile, also after the host gains memory.
smallThe small-host profile. The installer refuses to switch an installation that has a lobby to it.
standardThe standard profile. After a small-host installation is rerun with this value, the lobby can be created under Login & lobby.

Game proxy memory ​

The game proxy (Velocity) needs little memory per player. Its heap ceiling is FELIS_VELOCITY_XMX: default 1G, or 256M on the small-host profile; at least 256M, written as <n>M or <n>G. Raise it when journalctl -u felis-velocity shows long garbage-collection pauses or OutOfMemoryError.

  • In the panel: Platform settings → Access and security → Game proxy, set Heap ceiling (256M to 64G) and select Apply. The value is kept across installer reruns and updates.
  • On the command line: rerun the installer with FELIS_VELOCITY_XMX, for example FELIS_VELOCITY_XMX=2G. The installer reads the variable on every run.

WARNING

Changing the heap ceiling restarts the game proxy, which disconnects every player online. Make the change at a quiet hour.

Disk ​

Provide at least 40 GB of disk, and 60 GB or more once worlds and custom images accumulate. The worlds, world archives, registry, uploads and container images are stored under /var/lib/rancher/k3s and share one filesystem with it; the requested volume sizes are not enforced. To keep this data off the system disk, put /var/lib/rancher/k3s on a disk of its own (Move the data to its own disk).

The space each part takes, and how to grow the disk later, are described in Storage and disks. The free space the installer needs is listed under Preflight checks.

Network ​

Ports ​

PortProtocolPurposeReached from
25565 (FELIS_GAME_PORT)TCPthe game proxy; players connect hereplayers
30443 (FELIS_PANEL_NODEPORT)TCPthe panel and API over HTTPSpanel users, or the reverse proxy in front of the panel; closed to the public when a Cloudflare Tunnel serves the panel
6443TCPthe Kubernetes API (k3s)the host and its pods; the other nodes in a multi-node deployment
6444, 10248–10259TCPk3s's supervisor, kubelet, kube-proxy, controller manager and schedulerthe host itself
5000TCPthe image registry's loopback portthe host itself
15432TCPthe database's loopback portthe host itself

How the panel is reached (directly, through your own reverse proxy, or through Cloudflare Tunnel) is described in Access methods. Network requirements between nodes are described in Isolation and network requirements.

Firewall and network ranges ​

The installer opens the host firewall; it never turns it off.

  • With firewalld active, it opens the panel port, the game port and 6443, and puts k3s's pod and service ranges in the trusted zone.
  • With ufw enabled (common on Ubuntu and Debian), it admits 10.42.0.0/16 and 10.43.0.0/16, the panel port and the game port, each rule commented felis-…. Port 6443 stays closed to the network, because pods reach the API server from their own range.
  • Uninstalling removes these rules again.

Any other firewall in front of the host must admit the same traffic. Dropped pod traffic shows up as the first rollout timing out with control-plane rollout did not complete.

k3s uses 10.42.0.0/16 for pods and 10.43.0.0/16 for services. The host's address and the networks it routes to must lie outside these ranges; a Docker network inside them is the usual conflict. A wider route that covers them, such as a 10.0.0.0/8 VPN, makes hosts in those ranges unreachable from the host, and preflight warns about it.

Outbound access ​

The host needs outbound HTTPS, directly or through https_proxy, to these addresses:

HostWhat comes from it
github.com, and the githubusercontent.com hosts its release downloads redirect toFelis release assets, k3s and its images, cloudflared, the Temurin JRE, ViaVersion, ViaBackwards and ViaRewind
raw.githubusercontent.comk3s's install script, until k3s is installed
rpm.rancher.iok3s-selinux, which k3s's install script adds on an SELinux host of the Red Hat or SUSE family (CentOS Stream, RHEL, Rocky, Alma, Fedora, openSUSE Leap), until k3s is installed
fill-data.papermc.iothe Velocity jar, unless FELIS_VELOCITY_FORK_JAR supplies one
the distribution's package mirrorsbase packages (CA certificates, OpenSSL, curl and tar where missing), and container-selinux beside k3s-selinux
Docker Hubneeded only when images are built on the host

A fully offline installation is not supported. Installing from pre-downloaded release assets removes the download of Felis's own binary and images, while the other software is still downloaded (Installing from pre-downloaded assets). Some installer overrides add download hosts: FELIS_JRE_VERSION reads api.adoptium.net, a FELIS_VELOCITY_VERSION other than the pinned one reads fill.papermc.io, and FELIS_GAME_STACK=latest builds its images on the host from Docker Hub, PaperMC, Limbo's CI and LuckPerms.

Allow outbound UDP 123 for time synchronization (Time synchronization).

DNS ​

Felis serves everything under one root domain, set with FELIS_ROOT_DOMAIN at the first installation. The default is <host-address>.nip.io, or <public-address>.nip.io on a cloud host (Public address), which needs no DNS records of your own. A rerun of the installer keeps the installed domain; felis domain set moves it later (Changing the root domain).

NameUsed for
<name>.<root>each game server, as players address it; with :<port> appended when the game port is not 25565
console.<root>the panel
op.console.<root>the admin console

With a domain of your own, create records that lead to the host for <root>, *.<root>, console.<root> and op.console.<root>. The wildcard does not cover op.console.<root>, a third-level name, so give it its own record. When a Cloudflare Tunnel serves the panel, only <root> and *.<root> need to point at the host. How players join is described in Player access.

Static address ​

An installation is bound to the IPv4 address it was made on: the k3s node, the network policies and the panel certificate carry it, and the default nip.io domain carries it or the public address forwarded to it. Give the host a static address or a DHCP reservation before installing.

  • The installer warns when the address is a DHCP lease.
  • When the host loses its address, the watchdog reports host-address (critical, after 5 minutes). See Troubleshooting.
  • The k3s node name is pinned at installation, so changing the hostname is harmless.

Public address ​

Players and browsers reach the host at its public IPv4 address. On a cloud host, the host's own address is usually private (in 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 100.64.0.0/10), and the provider forwards a public address to it. When the host's own address is private and a cloud provider's metadata service answers, the installer treats the host as a cloud host. It reads the public address from the metadata service (Alibaba Cloud, Tencent Cloud and providers that serve public-ipv4), otherwise looks it up over HTTPS from 1.1.1.1 and, as a fallback, api.ipify.org, and uses it for:

  • the default root domain of a first installation (<public-address>.nip.io);
  • the panel certificate, which names both addresses;
  • the panel and game addresses the installer prints.

The k3s node, the network policies and the firewall rules keep the host's own address. The installer log states which address it uses and why. An installed root domain is always kept.

  • FELIS_PUBLIC_IP=<address> sets the public address without a lookup.
  • FELIS_PUBLIC_IP=none keeps the host's own address without a lookup.
  • A host on a home or office network is not a cloud host, so the installer keeps its own address; when players reach it through a router's port forwarding, name the public address with FELIS_PUBLIC_IP.
  • When the lookup fails, the installer keeps the host's own address and prints a warning.

Time synchronization ​

The host's clock must be kept by NTP. Sign-in codes and sessions expire by it, S3 refuses off-site uploads signed more than 15 minutes off, and certificate checks fail on a clock far off.

  • The installer turns NTP on (timedatectl set-ntp true, installing chrony where no client can be enabled) and waits for the clock to synchronize. Set FELIS_MANAGE_TIME_SYNC=0 on a host whose clock is kept another way.
  • Allow outbound UDP 123; a firewall that drops it keeps the clock unsynchronized.
  • The watchdog reports an unsynchronized clock as clock (warning, after 30 minutes). Check with timedatectl (expect System clock synchronized: yes and NTP service: active) and chronyc sources. See Troubleshooting.

Preflight checks ​

Before it changes anything, the installer checks the host, reports every problem at once, and stops with the host untouched. It checks:

  • Platform: the architecture (x86_64 or aarch64), systemd as init, and the memory cgroup controller k3s needs. On a Raspberry Pi, add cgroup_memory=1 cgroup_enable=memory to /boot/firmware/cmdline.txt and reboot.

  • Memory: less than 1.5 GiB is refused (a "2 GB" cloud host, which reports 1.6–1.9 GiB after the kernel's share, passes); a fresh installation with less than 3.5 GiB uses the small-host profile, and the installer notes that such a host runs only the platform and cannot create game servers. Felis-nano has no memory minimum.

  • Free disk on each filesystem the installer writes to, summed when several directories share one filesystem:

    DirectoryFree space needed (first installation)On a rerun or a reused directory
    /var/lib/rancher10 GiB3 GiB
    /var/lib/felis4 GiB when installing a release, otherwise 2 GiB3 GiB or 1 GiB
    /opt/felis3 GiB1 GiB
    /var/lib/containerd (only when images are built on the host)8 GiB2 GiB

    On a bare host with a single filesystem this comes to about 17 GiB for a release installation, 15 GiB from FELIS_ARTIFACT_DIR and 23 GiB when the images are built on the host; about 7 GiB for a rerun. A filesystem that would end above 85% full is a warning, because k3s starts deleting cached images there.

  • Ports: the game port, 6443, 6444, 10248, 10249, 10250, 10256, 10257, 10259, the panel port, the registry's loopback port 5000 and the database's loopback port 15432. A port held by the installer's own units (a rerun) passes; any other program holding one is reported by name.

  • Other Kubernetes: another distribution (kubelet, RKE2, k0s, MicroK8s) or a k3s agent on the host is refused.

  • Network ranges: the host's address or a routed network inside 10.42.0.0/16 or 10.43.0.0/16 is refused; a wider route that covers them is a warning.

  • Outbound HTTPS to the download hosts of this run (Outbound access). A host counts as reachable once a TLS handshake completes; each gets three tries two seconds apart, and the unreachable ones are listed in one message (cannot reach … over HTTPS). When installing a release, an unreachable Docker Hub is a warning; from FELIS_ARTIFACT_DIR it is not checked.

FELIS_PREFLIGHT=warn reports the same problems as warnings and installs anyway, for a host the checks misjudge.