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'
- 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 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
- Download a copy of the
docker-compose.ymlfile. - Edit the
docker-compose.ymlfile modifying the environment variables, see environment variables for more information. - Run
docker compose up -d. - Visit the address and port you specified for the frontend and login with username:
adminpassword:ganymede. - Change the admin password _or_ create a new user, grant admin permissions on that user, and delete the admin user.
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 directory. It will not recursively chown the /data/videos directory. Ensure the mounted /data/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 docker-compose.yml file has comments for each environment variable. Below is a list of all environment variables and their descriptions. See the env.go file for a full list of all environment variables and their default values.
##### 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. |
| 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. |
| MAX_CHAT_RENDER_EXECUTIONS | Maximum number of chat renders that can be running at once. |
| MAX_VIDEO_DOWNLOAD_EXECUTIONS | Maximum number of video downloads that can be running at once. Live streams bypass this limit. |
| MAX_VIDEO_CONVERT_EXECUTIONS | Maximum number of video conversions that can be running at once. |
| MAX_VIDEO_SPRITE_THUMBNAIL_EXECUTIONS | Maximum number of video sprite thumbnail generation jobs that can be running at once. This is not very CPU intensive. |
| 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.