Ryot

https://docs.ryot.io/
Admin
Ryot is a self-hosted platform for tracking various types of media and activities, including books,...
Tokens:25,453
Snippets:232
Trust Score:6.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start development servers: cargo run, caddy run, yarn turbo run

Source: https://docs.ryot.io/contributing

Run these three commands in separate terminals to start the backend, Caddy reverse proxy, and frontend development server. The frontend is then available at http://localhost:8000.

```bash
cargo run
```

```bash
caddy run --config 'ci/Caddyfile'
```

```bash
yarn turbo run dev --filter=@ryot/frontend
```

--------------------------------

### Kubernetes Helm installation

Source: https://docs.ryot.io/deployment

Installs the Ryot Helm chart from the GitHub Container Registry with required security and configuration settings.

```bash
helm install ryot oci://ghcr.io/ignisda/charts/ryot \
  --set secret.adminAccessToken.value="$(openssl rand -hex 16)" \
  --set postgres.auth.password="$(openssl rand -hex 16)" \
  --set config.frontendUrl="https://ryot.your-domain.com"
```

--------------------------------

### Start PostgreSQL with Docker

Source: https://docs.ryot.io/contributing

Run a PostgreSQL 18 Alpine container with the credentials and database name expected by the project's DATABASE_URL. Exposes port 5432 on localhost.

```bash
docker run -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres -e POSTGRES_DB=postgres -p 5432:5432 postgres:18-alpine
```

--------------------------------

### Dokku deployment script

Source: https://docs.ryot.io/deployment

A bash script to automate Ryot server setup on Dokku using the Ghcr image. Requires sudo privileges and an existing global domain configuration.

```bash
#!/usr/bin/env bash

set -euo pipefail

if [ "$EUID" -ne 0 ]
  then echo "Please run as root"
  exit
fi

IMAGE_NAME="ignisda/ryot"
APPNAME=""

read -rp "Enter the name of the app: " APPNAME

# check if app name is empty
if [ -z "$APPNAME" ]; then
    echo "App name empty. Using default name: ryot"
    APPNAME="ryot"
fi

# pull the latest image
docker rmi -f "$IMAGE_NAME" || true
docker pull "$IMAGE_NAME:latest"
image_sha="$(docker inspect --format={{ '"{{index .RepoDigests 0}}"' }} $IMAGE_NAME)"
echo "Calculated image sha: $image_sha"

if dokku apps:exists $APPNAME; then
    dokku git:from-image $APPNAME $image_sha || echo "Already on latest"
    exit 0
fi

dokku apps:create "$APPNAME"
dokku postgres:create "$APPNAME-service"
dokku postgres:link "$APPNAME-service" "$APPNAME"

# check if required dokku plugin exists
if ! dokku plugin:list | grep letsencrypt; then
    dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
fi

dokku domains:add $APPNAME $APPNAME."$(cat /home/dokku/VHOST)"
dokku letsencrypt:enable "$APPNAME"
dokku git:from-image "$APPNAME" "$image_sha"
```

--------------------------------

### Docker Compose image update for v4

Source: https://docs.ryot.io/migration

Example configuration change for the docker-compose file to upgrade to the latest RYOT version.

```yaml
image: "ignisda/ryot:latest"
```

--------------------------------

### Sink integration webhook URL format

Source: https://docs.ryot.io/integrations/overview

Webhook URL format for sink integrations. The first line shows the generic pattern with placeholders, and the second line is a concrete example. Keep these URLs private to prevent abuse.

```txt
https://<instance_url>/_i/<slug>
https://app.ryot.io/_i/int_a6cGGXEq6KOI # example
```

--------------------------------

### Create environment file with APP_VERSION, UNKEY_ROOT_KEY, DATABASE_URL

Source: https://docs.ryot.io/contributing

Create this environment file in the repository root. APP_VERSION is set to v10.0.2, UNKEY_ROOT_KEY is a dummy value, and DATABASE_URL points to the local PostgreSQL instance.

```bash
APP_VERSION=v10.0.2
UNKEY_ROOT_KEY=dummy-root-key
DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
```

--------------------------------

### Fly deployment: Launch application

Source: https://docs.ryot.io/deployment

Deploys the application using the fly.toml configuration file.

```bash
flyctl launch
```

--------------------------------

### Fly deployment: Create database

Source: https://docs.ryot.io/deployment

Initial step to create a new postgres database for the Ryot instance on Fly.

```bash
flyctl postgres create ryot-db
```

--------------------------------

### Fly deployment: Attach database

Source: https://docs.ryot.io/deployment

Connects the previously created postgres database to the Ryot application.

```bash
fly postgres attach --app ryot ryot-db
```

--------------------------------

### Run final v1 release for migrations

