289 lines
10 KiB
Markdown
289 lines
10 KiB
Markdown
# Bordanlage – Boat Onboard System
|
||
|
||
Multiroom audio + navigation dashboard for boats.
|
||
Full Docker stack — works on any machine, no hardware required in dev mode.
|
||
|
||
---
|
||
|
||
## Stack
|
||
|
||
| Service | Image / Build | Purpose |
|
||
|---|---|---|
|
||
| SignalK | `signalk/signalk-server` | NMEA 0183/2000 gateway, WebSocket delta stream |
|
||
| Snapserver | custom build (v0.35.0) | Multiroom audio server, JSON-RPC on :1705 |
|
||
| zone-salon/cockpit/bug/heck | custom build (v0.35.0) | Audio zones (snapclient) |
|
||
| Mopidy + Iris | custom Dockerfile | Local music, TuneIn radio, HTTP control on :6680 |
|
||
| librespot | custom build (v0.5.0) | Spotify Connect receiver, pipe backend |
|
||
| shairport-sync | `mikebrady/shairport-sync` | AirPlay 2 receiver, pipe backend |
|
||
| Jellyfin | `jellyfin/jellyfin` | Media library, :8096 |
|
||
| SignalK | `signalk/signalk-server` | Navigation data, demo NMEA in dev mode |
|
||
| Portainer | `portainer/portainer-ce` | Docker management UI, :9000 |
|
||
| Dashboard | React 18 + Vite | Touch UI, built with Vite (dev: HMR on :8090) |
|
||
|
||
Audio flow: `librespot / shairport / mopidy` → named pipe (PCM) → `snapserver` → `snapclient` zones
|
||
|
||
---
|
||
|
||
## Quick Start (Dev)
|
||
|
||
```bash
|
||
make dev
|
||
# or without make:
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
|
||
```
|
||
|
||
**Dashboard with hot-reload:** http://localhost:8090
|
||
|
||
**Everything runs in the browser - no additional software needed!**
|
||
|
||
On first run, Docker builds the custom images (snapserver, snapclient, mopidy, librespot stub). Subsequent starts are instant.
|
||
|
||
### Browser-Only Testing (Windows/Mac)
|
||
|
||
All services are accessible via browser:
|
||
- **Dashboard (Main UI):** http://localhost:8090 - Full boat control interface
|
||
- **Snapcast Web:** http://localhost:1780 - Audio zones + browser playback via Web Audio API
|
||
- **Mopidy/Iris:** http://localhost:6680/iris/ - Music player
|
||
- **SignalK:** http://localhost:3000 - Navigation backend (admin/bordanlage)
|
||
|
||
**Audio in browser:** Open Snapcast Web UI → Click 🔊 icon → Enable Web Audio playback!
|
||
|
||
### Native audio output
|
||
|
||
**Mac:**
|
||
```bash
|
||
make mac-audio # runs snapclient natively via Homebrew → Mac speakers
|
||
make spotify # runs librespot natively via Homebrew → Spotify Connect on Mac
|
||
```
|
||
|
||
Both commands require `brew install snapcast` / `brew install librespot` (auto-installed if missing).
|
||
|
||
**Windows:**
|
||
```powershell
|
||
make windows-audio # runs snapclient natively → Windows speakers (WASAPI)
|
||
```
|
||
|
||
Requires manual install: Download from https://github.com/badaix/snapcast/releases
|
||
|
||
See [WINDOWS_AUDIO_SETUP.md](WINDOWS_AUDIO_SETUP.md) for detailed Windows setup instructions.
|
||
|
||
---
|
||
|
||
## Service URLs
|
||
|
||
| Service | URL | Notes |
|
||
|---|---|---|
|
||
| Dashboard (dev) | http://localhost:8090 | Vite HMR, live reload |
|
||
| Dashboard (prod) | http://localhost:8080 | nginx-served built bundle |
|
||
| SignalK | http://localhost:3000 | Admin: `admin` / `bordanlage` |
|
||
| Mopidy/Iris | http://localhost:6680/iris/ | Music player UI |
|
||
| Snapcast Web | http://localhost:1780 | Zone control (Snapweb) |
|
||
| Jellyfin | http://localhost:8096 | Media library |
|
||
| Portainer | http://localhost:9000 | Docker management |
|
||
|
||
---
|
||
|
||
## Make Targets
|
||
|
||
```
|
||
make dev # start dev stack (Vite HMR, null audio, SignalK demo data)
|
||
make boot # start production stack (full audio pipeline)
|
||
make stop # stop dev stack
|
||
make stop-boot # stop production stack
|
||
make logs # tail logs (dev stack)
|
||
make rebuild # force rebuild all images (dev stack)
|
||
make status # show container status
|
||
make pipes # create audio named pipes in /tmp/audio (for boot mode)
|
||
make mac-audio # run snapclient natively on Mac (Homebrew)
|
||
make spotify # run librespot natively on Mac (Homebrew, Spotify Connect)
|
||
```
|
||
|
||
---
|
||
|
||
## Spotify Connect
|
||
|
||
**Dev mode (Mac):** run `make spotify` — shows as "Bordanlage" in Spotify app.
|
||
|
||
**Boot mode (boat):** librespot runs inside Docker, pipe backend, writes PCM to `/tmp/audio/spotify.pcm`.
|
||
|
||
> On Linux (boat), set `network_mode: host` for `librespot` and `shairport` in `docker-compose.yml` for reliable mDNS/Bonjour discovery.
|
||
|
||
---
|
||
|
||
## AirPlay
|
||
|
||
The `shairport` container runs `shairport-sync` with pipe output.
|
||
|
||
1. On iPhone/Mac: Control Center → AirPlay → select **"Bordanlage AirPlay"**
|
||
2. Audio goes through the snapserver multiroom pipeline
|
||
|
||
Config: `config/shairport.conf`
|
||
|
||
---
|
||
|
||
## Adding Music (Mopidy)
|
||
|
||
Drop files into `./music/`. Trigger a library scan:
|
||
|
||
```bash
|
||
curl -s http://localhost:6680/mopidy/rpc \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"jsonrpc":"2.0","id":1,"method":"local.scan"}'
|
||
```
|
||
|
||
---
|
||
|
||
## Zones
|
||
|
||
Four zones are pre-configured:
|
||
|
||
| Zone | hostID | Production use |
|
||
|---|---|---|
|
||
| Salon | zone-salon | Below-deck salon speakers |
|
||
| Cockpit | zone-cockpit | Cockpit/helm area |
|
||
| Bug | zone-bug | Forward cabin (Bug = bow in German) |
|
||
| Heck | zone-heck | Stern (Heck = stern in German) |
|
||
|
||
Each zone runs `snapclient` connecting to `snapserver` on the Docker internal network.
|
||
In dev mode the zones use `--player file:filename=null` (audio discarded, no hardware needed).
|
||
In production, replace with `--player alsa --soundcard hw:N,0` and expose `/dev/snd`.
|
||
|
||
---
|
||
|
||
## Environment Variables
|
||
|
||
Copy `.env.example` to `.env` and adjust:
|
||
|
||
```
|
||
SPOTIFY_NAME=Bordanlage
|
||
SPOTIFY_BITRATE=320
|
||
MUSIC_PATH=./music
|
||
VITE_USE_MOCK=false # true = force mock data in dashboard, false = real APIs
|
||
```
|
||
|
||
---
|
||
|
||
## Dashboard API Configuration
|
||
|
||
The dashboard reads hosts from environment at build time:
|
||
|
||
| Variable | Default | Description |
|
||
|---|---|---|
|
||
| `VITE_SNAPCAST_HOST` | `localhost` | Snapserver hostname |
|
||
| `VITE_SIGNALK_HOST` | `localhost` | SignalK hostname |
|
||
| `VITE_MOPIDY_HOST` | `localhost` | Mopidy hostname |
|
||
| `VITE_JELLYFIN_HOST` | `localhost` | Jellyfin hostname |
|
||
| `VITE_USE_MOCK` | `false` | Force mock data (no real APIs) |
|
||
|
||
---
|
||
|
||
## Architecture: Named Pipes
|
||
|
||
In **boot mode**, audio flows through named pipes on a tmpfs volume:
|
||
|
||
```
|
||
spotify.pcm ← librespot (Spotify Connect)
|
||
airplay.pcm ← shairport (AirPlay 2)
|
||
mopidy.pcm ← mopidy (local files, radio)
|
||
```
|
||
|
||
Snapserver reads all three as streams and routes them to zones.
|
||
|
||
Run `make pipes` once before `make boot` to create the pipes (or they are created automatically).
|
||
|
||
In **dev mode**, pipes are not used (no audio hardware crosses the Docker VM boundary on Mac).
|
||
|
||
---
|
||
|
||
## Deployment to Boat (Ubuntu Server)
|
||
|
||
This system is designed to run on a boat with an Ubuntu server in kiosk mode.
|
||
|
||
**See detailed guide:** [KIOSK_SETUP.md](KIOSK_SETUP.md)
|
||
|
||
### Quick Summary
|
||
|
||
Changes in `docker-compose.yml` for production:
|
||
|
||
1. **Zone audio output** — replace `--player file:filename=null` with `--player alsa --soundcard hw:N,0`, uncomment `/dev/snd` device
|
||
2. **Spotify / AirPlay discovery** — set `network_mode: host` for `librespot` and `shairport`
|
||
3. **NMEA hardware** — uncomment the `devices` block under `signalk`, configure the connection at http://[boat-ip]:3000
|
||
4. **Video decoding** (optional) — uncomment `/dev/dri` under `jellyfin`
|
||
5. Use `make boot` instead of `make dev`
|
||
|
||
### Kiosk Mode (Chromium Fullscreen)
|
||
|
||
```bash
|
||
chromium-browser --kiosk http://localhost:8080
|
||
```
|
||
|
||
See [KIOSK_SETUP.md](KIOSK_SETUP.md) for complete Ubuntu server setup with autostart.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
**Zones stuck restarting:**
|
||
- Check `docker compose logs zone-salon`. With snapclient v0.35+, the server URI must be `tcp://snapserver` (not `--host snapserver`).
|
||
- If "No audio player support": snapclient needs `--player file:filename=null` in dev (null player not compiled in the bookworm .deb).
|
||
|
||
**Dashboard crashes with exit 127 / npm not found:**
|
||
- The local `node:20-alpine` image was overwritten by the production dashboard build. Fix: `docker rmi node:20-alpine && make dev`.
|
||
- Root cause prevented by `dashboard/Dockerfile.dev` — dev uses its own build context.
|
||
|
||
**Shairport config syntax error:**
|
||
- Boolean values in `config/shairport.conf` must be quoted: `"yes"` not `yes`.
|
||
|
||
**Spotify device not visible:**
|
||
- On Mac, Docker Desktop bridges UDP poorly. Use `make spotify` (native librespot on Mac) for dev.
|
||
- On boat: use `network_mode: host` in `docker-compose.yml`.
|
||
|
||
**Librespot production build fails:**
|
||
- `cargo install librespot` (latest = v0.8.0) has a vergen_lib dependency conflict.
|
||
- Fixed by pinning to `--version "=0.5.0"` in `docker/librespot/Dockerfile`.
|
||
|
||
**Snapcast arm64 .deb not found:**
|
||
- v0.27.0 has no arm64 release. Use v0.35.0 which ships `arm64_bookworm.deb`.
|
||
|
||
**Port conflicts (e.g. 8080 taken by Supabase):**
|
||
- Dev dashboard is on **8090**, production on 8080. Change port mappings in `docker-compose.dev.yml` as needed.
|
||
|
||
---
|
||
|
||
## Project Layout
|
||
|
||
```
|
||
.
|
||
├── Makefile
|
||
├── docker-compose.yml # production stack
|
||
├── docker-compose.dev.yml # dev overrides (Vite HMR, null zones, SignalK demo)
|
||
├── config/
|
||
│ ├── snapserver.conf # pipe sources, HTTP API config
|
||
│ ├── mopidy.conf # music backends, HTTP server
|
||
│ └── shairport.conf # AirPlay name, pipe output
|
||
├── docker/
|
||
│ ├── snapserver/Dockerfile # snapcast v0.35.0 from GitHub releases
|
||
│ ├── snapclient/Dockerfile # snapcast v0.35.0 from GitHub releases
|
||
│ ├── mopidy/Dockerfile # mopidy + iris + local + tunein
|
||
│ └── librespot/
|
||
│ ├── Dockerfile # production: cargo install librespot v0.5.0
|
||
│ └── Dockerfile.dev # dev stub: alpine + sleep
|
||
├── dashboard/
|
||
│ ├── Dockerfile # production: Vite build → nginx
|
||
│ ├── Dockerfile.dev # dev: node:20-alpine base (avoid image overwrite)
|
||
│ ├── nginx.conf
|
||
│ └── src/
|
||
│ ├── api/ # real API clients (snapcast, signalk, mopidy, jellyfin)
|
||
│ ├── mock/ # mock data (VITE_USE_MOCK=true)
|
||
│ ├── hooks/ # useNMEA, useZones, usePlayer, useDocker
|
||
│ └── components/
|
||
│ ├── layout/ # TopBar, TabNav
|
||
│ ├── audio/ # ZoneCard, ZoneGrid, NowPlaying, SourcePicker
|
||
│ └── nav/ # InstrumentPanel, ChartPlaceholder
|
||
├── scripts/
|
||
│ ├── init-pipes.sh # create named pipes in /tmp/audio
|
||
│ ├── setup-dev.sh
|
||
│ └── setup-boot.sh
|
||
└── music/ # drop audio files here (Mopidy + Jellyfin)
|
||
```
|