Skip to content

installation.en.md

Latest commit

 

History

History
175 lines (125 loc) · 5.2 KB

installation.en.md

File metadata and controls

175 lines (125 loc) · 5.2 KB
Raw

NaviPort installation guide

NaviPort — Your music, back home

← Back to README · Guide en français

1. Start NaviPort

No .env file is required:

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

Open http://127.0.0.1:3000. NaviPort opens its first-run wizard and generates its own session secret.

2. Complete the web setup

  1. Open the Spotify Developer Dashboard.
  2. Create an application and open its settings.
  3. Select Web API. NaviPort does not use the Web Playback SDK.
  4. Copy the Redirect URI displayed by NaviPort into the Spotify application.
  5. Click Add next to that URI, then save the Spotify application.
  6. Copy the Client ID from Spotify into NaviPort.
  7. Save the wizard and select Connect with Spotify.

No Spotify Client Secret is required. NaviPort uses OAuth PKCE.

For a NAS or LAN installation, open NaviPort through your public HTTPS hostname before completing the wizard. It should display a callback similar to:

https://naviport.example.com/auth/callback

Spotify requires HTTPS except for explicit loopback addresses. localhost, plain HTTP LAN addresses, wildcards, and a callback that differs by a slash are not accepted.

For local setup, always open NaviPort as http://127.0.0.1:PORT, never http://localhost:PORT. NaviPort automatically corrects localhost links.

In Spotify development mode, add each person who will use NaviPort under the application's user management settings.

Inspect the deployment:

docker compose up -d
docker compose ps
docker compose logs -f naviport

Update later:

docker compose pull
docker compose up -d

3. ZimaOS

  1. Open the ZimaOS web interface.
  2. Go to App Store, click +, then Install a customized app.
  3. Select the Docker Compose import option.
  4. Copy the contents of deploy/zimaos/compose.yaml.
  5. Install the application.
  6. Open port 3000 from the ZimaOS application tile.
  7. Follow the first-run wizard.

The supplied manifest includes ZimaOS/CasaOS metadata and supports both amd64 and arm64 machines.

For authentication from another device, expose NaviPort through an HTTPS reverse proxy, set TRUST_PROXY=1, and use the exact HTTPS callback in both the manifest and Spotify dashboard.

4. TrueNAS SCALE 24.10 or newer

  1. Configure an Apps pool in TrueNAS if one is not already active.
  2. Open Apps → Discover Apps.
  3. Open the menu and choose Install via YAML.
  4. Use naviport as the application name.
  5. Copy the contents of deploy/truenas/compose.yaml.
  6. Save and wait for the application status to become Running.
  7. Open http://TRUENAS_IP:3000 or the HTTPS reverse-proxy URL.
  8. Follow the first-run wizard.

If port 3000 is already used, change only the left side of the port mapping:

ports:
  - "13000:3000"

The internal PORT remains 3000.

5. Reverse proxy

Recommended production environment when using the root Compose file:

SPOTIFY_REDIRECT_URI=https://naviport.example.com/auth/callback
TRUST_PROXY=1

The reverse proxy must:

  • terminate HTTPS;
  • forward requests to naviport:3000;
  • preserve the original host;
  • send X-Forwarded-Proto: https;
  • route /auth/callback to the same NaviPort instance.

Register the exact same HTTPS callback in Spotify. Do not expose NaviPort directly to the internet without TLS and access controls appropriate for your home server.

When using the NAS manifests, change TRUST_PROXY to 1 before deployment. The wizard detects the callback from the HTTPS address opened in the browser.

Resetting the setup

The configuration is stored in /data/config.json. To start over with the root Compose deployment:

docker compose down
docker volume rm naviport_naviport_data
docker compose up -d

This signs users out and removes only NaviPort's local OAuth configuration.

6. Downtify and Navidrome workflow

  1. Sign in to Spotify through NaviPort.
  2. Add an entire collection or open it to select individual tracks.
  3. Download the export.
  4. Copy the Spotify URLs from the file into Downtify.
  5. Let Downtify write into the directory already scanned by Navidrome.
  6. Trigger or wait for the next Navidrome library scan.

Lines beginning with # are informational comments. Each remaining line is a Spotify URL.

Troubleshooting

INVALID_CLIENT: Invalid redirect URI

The URI in Spotify, SPOTIFY_REDIRECT_URI, and the address used by the browser must agree. Check the scheme, hostname, port, path, capitalization, and trailing slash.

Login returns to the home page without connecting

Check container logs and confirm that cookies reach NaviPort through the proxy. When HTTPS terminates at the proxy, set TRUST_PROXY=1.

A playlist cannot be opened

Spotify can restrict playlist item access to playlists owned by the current user or playlists where that user is a collaborator. API development-mode limits can also apply.

Container is unhealthy

docker inspect --format '{{json .State.Health}}' naviport
docker logs naviport