Ganymede
Docker app from grtgbln's Repository
A Twitch VOD and Live Stream archiving platform with a real-time chat experience.
Requirements
Requires a separate Postgres database.
Overview
Readme
View on GitHub
Ganymede
Ganymede is a Twitch VOD and Live Stream archiving platform with a real-time chat experience. Every archive includes a rendered chat for viewing outside of Ganymede. Files are saved in a friendly format allowing for use without Ganymede.
Screenshot
https://github.com/user-attachments/assets/184451f1-e3ce-4329-8516-a9842648c01b
About
Ganymede allows archiving of past streams (VODs) and live streams with a real-time chat playback along with a archival-friendly rendered chat. All files are saved in a friendly way that doesn't require Ganymede to view them (see file structure). Ganymede is the successor of Ceres.
Features
- Realtime Chat Playback
- SSO / OAuth authentication (wiki)
- Light/dark mode toggle.
- 'Watched channels'
- Allows watching channels for archiving past broadcasts and live streams. Includes advanced filtering options.
- Twitch VOD/Livestream support.
- Full VOD, Channel, and User management.
- Custom post-download video FFmpeg parameters.
- Custom chat render parameters.
- Webhook notifications.
- Simple file structure for long-term archival that will outlast Ganymede.
- Recoverable queue system.
- Playback / progress saving.
- Playlists.
Documentation
For in-depth documentation on features visit the wiki.
API
Visit the docs folder for the API docs.
Translations
See the messages directory for available translations. If you would like to add a new translation, please create a pull request with the new translation file. The file should be named <language>.json where <language> is the language code (e.g. de.json for German). Additionally the language needs to be added to the navbar in the frontend/app/layout/Navbar.tsx file in the languages array. Use the frontend/translation-coverage.js script to see what has been translated or with the -u option to populate missing keys in translation files.
Installation
Requirements
- Linux environment with Docker.
- Optional network mounted storage.
- 50gb+ free storage, see storage requirements.
- A Twitch Application
Installation
Ganymede consists of two docker containers:
- Server
- Postgres Database
Feel free to use an existing Postgres database container if you don't want to spin new ones up.
- Download
compose.yamland.env.exampleinto the same directory. - Copy
.env.exampleto.envand edit it: set the Twitch credentials, choose a database password, and set the host storage paths. See environment variables for more information. Keep.envprivate: it contains credentials. - Run
docker compose up -dfrom that directory. - Visit
http://<host>:4800(or the port set byGANYMEDE_PORT) and log in with username:adminpassword:ganymede. - Change the admin password or create a new user, grant admin permissions on that user, and delete the admin user.
Migrating an existing Compose installation
Copy your existing settings and host and container paths into .env before starting the new Compose file. Keep the same Compose project directory, project name, and database storage path to use the existing data. If you used -p or COMPOSE_PROJECT_NAME, continue using the same project name. Remove or rename the old docker-compose.yml after adopting compose.yaml, and migrate any settings in an existing docker-compose.override.yml to compose.override.yaml. Changing DB_USER, DB_PASS, or DB_NAME in .env does not update an already initialized PostgreSQL database; keep its existing credentials or change them in PostgreSQL as well.
Single-quote passwords containing $ in .env to prevent Compose interpolation. For example, write DB_PASS='pa$word' to preserve the literal password pa$word.
PostgreSQL is no longer published on host port 4801. If host access is needed, add a compose.override.yaml with a port mapping, preferably bound to localhost, and attach PostgreSQL to the default network as well as its internal database network:
services:
ganymede-db:
ports:
- "127.0.0.1:4801:5432"
networks:
- default
Stop grace period
A clean shutdown can take up to ~80s. The example compose file sets stop_grace_period: 90s; on Kubernetes set terminationGracePeriodSeconds: 90.
A fatal process error stops the container with exit code 0, so use the unless-stopped/always restart policy, not on-failure.
Images
Images are published to ghcr.io. There are four types of tags available.
| Tag | Description |
|---|---|
| latest | Points to the latest release. |
| semver - e.g. 4.10.0 | The latest release in semver format. |
| dev | Build of the 'main' branch. Use for testing new features before release. |
| pr-* - e.g. pr-123 | Build of a pull request. Gets deleted when the PR is closed. |
Rootless
The API container can be run as a non root user. To do so add PUID and PGID environment variables, setting the value to your user. Read linuxserver's docs about this for more information.
Note: On startup the container will chown the config, temp, and logs directories. It will not recursively chown the videos directory (/data/videos by default). Ensure the mounted videos directory is readable by the set user.
If your storage does not support chown, such as an NFS or SMB mount (e.g. TrueNAS with NFSv4 ACLs), set SKIP_CHOWN=true to skip this step. Ensure the directories are already writable by the set user.
Config
A configuration file is generate on initial start of Ganymede. By default the configuration is at /data/config/config.json. See the config.go file for a full list of configuration settings. Most of the settings can be configured in the Web UI by navigating to Admin > Settings.
Environment Variables
The .env.example file documents the Compose settings and common environment variables. Below is a list of environment variables and their descriptions. See the env.go file for a full list of all environment variables and their default values.
In the Compose example, GANYMEDE_PORT sets the host port for the web interface (default 4800). VIDEOS_HOST_DIR, TEMP_HOST_DIR, LOGS_HOST_DIR, CONFIG_HOST_DIR, and DB_HOST_DIR select the host storage locations. Relative paths are resolved from the Compose project directory. The corresponding application *_DIR values select paths inside the container. Shell variables take precedence over .env for Compose interpolation; directory paths and shared database credentials are passed to both services or mounts using those interpolated values. PostgreSQL uses a dedicated internal network shared with Ganymede; Ganymede also uses the default network for external connectivity.
Server
| ENV Name | Description |
|---|---|
DEBUG |
Enable debug logging true or false. |
VIDEOS_DIR |
Path inside the container to the videos directory. Default: /data/videos. |
TEMP_DIR |
Path inside the container where temporary files are stored during archiving. Default: /data/temp. |
LOGS_DIR |
Path inside the container where log files are stored. Default: /data/logs. |
CONFIG_DIR |
Path inside the container where the config is stored. Default: /data/config. |
SKIP_CHOWN |
Optional Skip chown of the data directories on startup. Useful when storage does not support chown, e.g. NFS/SMB. Default: false. |
PATH_MIGRATION_ENABLED |
Enable path migration at startup. Default: true. |
TZ |
Timezone. |
DB_HOST |
Host of the database. |
DB_PORT |
Port of the database. |
DB_USER |
Username for the database. |
DB_PASS |
Password for the database. |
DB_NAME |
Name of the database. |
DB_SSL |
Whether to use SSL. Default: disable. See DB SSL for more information. |
DB_SSL_ROOT_CERT |
Optional Path to DB SSL root certificate. See DB SSL for more information. |
DB_MAX_CONNS |
Optional Caps each Postgres pool. API and worker each open 2 pools, and the worker's task queue holds 1 more connection outside its pool, so the total is at most 4 × value + 1 (5 allows 21). Low values queue requests under load. Minimum 2. Default: library defaults. |
TWITCH_CLIENT_ID |
Twitch application client ID. |
TWITCH_CLIENT_SECRET |
Twitch application client secret. |
OAUTH_ENABLED |
Optional Wether OAuth is enabled true or false. Must have the other OAuth variables set if this is enabled. |
OAUTH_PROVIDER_URL |
Optional OAuth provider URL. See https://github.com/Zibbp/ganymede/wiki/SSO---OpenID-Connect |
OAUTH_CLIENT_ID |
Optional OAuth client ID. |
OAUTH_CLIENT_SECRET |
Optional OAuth client secret. |
OAUTH_REDIRECT_URL |
Optional OAuth redirect URL, points to the API. Example: http://localhost:4000/api/v1/auth/oauth/callback. |
MAX_CHAT_DOWNLOAD_EXECUTIONS |
Maximum number of chat downloads that can be running at once. Live streams bypass this limit. This is memory-intensive, using around 1.9GB (per execution). CPU is negligible. Uses some network bandwidth. |
MAX_CHAT_RENDER_EXECUTIONS |
Maximum number of chat renders that can be running at once. This is very CPU-intensive. Memory is around 500MB (per execution). |
MAX_VIDEO_DOWNLOAD_EXECUTIONS |
Maximum number of video downloads that can be running at once. Live streams bypass this limit. Is storage- and network-intensive. |
MAX_VIDEO_CONVERT_EXECUTIONS |
Maximum number of video conversions that can be running at once. Can be resource-intensive depending on your FFmpeg arguments. By default, it is storage intensive and uses some memory. |
MAX_VIDEO_SPRITE_THUMBNAIL_EXECUTIONS |
Maximum number of video sprite thumbnail generation jobs that can be running at once. CPU, memory, and storage utilization is negligible. |
DISABLE_LIVE_ARCHIVE_STALL_CHECK |
Disable FFmpeg progress based stall detection for live archives. Default: false. |
LIVE_ARCHIVE_STALL_TIMEOUT_SECONDS |
Seconds without FFmpeg media progress before a live capture is stopped. Default: 180; values below 30 use the default. |
SHOW_SSO_LOGIN_BUTTON |
Frontend: true/false Show a "login via sso" button on the login page (defaults to false). |
FORCE_SSO_AUTH |
Frontend: true/false Force users to login via SSO by bypassing the login page (defaults to false). |
REQUIRE_LOGIN |
Frontend: true/false Require users to be logged in to view videos (defaults to false). |
SHOW_LOCALE_BUTTON |
Frontend: true/false Show the locale/language button on the navbar (defaults to true). |
DEFAULT_LOCALE |
Frontend: Sets the default locale/language. Must be the short code of the language. Example: en for English, de for German. |
FORCE_LOGIN |
Frontend: true/false Force require users to login to view any page (defaults to false). |
DB
Ensure these are the same in the API environment variables.
| ENV Name | Description |
|---|---|
POSTGRES_PASSWORD |
Database password |
POSTGRES_USER |
Database username. |
POSTGRES_DB |
Name of the database. |
Volumes
API
| Volume | Description | Example |
|---|---|---|
/data/videos |
Mount for video storage. This must match the VIDEOS_DIR environment variable. |
/mnt/nas/vods:/data/videos |
/data/logs |
Mount to store task logs. This must match the LOGS_DIR environment variable. |
./logs:/data/logs |
/data/temp |
Mount to store temporary files during the archive process. This is mounted to the host so files are recoverable in the event of a crash. This must match the TEMP_DIR environment variable. |
./temp:/data/temp |
/data/config |
Mount to store the config. This must match the CONFIG_DIR environment variable. |
./config:/data/config |
Development
A devcontainer is included for development. This container includes all the necessary tools to develop Ganymede. Once setup, the Makefile can be used to run the development environment.
make dev_server- Starts the server.make dev_worker- Starts the worker.make dev_web- Starts the web server.
View the Makefile for more commands.
Acknowledgements
License
Media gallery
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/zibbp/ganymede:latestRuntime arguments
- Web UI
http://[IP]:[PORT:4000]/- Network
bridge- Privileged
- false
Template configuration
Container Port: 4000
- Target
- 4000
- Default
- 4000
- Value
- 4000
Twitch Client ID
- Target
- TWITCH_CLIENT_ID
Twitch Client Secret
- Target
- TWITCH_CLIENT_SECRET
Postgres host
- Target
- DB_HOST
Postgres port
- Target
- DB_PORT
- Default
- 5432
- Value
- 5432
Postgres database name
- Target
- DB_NAME
- Default
- ganymede
- Value
- ganymede
Postgres user
- Target
- DB_USER
Postgres password
- Target
- DB_PASS
Use SSL for Postgres connection. Details: https://github.com/Zibbp/ganymede/wiki/DB-SSL
- Target
- DB_SSL
- Default
- disable|enable
Postgres SSL root certificate. Remove if not needed. Details: https://github.com/Zibbp/ganymede/wiki/DB-SSL
- Target
- DB_SSL_ROOT_CERT
Require users to be logged in to view videos.
- Target
- REQUIRE_LOGIN
- Default
- false|true
Enable OAuth
- Target
- OAUTH_ENABLED
- Default
- false|true
URL for OAuth provider. Details: https://github.com/Zibbp/ganymede/wiki/SSO---OpenID-Connect
- Target
- OAUTH_PROVIDER_URL
OAuth client ID
- Target
- OAUTH_CLIENT_ID
OAuth client secret
- Target
- OAUTH_CLIENT_SECRET
OAuth redirect URL. Details: https://github.com/Zibbp/ganymede/wiki/SSO---OpenID-Connect
- Target
- OAUTH_REDIRECT_URL
Show a 'login via sso' button on the login page.
- Target
- SHOW_SSO_LOGIN_BUTTON
- Default
- false|true
Force users to login via SSO by bypassing the login page.
- Target
- FORCE_SSO_AUTH
- Default
- false|true
Maximum number of chat downloads that can be running at once. Live streams bypass this limit.
- Target
- MAX_CHAT_DOWNLOAD_EXECUTIONS
- Default
- 1
- Value
- 1
Maximum number of chat renders that can be running at once.
- Target
- MAX_CHAT_RENDER_EXECUTIONS
- Default
- 1
- Value
- 1
Maximum number of video downloads that can be running at once. Live streams bypass this limit.
- Target
- MAX_VIDEO_DOWNLOAD_EXECUTIONS
- Default
- 1
- Value
- 1
Maximum number of video conversions that can be running at once.
- Target
- MAX_VIDEO_CONVERT_EXECUTIONS
- Default
- 1
- Value
- 1
Mount for video storage
- Target
- /data/videos
Enable debug logging
- Target
- DEBUG
- Default
- false|true
Internal path to videos. Not recommended to change.
- Target
- VIDEOS_DIR
- Default
- /data/videos
- Value
- /data/videos
Internal path to temporary data. Not recommended to change.
- Target
- TEMP_DIR
- Default
- /data/temp
- Value
- /data/temp
Internal path to logs. Not recommended to change.
- Target
- LOGS_DIR
- Default
- /data/logs
- Value
- /data/logs
Internal path to config. Not recommended to change.
- Target
- CONFIG_DIR
- Default
- /data/config
- Value
- /data/config
Enable path migration at startup
- Target
- PATH_MIGRATION_ENABLED
- Default
- true|false
Mount for config storage
- Target
- /data/config
- Default
- /mnt/user/appdata/ganymede/config
- Value
- /mnt/user/appdata/ganymede/config
Mount for log storage
- Target
- /data/logs
- Default
- /mnt/user/appdata/ganymede/logs
- Value
- /mnt/user/appdata/ganymede/logs
Mount to store temporary files during the archive process.
- Target
- /data/temp
- Default
- /mnt/user/appdata/ganymede/temp
- Value
- /mnt/user/appdata/ganymede/temp