Source: https://docs.ryot.io/migration

Run the last v1 release of the server to perform all necessary migrations before upgrading.

```bash
$ docker run --volume ./ryot/data:/data ignisda/ryot:v1.22.1
```

--------------------------------

### Deploy Ryot with Docker Compose

Source: https://docs.ryot.io/

Use this docker-compose.yml file to set up the Ryot service and its required PostgreSQL database. Ensure you replace the placeholder values for FRONTEND_URL, DATABASE_URL, and SERVER_ADMIN_ACCESS_TOKEN.

```yaml
services:
  ryot-db:
    image: postgres:18-alpine # at-least version 15 is required
    restart: unless-stopped
    container_name: ryot-db
    volumes:
      - postgres_storage:/var/lib/postgresql
    environment:
      - TZ=Europe/Amsterdam
      - POSTGRES_DB=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres

  ryot:
    image: ignisda/ryot:v10 # or ghcr.io/ignisda/ryot:v10
    pull_policy: always
    container_name: ryot
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - TZ=Europe/Amsterdam
      - FRONTEND_URL=https://ryot.your-domain.com # IP address is fine too
      - DATABASE_URL=postgres://postgres:postgres@ryot-db:5432/postgres # REQUIRED
      - SERVER_ADMIN_ACCESS_TOKEN=28ebb3ae554fa9867ba0 # REQUIRED: set to a long random string

volumes:
  postgres_storage:
```

--------------------------------

### Set Spotify environment variables

Source: https://docs.ryot.io/guides/music

Configure the Spotify Client ID and Client Secret as environment variables for your Ryot instance.

```bash
MUSIC_SPOTIFY_CLIENT_ID=your_client_id_here
MUSIC_SPOTIFY_CLIENT_SECRET=your_client_secret_here
```

--------------------------------

### Convert local user to OIDC user with SQL

Source: https://docs.ryot.io/guides/authentication

SQL commands to convert a local user to an OIDC user. First, delete the newly created OIDC user (identified by its oidc_issuer_id) using DELETE FROM "user" WHERE id = 'usr_v5aGOC9UzrId';. Then update the old local user's record with the OIDC issuer ID and set password to NULL using UPDATE "user" SET oidc_issuer_id = '104798859970005336426', password = NULL WHERE id = 'usr_ujrD0pCeKc1Y';. Run these in the database via docker exec -u postgres -it ryot-db psql.

```sql
DELETE FROM "user" WHERE id = 'usr_v5aGOC9UzrId';
```

```sql
UPDATE "user" SET oidc_issuer_id = '104798859970005336426', password = NULL WHERE id = 'usr_ujrD0pCeKc1Y';
```

--------------------------------

### Fly deployment: Configure secrets

Source: https://docs.ryot.io/deployment

Sets instance configuration secrets, such as S3 storage URLs.

```bash
fly secrets set FILE_STORAGE_S3_URL='https://play.min.io:9000'
```

--------------------------------

### Insert seaql_migrations for v3 to v4 upgrade

Source: https://docs.ryot.io/migration

SQL statements to populate the seaql_migrations table during the upgrade process from v3 to v4.

```sql
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230410_create_metadata', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230413_create_person', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230417_create_user', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230419_create_seen', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230501_create_metadata_group', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230502_create_genre', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230504_create_collection', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230505_create_review', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230509_create_import_report', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230622_create_exercise', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230804_create_user_measurement', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230819_create_workout', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230901_create_partial_metadata', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230912_create_calendar_event', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20231003_create_partial_metadata_to_person', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20231016_create_collection_to_entity', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20231017_create_user_to_entity', 1697640078);
```

--------------------------------

### Enable Ryot Pro Features

Source: https://docs.ryot.io/

Add the SERVER_PRO_KEY environment variable to your existing ryot service configuration in docker-compose.yml to enable Pro features.

```diff
  ryot:
    environment:
+      - SERVER_PRO_KEY=<pro_key_issued_to_you>
```

--------------------------------

### Configure OIDC environment variables

Source: https://docs.ryot.io/guides/authentication

Environment variables required to configure OpenID Connect (OIDC) authentication for Ryot. Set SERVER_OIDC_CLIENT_ID, SERVER_OIDC_CLIENT_SECRET, and SERVER_OIDC_ISSUER_URL; FRONTEND_URL is the instance URL. Optional variables include FRONTEND_OIDC_BUTTON_LABEL and RUST_LOG for debugging. After setting these, restart the instance to see the 'Continue with OpenID Connect' button.

