spinkever/music-import repository overview

⁠Music Import

A web UI that imports FLAC music from ZIP archives — extracts, tags with beets, renames files, and moves to a configured output directory.

⁠Usage

Start the container:

docker run -p 8080:8080 \
  -v /path/to/music:/music \
  -v /path/to/downloads:/downloads \
  -e OUTPUT_BASE=/music \
  -e OUTPUT_FORMAT="%albumartist%/%year% - %albumname%"

Open http://localhost:8080, upload a .zip with FLAC files.

⁠Environment Variables

⁠OIDC setup

The app supports OpenID Connect login (e.g. Keycloak, Authentik, Authelia, Google, GitHub). When OIDC is enabled, users click "Login with SSO" and are redirected to your IdP.

The OIDC_ISSUER is the base OIDC endpoint of your provider (e.g. https://auth.sfsk.nl/oidc or https://idp.example.com/realms/my-realm). The app automatically discovers the authorization, token, and userinfo endpoints by requesting OIDC_ISSUER + /.well-known/openid-configuration.

⁠1. Register an OIDC client at your provider

At the provider side, create a new OIDC/OAuth2 application and set:

• Client type: confidential (client secret is used)
• Redirect URI (callback URL): https://musicimport.example.com/auth/callback — the public URL of your app plus /auth/callback. It must match the derived callback URI exactly (see below).
• Allowed scopes: openid email profile

Note the issuer/base OIDC URL, the client ID, and the client secret the provider gives you.

⁠2. Run the container with OIDC variables

docker run -p 8080:8080 \
  -v /path/to/music:/music \
  -v /path/to/downloads:/downloads \
  -e OUTPUT_BASE=/music \
  -e EXTERNAL_URL=https://musicimport.example.com \
  -e OIDC_ISSUER=https://idp.example.com/oidc \
  -e OIDC_CLIENT_ID=music-import \
  -e OIDC_CLIENT_SECRET=your-client-secret \
  -e SESSION_SECRET=a-long-random-string

⁠What should the callback URL be?

The callback (redirect) URI is always https://<your-public-host>/auth/callback, i.e. EXTERNAL_URL + "/auth/callback". It is derived from EXTERNAL_URL — there is no separate setting. So if EXTERNAL_URL=https://musicimport.example.com, the callback is https://musicimport.example.com/auth/callback.

The value registered in the IdP must match exactly (scheme, host, port, and path) what the app sends, otherwise the provider rejects the redirect.

⁠Behind a reverse proxy

When the app runs behind a reverse proxy (nginx/Traefik) terminating TLS:

• Set EXTERNAL_URL to the public https:// URL so the callback URI and session cookie scheme are correct.
• Set FORWARDED_ALLOW_IPS to the proxy's IP address so uvicorn trusts its X-Forwarded-Proto / X-Forwarded-For headers. Without this the app sees the internal http scheme and the proxy's IP instead of the public URL, and OIDC login fails.
• If you don't use a proxy and the container is exposed directly over HTTPS, FORWARDED_ALLOW_IPS can stay at its default.

⁠Troubleshooting

• "redirect_uri mismatch" / login fails: the callback URI in the IdP does not match the derived EXTERNAL_URL + /auth/callback. Compare them exactly.
• Redirect shows http instead of https: EXTERNAL_URL is not set, or FORWARDED_ALLOW_IPS doesn't include the proxy, so uvicorn ignores the X-Forwarded-Proto header.
• Login succeeds but redirects back to / unauthenticated: check the session cookie SESSION_SECRET is stable across restarts.

⁠CLI Mode

python app.py /path/to/file.zip