Deploy and Host Sofa on Railway

Sofa is a self-hosted movie and TV show tracking app. It lets you build a personal library, track what you've watched, discover new titles, and manage your watchlist — all backed by TMDB data. It ships as a single Docker container with a web UI, REST API, and optional mobile app.

About Hosting Sofa

Sofa runs as a single container: a Bun-powered Hono API server that also serves the built SPA frontend on port 3000. It uses an embedded SQLite database stored on a persistent volume at /data, so there's no external database to configure. On startup it automatically runs any pending database migrations. You'll need a free TMDB API token for movie/TV metadata and a secret for authentication. Optionally, you can configure OIDC/SSO for single sign-on. The container includes a built-in health check endpoint at /api/health.

Common Use Cases

Track movies and TV shows you've watched, are watching, or plan to watch
Discover upcoming releases and browse trending/popular titles powered by TMDB
Self-host a private, ad-free alternative to services like Trakt, Letterboxd, or Serializd

Dependencies for Sofa Hosting

TMDB API token — A free API Read Access Token from themoviedb.org for movie/TV metadata and images
Persistent volume — Mounted at /data to persist the SQLite database, image cache, and backups

Deployment Dependencies

Docker image: ghcr.io/jakejarvis/sofa:edge
TMDB API documentation
Sofa documentation

Implementation Details

Required environment variables:

Variable	Description
`TMDB_API_READ_ACCESS_TOKEN`	TMDB API Read Access Token (get one here)
`BETTER_AUTH_SECRET`	Random secret string for signing auth tokens (generate with `openssl rand -hex 32`)
`BETTER_AUTH_URL`	Public URL of your Sofa instance (e.g. `https://sofa.up.railway.app`)

Optional environment variables:

Variable	Default	Description
`IMAGE_CACHE_ENABLED`	`true`	Cache TMDB images locally to `/data/cache/`
`LOG_LEVEL`	`info`	Logging verbosity (`error`, `warn`, `info`, `debug`)
`OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` / `OIDC_ISSUER_URL`	—	Enable SSO via any OIDC provider

Volume mount: /data (contains SQLite DB, image cache, and backups)

Port: 8080

Why Deploy Sofa on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Sofa on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.