Self-host Watchly

Watchly is made to self-host: the same code as the public instance, with your own Redis and your own keys. Every method needs the same few settings; pick the one that fits where you want it to live.

← Back to Watchly v1.15.0

Choose a method

One click

Vercel

No server to run: deploy from the button and add a Redis Cloud database in the same flow. Background refreshes are best effort.

 Recommended

Docker

Watchly and Redis with Docker Compose on any machine. Everything works, including background refreshes.

 Template

Unraid

Install from the bundled Community Applications template, next to any Redis container.

Deploy on Vercel

Vercel detects the FastAPI app and runs it on Python 3.12. The button clones the repository to your Git account and offers to create a Redis Cloud database.

Deploy to Vercel
  1. Click Deploy to Vercel and pick a project name.
  2. Accept the Redis store to try Watchly on a free Redis Cloud database; it adds REDIS_URL to the project. For an instance you'll keep, skip it and set up Upstash instead.
  3. Fill in TOKEN_SALT and HOST_NAME (see the table below), then deploy. Add TMDB_API_KEY under Settings → Environment Variables too; it is optional but recommended.
  4. Check the production domain Vercel gave you. If it differs from what you entered, update HOST_NAME under Settings → Environment Variables.
  5. Redeploy from the Deployments tab. Environment variable changes only apply to new deployments.
  6. Open https://<your-domain>/configure and set up your catalogs.

Limits on Vercel

Watchly does some work after it has already answered a request, and Vercel's Python runtime has no way to keep a function alive for that. That work may be paused or cut short:

  • Setup may stop at "Setup is taking a while". Your URL still works; the first home screen builds its rows as Stremio asks for them, so it is slower.
  • Stale rows are served as they are while a rebuild runs in the background. If that rebuild is cut, the next request tries again.
  • There is no scheduler. Catalogs refresh only when Stremio requests them, and that refresh is not guaranteed to finish.
  • A single request can run for up to 5 minutes by default. A very large library can take longer on its first build.

If you want refreshes to run reliably, use Docker.

Docker

Run the published image next to Redis with Docker Compose.

  1. Create a docker-compose.yml with a redis:7-alpine service and ghcr.io/timilsinabimal/watchly:latest on port 8000.
  2. Create a .env with the variables below and REDIS_URL=redis://redis:6379/0.
  3. Run docker compose up -d and open /configure on your HOST_NAME.
Full Docker guide

Choose a Redis

Watchly keeps every account, cache and rendered row in Redis. On Docker, run Redis next to Watchly. On Vercel, use Upstash.

Vercel pick

Upstash free

  • 500K commands a month
  • 256 MB of data
  • TLS always on
  • Idle for 30 days: archived, restorable
  • Then $0.20 per 100K commands
Deploy button

Redis Cloud free

  • 100 ops/sec
  • 30 MB of data, 30 connections
  • No TLS on the free plan
  • Idle for 14 days: deleted
  • Paid plans from $5 a month
Docker pick

Docker Redis

  • No command or connection limits
  • Data limited by your disk
  • Never deleted for being idle
  • Free

A cached row costs about 3 commands, so a home screen of ~10 rows is ~35. Each row also rebuilds once a day for about 10 more. A user who opens Stremio a few times a day uses 5–8K commands a month, so Upstash's free plan covers roughly 60–100 users. Redis Cloud's free plan runs out first on connections: each Vercel instance opens up to REDIS_MAX_CONNECTIONS (20), so two instances pass its 30. It is fine for trying Watchly; switch to Upstash before you share it.

Set up Upstash

  1. In the Upstash console, create a Redis database in the region nearest your Vercel functions. New Vercel projects run in iad1 (Washington, D.C.), so AWS us-east-1 is the usual choice.
  2. Open the database's Connect section and copy the rediss://default:<password>@<host>:<port> URL from the redis-cli snippet. Skip the REST URL and token; they are for Upstash's HTTP API, which Watchly can't use.
  3. In Vercel, set REDIS_URL to that URL under Settings → Environment Variables.
  4. Redeploy from the Deployments tab.

The rediss:// scheme turns on TLS; Watchly's Redis client needs no other setting for it.

Redis Cloud from the Deploy button

The button's Redis store creates a free Redis Cloud database and sets REDIS_URL for you. On the free plan, set REDIS_MAX_CONNECTIONS=10 so two instances stay under its limit, and keep in mind the database is deleted after 14 days without commands.

Limits checked September 2026; confirm them before you pick. Sources: Upstash pricing, Upstash FAQ, Redis Cloud limits, Redis Cloud TLS, Redis pricing.

Environment variables

Everything else has a working default. The configuration reference lists every option, including Trakt and Simkl.

Variable What to set
TMDB_API_KEY Optional Recommended. A free API key from TMDB. Each user enters their own key on the configure page and this one is the fallback. Without it the language list shows English only, and accounts saved before the page asked for a key have none to use.
TOKEN_SALT A long random secret that encrypts stored credentials, for example the output of openssl rand -hex 32. Changing it later makes every stored credential unreadable.
HOST_NAME The public URL of your instance, such as https://watchly.vercel.app. Manifest and OAuth callback URLs are built from it.
REDIS_URL A redis:// or rediss:// connection string. See Choose a Redis.