Reverse proxy deployment

Give Finetic a dedicated HTTPS hostname such as media.example.com, then send the complete hostname to Finetic. Do not maintain a list of individual application endpoints: Finetic adds API, streaming, artwork and live-event routes as releases evolve, and a narrow allowlist can leave the homepage working while playback, pairing or diagnostics silently fail.

The route to allow#

Use one inbound rule:

https://media.example.com/*  →  http://finetic:3000/*

That complete-origin rule covers:

• / and the web client's static assets;
• every /api/* authentication, catalogue, pairing and administration route;
• Direct Play byte ranges;
• HLS manifests, initialisation files and segments;
• artwork and subtitle delivery;
• temporary remote-access probes;
• long-lived Server-Sent Event connections.

If an organisational proxy requires path allowlists, allow the root document and static assets plus the entire /api/* namespace. This is still more fragile than forwarding / on a dedicated Finetic hostname because root-level asset names may change between releases.

Required behaviour#

Do not place a generic SSO or Basic Authentication HTML challenge in front of Finetic unless every intended native client has been tested with it. Fire TV and mobile clients expect Finetic API responses, not an intermediary login page.

Nginx#

map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 80;
  server_name media.example.com;
  return 308 https://$host$request_uri;
}

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

  # Configure your certificate and normal TLS policy here.

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    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 Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_request_buffering off;
    proxy_buffering off;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
  }
}

The location / rule is intentional. Do not replace it with only the API paths observed during setup.

Caddy#

media.example.com {
  reverse_proxy 127.0.0.1:3000
}

Caddy preserves paths and supports streaming and upgrades by default. Keep Finetic private and trust only the Caddy hop.

Traefik with Docker#

Connect Traefik and Finetic to the same private Docker network and use labels equivalent to:

services:
  finetic:
    labels:
      - traefik.enable=true
      - traefik.http.routers.finetic.rule=Host(`media.example.com`)
      - traefik.http.routers.finetic.entrypoints=websecure
      - traefik.http.routers.finetic.tls=true
      - traefik.http.services.finetic.loadbalancer.server.port=3000
      - traefik.http.services.finetic.loadbalancer.passhostheader=true

Do not apply path-stripping middleware. Restrict TRUST_PROXY to Traefik's actual address or network boundary.

Verify before relying on remote access#

1. Open https://media.example.com/api/app/version and confirm Finetic returns its version rather than a proxy login page, generic 404 or another service.
2. Sign in through the public hostname and confirm artwork loads.
3. Start and seek a Direct Play title.
4. Start a title using HLS and confirm its manifest and segments load.
5. Open Admin → Remote Access, enter the same origin and run the complete outside-home check.
6. Review the evidence for HTTPS, installation identity, byte ranges, HLS, upgrades and the safe guest route.

If the homepage works but the exact-route check returns 404, the proxy is not forwarding the complete origin. If playback starts but seeking or HLS fails, inspect rewrites, buffering, ranges, caching and timeouts before changing the playback planner.