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