Install the server on macOS

macOS is the platform SoundChex is developed on — everything here has been run many times, including managed background services via launchd.

1. Toolchain

brew install php composer node ffmpeg

Check versions afterwards: php -v (8.4+), node -v (22+), ffmpeg -version. macOS ships a system certificate bundle, so outbound HTTPS works out of the box — no extra configuration needed.

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

Don't skip storage:link. Without it every avatar and artist image 404s while everything else works — the classic silent failure of a fresh install.

Open http://localhost:8000 and register — the first account becomes the owner.

3. The background workers

Two long-running processes do the real work:

php artisan queue:work        # enrichment, transcoding, downloads, transfers
php artisan schedule:work     # scanning, backups, pruning

On macOS you have two good options for keeping them alive:

  • The Services page — Admin → Services starts, stops and shows logs for both workers. It is built on launchd and is macOS-only.
  • launchd at login — the repository ships ready-made plists (com.soundchex.queue.plist, com.soundchex.scheduler.plist, com.soundchex.serve.plist) in Documentation & Planning/. Copy them into ~/Library/LaunchAgents/ and adjust the paths to your clone.

If you ever move the repository folder, the launchd plists keep pointing at the old path and the workers restart-loop silently. Re-edit the paths and reload them.

4. Scan a small library first

Admin → Library settings → watch folders, then: 

php artisan library:scan

Start with a dozen files. When they appear under http://localhost:8000/app/music and play, point it at the real collection. See Libraries & scanning.

5. The desktop apps (optional)

Prebuilt downloads are on the releases page. To build them yourself you additionally need Rust: 

npm run tauri build           # the client (.app / .dmg)
npm run build:server          # SoundChex Server.app, with service controls

If the DMG bundling step fails while the .app builds fine (Tauri exits 0 either way — read the output, not the exit code), detach stale disk images and build just the app bundle:

hdiutil info | grep -B14 "rw\." | grep -oE "^/dev/disk[0-9]+" | xargs -n1 hdiutil detach -force
rm -f src-tauri/target/release/bundle/macos/rw.*
npm run tauri build -- --bundles app

Verify

  1. php artisan test — if tests fail, the problem is the PHP install, not you.
  2. Open /app — proves the library reads.
  3. Scan the small folder — proves paths resolve.
  4. Play something — proves FFmpeg is found and streaming works.