Reverse Proxy Deployment

The application is designed to run as a single HTTP service on one port.

Default internal URL:

http://127.0.0.1:5050

This same origin serves:

web UI on /
internal web API on /api/*
Subsonic API on /rest/*
cover art and streaming on the same host

That means mobile and TV Subsonic clients should use the same base URL as the browser.

Examples:

web UI: http://your-host:5050/
Subsonic client server URL: http://your-host:5050

Direct Docker Run

Use the root docker-compose.yml.

It publishes:

5050:5050

After startup the app is available at:

http://localhost:5050

External Reverse Proxy

If you later publish the service through another reverse proxy, forward the entire host to the same upstream:

upstream: http://app-host:5050

Do not split web and Subsonic traffic across different public ports.

Forward all of these paths to the same backend:

/
/api/*
/rest/*
/health

Caddy Example

See deploy/Caddyfile.

This example listens on plain HTTP and proxies all requests to app:5050.

Nginx Example

server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:5050;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
    }
}

Notes

In production the frontend uses relative URLs, so it works correctly behind the same origin without hardcoded API hosts.
In local frontend development, Vite proxies /api, /rest, and /health to http://127.0.0.1:5050.
If you later enable HTTPS on an external reverse proxy, clients should still connect to one public base URL only.
Web UI and Subsonic clients should always use the same public base URL, only differing by path usage.

Recommended Public Contract

Public examples:

browser: https://music.example.com/
Subsonic clients: https://music.example.com

Internal upstream:

http://127.0.0.1:5050

Do not publish separate public ports for:

web UI
/api/*
/rest/*
/api/stream/*
/api/cover-art/*

2.2 KiB Raw Blame History