Skip to content

Commit

Permalink
documentation update
Browse files Browse the repository at this point in the history
  • Loading branch information
@Zibbp
Zibbp committed Aug 11, 2024
1 parent 0332472 commit f0f1522
Show file tree
Hide file tree
Showing 3 changed files with 62 additions and 59 deletions.
3 changes: 2 additions & 1 deletion .devcontainer/devcontainer.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"eamodio.gitlens",
"github.copilot"
"github.copilot",
"yzhang.markdown-all-in-one"
]
}
},
Expand Down
101 changes: 51 additions & 50 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,35 +7,37 @@
<h2 align="center">Ganymede</h2>

<p align="center">
Twitch VOD and Stream archiving platform with a rendered chat. Files are saved in a friendly format allowing for use without Ganymede.
Twitch VOD and Live Stream archiving platform with a real-time and rendered chat experience. Files are saved in a friendly format allowing for use without Ganymede.
</p>
</div>

---

## Demo
## Screenshot

![ganymede-readme_landing](https://user-images.githubusercontent.com/21207065/203620886-f40b82f6-317c-4ded-afdc-733d1658f6ca.jpg)

https://user-images.githubusercontent.com/21207065/203620893-41a6a3a0-339a-4c62-8df8-0f66ec68327d.mp4

## About

Ganymede allows archiving of past streams (VODs) and livestreams both with a rendered chat. All files are saved in a friendly way that doesn't require Ganymede to view them (see [file structure](https://github.com/Zibbp/ganymede/wiki/File-Structure)). Ganymede is the successor of [Ceres](https://github.com/Zibbp/Ceres).
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](https://github.com/Zibbp/ganymede/wiki/File-Structure)). Ganymede is the successor of [Ceres](https://github.com/Zibbp/Ceres).

## Features

- Realtime Chat Playback
- SSO / OAuth authentication ([wiki](https://github.com/Zibbp/ganymede/wiki/SSO---OpenID-Connect))
- Light/dark mode toggle.
- Watch channels for new videos and streams.
- 'Watched channels' - watch channels for videos and live streams.
- Twitch VOD/Livestream support.
- Queue holds.
- Queue task restarts.
- 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 outlas Ganymede.
- Recoverable queue system.
- Playback / progress saving.
- Playlists.

## Documentation

Expand Down Expand Up @@ -67,7 +69,7 @@ Ganymede consists of four docker containers:
Feel free to use an existing Postgres database container and Nginx container if you don't want to spin new ones up.

1. Download a copy of the `docker-compose.yml` file and `nginx.conf`.
2. Edit the `docker-compose.yml` file modifying the environment variables, see [environment variables](https://github.com/Zibbp/ganymede#environment-variables).
2. Edit the `docker-compose.yml` file modifying the environment variables, see [environment variables](https://github.com/Zibbp/ganymede#environment-variables) for more information.
3. Run `docker compose up -d`.
4. Visit the address and port you specified for the frontend and login with username: `admin` password: `ganymede`.
5. Change the admin password _or_ create a new user, grant admin permissions on that user, and delete the admin user.
Expand All @@ -76,37 +78,43 @@ Feel free to use an existing Postgres database container and Nginx container if

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](https://docs.linuxserver.io/general/understanding-puid-and-pgid) about this for more information.

Note: On startup the container will `chown` `/data`, `/logs`, and `/tmp`. It will not recursively `chown` the `/vods` directory. Ensure the mounted `vods` directory is readable by the set user.
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.

### Environment Variables

The `docker-compose.yml` file has comments for each environment variable. The `*_URL` envionrment variables _must_ be the 'public' URLs (e.g. `https://ganymedem.domain.com`) it cannot be a URL to just the docker service.

##### API

| ENV Name | Description |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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](https://github.com/Zibbp/ganymede/wiki/DB-SSL) for more information. |
| `DB_SSL_ROOT_CERT` | _Optional_ Path to DB SSL root certificate. See [DB SSL](https://github.com/Zibbp/ganymede/wiki/DB-SSL) for more information. |
| `JWT_SECRET` | Secret for JWT tokens. This should be a long random string. |
| `JWT_REFRESH_SECRET` | Secret for JWT refresh tokens. This should be a long random string. |
| `TWITCH_CLIENT_ID` | Twitch application client ID. |
| `TWITCH_CLIENT_SECRET` | Twitch application client secret. |
| `FRONTEND_HOST` | Host of the frontend, used for CORS. Example: `http://192.168.1.2:4801` |
| `COOKIE_DOMAIN` | _Optional_ Base domain for cookies. Used when reverse proxying. See [reverse proxy](https://github.com/Zibbp/ganymede/wiki/Reverse-Proxy) for more information. |
| `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`. |
| `TEMPORAL_URL` | URL to the Temporal server |
| `MAX_CHAT_DOWNLOAD_EXECUTIONS` | Maximum number of chat downloads that can be running at once. |
| `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. |
| `MAX_VIDEO_CONVERT_EXECUTIONS` | Maximum number of video conversions that can be running at once. |
| 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`. |
| `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](https://github.com/Zibbp/ganymede/wiki/DB-SSL) for more information. |
| `DB_SSL_ROOT_CERT` | _Optional_ Path to DB SSL root certificate. See [DB SSL](https://github.com/Zibbp/ganymede/wiki/DB-SSL) for more information. |
| `JWT_SECRET` | Secret for JWT tokens. This should be a long random string. |
| `JWT_REFRESH_SECRET` | Secret for JWT refresh tokens. This should be a long random string. |
| `TWITCH_CLIENT_ID` | Twitch application client ID. |
| `TWITCH_CLIENT_SECRET` | Twitch application client secret. |
| `FRONTEND_HOST` | Host of the frontend, used for CORS. Example: `http://192.168.1.2:4801` |
| `OAUTH_ENABLED` | _Optional_ Wheter 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. |

##### Frontend

Expand All @@ -132,22 +140,19 @@ Note: On startup the container will `chown` `/data`, `/logs`, and `/tmp`. It wil

##### API

| Volume | Description | Example |
| ------- | ------------------------------------------------------------------------------- | ----------------------- |
| `/vods` | Mount for VOD storage. This example I have my NAS mounted to `/mnt/vault/vods`. | `/mnt/vault/vods:/vods` |
| `/logs` | Queue log folder. | `./logs:/logs` |
| `/data` | Config folder. | `./data:/data` |

**Optional**

`./tmp:/tmp` Binding the `tmp` folder prevents lost data if the container crashes as temporary downloads are stored in `tmp` which gets flushed when the container stops.
| 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 temporay 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` |

##### Nginx

| Volume | Description | Example |
| -------------------------- | ---------------------------------------------- | ---------------------------------------------- |
| `/mnt/vods` | VOD storage, same as the API container volume. | `/mnt/vault/vods:/mnt/vods` |
| `/etc/nginx/nginx.conf:ro` | Path to the Nginx conf file. | `/path/to/nginx.conf:/etc/nginx/nginx.conf:ro` |
| Volume | Description | Example |
| -------------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| `/data/videos` | Mount for video storage, same as the API container volume. | `/mnt/nas/vods:/data/videos` |
| `/etc/nginx/nginx.conf:ro` | Path to the Nginx conf file. | `/path/to/nginx.conf:/etc/nginx/nginx.conf:ro` |

## Acknowledgements

Expand All @@ -158,7 +163,3 @@ Note: On startup the container will `chown` `/data`, `/logs`, and `/tmp`. It wil
## License

[GNU General Public License v3.0](https://github.com/Zibbp/ganymede/blob/master/LICENSE)

## Authors

- [@Zibbp](https://www.github.com/Zibbp)
Loading

0 comments on commit f0f1522

Please sign in to comment.