NaviPort

Move the Spotify library you choose toward your self-hosted music server.

Français · English installation guide · Contributing · Security

NaviPort is a lightweight, self-hosted web interface for browsing a Spotify library and exporting selected playlist, album, and track links. The generated text file can be used as an input list for tools such as Downtify, while Navidrome scans the resulting music directory.

NaviPort does not download or host audio. It accesses Spotify metadata with read-only permissions and exports links only. Use it solely for content you are legally entitled to obtain and store.

Features

• First-run web setup with no .env file or Spotify Client Secret required
• Spotify Authorization Code flow with PKCE
• Liked tracks, saved albums, private and collaborative playlists
• Whole-collection or track-by-track selection
• Search, filtering, link deduplication, and plain-text export
• French and English interface with a persistent language preference
• Responsive interface for desktop, tablet, and mobile
• Multi-architecture container image for linux/amd64 and linux/arm64
• Ready-to-import manifests for ZimaOS and TrueNAS SCALE
• Healthcheck, reverse-proxy support, and least-privilege container user

Quick start

Start NaviPort:

git clone https://github.com/JavaScript-X/NaviPort.git
cd NaviPort
docker compose up -d

Open http://127.0.0.1:3000. The first-run wizard generates the local secret, shows the exact Spotify callback to register, and asks only for a Spotify Client ID. No Client Secret is needed.

For a NAS or another machine on your network, Spotify requires an HTTPS redirect URI. Follow the platform-specific reverse-proxy instructions in the English or French guide.

Supported platforms

Platform	Installation method	Architecture
Docker / Compose	Root compose.yaml	amd64, arm64
ZimaOS	Custom App import	amd64, arm64
TrueNAS SCALE 24.10+	Install via YAML	amd64, arm64
Unraid / Portainer / Dockge	Generic container or Compose	amd64, arm64

Container image:

ghcr.io/javascript-x/naviport:latest

Configuration

Variable	Required	Default	Description
SPOTIFY_CLIENT_ID	No	Web setup	Optional unattended setup
SPOTIFY_REDIRECT_URI	No	Web setup	Optional unattended setup
SESSION_SECRET	No	Generated	Optional secret override
PORT	No	3000	Internal HTTP port
NAVIPORT_PORT	No	3000	Host port used by the root Compose file
TRUST_PROXY	No	0	Set to 1 behind a trusted HTTPS reverse proxy

The web configuration is stored in the private naviport_data Docker volume. Environment variables remain available for automated deployments and override the stored values.

Architecture

Browser
  └─ NaviPort UI
       └─ Express API
            ├─ OAuth session
            └─ Spotify Web API (read-only)

Selected links → text export → your downloader → music directory → Navidrome

The access and refresh tokens stay in the server-side session. The Client ID is public by OAuth design; no Spotify Client Secret is collected or required.

Development

npm install
npm run dev

Run validation:

npm run check
docker compose config

Limitations

• In-memory sessions are lost when the container restarts.
• Local Spotify tracks do not have Spotify URLs and cannot be exported.
• The current workflow exports a portable text file and does not call the Downtify API directly.
• Spotify development-mode user and endpoint limits still apply.

License

MIT