Install the server on Linux

The server is a normal Laravel application and runs anywhere PHP 8.4 does. Linux is the natural home for an always-on server — the one thing it lacks is the macOS Services page, so the workers run under systemd instead.

Honesty first: development happens on macOS, and Linux has had less real-world mileage than the docs might suggest. The steps are straightforward — but if you hit something, report it.

1. Toolchain (Debian/Ubuntu shown)

sudo apt install ffmpeg git unzip
# PHP 8.4 — via your distribution, or the Sury repository on Debian/Ubuntu:
sudo apt install php8.4-cli php8.4-sqlite3 php8.4-xml php8.4-curl php8.4-mbstring php8.4-zip php8.4-gd
# Composer: https://getcomposer.org/download/
# Node 22+: https://nodejs.org or your distribution's NodeSource packages

Check: php -v (8.4+), node -v (22+), ffmpeg -version. Linux has a system certificate bundle, so outbound HTTPS works without extra setup.

2. Install

git clone https://github.com/tripsittr/SoundChex.git
cd SoundChex

composer install
npm install

cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan storage:link

npm run build
php artisan serve --host=0.0.0.0

Don't skip storage:link — without it every avatar and artist image 404s silently.

Set APP_URL in .env to the address other devices will use, port included — e.g. APP_URL=http://192.168.1.20:8000. It is what the server advertises to phones. Open it, register, and the first account becomes the owner.

3. Workers under systemd

The Admin → Services page is launchd-based and macOS-only; on Linux run the two workers as user services. Example — ~/.config/systemd/user/soundchex-queue.service: 

[Unit]
Description=SoundChex queue worker
After=network.target

[Service]
WorkingDirectory=/home/you/SoundChex
ExecStart=/usr/bin/php artisan queue:work --tries=3
Restart=always

[Install]
WantedBy=default.target

Duplicate it as soundchex-scheduler.service with ExecStart=/usr/bin/php artisan schedule:work, then: 

systemctl --user daemon-reload
systemctl --user enable --now soundchex-queue soundchex-scheduler
loginctl enable-linger $USER    # keep them running when logged out

4. Scan a small library first

Admin → Library settings → watch folders, then php artisan library:scan. A dozen files first; when they appear and play, add the real collection. See Libraries & scanning.

Building the desktop app (optional)

To build the Linux client rather than waiting for prebuilt packages:

sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

npm run tauri build     # produces .deb, .rpm and .AppImage

Verify

  1. php artisan test — failures here mean the PHP install, not the port.
  2. Open /app from another device on the LAN — proves APP_URL and the firewall.
  3. Scan the small folder — proves paths resolve.
  4. Play something — proves FFmpeg is found and streaming works.