Skip to content

quickstart_web.md

Latest commit

 

History

History
151 lines (98 loc) · 3.94 KB

quickstart_web.md

File metadata and controls

151 lines (98 loc) · 3.94 KB
Raw

Web App Quickstart

Works on Windows, macOS, and Linux — no GTK or WSL2 required.

The web app consists of two parts running on your local machine:

  • API server (dplayer-api) — Python process that talks to your SQLite database
  • Browser frontend — React app served by a local dev server (or bundled via Tauri for release builds)

Prerequisites

Estimated time: ~10 minutes

Tool Version Notes
Python 3.10+ Already required for the CLI
Node.js 20+ Only needed to run the frontend dev server

Step 1 — Install

python3 -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

pip install -e ".[web]"

Note: pip install -e ".[web]" installs the fastapi and uvicorn dependencies that dplayer-api requires. A plain pip install -e . (core profile) will not include these.

Step 2 — Set your Discogs token

# Linux / macOS
export DISCOGS_TOKEN="your_discogs_personal_access_token"

# Windows (PowerShell)
$env:DISCOGS_TOKEN = "your_discogs_personal_access_token"

Need a token? Get your Discogs personal access token →

If the token is not set, the app will redirect you to a setup page automatically (see First-run FTUX below).

Step 3 — Start the API server

dplayer-api

You should see:

Spinner for Discogs API — http://127.0.0.1:8768  (Ctrl+C to stop)
INFO:     Started server process [...]
INFO:     Uvicorn running on http://127.0.0.1:8768

Leave this terminal running. The API must be running for the frontend to work.

Step 4 — Start the frontend dev server

Open a second terminal (with the virtualenv active) and run:

npm --prefix webapp install   # first time only
npm --prefix webapp run dev

You should see:

  VITE v5.x.x  ready in ...ms

  ➜  Local:   http://localhost:5173/

Open http://localhost:5173 in your browser.

Why a separate dev server? The API server (dplayer-api) currently serves only the JSON API — static file hosting is not wired in. Production release builds are bundled via Tauri (the desktop shell) and don't require a separate Node.js process. For now, the dev server is the supported browser path.

First-run FTUX

If DISCOGS_TOKEN is not set when the API starts, the frontend automatically redirects you to /setup. On that page:

  1. Paste your Discogs personal access token into the field
  2. Click Save
  3. The app redirects to the home page and starts loading your collection

Step 5 — Sync your collection

Either:

  • Click Sync in the navigation bar, or
  • Run dplayer sync in a terminal

The initial sync fetches all releases and wantlist items from Discogs. Subsequent syncs are incremental and much faster.

Done? Verify it works

Open http://localhost:5173 in your browser and click Spin. If it returns a record from your collection, you're all set. You can also verify from the terminal:

dplayer status

Troubleshooting

Symptom Fix
"API not reachable" / blank page Confirm dplayer-api is running and check for errors in that terminal
ModuleNotFoundError: fastapi Run pip install -e ".[web]" — you installed the core profile only
npm: command not found Install Node.js 20+ from nodejs.org
Token errors after save Check that the token is a valid Discogs personal access token (not OAuth)
Port 8768 already in use Another process is using that port; kill it or restart your machine

What's next

  • Spin — the Spin button picks a random record from your collection
  • Value dashboard — see your collection's market value and top movers
  • Wantlist — browse and filter records you're looking for
  • Playback — optional Spotify or YouTube Music integration; see Token Setup