Skip to content

Deployment

Jump to bottom
alsi-lawr edited this page Jul 29, 2026 · 1 revision

Deployment

Requirements

A Spotify-backed Phrasic display needs:

  • a public HTTPS origin;
  • a Spotify Developer application;
  • Docker or another way to run the bundled Bun host.

Phrasic stores Spotify authorization in the browser profile. The host receives no client secret, refresh token, playback history, or audio stream.

Spotify application

Register the exact callback, including its trailing slash:

https://display.example/spotify/

Create a deployment-specific config.json:

{
  "spotify": {
    "clientId": "public-client-id",
    "redirectUri": "https://display.example/spotify/"
  }
}

The configuration accepts exactly those two public fields. Do not add a client secret, token, query string, fragment, or additional property. The redirect must be HTTPS, same-origin with the active page, and end in /spotify/.

Published container

docker pull alsilawr/phrasic:latest

docker run --rm --publish 127.0.0.1:8080:8080 \
  --mount type=bind,src="$(pwd)/config.json",dst=/app/config.json,readonly \
  alsilawr/phrasic:latest

Release tags publish AMD64 and ARM64 images under the full version, major/minor, major, and latest tags. Pin a versioned tag where reproducible deployment matters.

The bundled Bun host listens on port 8080 by default and owns Phrasic's route, cache, content-type, and security-header policy. The operator owns host-interface publication, reverse proxying, and TLS. Bind the container to a private interface and publish it through the HTTPS-owning reverse proxy; do not expose it directly to the public network.

Display setup

Open:

https://display.example/spotify/?width=1920&setup=1

Select Connect Spotify and authorize in that browser profile. Afterwards, use the display URL without setup=1.

width accepts one integer from 320 through 7680; it defaults to 1920. setup=1 shows reconnect, retry, and disconnect controls. Malformed, repeated, unsupported, or out-of-range parameters produce an in-display diagnostic and fall back to safe display geometry.

Phrasic can run in a browser window, web view, signage surface, stream compositor, or browser-source implementation. Use the host's interaction mode while setup controls are visible.

Fake Music route

The production host returns 404 for /fake/ by default. Enable the development provider only for an intentional test deployment:

docker run --rm --publish 127.0.0.1:8080:8080 \
  --env FAKE_PROVIDER_ENABLED=true \
  --mount type=bind,src="$(pwd)/config.json",dst=/app/config.json,readonly \
  alsilawr/phrasic:latest

Keep it disabled on normal deployments. See Fake Music provider for its control contract.

Version boundary

Version 2 has no version 1 migration. Deploy the current bundled host and dist/ output together, provide the current config.json, and authorize again for every deployed origin and browser profile.

Phrasic

Clone this wiki locally