# 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.

Source: https://featherpanel.com/docs/wings/configuration/

`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.

| Mode | What you give it | What it does |
|------|------------------|--------------|
| Automatic (OAuth2) | `--panel-url` | Authorizes in your browser, creates the node in the panel, then joins it |
| Manual (join data) | `--join-data` or `FEATHERWINGS_JOIN_DATA` | Joins a node you already created in the admin area |

Install the daemon first, see [Install FeatherWings](https://featherpanel.com/docs/wings/installation).

## Automatic setup with OAuth2

```bash
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"):

```bash
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.

```bash
systemctl status featherwings
journalctl -u featherwings -f
```

## Flags

| Flag | Purpose |
|------|---------|
| `--panel-url` | Panel base URL for the OAuth2 quick setup |
| `--join-data` | Base64 join data from the node page |
| `-c, --config` | Where to write config.yml |
| `--override` | Replace an existing config without asking |
| `--install-service` | Install, enable and start the systemd unit |
| `--no-service` | Skip the systemd step |
| `--keep-oauth-key` | Keep the temporary OAuth2 API key on the panel |
| `--node-name`, `--node-fqdn`, `--location-id`, `--callback-host` | Node fields for unattended quick setup |
| `--allow-insecure` | Skip TLS verification when talking to the panel |
| `-q, --quiet` | No interactive UI or animations |

Every other key of the file is described in the [config.yml reference](https://featherpanel.com/docs/wings/config-reference), and every
command in the [command reference](https://featherpanel.com/docs/wings/cli).

## Frequently asked questions

### Can I run featherwings configure again on a node that is already set up?

Yes. It asks before replacing an existing config.yml, or replaces it without asking when you pass --override.

### Does the quick setup leave an API key behind on the panel?

Not by default. The temporary OAuth2 API key is deleted after the node is created, unless you pass --keep-oauth-key or answer no to the prompt.