Join a node to the panel

How featherwings configure connects a node to FeatherPanel, with the OAuth2 quick setup or join data, TLS certificates and the systemd service.

featherwings configure writes /etc/featherpanel/config.yml for a node and can install the systemd service. It has two modes. In a terminal it asks which one you want; without a terminal (or with --quiet) it picks the mode from the flags.

Install the daemon first, see Install FeatherWings.

Automatic setup with OAuth2

sudo featherwings configure --panel-url 'https://panel.example.com' --install-service

1. Wings starts an OAuth2 device authorization on the panel and prints a link and a code. It also tries to open the link in a browser. Sign in as an administrator who may create nodes and approve the request.
2. The panel returns a temporary API key. Wings checks it and prints the account it is acting as.
3. You fill in the node form. The defaults come from the machine: the hostname as name, total memory and disk of / as limits, 8443 as daemon port, 2022 for SFTP, 80 for FastDL and 100 MB as upload limit.
4. You pick a game location or create a new one (name, description, flag code).
5. Wings creates the node through the panel API, downloads its join data and continues as in manual mode.
6. The temporary API key is deleted, unless you pass --keep-oauth-key or decline the prompt.

For unattended runs pass the node fields as flags: --node-name, --node-fqdn, --location-id and --callback-host (the public IP of the node).

Data directory

The wizard asks where server volumes live: /var/lib/featherpanel/volumes (the FeatherPanel default), /var/lib/featherwings/volumes, or a custom absolute path. Pick the first unless you have a reason not to.

Network and TLS

The wizard then asks if a reverse proxy (Cloudflare, nginx or similar) terminates TLS in front of Wings.

• Behind a proxy: you enter the domain the proxy serves. The node is saved with https and Wings does not look for a certificate.
• Panel on HTTP or on an IP address: the node uses http and the FQDN defaults to the node IP.
• Panel on HTTPS, no proxy: you enter a domain and Wings looks for a Let’s Encrypt certificate in /etc/letsencrypt/live/<domain>/. If none exists it offers to run certbot.

certbot can verify the domain over HTTP (standalone, webroot or the nginx plugin, which is offered when nginx is running) or with a DNS TXT record, which also works behind a CDN. If issuing fails you can stop web servers and retry in standalone mode, switch method, check again after installing a certificate yourself, or use another domain.

Manual setup with join data

Create the node in the admin area, then copy the join data from its Quick setup box (“Advanced: join data only”):

sudo featherwings configure --join-data '<value>' --install-service

Join data is a base64 encoded YAML document with the node UUID, the token id and token, and the panel URL. Wings:

1. Decodes it and checks that the credentials are complete.
2. Calls GET /api/remote/health on the panel to confirm the token is accepted.
3. Downloads the full runtime configuration from GET /api/remote/config, unless the join data already contains a complete config.yml.
4. Writes the file to the path in --config (default /etc/featherpanel/config.yml).

If a config file exists, Wings asks before replacing it. Pass --override to replace it without asking.

The systemd service

With --install-service Wings writes /etc/systemd/system/featherwings.service, enables it and starts it. Without the flag it asks, and --no-service skips the step. APT installs ship their own unit in /lib/systemd/system/featherwings.service.

The generated unit runs as root, starts after docker.service, requires it, and restarts Wings five seconds after a crash.

systemctl status featherwings
journalctl -u featherwings -f

Flags

Every other key of the file is described in the config.yml reference, and every command in the command reference.