Skip to content

http-api-deployment.md

Latest commit

 

History

History
84 lines (59 loc) · 3.29 KB

http-api-deployment.md

File metadata and controls

84 lines (59 loc) · 3.29 KB
Raw

slskr HTTP API Deployment

This page is current release guidance. Older http_api_* and SLSKR_BEARER_TOKEN names are obsolete.

Local Default

slskr serve binds to 127.0.0.1:5030 by default. Loopback-only binds may run without API auth when no token is configured.

SLSKR_HTTP_BIND=127.0.0.1:5030 cargo run -p slskr -- serve
curl http://127.0.0.1:5030/api/health

Exposed Deployment

Any non-loopback bind requires SLSKR_API_TOKEN unless SLSKR_AUTH_DISABLED=true is explicitly set. Do not disable auth on exposed binds.

export SLSKR_HTTP_BIND=0.0.0.0:5030
export SLSKR_API_TOKEN="$(openssl rand -hex 32)"
export SLSKR_AUTH_DISABLED=false
slskr serve

Protected routes accept:

  • Authorization: Bearer <token>
  • X-API-Key: <token>
  • slskr.session cookie only when SLSKR_API_COOKIE_AUTH_ENABLED=true

Health/version/capability bootstrap routes remain public: /, /api/health, /api/version, /api/session/enabled, and /api/v0/capabilities.

Reverse Proxy

Terminate TLS at the proxy and forward to the loopback-bound daemon where possible.

server {
    listen 443 ssl http2;
    server_name slskr.example.com;

    ssl_certificate /etc/letsencrypt/live/slskr.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/slskr.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5030;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Forwarded "for=$remote_addr;proto=$scheme;host=$host";
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Set SLSKR_TRUSTED_PROXY_CIDRS or [auth].trusted_proxy_cidrs to every trusted proxy CIDR before relying on Forwarded or X-Forwarded-For for anonymous rate-limit keys. slskr ignores these headers from untrusted peers, walks forwarded chains from the socket peer toward the client, and fails closed to the socket address when a chain is malformed. Proxies should append or replace forwarding headers consistently.

Do not add wildcard Access-Control-Allow-Origin: * for authenticated browser deployments. slskr emits same-origin CORS responses and rejects cross-site mutating API requests when auth is enabled.

Kubernetes

Use the maintained manifests under k8s/. They run the API as one stateful replica by default, mount /data from the slskr-data PVC, and expose metrics at /api/metrics on the authenticated HTTP port.

Before applying, create real secrets from placeholders in k8s/secrets.example.yaml:

kubectl create namespace slskr
kubectl -n slskr create secret generic slskr-secrets \
  --from-literal=SLSKR_API_TOKEN="$(openssl rand -hex 32)" \
  --from-literal=SLSK_USERNAME="<username>" \
  --from-literal=SLSK_PASSWORD="<password>"

Then set concrete release image tags in k8s/deployment.yaml and apply:

kubectl apply -k k8s
kubectl -n slskr rollout status deployment/slskr-api

Metrics

Prometheus-compatible metrics are served at both /api/metrics and /api/v0/metrics. These routes are protected when API auth is enabled. The Kubernetes ServiceMonitor uses /api/metrics on the http service port and reads SLSKR_API_TOKEN from slskr-secrets as a bearer token.