# FeatherPanel documentation (full text) > Every page of https://featherpanel.com/docs/ as Markdown, generated 2026-10-23. Index: https://featherpanel.com/llms.txt --- # FeatherPanel documentation > Install, run and extend FeatherPanel, the open-source panel for game servers, Proxmox VDS and web hosting, with FeatherWings, FeatherQuilld and FeatherCli. Source: https://featherpanel.com/docs/ ## What FeatherPanel runs FeatherPanel is a self-hosted control panel from MythicalSystems. One panel manages three kinds of workload: - Game servers. The [FeatherWings](https://featherpanel.com/docs/wings) daemon on each game node runs them in Docker containers. - Virtual machines and containers on Proxmox VE, sold to users as "VDS". The panel talks to the Proxmox API directly. - Web hosting. The [FeatherQuilld](https://featherpanel.com/docs/quilld) daemon on each web node runs WebSpaces, a reverse proxy, DNS, mail and SFTP/FTP. The panel is released under the AGPL-3.0. FeatherWings is a fork of Pterodactyl Wings and keeps its MIT license. If you are coming from Pterodactyl, read [FeatherPanel vs Pterodactyl](https://featherpanel.com/docs/featherpanel-vs-pterodactyl) and the [migration guide](https://featherpanel.com/docs/migrating/pterodactyl). ## Components | Component | What it is | Docs | |-----------|------------|------| | FeatherPanel | The web panel: PHP 8.5 backend (FrankenPHP), Next.js frontend, Rust async runner, MCP server, MariaDB and Redis | [Install](https://featherpanel.com/docs/panel/installation), [Admin guide](https://featherpanel.com/docs/admin), [User guide](https://featherpanel.com/docs/user) | | FeatherWings | Go daemon that runs game servers in Docker and serves SFTP | [FeatherWings](https://featherpanel.com/docs/wings) | | FeatherQuilld | .NET daemon for web hosting nodes (WebSpaces, proxy, DNS, mail, SFTP/FTP) | [FeatherQuilld](https://featherpanel.com/docs/quilld) | | FeatherCli | .NET command line client for the panel API and the Pterodactyl migration tool | [FeatherCli](https://featherpanel.com/docs/cli/feathercli) | | Panel CLI | `php cli` inside the backend (wrapped as `featherpanel` on installer hosts) | [Panel CLI](https://featherpanel.com/docs/cli/panel) | | Installer | `install.bash`, the interactive installer for the panel, Wings, Quilld, CLI and SSL | [Installer script](https://featherpanel.com/docs/cli/installer) | ## How these docs are made Scripts in [`scripts/docs-data`](https://github.com/MythicalLTD/FeatherPanel-Website/tree/v4/scripts/docs-data) generate the reference pages from the source code of each repository: API endpoints, permission nodes, settings, plugin events, widget slots, Wings and Quilld `config.yml` keys and command flags. The guides are written by hand against the same code. Each page lists the source files it was written from at the bottom. If a page no longer matches the code, use "Edit this page on GitHub". ## Getting help - Community support: [Discord](https://discord.mythical.systems) - Bugs: [FeatherPanel issues](https://github.com/MythicalLTD/FeatherPanel/issues), [FeatherWings issues](https://github.com/MythicalLTD/FeatherWings/issues), [FeatherQuilld issues](https://github.com/MythicalLTD/FeatherQuilld/issues) - Security reports: see [Security](https://featherpanel.com/docs/security) --- # Getting started > Where to begin with FeatherPanel. Read the architecture, check the requirements, then follow the quick start to install the panel and run a first game server. Source: https://featherpanel.com/docs/getting-started/ Read these pages in order if FeatherPanel is new to you. Together they take you from "what is this" to a running game server. 1. [Architecture](https://featherpanel.com/docs/getting-started/architecture): the panel, its runner, and the FeatherWings and FeatherQuilld nodes, and how they talk to each other. 2. [Requirements](https://featherpanel.com/docs/getting-started/requirements): supported operating systems, CPU architectures, virtualization types and the firewall ports to open. 3. [Quick start](https://featherpanel.com/docs/getting-started/quick-start): install the panel with the installer script, create the admin account, add a node and start a server. 4. [Features](https://featherpanel.com/docs/getting-started/features): everything the panel can do, taken from the code. 5. [Glossary](https://featherpanel.com/docs/getting-started/glossary): FeatherPanel terms and their Pterodactyl equivalents. ## Next steps - Pick an install method in [Installation](https://featherpanel.com/docs/panel/installation). - Put the panel behind a [web server](https://featherpanel.com/docs/panel/web-server) and add [SSL](https://featherpanel.com/docs/panel/ssl). - Coming from Pterodactyl? Read [Migrating from Pterodactyl](https://featherpanel.com/docs/migrating/pterodactyl). --- # Architecture > How FeatherPanel is built - FrankenPHP backend, Next.js frontend, Rust async runner, MCP server, MariaDB, Redis, FeatherWings and FeatherQuilld nodes. Source: https://featherpanel.com/docs/getting-started/architecture/ FeatherPanel is split into a **panel** that you install once and **daemons** that you install on every machine that runs workloads. The panel never runs game servers or websites itself: it stores state, checks permissions and tells the daemons what to do. ## The big picture ```text Browser / API client / MCP client │ HTTPS your reverse proxy (nginx, Apache, Caddy, Cloudflare Tunnel) │ http://127.0.0.1:4831 ┌──────────────────────────── panel host (Docker) ─────────────────────────────┐ │ frontendv2 (Caddy + Next.js) ── /api, /pma, /webmail, /addons ──► backend │ │ │ └─ /mcp, OAuth ──► mcp (Node.js) │ │ │ └─ /vnc-proxy ──► async-runner (Rust) ◄── Redis pub/sub ─────┤ │ │ MariaDB ◄────────┤ Redis │ └──────────────────────────────────────────────────────────────────────┼────────┘ ┌───────────────────────────────┬─────────────────────────┘ ▼ HTTPS + node token ▼ HTTPS + node token ▼ Proxmox API FeatherWings (game nodes) FeatherQuilld (web nodes) Proxmox VE (VDS nodes) Docker, SFTP :2022, API :8080 WebSpaces, proxy, DNS, mail, VMs and LXC containers SFTP :2222, FTP :21, API :8989 ``` ## Panel services The Docker install (`docker-compose.yml`) runs these containers: | Service | Image | What it does | |---------|-------|--------------| | `frontendv2` | `ghcr.io/mythicalltd/featherpanel-frontendv2` | The only published container (host port `4831` by default). A Caddy server in front of the Next.js app that also routes API, MCP and VNC traffic to the other services. | | `backend` | `ghcr.io/mythicalltd/featherpanel-backend` | The PHP API on FrankenPHP (Caddy with PHP built in), plus cron and the bundled phpMyAdmin and webmail. | | `async-runner` | `ghcr.io/mythicalltd/featherpanel-async-runner` | A Rust worker. Sends queued mail, creates Proxmox VMs and proxies VNC consoles. | | `mcp` | `ghcr.io/mythicalltd/featherpanel-mcp` | The [Model Context Protocol server](https://featherpanel.com/docs/panel/mcp-server) for AI assistants. | | `mysql` | `mariadb:latest` | The panel database. | | `redis` | `redis:latest` | Cache, rate limit and account lockout counters, two-factor challenges, the player status cache and the pub/sub queue for the async runner. | ### How requests are routed The Caddy server inside `frontendv2` decides where each request goes: | Path | Goes to | |------|---------| | `/api*`, `/pma*`, `/webmail*`, `/attachments*`, `/addons*`, `/components*` | `backend` | | `/mcp*`, `/authorize`, `/token`, `/register`, `/revoke`, `/oauth*`, OAuth `/.well-known/*` documents | `mcp` | | `/vnc-proxy*` | `async-runner` on port 9100 | | everything else | Next.js | Requests may be up to 250 MB. Event streams (`/api/mercure` and the chatbot streams) are not compressed so they reach the browser immediately. ### Inside the backend The backend runs PHP on [FrankenPHP](https://frankenphp.dev/). By default it uses **worker mode**: the app boots once and stays in memory, which removes the per-request bootstrap cost. There are two worker pools: - `featherpanel-api` serves `/api/*`. It starts `2 x CPU` threads and can grow to `3 x CPU` (at most 32) under load. - `featherpanel-slow` serves long responses (chatbot streams, file and backup downloads) so a few of them cannot block the rest of the API. Set `FRANKENPHP_WORKER=false` to fall back to classic mode. See [Cron, workers and runner](https://featherpanel.com/docs/panel/cron-and-workers) for every knob. The backend also hosts the [Mercure](https://featherpanel.com/docs/panel/realtime) hub that pushes live updates to the browser, and runs the cron jobs every minute. ### The async runner The runner listens on three Redis channels: - `featherpanel:mail:pending` sends queued e-mail over SMTP, so a slow mail server never slows down a request. - `featherpanel:vm:pending` creates VDS instances on Proxmox and reports progress. - `featherpanel:settings:reload` reloads settings after an admin changes them. It also serves the browser VNC console for VDS instances at `/vnc-proxy`. ## Daemons ### FeatherWings (game servers) [FeatherWings](https://featherpanel.com/docs/wings) is a Go daemon, forked from Pterodactyl Wings. Each game node runs one. It creates a Docker container per server, streams the console over a websocket, serves SFTP on port 2022 and takes backups. The panel talks to it over HTTPS on port 8080 with the node token; Wings calls back to the panel with `token_id.token`. A node's **daemon type** can also be `wings_rs` ([Calagopus Wings](https://github.com/calagopus/wings)). Those nodes default to `/etc/calagopus-wings/config.yml`, `/var/lib/calagopus-wings/volumes` and the `wings` systemd unit. The panel keeps a feature matrix per daemon type (`DaemonCapabilities`) and hides what a node cannot do: | Only on FeatherWings nodes | Only on Calagopus Wings nodes | |----------------------------|-------------------------------| | modules, live config, host terminal, trash, node firewall, FastDL, diagnostics, Docker disk view, proxy, server import, file sharing, reconcile, container exec | system logs, install abort, directory download, file operation progress, backup browsing, server scripts, live websocket permissions, file fingerprints, paginated file lists, transfer backups, 7z compression | Both support the core server API, Docker, file search, archive browsing, deauthorize, self update, file history and file collaboration. ### FeatherQuilld (web hosting) [FeatherQuilld](https://featherpanel.com/docs/quilld) is a .NET daemon for web nodes. It runs customer **WebSpaces** in Docker, manages a reverse proxy (Caddy, nginx or Traefik), DNS through PowerDNS, mail through docker-mailserver or mailcow, and SFTP/FTP. Its API listens on port 8989. ### Proxmox VE (VDS) VDS hosting needs no FeatherPanel daemon. The panel stores a Proxmox API token per VDS node and drives Proxmox directly; the async runner does the long-running VM creation. The installer has a **Proxmox VNC Agent** option that you run on the Proxmox node; it adds noVNC files for PVE token forwarding so the in-panel console works. ## Data and state | What | Where | |------|-------| | Users, servers, nodes, settings, activity | MariaDB (225 migrations at the time of writing) | | Secrets in the database (node tokens, API client keys, SMTP password, OIDC secrets and more) | Encrypted with `DATABASE_ENCRYPTION_KEY` (XChaCha20) | | Uploaded files, plugins, translations, snapshots, logs | Docker volumes `featherpanel_attachments`, `featherpanel_addons`, `featherpanel_translations`, `featherpanel_snapshots`, `featherpanel_logs` | | `.env` and other config | Volume `featherpanel_config` (`backend/storage/config`) | | Game server files and backups | On each Wings node (`/var/lib/featherpanel`) | | WebSpace files and backups | On each Quilld node (`/var/lib/featherquilld`) | ## Optional parts - **phpMyAdmin** (`/pma`) and **webmail** (`/webmail`) are served by the backend. phpMyAdmin is installed with `featherpanel module install pma`. - **Telemetry**: the `UmamiTelemetryReporter` cron job sends one event per day with aggregate counts (users, servers, backups, nodes, schedules, webspaces, VMs and similar). The hostname is sent as the fixed string `featherpanel`. Turn it off with the `telemetry` setting, or force it off for the whole install with `UMAMI_ENABLED=false`. - **Plugins** add PHP routes, event listeners, cron jobs and frontend pages. See [Plugins](https://featherpanel.com/docs/plugins). ## Frequently asked questions ### Does FeatherPanel need FeatherWings? Only for game servers. Proxmox VDS hosting talks to the Proxmox API directly and web hosting uses FeatherQuilld. A panel with only the web or VDS module enabled needs no Wings node. ### Can FeatherPanel use Calagopus Wings instead of FeatherWings? Yes. A node's daemon type can be set to Calagopus Wings (wings_rs). The panel keeps a feature matrix per daemon type and hides features a node does not support, such as modules, the node firewall and FastDL on Calagopus Wings nodes. --- # Features > Every FeatherPanel feature, taken from the code - game servers on Wings, Proxmox VDS, WebSpaces on Quilld, SSO, tickets, plugins, API and more. Source: https://featherpanel.com/docs/getting-started/features/ This page lists what FeatherPanel does, grouped by area. Each item links to the guide that explains it. Everything here is in the code of the panel, FeatherWings or FeatherQuilld today; nothing is a roadmap item. FeatherPanel has three hosting **modules**. Each can be switched off in **Admin → Settings → Modules** (`module_game_enabled`, `module_vds_enabled`, `module_web_enabled`), which hides its pages, routes in the sidebar and search, and its MCP tools. ## Game servers (FeatherWings) | Feature | What you get | |---------|--------------| | Console | Live console over a websocket, command input, power actions (start, stop, restart, kill), install logs, CPU, memory and disk graphs with a stored resource history, and player counts and names for supported games. | | File manager | Browse, edit, upload, download (files and whole folders), copy, rename, change permissions, compress and extract archives, browse inside archives, search, pull a file from a URL, file hashes, and a trash bin with retention and size limits. | | File sharing | Share a file through a temporary upload link (temp uploads, up to 15 GB anonymous or 30 GB with a token). | | Databases | Per-server MySQL/MariaDB databases on database hosts that are global or bound to one node, with SQL export and import and phpMyAdmin access. | | Backups | Create, lock, restore, download and delete backups. Retention is a hard limit or FIFO rolling, with per-server overrides. Admins can add scheduled backup policies for many servers. | | Schedules | Cron-style schedules with tasks: power, command, backup (files or database), and container shell (off by default). | | Lifecycle hooks | Pipelines that run on `pre_start`, `post_start`, `pre_stop`, `post_stop` and `server_crash`. Steps: Discord webhook, container command, container shell, backup, HTTP request and sleep. | | Subusers | Invite users to a server with 50 fine-grained permission nodes. | | Network | Allocations (with optional user self-selection), a per-server firewall, reverse proxy domains with automatic SSL, Cloudflare subdomains with SRV records, and FastDL for Source games. | | Startup | Edit startup variables, choose a Docker image from the spell (or a custom one if allowed), change the spell within or across realms if allowed. | | Server import | Pull files from a remote SFTP or FTP server into a stopped server. | | Auto start | Servers can start automatically when their node reconnects after a reboot, staggered so a node does not start everything at once. | | Expiry | Servers and VDS instances can have an expiry date and are suspended automatically when it passes. | | Bulk actions | Start, stop, restart, kill or reinstall many servers at once from the server list. | | Transfers | Admins move one server, or all servers of a node (mass transfer), to another node. | | Spells and realms | Spells (eggs) grouped in realms (nests). Import Pterodactyl eggs, and browse spells from the FeatherCloud marketplace. | | FeatherZeroTrust | Scans server files for known malicious hashes on a schedule. | Read the [user guide for servers](https://featherpanel.com/docs/user/servers/console) and the [admin guide for servers](https://featherpanel.com/docs/admin/servers). ## VDS (Proxmox VE) | Feature | What you get | |---------|--------------| | VM and LXC instances | Create QEMU/KVM virtual machines (with cloud-init) or LXC containers from templates and plans on Proxmox nodes. Creation runs in the background on the async runner. | | Console | Browser VNC console through the panel. | | Power and reinstall | Start, stop, reboot, reinstall from a template, with task progress. | | ISO media | Fetch an ISO from a URL or upload one, mount and unmount it. | | Hardware and network | QEMU hardware view, network and DNS settings. | | Backups | Create, restore and delete instance backups with progress polling. | | Subusers | Share a VDS with other users. | See [VDS for admins](https://featherpanel.com/docs/admin/vds) and [VDS for users](https://featherpanel.com/docs/user/vds). ## Web hosting (FeatherQuilld) | Feature | What you get | |---------|--------------| | WebSpaces | Isolated hosting accounts on web nodes, created from **hosting packages** (disk, CPU, memory and database limits) and **WebPlates** (templates). | | Domains and SSL | Domains, SSL certificates and proxy logs. | | One-click apps | WordPress (with staging, promote, updates, plugins and auto-update), Laravel, Ghost, Joomla, Drupal, Magento, PrestaShop, Node.js and Python starters, and Git deploy with a webhook and deploy key. | | PHP | PHP `ini` settings and extensions per WebSpace, plus Redis. | | Files | File manager, trash, archives, search and upload/download links. SFTP accounts and FTP. | | Databases | Per-WebSpace databases. | | Mail | Mailboxes and webmail, backed by docker-mailserver or mailcow on the web node. | | DNS | DNS zones on PowerDNS, with a DNS check and provisioning. | | Security | A per-WebSpace WAF (deny lists for IPs and paths) and malware scans. | | Operations | Backups, cron schedules, logs, analytics, activity and subusers. | See [Web hosting for admins](https://featherpanel.com/docs/admin/web-hosting) and [WebSpaces for users](https://featherpanel.com/docs/user/webspaces). ## Accounts and sign-in - Local accounts with registration (on or off), e-mail verification and device-based registration limits. - Two-factor authentication (TOTP), **passkeys**, passwordless **e-mail login codes** and **QR code login** from a phone that is already signed in. - **Discord** login, any number of **OIDC** providers and **LDAP** providers, plus admin-generated **SSO login tokens**. - Captcha: Cloudflare Turnstile, hCaptcha, Google reCAPTCHA v2 and v3, Friendly Captcha and reForge Captcha. - **AbuseIPDB** checks on registration and user IP scans, blocked IPs and blocked e-mail domains. - Session management, SSH keys for SFTP, personal API keys, user data export and self-service account deletion (instant, delayed or after services expire). - Privacy mode that masks IPs, hosts, e-mails and keys in the UI. See [Authentication](https://featherpanel.com/docs/admin/authentication) and [Account](https://featherpanel.com/docs/user/account). ## Roles and permissions Roles carry admin permission nodes (`admin.users.list`, `admin.nodes.view` and so on). Server, VDS and WebSpace subusers have their own permission sets. The full list is in the [permissions reference](https://featherpanel.com/docs/reference/permissions). ## Support and communication - **Tickets** with categories, priorities, statuses, attachments and a per-user open ticket limit. - **Knowledgebase** with categories, tags and attachments, optionally public. - **Status page** for nodes and servers, optionally public and embeddable. - **Notifications** (banners) and a per-user **inbox**, **mail templates** and SMTP delivery through the async runner. - **Panel AI** chatbot for users (providers: built-in basic, Google Gemini, OpenRouter, OpenAI or compatible, Ollama, xAI Grok and Perplexity). ## Administration - Dashboard with node, server and ticket overviews, analytics and an audit log. - Locations, nodes, allocations, mounts, database hosts and Docker images. - Rate limits per route (opt-in), API keys, mail and DNS hosts for web nodes. - **Storage Sense** to prune old rows from history tables. - Panel database snapshots, Wings node backups and backup schedules. - Translations editor, branding (logos, accent colours, backgrounds, themes, login page layout), custom CSS and JS, PWA install, SEO settings. - A built-in **updates** page and a setup wizard on first launch. - The **Pterodactyl importer** page, which points to the migration agent. ## Extending FeatherPanel - **Plugins** (`.fpa` packages) with PHP event listeners for 465 events, routes, cron jobs (`Cron/`), CLI commands (`Commands/`), database migrations (`Migrations/`), sidebar pages and dashboard widgets. See [Plugins](https://featherpanel.com/docs/plugins). - **Themes and UI packs** that plugins ship and admins pick as defaults. - **FeatherCloud marketplace** for plugins, spells and translations. - **REST API** with personal API keys, OAuth2 apps (authorization code and device flow) and a Calagopus-compatible client API. See [API](https://featherpanel.com/docs/api). - **MCP server** so AI assistants (Claude, Cursor and other MCP clients) can manage servers, files, VDS and WebSpaces with the user's own permissions. See [MCP server](https://featherpanel.com/docs/panel/mcp-server). - **FeatherCli**, a terminal client for the API. See [FeatherCli](https://featherpanel.com/docs/cli/feathercli). ## Daemon features FeatherWings adds features on top of Pterodactyl Wings, such as modules, a node firewall, FastDL, server import, trash, host diagnostics and node backups. See [FeatherWings](https://featherpanel.com/docs/wings). FeatherQuilld is new: it has no Pterodactyl equivalent. See [FeatherQuilld](https://featherpanel.com/docs/quilld). ## Performance FeatherPanel's backend runs in FrankenPHP worker mode by default. Measured numbers live on the [benchmarks page](https://featherpanel.com/benchmarks) instead of in these docs, so they stay current. ## Frequently asked questions ### Can I turn off the parts of FeatherPanel I do not need? Yes. The settings module_game_enabled, module_vds_enabled and module_web_enabled switch the game server, Proxmox VDS and web hosting modules on or off. Disabled modules disappear from the sidebar, search and the MCP tool list. ### Does FeatherPanel support Pterodactyl eggs? Yes. Eggs are called spells and nests are called realms. Admins can import a Pterodactyl egg as a spell, and the FeatherCli migration tool moves locations, nests, eggs, nodes, allocations, users, servers, databases, backups, schedules and subusers from a Pterodactyl install. --- # Requirements > Supported operating systems, CPU architectures, virtualization types, software and firewall ports for FeatherPanel, FeatherWings and FeatherQuilld. Source: https://featherpanel.com/docs/getting-started/requirements/ FeatherPanel does not publish minimum CPU or RAM figures. Size the panel host for the number of users you expect and the game, VDS and web nodes for the workloads they run. The backend sizes its PHP thread pool from the memory it can see, so it adapts to small and large machines (see [Cron, workers and runner](https://featherpanel.com/docs/panel/cron-and-workers)). ## Operating systems The installer (`install.bash`) checks `/etc/os-release` before it does anything: | Distribution | Versions accepted by the installer | |--------------|-----------------------------------| | Debian | 11, 12, 13 | | Ubuntu | 22.04 LTS, 24.04 LTS, 26.04 LTS, 25.04, 25.10 (20.04 also passes the check) | Anything else stops with an error unless you pass `--skip-os-check`. The installer also warns when your release is past or close to its end of life. > [!NOTE] > Ubuntu 20.04 passes the version check but is not listed in the installer's own "officially supports" message. Prefer a > current LTS release. **Windows**: the PowerShell installer (`install.ps1`) installs the panel and FeatherCli on top of Docker Desktop, into `C:\featherpanel`. FeatherWings and FeatherQuilld are Linux only. See [Windows install](https://featherpanel.com/docs/panel/installation/windows). ## CPU architectures | Architecture | Status | |--------------|--------| | `amd64` (x86_64) | Native images and packages | | `arm64` (aarch64) | Native images and packages | | `armv7l`, `armv6l` | Not native. The installer offers to install QEMU and run the amd64 images through emulation (`--force-arm` skips the confirmation). Expect slower startup and higher CPU and memory use. | ## Virtualization Docker has to work on the machine. The installer runs `systemd-detect-virt` and refuses: - OpenVZ / OVZ / Virtuozzo - LXC (including `lxc-libvirt`) KVM, VMware, Xen, Hyper-V and bare metal are fine. `--skip-virt-check` overrides the check if you know your container supports nested Docker. On kernels older than 6.1 the installer reminds you to add `swapaccount=1` to `GRUB_CMDLINE_LINUX_DEFAULT` if you want Docker swap limits for game servers. ## Software ### Panel (Docker install, recommended) - Docker Engine with the Compose plugin. The installer installs both if they are missing. - That is all. PHP, MariaDB, Redis, Node.js and the Rust runner all ship in the images (`ghcr.io/mythicalltd/featherpanel-*`). - A web server on the host only if you want one in front of the panel: nginx, Apache or Caddy for TLS, or a Cloudflare Tunnel. See [Web server](https://featherpanel.com/docs/panel/web-server). ### Panel (source install, unsupported) The source installer (`installer/source/*.bash`) installs PHP **8.5** (`composer.json` requires `^8.5`), FrankenPHP, MariaDB, Redis, Node.js for the Next.js build and a Rust toolchain for the async runner. It is meant for developers and gets no support guarantee. See [Source install](https://featherpanel.com/docs/panel/installation/source). ### FeatherWings - Docker CE. The installer installs it when it is missing. - systemd. - Installed from the MythicalSystems APT repository (`featherwings`, or the nightly package) or as a direct binary download from GitHub. See [Install Wings](https://featherpanel.com/docs/wings/installation). ### FeatherQuilld - Debian or Ubuntu (APT and dpkg). FeatherQuilld is only shipped as an APT package (`featherquilld`, or `featherquilld-dev` for nightly). - Docker CE (a recommended dependency; the installer makes sure it is present) and systemd. - See [Install Quilld](https://featherpanel.com/docs/quilld/installation). ### FeatherCli A single binary in `/usr/local/bin/feathercli`. The installer also installs `libicu-dev`, which the .NET runtime needs. See [FeatherCli](https://featherpanel.com/docs/cli/feathercli). ## Network and ports | Component | Port | Direction | Purpose | |-----------|------|-----------|---------| | Panel | `4831/tcp` | local | `frontendv2` container. Set `FEATHERPANEL_PANEL_PORT` to change it. Keep it closed when a reverse proxy is in front. | | Panel | `80/tcp`, `443/tcp` | inbound | Your reverse proxy (HTTP and HTTPS). | | FeatherWings | `8080/tcp` | inbound from the panel and browsers | Wings API and console websocket (`api.port`). | | FeatherWings | `2022/tcp` | inbound | SFTP for server files (`system.sftp.bind_port`). | | FeatherWings | allocation ports | inbound | The game ports you assign to servers. | | FeatherWings | `80/tcp` | inbound (optional) | FastDL, only if enabled. | | FeatherQuilld | `8989/tcp` | inbound from the panel and browsers | Quilld API (`api.port`). | | FeatherQuilld | `2222/tcp` | inbound | SFTP for WebSpaces. | | FeatherQuilld | `21/tcp`, `50000-50100/tcp` | inbound | FTP and its passive range. | | FeatherQuilld | `80/tcp`, `443/tcp` | inbound | Websites through the managed reverse proxy. | | FeatherQuilld | `587/tcp`, `993/tcp` (and `25/tcp` for inbound mail) | inbound | Mail, if a mail backend is installed. See [Mail](https://featherpanel.com/docs/quilld/mail). | | Proxmox | `8006/tcp` | from the panel | Proxmox API for VDS nodes. | The panel must reach every node API, and browsers must reach Wings and Quilld directly for console websockets and file transfers. Put the daemons behind TLS (Let's Encrypt from the installer's SSL menu, or your own certificate) when the panel is served over HTTPS; browsers block mixed content. When the installer configures a firewall it only touches rules of an **existing** `ufw` or `iptables` setup. It opens 80 and 443 and closes the panel port if it finds a reverse proxy, or opens the panel port when there is none. ## Domains and TLS - One domain (or subdomain) for the panel, e.g. `panel.example.com`. - One per node is recommended, e.g. `node1.example.com`, so Wings and Quilld can have their own certificates. - The installer's **SSL** menu issues Let's Encrypt certificates with certbot. See [SSL](https://featherpanel.com/docs/panel/ssl). ## Next steps - [Quick start](https://featherpanel.com/docs/getting-started/quick-start) - [Panel installation](https://featherpanel.com/docs/panel/installation) - [Architecture](https://featherpanel.com/docs/getting-started/architecture) ## Frequently asked questions ### Which Linux distributions does FeatherPanel support? The installer supports Debian 11, 12 and 13 and Ubuntu 22.04, 24.04, 25.04, 25.10 and 26.04 (20.04 also passes the check). Other distributions need --skip-os-check and are not supported. ### Does FeatherPanel run on ARM? Yes. All images are published for amd64 and arm64. Older ARM (armv6, armv7) only works through QEMU emulation of the amd64 images, which the installer offers to set up. ### Can I run FeatherWings in an LXC or OpenVZ container? The installer refuses OpenVZ, Virtuozzo and LXC by default because Docker does not work reliably there. Use a KVM, VMware, Xen or bare metal machine, or pass --skip-virt-check at your own risk. --- # Quick start > Install FeatherPanel with the installer script, create the admin account, add a FeatherWings node and start your first game server in one sitting. Source: https://featherpanel.com/docs/getting-started/quick-start/ This page takes you from an empty server to a running game server. It uses the defaults everywhere; the linked pages explain the alternatives. You need: - A Debian 11-13 or Ubuntu 22.04+ server for the panel (see [Requirements](https://featherpanel.com/docs/getting-started/requirements)). - A second server for game servers (it can be the same machine for testing). - A domain pointing at each server if you want HTTPS (optional for a home lab). - Root access. ## 1. Install the panel Run the installer as root: ```bash curl -sSL https://get.featherpanel.com/installer.sh | bash ``` In the menus pick: 1. `[1] Panel` (Web Interface) 2. `[1] Install Panel` 3. `[1] Docker Mode`. Source mode exists for developers; see [Source install](https://featherpanel.com/docs/panel/installation/source). 4. A release type: `[1] Stable Release` for production. 5. An access method: | Choice | When to use it | |--------|----------------| | Cloudflare Tunnel | HTTPS through Cloudflare, no open ports. Full automatic (API key) or with a tunnel token. | | Nginx reverse proxy | Classic setup on a VPS with a domain. | | Apache2 reverse proxy | If Apache already runs on the host. | | Direct access | Home lab or testing: `http://YOUR_IP:4831`, no domain or TLS. | The installer installs Docker if needed, downloads `docker-compose.yml` to `/var/www/featherpanel`, starts the containers and, for nginx or Apache, writes the site config and offers a Let's Encrypt certificate. The full walkthrough is in [Docker installation](https://featherpanel.com/docs/panel/installation/docker). > [!TIP] > Every menu choice can also be passed as environment variables for unattended installs, for example > `FP_COMPONENT=panel FP_ACTION=install`. See the [installer reference](https://featherpanel.com/docs/cli/installer). ## 2. Create the administrator Wait about five minutes for the first start, then open the panel URL and register. > [!IMPORTANT] > The first account that registers on a new panel becomes the administrator. Register it yourself before you share > the URL. When the administrator opens the admin area of a fresh install, the panel sends them to the setup wizard (`/setup`). Its steps are: 1. **Welcome**: the panel URL and name. 2. **Time and language**: timezone and default language. 3. **Mail**: SMTP, optional but needed for password resets and verification mails. 4. **Modules**: game servers, VDS and web hosting. 5. **Security basics**: who can register and how admins sign in. 6. **Location and node**: your first location and node (the next two steps below do the same by hand). You can choose to finish later; a banner reminds you. Everything is editable afterwards in **Admin → Settings**. ## 3. Add a location and a node 1. **Admin → Locations → Create**. Pick the game server type. Nodes can only be added to a location of the matching type. 2. **Admin → Nodes → Create**. Enter a name, the node's FQDN (or IP), the location, whether the node uses SSL, and the memory and disk the node may hand out. Keep the daemon type FeatherWings (it cannot be changed after creation) and the ports at their defaults (API `8080`, SFTP `2022`) unless you have a reason. 3. Open the node's Wings configuration. The Quick setup box shows two commands. ## 4. Install FeatherWings on the node On the game node, run step 1 (it installs FeatherWings only): ```bash curl -sSL https://get.featherpanel.com/installer.sh | env FP_COMPONENT=wings FP_ACTION=install FP_WINGS_SKIP_CONFIGURE=true bash ``` Then run step 2, the setup wizard, exactly as the panel shows it. It looks like this: ```bash featherwings configure --join-data '' --override --install-service ``` The wizard connects to the panel, checks DNS, issues an SSL certificate when the node needs one, writes `/etc/featherpanel/config.yml` and starts the `featherwings` service. Back in the panel the node turns green within a few seconds. Details and the manual path are in [Install Wings](https://featherpanel.com/docs/wings/installation). ## 5. Add allocations Open the node's Allocations tab and add the IP and ports that servers may use, for example `0.0.0.0` with ports `25565-25575`. ## 6. Create a server 1. **Admin → Servers → Create**. 2. Pick the owner, the node, an allocation, a realm and spell (FeatherPanel's names for nest and egg), and the CPU, memory and disk limits. 3. Save. Wings pulls the Docker image and runs the install script; follow it on the server's console. Open Servers in the user area, start the server and connect. ## Next steps - Put the panel behind HTTPS: [Web server](https://featherpanel.com/docs/panel/web-server) and [SSL](https://featherpanel.com/docs/panel/ssl). - Coming from Pterodactyl? [Migrate from Pterodactyl](https://featherpanel.com/docs/migrating/pterodactyl). - Set up mail so password resets work: [Notifications and mail](https://featherpanel.com/docs/admin/notifications-and-mail). - Back up the panel: [Panel backups](https://featherpanel.com/docs/panel/backups). - Offer web hosting: [Install FeatherQuilld](https://featherpanel.com/docs/quilld/installation). ## Frequently asked questions ### How do I install FeatherPanel? Run curl -sSL https://get.featherpanel.com/installer.sh | bash as root on Debian or Ubuntu, choose Panel, then Install, pick Docker mode and an access method. Open the panel URL and register the first account, which becomes the administrator. ### Who becomes the FeatherPanel administrator? The first account that registers on a fresh panel is promoted to the Administrator role. Register it yourself right after the install finishes. ### How long does the first start take? The installer tells you to wait about five minutes after the containers start, while the backend runs its database migrations and the frontend warms up. --- # Migrating > Move to FeatherPanel from Pterodactyl, or move an existing FeatherPanel install or FeatherWings node to a new machine. Pick the guide that matches your move. Source: https://featherpanel.com/docs/migrating/ There are two kinds of migration. Pick the one that matches your situation. | You want to | Guide | Tool | |-------------|-------|------| | Replace a Pterodactyl panel with FeatherPanel, keeping users, nodes, eggs, servers and backups | [From Pterodactyl](https://featherpanel.com/docs/migrating/pterodactyl) | `feathercli migrate` | | Move a FeatherPanel install or a FeatherWings node to another machine | [Move to a new host](https://featherpanel.com/docs/migrating/between-hosts) | Installer export and import | ## Before you start - Take a backup of the source panel database and the node data. See [Backups and snapshots](https://featherpanel.com/docs/panel/backups). - Check that the target machine meets the [requirements](https://featherpanel.com/docs/getting-started/requirements). - Read [FeatherPanel vs Pterodactyl](https://featherpanel.com/docs/featherpanel-vs-pterodactyl) if you want to know what changes for your users. --- # Migrating from Pterodactyl > Move a Pterodactyl panel to FeatherPanel with feathercli migrate. What is imported, the 15 migration steps, and how to switch each node from Wings to FeatherWings. Source: https://featherpanel.com/docs/migrating/pterodactyl/ FeatherPanel imports a Pterodactyl panel through the Pterodactyl Migration Agent, which is the `migrate` command of [FeatherCli](https://featherpanel.com/docs/cli/feathercli). The agent reads the Pterodactyl database and sends the data to the importer endpoints of your new panel. The direct HTTP import in older versions is gone. > [!IMPORTANT] > Back up the Pterodactyl database and `.env` before you start. The migration only reads from Pterodactyl, but it puts the > panel into maintenance mode. ## What is imported The migration runs 15 steps in this order and records progress in `.migration-progress.json` in the current directory, so an interrupted run can resume: 1. Panel settings 2. Locations 3. Nests, as [realms](https://featherpanel.com/docs/admin/realms-and-spells) 4. Eggs and their variables, as [spells](https://featherpanel.com/docs/spells) 5. Nodes 6. Database hosts 7. Allocations 8. Users, with their bcrypt password hashes 9. SSH keys 10. Servers and server variables, keeping their UUIDs 11. Server databases 12. Backups 13. Subusers 14. Schedules 15. Schedule tasks The migration decrypts values Pterodactyl stored with its `APP_KEY`, which is why it needs the Pterodactyl `.env` or the key itself. If [Blueprint](https://blueprint.zip) is installed on the Pterodactyl panel, the agent warns that its database changes may break the migration and asks you to confirm with `--confirm-blueprint`. ## 1. Prepare FeatherPanel [Install FeatherPanel](https://featherpanel.com/docs/panel/installation) on a new server or next to Pterodactyl, and register the first account. Do not create nodes, locations or servers: the importer checks that the panel has at most one user and nothing else. Open `/admin/pterodactyl-importer`. The page shows the prerequisite check, lets you create an API key for the agent, and lists the commands below. The key needs the `admin.root` permission. ## 2. Install and configure FeatherCli On the Pterodactyl server: ```bash curl -sSL https://get.featherpanel.com/stable.sh | bash # choose [3] CLI feathercli config setup # panel URL and the API key from step 1 feathercli config test ``` ## 3. Run the migration
```bash feathercli migrate check --pterodactyl-dir /var/www/pterodactyl feathercli migrate --pterodactyl-dir /var/www/pterodactyl ``` The agent reads `/var/www/pterodactyl/.env`, connects to the Pterodactyl database and runs `php artisan down` to stop changes during the import. If that fails it asks you to run it yourself.
For a Dockerised Pterodactyl, export the database and `.env`, then let the agent load the dump into a staging MySQL server it can reach: ```bash docker compose exec database mariadb-dump -u root -p"$MARIADB_ROOT_PASS" panel > panel.sql docker compose exec panel cat /app/var/.env > panel.env feathercli migrate \ --sql-dump ./panel.sql \ --env-file ./panel.env \ --staging-db-host 127.0.0.1 \ --staging-db-user root \ --staging-db-password 'your-mysql-password' ``` Use `--app-key` instead of `--env-file` if you only have the key. `--sql-dump` and `--pterodactyl-dir` cannot be combined.
| Flag | Meaning | |------|---------| | `--confirm-migrate` | Skip the final confirmation | | `--confirm-blueprint` | Continue although Blueprint is installed | | `--reset` | Forget saved progress and start from step 1 | | `--staging-db-port` | Port of the staging database | ## 4. Switch each node to FeatherWings The migration moves data, not daemons. Right after it finishes, do this on every node: ```bash sudo systemctl disable --now wings curl -sSL https://get.featherpanel.com/installer.sh | bash # choose [2] Wings, install only ``` Then get the node's configuration from FeatherPanel (the node page in the admin area) and apply it with `featherwings configure --join-data ... --override`, or place it in `/etc/featherpanel/config.yml`, and start the service: ```bash sudo systemctl enable --now featherwings ``` Imported nodes keep their data directory, so FeatherWings finds the existing server files in `/var/lib/pterodactyl/volumes` without copying anything. Server UUIDs are unchanged. ## After the migration - Sign in with a migrated user and open a few servers: console, files, backups. - Check that every node is green and that schedules run. - Point your domain at FeatherPanel when you are satisfied, and keep the Pterodactyl backup for a while. - If you used the Pterodactyl API in other tools, read the [API reference](https://featherpanel.com/docs/api/reference). The agent's closing message recommends a Pterodactyl API compatibility plugin for existing integrations. For a side by side comparison of the two panels, see [FeatherPanel vs Pterodactyl](https://featherpanel.com/docs/featherpanel-vs-pterodactyl). ## Frequently asked questions ### Do users need new passwords after migrating from Pterodactyl? No. Pterodactyl stores bcrypt password hashes and the migration copies them unchanged, so users sign in to FeatherPanel with their existing passwords. ### Are server files copied during the migration? No. Server files stay on the nodes. Imported nodes keep Pterodactyl's data directory (/var/lib/pterodactyl/volumes by default), and FeatherWings uses it once you switch the node over. ### Can I migrate into a FeatherPanel that already has servers? No. The importer requires a clean panel with at most one user and no nodes, locations, realms, spells, servers, databases or allocations. --- # Moving to a new server > Move a FeatherPanel install or a FeatherWings node to another machine with the installer's Export for Migration and Import Migration tools. Source: https://featherpanel.com/docs/migrating/between-hosts/ The installer can package a whole Docker install of the panel, or a whole FeatherWings node, into one archive and restore it on another machine. This page covers both. To move from Pterodactyl instead, read [Migrating from Pterodactyl](https://featherpanel.com/docs/migrating/pterodactyl). > [!WARNING] > Both tools copy live files. For a consistent database copy, stop users from making changes during the export, and > keep a separate [database dump](https://featherpanel.com/docs/panel/backups) as a fallback. ## Move the panel ### 1. Export on the old server Run the installer and open **Panel → Backup Manager → Export for Migration**: ```bash curl -sSL https://get.featherpanel.com/installer.sh | bash ``` The containers must be running. The installer: - exports every Docker volume used by the `mysql`, `backend` and `redis` containers (database files, config with the encryption key, attachments, snapshots, Redis data) as `.tar.gz` files, - copies `docker-compose.yml` and `.env`, - writes `migration_info.txt` (it looks up the server's public IP with `ifconfig.me`) and `README_MIGRATION.txt`, - packs everything into `/var/www/featherpanel/migrations/featherpanel_migration_YYYYMMDD_HHMMSS.tar.gz` with mode 600. ### 2. Copy the archive From the new server: ```bash mkdir -p /var/www/featherpanel/migrations scp root@OLD_SERVER:/var/www/featherpanel/migrations/featherpanel_migration_*.tar.gz /var/www/featherpanel/migrations/ ``` `rsync -avz` works the same way. ### 3. Import on the new server Run the installer and open **Panel → Backup Manager → Import Migration**. It lists archives in `/var/www/featherpanel/migrations` and up to two levels below `/root` and `/home`, or asks for a path. Type `yes` to confirm. - If the panel is not installed yet, the installer installs Docker, restores `docker-compose.yml` and `.env` from the package, restores the volumes and starts the stack. - If a panel is installed, it runs `docker compose down`, replaces every volume with the imported data and starts the containers again. Everything that was on the new server is lost. ### 4. Finish the move The import does not configure a web server or certificates. On the new server: 1. Point your DNS record at the new IP. 2. Set up the [web server](https://featherpanel.com/docs/panel/web-server) and [SSL](https://featherpanel.com/docs/panel/ssl), or a [Cloudflare Tunnel](https://featherpanel.com/docs/panel/web-server/cloudflare-tunnel). 3. Sign in and check that servers, nodes and settings look right. Nodes keep working without changes as long as the panel URL stays the same. If the URL changes, change it in the panel settings and re-run `featherwings configure` on each node so the node talks to the new address. ## Move a FeatherWings node ### Export In the installer open **Wings → Backup Manager → Export for Migration**, or run: ```bash featherwings node-backup export --out /var/lib/featherpanel/wings_migrations ``` The installer stops the `featherwings` service during the export and starts it again afterwards. If the CLI export is not available it falls back to a tar archive with the server volumes, local backups and `config.yml`, named `featherwings_migration_YYYYMMDD_HHMMSS.tar.gz`. ### Import 1. [Install FeatherWings](https://featherpanel.com/docs/wings/installation) on the new machine. 2. Copy the archive to `/var/lib/featherpanel/wings_migrations/`. 3. Run the installer's **Wings → Backup Manager → Import Migration**, or: ```bash featherwings node-backup import --file /var/lib/featherpanel/wings_migrations/featherwings_migration_XXXX.tar.gz ``` 4. Start FeatherWings and, if the IP or hostname changed, update the node's FQDN in **Admin → Nodes**. Game ports are bound to the node's IP addresses. If the new machine has different IPs, update the allocations too. ## Related - [Backups](https://featherpanel.com/docs/panel/backups) - [Updating the panel](https://featherpanel.com/docs/panel/updating) - [Uninstall](https://featherpanel.com/docs/panel/uninstall) ## Frequently asked questions ### Does the migration package include the encryption key? Yes. The panel package contains every FeatherPanel Docker volume, including featherpanel_config with DATABASE_ENCRYPTION_KEY, plus docker-compose.yml and .env. Treat the archive as a secret. ### Do I need to install FeatherPanel on the new server first? No. Import Migration installs Docker and the panel with the imported data when it finds no existing install. If a panel is already there, its data is replaced. --- # Running the panel > The FeatherPanel operator guide in one place. Install the panel, put it behind a web server with SSL, configure workers and settings, update it and back it up. Source: https://featherpanel.com/docs/panel/ These pages cover the panel host: the machine that runs the FeatherPanel web app, its database and its workers. Game nodes are covered in [FeatherWings](https://featherpanel.com/docs/wings) and web hosting nodes in [FeatherQuilld](https://featherpanel.com/docs/quilld). ## Install | Page | Covers | |------|--------| | [Installation overview](https://featherpanel.com/docs/panel/installation) | Every install method and how to choose | | [Docker (installer)](https://featherpanel.com/docs/panel/installation/docker) | The recommended path on Debian and Ubuntu | | [All-in-one image](https://featherpanel.com/docs/panel/installation/all-in-one) | One container with everything inside | | [Source install](https://featherpanel.com/docs/panel/installation/source) | Manual install without Docker | | [Windows (Docker Desktop)](https://featherpanel.com/docs/panel/installation/windows) | Running the panel on Windows | | [Web server](https://featherpanel.com/docs/panel/web-server) | Nginx, Apache, Caddy or a Cloudflare Tunnel in front of the panel | | [SSL certificates](https://featherpanel.com/docs/panel/ssl) | Let's Encrypt through the installer | ## Configure and operate | Page | Covers | |------|--------| | [Cron and workers](https://featherpanel.com/docs/panel/cron-and-workers) | Scheduled jobs and the async runner | | [Environment variables](https://featherpanel.com/docs/panel/environment-variables) | Every variable the backend reads | | [Settings reference](https://featherpanel.com/docs/panel/settings) | Every setting in the admin area | | [Realtime (Mercure)](https://featherpanel.com/docs/panel/realtime) | Live updates and the polling fallback | | [MCP server](https://featherpanel.com/docs/panel/mcp-server) | Let AI clients manage the panel | | [Updating](https://featherpanel.com/docs/panel/updating) | Updates with the installer, the admin area or Docker Compose | | [Backups and snapshots](https://featherpanel.com/docs/panel/backups) | What to back up and how to restore | | [Uninstalling](https://featherpanel.com/docs/panel/uninstall) | Removing the panel cleanly | After the panel runs, the [admin guide](https://featherpanel.com/docs/admin) explains users, nodes, servers and the rest of the admin area. --- # Install the panel > Choose how to install FeatherPanel. The installer script with Docker Compose is the supported path; source mode exists for development. Source: https://featherpanel.com/docs/panel/installation/ FeatherPanel ships as a set of container images. The installer script runs them with Docker Compose and is the path this documentation assumes. There are two install modes: | Mode | What runs where | Use it for | |------|-----------------|------------| | Docker (recommended) | MariaDB, Redis, backend, frontend, MCP server and async runner in containers from `ghcr.io/mythicalltd` | Production and most test installs | | Source | The backend under FrankenPHP, the Next.js frontend and the Rust async runner built on the host, as systemd services | Developing FeatherPanel itself | The installer prints "Docker (recommended for most users)" next to the Docker mode and shows a support warning before a source install. ## Before you start Check the [requirements](https://featherpanel.com/docs/getting-started/requirements): a 64-bit Debian or Ubuntu server, root access, and a domain name if you want HTTPS. The panel listens on port `4831` on the host. You put a reverse proxy or a Cloudflare Tunnel in front of it, or open it directly for a home lab. ## Run the installer ```bash curl -sSL https://get.featherpanel.com/installer.sh | bash ``` Pick `[1] Panel`, then `Install Panel`. The installer asks for: 1. The install mode, Docker or source. 2. The release type: Stable Release, Development Build (latest `develop` images) or Development Build (Custom) for a specific branch and commit. 3. The access method: Cloudflare Tunnel, Nginx reverse proxy, Apache2 reverse proxy or direct access on `http://YOUR_IP:4831`. The rest of the install is described in [Docker installation](https://featherpanel.com/docs/panel/installation/docker). ## After the install - Register the first account. It becomes the administrator. - Put HTTPS in front of the panel if you did not pick it during the install: see [Web server](https://featherpanel.com/docs/panel/web-server) and [SSL certificates](https://featherpanel.com/docs/panel/ssl). - Add a node: [Install FeatherWings](https://featherpanel.com/docs/wings/installation). - Read [Updating](https://featherpanel.com/docs/panel/updating) and [Backups](https://featherpanel.com/docs/panel/backups) before you put real users on the panel. ## Frequently asked questions ### What is the recommended way to install FeatherPanel? Run the installer script as root on Debian or Ubuntu and choose Docker mode. It downloads docker-compose.yml to /var/www/featherpanel, starts the containers and can set up nginx, Apache or a Cloudflare Tunnel in front of them. ### Can I install FeatherPanel without Docker? The installer has a source mode that builds the backend, frontend and async runner on the host and runs them as systemd services. The installer marks it as a mode for developers; Docker mode is the one it recommends for most users. --- # Docker installation > Install FeatherPanel with Docker Compose, by the installer script or by hand. Covers the services, volumes, ports, .env values and the first start. Source: https://featherpanel.com/docs/panel/installation/docker/ ## With the installer Run the installer as root and choose `[1] Panel`, then `Install Panel`, then Docker mode: ```bash curl -sSL https://get.featherpanel.com/installer.sh | bash ``` The installer then: 1. Updates the system and installs `curl`, `unzip`, `jq` and `socat`, and Docker if it is missing. 2. Creates `/var/www/featherpanel` and `/var/www/featherpanel/backups`. 3. Writes a random `DOCKER_UPDATER_TOKEN` to `/var/www/featherpanel/.env` and installs the `featherpanel-docker-updater` systemd service (see [Updating](https://featherpanel.com/docs/panel/updating)). 4. Downloads `docker-compose.yml` from the `main` branch (or `docker-compose.v2.dev.yml` for development builds) and applies the panel port. 5. Stops any old FeatherPanel containers and runs `docker compose up -d`. 6. Sets up the access method you picked: a Cloudflare Tunnel, or an nginx or Apache site from the templates in [Web server](https://featherpanel.com/docs/panel/web-server) with an optional Let's Encrypt certificate. 7. Installs the `featherpanel` command in `/usr/local/bin`, which runs `php cli` inside the backend container. See [Panel CLI](https://featherpanel.com/docs/cli/panel). Wait about five minutes, open the panel and register. The first account becomes the administrator. ### Unattended installs Every menu choice can be passed as an environment variable. The full list is in the [installer reference](https://featherpanel.com/docs/cli/installer). For example: ```bash curl -sSL https://get.featherpanel.com/installer.sh | env FP_COMPONENT=panel FP_ACTION=install bash ``` ## By hand You can run the same Compose file without the installer. ```bash mkdir -p /var/www/featherpanel && cd /var/www/featherpanel curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/MythicalLTD/FeatherPanel/main/docker-compose.yml ``` Create `/var/www/featherpanel/.env` before the first start. Compose reads it for the variables below; every one has a default in the Compose file. ```ini MARIADB_ROOT_PASSWORD=change-me MARIADB_DATABASE=featherpanel MARIADB_USER=featherpanel MARIADB_PASSWORD=change-me-too REDIS_PASSWORD=change-me-three FEATHERPANEL_PANEL_PORT=4831 ``` > [!WARNING] > The `mysql` health check in `docker-compose.yml` runs `mariadb-admin ping` with the literal password > `featherpanel_root`. If you change `MARIADB_ROOT_PASSWORD`, change the `-p` argument of that health check too, or the > database never reports healthy and the other services never start. > [!NOTE] > MariaDB only reads `MARIADB_*` values when it initialises an empty volume. Changing them later does not change the > passwords of an existing database. Start the stack: ```bash docker compose up -d docker compose ps ``` ## What runs | Service | Image | Role | |---------|-------|------| | `mysql` | `mariadb:latest` | Database. Not published on the host. | | `redis` | `redis:latest` | Cache, sessions and queues, with append-only persistence and a password. | | `backend` | `featherpanel-backend` | PHP API under FrankenPHP (worker mode by default) and the cron runner, both managed by supervisord. | | `frontendv2` | `featherpanel-frontendv2` | Next.js frontend. Publishes `${FEATHERPANEL_PANEL_PORT:-4831}:80` and proxies `/api` to the backend. | | `mcp` | `featherpanel-mcp` | [MCP server](https://featherpanel.com/docs/panel/mcp-server) on port 3001 inside the network. | | `async-runner` | `featherpanel-async-runner` | Rust worker for background jobs. See [Cron and workers](https://featherpanel.com/docs/panel/cron-and-workers). | All images are published for `amd64` and `arm64`. On 32-bit ARM the installer sets up QEMU emulation. Only the frontend publishes a port. The backend reaches the host's updater service through `host.docker.internal:9418`. ## Volumes | Volume | Mounted at | Contents | |--------|-----------|----------| | `mariadb_data` | `/var/lib/mysql` | The database | | `redis_data` | `/data` | Redis append-only file | | `featherpanel_config` | `/var/www/html/storage/config` | The backend `.env`, including `DATABASE_ENCRYPTION_KEY` | | `featherpanel_attachments` | `/var/www/html/public/attachments` | Uploaded files | | `featherpanel_snapshots` | `/var/www/html/storage/backups` | Panel snapshots | | `featherpanel_logs` | `/var/www/html/storage/logs` | Logs, shared with the async runner | | `featherpanel_translations` | `/var/www/html/public/translations` | Translation files | | `featherpanel_addons` | `/var/www/html/storage/addons` | Installed plugins | | `featherpanel_data` | `/var/www/html/storage/data` | Runtime data | | `featherpanel_pma` | `/var/www/html/public/pma` | phpMyAdmin files | | `featherpanel_webmail` | `/var/www/html/public/webmail` | Webmail files | | `mcp_oauth_data` | `/data` | MCP OAuth store | > [!DANGER] > `featherpanel_config` holds the key that encrypts secrets in the database. A database backup without this volume cannot > decrypt them. Back up both. See [Backups](https://featherpanel.com/docs/panel/backups). Compose prefixes volume names with the project name, so on an installer host they appear as `featherpanel_mariadb_data`, `featherpanel_featherpanel_config` and so on. ## Backend environment The Compose file sets these on the backend container. You rarely need to change them. | Variable | Value | Meaning | |----------|-------|---------| | `DATABASE_HOST`, `DATABASE_PORT` | `mysql`, `3306` | Database inside the Compose network | | `DATABASE_ENCRYPTION` | `xchacha20` | Cipher for encrypted columns | | `TRUST_PROXY_HEADERS` | `true` | Read the client IP from `X-Forwarded-For` | | `PANEL_DOCKER_DEPLOYMENT` | `true` | Enables Docker-only actions such as the in-panel update button | | `FRANKENPHP_WORKER` | `true` | Set `false` for classic (non-worker) PHP mode | | `DOCKER_UPDATER_URL`, `DOCKER_UPDATER_TOKEN` | `http://host.docker.internal:9418/update`, from `.env` | Host updater used by the update button | The full list of variables the backend reads is in [Environment variables](https://featherpanel.com/docs/panel/environment-variables). ## Check that it works ```bash cd /var/www/featherpanel docker compose ps curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4831/ ``` All services should show `healthy`. If the backend restarts in a loop, read its log with `docker compose logs backend` and see [Troubleshooting](https://featherpanel.com/docs/troubleshooting). ## Frequently asked questions ### Which port does FeatherPanel use? The frontend container publishes port 4831 on the host by default. Set FEATHERPANEL_PANEL_PORT in /var/www/featherpanel/.env, or the panel port in the installer's Configuration menu, to change it. ### Where does the Docker install live? The installer keeps docker-compose.yml, .env, install.log and the backups folder in /var/www/featherpanel. Application data lives in named Docker volumes whose names start with featherpanel_. ### How long does the first start take? The installer asks you to wait about five minutes. The backend health check allows a 180 second start period while it runs database migrations. --- # All-in-one image > Run FeatherPanel as a single container with the featherpanel-oci image. MariaDB, Redis, backend, frontend, async runner and cron in one image with one data volume. Source: https://featherpanel.com/docs/panel/installation/all-in-one/ The `featherpanel-oci` image packs MariaDB, Redis, the PHP backend, the Next.js frontend, the async runner and cron into one container, managed by supervisord. Use it when a platform can only run a single container. Otherwise prefer the [Docker Compose install](https://featherpanel.com/docs/panel/installation/docker). Release builds are published for `linux/amd64` and `linux/arm64` as `ghcr.io/mythicalltd/featherpanel-oci`, tagged with the version and `latest`. ## Run it ```bash docker run -d --name featherpanel \ -p 80:80 \ -v featherpanel_data:/home/container/data \ -e FEATHERPANEL_ADMIN_EMAIL=admin@example.com \ -e FEATHERPANEL_ADMIN_USERNAME=admin \ -e FEATHERPANEL_ADMIN_PASSWORD='choose-a-strong-password' \ --restart unless-stopped \ ghcr.io/mythicalltd/featherpanel-oci:latest ``` The first start initialises MariaDB, writes `config/.env` with a new database encryption key and runs migrations. The health check calls `/api/system/health`. Put a reverse proxy with TLS in front, see [Web server](https://featherpanel.com/docs/panel/web-server). > [!WARNING] > `config/.env` in the data volume holds `DATABASE_ENCRYPTION_KEY`. Losing it makes encrypted data unreadable. Back up > the whole volume. ## Environment variables | Variable | Default | Notes | | --- | --- | --- | | `DATABASE_DATABASE`, `DATABASE_USER`, `DATABASE_PASSWORD` | from the image | Used for the bundled MariaDB and written to `.env` on first start. | | `REDIS_PASSWORD` | from the image | Password of the bundled Redis. | | `MARIADB_ROOT_PASSWORD` | from the image | Root password of the bundled MariaDB. | | `FEATHERPANEL_ADMIN_EMAIL`, `FEATHERPANEL_ADMIN_USERNAME`, `FEATHERPANEL_ADMIN_PASSWORD` | empty password | First admin, created only when a password is set and no users exist. | | `ENABLE_MARIADB`, `ENABLE_REDIS`, `ENABLE_BACKEND`, `ENABLE_FRONTEND`, `ENABLE_ASYNC_RUNNER`, `ENABLE_CRON` | `true` | Set to `false` to skip a service. | | `FRANKENPHP_WORKER` | `true` | FrankenPHP worker mode for `/api/*`. `false` uses classic mode. | | `FEATHERPANEL_APP_URL` | empty | Shown in the container's login banner. | Set the passwords before the first start. The database user is created on the first start and keeps that password. ## Data volume | Path in `/home/container/data` | Content | | --- | --- | | `mysql`, `redis` | Database and cache files | | `config` | `.env` | | `attachments`, `uploads`, `translations`, `addons`, `pma` | Attachments, uploads, translations, plugins and phpMyAdmin | | `logs`, `backups` | Panel logs and backups | Plugin symlinks are rebuilt on every start, so plugins survive image updates. ## Running as a game server The image also starts as a non-root user, for example as a server on a [FeatherWings](https://featherpanel.com/docs/wings) node. In that mode MariaDB and Redis run as the current user and cron is turned off. ## Commands `featherpanel` inside the container runs the [panel CLI](https://featherpanel.com/docs/cli/panel): ```bash docker exec -it featherpanel featherpanel help ``` ## Updating Pull the new image and recreate the container with the same volume. Migrations run on start. To build the image yourself, run `deploy/oci/build.sh` from a FeatherPanel checkout. ## Frequently asked questions ### Should I use the all-in-one image in production? The multi-container Docker install is easier to update and inspect, and is what the installer sets up. The all-in-one image suits platforms that only run one container, and quick tests. ### Where is my data? Everything lives in /home/container/data inside the container. Mount a volume there or the data is lost when the container is replaced. ### How do I create the first admin? Set FEATHERPANEL_ADMIN_PASSWORD (and optionally the email and username) before the first start, or register in the browser. The first account becomes the administrator. --- # Source install > What the FeatherPanel source install does, which packages and services it sets up, where its files live, and what it cannot do that the Docker install can. Source: https://featherpanel.com/docs/panel/installation/source/ The source install puts the panel's code in `/var/www/featherpanel` and runs every part as a native service. It exists for people who want to change the code. For anything else, use the [Docker install](https://featherpanel.com/docs/panel/installation/docker). > [!WARNING] > The installer shows this notice before a source install: support is not guaranteed, and these features do not work > in source mode: panel backups through the installer, migration export and import to another server, and backup > restore through the installer. Plan your own [database backups](https://featherpanel.com/docs/panel/backups). ## Run the installer ```bash curl -sSL https://get.featherpanel.com/installer.sh | bash ``` Choose **Panel → Install**, then **[2] Source Mode**. Set `FP_PANEL_MODE=source` to skip the question. The installer downloads its source sub-scripts from the `main` branch on GitHub (or `develop` when you use the dev channel) and runs them in this order. ### 1. Prerequisites (`debian.bash` or `ubuntu.bash`) - Adds the sury.org PHP repository (Debian) or the matching PPA (Ubuntu), the Redis repository and the MariaDB repository. - Installs PHP `8.5` (override with `PHP_VERSION`) with the `cli`, `gd`, `mysql`, `mbstring`, `bcmath`, `xml`, `curl`, `zip`, `redis`, `mongodb`, `pgsql`, `sqlite3`, `ldap`, `bz2`, `gmp`, `imagick` and `yaml` extensions. - Installs `mariadb-server`, `nginx`, `redis-server`, `git`, `make` and Composer. ### 2. Toolchains (`universal.bash`) Installs nvm `v0.40.4` with the current Node.js LTS and pnpm, and the Rust toolchain for the async runner. ### 3. Panel (`init/panel.bash`) 1. Clones the repository to `/var/www/featherpanel`. Stable installs check out the latest release tag; the dev channel uses the `develop` branch. 2. Runs `composer install` in `backend` and `pnpm install` in `frontendv2`. 3. Creates the `featherpanel` database and user. The password is reused from an existing `.env` or generated with `openssl rand -hex 24`. 4. Writes `backend/storage/config/.env` with the database settings, `DATABASE_ENCRYPTION=xchacha20`, a new `DATABASE_ENCRYPTION_KEY` (kept if one already exists) and the Redis settings. 5. Runs the database migrations with `php app migrate`. 6. Installs FrankenPHP as `featherpanel-backend.service` on `127.0.0.1:8721` in worker mode with the Mercure hub. 7. Builds the Rust async runner and installs `featherpanel-async-runner.service`. 8. Writes the nginx site `/etc/nginx/sites-available/FeatherPanel.conf`, or sets up a Cloudflare Tunnel. 9. Writes `/etc/cron.d/featherpanel`, which runs `runner.bash` and `runner.php` every minute as `www-data`. 10. Builds the frontend with `pnpm build` and installs `featherpanel-next.service` on port 3000. > [!WARNING] > The Redis password defaults to a fixed value when `REDIS_PASSWORD` is not set. Set your own before you run the > installer, or change it in Redis and in `backend/storage/config/.env` afterwards. ## Layout | Path or unit | Purpose | |--------------|---------| | `/var/www/featherpanel` | Git checkout of the panel | | `backend/storage/config/.env` | Database, encryption key and Redis settings | | `featherpanel-backend.service` | FrankenPHP serving `/api`, Mercure, phpMyAdmin and webmail on `127.0.0.1:8721` | | `featherpanel-next.service` | Next.js frontend on port 3000 | | `featherpanel-async-runner.service` | Rust worker for background jobs | | `/etc/cron.d/featherpanel` | Cron runner every minute | | `/etc/nginx/sites-available/FeatherPanel.conf` | Proxies `/api`, `/pma`, `/webmail`, `/attachments`, `/addons` and `/components` to the backend and everything else to port 3000 | Check them with: ```bash systemctl status featherpanel-backend featherpanel-next featherpanel-async-runner ``` ## Installer variables `init/panel.bash` reads these variables, so you can set them before running it: | Variable | Default | |----------|---------| | `PANEL_DIR` | `/var/www/featherpanel` | | `PANEL_REPO` | `https://github.com/mythicalltd/featherpanel.git` | | `FRONTEND_MODE` | `build`, or `skip` to skip the build (`watch` calls a `pnpm watch` script that `frontendv2` does not define) | | `DB_NAME`, `DB_USER` | `featherpanel` | | `DB_HOST`, `DB_PORT` | `127.0.0.1`, `3306` | | `DB_PASSWORD` | Reused or generated | | `REDIS_HOST` | `127.0.0.1` | | `MARIADB_ROOT_PASSWORD` | Empty (socket auth as root) | ## Updating and removing Run the installer again and choose **Update**. In source mode it runs `init/update.bash`, which discards local changes in the checkout, so keep your modifications in a fork or a plugin. See [Updating](https://featherpanel.com/docs/panel/updating) and [Uninstall](https://featherpanel.com/docs/panel/uninstall). ## Next steps - [Set up SSL](https://featherpanel.com/docs/panel/ssl) - [Cron and workers](https://featherpanel.com/docs/panel/cron-and-workers) - [Install FeatherWings](https://featherpanel.com/docs/wings/installation) ## Frequently asked questions ### Is the source install supported? No. The installer warns that support is not guaranteed for source installs. Use it if you need the panel code on disk to modify it. Everyone else should use the Docker install. ### Which PHP version does the source install use? PHP 8.5 from the sury.org repository by default, set by PHP_VERSION in the prerequisite script. The web backend runs under FrankenPHP with its own PHP build; cron and the CLI use the distribution PHP. --- # Windows (Docker Desktop) > Install FeatherPanel on Windows with the PowerShell installer and Docker Desktop. Covers the menu, the C:\featherpanel folder, port 4831, updates, backups and FeatherCli. Source: https://featherpanel.com/docs/panel/installation/windows/ The PowerShell installer (`install.ps1`) runs the panel in Docker Desktop with the same `docker-compose.yml` as the [Linux Docker install](https://featherpanel.com/docs/panel/installation/docker). It is meant for testing and small setups. Game servers still need a Linux node running [FeatherWings](https://featherpanel.com/docs/wings). ## Requirements - PowerShell 5.1 or newer. The backup tools use the `tar` command that ships with Windows 10 and later. - [Docker Desktop](https://www.docker.com/products/docker-desktop), started and fully running. The installer stops with an error if `docker info` fails. - Administrator rights. The script asks for elevation through UAC if you did not start it as administrator. ## Install Open PowerShell and run: ```powershell irm https://get.featherpanel.com/stable.ps1 | iex ``` Then choose `[0] Panel` and `[0] Install Panel`, and pick a release type: Stable, Development (the `develop` branch) or a custom branch or commit. The installer: 1. Creates `C:\featherpanel` with `backups` and `migrations` folders and an `install.log`. 2. Downloads `docker-compose.yml` from the `main` branch. 3. Pulls the images and runs `docker compose up -d`. 4. Installs a `featherpanel` command in `C:\Program Files\FeatherPanel` and adds it to the system PATH. It runs `php cli` inside the `featherpanel_backend` container, so `featherpanel help` works like on Linux. See [Panel CLI](https://featherpanel.com/docs/cli/panel). Open `http://localhost:4831` and register. The first account becomes the administrator. ## Menu | Menu | Options | | --- | --- | | Panel | Install, Uninstall (removes containers, volumes and `C:\featherpanel`), Update (pulls new images and restarts), Backup Manager | | Backup Manager | Create, list, restore and delete backups of the Docker volumes; export a migration package (`featherpanel_migration_