Joining a web node
How featherquilld configure connects a web node to FeatherPanel with OAuth, join data or a token, and how the panel keeps the node config in sync afterwards.
On this page
A web node is a FeatherQuilld install that the panel knows about. featherquilld configure writes
/etc/featherquilld/config.yml with the node’s identity and the panel address, then pulls the rest of the configuration
from the panel. If you followed Installation you already ran it once.
Three ways to connect
Run sudo featherquilld configure in a terminal and pick one:
- OAuth quick setup (recommended). Enter the panel URL. Quilld shows a device code and a link, you approve it in
the browser while signed in as an admin, and Quilld then creates the web node through the admin API. It asks for the
name, FQDN and web location (it can create a location if there is none), and suggests this machine’s IP and hostname.
The temporary API key is deleted at the end unless you pass
--keep-oauth-key. - Paste join data. Create the web node in the admin area first, open its FeatherQuilld config tab and copy the join data (base64). This is what the panel’s two setup commands do for you.
- Manual credentials. Enter the panel URL, the token ID and secret of the node, an optional node UUID and the API port.
Without a terminal (for example in a provisioning script) the wizard does not run. Pass --join-data, set
FEATHERQUILLD_JOIN_DATA, or use --panel-url with --node-name, --node-fqdn and --location-id for an OAuth setup.
An existing config is kept unless you add --override.
| Flag | Use |
|---|---|
--join-data <base64> | Join data from the panel |
--panel-url <url> | Panel URL for OAuth |
--node-name, --node-fqdn, --location-id | Node details for a non-interactive OAuth setup |
--node-ip, --callback-host | Override the detected IP and the host used for the OAuth callback |
--daemon-listen <port>, --sftp-port <port> | API port (default 8989) and SFTP port (default 2222) |
--daemon-base <dir> | Base directory (default /var/lib/featherquilld) |
--behind-proxy, --no-behind-proxy, --scheme | How the panel reaches the node |
--allow-insecure | Accept an invalid TLS certificate on the panel |
--keep-oauth-key | Do not delete the OAuth API key afterwards |
--install-service, --no-service | Install or skip the systemd unit |
--config <path> | Write a different config file |
--override | Replace an existing config |
--quiet, -q | Less output |
TLS for the node API
Browsers talk to the Quilld API directly (file uploads, the console), so when the panel uses HTTPS the node needs HTTPS
too. If the panel is on HTTPS and you did not mark the node as behind a proxy, the wizard asks for a node FQDN and
checks /etc/letsencrypt/live/<fqdn>/. When there is no certificate it offers to get one with certbot, by HTTP
verification or by a DNS TXT record (which also works behind a CDN). The certificate is written into api.ssl.
If a proxy such as Cloudflare terminates TLS in front of the node, choose behind proxy and Quilld skips the certificate.
What happens after joining
- Quilld saves the join config:
uuid,token_id,tokenand theremoteblock. - It fetches the runtime config from
GET /api/quilld-remote/configon the panel and merges it into the file. - It installs and starts
featherquilld.service(unless you passed--no-service). The unit runs after and requiresdocker.service.
While it runs, Quilld checks GET /api/quilld-remote/health and fetches the runtime config again every 60 seconds.
When the panel reports maintenance mode, the node marks itself unhealthy.
Settings that come from the panel
The web node edit page in the admin area is the main place to change a node. The panel turns these fields into the runtime config:
| Tab | Fields | Config keys |
|---|---|---|
| Configuration | Daemon base, volumes, backup and plugins directories | system.root_directory, system.data, system.backup_directory, plugins.directory |
| Configuration | Backup storage | system.backups (see Backups) |
| Network | Site reverse proxy, provider, ACME email and staging, backend port range and hosts | system.proxy (see Reverse proxy and DNS) |
| Network | Daemon API port, SFTP port | api.port, sftp.port |
| Remote & SFTP | Timeout, retry limit, SFTP, host key algorithm, password login, classic FTP | remote, sftp, ftp |
| Advanced | Upload size limit | api.upload_limit |
Anything else goes into Advanced Config Overrides (JSON) on the Configuration tab. It is merged last, so it wins over the fields above. For example, to switch mail to mailcow and turn on plugins:
{
"system": { "mail": { "backend": "mailcow" } },
"plugins": { "enabled": true }
}Keys that neither the panel nor your overrides send stay as they are in the local config.yml. The FeatherQuilld
config tab also shows the generated join and runtime config, and has a button to reset the daemon token. After a reset,
run configure again with the new join data.
See the config.yml reference for every key.
Frequently asked questions
Every 60 seconds Quilld fetches its runtime config from the panel and merges it into config.yml. Keys the panel sends win. Set those values in the web node settings or in the Advanced Config Overrides field instead.
In Configuration, Advanced Config Overrides (JSON) on the web node. The JSON is merged last into the generated config, so it can set any FeatherQuilld key.