```bash
FRONTEND_URL=https://app.ryot.io # The URL of your Ryot instance
SERVER_OIDC_CLIENT_ID=********
SERVER_OIDC_CLIENT_SECRET=********
SERVER_OIDC_ISSUER_URL=https://accounts.google.com # The URL of your OIDC provider (might end with trailing slash)
# Below are optional
FRONTEND_OIDC_BUTTON_LABEL=Use Google
RUST_LOG=ryot=debug # To debug why OIDC authentication is failing
```

--------------------------------

### Reset and populate seaql_migrations for v2 to v3 upgrade

Source: https://docs.ryot.io/migration

SQL commands to clear existing migrations and re-insert the required migration history for the v2 to v3 upgrade.

```sql
DELETE FROM seaql_migrations;

INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230410_create_metadata', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230413_create_person', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230417_create_user', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230419_create_seen', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230502_create_genre', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230505_create_review', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230507_create_collection', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230509_create_import_report', 1684693316);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230622_create_exercise', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230804_create_user_measurement', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230819_create_workout', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230901_create_metadata_group', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230901_create_partial_metadata', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20230912_create_calendar_event', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20231003_create_partial_metadata_to_person', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20231016_create_collection_to_entity', 1697640078);
INSERT INTO seaql_migrations (version, applied_at) VALUES ('m20231017_create_user_to_entity', 1697640078);
```

--------------------------------

### Configure Ryot for Cloudflare R2 with environment variables

Source: https://docs.ryot.io/guides/file-storage

Set these environment variables on your Ryot instance to use Cloudflare R2 for file storage and exporting. Replace <ACCOUNT_ID> with your Cloudflare account ID and use the actual values for your bucket name and API credentials. FILE_STORAGE_S3_REGION is optional; some clients require a region, so use "auto" for R2.

```sh
FILE_STORAGE_S3_BUCKET_NAME=ryot-storage
FILE_STORAGE_S3_ACCESS_KEY_ID=your-access-key-id
FILE_STORAGE_S3_SECRET_ACCESS_KEY=your-secret-access-key
FILE_STORAGE_S3_URL=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
FILE_STORAGE_S3_REGION=auto # optional: some clients require a region; use "auto" for R2
```

--------------------------------

### Export and restore the entire database with pg_dump and pg_restore

Source: https://docs.ryot.io/exporting

Use these commands to export and restore the entire Ryot database. The first command dumps the database to a file, and the second restores it from that file. Both commands require the ryot-db container to be running.

```bash
docker exec -u postgres -i ryot-db pg_dump -Fc --no-acl --no-owner > /tmp/ryot.file.sql
```

```bash
docker exec -u postgres -i ryot-db pg_restore -U postgres -d postgres < /tmp/ryot.file.sql
```

--------------------------------

### WorkoutSummary Interface

Source: https://docs.ryot.io/exporting

Represents the overall summary of a workout, containing exercises, focused metrics, and total values.

```typescript
export interface WorkoutSummary {
	exercises: WorkoutSummaryExercise[];
	focused: WorkoutFocusedSummary;
	total: WorkoutOrExerciseTotals | null;
}
```

--------------------------------

### Workout Summary Interfaces

Source: https://docs.ryot.io/exporting

Interfaces for summarizing exercises, equipment, force, and level focus within a workout.

```typescript
/** The summary about an exercise done in a workout. */
export interface WorkoutSummaryExercise {
	best_set: WorkoutSetRecord | null;
	id: string;
	/** @default 'reps_and_weight' */
	lot: ExerciseLot | null;
	num_sets: number;
	/**
	 * @default 'metric'
	 * @type {'metric' | 'imperial'}
	 */
	unit_system: UserUnitSystem;
}

export type ExerciseEquipment = 'bands' | 'cable' | 'other' | 'barbell' | 'machine' | 'body_only' | 'dumbbell' | 'foam_roll' | 'ez_curl_bar' | 'kettlebells' | 'exercise_ball' | 'medicine_ball';

export interface WorkoutEquipmentFocusedSummary {
	/**
	 * @default 'barbell'
	 * @type {'bands' | 'cable' | 'other' | 'barbell' | 'machine' | 'body_only' | 'dumbbell' | 'foam_roll' | 'ez_curl_bar' | 'kettlebells' | 'exercise_ball' | 'medicine_ball'}
	 */
	equipment: ExerciseEquipment;
	exercises: number[];
}

export type ExerciseForce = 'pull' | 'push' | 'static';

export interface WorkoutForceFocusedSummary {
	exercises: number[];
	/**
	 * @default 'pull'
	 * @type {'pull' | 'push' | 'static'}
	 */
	force: ExerciseForce;
}

export type ExerciseLevel = 'beginner' | 'expert' | 'intermediate';

export interface WorkoutLevelFocusedSummary {
	exercises: number[];
	/**
	 * @default 'beginner'
	 * @type {'beginner' | 'expert' | 'intermediate'}
	 */
	level: ExerciseLevel;
}
```

