shelfless/deploy

Deployment (Proxmox LXC, auto-start)

Shelfless runs as a small Node server that serves the built SPA and reverse-proxies the ABS API. So the browser only ever talks to Shelfless (one origin → no CORS), and the Audiobookshelf address is fixed by the deployment (ABS_URL) — users only log in.

1. Prerequisites on the container

apt update && apt install -y nodejs npm git   # Node 18+ (20+ recommended)
node --version

2. Get the code & build

mkdir -p /opt/shelfless && cd /opt/shelfless
# copy the project here (git clone / scp / rsync), then:
npm ci
npm run build        # produces dist/

3. Configure the ABS target

The server reads these env vars (see the systemd unit):

• ABS_URL — the Audiobookshelf server, e.g. http://127.0.0.1:13378 (same container) or http://192.168.1.71:13378 (another host).
• PORT — the port Shelfless listens on (default 8080).
• HOST — bind address (default 0.0.0.0).

Quick manual test:

ABS_URL=http://127.0.0.1:13378 PORT=8080 npm start
# open http://<container-ip>:8080

4. Auto-start with systemd

cp deploy/shelfless.service /etc/systemd/system/shelfless.service
# edit WorkingDirectory / ABS_URL / PORT inside the file if needed
systemctl daemon-reload
systemctl enable --now shelfless
systemctl status shelfless        # check it's running
journalctl -u shelfless -f        # logs

Open http://<container-ip>:8080. The setup screen asks only for username + password (the server URL is fixed). "Angemeldet bleiben" keeps you logged in across reloads; otherwise you log in each session.

Updating

cd /opt/shelfless
git pull            # or copy new files
npm ci && npm run build
systemctl restart shelfless

Notes

• Put it behind a reverse proxy (nginx/Caddy/Traefik) for HTTPS + a domain if you expose it beyond the LAN.
• Proxied paths: /api, /login, /logout, /public, /status, /hls, /feed, /socket.io. Everything else is served from dist/ (SPA fallback to index.html).