Felis-nano
Felis-nano is the minimal form of Felis and handles login control only. The operator keeps managing the servers, the routing and the proxy configuration; Felis-nano provides login through multiple authentication sources, the account system and the management panel. It suits an existing Velocity network that adopts Felis's authentication sources and account management without moving its servers.
Scope
| Area | Contents |
|---|---|
| Login | Mojang accounts and third-party Yggdrasil authentication sources side by side. Player UUIDs are derived as on the full platform; see Authentication sources. |
| Accounts | Panel sign-in (passkey, email code, in-game approval), game account linking, session management and personal API tokens. |
| Administration | User management, authentication sources, the audit log, mail delivery, the default interface language and the panel's appearance. |
| In-game commands | /link, /felis web and /felis web op approve <code>. |
Felis-nano does not include server management, the lobby and login space, backups, image builds, account migration or k3s. In Felis-nano mode the proxy plugin does not take over routing and registers neither the server commands nor /invite.
Components
| Component | Description |
|---|---|
felis-nano.service | Runs as the system user felis-nano. The internal port (default 127.0.0.1:8081, HTTP) serves the hasJoined endpoint and the proxy plugin's API; the panel port (default 8443, HTTPS) serves the panel. |
| PostgreSQL | PostgreSQL 13 or later on the host. The database and the role are both felis and accept local connections only. |
| Proxy plugin | felis-velocity.jar on the operator's Velocity, running with mode=nano. |
Requirements
- A Linux host with systemd, on the distributions the full installation supports; see Requirements. Felis-nano has no memory minimum.
- Where the distribution ships a PostgreSQL older than 13 (for example Ubuntu 20.04), install 13 or later from the PostgreSQL project's repository first. On RHEL-family distributions the installer enables the newest PostgreSQL module stream.
- The Velocity proxy runs with
online-modeenabled. - The proxy's host can reach Felis-nano's internal port.
Installation
Run the installer (development channel):
curl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/main/deploy/bootstrap.sh | sudo FELIS_VERSION_BOOTSTRAP=dev FELIS_INSTALL_MODE=nano bashThe installer performs these steps:
- Installs PostgreSQL and creates the database and the role.
- Writes
/etc/felis/felis.tomland generates a self-signed certificate for the panel. - Runs the database migrations.
- Prepares the proxy plugin and its settings in
/etc/felis/nano-proxy/. The development channel builds the Felis binary and the plugin on the host; Docker is installed and started for the build and stopped afterwards, and the build uses about 1 GiB of additional memory. - Installs and starts
felis-nano.serviceand opens the panel port. - Creates the Owner account and prints a one-time setup link.
The installer can be run again. A rerun keeps the generated secrets (/etc/felis/nano.env), the root domain and the port settings.
Installer variables
| Variable | Default | Description |
|---|---|---|
FELIS_INSTALL_MODE | Interactive prompt | Set to nano. |
FELIS_ROOT_DOMAIN | <host address>.nip.io, or <public address>.nip.io on a cloud host (Public address) | Root domain. The player panel is console.<root domain> and the operator console op.console.<root domain>. |
FELIS_NANO_LISTEN | 127.0.0.1:8081 | Listen address of the internal port. Set a private-network address when the proxy runs on another host. |
FELIS_NANO_PROXY_CIDR | — | The proxy allowed to reach the internal port, as an address with a prefix length (for example 10.0.0.7/32). |
FELIS_NANO_PANEL_PORT | 8443 | HTTPS port of the panel. |
FELIS_NANO_PUBLIC_PORT | The panel port | Port in the panel's public address. Set 443 when a reverse proxy serves the panel on port 443. |
WARNING
The hasJoined endpoint takes no token. Open the internal port to the proxy alone: when it listens on a non-loopback address, also set FELIS_NANO_PROXY_CIDR, and the host firewall opens the port to that source only.
Connecting the proxy
Copy
/etc/felis/nano-proxy/felis-velocity.jarinto Velocity'splugins/directory.Copy
/etc/felis/nano-proxy/felis-link.propertiestoplugins/felis-link/felis-link.properties. The file holds the service token; make it readable by the proxy's user only.Add this JVM option to the proxy's start command, between
javaand-jar:text-Dmojang.sessionserver=http://127.0.0.1:8081/session/minecraft/hasJoinedWhen the internal port is on another host, use the address of
FELIS_NANO_LISTEN.Make sure
velocity.tomlhasonline-mode = true, then restart the proxy.
Plugin settings:
| Setting | Description |
|---|---|
mode | Always nano. The plugin registers the login commands only; servers and routing follow the proxy's own configuration. |
api-base-url | Address of Felis-nano's internal port. |
service-token | Token the plugin uses for the internal API; matches FELIS_SERVICE_TOKEN in /etc/felis/nano.env. |
panel-hostname, admin-hostname | Panel addresses shown in in-game messages, with the port unless it is 443. |
Players of a third-party authentication source start their client through authlib-injector, pointed at that source's site. Authentication sources are added on the panel's Authentication sources page; see Authentication sources.
Owner setup
The installer ends with a setup link that is valid for 30 minutes. When /etc/felis/felis.toml has an [smtp] section, the setup page sends a code to the email address the Owner enters, and verifying it completes setup; a passkey can be added later on the Account page. Without mail delivery, the setup page records an email address and then creates a passkey. Browsers create passkeys only under a trusted certificate, so use one of the following:
- Add an
[smtp]section to/etc/felis/felis.toml, runsudo systemctl restart felis-nano, then open the setup page again and complete setup with an email code. - Write a trusted certificate and key to
/etc/felis/panel-tls.crtand/etc/felis/panel-tls.key, then runsudo systemctl restart felis-nano. The certificate must cover both panel hostnames. - Serve the panel through a reverse proxy on port 443; see Reverse proxy.
When the link has expired, run the following command for a new one. Append -public-port <port> when the public port is not 8443:
sudo felis nano setupOnce the Owner has completed setup, the command prints only the sign-in address.
Reverse proxy
Configure the reverse proxy with the upstream
https://127.0.0.1:8443. That port uses a self-signed certificate, so the reverse proxy skips upstream TLS verification; it also forwards the originalHostheader. A Caddy example:textop.console.mc.example.com, console.mc.example.com { reverse_proxy https://127.0.0.1:8443 { transport http { tls_insecure_skip_verify } header_up Host {host} } }Add to
/etc/felis/felis.toml:toml[auth] client_ip_header = "X-Forwarded-For"Run the installer again with
FELIS_NANO_PUBLIC_PORT=443. The installer updates the addresses in panel links and the setup link, regenerates/etc/felis/nano-proxy/felis-link.properties, and closes the panel port in the host firewall so that only the reverse proxy on this host reaches it.Copy the new
felis-link.propertiesto the proxy, then restart the proxy.
When the reverse proxy runs on another host, allow that host to reach the panel port in the firewall.
Configuration file
/etc/felis/felis.toml has mode 0640 and group felis-nano. After editing it, run sudo systemctl restart felis-nano.
| Section | Description |
|---|---|
[server] | root_domain: the root domain. |
[database] | url: the PostgreSQL connection URL, written by the installer. |
[auth] | Optional. panel_hostname, admin_hostname and client_ip_header, as on the full platform; see the Configuration reference. |
[smtp] | Optional. Mail delivery can also be configured in the panel under Platform settings → Mail delivery. |
[[auth_source]] | Optional. The initial list of authentication sources; once the Owner saves a list in the panel, the panel's list applies. |
Upgrading
Run the installer again to upgrade Felis-nano. The installer runs the database migrations before starting the new version, and backs up the database first when migrations are pending. felis update does not apply to Felis-nano.
Earlier versions of Felis-nano used no database and read only the [[auth_source]] entries in felis.toml. On such a host, a rerun of the installer keeps the existing authentication sources and adds the [server] and [database] sections. The sources' tag values stay the same, and so do the players' UUIDs.
Uninstalling
Felis-nano uses the same uninstall script as the full platform; see Uninstall and reinstall. By default /etc/felis and the database are kept; --purge also drops the database and the role.
Uninstall Felis-nano before installing the full platform on the same host; the installer stops when it finds Felis-nano.