--------------------------------

### Set Hardcover API key environment variable

Source: https://docs.ryot.io/guides/books

Set this environment variable to enable Hardcover book tracking in Ryot. The API key expires after a year or on January 1st, so you will need to renew it accordingly.

```bash
BOOKS_HARDCOVER_API_KEY=Bearer eyJhbGciOiJIUzI1NiIsCJ9.5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36Pw5c
```

--------------------------------

### WorkoutFocusedSummary Interface

Source: https://docs.ryot.io/exporting

Aggregates various focused summary types including equipment, forces, levels, lots, and muscles.

```typescript
export interface WorkoutFocusedSummary {
	equipments: WorkoutEquipmentFocusedSummary[];
	forces: WorkoutForceFocusedSummary[];
	levels: WorkoutLevelFocusedSummary[];
	lots: WorkoutLotFocusedSummary[];
	muscles: WorkoutMuscleFocusedSummary[];
}
```

--------------------------------

### ImportOrExportMetadataItem interface

Source: https://docs.ryot.io/exporting

Defines a media item for import/export, including collections, identifier, lot, reviews, seen history, source, and source_id. The lot defaults to 'book' and source defaults to 'custom'.

```typescript
export interface ImportOrExportMetadataItem {
	/** The collections this entity was added to. */
	collections: CollectionToEntityDetails[];
	/** The provider identifier. For eg: TMDB-ID, Openlibrary ID and so on. */
	identifier: string;
	/**
	 * The type of media.
	 *
	 * @default 'book'
	 * @type {'book' | 'show' | 'movie' | 'anime' | 'manga' | 'music' | 'podcast' | 'audio_book' | 'video_game' | 'comic_book' | 'visual_novel'}
	 */
	lot: MediaLot;
	/** The review history for the user. */
	reviews: ImportOrExportItemRating[];
	/** The seen history for the user. */
	seen_history: ImportOrExportMetadataItemSeen[];
	/**
	 * The source of media.
	 *
	 * @default 'custom'
	 * @type {'igdb' | 'tmdb' | 'tvdb' | 'vndb' | 'custom' | 'metron' | 'itunes' | 'anilist' | 'audible' | 'spotify' | 'music_brainz' | 'giant_bomb' | 'hardcover' | 'myanimelist' | 'listennotes' | 'google_books' | 'openlibrary' | 'manga_updates' | 'youtube_music'}
	 */
	source: MediaSource;
	/** An string to help identify it in the original source. */
	source_id: string;
}
```

--------------------------------

### Workout Interface

Source: https://docs.ryot.io/exporting

Represents a completed workout by the user, including timing, metrics, and summary data.

```typescript
/** A workout that was completed by the user. */
export interface Workout {
	calories_burnt: string | null;
	duration: number;
	end_time: string;
	id: string;
	information: WorkoutInformation;
	name: string;
	repeated_from: string | null;
	start_time: string;
	summary: WorkoutSummary;
	template_id: string | null;
}
```

--------------------------------

### WorkoutMuscleFocusedSummary Interface

Source: https://docs.ryot.io/exporting

Defines the structure for a workout summary focused on specific muscle groups.

```typescript
export interface WorkoutMuscleFocusedSummary {
	exercises: number[];
	/**
	 * @default 'abdominals'
	 * @type {'lats' | 'neck' | 'traps' | 'chest' | 'biceps' | 'calves' | 'glutes' | 'triceps' | 'forearms' | 'abductors' | 'adductors' | 'lower_back' | 'shoulders' | 'abdominals' | 'hamstrings' | 'middle_back' | 'quadriceps'}
	 */
	muscle: ExerciseMuscle;
}
```

--------------------------------

### Workout Set Statistics and Records

Source: https://docs.ryot.io/exporting

Interfaces for tracking individual set statistics, totals, and records.

```typescript
/** Details about the statistics of the set performed. */
export interface WorkoutSetStatistic {
	distance: string | null;
	duration: string | null;
	one_rm: string | null;
	pace: string | null;
	reps: string | null;
	volume: string | null;
	weight: string | null;
}

export interface WorkoutSetTotals {
	weight: string | null;
}

/** Details about the set performed. */
export interface WorkoutSetRecord {
	confirmed_at: string | null;
	/**
	 * @default 'normal'
	 * @type {'drop' | 'normal' | 'warm_up' | 'failure'}
	 */
	lot: SetLot;
	note: string | null;
	personal_bests: WorkoutSetPersonalBest[] | null;
	rest_time: number | null;
	rest_timer_started_at: string | null;
	rpe: number | null;
	statistic: WorkoutSetStatistic;
	totals: WorkoutSetTotals | null;
}
```
Tokens:
Raw