To self-host Ryot on a managed VPS is to keep the history of what you watch, read, play and lift on a server of your own, which our teams keep up to date and monitor day and night. Ryot is a free, open source tracker under the GPL-3.0 license, for movies, shows, books, games, podcasts, music and workouts. This guide follows its official Docker image at version v10.5.8, and we ran every command on a Simafri VPS before writing it: installation with Docker Compose and PostgreSQL, HTTPS, the first account, the API keys of each media type, backups and updates.
By Simon Vasconcelos Lee
Published on 19 November 202611 minute read
ignisda/ryot and PostgreSQL 18, with port 8000 published on 127.0.0.1 behind an HTTPS reverse proxy.SERVER_ADMIN_ACCESS_TOKEN in a .env file, and set FRONTEND_URL to your public address.USERS_ALLOW_REGISTRATION=false to close sign-ups on a private instance.pg_dump, then update by changing the image tag.Ryot, for “Roll Your Own Tracker” and pronounced “riot”, keeps in one place what you have seen, read, played and trained, with statistics, a calendar of what is coming and collections of your own. Its developer, IgnisDa, writes it in Rust, with a web interface you can install on a phone as an app.
Ryot is published under the GNU General Public License, version 3 (GPL-3.0). You can use it free of charge, for yourself, your family, your club or your company, copy it and modify it. If you distribute a modified version, you distribute its source code under the same license. The software is provided without warranty.
Ryot Pro is a paid key sold by its developer, which unlocks extra features such as profile sharing and personalized recommendations. It goes in a SERVER_PRO_KEY variable of the same image, and the server returns to the community version if the key expires. Nothing in this guide needs it.
The documentation sets no minimum size, and Ryot is light. Here is what we measured on our test VPS, freshly installed:
Server size therefore depends on the number of users and on the other applications you run beside Ryot. On a managed VPS, tell us about your usage and we will recommend the right size.
Ryot ships as a single image, ignisda/ryot, also published as ghcr.io/ignisda/ryot, which serves both the interface and the API on port 8000. It needs PostgreSQL 15 or later, run beside it in its own container. On a server with Docker Engine and its Compose plugin, installed from Docker’s repository for Ubuntu, create a folder such as /opt/ryot and put this compose.yaml in it, based on the file of the installation page:
services:
ryot-db:
image: postgres:18-alpine
restart: unless-stopped
environment:
- TZ=Europe/Amsterdam
- POSTGRES_DB=ryot
- POSTGRES_USER=ryot
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
volumes:
- postgres_storage:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ryot -d ryot"]
interval: 5s
timeout: 5s
retries: 10
ryot:
image: ignisda/ryot:v10.5.8
restart: unless-stopped
ports:
- "127.0.0.1:8000:8000"
environment:
- TZ=Europe/Amsterdam
- FRONTEND_URL=https://ryot.example.com
- DATABASE_URL=postgres://ryot:${POSTGRES_PASSWORD}@ryot-db:5432/ryot
- SERVER_ADMIN_ACCESS_TOKEN=${SERVER_ADMIN_ACCESS_TOKEN:?set SERVER_ADMIN_ACCESS_TOKEN in .env}
depends_on:
ryot-db:
condition: service_healthy
volumes:
postgres_storage:
The two secrets go in a .env file next to it, which Docker Compose reads on its own. Create it readable by root only, then start the stack:
umask 077
printf 'POSTGRES_PASSWORD=%s\nSERVER_ADMIN_ACCESS_TOKEN=%s\n' "$(openssl rand -hex 24)" "$(openssl rand -hex 32)" > .env
umask 022
docker compose up -d
docker compose ps
127.0.0.1: the reference file publishes it without an address, and Docker then opens it on every address of the server. Published locally, it is reachable only through the reverse proxy.postgres as user and password. Here a dedicated ryot user gets a random password, in hexadecimal so that it needs no escaping in DATABASE_URL.SERVER_ADMIN_ACCESS_TOKEN is required: it authorizes administrator operations through the API, and it encrypts the two-factor authentication secrets of your users. Keep it secret, and keep it stable: with another token, those secrets can no longer be read.FRONTEND_URL is your public address, with https://. Ryot uses it as the base of the links it generates, and OpenID Connect needs it.TZ is the time zone of the scheduled jobs, GMT by default: put yours, from the IANA list.v10 with pull_policy: always, which follows every minor release at each start. A full version, here v10.5.8, lets you choose when each update happens.postgres_storage holds all your data. PostgreSQL 18 keeps it under /var/lib/postgresql, which is why the volume is mounted there and not on /var/lib/postgresql/data as with older versions.The first start runs the database migrations and downloads the exercise catalog; on our test VPS, Ryot answered in a few seconds. To check that it responds:
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/health
curl -s http://127.0.0.1:8000/backend/config | head -c 300
The first command answers 200. The second returns the configuration the server loaded, as JSON, with its secrets redacted: a handy way to check a variable.
The container serves Ryot over HTTP, on port 8000. HTTPS is handled by a reverse proxy in front of it, which must forward the public Host header and X-Forwarded-Proto. We tested Caddy, installed from its official Debian and Ubuntu repository: it obtains the Let’s Encrypt certificate itself, renews it, and forwards these headers by default.
ryot.example.com {
reverse_proxy 127.0.0.1:8000
}
sudo systemctl reload caddy
CADDY_TRUSTED_PROXIES.Ryot has no default account, and sign-ups are open on a new instance. The first account created gets the Admin role; the following ones are normal users. Create yours right after the first start:
For a private instance, close sign-ups: add USERS_ALLOW_REGISTRATION=false to the environment of the ryot service, then run docker compose up -d. On our test VPS, the “Create a new account?” link disappeared, and a sign-up attempted from the registration address was refused by the server with “Registration is disabled”.
We tested it with sign-ups closed: the invited account was created as a normal user, its password was set from the link, and it reached its own dashboard.
To sign in with your company accounts instead, Ryot supports OpenID Connect: set SERVER_OIDC_CLIENT_ID, SERVER_OIDC_CLIENT_SECRET and SERVER_OIDC_ISSUER_URL, and declare https://ryot.example.com/api/auth as the redirect address at your provider.
Ryot finds the details and covers of each media type at a provider. Some work without a key, others need yours, since the shared keys were removed in v9:
| Media | Provider | What to set |
|---|---|---|
| Books | Open Library | Nothing: it works at once. Google Books and Hardcover are optional, with their API key |
| Movies and shows | TMDB, or TVDB | MOVIES_AND_SHOWS_TMDB_ACCESS_TOKEN, the API Read Access Token of a free TMDB account, or MOVIES_AND_SHOWS_TVDB_API_KEY |
| Video games | IGDB, through Twitch | VIDEO_GAMES_TWITCH_CLIENT_ID and VIDEO_GAMES_TWITCH_CLIENT_SECRET, from an application in the Twitch developer console |
| Music | Spotify, optional | MUSIC_SPOTIFY_CLIENT_ID and MUSIC_SPOTIFY_CLIENT_SECRET |
| Anime import | MyAnimeList | ANIME_AND_MANGA_MAL_CLIENT_ID, needed only to import from MyAnimeList |
These keys are secrets: put them in the .env file, add a line such as - MOVIES_AND_SHOWS_TMDB_ACCESS_TOKEN=${MOVIES_AND_SHOWS_TMDB_ACCESS_TOKEN} to the environment of the ryot service, then run docker compose up -d. The configuration page of the documentation lists every other variable.
Everything lives in two places: the PostgreSQL database, in the postgres_storage volume, and your .env file. Keep the latter safe: SERVER_ADMIN_ACCESS_TOKEN is needed to read the two-factor secrets stored in the database. The PostgreSQL image includes pg_dump:
docker compose exec -T ryot-db pg_dump -U ryot -Fc ryot > ryot-$(date +%F).dump
cp .env env-$(date +%F).bak
Schedule this copy and send it off the server. Stored on the disk, the dumps are also included in the server’s nightly backups.
On the same or a new installation, with the same .env, stop the application, load the dump, then start it again:
docker compose stop ryot
docker compose exec -T ryot-db pg_restore -U ryot -d ryot --clean --if-exists --no-owner < ryot-2026-11-18.dump
docker compose start ryot
We tested the whole cycle on our VPS: dump, the database actually deleted, restore. The two accounts, their collections and the 876 exercises came back, and the administrator signed in again at once.
Ryot also exports your own data as JSON, from the “Imports and Exports” settings page, which it can import back. That export needs S3-compatible file storage; the database dump above works without it.
Ryot is released often, on a loosely weekly basis. Read the release notes, take a backup, change the image tag in the compose.yaml, then pull the new image and recreate the container. The database migrations run on their own at startup:
docker compose pull
docker compose up -d
docker compose logs ryot | grep -i migration
develop tag follows the main branch: the documentation warns that it often has major bugs and can lose data. Stay on releases.Ryot collects anonymous usage data, page views and a few events, on a self-hosted Umami instance of its developer. To turn it off, add DISABLE_TELEMETRY=true to the environment of the ryot service, then run docker compose up -d.
Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Ryot remains your software, with your history and your settings.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits you |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Your history, your collections and your integrations in Ryot |
| Ryot | Proactive monitoring: errors, slowdowns, database and disk space spotted, fix recommended | Its installation, updates, API keys and settings, which you apply, yourself or through your AI assistant |
| Users | The server that carries them, monitored and backed up | Accounts, sign-ups and single sign-on |
| Backups | Every night, encrypted and kept off the machine; restores included | Ryot’s own database dumps and JSON exports, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The timing of the switch |
If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.
With a Simafri Managed VPS, our teams keep your Ryot instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.
Yes. Ryot is under the GPL-3.0 license: you can run it for yourself, your family or your team with no license to buy. Ryot Pro is an optional paid key that adds features to the same image. What remains is the cost of the server that runs it.
Use the ignisda/ryot image and PostgreSQL 18 in a compose.yaml. Put the database password and SERVER_ADMIN_ACCESS_TOKEN in a .env file, set FRONTEND_URL to your https address, publish port 8000 on 127.0.0.1, run docker compose up -d, and put an HTTPS reverse proxy in front.
There is none. Click “Create a new account?” on the login page: the first account created becomes the administrator. Then set USERS_ALLOW_REGISTRATION=false to close sign-ups; the administrator invites the other users from Settings, Users, with a one-time link.
Since v9, movies and shows need your own TMDB token: create a free TMDB account, request an API key, and set its API Read Access Token in MOVIES_AND_SHOWS_TMDB_ACCESS_TOKEN. Video games need a Twitch application, while books work without any key.
Little. On our test VPS, a fresh installation used about 240 to 300 MB for Ryot and 70 MB for PostgreSQL, and the two images take about 810 MB of disk.
Dump the PostgreSQL database with docker compose exec -T ryot-db pg_dump -U ryot -Fc ryot, and keep a copy of your .env file. Restore with pg_restore --clean --if-exists --no-owner, the application stopped.
Read the release notes and take a backup, change the image tag in compose.yaml, then run docker compose pull and docker compose up -d. The database migrations run on their own at startup. Between major versions, follow the migration page.
A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.
Simafri
Let's talk about your project
Tell us what you need in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.