From 5774aefdf9628ec651f7b7fa7e8dda5a13f12019 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 15:15:59 +0100 Subject: [PATCH 01/65] Setup jekyll documentation --- docs/_config.yml | 2 ++ docs/index.md | 3 +++ 2 files changed, 5 insertions(+) create mode 100644 docs/_config.yml create mode 100644 docs/index.md diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..c34df6fb --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,2 @@ +plugins: + - jemoji diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..30aceefb --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +# Zwift + +Easily Zwift on Linux! :100: From 24871242da11b365ab4686a6b92ef14db292ff73 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 16:06:52 +0100 Subject: [PATCH 02/65] Create workflow to build pages site --- .github/workflows/github_pages.yaml | 39 +++++++++++++++++++++++++++++ docs/index.md | 3 +++ 2 files changed, 42 insertions(+) create mode 100644 .github/workflows/github_pages.yaml diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml new file mode 100644 index 00000000..73ac3eb2 --- /dev/null +++ b/.github/workflows/github_pages.yaml @@ -0,0 +1,39 @@ +name: Build Jekyll site +on: + push: + branches: ["gp-docs"] + workflow_dispatch: +permissions: + contents: read + pages: write + id-token: write +concurrency: + group: "pages" + cancel-in-progress: false +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository code + uses: actions/checkout@v6 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Build site + uses: actions/jekyll-build-pages@v1 + with: + source: ./docs + destination: ./docs/_site + - name: Upload pages artifact + uses: actions/upload-pages-artifact@v4 + with: + path: ./docs/_site + deploy: + runs-on: ubuntu-latest + needs: build + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to github pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/index.md b/docs/index.md index 30aceefb..4598821c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,6 @@ +--- +--- + # Zwift Easily Zwift on Linux! :100: From 5a6f5851aec117fdc12e324905c2dc009dc08d82 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:06:13 +0100 Subject: [PATCH 03/65] Try just the docks template --- docs/_config.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/_config.yml b/docs/_config.yml index c34df6fb..f0633c9b 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,2 +1,6 @@ +title: Zwift +description: Easily Zwift on Linux +repository: netbrain/zwift +remote_theme: just-the-docs/just-the-docs@v0.12.0 plugins: - jemoji From f6133d9c53261c5ccbd6d9dca6013cb49f26be58 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:19:06 +0100 Subject: [PATCH 04/65] Configure theme --- .config/.markdownlint-cli2.jsonc | 3 ++- docs/_config.yml | 5 +++++ docs/index.md | 5 +++++ 3 files changed, 12 insertions(+), 1 deletion(-) diff --git a/.config/.markdownlint-cli2.jsonc b/.config/.markdownlint-cli2.jsonc index 6e8ed367..53881e70 100644 --- a/.config/.markdownlint-cli2.jsonc +++ b/.config/.markdownlint-cli2.jsonc @@ -10,7 +10,8 @@ "no-duplicate-heading": { "siblings_only": true }, - "no-inline-html": false + "no-inline-html": false, + "ignore-front-matter": true }, "gitignore": true, "globs": [ diff --git a/docs/_config.yml b/docs/_config.yml index f0633c9b..3b3a9cf4 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,6 +1,11 @@ title: Zwift description: Easily Zwift on Linux +baseurl: "/zwift-linux" +url: "https://glennvl.github.io" repository: netbrain/zwift +permalink: pretty +back_to_top: true +back_to_top_text: "Back to top" remote_theme: just-the-docs/just-the-docs@v0.12.0 plugins: - jemoji diff --git a/docs/index.md b/docs/index.md index 4598821c..2c7ca538 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,9 @@ --- +title: Home +layout: home +nav_order: 1 +description: "Easily Zwift on Linux!" +permalink: / --- # Zwift From de448e17c4b834a1674245ed7f788c6dcfc4704e Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:21:40 +0100 Subject: [PATCH 05/65] Configure theme --- docs/_config.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 3b3a9cf4..73c5cfce 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,11 +1,14 @@ title: Zwift description: Easily Zwift on Linux -baseurl: "/zwift-linux" -url: "https://glennvl.github.io" +baseurl: "/zwift" +url: "https://netbrain.github.io" repository: netbrain/zwift permalink: pretty back_to_top: true back_to_top_text: "Back to top" +aux_links: + "Zwift on GitHub": + - "https://github.com/netbrain/zwift" remote_theme: just-the-docs/just-the-docs@v0.12.0 plugins: - jemoji From 3806cd42fa98b4b957cfe9b2e75864f3c6c02dc1 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:23:34 +0100 Subject: [PATCH 06/65] Configure theme --- docs/_config.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 73c5cfce..3f4ee53c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,7 +1,5 @@ title: Zwift description: Easily Zwift on Linux -baseurl: "/zwift" -url: "https://netbrain.github.io" repository: netbrain/zwift permalink: pretty back_to_top: true From 88361fc746f6f394e4998d1f814798f728f92066 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:25:57 +0100 Subject: [PATCH 07/65] Configure theme --- docs/_config.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/_config.yml b/docs/_config.yml index 3f4ee53c..e17ef196 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -7,6 +7,9 @@ back_to_top_text: "Back to top" aux_links: "Zwift on GitHub": - "https://github.com/netbrain/zwift" +nav_external_links: + - title: Zwift on GitHub + url: https://github.com/netbrain/zwift remote_theme: just-the-docs/just-the-docs@v0.12.0 plugins: - jemoji From 2b13765deea1dbe159ce16675125f9c2253a1f77 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:28:04 +0100 Subject: [PATCH 08/65] Rename to zwift container --- docs/_config.yml | 6 +++--- docs/index.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index e17ef196..e4d0ee76 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,14 +1,14 @@ -title: Zwift +title: Zwift Container description: Easily Zwift on Linux repository: netbrain/zwift permalink: pretty back_to_top: true back_to_top_text: "Back to top" aux_links: - "Zwift on GitHub": + "Zwift Container on GitHub": - "https://github.com/netbrain/zwift" nav_external_links: - - title: Zwift on GitHub + - title: Zwift Container on GitHub url: https://github.com/netbrain/zwift remote_theme: just-the-docs/just-the-docs@v0.12.0 plugins: diff --git a/docs/index.md b/docs/index.md index 2c7ca538..7aa95e49 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,6 @@ description: "Easily Zwift on Linux!" permalink: / --- -# Zwift +# Zwift Container Easily Zwift on Linux! :100: From e2875330b3edb08ae6694a1deccc8a66232e0605 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:38:21 +0100 Subject: [PATCH 09/65] Lint all markdown files --- .config/.cspell.json | 2 +- .config/.markdownlint-cli2.jsonc | 2 +- .github/workflows/{lint_readme.yaml => lint_markdown.yaml} | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) rename .github/workflows/{lint_readme.yaml => lint_markdown.yaml} (94%) diff --git a/.config/.cspell.json b/.config/.cspell.json index 03b221b4..ed47c272 100644 --- a/.config/.cspell.json +++ b/.config/.cspell.json @@ -9,7 +9,7 @@ "zwifters" ], "files": [ - "README.md" + "**/*.md" ], "languageSettings": [ { diff --git a/.config/.markdownlint-cli2.jsonc b/.config/.markdownlint-cli2.jsonc index 53881e70..4bfee8d3 100644 --- a/.config/.markdownlint-cli2.jsonc +++ b/.config/.markdownlint-cli2.jsonc @@ -15,6 +15,6 @@ }, "gitignore": true, "globs": [ - "README.md" + "**/*.md" ] } diff --git a/.github/workflows/lint_readme.yaml b/.github/workflows/lint_markdown.yaml similarity index 94% rename from .github/workflows/lint_readme.yaml rename to .github/workflows/lint_markdown.yaml index ff5d045a..e1e811a9 100644 --- a/.github/workflows/lint_readme.yaml +++ b/.github/workflows/lint_markdown.yaml @@ -2,10 +2,10 @@ name: Validate markdown on: pull_request: paths: - - 'README.md' + - '**.md' push: paths: - - 'README.md' + - '**.md' jobs: validate-readme-markdown: runs-on: ubuntu-latest From 331a0971692ef2a4f33578c1f174bcd97c1b4233 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:51:19 +0100 Subject: [PATCH 10/65] Only generates pages when docs changed --- .github/workflows/github_pages.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index 73ac3eb2..4b6ad576 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -2,6 +2,8 @@ name: Build Jekyll site on: push: branches: ["gp-docs"] + paths: + - 'docs/**' workflow_dispatch: permissions: contents: read From 85dddfea46c7355d1040ffbe0379e16c55a77b6e Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:53:00 +0100 Subject: [PATCH 11/65] Rename to netbrain/zwift --- docs/_config.yml | 6 +++--- docs/index.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index e4d0ee76..674a0810 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,14 +1,14 @@ -title: Zwift Container +title: netbrain/zwift description: Easily Zwift on Linux repository: netbrain/zwift permalink: pretty back_to_top: true back_to_top_text: "Back to top" aux_links: - "Zwift Container on GitHub": + "netbrain/zwift on GitHub": - "https://github.com/netbrain/zwift" nav_external_links: - - title: Zwift Container on GitHub + - title: netbrain/zwift on GitHub url: https://github.com/netbrain/zwift remote_theme: just-the-docs/just-the-docs@v0.12.0 plugins: diff --git a/docs/index.md b/docs/index.md index 7aa95e49..04a9bc87 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,6 @@ description: "Easily Zwift on Linux!" permalink: / --- -# Zwift Container +# netbrain/zwift Easily Zwift on Linux! :100: From 2c61ef10af4f86fed31f20168ab99648cb0c3e1e Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:57:35 +0100 Subject: [PATCH 12/65] Fix markdown --- .github/ISSUE_TEMPLATE/bug_report.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d3950433..23f23eb3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -4,24 +4,29 @@ about: Create a report to help us improve title: '' labels: '' assignees: netbrain - --- -**Describe the bug** +## Describe the bug + A clear and concise description of what the bug is. -**To Reproduce** +## To Reproduce + Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' + +1. Go to `...` +2. Click on `...` +3. Scroll down to `...` 4. See error -**Expected behavior** +## Expected behavior + A clear and concise description of what you expected to happen. -**Screenshots** +## Screenshots + If applicable, add screenshots to help explain your problem. -**Additional context** +## Additional context + Add any other context about the problem here. From ce1e68e26f2687a48ce9f9bca858bfd492935364 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 18:58:18 +0100 Subject: [PATCH 13/65] Update globs --- .config/.cspell.json | 2 +- .config/.markdownlint-cli2.jsonc | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.config/.cspell.json b/.config/.cspell.json index ed47c272..0353adae 100644 --- a/.config/.cspell.json +++ b/.config/.cspell.json @@ -9,7 +9,7 @@ "zwifters" ], "files": [ - "**/*.md" + "**.md" ], "languageSettings": [ { diff --git a/.config/.markdownlint-cli2.jsonc b/.config/.markdownlint-cli2.jsonc index 4bfee8d3..d7c5d52b 100644 --- a/.config/.markdownlint-cli2.jsonc +++ b/.config/.markdownlint-cli2.jsonc @@ -10,11 +10,10 @@ "no-duplicate-heading": { "siblings_only": true }, - "no-inline-html": false, - "ignore-front-matter": true + "no-inline-html": false }, "gitignore": true, "globs": [ - "**/*.md" + "**.md" ] } From 5f1d2fd834ec4a986b2430d8361abb228fea72bc Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 19:02:57 +0100 Subject: [PATCH 14/65] Update globs and jobs names --- .config/.cspell.json | 2 +- .config/.markdownlint-cli2.jsonc | 2 +- .github/workflows/lint_markdown.yaml | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.config/.cspell.json b/.config/.cspell.json index 0353adae..ed47c272 100644 --- a/.config/.cspell.json +++ b/.config/.cspell.json @@ -9,7 +9,7 @@ "zwifters" ], "files": [ - "**.md" + "**/*.md" ], "languageSettings": [ { diff --git a/.config/.markdownlint-cli2.jsonc b/.config/.markdownlint-cli2.jsonc index d7c5d52b..b1cc4a19 100644 --- a/.config/.markdownlint-cli2.jsonc +++ b/.config/.markdownlint-cli2.jsonc @@ -14,6 +14,6 @@ }, "gitignore": true, "globs": [ - "**.md" + "**/*.md" ] } diff --git a/.github/workflows/lint_markdown.yaml b/.github/workflows/lint_markdown.yaml index e1e811a9..7b13c07a 100644 --- a/.github/workflows/lint_markdown.yaml +++ b/.github/workflows/lint_markdown.yaml @@ -7,22 +7,22 @@ on: paths: - '**.md' jobs: - validate-readme-markdown: + validate-markdown: runs-on: ubuntu-latest steps: - name: Checkout repository code uses: actions/checkout@v5 - - name: Check README.md file for errors + - name: Check markdown files for errors uses: DavidAnson/markdownlint-cli2-action@v20 with: config: '.config/.markdownlint-cli2.jsonc' globs: "" - spellcheck-readme: + spellcheck-markdown: runs-on: ubuntu-latest steps: - name: Checkout repository code uses: actions/checkout@v5 - - name: Spellcheck README.md + - name: Spellcheck markdown files uses: streetsidesoftware/cspell-action@v7 with: config: '.config/.cspell.json' From c079e3f771ef8dac78d193ad821f4cd354983d68 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 22:36:53 +0100 Subject: [PATCH 15/65] ignore front matter title --- .config/.markdownlint-cli2.jsonc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.config/.markdownlint-cli2.jsonc b/.config/.markdownlint-cli2.jsonc index b1cc4a19..322a487e 100644 --- a/.config/.markdownlint-cli2.jsonc +++ b/.config/.markdownlint-cli2.jsonc @@ -10,7 +10,10 @@ "no-duplicate-heading": { "siblings_only": true }, - "no-inline-html": false + "no-inline-html": false, + "single-title": { + "front_matter_title": "" + } }, "gitignore": true, "globs": [ From 54d41b0717265df3171d533b406b950ad032ce47 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 22:45:00 +0100 Subject: [PATCH 16/65] Move non-essential information from README to docs --- README.md | 437 +------------------------------------------------- docs/index.md | 430 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 434 insertions(+), 433 deletions(-) diff --git a/README.md b/README.md index 2d74a18c..5ffd0276 100644 --- a/README.md +++ b/README.md @@ -24,20 +24,17 @@ time. - [nvidia-container-toolkit](https://github.com/NVIDIA/nvidia-container-toolkit) if you have nvidia proprietary driver - ATI, Intel and Nouveau drivers should work out of the box -> :warning: **Podman Support 4.3 and Later.**: Podman before 4.3 does not support `--userns=keep-id:uid=xxx,gid=xxx` and will - not start correctly, this impacts Ubuntu 22.04 and related builds such as PopOS 22.04. See Podman Section below. - ## Install ```console sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/netbrain/zwift/master/bin/install.sh)" ``` -This will put the `zwift.sh` script on your `$PATH`, add a desktop icon to `/usr/local/share/applications`. +This will put the `zwift.sh` script on your `$PATH` and add a desktop icon to `/usr/local/share/applications`. -NOTE: Icon may not show until logging off and back in. +**NOTE**: Icon may not show until logging off and back in. -## RUN +## Run After installation, simply run: @@ -45,433 +42,7 @@ After installation, simply run: zwift ``` -NOTE: You might want to disable video screenshots ([#75](https://github.com/netbrain/zwift/issues/75)) - -If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or -other programs listening on the bus from inhibiting the screen. - -## Configuration options - -| Key | Default | Description | -|-----------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| `USER` | `$USER` | Used in creating the zwift volume `zwift-$USER` | -| `IMAGE` | `docker.io/netbrain/zwift` | The image to use | -| `VERSION` | `latest` | The image version/tag to use | -| `DONT_CHECK` | | If set, don't check for updated `zwift.sh` | -| `DONT_PULL` | | If set, don't pull for new image version | -| `DRYRUN` | | If set, print the full container run command and exit | -| `INTERACTIVE` | | If set, force `-it` and use `--entrypoint bash` for debugging | -| `CONTAINER_TOOL` | | Defaults to podman if installed, else docker | -| `CONTAINER_EXTRA_ARGS` | | Extra args passed to docker/podman (`--cups=1.5`) | -| `ZWIFT_USERNAME` | | If set, try to login to zwift automatically | -| `ZWIFT_PASSWORD` | | If set, try to login to zwift automatically | -| `ZWIFT_WORKOUT_DIR` | | Set the workouts directory location | -| `ZWIFT_ACTIVITY_DIR` | | Set the activities directory location | -| `ZWIFT_LOG_DIR` | | Set the logs directory location | -| `ZWIFT_SCREENSHOTS_DIR` | | Set the screenshots directory location, recommended to set `ZWIFT_SCREENSHOTS_DIR="$(xdg-user-dir PICTURES)/Zwift"` | -| `ZWIFT_OVERRIDE_GRAPHICS` | | If set, override the default zwift graphics profiles | -| `ZWIFT_OVERRIDE_RESOLUTION` | | If set, change game resolution (2560x1440, 3840x2160, ...) | -| `ZWIFT_FG` | | If set, run the process in fg instead of bg (`-d`) | -| `ZWIFT_NO_GAMEMODE` | | If set, don't run game mode | -| `WINE_EXPERIMENTAL_WAYLAND` | | If set, try to use experimental wayland support in wine 9 | -| `NETWORKING` | `bridge` | Sets the type of container networking to use. | -| `ZWIFT_UID` | current users id | Sets the UID that Zwift will run as (docker only) | -| `ZWIFT_GID` | current users group id | Sets the GID that Zwift will run as (docker only) | -| `DEBUG` | | If set enabled debug of zwift script `set -x` | -| `VGA_DEVICE_FLAG` | | Override GPU/device flags for container (`--gpus=all`) | -| `PRIVILEGED_CONTAINER` | `0` | If set, container will run in privileged mode, SELinux label separation will be disabled (`--privileged --security-opt label=disable`) | - -These environment variables can be used to alter the execution of the zwift bash script. - -Short note on NVIDIA Container Toolkit device flags: - -- Podman: prefer setting `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` (CDI device request). -- Docker: prefer setting `VGA_DEVICE_FLAG="--gpus=all"`. If Docker ≥ 25 is configured with CDI - (`nvidia-ctk runtime configure --enable-cdi`), `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` also works. - -If you're running Docker with CDI and zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` -(instead of `"--gpus=all"`). - -See for context. - -Examples: - -- `DONT_PULL="1" zwift` will prevent docker/podman pull before launch -- `DRYRUN="1" zwift` will print the underlying container run command and exit (no container is started) -- `INTERACTIVE="1" zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the - container -- `CONTAINER_TOOL="docker" zwift` will launch zwift with docker even if podman is installed -- `CONTAINER_EXTRA_ARGS="--cpus=1.5"` will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, - this is useful on laptops to avoid overheating and subsequent throttling of the CPU by the system). -- `USER="Fred" zwift` perfect if your neighbor fred want's to try zwift, and you don't want to mess up your zwift config. -- `NETWORKING="host" zwift` will use host networking which may be needed to have zwift talk to wifi enabled trainers. -- `ZWIFT_UID="123" ZWIFT_GID="123" zwift` will run zwift as the given uid and gid. By default zwift runs with the uid and gid of - the user that started the container. You should not need to change this except in rare cases. NOTE: This does not work in - wayland only X11. -- `WINE_EXPERIMENTAL_WAYLAND="1" zwift` This will start zwift using Wayland and not XWayland. It will start full screen - windowed. - -You can also set these in `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config` to be sourced by the `zwift.sh` -script on execution. - -## How can I persist my login information so i don't need to login on every startup? - -To authenticate through Zwift automatically simply add the following file `$HOME/.config/zwift/config`: - -```bash -ZWIFT_USERNAME='username' -ZWIFT_PASSWORD='password' -``` - -Where `username` is your zwift account email, and `password` your zwift account password, respectively. - -The credentials will be used to authenticate before launching the zwift app, and the user should be logged in automatically in -the game. - -NOTE: This will be loaded by `zwift.sh` in cleartext as environment variables into the container. - -Alternatively, instead of saving your password in the file, you can save your password in the secret service keyring like so: - -```console -secret-tool store --label "Zwift password for ${ZWIFT_USERNAME}" application zwift username ${ZWIFT_USERNAME} -``` - -In this case the username should still be saved in the config file and the password will be read upon startup from the keyring -and passed as a secret into the container (where it is an environment variable). - -> :warning: **You should quote variables!** Use double quotes around values to avoid issues with spaces `VARIABLE="my value"`. -For values that can contain special characters other than spaces, use single quotes instead `VARIABLE='$\nice ${v@lue}'`. This -applies vor `ZWIFT_USERNAME` and `ZWIFT_PASSWORD`. If the value itself contains single quotes `'`, replace them with `'"'"'` -(omit the first or last `'` respectively if the single quote appears as first or last character in the value). - -NOTE: You can also add other environment variable from the table to make starting easier: - -```bash -ZWIFT_USERNAME='username' -ZWIFT_PASSWORD='password' - -ZWIFT_WORKOUT_DIR="$HOME/.config/zwift/workouts" -WINE_EXPERIMENTAL_WAYLAND="1" -``` - -## Podman Support - -When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need -to map the container id 1000 to the host id using `uidmap` and `gidmap`. - -For example if the host uid/gid is 1001/1001 then we need to map the host resources from `/run/user/1001` to the container -resource `/run/user/1000` and map the user and group id's the same. This had to be done manually on the host podman start using -`--uidmap` and `--gidmap` (not covered here). - -From Podman 4.3 this became automatic by providing the Container UID/GID and podman automatically sets up this mapping. - -NOTE: Using ZWIFT_UID/GID will only work if the user starting podman has access to the `/run/user/$ZWIFT_UID` resources and does -not work the same way as in Docker so is not supported. - -## Where are the saves and why do I get a popup can't write to Document Folder? - -This is a hang up from previous versions, mainly with podman. delete the volumes and after re-creation it should work fine. - -```console -podman volume rm zwift-xxxxx -``` - -or - -```console -docker volume rm zwift-xxxxx -``` - -NOTE: if you see a weird volume e.g. `zwift-naeva` it is a hang up from the past, delete it. - -## I sometimes get a popup Not responding why? - -For Gnome it is just timing out before zwift responds, just extend the timeout. - -```console -gsettings set org.gnome.mutter check-alive-timeout 60000 -``` - -## The container is slow to start, why? - -If your `$(id -u)` or `$(id -g)` is not equal to 1000 then this would cause the zwift container to re-map all files (`chown`, -`chgrp`) within the container so there is no uid/gid conflicts. So if speed is a concern of yours, consider changing your user -to match the containers uid and gid using `usermod` or contribute a better solution for handling uid/gid remapping in containers -:smiley: - -## How do I connect my trainer, heart rate monitor, etc? - -You can [use your phone as a bridge](https://support.zwift.com/using-the-zwift-companion-app-Hybn8qzPr). - -For example, your Wahoo Kickr and Apple Watch connect to the Zwift Companion app on your iPhone; then the Companion app connects -over wifi to your PC running Zwift. - -## How can I add custom .zwo files? - -You can map the zwift Workout folder using the environment variable `ZWIFT_WORKOUT_DIR`, for example if your workout directory -is in `$HOME/zwift_workouts` then you would provide the environment variable `ZWIFT_WORKOUT_DIR="$HOME/zwift_workouts"`. - -You can add this variable into `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config`. - -The workouts folder will contain subdirectories e.g. `$HOME/.config/zwift/workouts/393938`. The number is your internal zwift -id and you store you zwo files in the relevant folder. There will usually be only one ID, however if you have multiple zwift -logins it may show one subdirectory for each, to find the ID you can use the following link: - -Webpage for finding internal ID: - -NOTES: - -- Any workouts created already will be copied into this folder on first start -- To add a new workout just copy the zwo file to this directory -- Deleting files from the directory will not delete them, they will be re-added when re-starting zwift, you must delete from the - zwift menu - -## How can I access/modify the graphics settings? - -By default, zwift assigns a graphics profile based on your graphics card. This profile can be either basic, medium, high, or -ultra. This profile determines the level of detail and the quality of the textures you get in game. It is not possible to change -which graphics profile the game uses. When the default options of the profile aren't optimal (for example when zwift doesn't -recognize your graphics card and you only get the medium profile or when your cpu is the bottleneck and your fps is on the low -side because zwift assigned the ultra profile), it is possible to manually tweak the graphics settings by setting -`ZWIFT_OVERRIDE_GRAPHICS="1"`, and editing the settings in the `$HOME/.config/zwift/graphics.txt` or -`$HOME/.config/zwift/$USER-graphics.txt` file as you see fit. To find out which profile zwift assigned, you can upload your -zwift log to . - -The default settings for the different profiles are: - -| key | description | basic | medium | high | ultra | -|----------------------|--------------------------------------------------------|--------------|--------------|--------------|---------------| -| `res` | texture resolution (independent from game resolution) | 1024x576(0x) | 1280x720(0x) | 1280x720(0x) | 1920x1080(0x) | -| `sres` | shadow resolution | 512x512 | 1024x1024 | 1024x1024 | 2048x2048 | -| `gSSAO` | enable high-quality lighting and shadows | 0 | 0 | 1 | 1 | -| `gFXAA` | enable anti-aliasing | 1 | 1 | 1 | 1 | -| `gSunRays` | enable sun rays (default 1) | 0 | 0 | | | -| `gHeadLight` | enable bike headlights (default 1) | 0 | 0 | | | -| `gFoliagePercent` | reduce/increase auto-generated foliage (default 1.0) | 0.5 | 0.5 | | | -| `gSimpleReflections` | lower quality reflections (default 0) | 1 | 1 | | | -| `gLODBias` | lower polygon count (higher value is lower, default 0) | 1 | 1 | | | -| `gShowFPS` | display fps in the top left corner (default 0) | | | | | - -The number in parentheses after the texture resolution (for example `(0x)` after `1920x1080`) is the anti-aliasing setting. This -number can be modified to for example `1920x1080(4x)` or `1920x1080(8x)` to increase anti-aliasing. - -Example `$HOME/.config/zwift/graphics.txt` (settings from the ultra profile, with in-game fps counter enabled): - -```text -res 1920x1080(0x) -sres 2048x2048 -set gSSAO=1 -set gFXAA=1 -set gShowFPS=1 -``` - -Start zwift with the `ZWIFT_OVERRIDE_GRAPHICS="1" zwift` command to use the settings from the graphics.txt file. - -You can find more information about these settings in this [Zwift Insider](https://zwiftinsider.com/config-file-tweaks/) -article. Note that this is an older article and as such some of the information in it is outdated. The default values of the -different profiles have changed to what is in the table listed above and for example the `aniso` setting does not exist anymore. - -> :warning: **Before using ZWIFT_OVERRIDE_GRAPHICS**: This option requires that the `$HOME/.config/zwift/graphics.txt` file -exists. If `graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically the -first time zwift is launched. - -Aside from the graphics profile which is assigned by zwift and cannot be changed, there is also the in-game setting to change -the display resolution. Changing this resolution does not change the graphics profile and as such does not affect the quality of -the textures, shadows, and other graphics options. It only affects the resolution of the game itself. Which resolutions are -available in the zwift in-game setting is dependent on the graphics profile assigned based on your graphics card. If zwift does -not recognize your graphics card or you have a WQHD or UHD display and zwift does not offer the higher resolutions, it is -possible to manually override the game resolution by setting the `ZWIFT_OVERRIDE_RESOLUTION` option. For example to force zwift -to use UHD you can launch it using `ZWIFT_OVERRIDE_RESOLUTION="3840x2160" zwift`. - -The full list of available resolutions is: - -| name | resolution | pixels | -|--------|------------|-----------| -| Low | 576p | 720x576 | -| Medium | 720p | 1280x720 | -| High | 1080p | 1920x1080 | -| Ultra | 1440p | 2560x1440 | -| 4k UHD | 2160p | 3840x2160 | - -> :warning: **Before using ZWIFT_OVERRIDE_RESOLUTION**: This option requires that the `prefs.xml` file exists. Make sure to - launch zwift at least once so it creates the `prefs.xml` file before using the `ZWIFT_OVERRIDE_RESOLUTION` option. - -## How can I build the image myself? - -```console -./bin/build-image.sh -``` - -## How can I fetch the image from docker hub? - - - -```console -docker pull netbrain/zwift:$VERSION # or simply latest -``` - -## How can I update Zwift? - -The `zwift.sh` script will update zwift by checking for new image versions on every launch, however if you are not using this -then you will have to pull `netbrain/zwift:latest` from time to time in order to be on the latest version. - -There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. - -## How can I install this on NixOS? - -To use the NixOS module, configure your flake.nix: - -```nix -{ - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - zwift.url = "github:netbrain/zwift"; - }; - - outputs = { nixpkgs, zwift, ... }: { - nixosConfigurations."«hostname»" = nixpkgs.lib.nixosSystem { - system = "x86_64-linux"; - modules = [ zwift.nixosModules.zwift ./configuration.nix ]; - }; - }; -} -``` - -Then enable and configure the module in your NixOS configuration. The configuration options are written analog to the -environment variables in camelCase: - -```nix -{ - programs.zwift = { - # Enable the zwift module and install required dependencies - enable = true; - # The Docker image to use for zwift - image = "docker.io/netbrain/zwift"; - # The zwift game version to run - version = "1.67.0"; - # Container tool to run zwift (e.g., "podman" or "docker") - containerTool = "podman"; - # If true, do not pull the image (use locally cached image) - dontPull = false; - # If true, skip new version check - dontCheck = false; - # If true, print the container run command and exit - dryRun = false; - # If set, launch container with "-it --entrypoint bash" for debugging - interactive = false; - # Extra args passed to docker/podman (e.g. "--cpus=1.5") - containerExtraArgs = ""; - # Zwift account username (email address) - zwiftUsername = "user@example.com"; - # Zwift account password - zwiftPassword = "xxxx"; - # Directory to store zwift workout files - zwiftWorkoutDir = "/var/lib/zwift/workouts"; - # Directory to store zwift activity files - zwiftActivityDir = "/var/lib/zwift/activities"; - # Directory to store zwift log files - zwiftLogDir = "/var/lib/zwift/logs"; - # Directory to store zwift screenshots - zwiftScreenshotsDir = "/var/lib/zwift/screenshots"; - # Run zwift in the foreground (set true for foreground mode) - zwiftFg = false; - # Disable Linux GameMode if true - zwiftNoGameMode = false; - # Enable Wine's experimental Wayland support if using Wayland - wineExperimentalWayland = false; - # Networking mode for the container ("bridge" is default) - networking = "bridge"; - # User ID for running the container (usually your own UID) - zwiftUid = "1000"; - # Group ID for running the container (usually your own GID) - zwiftGid = "1000"; - # GPU/device flags override (Docker: "--gpus=all", Podman/CDI: "--device=nvidia.com/gpu=all") - vgaDeviceFlag = "--device=nvidia.com/gpu=all"; - # Enable debug output and verbose logging if true - debug = false; - # If set, run container in privileged mode ("--privileged --security-opt label=disable") - privilegedContainer = false; - }; -} -``` - -### Firewall configuration - -You may need to adjust your firewall settings to allow multicast traffic for device (needed to communicate to the -companion app as well as to access the Wahoo trainer and Zwift click devices). - -```nix -networking = { - firewall = { - allowedUDPPorts = [3022 3024]; - allowedTCPPorts = [21587 21588]; - }; -}; -``` - -## Troubleshooting - -
-

My WiFi-capable trainer / Zwift Companion App is not detected

 - -If you have issues with device detection over WiFi/network, the issue may be related to your system's firewall. -Some Linux distributions use `firewalld` instead of `ufw`, -which is more restrictive and blocks multicast traffic by default, -which is essential for discovering devices over WiFi. - -Distributions that use `firewalld` by default include: - -- CentOS 7 and newer -- Fedora 18 and newer -- openSUSE 15 and newer (including Tumbleweed) - -To check if the firewall is the issue, you can temporarily disable `firewalld`: - -```console -systemctl stop firewalld -``` - -If your WiFi trainer / Zwift Companion App is now detected, the firewall is indeed the culprit. -Once you've identified this as the issue, you should configure your firewall -to allow multicast traffic on your network instead of disabling it entirely: - -1. Identify your network/WiFi name. - -2. Assign that network to a specific zone (e.g., "home"): - - (Assuming your distribution uses 'NetworkManager', which almost all do) - - **Via GUI**: On Plasma Settings (or similar), navigate to WiFi → [network name] → General → Firewall Zone, and select "home". - - **Via CLI**: - - ```console - nmcli connection modify "" connection.zone home - ``` - -3. Allow multicast traffic on the zone: - - The zone "home" might already be pre-configured with multicast support. If not, manually allow multicast with: - - ```console - firewall-cmd --permanent --zone=home --add-rich-rule='rule family="ipv4" destination address="224.0.0.0/4" protocol value="udp" accept' - ``` - -4. Restart `firewalld` or reload the configuration for the changes to take effect (shouldn't be needed but just in case): - - **Reload configuration** (recommended, no service interruption): - - ```console - firewall-cmd --reload - ``` - - **Restart the service**: - - ```console - systemctl restart firewalld - ``` - -
+**NOTE**: You might want to disable video screenshots ([#75](https://github.com/netbrain/zwift/issues/75)) ## Sponsors 💖 diff --git a/docs/index.md b/docs/index.md index 04a9bc87..cbb93a78 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,3 +9,433 @@ permalink: / # netbrain/zwift Easily Zwift on Linux! :100: + +> :warning: **Podman Support 4.3 and Later.**: Podman before 4.3 does not support `--userns=keep-id:uid=xxx,gid=xxx` and will + not start correctly, this impacts Ubuntu 22.04 and related builds such as PopOS 22.04. See Podman Section below. + +If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or +other programs listening on the bus from inhibiting the screen. + +## Configuration options + +| Key | Default | Description | +|-----------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| `USER` | `$USER` | Used in creating the zwift volume `zwift-$USER` | +| `IMAGE` | `docker.io/netbrain/zwift` | The image to use | +| `VERSION` | `latest` | The image version/tag to use | +| `DONT_CHECK` | | If set, don't check for updated `zwift.sh` | +| `DONT_PULL` | | If set, don't pull for new image version | +| `DRYRUN` | | If set, print the full container run command and exit | +| `INTERACTIVE` | | If set, force `-it` and use `--entrypoint bash` for debugging | +| `CONTAINER_TOOL` | | Defaults to podman if installed, else docker | +| `CONTAINER_EXTRA_ARGS` | | Extra args passed to docker/podman (`--cups=1.5`) | +| `ZWIFT_USERNAME` | | If set, try to login to zwift automatically | +| `ZWIFT_PASSWORD` | | If set, try to login to zwift automatically | +| `ZWIFT_WORKOUT_DIR` | | Set the workouts directory location | +| `ZWIFT_ACTIVITY_DIR` | | Set the activities directory location | +| `ZWIFT_LOG_DIR` | | Set the logs directory location | +| `ZWIFT_SCREENSHOTS_DIR` | | Set the screenshots directory location, recommended to set `ZWIFT_SCREENSHOTS_DIR=$(xdg-user-dir PICTURES)/Zwift` | +| `ZWIFT_OVERRIDE_GRAPHICS` | | If set, override the default zwift graphics profiles | +| `ZWIFT_OVERRIDE_RESOLUTION` | | If set, change game resolution (2560x1440, 3840x2160, ...) | +| `ZWIFT_FG` | | If set, run the process in fg instead of bg (`-d`) | +| `ZWIFT_NO_GAMEMODE` | | If set, don't run game mode | +| `WINE_EXPERIMENTAL_WAYLAND` | | If set, try to use experimental wayland support in wine 9 | +| `NETWORKING` | `bridge` | Sets the type of container networking to use. | +| `ZWIFT_UID` | current users id | Sets the UID that Zwift will run as (docker only) | +| `ZWIFT_GID` | current users group id | Sets the GID that Zwift will run as (docker only) | +| `DEBUG` | | If set enabled debug of zwift script `set -x` | +| `VGA_DEVICE_FLAG` | | Override GPU/device flags for container (`--gpus=all`) | +| `PRIVILEGED_CONTAINER` | `0` | If set, container will run in privileged mode, SELinux label separation will be disabled (`--privileged --security-opt label=disable`) | + +These environment variables can be used to alter the execution of the zwift bash script. + +Short note on NVIDIA Container Toolkit device flags: + +- Podman: prefer setting `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` (CDI device request). +- Docker: prefer setting `VGA_DEVICE_FLAG="--gpus=all"`. If Docker ≥ 25 is configured with CDI + (`nvidia-ctk runtime configure --enable-cdi`), `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` also works. + +If you're running Docker with CDI and zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` +(instead of `"--gpus=all"`). + +See for context. + +Examples: + +- `DONT_PULL=1 zwift` will prevent docker/podman pull before launch +- `DRYRUN=1 zwift` will print the underlying container run command and exit (no container is started) +- `INTERACTIVE=1 zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the container +- `CONTAINER_TOOL=docker zwift` will launch zwift with docker even if podman is installed +- `CONTAINER_EXTRA_ARGS=--cpus=1.5` will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, + this is useful on laptops to avoid overheating and subsequent throttling of the CPU by the system). +- `USER=Fred zwift` perfect if your neighbor fred want's to try zwift, and you don't want to mess up your zwift config. +- `NETWORKING=host zwift` will use host networking which may be needed to have zwift talk to wifi enabled trainers. +- `ZWIFT_UID=123 ZWIFT_GID=123 zwift` will run zwift as the given uid and gid. By default zwift runs with the uid and gid of + the user that started the container. You should not need to change this except in rare cases. NOTE: This does not work in + wayland only X11. +- `WINE_EXPERIMENTAL_WAYLAND=1 zwift` This will start zwift using Wayland and not XWayland. It will start full screen windowed. + +You can also set these in `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config` to be sourced by the `zwift.sh` +script on execution. + +## How can I persist my login information so i don't need to login on every startup? + +To authenticate through Zwift automatically simply add the following file `$HOME/.config/zwift/config`: + +```text +ZWIFT_USERNAME=username +ZWIFT_PASSWORD=password +``` + +Where `username` is your zwift account email, and `password` your zwift account password, respectively. + +The credentials will be used to authenticate before launching the zwift app, and the user should be logged in automatically in +the game. + +NOTE: This will be loaded by `zwift.sh` in cleartext as environment variables into the container. + +Alternatively, instead of saving your password in the file, you can save your password in the secret service keyring like so: + +```text +secret-tool store --label "Zwift password for ${ZWIFT_USERNAME}" application zwift username ${ZWIFT_USERNAME} +``` + +In this case the username should still be saved in the config file and the password will be read upon startup from the keyring +and passed as a secret into the container (where it is an environment variable). + +> :warning: **Do Not Quote the variables or add spaces**: The ID and Password are read as raw format so if you put + `ZWIFT_PASSWORD="password"` it tries to use `"password"` and not just `password`, same for `''`. In addition do not add a + space to the end of the line it will be sent as part of the password or username. This applies to `ZWIFT_USERNAME` and + `ZWIFT_PASSWORD`. + +NOTE: You can also add other environment variable from the table to make starting easier: + +```text +ZWIFT_USERNAME=username +ZWIFT_PASSWORD=password + +ZWIFT_WORKOUT_DIR=~/.config/zwift/workouts +WINE_EXPERIMENTAL_WAYLAND=1 +``` + +## Podman Support + +When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need +to map the container id 1000 to the host id using `uidmap` and `gidmap`. + +For example if the host uid/gid is 1001/1001 then we need to map the host resources from `/run/user/1001` to the container +resource `/run/user/1000` and map the user and group id's the same. This had to be done manually on the host podman start using +`--uidmap` and `--gidmap` (not covered here). + +From Podman 4.3 this became automatic by providing the Container UID/GID and podman automatically sets up this mapping. + +NOTE: Using ZWIFT_UID/GID will only work if the user starting podman has access to the `/run/user/$ZWIFT_UID` resources and does +not work the same way as in Docker so is not supported. + +## Where are the saves and why do I get a popup can't write to Document Folder? + +This is a hang up from previous versions, mainly with podman. delete the volumes and after re-creation it should work fine. + +```text +podman volume rm zwift-xxxxx +``` + +or + +```text +docker volume rm zwift-xxxxx +``` + +NOTE: if you see a weird volume e.g. `zwift-naeva` it is a hang up from the past, delete it. + +## I sometimes get a popup Not responding why? + +For Gnome it is just timing out before zwift responds, just extend the timeout. + +```text +gsettings set org.gnome.mutter check-alive-timeout 60000 +``` + +## The container is slow to start, why? + +If your `$(id -u)` or `$(id -g)` is not equal to 1000 then this would cause the zwift container to re-map all files (`chown`, +`chgrp`) within the container so there is no uid/gid conflicts. So if speed is a concern of yours, consider changing your user +to match the containers uid and gid using `usermod` or contribute a better solution for handling uid/gid remapping in containers +:smiley: + +## How do I connect my trainer, heart rate monitor, etc? + +You can [use your phone as a bridge](https://support.zwift.com/using-the-zwift-companion-app-Hybn8qzPr). + +For example, your Wahoo Kickr and Apple Watch connect to the Zwift Companion app on your iPhone; then the Companion app connects +over wifi to your PC running Zwift. + +## How can I add custom .zwo files? + +You can map the zwift Workout folder using the environment variable `ZWIFT_WORKOUT_DIR`, for example if your workout directory +is in `$HOME/zwift_workouts` then you would provide the environment variable `ZWIFT_WORKOUT_DIR=$HOME/zwift_workouts`. + +You can add this variable into `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config`. + +The workouts folder will contain subdirectories e.g. `$HOME/.config/zwift/workouts/393938`. The number is your internal zwift +id and you store you zwo files in the relevant folder. There will usually be only one ID, however if you have multiple zwift +logins it may show one subdirectory for each, to find the ID you can use the following link: + +Webpage for finding internal ID: + +NOTES: + +- Any workouts created already will be copied into this folder on first start +- To add a new workout just copy the zwo file to this directory +- Deleting files from the directory will not delete them, they will be re-added when re-starting zwift, you must delete from the + zwift menu + +## How can I access/modify the graphics settings? + +By default, zwift assigns a graphics profile based on your graphics card. This profile can be either basic, medium, high, or +ultra. This profile determines the level of detail and the quality of the textures you get in game. It is not possible to change +which graphics profile the game uses. When the default options of the profile aren't optimal (for example when zwift doesn't +recognize your graphics card and you only get the `medium` profile or when your cpu is the bottleneck and your fps is on the low +side because zwift assigned the ultra profile), it is possible to manually tweak the graphics settings by setting +`ZWIFT_OVERRIDE_GRAPHICS=1`, and editing the settings in the `$HOME/.config/zwift/graphics.txt` or +`$HOME/.config/zwift/$USER-graphics.txt` file as you see fit. To find out which profile zwift assigned, you can upload your +zwift log to . + +The default settings for the different profiles are: + +| key | description | basic | medium | high | ultra | +|----------------------|--------------------------------------------------------|--------------|--------------|--------------|---------------| +| `res` | texture resolution (independent from game resolution) | 1024x576(0x) | 1280x720(0x) | 1280x720(0x) | 1920x1080(0x) | +| `sres` | shadow resolution | 512x512 | 1024x1024 | 1024x1024 | 2048x2048 | +| `gSSAO` | enable high-quality lighting and shadows | 0 | 0 | 1 | 1 | +| `gFXAA` | enable anti-aliasing | 1 | 1 | 1 | 1 | +| `gSunRays` | enable sun rays (default 1) | 0 | 0 | | | +| `gHeadLight` | enable bike headlights (default 1) | 0 | 0 | | | +| `gFoliagePercent` | reduce/increase auto-generated foliage (default 1.0) | 0.5 | 0.5 | | | +| `gSimpleReflections` | lower quality reflections (default 0) | 1 | 1 | | | +| `gLODBias` | lower polygon count (higher value is lower, default 0) | 1 | 1 | | | +| `gShowFPS` | display fps in the top left corner (default 0) | | | | | + +The number in parentheses after the texture resolution (for example `(0x)` after `1920x1080`) is the anti-aliasing setting. This +number can be modified to for example `1920x1080(4x)` or `1920x1080(8x)` to increase anti-aliasing. + +Example `$HOME/.config/zwift/graphics.txt` (settings from the ultra profile, with in-game fps counter enabled): + +```text +res 1920x1080(0x) +sres 2048x2048 +set gSSAO=1 +set gFXAA=1 +set gShowFPS=1 +``` + +Start zwift with the `ZWIFT_OVERRIDE_GRAPHICS=1 zwift` command to use the settings from the graphics.txt file. + +You can find more information about these settings in this [Zwift Insider](https://zwiftinsider.com/config-file-tweaks/) +article. Note that this is an older article and as such some of the information in it is outdated. The default values of the +different profiles have changed to what is in the table listed above and for example the `aniso` setting does not exist anymore. + +> :warning: **Before using ZWIFT_OVERRIDE_GRAPHICS**: This option requires that the `$HOME/.config/zwift/graphics.txt` file +exists. If a `graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically +the first time zwift is launched. + +Aside from the graphics profile which is assigned by zwift and cannot be changed, there is also the in-game setting to change +the display resolution. Changing this resolution does not change the graphics profile and as such does not affect the quality of +the textures, shadows, and other graphics options. It only affects the resolution of the game itself. Which resolutions are +available in the zwift in-game setting is dependent on the graphics profile assigned based on your graphics card. If zwift does +not recognize your graphics card or you have a WQHD or UHD display and zwift does not offer the higher resolutions, it is +possible to manually override the game resolution by setting the `ZWIFT_OVERRIDE_RESOLUTION` option. For example to force zwift +to use UHD you can launch it using `ZWIFT_OVERRIDE_RESOLUTION=3840x2160 zwift`. + +The full list of available resolutions is: + +| name | resolution | pixels | +|--------|------------|-----------| +| Low | 576p | 720x576 | +| Medium | 720p | 1280x720 | +| High | 1080p | 1920x1080 | +| Ultra | 1440p | 2560x1440 | +| 4k UHD | 2160p | 3840x2160 | + +> :warning: **Before using ZWIFT_OVERRIDE_RESOLUTION**: This option requires that the `prefs.xml` file exists. Make sure to + launch zwift at least once so it creates the `prefs.xml` file before using the `ZWIFT_OVERRIDE_RESOLUTION` option. + +## How can I build the image myself? + +```console +./bin/build-image.sh +``` + +## How can I fetch the image from docker hub? + + + +```console +docker pull netbrain/zwift:$VERSION # or simply latest +``` + +## How can I update Zwift? + +The `zwift.sh` script will update zwift by checking for new image versions on every launch, however if you are not using this +then you will have to pull `netbrain/zwift:latest` from time to time in order to be on the latest version. + +There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. + +## How can I install this on NixOS? + +To use the NixOS module, configure your flake.nix: + +```nix +{ + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + zwift.url = "github:netbrain/zwift"; + }; + + outputs = { nixpkgs, zwift, ... }: { + nixosConfigurations."«hostname»" = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; + modules = [ zwift.nixosModules.zwift ./configuration.nix ]; + }; + }; +} +``` + +Then enable and configure the module in your NixOS configuration. The configuration options are written analog to the +environment variables in camelCase: + +```nix +{ + programs.zwift = { + # Enable the zwift module and install required dependencies + enable = true; + # The Docker image to use for zwift + image = "docker.io/netbrain/zwift"; + # The zwift game version to run + version = "1.67.0"; + # Container tool to run zwift (e.g., "podman" or "docker") + containerTool = "podman"; + # If true, do not pull the image (use locally cached image) + dontPull = false; + # If true, skip new version check + dontCheck = false; + # If true, print the container run command and exit + dryRun = false; + # If set, launch container with "-it --entrypoint bash" for debugging + interactive = false; + # Extra args passed to docker/podman (e.g. "--cpus=1.5") + containerExtraArgs = ""; + # Zwift account username (email address) + zwiftUsername = "user@example.com"; + # Zwift account password + zwiftPassword = "xxxx"; + # Directory to store zwift workout files + zwiftWorkoutDir = "/var/lib/zwift/workouts"; + # Directory to store zwift activity files + zwiftActivityDir = "/var/lib/zwift/activities"; + # Directory to store zwift log files + zwiftLogDir = "/var/lib/zwift/logs"; + # Directory to store zwift screenshots + zwiftScreenshotsDir = "/var/lib/zwift/screenshots"; + # Run zwift in the foreground (set true for foreground mode) + zwiftFg = false; + # Disable Linux GameMode if true + zwiftNoGameMode = false; + # Enable Wine's experimental Wayland support if using Wayland + wineExperimentalWayland = false; + # Networking mode for the container ("bridge" is default) + networking = "bridge"; + # User ID for running the container (usually your own UID) + zwiftUid = "1000"; + # Group ID for running the container (usually your own GID) + zwiftGid = "1000"; + # GPU/device flags override (Docker: "--gpus=all", Podman/CDI: "--device=nvidia.com/gpu=all") + vgaDeviceFlag = "--device=nvidia.com/gpu=all"; + # Enable debug output and verbose logging if true + debug = false; + # If set, run container in privileged mode ("--privileged --security-opt label=disable") + privilegedContainer = false; + }; +} +``` + +### Firewall configuration + +You may need to adjust your firewall settings to allow multicast traffic for device (needed to communicate to the +companion app as well as to access the Wahoo trainer and Zwift click devices). + +```nix +networking = { + firewall = { + allowedUDPPorts = [ + 3022 + 3024 + ]; + allowedTCPPorts = [21587 21588]; + }; +}; +``` + +## Troubleshooting + +
+

My WiFi-capable trainer / Zwift Companion App is not detected

 + +If you have issues with device detection over WiFi/network, the issue may be related to your system's firewall. +Some Linux distributions use `firewalld` instead of `ufw`, +which is more restrictive and blocks multicast traffic by default, +which is essential for discovering devices over WiFi. + +Distributions that use `firewalld` by default include: + +- CentOS 7 and newer +- Fedora 18 and newer +- openSUSE 15 and newer (including Tumbleweed) + +To check if the firewall is the issue, you can temporarily disable `firewalld`: + +```console +systemctl stop firewalld +``` + +If your WiFi trainer / Zwift Companion App is now detected, the firewall is indeed the culprit. +Once you've identified this as the issue, you should configure your firewall +to allow multicast traffic on your network instead of disabling it entirely: + +1. Identify your network/WiFi name. + +2. Assign that network to a specific zone (e.g., "home"): + + (Assuming your distribution uses 'NetworkManager', which almost all do) + + **Via GUI**: On Plasma Settings (or similar), navigate to WiFi → [network name] → General → Firewall Zone, and select "home". + + **Via CLI**: + + ```console + nmcli connection modify "" connection.zone home + ``` + +3. Allow multicast traffic on the zone: + + The zone "home" might already be pre-configured with multicast support. If not, manually allow multicast with: + + ```console + firewall-cmd --permanent --zone=home --add-rich-rule='rule family="ipv4" destination address="224.0.0.0/4" protocol value="udp" accept' + ``` + +4. Restart `firewalld` or reload the configuration for the changes to take effect (shouldn't be needed but just in case): + + **Reload configuration** (recommended, no service interruption): + + ```console + firewall-cmd --reload + ``` + + **Restart the service**: + + ```console + systemctl restart firewalld + ``` + +
From 2fc1018ed670bd626c4af5dc4f704648d75d244d Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 22:47:35 +0100 Subject: [PATCH 17/65] Add getting started title --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5ffd0276..91f51a5b 100644 --- a/README.md +++ b/README.md @@ -16,15 +16,17 @@ If you find this image useful, then feel free to [add me on zwift](https://www.zwift.com/eu/athlete/4e3c5880-1edd-4c5d-a1b8-0974ce3874f0) and give me a ride on from time to time. +## Getting started + ![example.gif](https://raw.githubusercontent.com/netbrain/zwift/master/example.gif) -## Prerequisites +### Prerequisites - [Docker](https://docs.docker.com/get-docker) or [Podman](https://podman.io/getting-started/installation) - [nvidia-container-toolkit](https://github.com/NVIDIA/nvidia-container-toolkit) if you have nvidia proprietary driver - ATI, Intel and Nouveau drivers should work out of the box -## Install +### Install ```console sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/netbrain/zwift/master/bin/install.sh)" @@ -34,7 +36,7 @@ This will put the `zwift.sh` script on your `$PATH` and add a desktop icon to `/ **NOTE**: Icon may not show until logging off and back in. -## Run +### Run After installation, simply run: From ef372cae6298ce8a335eedc67e7bfe0fdb4e71f6 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 22:53:16 +0100 Subject: [PATCH 18/65] Move NixOS documentation to separate file --- docs/index.md | 95 ----------------------------------------------- docs/nixos.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 95 deletions(-) create mode 100644 docs/nixos.md diff --git a/docs/index.md b/docs/index.md index cbb93a78..dcc0de42 100644 --- a/docs/index.md +++ b/docs/index.md @@ -281,101 +281,6 @@ then you will have to pull `netbrain/zwift:latest` from time to time in order to There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. -## How can I install this on NixOS? - -To use the NixOS module, configure your flake.nix: - -```nix -{ - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - zwift.url = "github:netbrain/zwift"; - }; - - outputs = { nixpkgs, zwift, ... }: { - nixosConfigurations."«hostname»" = nixpkgs.lib.nixosSystem { - system = "x86_64-linux"; - modules = [ zwift.nixosModules.zwift ./configuration.nix ]; - }; - }; -} -``` - -Then enable and configure the module in your NixOS configuration. The configuration options are written analog to the -environment variables in camelCase: - -```nix -{ - programs.zwift = { - # Enable the zwift module and install required dependencies - enable = true; - # The Docker image to use for zwift - image = "docker.io/netbrain/zwift"; - # The zwift game version to run - version = "1.67.0"; - # Container tool to run zwift (e.g., "podman" or "docker") - containerTool = "podman"; - # If true, do not pull the image (use locally cached image) - dontPull = false; - # If true, skip new version check - dontCheck = false; - # If true, print the container run command and exit - dryRun = false; - # If set, launch container with "-it --entrypoint bash" for debugging - interactive = false; - # Extra args passed to docker/podman (e.g. "--cpus=1.5") - containerExtraArgs = ""; - # Zwift account username (email address) - zwiftUsername = "user@example.com"; - # Zwift account password - zwiftPassword = "xxxx"; - # Directory to store zwift workout files - zwiftWorkoutDir = "/var/lib/zwift/workouts"; - # Directory to store zwift activity files - zwiftActivityDir = "/var/lib/zwift/activities"; - # Directory to store zwift log files - zwiftLogDir = "/var/lib/zwift/logs"; - # Directory to store zwift screenshots - zwiftScreenshotsDir = "/var/lib/zwift/screenshots"; - # Run zwift in the foreground (set true for foreground mode) - zwiftFg = false; - # Disable Linux GameMode if true - zwiftNoGameMode = false; - # Enable Wine's experimental Wayland support if using Wayland - wineExperimentalWayland = false; - # Networking mode for the container ("bridge" is default) - networking = "bridge"; - # User ID for running the container (usually your own UID) - zwiftUid = "1000"; - # Group ID for running the container (usually your own GID) - zwiftGid = "1000"; - # GPU/device flags override (Docker: "--gpus=all", Podman/CDI: "--device=nvidia.com/gpu=all") - vgaDeviceFlag = "--device=nvidia.com/gpu=all"; - # Enable debug output and verbose logging if true - debug = false; - # If set, run container in privileged mode ("--privileged --security-opt label=disable") - privilegedContainer = false; - }; -} -``` - -### Firewall configuration - -You may need to adjust your firewall settings to allow multicast traffic for device (needed to communicate to the -companion app as well as to access the Wahoo trainer and Zwift click devices). - -```nix -networking = { - firewall = { - allowedUDPPorts = [ - 3022 - 3024 - ]; - allowedTCPPorts = [21587 21588]; - }; -}; -``` - ## Troubleshooting
diff --git a/docs/nixos.md b/docs/nixos.md new file mode 100644 index 00000000..a7b19180 --- /dev/null +++ b/docs/nixos.md @@ -0,0 +1,100 @@ +--- +title: NixOS +nav_order: 2 +--- + +# NixOS + +## Installation + +To use the NixOS module, configure your flake.nix: + +```nix +{ + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + zwift.url = "github:netbrain/zwift"; + }; + + outputs = { nixpkgs, zwift, ... }: { + nixosConfigurations."«hostname»" = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; + modules = [ zwift.nixosModules.zwift ./configuration.nix ]; + }; + }; +} +``` + +## Configuration + +Then enable and configure the module in your NixOS configuration. The configuration options are written analog to the +environment variables in camelCase: + +```nix +{ + programs.zwift = { + # Enable the zwift module and install required dependencies + enable = true; + # The Docker image to use for zwift + image = "docker.io/netbrain/zwift"; + # The zwift game version to run + version = "1.67.0"; + # Container tool to run zwift (e.g., "podman" or "docker") + containerTool = "podman"; + # If true, do not pull the image (use locally cached image) + dontPull = false; + # If true, skip new version check + dontCheck = false; + # If true, print the container run command and exit + dryRun = false; + # If set, launch container with "-it --entrypoint bash" for debugging + interactive = false; + # Extra args passed to docker/podman (e.g. "--cpus=1.5") + containerExtraArgs = ""; + # Zwift account username (email address) + zwiftUsername = "user@example.com"; + # Zwift account password + zwiftPassword = "xxxx"; + # Directory to store zwift workout files + zwiftWorkoutDir = "/var/lib/zwift/workouts"; + # Directory to store zwift activity files + zwiftActivityDir = "/var/lib/zwift/activities"; + # Directory to store zwift log files + zwiftLogDir = "/var/lib/zwift/logs"; + # Directory to store zwift screenshots + zwiftScreenshotsDir = "/var/lib/zwift/screenshots"; + # Run zwift in the foreground (set true for foreground mode) + zwiftFg = false; + # Disable Linux GameMode if true + zwiftNoGameMode = false; + # Enable Wine's experimental Wayland support if using Wayland + wineExperimentalWayland = false; + # Networking mode for the container ("bridge" is default) + networking = "bridge"; + # User ID for running the container (usually your own UID) + zwiftUid = "1000"; + # Group ID for running the container (usually your own GID) + zwiftGid = "1000"; + # GPU/device flags override (Docker: "--gpus=all", Podman/CDI: "--device=nvidia.com/gpu=all") + vgaDeviceFlag = "--device=nvidia.com/gpu=all"; + # Enable debug output and verbose logging if true + debug = false; + # If set, run container in privileged mode ("--privileged --security-opt label=disable") + privilegedContainer = false; + }; +} +``` + +## Firewall + +You may need to adjust your firewall settings to allow multicast traffic for device (needed to communicate to the +companion app as well as to access the Wahoo trainer and Zwift click devices). + +```nix +networking = { + firewall = { + allowedUDPPorts = [3022 3024]; + allowedTCPPorts = [21587 21588]; + }; +}; +``` From f62b8c036f08c6b5106672e213821fdab3a09770 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 22:55:36 +0100 Subject: [PATCH 19/65] Move graphics configuration documentation to separate file --- docs/graphics.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 70 -------------------------------------------- docs/nixos.md | 2 +- 3 files changed, 77 insertions(+), 71 deletions(-) create mode 100644 docs/graphics.md diff --git a/docs/graphics.md b/docs/graphics.md new file mode 100644 index 00000000..fc85527b --- /dev/null +++ b/docs/graphics.md @@ -0,0 +1,76 @@ +--- +title: Customize Zwift graphics +nav_order: 2 +--- + +# Customize Zwift graphics + +## How can I access/modify the graphics settings? + +By default, zwift assigns a graphics profile based on your graphics card. This profile can be either basic, medium, high, or +ultra. This profile determines the level of detail and the quality of the textures you get in game. It is not possible to change +which graphics profile the game uses. When the default options of the profile aren't optimal (for example when zwift doesn't +recognize your graphics card and you only get the `medium` profile or when your cpu is the bottleneck and your fps is on the low +side because zwift assigned the ultra profile), it is possible to manually tweak the graphics settings by setting +`ZWIFT_OVERRIDE_GRAPHICS=1`, and editing the settings in the `$HOME/.config/zwift/graphics.txt` or +`$HOME/.config/zwift/$USER-graphics.txt` file as you see fit. To find out which profile zwift assigned, you can upload your +zwift log to . + +The default settings for the different profiles are: + +| key | description | basic | medium | high | ultra | +|----------------------|--------------------------------------------------------|--------------|--------------|--------------|---------------| +| `res` | texture resolution (independent from game resolution) | 1024x576(0x) | 1280x720(0x) | 1280x720(0x) | 1920x1080(0x) | +| `sres` | shadow resolution | 512x512 | 1024x1024 | 1024x1024 | 2048x2048 | +| `gSSAO` | enable high-quality lighting and shadows | 0 | 0 | 1 | 1 | +| `gFXAA` | enable anti-aliasing | 1 | 1 | 1 | 1 | +| `gSunRays` | enable sun rays (default 1) | 0 | 0 | | | +| `gHeadLight` | enable bike headlights (default 1) | 0 | 0 | | | +| `gFoliagePercent` | reduce/increase auto-generated foliage (default 1.0) | 0.5 | 0.5 | | | +| `gSimpleReflections` | lower quality reflections (default 0) | 1 | 1 | | | +| `gLODBias` | lower polygon count (higher value is lower, default 0) | 1 | 1 | | | +| `gShowFPS` | display fps in the top left corner (default 0) | | | | | + +The number in parentheses after the texture resolution (for example `(0x)` after `1920x1080`) is the anti-aliasing setting. This +number can be modified to for example `1920x1080(4x)` or `1920x1080(8x)` to increase anti-aliasing. + +Example `$HOME/.config/zwift/graphics.txt` (settings from the ultra profile, with in-game fps counter enabled): + +```text +res 1920x1080(0x) +sres 2048x2048 +set gSSAO=1 +set gFXAA=1 +set gShowFPS=1 +``` + +Start zwift with the `ZWIFT_OVERRIDE_GRAPHICS=1 zwift` command to use the settings from the graphics.txt file. + +You can find more information about these settings in this [Zwift Insider](https://zwiftinsider.com/config-file-tweaks/) +article. Note that this is an older article and as such some of the information in it is outdated. The default values of the +different profiles have changed to what is in the table listed above and for example the `aniso` setting does not exist anymore. + +> :warning: **Before using ZWIFT_OVERRIDE_GRAPHICS**: This option requires that the `$HOME/.config/zwift/graphics.txt` file +exists. If a `graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically +the first time zwift is launched. + +Aside from the graphics profile which is assigned by zwift and cannot be changed, there is also the in-game setting to change +the display resolution. Changing this resolution does not change the graphics profile and as such does not affect the quality of +the textures, shadows, and other graphics options. It only affects the resolution of the game itself. Which resolutions are +available in the zwift in-game setting is dependent on the graphics profile assigned based on your graphics card. If zwift does +not recognize your graphics card or you have a WQHD or UHD display and zwift does not offer the higher resolutions, it is +possible to manually override the game resolution by setting the `ZWIFT_OVERRIDE_RESOLUTION` option. For example to force zwift +to use UHD you can launch it using `ZWIFT_OVERRIDE_RESOLUTION=3840x2160 zwift`. + +The full list of available resolutions is: + +| name | resolution | pixels | +|--------|------------|-----------| +| Low | 576p | 720x576 | +| Medium | 720p | 1280x720 | +| High | 1080p | 1920x1080 | +| Ultra | 1440p | 2560x1440 | +| 4k UHD | 2160p | 3840x2160 | + +> :warning: **Before using ZWIFT_OVERRIDE_RESOLUTION**: This option requires that the `prefs.xml` file exists. Make sure to + launch zwift at least once so it creates the `prefs.xml` file before using the `ZWIFT_OVERRIDE_RESOLUTION` option. diff --git a/docs/index.md b/docs/index.md index dcc0de42..77b1261f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -190,76 +190,6 @@ NOTES: - Deleting files from the directory will not delete them, they will be re-added when re-starting zwift, you must delete from the zwift menu -## How can I access/modify the graphics settings? - -By default, zwift assigns a graphics profile based on your graphics card. This profile can be either basic, medium, high, or -ultra. This profile determines the level of detail and the quality of the textures you get in game. It is not possible to change -which graphics profile the game uses. When the default options of the profile aren't optimal (for example when zwift doesn't -recognize your graphics card and you only get the `medium` profile or when your cpu is the bottleneck and your fps is on the low -side because zwift assigned the ultra profile), it is possible to manually tweak the graphics settings by setting -`ZWIFT_OVERRIDE_GRAPHICS=1`, and editing the settings in the `$HOME/.config/zwift/graphics.txt` or -`$HOME/.config/zwift/$USER-graphics.txt` file as you see fit. To find out which profile zwift assigned, you can upload your -zwift log to . - -The default settings for the different profiles are: - -| key | description | basic | medium | high | ultra | -|----------------------|--------------------------------------------------------|--------------|--------------|--------------|---------------| -| `res` | texture resolution (independent from game resolution) | 1024x576(0x) | 1280x720(0x) | 1280x720(0x) | 1920x1080(0x) | -| `sres` | shadow resolution | 512x512 | 1024x1024 | 1024x1024 | 2048x2048 | -| `gSSAO` | enable high-quality lighting and shadows | 0 | 0 | 1 | 1 | -| `gFXAA` | enable anti-aliasing | 1 | 1 | 1 | 1 | -| `gSunRays` | enable sun rays (default 1) | 0 | 0 | | | -| `gHeadLight` | enable bike headlights (default 1) | 0 | 0 | | | -| `gFoliagePercent` | reduce/increase auto-generated foliage (default 1.0) | 0.5 | 0.5 | | | -| `gSimpleReflections` | lower quality reflections (default 0) | 1 | 1 | | | -| `gLODBias` | lower polygon count (higher value is lower, default 0) | 1 | 1 | | | -| `gShowFPS` | display fps in the top left corner (default 0) | | | | | - -The number in parentheses after the texture resolution (for example `(0x)` after `1920x1080`) is the anti-aliasing setting. This -number can be modified to for example `1920x1080(4x)` or `1920x1080(8x)` to increase anti-aliasing. - -Example `$HOME/.config/zwift/graphics.txt` (settings from the ultra profile, with in-game fps counter enabled): - -```text -res 1920x1080(0x) -sres 2048x2048 -set gSSAO=1 -set gFXAA=1 -set gShowFPS=1 -``` - -Start zwift with the `ZWIFT_OVERRIDE_GRAPHICS=1 zwift` command to use the settings from the graphics.txt file. - -You can find more information about these settings in this [Zwift Insider](https://zwiftinsider.com/config-file-tweaks/) -article. Note that this is an older article and as such some of the information in it is outdated. The default values of the -different profiles have changed to what is in the table listed above and for example the `aniso` setting does not exist anymore. - -> :warning: **Before using ZWIFT_OVERRIDE_GRAPHICS**: This option requires that the `$HOME/.config/zwift/graphics.txt` file -exists. If a `graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically -the first time zwift is launched. - -Aside from the graphics profile which is assigned by zwift and cannot be changed, there is also the in-game setting to change -the display resolution. Changing this resolution does not change the graphics profile and as such does not affect the quality of -the textures, shadows, and other graphics options. It only affects the resolution of the game itself. Which resolutions are -available in the zwift in-game setting is dependent on the graphics profile assigned based on your graphics card. If zwift does -not recognize your graphics card or you have a WQHD or UHD display and zwift does not offer the higher resolutions, it is -possible to manually override the game resolution by setting the `ZWIFT_OVERRIDE_RESOLUTION` option. For example to force zwift -to use UHD you can launch it using `ZWIFT_OVERRIDE_RESOLUTION=3840x2160 zwift`. - -The full list of available resolutions is: - -| name | resolution | pixels | -|--------|------------|-----------| -| Low | 576p | 720x576 | -| Medium | 720p | 1280x720 | -| High | 1080p | 1920x1080 | -| Ultra | 1440p | 2560x1440 | -| 4k UHD | 2160p | 3840x2160 | - -> :warning: **Before using ZWIFT_OVERRIDE_RESOLUTION**: This option requires that the `prefs.xml` file exists. Make sure to - launch zwift at least once so it creates the `prefs.xml` file before using the `ZWIFT_OVERRIDE_RESOLUTION` option. - ## How can I build the image myself? ```console diff --git a/docs/nixos.md b/docs/nixos.md index a7b19180..b9222e12 100644 --- a/docs/nixos.md +++ b/docs/nixos.md @@ -1,6 +1,6 @@ --- title: NixOS -nav_order: 2 +nav_order: 3 --- # NixOS From 0a68c466860d5c9f5b028e7f06e3ac34d2aa036f Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 22:57:06 +0100 Subject: [PATCH 20/65] Move troubleshooting section to separate file --- docs/index.md | 64 -------------------------------------- docs/troubleshooting.md | 68 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 64 deletions(-) create mode 100644 docs/troubleshooting.md diff --git a/docs/index.md b/docs/index.md index 77b1261f..38aab026 100644 --- a/docs/index.md +++ b/docs/index.md @@ -210,67 +210,3 @@ The `zwift.sh` script will update zwift by checking for new image versions on ev then you will have to pull `netbrain/zwift:latest` from time to time in order to be on the latest version. There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. - -## Troubleshooting - -
-

My WiFi-capable trainer / Zwift Companion App is not detected

 - -If you have issues with device detection over WiFi/network, the issue may be related to your system's firewall. -Some Linux distributions use `firewalld` instead of `ufw`, -which is more restrictive and blocks multicast traffic by default, -which is essential for discovering devices over WiFi. - -Distributions that use `firewalld` by default include: - -- CentOS 7 and newer -- Fedora 18 and newer -- openSUSE 15 and newer (including Tumbleweed) - -To check if the firewall is the issue, you can temporarily disable `firewalld`: - -```console -systemctl stop firewalld -``` - -If your WiFi trainer / Zwift Companion App is now detected, the firewall is indeed the culprit. -Once you've identified this as the issue, you should configure your firewall -to allow multicast traffic on your network instead of disabling it entirely: - -1. Identify your network/WiFi name. - -2. Assign that network to a specific zone (e.g., "home"): - - (Assuming your distribution uses 'NetworkManager', which almost all do) - - **Via GUI**: On Plasma Settings (or similar), navigate to WiFi → [network name] → General → Firewall Zone, and select "home". - - **Via CLI**: - - ```console - nmcli connection modify "" connection.zone home - ``` - -3. Allow multicast traffic on the zone: - - The zone "home" might already be pre-configured with multicast support. If not, manually allow multicast with: - - ```console - firewall-cmd --permanent --zone=home --add-rich-rule='rule family="ipv4" destination address="224.0.0.0/4" protocol value="udp" accept' - ``` - -4. Restart `firewalld` or reload the configuration for the changes to take effect (shouldn't be needed but just in case): - - **Reload configuration** (recommended, no service interruption): - - ```console - firewall-cmd --reload - ``` - - **Restart the service**: - - ```console - systemctl restart firewalld - ``` - -
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..8233a10b --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,68 @@ +--- +title: Troubleshooting +nav_order: 3 +--- + +# Troubleshooting + +
+

My WiFi-capable trainer / Zwift Companion App is not detected

 + +If you have issues with device detection over WiFi/network, the issue may be related to your system's firewall. +Some Linux distributions use `firewalld` instead of `ufw`, +which is more restrictive and blocks multicast traffic by default, +which is essential for discovering devices over WiFi. + +Distributions that use `firewalld` by default include: + +- CentOS 7 and newer +- Fedora 18 and newer +- openSUSE 15 and newer (including Tumbleweed) + +To check if the firewall is the issue, you can temporarily disable `firewalld`: + +```console +systemctl stop firewalld +``` + +If your WiFi trainer / Zwift Companion App is now detected, the firewall is indeed the culprit. +Once you've identified this as the issue, you should configure your firewall +to allow multicast traffic on your network instead of disabling it entirely: + +1. Identify your network/WiFi name. + +2. Assign that network to a specific zone (e.g., "home"): + + (Assuming your distribution uses 'NetworkManager', which almost all do) + + **Via GUI**: On Plasma Settings (or similar), navigate to WiFi → [network name] → General → Firewall Zone, and select "home". + + **Via CLI**: + + ```console + nmcli connection modify "" connection.zone home + ``` + +3. Allow multicast traffic on the zone: + + The zone "home" might already be pre-configured with multicast support. If not, manually allow multicast with: + + ```console + firewall-cmd --permanent --zone=home --add-rich-rule='rule family="ipv4" destination address="224.0.0.0/4" protocol value="udp" accept' + ``` + +4. Restart `firewalld` or reload the configuration for the changes to take effect (shouldn't be needed but just in case): + + **Reload configuration** (recommended, no service interruption): + + ```console + firewall-cmd --reload + ``` + + **Restart the service**: + + ```console + systemctl restart firewalld + ``` + +
From 17c6191d34a05bc37a6c00045316a5aaaaa5443b Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 22:59:24 +0100 Subject: [PATCH 21/65] Move more items to troubleshooting --- docs/index.md | 31 ------------------------------- docs/troubleshooting.md | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 31 deletions(-) diff --git a/docs/index.md b/docs/index.md index 38aab026..b0ed1841 100644 --- a/docs/index.md +++ b/docs/index.md @@ -132,37 +132,6 @@ From Podman 4.3 this became automatic by providing the Container UID/GID and pod NOTE: Using ZWIFT_UID/GID will only work if the user starting podman has access to the `/run/user/$ZWIFT_UID` resources and does not work the same way as in Docker so is not supported. -## Where are the saves and why do I get a popup can't write to Document Folder? - -This is a hang up from previous versions, mainly with podman. delete the volumes and after re-creation it should work fine. - -```text -podman volume rm zwift-xxxxx -``` - -or - -```text -docker volume rm zwift-xxxxx -``` - -NOTE: if you see a weird volume e.g. `zwift-naeva` it is a hang up from the past, delete it. - -## I sometimes get a popup Not responding why? - -For Gnome it is just timing out before zwift responds, just extend the timeout. - -```text -gsettings set org.gnome.mutter check-alive-timeout 60000 -``` - -## The container is slow to start, why? - -If your `$(id -u)` or `$(id -g)` is not equal to 1000 then this would cause the zwift container to re-map all files (`chown`, -`chgrp`) within the container so there is no uid/gid conflicts. So if speed is a concern of yours, consider changing your user -to match the containers uid and gid using `usermod` or contribute a better solution for handling uid/gid remapping in containers -:smiley: - ## How do I connect my trainer, heart rate monitor, etc? You can [use your phone as a bridge](https://support.zwift.com/using-the-zwift-companion-app-Hybn8qzPr). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 8233a10b..a648de17 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -66,3 +66,43 @@ to allow multicast traffic on your network instead of disabling it entirely: ```
+ +
+

Where are the saves and why do I get a popup can't write to Document Folder?

 + +This is a hang up from previous versions, mainly with podman. delete the volumes and after re-creation it should work fine. + +```text +podman volume rm zwift-xxxxx +``` + +or + +```text +docker volume rm zwift-xxxxx +``` + +**NOTE**: if you see a weird volume e.g. `zwift-naeva` it is a hang up from the past, delete it. + +
+ +
+

I sometimes get a popup Not responding why?

 + +For Gnome it is just timing out before zwift responds, just extend the timeout. + +```text +gsettings set org.gnome.mutter check-alive-timeout 60000 +``` + +
+ +
+

The container is slow to start, why?

 + +If your `$(id -u)` or `$(id -g)` is not equal to 1000 then this would cause the zwift container to re-map all files (`chown`, +`chgrp`) within the container so there is no uid/gid conflicts. So if speed is a concern of yours, consider changing your user +to match the containers uid and gid using `usermod` or contribute a better solution for handling uid/gid remapping in containers +:smiley: + +
From 56413ad9a001214bb940ec9fe06ff37c25aa383e Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 23:01:49 +0100 Subject: [PATCH 22/65] Move configuration options documentation to separate file --- docs/graphics.md | 2 +- docs/index.md | 62 -------------------------------------- docs/nixos.md | 2 +- docs/options.md | 66 +++++++++++++++++++++++++++++++++++++++++ docs/troubleshooting.md | 2 +- 5 files changed, 69 insertions(+), 65 deletions(-) create mode 100644 docs/options.md diff --git a/docs/graphics.md b/docs/graphics.md index fc85527b..58f6dbe6 100644 --- a/docs/graphics.md +++ b/docs/graphics.md @@ -1,6 +1,6 @@ --- title: Customize Zwift graphics -nav_order: 2 +nav_order: 3 --- # Customize Zwift graphics diff --git a/docs/index.md b/docs/index.md index b0ed1841..4f90696f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,68 +16,6 @@ Easily Zwift on Linux! :100: If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or other programs listening on the bus from inhibiting the screen. -## Configuration options - -| Key | Default | Description | -|-----------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| `USER` | `$USER` | Used in creating the zwift volume `zwift-$USER` | -| `IMAGE` | `docker.io/netbrain/zwift` | The image to use | -| `VERSION` | `latest` | The image version/tag to use | -| `DONT_CHECK` | | If set, don't check for updated `zwift.sh` | -| `DONT_PULL` | | If set, don't pull for new image version | -| `DRYRUN` | | If set, print the full container run command and exit | -| `INTERACTIVE` | | If set, force `-it` and use `--entrypoint bash` for debugging | -| `CONTAINER_TOOL` | | Defaults to podman if installed, else docker | -| `CONTAINER_EXTRA_ARGS` | | Extra args passed to docker/podman (`--cups=1.5`) | -| `ZWIFT_USERNAME` | | If set, try to login to zwift automatically | -| `ZWIFT_PASSWORD` | | If set, try to login to zwift automatically | -| `ZWIFT_WORKOUT_DIR` | | Set the workouts directory location | -| `ZWIFT_ACTIVITY_DIR` | | Set the activities directory location | -| `ZWIFT_LOG_DIR` | | Set the logs directory location | -| `ZWIFT_SCREENSHOTS_DIR` | | Set the screenshots directory location, recommended to set `ZWIFT_SCREENSHOTS_DIR=$(xdg-user-dir PICTURES)/Zwift` | -| `ZWIFT_OVERRIDE_GRAPHICS` | | If set, override the default zwift graphics profiles | -| `ZWIFT_OVERRIDE_RESOLUTION` | | If set, change game resolution (2560x1440, 3840x2160, ...) | -| `ZWIFT_FG` | | If set, run the process in fg instead of bg (`-d`) | -| `ZWIFT_NO_GAMEMODE` | | If set, don't run game mode | -| `WINE_EXPERIMENTAL_WAYLAND` | | If set, try to use experimental wayland support in wine 9 | -| `NETWORKING` | `bridge` | Sets the type of container networking to use. | -| `ZWIFT_UID` | current users id | Sets the UID that Zwift will run as (docker only) | -| `ZWIFT_GID` | current users group id | Sets the GID that Zwift will run as (docker only) | -| `DEBUG` | | If set enabled debug of zwift script `set -x` | -| `VGA_DEVICE_FLAG` | | Override GPU/device flags for container (`--gpus=all`) | -| `PRIVILEGED_CONTAINER` | `0` | If set, container will run in privileged mode, SELinux label separation will be disabled (`--privileged --security-opt label=disable`) | - -These environment variables can be used to alter the execution of the zwift bash script. - -Short note on NVIDIA Container Toolkit device flags: - -- Podman: prefer setting `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` (CDI device request). -- Docker: prefer setting `VGA_DEVICE_FLAG="--gpus=all"`. If Docker ≥ 25 is configured with CDI - (`nvidia-ctk runtime configure --enable-cdi`), `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` also works. - -If you're running Docker with CDI and zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` -(instead of `"--gpus=all"`). - -See for context. - -Examples: - -- `DONT_PULL=1 zwift` will prevent docker/podman pull before launch -- `DRYRUN=1 zwift` will print the underlying container run command and exit (no container is started) -- `INTERACTIVE=1 zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the container -- `CONTAINER_TOOL=docker zwift` will launch zwift with docker even if podman is installed -- `CONTAINER_EXTRA_ARGS=--cpus=1.5` will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, - this is useful on laptops to avoid overheating and subsequent throttling of the CPU by the system). -- `USER=Fred zwift` perfect if your neighbor fred want's to try zwift, and you don't want to mess up your zwift config. -- `NETWORKING=host zwift` will use host networking which may be needed to have zwift talk to wifi enabled trainers. -- `ZWIFT_UID=123 ZWIFT_GID=123 zwift` will run zwift as the given uid and gid. By default zwift runs with the uid and gid of - the user that started the container. You should not need to change this except in rare cases. NOTE: This does not work in - wayland only X11. -- `WINE_EXPERIMENTAL_WAYLAND=1 zwift` This will start zwift using Wayland and not XWayland. It will start full screen windowed. - -You can also set these in `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config` to be sourced by the `zwift.sh` -script on execution. - ## How can I persist my login information so i don't need to login on every startup? To authenticate through Zwift automatically simply add the following file `$HOME/.config/zwift/config`: diff --git a/docs/nixos.md b/docs/nixos.md index b9222e12..0ac1f7b9 100644 --- a/docs/nixos.md +++ b/docs/nixos.md @@ -1,6 +1,6 @@ --- title: NixOS -nav_order: 3 +nav_order: 4 --- # NixOS diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 00000000..baa488d0 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,66 @@ +--- +title: Configuration options +nav_order: 2 +--- + +# Configuration options + +| Key | Default | Description | +|-----------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| `USER` | `$USER` | Used in creating the zwift volume `zwift-$USER` | +| `IMAGE` | `docker.io/netbrain/zwift` | The image to use | +| `VERSION` | `latest` | The image version/tag to use | +| `DONT_CHECK` | | If set, don't check for updated `zwift.sh` | +| `DONT_PULL` | | If set, don't pull for new image version | +| `DRYRUN` | | If set, print the full container run command and exit | +| `INTERACTIVE` | | If set, force `-it` and use `--entrypoint bash` for debugging | +| `CONTAINER_TOOL` | | Defaults to podman if installed, else docker | +| `CONTAINER_EXTRA_ARGS` | | Extra args passed to docker/podman (`--cups=1.5`) | +| `ZWIFT_USERNAME` | | If set, try to login to zwift automatically | +| `ZWIFT_PASSWORD` | | If set, try to login to zwift automatically | +| `ZWIFT_WORKOUT_DIR` | | Set the workouts directory location | +| `ZWIFT_ACTIVITY_DIR` | | Set the activities directory location | +| `ZWIFT_LOG_DIR` | | Set the logs directory location | +| `ZWIFT_SCREENSHOTS_DIR` | | Set the screenshots directory location, recommended to set `ZWIFT_SCREENSHOTS_DIR=$(xdg-user-dir PICTURES)/Zwift` | +| `ZWIFT_OVERRIDE_GRAPHICS` | | If set, override the default zwift graphics profiles | +| `ZWIFT_OVERRIDE_RESOLUTION` | | If set, change game resolution (2560x1440, 3840x2160, ...) | +| `ZWIFT_FG` | | If set, run the process in fg instead of bg (`-d`) | +| `ZWIFT_NO_GAMEMODE` | | If set, don't run game mode | +| `WINE_EXPERIMENTAL_WAYLAND` | | If set, try to use experimental wayland support in wine 9 | +| `NETWORKING` | `bridge` | Sets the type of container networking to use. | +| `ZWIFT_UID` | current users id | Sets the UID that Zwift will run as (docker only) | +| `ZWIFT_GID` | current users group id | Sets the GID that Zwift will run as (docker only) | +| `DEBUG` | | If set enabled debug of zwift script `set -x` | +| `VGA_DEVICE_FLAG` | | Override GPU/device flags for container (`--gpus=all`) | +| `PRIVILEGED_CONTAINER` | `0` | If set, container will run in privileged mode, SELinux label separation will be disabled (`--privileged --security-opt label=disable`) | + +These environment variables can be used to alter the execution of the zwift bash script. + +Short note on NVIDIA Container Toolkit device flags: + +- Podman: prefer setting `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` (CDI device request). +- Docker: prefer setting `VGA_DEVICE_FLAG="--gpus=all"`. If Docker ≥ 25 is configured with CDI + (`nvidia-ctk runtime configure --enable-cdi`), `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` also works. + +If you're running Docker with CDI and zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` +(instead of `"--gpus=all"`). + +See for context. + +Examples: + +- `DONT_PULL=1 zwift` will prevent docker/podman pull before launch +- `DRYRUN=1 zwift` will print the underlying container run command and exit (no container is started) +- `INTERACTIVE=1 zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the container +- `CONTAINER_TOOL=docker zwift` will launch zwift with docker even if podman is installed +- `CONTAINER_EXTRA_ARGS=--cpus=1.5` will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, + this is useful on laptops to avoid overheating and subsequent throttling of the CPU by the system). +- `USER=Fred zwift` perfect if your neighbor fred want's to try zwift, and you don't want to mess up your zwift config. +- `NETWORKING=host zwift` will use host networking which may be needed to have zwift talk to wifi enabled trainers. +- `ZWIFT_UID=123 ZWIFT_GID=123 zwift` will run zwift as the given uid and gid. By default zwift runs with the uid and gid of + the user that started the container. You should not need to change this except in rare cases. NOTE: This does not work in + wayland only X11. +- `WINE_EXPERIMENTAL_WAYLAND=1 zwift` This will start zwift using Wayland and not XWayland. It will start full screen windowed. + +You can also set these in `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config` to be sourced by the `zwift.sh` +script on execution. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index a648de17..17160c1c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,6 +1,6 @@ --- title: Troubleshooting -nav_order: 3 +nav_order: 5 --- # Troubleshooting From 29e9b83beb1ec31e78282f251dae81ea4c6ba6cc Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Tue, 27 Jan 2026 23:05:43 +0100 Subject: [PATCH 23/65] Add title for resolution --- docs/graphics.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/graphics.md b/docs/graphics.md index 58f6dbe6..5e5c3461 100644 --- a/docs/graphics.md +++ b/docs/graphics.md @@ -54,6 +54,8 @@ different profiles have changed to what is in the table listed above and for exa exists. If a `graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically the first time zwift is launched. +## How can I change the game resolution? + Aside from the graphics profile which is assigned by zwift and cannot be changed, there is also the in-game setting to change the display resolution. Changing this resolution does not change the graphics profile and as such does not affect the quality of the textures, shadows, and other graphics options. It only affects the resolution of the game itself. Which resolutions are From 9bb8133811e52aaf694047e7997f96547a4fe67f Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Wed, 28 Jan 2026 12:10:04 +0100 Subject: [PATCH 24/65] Enable dark mode --- docs/_config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_config.yml b/docs/_config.yml index 674a0810..eae34cc8 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,6 +1,7 @@ title: netbrain/zwift description: Easily Zwift on Linux repository: netbrain/zwift +color_scheme: dark permalink: pretty back_to_top: true back_to_top_text: "Back to top" From 085b2d591ec35f8ccc11ab60864910ec856d2cdb Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Wed, 28 Jan 2026 12:20:30 +0100 Subject: [PATCH 25/65] Add callouts --- docs/_config.yml | 15 +++++++++++++++ docs/graphics.md | 12 +++++++----- docs/index.md | 33 ++++++++++++++++++++------------- 3 files changed, 42 insertions(+), 18 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index eae34cc8..938b237e 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -12,5 +12,20 @@ nav_external_links: - title: netbrain/zwift on GitHub url: https://github.com/netbrain/zwift remote_theme: just-the-docs/just-the-docs@v0.12.0 +callouts: + highlight: + color: yellow + important: + title: Important + color: blue + new: + title: New + color: green + note: + title: Note + color: purple + warning: + title: Warning + color: red plugins: - jemoji diff --git a/docs/graphics.md b/docs/graphics.md index 5e5c3461..cfc7f2bd 100644 --- a/docs/graphics.md +++ b/docs/graphics.md @@ -50,9 +50,10 @@ You can find more information about these settings in this [Zwift Insider](https article. Note that this is an older article and as such some of the information in it is outdated. The default values of the different profiles have changed to what is in the table listed above and for example the `aniso` setting does not exist anymore. -> :warning: **Before using ZWIFT_OVERRIDE_GRAPHICS**: This option requires that the `$HOME/.config/zwift/graphics.txt` file -exists. If a `graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically -the first time zwift is launched. +{: .important } +**Before using ZWIFT_OVERRIDE_GRAPHICS**: This option requires that the `$HOME/.config/zwift/graphics.txt` file exists. If a +`graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically the first time +zwift is launched. ## How can I change the game resolution? @@ -74,5 +75,6 @@ The full list of available resolutions is: | Ultra | 1440p | 2560x1440 | | 4k UHD | 2160p | 3840x2160 | -> :warning: **Before using ZWIFT_OVERRIDE_RESOLUTION**: This option requires that the `prefs.xml` file exists. Make sure to - launch zwift at least once so it creates the `prefs.xml` file before using the `ZWIFT_OVERRIDE_RESOLUTION` option. +{: .important } +**Before using ZWIFT_OVERRIDE_RESOLUTION**: This option requires that the `prefs.xml` file exists. Make sure to launch zwift at +least once so it creates the `prefs.xml` file before using the `ZWIFT_OVERRIDE_RESOLUTION` option. diff --git a/docs/index.md b/docs/index.md index 4f90696f..62de1bb4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,8 +10,9 @@ permalink: / Easily Zwift on Linux! :100: -> :warning: **Podman Support 4.3 and Later.**: Podman before 4.3 does not support `--userns=keep-id:uid=xxx,gid=xxx` and will - not start correctly, this impacts Ubuntu 22.04 and related builds such as PopOS 22.04. See Podman Section below. +{: .warning } +**Podman Support 4.3 and Later.**: Podman before 4.3 does not support `--userns=keep-id:uid=xxx,gid=xxx` and will not start +correctly, this impacts Ubuntu 22.04 and related builds such as PopOS 22.04. See Podman Section below. If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or other programs listening on the bus from inhibiting the screen. @@ -30,7 +31,8 @@ Where `username` is your zwift account email, and `password` your zwift account The credentials will be used to authenticate before launching the zwift app, and the user should be logged in automatically in the game. -NOTE: This will be loaded by `zwift.sh` in cleartext as environment variables into the container. +{: .note } +This will be loaded by `zwift.sh` in cleartext as environment variables into the container. Alternatively, instead of saving your password in the file, you can save your password in the secret service keyring like so: @@ -41,12 +43,14 @@ secret-tool store --label "Zwift password for ${ZWIFT_USERNAME}" application zwi In this case the username should still be saved in the config file and the password will be read upon startup from the keyring and passed as a secret into the container (where it is an environment variable). -> :warning: **Do Not Quote the variables or add spaces**: The ID and Password are read as raw format so if you put - `ZWIFT_PASSWORD="password"` it tries to use `"password"` and not just `password`, same for `''`. In addition do not add a - space to the end of the line it will be sent as part of the password or username. This applies to `ZWIFT_USERNAME` and - `ZWIFT_PASSWORD`. +{: .warning } +**Do Not Quote the variables or add spaces**: The ID and Password are read as raw format so if you put +`ZWIFT_PASSWORD="password"` it tries to use `"password"` and not just `password`, same for `''`. In addition do not add a space +to the end of the line it will be sent as part of the password or username. This applies to `ZWIFT_USERNAME` and +`ZWIFT_PASSWORD`. -NOTE: You can also add other environment variable from the table to make starting easier: +{: .note } +You can also add other environment variable from the table to make starting easier: ```text ZWIFT_USERNAME=username @@ -90,12 +94,15 @@ logins it may show one subdirectory for each, to find the ID you can use the fol Webpage for finding internal ID: -NOTES: +{: .note } +Any workouts created already will be copied into this folder on first start -- Any workouts created already will be copied into this folder on first start -- To add a new workout just copy the zwo file to this directory -- Deleting files from the directory will not delete them, they will be re-added when re-starting zwift, you must delete from the - zwift menu +{: .note } +To add a new workout just copy the zwo file to this directory + +{: .note } +Deleting files from the directory will not delete them, they will be re-added when re-starting zwift, you must delete from the +zwift menu ## How can I build the image myself? From 698e5dde88e4f950b97e458612ce32745dabbe65 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Wed, 28 Jan 2026 18:23:49 +0100 Subject: [PATCH 26/65] Fix collapsible questions? --- docs/troubleshooting.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 17160c1c..afa5578a 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -5,8 +5,8 @@ nav_order: 5 # Troubleshooting -
-

My WiFi-capable trainer / Zwift Companion App is not detected

 +
+My WiFi-capable trainer / Zwift Companion App is not detected If you have issues with device detection over WiFi/network, the issue may be related to your system's firewall. Some Linux distributions use `firewalld` instead of `ufw`, @@ -67,8 +67,8 @@ to allow multicast traffic on your network instead of disabling it entirely:
-
-

Where are the saves and why do I get a popup can't write to Document Folder?

 +
+Where are the saves and why do I get a popup can't write to Document Folder? This is a hang up from previous versions, mainly with podman. delete the volumes and after re-creation it should work fine. @@ -86,8 +86,8 @@ docker volume rm zwift-xxxxx
-
-

I sometimes get a popup Not responding why?

 +
+I sometimes get a popup Not responding why? For Gnome it is just timing out before zwift responds, just extend the timeout. @@ -97,8 +97,8 @@ gsettings set org.gnome.mutter check-alive-timeout 60000
-
-

The container is slow to start, why?

 +
+The container is slow to start, why? If your `$(id -u)` or `$(id -g)` is not equal to 1000 then this would cause the zwift container to re-map all files (`chown`, `chgrp`) within the container so there is no uid/gid conflicts. So if speed is a concern of yours, consider changing your user From e5c9115a573d7c254b8c0ab39f00d311e62cac26 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 16:27:04 +0100 Subject: [PATCH 27/65] Move remaining index.md content to more for now --- docs/index.md | 115 ------------------------------------------------ docs/more.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 115 deletions(-) create mode 100644 docs/more.md diff --git a/docs/index.md b/docs/index.md index 62de1bb4..04a9bc87 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,118 +9,3 @@ permalink: / # netbrain/zwift Easily Zwift on Linux! :100: - -{: .warning } -**Podman Support 4.3 and Later.**: Podman before 4.3 does not support `--userns=keep-id:uid=xxx,gid=xxx` and will not start -correctly, this impacts Ubuntu 22.04 and related builds such as PopOS 22.04. See Podman Section below. - -If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or -other programs listening on the bus from inhibiting the screen. - -## How can I persist my login information so i don't need to login on every startup? - -To authenticate through Zwift automatically simply add the following file `$HOME/.config/zwift/config`: - -```text -ZWIFT_USERNAME=username -ZWIFT_PASSWORD=password -``` - -Where `username` is your zwift account email, and `password` your zwift account password, respectively. - -The credentials will be used to authenticate before launching the zwift app, and the user should be logged in automatically in -the game. - -{: .note } -This will be loaded by `zwift.sh` in cleartext as environment variables into the container. - -Alternatively, instead of saving your password in the file, you can save your password in the secret service keyring like so: - -```text -secret-tool store --label "Zwift password for ${ZWIFT_USERNAME}" application zwift username ${ZWIFT_USERNAME} -``` - -In this case the username should still be saved in the config file and the password will be read upon startup from the keyring -and passed as a secret into the container (where it is an environment variable). - -{: .warning } -**Do Not Quote the variables or add spaces**: The ID and Password are read as raw format so if you put -`ZWIFT_PASSWORD="password"` it tries to use `"password"` and not just `password`, same for `''`. In addition do not add a space -to the end of the line it will be sent as part of the password or username. This applies to `ZWIFT_USERNAME` and -`ZWIFT_PASSWORD`. - -{: .note } -You can also add other environment variable from the table to make starting easier: - -```text -ZWIFT_USERNAME=username -ZWIFT_PASSWORD=password - -ZWIFT_WORKOUT_DIR=~/.config/zwift/workouts -WINE_EXPERIMENTAL_WAYLAND=1 -``` - -## Podman Support - -When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need -to map the container id 1000 to the host id using `uidmap` and `gidmap`. - -For example if the host uid/gid is 1001/1001 then we need to map the host resources from `/run/user/1001` to the container -resource `/run/user/1000` and map the user and group id's the same. This had to be done manually on the host podman start using -`--uidmap` and `--gidmap` (not covered here). - -From Podman 4.3 this became automatic by providing the Container UID/GID and podman automatically sets up this mapping. - -NOTE: Using ZWIFT_UID/GID will only work if the user starting podman has access to the `/run/user/$ZWIFT_UID` resources and does -not work the same way as in Docker so is not supported. - -## How do I connect my trainer, heart rate monitor, etc? - -You can [use your phone as a bridge](https://support.zwift.com/using-the-zwift-companion-app-Hybn8qzPr). - -For example, your Wahoo Kickr and Apple Watch connect to the Zwift Companion app on your iPhone; then the Companion app connects -over wifi to your PC running Zwift. - -## How can I add custom .zwo files? - -You can map the zwift Workout folder using the environment variable `ZWIFT_WORKOUT_DIR`, for example if your workout directory -is in `$HOME/zwift_workouts` then you would provide the environment variable `ZWIFT_WORKOUT_DIR=$HOME/zwift_workouts`. - -You can add this variable into `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config`. - -The workouts folder will contain subdirectories e.g. `$HOME/.config/zwift/workouts/393938`. The number is your internal zwift -id and you store you zwo files in the relevant folder. There will usually be only one ID, however if you have multiple zwift -logins it may show one subdirectory for each, to find the ID you can use the following link: - -Webpage for finding internal ID: - -{: .note } -Any workouts created already will be copied into this folder on first start - -{: .note } -To add a new workout just copy the zwo file to this directory - -{: .note } -Deleting files from the directory will not delete them, they will be re-added when re-starting zwift, you must delete from the -zwift menu - -## How can I build the image myself? - -```console -./bin/build-image.sh -``` - -## How can I fetch the image from docker hub? - - - -```console -docker pull netbrain/zwift:$VERSION # or simply latest -``` - -## How can I update Zwift? - -The `zwift.sh` script will update zwift by checking for new image versions on every launch, however if you are not using this -then you will have to pull `netbrain/zwift:latest` from time to time in order to be on the latest version. - -There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. diff --git a/docs/more.md b/docs/more.md new file mode 100644 index 00000000..e89a8553 --- /dev/null +++ b/docs/more.md @@ -0,0 +1,119 @@ +--- +title: More stuff +nav_order: 6 +--- + +{: .warning } +**Podman Support 4.3 and Later.**: Podman before 4.3 does not support `--userns=keep-id:uid=xxx,gid=xxx` and will not start +correctly, this impacts Ubuntu 22.04 and related builds such as PopOS 22.04. See Podman Section below. + +If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or +other programs listening on the bus from inhibiting the screen. + +## How can I persist my login information so i don't need to login on every startup? + +To authenticate through Zwift automatically simply add the following file `$HOME/.config/zwift/config`: + +```text +ZWIFT_USERNAME=username +ZWIFT_PASSWORD=password +``` + +Where `username` is your zwift account email, and `password` your zwift account password, respectively. + +The credentials will be used to authenticate before launching the zwift app, and the user should be logged in automatically in +the game. + +{: .note } +This will be loaded by `zwift.sh` in cleartext as environment variables into the container. + +Alternatively, instead of saving your password in the file, you can save your password in the secret service keyring like so: + +```text +secret-tool store --label "Zwift password for ${ZWIFT_USERNAME}" application zwift username ${ZWIFT_USERNAME} +``` + +In this case the username should still be saved in the config file and the password will be read upon startup from the keyring +and passed as a secret into the container (where it is an environment variable). + +{: .warning } +**Do Not Quote the variables or add spaces**: The ID and Password are read as raw format so if you put +`ZWIFT_PASSWORD="password"` it tries to use `"password"` and not just `password`, same for `''`. In addition do not add a space +to the end of the line it will be sent as part of the password or username. This applies to `ZWIFT_USERNAME` and +`ZWIFT_PASSWORD`. + +{: .note } +You can also add other environment variable from the table to make starting easier: + +```text +ZWIFT_USERNAME=username +ZWIFT_PASSWORD=password + +ZWIFT_WORKOUT_DIR=~/.config/zwift/workouts +WINE_EXPERIMENTAL_WAYLAND=1 +``` + +## Podman Support + +When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need +to map the container id 1000 to the host id using `uidmap` and `gidmap`. + +For example if the host uid/gid is 1001/1001 then we need to map the host resources from `/run/user/1001` to the container +resource `/run/user/1000` and map the user and group id's the same. This had to be done manually on the host podman start using +`--uidmap` and `--gidmap` (not covered here). + +From Podman 4.3 this became automatic by providing the Container UID/GID and podman automatically sets up this mapping. + +NOTE: Using ZWIFT_UID/GID will only work if the user starting podman has access to the `/run/user/$ZWIFT_UID` resources and does +not work the same way as in Docker so is not supported. + +## How do I connect my trainer, heart rate monitor, etc? + +You can [use your phone as a bridge](https://support.zwift.com/using-the-zwift-companion-app-Hybn8qzPr). + +For example, your Wahoo Kickr and Apple Watch connect to the Zwift Companion app on your iPhone; then the Companion app connects +over wifi to your PC running Zwift. + +## How can I add custom .zwo files? + +You can map the zwift Workout folder using the environment variable `ZWIFT_WORKOUT_DIR`, for example if your workout directory +is in `$HOME/zwift_workouts` then you would provide the environment variable `ZWIFT_WORKOUT_DIR=$HOME/zwift_workouts`. + +You can add this variable into `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config`. + +The workouts folder will contain subdirectories e.g. `$HOME/.config/zwift/workouts/393938`. The number is your internal zwift +id and you store you zwo files in the relevant folder. There will usually be only one ID, however if you have multiple zwift +logins it may show one subdirectory for each, to find the ID you can use the following link: + +Webpage for finding internal ID: + +{: .note } +Any workouts created already will be copied into this folder on first start + +{: .note } +To add a new workout just copy the zwo file to this directory + +{: .note } +Deleting files from the directory will not delete them, they will be re-added when re-starting zwift, you must delete from the +zwift menu + +## How can I build the image myself? + +```console +./bin/build-image.sh +``` + +## How can I fetch the image from docker hub? + + + +```console +docker pull netbrain/zwift:$VERSION # or simply latest +``` + +## How can I update Zwift? + +The `zwift.sh` script will update zwift by checking for new image versions on every launch, however if you are not using this +then you will have to pull `netbrain/zwift:latest` from time to time in order to be on the latest version. + +There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. From 590f758c05a9981210a01b8333dbb29a53609a41 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 16:29:45 +0100 Subject: [PATCH 28/65] First version of landing page --- docs/index.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/index.md b/docs/index.md index 04a9bc87..f70e84a8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,3 +9,17 @@ permalink: / # netbrain/zwift Easily Zwift on Linux! :100: + +## Quick Start + +```bash +sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/netbrain/zwift/master/bin/install.sh)" +``` + +## Key Features + +- **Easy installation** +- **Comprehensive configuration options** +- **Multi-instance support** + +[Get Started](/getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } From 49e09055e07693901f90e11a94c490bd7110bc0b Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 19:08:37 +0100 Subject: [PATCH 29/65] Work on getting started section --- docs/getting-started/index.md | 30 +++++++++++++++++++++ docs/getting-started/installation.md | 38 +++++++++++++++++++++++++++ docs/getting-started/prerequisites.md | 38 +++++++++++++++++++++++++++ 3 files changed, 106 insertions(+) create mode 100644 docs/getting-started/index.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/getting-started/prerequisites.md diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 00000000..011ffc98 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,30 @@ +--- +title: Getting Started +nav_order: 2 +description: "Learn how to set up and run Zwift on Linux using Podman or Docker" +permalink: /getting-started +--- + +# Getting Started with Zwift Docker Container + +Welcome to the Zwift container setup guide. This section will walk you through everything you need to know to get Zwift running +smoothly on your Linux system. + +## Quick Navigation + +- TOC +{:toc} + +## Overview + +The Zwift container provides an easy, consistent way to run Zwift on Linux systems. Whether you're a casual user or a serious +cyclist, this guide will help you get up and running quickly. + +### What You'll Learn + +- System requirements +- Installation methods +- Initial configuration +- Troubleshooting common setup issues + +[Start Installation](/getting-started/prerequisites){: .btn .btn-green } diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 00000000..03c3880e --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,38 @@ +--- +title: Installation +parent: Getting Started +nav_order: 2 +--- + +# Installation Methods + +## Automatic Installation Script + +### One-Line Installation + +```bash +sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/netbrain/zwift/master/bin/install.sh)" +``` + +This script will: + +- Download the Zwift Docker image +- Create necessary configuration files +- Add zwift command to your system path +- Create desktop shortcut + +## Manual Installation Steps + +### How can I build the image myself? + +```bash +./bin/build-image.sh +``` + +### How can I fetch the image from docker hub? + + + +```bash +docker pull netbrain/zwift:$VERSION # or simply latest +``` diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md new file mode 100644 index 00000000..71893888 --- /dev/null +++ b/docs/getting-started/prerequisites.md @@ -0,0 +1,38 @@ +--- +title: Prerequisites +parent: Getting Started +nav_order: 1 +--- + +# System Prerequisites + +## Minimum System Requirements + +| Component | Minimum Requirements | +|-----------------------|------------------------| +| **Operating System** | Linux (64-bit) | +| **Container Runtime** | Docker or Podman 4.3+ | +| **RAM** | 8 GB | +| **Graphics** | OpenGL 3.1+ compatible | +| **Storage** | 15 GB of free space | + +## Required Software + +### Container Runtimes + +- **Docker** + - Install from [Docker documentation](https://docs.docker.com/get-docker/) +- **Podman** (Alternative) + - Version 4.3+ recommended + - Install from [Podman installation guide](https://podman.io/getting-started/installation) + +### Additional Dependencies for NVIDIA users + +- **NVIDIA Container Toolkit** + - Install from [install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) + +{: .note } +**Note for Podman users**: Also follow the Container Device Interface +[guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html). + +[Next: Installation](/getting-started/installation){: .btn .btn-green } From b2c1b91af8b13b64c97c4a6ce8a3d66be613b394 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 22:04:19 +0100 Subject: [PATCH 30/65] Work on prerequisites section --- docs/getting-started/index.md | 9 +-------- docs/getting-started/prerequisites.md | 13 ++++++++----- docs/index.md | 2 -- 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 011ffc98..bb22f7ca 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -10,21 +10,14 @@ permalink: /getting-started Welcome to the Zwift container setup guide. This section will walk you through everything you need to know to get Zwift running smoothly on your Linux system. -## Quick Navigation - -- TOC -{:toc} - ## Overview The Zwift container provides an easy, consistent way to run Zwift on Linux systems. Whether you're a casual user or a serious cyclist, this guide will help you get up and running quickly. -### What You'll Learn +## What You'll Learn - System requirements - Installation methods - Initial configuration - Troubleshooting common setup issues - -[Start Installation](/getting-started/prerequisites){: .btn .btn-green } diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md index 71893888..04b0258b 100644 --- a/docs/getting-started/prerequisites.md +++ b/docs/getting-started/prerequisites.md @@ -29,10 +29,13 @@ nav_order: 1 ### Additional Dependencies for NVIDIA users - **NVIDIA Container Toolkit** - - Install from [install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) + - Install from [NVIDIA Container Toolkit installation guide]( + https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) -{: .note } -**Note for Podman users**: Also follow the Container Device Interface -[guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html). +{: .important } +**Podman users**: Also follow the [Container Device Interface guide]( + https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html) -[Next: Installation](/getting-started/installation){: .btn .btn-green } +{: .note } +**NVIDIA Container Toolkit before v1.18.0**: The cdi specification file needs to be generated manually each time +the NVIDIA driver is updated using the following command: `sudo nvidia-ctk cdi generate --output=/var/run/cdi/nvidia.yaml` diff --git a/docs/index.md b/docs/index.md index f70e84a8..3335da98 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,5 +21,3 @@ sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/netbrain/zwift/mast - **Easy installation** - **Comprehensive configuration options** - **Multi-instance support** - -[Get Started](/getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } From 1e1cd3528db04be45766fedf00232e38f365defa Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 22:07:29 +0100 Subject: [PATCH 31/65] Add example installation gif --- docs/getting-started/installation.md | 2 ++ docs/index.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 03c3880e..1f533db3 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -10,6 +10,8 @@ nav_order: 2 ### One-Line Installation +![example.gif](https://raw.githubusercontent.com/netbrain/zwift/master/example.gif) + ```bash sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/netbrain/zwift/master/bin/install.sh)" ``` diff --git a/docs/index.md b/docs/index.md index 3335da98..37f35e72 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,6 +12,8 @@ Easily Zwift on Linux! :100: ## Quick Start +![example.gif](https://raw.githubusercontent.com/netbrain/zwift/master/example.gif) + ```bash sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/netbrain/zwift/master/bin/install.sh)" ``` From 52f8c54388ae15f5d07e37945830e615491a8893 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 22:11:21 +0100 Subject: [PATCH 32/65] Try different colors for callouts --- docs/_config.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 938b237e..06a79472 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -17,13 +17,13 @@ callouts: color: yellow important: title: Important - color: blue + color: yellow new: title: New color: green note: title: Note - color: purple + color: yellow warning: title: Warning color: red From c968d7c675fa673a777a23b61cc93f6307eadd49 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 22:18:01 +0100 Subject: [PATCH 33/65] Add old podman warning --- docs/getting-started/prerequisites.md | 6 +++++- docs/more.md | 4 ---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md index 04b0258b..c52a3016 100644 --- a/docs/getting-started/prerequisites.md +++ b/docs/getting-started/prerequisites.md @@ -26,7 +26,11 @@ nav_order: 1 - Version 4.3+ recommended - Install from [Podman installation guide](https://podman.io/getting-started/installation) -### Additional Dependencies for NVIDIA users +{: .warning } +**Podman 4.3 and earlier**: Does not support `--userns=keep-id:uid=xxx,gid=xxx` and will not start correctly, this impacts +Ubuntu 22.04 and related builds such as PopOS! 22.04. + +### Additional Dependencies for NVIDIA graphics cards - **NVIDIA Container Toolkit** - Install from [NVIDIA Container Toolkit installation guide]( diff --git a/docs/more.md b/docs/more.md index e89a8553..f84688d0 100644 --- a/docs/more.md +++ b/docs/more.md @@ -3,10 +3,6 @@ title: More stuff nav_order: 6 --- -{: .warning } -**Podman Support 4.3 and Later.**: Podman before 4.3 does not support `--userns=keep-id:uid=xxx,gid=xxx` and will not start -correctly, this impacts Ubuntu 22.04 and related builds such as PopOS 22.04. See Podman Section below. - If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or other programs listening on the bus from inhibiting the screen. From ba63a570c5c7e2a03a2f8bf26cfee569fa2e22d4 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 22:23:51 +0100 Subject: [PATCH 34/65] Tweaking a bit --- docs/getting-started/prerequisites.md | 14 +++++++------- docs/index.md | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md index c52a3016..64bc95f4 100644 --- a/docs/getting-started/prerequisites.md +++ b/docs/getting-started/prerequisites.md @@ -8,13 +8,13 @@ nav_order: 1 ## Minimum System Requirements -| Component | Minimum Requirements | -|-----------------------|------------------------| -| **Operating System** | Linux (64-bit) | -| **Container Runtime** | Docker or Podman 4.3+ | -| **RAM** | 8 GB | -| **Graphics** | OpenGL 3.1+ compatible | -| **Storage** | 15 GB of free space | +| Component | Minimum Requirements | +|-----------------------|-------------------------------------------------| +| **Operating System** | Linux (64-bit) | +| **Container Runtime** | Docker or Podman 4.3+ | +| **RAM** | 8 GB | +| **Graphics** | OpenGL 3.1+ compatible (integrated or discrete) | +| **Storage** | 15 GB of free space | ## Required Software diff --git a/docs/index.md b/docs/index.md index 37f35e72..304f3314 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,12 +12,12 @@ Easily Zwift on Linux! :100: ## Quick Start -![example.gif](https://raw.githubusercontent.com/netbrain/zwift/master/example.gif) - ```bash sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/netbrain/zwift/master/bin/install.sh)" ``` +![example.gif](https://raw.githubusercontent.com/netbrain/zwift/master/example.gif) + ## Key Features - **Easy installation** From a5f961bcd656fbc13c304766e222236f31feb748 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 22:38:16 +0100 Subject: [PATCH 35/65] Create graphics section and move everything else to TODO --- docs/configuration/authentication.md | 7 +++++++ docs/configuration/graphics.md | 7 +++++++ docs/configuration/index.md | 8 ++++++++ docs/configuration/options.md | 7 +++++++ docs/{ => todo}/graphics.md | 3 ++- docs/todo/index.md | 8 ++++++++ docs/{ => todo}/more.md | 3 ++- docs/{ => todo}/nixos.md | 3 ++- docs/{ => todo}/options.md | 1 + docs/{ => todo}/troubleshooting.md | 3 ++- 10 files changed, 46 insertions(+), 4 deletions(-) create mode 100644 docs/configuration/authentication.md create mode 100644 docs/configuration/graphics.md create mode 100644 docs/configuration/index.md create mode 100644 docs/configuration/options.md rename docs/{ => todo}/graphics.md (99%) create mode 100644 docs/todo/index.md rename docs/{ => todo}/more.md (99%) rename docs/{ => todo}/nixos.md (99%) rename docs/{ => todo}/options.md (99%) rename docs/{ => todo}/troubleshooting.md (99%) diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md new file mode 100644 index 00000000..621951ef --- /dev/null +++ b/docs/configuration/authentication.md @@ -0,0 +1,7 @@ +--- +title: Authentication +parent: Configuration +nav_order: 1 +--- + +# Authentication diff --git a/docs/configuration/graphics.md b/docs/configuration/graphics.md new file mode 100644 index 00000000..9f368982 --- /dev/null +++ b/docs/configuration/graphics.md @@ -0,0 +1,7 @@ +--- +title: Graphics Settings +parent: Configuration +nav_order: 3 +--- + +# Zwift Graphics Settings diff --git a/docs/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 00000000..0b17787e --- /dev/null +++ b/docs/configuration/index.md @@ -0,0 +1,8 @@ +--- +title: Configuration +nav_order: 3 +description: "Learn how to set up and run Zwift on Linux using Podman or Docker" +permalink: /configuration +--- + +# Configuration diff --git a/docs/configuration/options.md b/docs/configuration/options.md new file mode 100644 index 00000000..209e547e --- /dev/null +++ b/docs/configuration/options.md @@ -0,0 +1,7 @@ +--- +title: Configuration Options +parent: Configuration +nav_order: 2 +--- + +# Configuration Options diff --git a/docs/graphics.md b/docs/todo/graphics.md similarity index 99% rename from docs/graphics.md rename to docs/todo/graphics.md index cfc7f2bd..b31ad190 100644 --- a/docs/graphics.md +++ b/docs/todo/graphics.md @@ -1,6 +1,7 @@ --- title: Customize Zwift graphics -nav_order: 3 +parent: TODO +nav_order: 1 --- # Customize Zwift graphics diff --git a/docs/todo/index.md b/docs/todo/index.md new file mode 100644 index 00000000..bb7d3332 --- /dev/null +++ b/docs/todo/index.md @@ -0,0 +1,8 @@ +--- +title: TODO +nav_order: 3 +description: "Stuff that needs to be moved to a proper location in the documentation" +permalink: /todo +--- + +# TODO diff --git a/docs/more.md b/docs/todo/more.md similarity index 99% rename from docs/more.md rename to docs/todo/more.md index f84688d0..1269fe04 100644 --- a/docs/more.md +++ b/docs/todo/more.md @@ -1,6 +1,7 @@ --- title: More stuff -nav_order: 6 +nav_order: 5 +parent: TODO --- If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or diff --git a/docs/nixos.md b/docs/todo/nixos.md similarity index 99% rename from docs/nixos.md rename to docs/todo/nixos.md index 0ac1f7b9..1eddca31 100644 --- a/docs/nixos.md +++ b/docs/todo/nixos.md @@ -1,6 +1,7 @@ --- title: NixOS -nav_order: 4 +parent: TODO +nav_order: 3 --- # NixOS diff --git a/docs/options.md b/docs/todo/options.md similarity index 99% rename from docs/options.md rename to docs/todo/options.md index baa488d0..9637cfb1 100644 --- a/docs/options.md +++ b/docs/todo/options.md @@ -1,5 +1,6 @@ --- title: Configuration options +parent: TODO nav_order: 2 --- diff --git a/docs/troubleshooting.md b/docs/todo/troubleshooting.md similarity index 99% rename from docs/troubleshooting.md rename to docs/todo/troubleshooting.md index afa5578a..7d6f19f1 100644 --- a/docs/troubleshooting.md +++ b/docs/todo/troubleshooting.md @@ -1,6 +1,7 @@ --- title: Troubleshooting -nav_order: 5 +nav_order: 4 +parent: TODO --- # Troubleshooting From cefa35a238092a17d762a801cd8ddda8a98b5773 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Thu, 29 Jan 2026 22:40:39 +0100 Subject: [PATCH 36/65] Fix nav order --- docs/todo/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/todo/index.md b/docs/todo/index.md index bb7d3332..41f4aa2b 100644 --- a/docs/todo/index.md +++ b/docs/todo/index.md @@ -1,6 +1,6 @@ --- title: TODO -nav_order: 3 +nav_order: 4 description: "Stuff that needs to be moved to a proper location in the documentation" permalink: /todo --- From 21e58fb59ce35deb755fbb181f3013374daa6a9d Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 17:43:43 +0100 Subject: [PATCH 37/65] Move zwift graphics documentation to configuration section --- docs/configuration/graphics.md | 76 ++++++++++++++++++++++++++++++- docs/todo/graphics.md | 81 ---------------------------------- 2 files changed, 75 insertions(+), 82 deletions(-) delete mode 100644 docs/todo/graphics.md diff --git a/docs/configuration/graphics.md b/docs/configuration/graphics.md index 9f368982..a927ade3 100644 --- a/docs/configuration/graphics.md +++ b/docs/configuration/graphics.md @@ -4,4 +4,78 @@ parent: Configuration nav_order: 3 --- -# Zwift Graphics Settings +# Customize Zwift graphics + +## How can I access/modify the graphics settings? + +By default, zwift assigns a graphics profile based on your graphics card. This profile can be either basic, medium, high, or +ultra. This profile determines the level of detail and the quality of the textures you get in game. It is not possible to change +which graphics profile the game uses. When the default options of the profile aren't optimal (for example when zwift doesn't +recognize your graphics card and you only get the `medium` profile or when your cpu is the bottleneck and your fps is on the low +side because zwift assigned the ultra profile), it is possible to manually tweak the graphics settings by setting +`ZWIFT_OVERRIDE_GRAPHICS=1`, and editing the settings in the `$HOME/.config/zwift/graphics.txt` or +`$HOME/.config/zwift/$USER-graphics.txt` file as you see fit. To find out which profile zwift assigned, you can upload your +zwift log to . + +The default settings for the different profiles are: + +| key | description | basic | medium | high | ultra | +|----------------------|--------------------------------------------------------|--------------|--------------|--------------|---------------| +| `res` | texture resolution (independent from game resolution) | 1024x576(0x) | 1280x720(0x) | 1280x720(0x) | 1920x1080(0x) | +| `sres` | shadow resolution | 512x512 | 1024x1024 | 1024x1024 | 2048x2048 | +| `gSSAO` | enable high-quality lighting and shadows | 0 | 0 | 1 | 1 | +| `gFXAA` | enable anti-aliasing | 1 | 1 | 1 | 1 | +| `gSunRays` | enable sun rays (default 1) | 0 | 0 | | | +| `gHeadLight` | enable bike headlights (default 1) | 0 | 0 | | | +| `gFoliagePercent` | reduce/increase auto-generated foliage (default 1.0) | 0.5 | 0.5 | | | +| `gSimpleReflections` | lower quality reflections (default 0) | 1 | 1 | | | +| `gLODBias` | lower polygon count (higher value is lower, default 0) | 1 | 1 | | | +| `gShowFPS` | display fps in the top left corner (default 0) | | | | | + +The number in parentheses after the texture resolution (for example `(0x)` after `1920x1080`) is the anti-aliasing setting. This +number can be modified to for example `1920x1080(4x)` or `1920x1080(8x)` to increase anti-aliasing. + +Example `$HOME/.config/zwift/graphics.txt` (settings from the ultra profile, with in-game fps counter enabled): + +```text +res 1920x1080(0x) +sres 2048x2048 +set gSSAO=1 +set gFXAA=1 +set gShowFPS=1 +``` + +Start zwift with the `ZWIFT_OVERRIDE_GRAPHICS=1 zwift` command to use the settings from the graphics.txt file. + +You can find more information about these settings in this [Zwift Insider](https://zwiftinsider.com/config-file-tweaks/) +article. Note that this is an older article and as such some of the information in it is outdated. The default values of the +different profiles have changed to what is in the table listed above and for example the `aniso` setting does not exist anymore. + +{: .important } +**Before using ZWIFT_OVERRIDE_GRAPHICS**: This option requires that the `$HOME/.config/zwift/graphics.txt` file exists. If a +`graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically the first time +zwift is launched. + +## How can I change the game resolution? + +Aside from the graphics profile which is assigned by zwift and cannot be changed, there is also the in-game setting to change +the display resolution. Changing this resolution does not change the graphics profile and as such does not affect the quality of +the textures, shadows, and other graphics options. It only affects the resolution of the game itself. Which resolutions are +available in the zwift in-game setting is dependent on the graphics profile assigned based on your graphics card. If zwift does +not recognize your graphics card or you have a WQHD or UHD display and zwift does not offer the higher resolutions, it is +possible to manually override the game resolution by setting the `ZWIFT_OVERRIDE_RESOLUTION` option. For example to force zwift +to use UHD you can launch it using `ZWIFT_OVERRIDE_RESOLUTION=3840x2160 zwift`. + +The full list of available resolutions is: + +| name | resolution | pixels | +|--------|------------|-----------| +| Low | 576p | 720x576 | +| Medium | 720p | 1280x720 | +| High | 1080p | 1920x1080 | +| Ultra | 1440p | 2560x1440 | +| 4k UHD | 2160p | 3840x2160 | + +{: .important } +**Before using ZWIFT_OVERRIDE_RESOLUTION**: This option requires that the `prefs.xml` file exists. Make sure to launch zwift at +least once so it creates the `prefs.xml` file before using the `ZWIFT_OVERRIDE_RESOLUTION` option. diff --git a/docs/todo/graphics.md b/docs/todo/graphics.md deleted file mode 100644 index b31ad190..00000000 --- a/docs/todo/graphics.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Customize Zwift graphics -parent: TODO -nav_order: 1 ---- - -# Customize Zwift graphics - -## How can I access/modify the graphics settings? - -By default, zwift assigns a graphics profile based on your graphics card. This profile can be either basic, medium, high, or -ultra. This profile determines the level of detail and the quality of the textures you get in game. It is not possible to change -which graphics profile the game uses. When the default options of the profile aren't optimal (for example when zwift doesn't -recognize your graphics card and you only get the `medium` profile or when your cpu is the bottleneck and your fps is on the low -side because zwift assigned the ultra profile), it is possible to manually tweak the graphics settings by setting -`ZWIFT_OVERRIDE_GRAPHICS=1`, and editing the settings in the `$HOME/.config/zwift/graphics.txt` or -`$HOME/.config/zwift/$USER-graphics.txt` file as you see fit. To find out which profile zwift assigned, you can upload your -zwift log to . - -The default settings for the different profiles are: - -| key | description | basic | medium | high | ultra | -|----------------------|--------------------------------------------------------|--------------|--------------|--------------|---------------| -| `res` | texture resolution (independent from game resolution) | 1024x576(0x) | 1280x720(0x) | 1280x720(0x) | 1920x1080(0x) | -| `sres` | shadow resolution | 512x512 | 1024x1024 | 1024x1024 | 2048x2048 | -| `gSSAO` | enable high-quality lighting and shadows | 0 | 0 | 1 | 1 | -| `gFXAA` | enable anti-aliasing | 1 | 1 | 1 | 1 | -| `gSunRays` | enable sun rays (default 1) | 0 | 0 | | | -| `gHeadLight` | enable bike headlights (default 1) | 0 | 0 | | | -| `gFoliagePercent` | reduce/increase auto-generated foliage (default 1.0) | 0.5 | 0.5 | | | -| `gSimpleReflections` | lower quality reflections (default 0) | 1 | 1 | | | -| `gLODBias` | lower polygon count (higher value is lower, default 0) | 1 | 1 | | | -| `gShowFPS` | display fps in the top left corner (default 0) | | | | | - -The number in parentheses after the texture resolution (for example `(0x)` after `1920x1080`) is the anti-aliasing setting. This -number can be modified to for example `1920x1080(4x)` or `1920x1080(8x)` to increase anti-aliasing. - -Example `$HOME/.config/zwift/graphics.txt` (settings from the ultra profile, with in-game fps counter enabled): - -```text -res 1920x1080(0x) -sres 2048x2048 -set gSSAO=1 -set gFXAA=1 -set gShowFPS=1 -``` - -Start zwift with the `ZWIFT_OVERRIDE_GRAPHICS=1 zwift` command to use the settings from the graphics.txt file. - -You can find more information about these settings in this [Zwift Insider](https://zwiftinsider.com/config-file-tweaks/) -article. Note that this is an older article and as such some of the information in it is outdated. The default values of the -different profiles have changed to what is in the table listed above and for example the `aniso` setting does not exist anymore. - -{: .important } -**Before using ZWIFT_OVERRIDE_GRAPHICS**: This option requires that the `$HOME/.config/zwift/graphics.txt` file exists. If a -`graphics.txt` does not exist and the `ZWIFT_OVERRIDE_GRAPHICS` option is used, it will be created automatically the first time -zwift is launched. - -## How can I change the game resolution? - -Aside from the graphics profile which is assigned by zwift and cannot be changed, there is also the in-game setting to change -the display resolution. Changing this resolution does not change the graphics profile and as such does not affect the quality of -the textures, shadows, and other graphics options. It only affects the resolution of the game itself. Which resolutions are -available in the zwift in-game setting is dependent on the graphics profile assigned based on your graphics card. If zwift does -not recognize your graphics card or you have a WQHD or UHD display and zwift does not offer the higher resolutions, it is -possible to manually override the game resolution by setting the `ZWIFT_OVERRIDE_RESOLUTION` option. For example to force zwift -to use UHD you can launch it using `ZWIFT_OVERRIDE_RESOLUTION=3840x2160 zwift`. - -The full list of available resolutions is: - -| name | resolution | pixels | -|--------|------------|-----------| -| Low | 576p | 720x576 | -| Medium | 720p | 1280x720 | -| High | 1080p | 1920x1080 | -| Ultra | 1440p | 2560x1440 | -| 4k UHD | 2160p | 3840x2160 | - -{: .important } -**Before using ZWIFT_OVERRIDE_RESOLUTION**: This option requires that the `prefs.xml` file exists. Make sure to launch zwift at -least once so it creates the `prefs.xml` file before using the `ZWIFT_OVERRIDE_RESOLUTION` option. From b410b1fea61bb6c7b15642f26dd5c70a0d805522 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 18:16:34 +0100 Subject: [PATCH 38/65] Working on configuration options section --- docs/configuration/authentication.md | 2 +- docs/configuration/graphics.md | 6 +-- docs/configuration/options.md | 78 +++++++++++++++++++++++++++- docs/todo/more.md | 13 +---- docs/todo/options.md | 67 ------------------------ 5 files changed, 82 insertions(+), 84 deletions(-) delete mode 100644 docs/todo/options.md diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md index 621951ef..a87dc12c 100644 --- a/docs/configuration/authentication.md +++ b/docs/configuration/authentication.md @@ -1,7 +1,7 @@ --- title: Authentication parent: Configuration -nav_order: 1 +nav_order: 2 --- # Authentication diff --git a/docs/configuration/graphics.md b/docs/configuration/graphics.md index a927ade3..99055d23 100644 --- a/docs/configuration/graphics.md +++ b/docs/configuration/graphics.md @@ -13,7 +13,7 @@ ultra. This profile determines the level of detail and the quality of the textur which graphics profile the game uses. When the default options of the profile aren't optimal (for example when zwift doesn't recognize your graphics card and you only get the `medium` profile or when your cpu is the bottleneck and your fps is on the low side because zwift assigned the ultra profile), it is possible to manually tweak the graphics settings by setting -`ZWIFT_OVERRIDE_GRAPHICS=1`, and editing the settings in the `$HOME/.config/zwift/graphics.txt` or +`ZWIFT_OVERRIDE_GRAPHICS="1"`, and editing the settings in the `$HOME/.config/zwift/graphics.txt` or `$HOME/.config/zwift/$USER-graphics.txt` file as you see fit. To find out which profile zwift assigned, you can upload your zwift log to . @@ -45,7 +45,7 @@ set gFXAA=1 set gShowFPS=1 ``` -Start zwift with the `ZWIFT_OVERRIDE_GRAPHICS=1 zwift` command to use the settings from the graphics.txt file. +Start zwift with the `ZWIFT_OVERRIDE_GRAPHICS="1" zwift` command to use the settings from the graphics.txt file. You can find more information about these settings in this [Zwift Insider](https://zwiftinsider.com/config-file-tweaks/) article. Note that this is an older article and as such some of the information in it is outdated. The default values of the @@ -64,7 +64,7 @@ the textures, shadows, and other graphics options. It only affects the resolutio available in the zwift in-game setting is dependent on the graphics profile assigned based on your graphics card. If zwift does not recognize your graphics card or you have a WQHD or UHD display and zwift does not offer the higher resolutions, it is possible to manually override the game resolution by setting the `ZWIFT_OVERRIDE_RESOLUTION` option. For example to force zwift -to use UHD you can launch it using `ZWIFT_OVERRIDE_RESOLUTION=3840x2160 zwift`. +to use UHD you can launch it using `ZWIFT_OVERRIDE_RESOLUTION="3840x2160" zwift`. The full list of available resolutions is: diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 209e547e..1a8d507c 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -1,7 +1,83 @@ --- title: Configuration Options parent: Configuration -nav_order: 2 +nav_order: 1 --- # Configuration Options + +## List of Environment Variables + +| Key | Default | Description | +|-----------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| `USER` | `$USER` | Used in creating the zwift volume `zwift-$USER` | +| `IMAGE` | `docker.io/netbrain/zwift` | The image to use | +| `VERSION` | `latest` | The image version/tag to use | +| `DONT_CHECK` | | If set, don't check for updated `zwift.sh` | +| `DONT_PULL` | | If set, don't pull for new image version | +| `DRYRUN` | | If set, print the full container run command and exit | +| `INTERACTIVE` | | If set, force `-it` and use `--entrypoint bash` for debugging | +| `CONTAINER_TOOL` | | Defaults to podman if installed, else docker | +| `CONTAINER_EXTRA_ARGS` | | Extra args passed to docker/podman (`--cups=1.5`) | +| `ZWIFT_USERNAME` | | If set, try to login to zwift automatically | +| `ZWIFT_PASSWORD` | | If set, try to login to zwift automatically | +| `ZWIFT_WORKOUT_DIR` | | Set the workouts directory location | +| `ZWIFT_ACTIVITY_DIR` | | Set the activities directory location | +| `ZWIFT_LOG_DIR` | | Set the logs directory location | +| `ZWIFT_SCREENSHOTS_DIR` | | Set the screenshots directory location, recommended to set `ZWIFT_SCREENSHOTS_DIR="$(xdg-user-dir PICTURES)/Zwift"` | +| `ZWIFT_OVERRIDE_GRAPHICS` | | If set, override the default zwift graphics profiles | +| `ZWIFT_OVERRIDE_RESOLUTION` | | If set, change game resolution (2560x1440, 3840x2160, ...) | +| `ZWIFT_FG` | | If set, run the process in fg instead of bg (`-d`) | +| `ZWIFT_NO_GAMEMODE` | | If set, don't run game mode | +| `WINE_EXPERIMENTAL_WAYLAND` | | If set, try to use experimental wayland support in wine 9 | +| `NETWORKING` | `bridge` | Sets the type of container networking to use. | +| `ZWIFT_UID` | current users id | Sets the UID that Zwift will run as (docker only) | +| `ZWIFT_GID` | current users group id | Sets the GID that Zwift will run as (docker only) | +| `DEBUG` | | If set enabled debug of zwift script `set -x` | +| `VGA_DEVICE_FLAG` | | Override GPU/device flags for container (`--gpus=all`) | +| `PRIVILEGED_CONTAINER` | `0` | If set, container will run in privileged mode, SELinux label separation will be disabled (`--privileged --security-opt label=disable`) | + +These environment variables can be used to alter the execution of the zwift bash script. + +{: .note } +> Short note on NVIDIA Container Toolkit device flags: +> +> If you're running Docker with CDI and Zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` +> (instead of `"--gpus=all"`). +> +> See for context. + +### Examples + +- `DONT_PULL="1" zwift` will prevent docker/podman pull before launch +- `DRYRUN="1" zwift` will print the underlying container run command and exit (no container is started) +- `INTERACTIVE="1" zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the container +- `CONTAINER_TOOL="docker" zwift` will launch zwift with docker even if podman is installed +- `CONTAINER_EXTRA_ARGS="--cpus=1.5"` will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, + this is useful on laptops to avoid overheating and subsequent throttling of the CPU by the system). +- `USER="Fred" zwift` perfect if your neighbor Fred want's to try zwift, and you don't want to mess up your zwift config. +- `NETWORKING="host" zwift` will use host networking which may be needed to have zwift talk to wifi enabled trainers. +- `ZWIFT_UID="123" ZWIFT_GID="123" zwift` will run zwift as the given uid and gid. By default zwift runs with the uid and gid of + the user that started the container. You should not need to change this except in rare cases. NOTE: This does not work in + wayland only X11. +- `WINE_EXPERIMENTAL_WAYLAND="1" zwift` This will start zwift using Wayland and not XWayland. It will start full screen + windowed. + +## Configuration files + +You can also set these in `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config` to be sourced by the `zwift.sh` +script on execution. + +### Example + +The `$HOME/.config/zwift/config` file could look like: + +```bash +ZWIFT_USERNAME='user@mail.com' +ZWIFT_PASSWORD='this % is \ a "special" / $(password) with ${characters}, \n is literal and not a newline' +ZWIFT_WORKOUT_DIR="$(xdg-user-dir DOCUMENTS)/Zwift/Workouts" +ZWIFT_LOG_DIR="$(xdg-user-dir DOCUMENTS)/Zwift/Logs" +ZWIFT_SCREENSHOTS_DIR="$(xdg-user-dir PICTURES)/Zwift" +NETWORKING="host" +ZWIFT_OVERRIDE_GRAPHICS="1" +``` diff --git a/docs/todo/more.md b/docs/todo/more.md index 1269fe04..c26f302f 100644 --- a/docs/todo/more.md +++ b/docs/todo/more.md @@ -39,17 +39,6 @@ and passed as a secret into the container (where it is an environment variable). to the end of the line it will be sent as part of the password or username. This applies to `ZWIFT_USERNAME` and `ZWIFT_PASSWORD`. -{: .note } -You can also add other environment variable from the table to make starting easier: - -```text -ZWIFT_USERNAME=username -ZWIFT_PASSWORD=password - -ZWIFT_WORKOUT_DIR=~/.config/zwift/workouts -WINE_EXPERIMENTAL_WAYLAND=1 -``` - ## Podman Support When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need @@ -74,7 +63,7 @@ over wifi to your PC running Zwift. ## How can I add custom .zwo files? You can map the zwift Workout folder using the environment variable `ZWIFT_WORKOUT_DIR`, for example if your workout directory -is in `$HOME/zwift_workouts` then you would provide the environment variable `ZWIFT_WORKOUT_DIR=$HOME/zwift_workouts`. +is in `$HOME/zwift_workouts` then you would provide the environment variable `ZWIFT_WORKOUT_DIR="$HOME/zwift_workouts"`. You can add this variable into `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config`. diff --git a/docs/todo/options.md b/docs/todo/options.md deleted file mode 100644 index 9637cfb1..00000000 --- a/docs/todo/options.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Configuration options -parent: TODO -nav_order: 2 ---- - -# Configuration options - -| Key | Default | Description | -|-----------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| `USER` | `$USER` | Used in creating the zwift volume `zwift-$USER` | -| `IMAGE` | `docker.io/netbrain/zwift` | The image to use | -| `VERSION` | `latest` | The image version/tag to use | -| `DONT_CHECK` | | If set, don't check for updated `zwift.sh` | -| `DONT_PULL` | | If set, don't pull for new image version | -| `DRYRUN` | | If set, print the full container run command and exit | -| `INTERACTIVE` | | If set, force `-it` and use `--entrypoint bash` for debugging | -| `CONTAINER_TOOL` | | Defaults to podman if installed, else docker | -| `CONTAINER_EXTRA_ARGS` | | Extra args passed to docker/podman (`--cups=1.5`) | -| `ZWIFT_USERNAME` | | If set, try to login to zwift automatically | -| `ZWIFT_PASSWORD` | | If set, try to login to zwift automatically | -| `ZWIFT_WORKOUT_DIR` | | Set the workouts directory location | -| `ZWIFT_ACTIVITY_DIR` | | Set the activities directory location | -| `ZWIFT_LOG_DIR` | | Set the logs directory location | -| `ZWIFT_SCREENSHOTS_DIR` | | Set the screenshots directory location, recommended to set `ZWIFT_SCREENSHOTS_DIR=$(xdg-user-dir PICTURES)/Zwift` | -| `ZWIFT_OVERRIDE_GRAPHICS` | | If set, override the default zwift graphics profiles | -| `ZWIFT_OVERRIDE_RESOLUTION` | | If set, change game resolution (2560x1440, 3840x2160, ...) | -| `ZWIFT_FG` | | If set, run the process in fg instead of bg (`-d`) | -| `ZWIFT_NO_GAMEMODE` | | If set, don't run game mode | -| `WINE_EXPERIMENTAL_WAYLAND` | | If set, try to use experimental wayland support in wine 9 | -| `NETWORKING` | `bridge` | Sets the type of container networking to use. | -| `ZWIFT_UID` | current users id | Sets the UID that Zwift will run as (docker only) | -| `ZWIFT_GID` | current users group id | Sets the GID that Zwift will run as (docker only) | -| `DEBUG` | | If set enabled debug of zwift script `set -x` | -| `VGA_DEVICE_FLAG` | | Override GPU/device flags for container (`--gpus=all`) | -| `PRIVILEGED_CONTAINER` | `0` | If set, container will run in privileged mode, SELinux label separation will be disabled (`--privileged --security-opt label=disable`) | - -These environment variables can be used to alter the execution of the zwift bash script. - -Short note on NVIDIA Container Toolkit device flags: - -- Podman: prefer setting `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` (CDI device request). -- Docker: prefer setting `VGA_DEVICE_FLAG="--gpus=all"`. If Docker ≥ 25 is configured with CDI - (`nvidia-ctk runtime configure --enable-cdi`), `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` also works. - -If you're running Docker with CDI and zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` -(instead of `"--gpus=all"`). - -See for context. - -Examples: - -- `DONT_PULL=1 zwift` will prevent docker/podman pull before launch -- `DRYRUN=1 zwift` will print the underlying container run command and exit (no container is started) -- `INTERACTIVE=1 zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the container -- `CONTAINER_TOOL=docker zwift` will launch zwift with docker even if podman is installed -- `CONTAINER_EXTRA_ARGS=--cpus=1.5` will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, - this is useful on laptops to avoid overheating and subsequent throttling of the CPU by the system). -- `USER=Fred zwift` perfect if your neighbor fred want's to try zwift, and you don't want to mess up your zwift config. -- `NETWORKING=host zwift` will use host networking which may be needed to have zwift talk to wifi enabled trainers. -- `ZWIFT_UID=123 ZWIFT_GID=123 zwift` will run zwift as the given uid and gid. By default zwift runs with the uid and gid of - the user that started the container. You should not need to change this except in rare cases. NOTE: This does not work in - wayland only X11. -- `WINE_EXPERIMENTAL_WAYLAND=1 zwift` This will start zwift using Wayland and not XWayland. It will start full screen windowed. - -You can also set these in `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config` to be sourced by the `zwift.sh` -script on execution. From 43b190bf3c8fd3d9b17b5f4c7454e9d2de635dac Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 18:17:56 +0100 Subject: [PATCH 39/65] Fix markdown linter error --- docs/configuration/options.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 1a8d507c..a1c02347 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -51,7 +51,8 @@ These environment variables can be used to alter the execution of the zwift bash - `DONT_PULL="1" zwift` will prevent docker/podman pull before launch - `DRYRUN="1" zwift` will print the underlying container run command and exit (no container is started) -- `INTERACTIVE="1" zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the container +- `INTERACTIVE="1" zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the + container - `CONTAINER_TOOL="docker" zwift` will launch zwift with docker even if podman is installed - `CONTAINER_EXTRA_ARGS="--cpus=1.5"` will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, this is useful on laptops to avoid overheating and subsequent throttling of the CPU by the system). From 5c535dd4d41b0b79ac3f2e7f099522e5cad704e1 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 18:38:44 +0100 Subject: [PATCH 40/65] Working on options documentation --- docs/configuration/options.md | 16 +++++----------- docs/getting-started/prerequisites.md | 6 ++++++ 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index a1c02347..ff521a21 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -8,6 +8,8 @@ nav_order: 1 ## List of Environment Variables +These environment variables can be used to alter the execution of the zwift bash script. + | Key | Default | Description | |-----------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | `USER` | `$USER` | Used in creating the zwift volume `zwift-$USER` | @@ -37,15 +39,8 @@ nav_order: 1 | `VGA_DEVICE_FLAG` | | Override GPU/device flags for container (`--gpus=all`) | | `PRIVILEGED_CONTAINER` | `0` | If set, container will run in privileged mode, SELinux label separation will be disabled (`--privileged --security-opt label=disable`) | -These environment variables can be used to alter the execution of the zwift bash script. - -{: .note } -> Short note on NVIDIA Container Toolkit device flags: -> -> If you're running Docker with CDI and Zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` -> (instead of `"--gpus=all"`). -> -> See for context. +{: .warning } +`ZWIFT_UID` and `ZWIFT_GID` can only used in X11. They do not work in wayland! ### Examples @@ -59,8 +54,7 @@ These environment variables can be used to alter the execution of the zwift bash - `USER="Fred" zwift` perfect if your neighbor Fred want's to try zwift, and you don't want to mess up your zwift config. - `NETWORKING="host" zwift` will use host networking which may be needed to have zwift talk to wifi enabled trainers. - `ZWIFT_UID="123" ZWIFT_GID="123" zwift` will run zwift as the given uid and gid. By default zwift runs with the uid and gid of - the user that started the container. You should not need to change this except in rare cases. NOTE: This does not work in - wayland only X11. + the user that started the container. You should not need to change this except in rare cases. - `WINE_EXPERIMENTAL_WAYLAND="1" zwift` This will start zwift using Wayland and not XWayland. It will start full screen windowed. diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md index 64bc95f4..c6d29222 100644 --- a/docs/getting-started/prerequisites.md +++ b/docs/getting-started/prerequisites.md @@ -43,3 +43,9 @@ Ubuntu 22.04 and related builds such as PopOS! 22.04. {: .note } **NVIDIA Container Toolkit before v1.18.0**: The cdi specification file needs to be generated manually each time the NVIDIA driver is updated using the following command: `sudo nvidia-ctk cdi generate --output=/var/run/cdi/nvidia.yaml` + +{: .note } +> If you're running Docker with CDI and Zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` +> (instead of `"--gpus=all"`). +> +> See for context. From ec8879bed836c588e4b557dddcbe0d6c53f9dbf8 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 18:50:49 +0100 Subject: [PATCH 41/65] Working on prerequisites --- docs/configuration/options.md | 2 +- docs/getting-started/prerequisites.md | 16 ++++------------ docs/todo/more.md | 6 ++++++ 3 files changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index ff521a21..d84e9ad6 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -39,7 +39,7 @@ These environment variables can be used to alter the execution of the zwift bash | `VGA_DEVICE_FLAG` | | Override GPU/device flags for container (`--gpus=all`) | | `PRIVILEGED_CONTAINER` | `0` | If set, container will run in privileged mode, SELinux label separation will be disabled (`--privileged --security-opt label=disable`) | -{: .warning } +{: .important } `ZWIFT_UID` and `ZWIFT_GID` can only used in X11. They do not work in wayland! ### Examples diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md index c6d29222..17b73638 100644 --- a/docs/getting-started/prerequisites.md +++ b/docs/getting-started/prerequisites.md @@ -35,17 +35,9 @@ Ubuntu 22.04 and related builds such as PopOS! 22.04. - **NVIDIA Container Toolkit** - Install from [NVIDIA Container Toolkit installation guide]( https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) - -{: .important } -**Podman users**: Also follow the [Container Device Interface guide]( - https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html) - -{: .note } -**NVIDIA Container Toolkit before v1.18.0**: The cdi specification file needs to be generated manually each time -the NVIDIA driver is updated using the following command: `sudo nvidia-ctk cdi generate --output=/var/run/cdi/nvidia.yaml` + - Podman: Also follow the [Container Device Interface guide]( + https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html) {: .note } -> If you're running Docker with CDI and Zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` -> (instead of `"--gpus=all"`). -> -> See for context. +**Podman and NVIDIA Container Toolkit before v1.18.0**: The cdi specification file needs to be generated manually each time the +NVIDIA driver is updated using the following command: `sudo nvidia-ctk cdi generate --output=/var/run/cdi/nvidia.yaml` diff --git a/docs/todo/more.md b/docs/todo/more.md index c26f302f..7fcf6f91 100644 --- a/docs/todo/more.md +++ b/docs/todo/more.md @@ -103,3 +103,9 @@ The `zwift.sh` script will update zwift by checking for new image versions on ev then you will have to pull `netbrain/zwift:latest` from time to time in order to be on the latest version. There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. + +{: .note } +> If you're running Docker with CDI and Zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` +> (instead of `"--gpus=all"`). +> +> See for context. From 6862aa4f5afb20e0d3fe9400491431254140b295 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 19:03:58 +0100 Subject: [PATCH 42/65] Add example config files for multiple users --- docs/configuration/options.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index d84e9ad6..185480ef 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -51,7 +51,7 @@ These environment variables can be used to alter the execution of the zwift bash - `CONTAINER_TOOL="docker" zwift` will launch zwift with docker even if podman is installed - `CONTAINER_EXTRA_ARGS="--cpus=1.5"` will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, this is useful on laptops to avoid overheating and subsequent throttling of the CPU by the system). -- `USER="Fred" zwift` perfect if your neighbor Fred want's to try zwift, and you don't want to mess up your zwift config. +- `USER="fred" zwift` perfect if your neighbor Fred want's to try zwift, and you don't want to mess up your zwift config. - `NETWORKING="host" zwift` will use host networking which may be needed to have zwift talk to wifi enabled trainers. - `ZWIFT_UID="123" ZWIFT_GID="123" zwift` will run zwift as the given uid and gid. By default zwift runs with the uid and gid of the user that started the container. You should not need to change this except in rare cases. @@ -60,19 +60,39 @@ These environment variables can be used to alter the execution of the zwift bash ## Configuration files -You can also set these in `$HOME/.config/zwift/config` or `$HOME/.config/zwift/$USER-config` to be sourced by the `zwift.sh` -script on execution. +You can also save these in a configuration file that is automatically loaded by the zwift script. -### Example +- `$HOME/.config/zwift/config` +- `$HOME/.config/zwift/$USER-config` -The `$HOME/.config/zwift/config` file could look like: +### Example config file ```bash ZWIFT_USERNAME='user@mail.com' -ZWIFT_PASSWORD='this % is \ a "special" / $(password) with ${characters}, \n is literal and not a newline' ZWIFT_WORKOUT_DIR="$(xdg-user-dir DOCUMENTS)/Zwift/Workouts" ZWIFT_LOG_DIR="$(xdg-user-dir DOCUMENTS)/Zwift/Logs" ZWIFT_SCREENSHOTS_DIR="$(xdg-user-dir PICTURES)/Zwift" NETWORKING="host" ZWIFT_OVERRIDE_GRAPHICS="1" ``` + +### Example: Two Zwift users sharing a single Linux user account + +- The `$HOME/.config/zwift/config` file could look like: + + ```bash + ZWIFT_USERNAME='bob@mail.com' + ZWIFT_PASSWORD='the password for bob' + NETWORKING="host" + ZWIFT_OVERRIDE_GRAPHICS="1" + ``` + +- The `$HOME/.config/zwift/fred-config` file could look like: + + ```bash + ZWIFT_USERNAME='fred@mail.com' + ZWIFT_PASSWORD='the password for fred' + ``` + +- Running `USER="fred" zwift` will first load the `config` file and then the `fred-config` file. The values in the `fred-config` + file will overwrite the values in the `config` file. So the zwift script will use Fred's username and password. From 585fa6cd467f7ed20776b7b403b19ea6a31d37da Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 19:10:33 +0100 Subject: [PATCH 43/65] Try out definition list --- docs/configuration/options.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 185480ef..ebc631c5 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -44,6 +44,29 @@ These environment variables can be used to alter the execution of the zwift bash ### Examples +
+
`DONT_PULL="1" zwift`
+
Will prevent docker/podman pull before launch
+
`DRYRUN="1" zwift`
+
Will print the underlying container run command and exit (no container is started)
+
`INTERACTIVE="1" zwift`
+
Will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the container
+
`CONTAINER_TOOL="docker" zwift`
+
Will launch zwift with docker even if podman is installed
+
`CONTAINER_EXTRA_ARGS="--cpus=1.5"`
+
Will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, this is useful on laptops to + avoid overheating and subsequent throttling of the CPU by the system).
+
`USER="fred" zwift`
+
Perfect if your neighbor Fred want's to try zwift, and you don't want to mess up your zwift config
+
`NETWORKING="host" zwift`
+
Will use host networking which may be needed to have zwift talk to wifi enabled trainers
+
`ZWIFT_UID="123" ZWIFT_GID="123" zwift`
+
Will run zwift as the given uid and gid. By default zwift runs with the uid and gid of the user that started the + container. You should not need to change this except in rare cases.
+
`WINE_EXPERIMENTAL_WAYLAND="1" zwift`
+
This will start zwift using Wayland and not XWayland. It will start full screen windowed
+
+ - `DONT_PULL="1" zwift` will prevent docker/podman pull before launch - `DRYRUN="1" zwift` will print the underlying container run command and exit (no container is started) - `INTERACTIVE="1" zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the From 235122d4a0f84cc596119dec15e24d2b11238fce Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 19:12:24 +0100 Subject: [PATCH 44/65] Remove definition list again --- docs/configuration/options.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index ebc631c5..185480ef 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -44,29 +44,6 @@ These environment variables can be used to alter the execution of the zwift bash ### Examples -
-
`DONT_PULL="1" zwift`
-
Will prevent docker/podman pull before launch
-
`DRYRUN="1" zwift`
-
Will print the underlying container run command and exit (no container is started)
-
`INTERACTIVE="1" zwift`
-
Will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the container
-
`CONTAINER_TOOL="docker" zwift`
-
Will launch zwift with docker even if podman is installed
-
`CONTAINER_EXTRA_ARGS="--cpus=1.5"`
-
Will pass `--cpus=1.5` as extra argument to docker/podman (will use at most 1.5 CPU cores, this is useful on laptops to - avoid overheating and subsequent throttling of the CPU by the system).
-
`USER="fred" zwift`
-
Perfect if your neighbor Fred want's to try zwift, and you don't want to mess up your zwift config
-
`NETWORKING="host" zwift`
-
Will use host networking which may be needed to have zwift talk to wifi enabled trainers
-
`ZWIFT_UID="123" ZWIFT_GID="123" zwift`
-
Will run zwift as the given uid and gid. By default zwift runs with the uid and gid of the user that started the - container. You should not need to change this except in rare cases.
-
`WINE_EXPERIMENTAL_WAYLAND="1" zwift`
-
This will start zwift using Wayland and not XWayland. It will start full screen windowed
-
- - `DONT_PULL="1" zwift` will prevent docker/podman pull before launch - `DRYRUN="1" zwift` will print the underlying container run command and exit (no container is started) - `INTERACTIVE="1" zwift` will force foreground `-it` and set `--entrypoint bash` for step-by-step debugging inside the From 11b0b059715e42bd8e402c32c69ccecc4d085430 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 19:45:08 +0100 Subject: [PATCH 45/65] Add section about syntax --- docs/configuration/options.md | 52 +++++++++++++++++++++++++++++++++++ docs/todo/more.md | 6 ---- 2 files changed, 52 insertions(+), 6 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 185480ef..0eeb1ef9 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -58,6 +58,55 @@ These environment variables can be used to alter the execution of the zwift bash - `WINE_EXPERIMENTAL_WAYLAND="1" zwift` This will start zwift using Wayland and not XWayland. It will start full screen windowed. +## Syntax + +Special characters in the value of environment variables need to be escaped to make sure they are interpreted literally. For +example `ZWIFT_PASSWORD=my password` would cause the `ZWIFT_PASSWORD` variable to have two values `my` and `password` instead +of the single value `my password`. + +{: .important } +> Use single quotes to escape the value of the username and password! +> +> `ZWIFT_USERNAME='user@mail.com'` +> +> `ZWIFT_PASSWORD='my password'` + +{: .important } +> Use double quotes to escape the value of all environment variables except for username and password! +> +> `ZWIFT_SCREENSHOTS_DIR="$(xdg-user-dir PICTURES)/Zwift"` +> +> `DONT_PULL="1"` +> +> `CONTAINER_EXTRA_ARGS="--cups=1.5"` +> +> `...` + +Most environment variables don't have special characters aside from spaces. For those variables is it enough to wrap them in +double quotes. + +Passwords (and to some extend email addresses) can however contain nearly every possible character sequence. Double quotes are +not enough to stop escape sequences and bash code from being substituted. For example writing `MY_PASSWORD="Pa$word\n123"` would +try to substitute `$word` for the value of the variable `word`, which would most likely be empty. It would also replace `\n` +with a new line. This is not desirable. Instead of double quotes, single quotes can be used to prevent this expansion from +happening. Using `MY_PASSWORD='Pa$word\n123'` would treat all characters literally and behave as expected. + +{: .important } +> Since we use single quotes around the password, passwords that contain single quotes still pose an issue. For example +> `bob's excellent pa$$w0rd` would cause all sorts of nasty errors being spit out by the zwift script. Single quotes in the +> password need to be replaced by a different character sequence to make them work. +> +> `MY_PASSWORD='bob'"'"'s excellent pa$$w0rd'` +> +> The sequence is a bit different depending on whether the `'` appears at the start, somewhere in the middle or at the end of the +> password. +> +> For a password with value `p'as`, set `MY_PASSWORD='p'"'"'as'` (replace `'` with `'"'"'`) +> +> For a password with value `'pas`, set `MY_PASSWORD="'"'pas'` (prepend `'pas'` with `"'"`) +> +> For a password with value `'pas`, set `MY_PASSWORD='pas'"'"` (append `'"'` to `'pas'`) + ## Configuration files You can also save these in a configuration file that is automatically loaded by the zwift script. @@ -65,6 +114,9 @@ You can also save these in a configuration file that is automatically loaded by - `$HOME/.config/zwift/config` - `$HOME/.config/zwift/$USER-config` +{: .note } +The same syntax rules apply for the configuration files as for passing environment variables on the command line. + ### Example config file ```bash diff --git a/docs/todo/more.md b/docs/todo/more.md index 7fcf6f91..6cffc3e0 100644 --- a/docs/todo/more.md +++ b/docs/todo/more.md @@ -33,12 +33,6 @@ secret-tool store --label "Zwift password for ${ZWIFT_USERNAME}" application zwi In this case the username should still be saved in the config file and the password will be read upon startup from the keyring and passed as a secret into the container (where it is an environment variable). -{: .warning } -**Do Not Quote the variables or add spaces**: The ID and Password are read as raw format so if you put -`ZWIFT_PASSWORD="password"` it tries to use `"password"` and not just `password`, same for `''`. In addition do not add a space -to the end of the line it will be sent as part of the password or username. This applies to `ZWIFT_USERNAME` and -`ZWIFT_PASSWORD`. - ## Podman Support When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need From b72bb647fad2e9cc98734fa23667b4e5b8f42548 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 19:46:10 +0100 Subject: [PATCH 46/65] Fix markdown linter error --- docs/configuration/options.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 0eeb1ef9..35e06765 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -98,8 +98,8 @@ happening. Using `MY_PASSWORD='Pa$word\n123'` would treat all characters literal > > `MY_PASSWORD='bob'"'"'s excellent pa$$w0rd'` > -> The sequence is a bit different depending on whether the `'` appears at the start, somewhere in the middle or at the end of the -> password. +> The sequence is a bit different depending on whether the `'` appears at the start, somewhere in the middle or at the end of +> the password. > > For a password with value `p'as`, set `MY_PASSWORD='p'"'"'as'` (replace `'` with `'"'"'`) > From e45dfe97ab6de26ca9e3814b0ce4a8f1bb5657f4 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 19:48:53 +0100 Subject: [PATCH 47/65] Use ZWIFT_PASSWORD in MY_PASSWORD in examples --- docs/configuration/options.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 35e06765..f6882ff4 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -86,26 +86,26 @@ Most environment variables don't have special characters aside from spaces. For double quotes. Passwords (and to some extend email addresses) can however contain nearly every possible character sequence. Double quotes are -not enough to stop escape sequences and bash code from being substituted. For example writing `MY_PASSWORD="Pa$word\n123"` would -try to substitute `$word` for the value of the variable `word`, which would most likely be empty. It would also replace `\n` -with a new line. This is not desirable. Instead of double quotes, single quotes can be used to prevent this expansion from -happening. Using `MY_PASSWORD='Pa$word\n123'` would treat all characters literally and behave as expected. +not enough to stop escape sequences and bash code from being substituted. For example writing `ZWIFT_PASSWORD="Pa$word\n123"` +would try to substitute `$word` for the value of the variable `word`, which would most likely be empty. It would also replace +`\n` with a new line. This is not desirable. Instead of double quotes, single quotes can be used to prevent this expansion from +happening. Using `ZWIFT_PASSWORD='Pa$word\n123'` would treat all characters literally and behave as expected. {: .important } > Since we use single quotes around the password, passwords that contain single quotes still pose an issue. For example > `bob's excellent pa$$w0rd` would cause all sorts of nasty errors being spit out by the zwift script. Single quotes in the > password need to be replaced by a different character sequence to make them work. > -> `MY_PASSWORD='bob'"'"'s excellent pa$$w0rd'` +> `ZWIFT_PASSWORD='bob'"'"'s excellent pa$$w0rd'` > > The sequence is a bit different depending on whether the `'` appears at the start, somewhere in the middle or at the end of > the password. > -> For a password with value `p'as`, set `MY_PASSWORD='p'"'"'as'` (replace `'` with `'"'"'`) +> For a password with value `p'as`, set `ZWIFT_PASSWORD='p'"'"'as'` (replace `'` with `'"'"'`) > -> For a password with value `'pas`, set `MY_PASSWORD="'"'pas'` (prepend `'pas'` with `"'"`) +> For a password with value `'pas`, set `ZWIFT_PASSWORD="'"'pas'` (prepend `'pas'` with `"'"`) > -> For a password with value `'pas`, set `MY_PASSWORD='pas'"'"` (append `'"'` to `'pas'`) +> For a password with value `'pas`, set `ZWIFT_PASSWORD='pas'"'"` (append `'"'` to `'pas'`) ## Configuration files From 0c8cd7b12377c5119c7656eb13314abb91b01913 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 19:51:21 +0100 Subject: [PATCH 48/65] Fix example --- docs/configuration/options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index f6882ff4..742c6797 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -105,7 +105,7 @@ happening. Using `ZWIFT_PASSWORD='Pa$word\n123'` would treat all characters lite > > For a password with value `'pas`, set `ZWIFT_PASSWORD="'"'pas'` (prepend `'pas'` with `"'"`) > -> For a password with value `'pas`, set `ZWIFT_PASSWORD='pas'"'"` (append `'"'` to `'pas'`) +> For a password with value `pas'`, set `ZWIFT_PASSWORD='pas'"'"` (append `'"'` to `'pas'`) ## Configuration files From 14652d60169c909dcceceb61f112db40fb7afb74 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 20:00:03 +0100 Subject: [PATCH 49/65] A bit of cleanup --- docs/configuration/options.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 742c6797..a4135167 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -79,8 +79,6 @@ of the single value `my password`. > `DONT_PULL="1"` > > `CONTAINER_EXTRA_ARGS="--cups=1.5"` -> -> `...` Most environment variables don't have special characters aside from spaces. For those variables is it enough to wrap them in double quotes. @@ -94,7 +92,8 @@ happening. Using `ZWIFT_PASSWORD='Pa$word\n123'` would treat all characters lite {: .important } > Since we use single quotes around the password, passwords that contain single quotes still pose an issue. For example > `bob's excellent pa$$w0rd` would cause all sorts of nasty errors being spit out by the zwift script. Single quotes in the -> password need to be replaced by a different character sequence to make them work. +> password need to be replaced by a different character sequence to make them work. If multiple single quotes are present in the +> password, each of them needs to be replaced according to the rules below. > > `ZWIFT_PASSWORD='bob'"'"'s excellent pa$$w0rd'` > From 34b10fc86d8aa5b30210357f6b3e908d6e7475fe Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 20:11:27 +0100 Subject: [PATCH 50/65] Write authentication documentation --- docs/configuration/authentication.md | 23 +++++++++++++++++++++++ docs/todo/more.md | 26 -------------------------- 2 files changed, 23 insertions(+), 26 deletions(-) diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md index a87dc12c..399351b1 100644 --- a/docs/configuration/authentication.md +++ b/docs/configuration/authentication.md @@ -5,3 +5,26 @@ nav_order: 2 --- # Authentication + +## How can I persist my login information so i don't need to login on every startup? + +One way to authenticate through Zwift automatically, is to add the username and password to `$HOME/.config/zwift/config`: + +```bash +ZWIFT_USERNAME='username' +ZWIFT_PASSWORD='password' +``` + +Where `username` is your zwift account email, and `password` your zwift account password, respectively. + +This however has the disadvantage that your password is written in plain text in the config file. Alternatively, instead of +saving your password in the config file, you can store it securely in the secret service keyring like so: + +```bash +secret-tool store --label "Zwift password for ${ZWIFT_USERNAME}" application zwift username ${ZWIFT_USERNAME} +``` + +In this case the username should still be saved in the config file. + +{: .note } +It is recommended to save your password securely in the secret store and add your username to the config file. diff --git a/docs/todo/more.md b/docs/todo/more.md index 6cffc3e0..8c2268a7 100644 --- a/docs/todo/more.md +++ b/docs/todo/more.md @@ -7,32 +7,6 @@ parent: TODO If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or other programs listening on the bus from inhibiting the screen. -## How can I persist my login information so i don't need to login on every startup? - -To authenticate through Zwift automatically simply add the following file `$HOME/.config/zwift/config`: - -```text -ZWIFT_USERNAME=username -ZWIFT_PASSWORD=password -``` - -Where `username` is your zwift account email, and `password` your zwift account password, respectively. - -The credentials will be used to authenticate before launching the zwift app, and the user should be logged in automatically in -the game. - -{: .note } -This will be loaded by `zwift.sh` in cleartext as environment variables into the container. - -Alternatively, instead of saving your password in the file, you can save your password in the secret service keyring like so: - -```text -secret-tool store --label "Zwift password for ${ZWIFT_USERNAME}" application zwift username ${ZWIFT_USERNAME} -``` - -In this case the username should still be saved in the config file and the password will be read upon startup from the keyring -and passed as a secret into the container (where it is an environment variable). - ## Podman Support When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need From 132ba74ccff7687aec0b3c61ce9ec36c04cb2161 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 20:23:01 +0100 Subject: [PATCH 51/65] Create troubleshooting section --- docs/troubleshooting/documents-folder.md | 22 ++++++++ docs/troubleshooting/gnome-not-responding.md | 13 +++++ docs/troubleshooting/index.md | 8 +++ docs/troubleshooting/slow-start.md | 13 +++++ .../wifi-devices.md} | 53 ++----------------- 5 files changed, 60 insertions(+), 49 deletions(-) create mode 100644 docs/troubleshooting/documents-folder.md create mode 100644 docs/troubleshooting/gnome-not-responding.md create mode 100644 docs/troubleshooting/index.md create mode 100644 docs/troubleshooting/slow-start.md rename docs/{todo/troubleshooting.md => troubleshooting/wifi-devices.md} (57%) diff --git a/docs/troubleshooting/documents-folder.md b/docs/troubleshooting/documents-folder.md new file mode 100644 index 00000000..08a0449a --- /dev/null +++ b/docs/troubleshooting/documents-folder.md @@ -0,0 +1,22 @@ +--- +title: Documents Folder Not Writable +parent: Troubleshooting +nav_order: 4 +--- + +# Where are the saves and why do I get a popup can't write to Document Folder? + +This is a hang up from previous versions, mainly with podman. Delete the volumes and after re-creation it should work fine. + +```bash +podman volume rm zwift-xxxxx +``` + +or + +```bash +docker volume rm zwift-xxxxx +``` + +{: .note } +If you see a weird volume e.g. `zwift-naeva` it is a hang up from the past, delete it. diff --git a/docs/troubleshooting/gnome-not-responding.md b/docs/troubleshooting/gnome-not-responding.md new file mode 100644 index 00000000..4c1e3617 --- /dev/null +++ b/docs/troubleshooting/gnome-not-responding.md @@ -0,0 +1,13 @@ +--- +title: Gnome Not Responding +parent: Troubleshooting +nav_order: 2 +--- + +# I sometimes get a popup Not responding why? + +For Gnome it is just timing out before zwift responds, extend the timeout. + +```bash +gsettings set org.gnome.mutter check-alive-timeout 60000 +``` diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md new file mode 100644 index 00000000..8f3cf14f --- /dev/null +++ b/docs/troubleshooting/index.md @@ -0,0 +1,8 @@ +--- +title: Troubleshooting +nav_order: 4 +description: "Solve common issues with Zwift Docker Container" +permalink: /troubleshooting +--- + +# Troubleshooting diff --git a/docs/troubleshooting/slow-start.md b/docs/troubleshooting/slow-start.md new file mode 100644 index 00000000..2bf80023 --- /dev/null +++ b/docs/troubleshooting/slow-start.md @@ -0,0 +1,13 @@ +--- +title: Slow Start +parent: Troubleshooting +nav_order: 3 +--- + +# The container is slow to start, why? + +If your `$(id -u)` or `$(id -g)` is not equal to 1000 then this would cause the zwift container to re-map all files (`chown`, +`chgrp`) within the container so there is no uid/gid conflicts. + +So if speed is a concern of yours, consider changing your user to match the containers uid and gid using `usermod` or contribute +a better solution for handling uid/gid remapping in containers. :smiley: diff --git a/docs/todo/troubleshooting.md b/docs/troubleshooting/wifi-devices.md similarity index 57% rename from docs/todo/troubleshooting.md rename to docs/troubleshooting/wifi-devices.md index 7d6f19f1..f8f2ef61 100644 --- a/docs/todo/troubleshooting.md +++ b/docs/troubleshooting/wifi-devices.md @@ -1,13 +1,10 @@ --- -title: Troubleshooting -nav_order: 4 -parent: TODO +title: WiFi Device Detection +parent: Troubleshooting +nav_order: 1 --- -# Troubleshooting - -
-My WiFi-capable trainer / Zwift Companion App is not detected +# My WiFi-capable trainer / Zwift Companion App is not detected If you have issues with device detection over WiFi/network, the issue may be related to your system's firewall. Some Linux distributions use `firewalld` instead of `ufw`, @@ -65,45 +62,3 @@ to allow multicast traffic on your network instead of disabling it entirely: ```console systemctl restart firewalld ``` - -
- -
-Where are the saves and why do I get a popup can't write to Document Folder? - -This is a hang up from previous versions, mainly with podman. delete the volumes and after re-creation it should work fine. - -```text -podman volume rm zwift-xxxxx -``` - -or - -```text -docker volume rm zwift-xxxxx -``` - -**NOTE**: if you see a weird volume e.g. `zwift-naeva` it is a hang up from the past, delete it. - -
- -
-I sometimes get a popup Not responding why? - -For Gnome it is just timing out before zwift responds, just extend the timeout. - -```text -gsettings set org.gnome.mutter check-alive-timeout 60000 -``` - -
- -
-The container is slow to start, why? - -If your `$(id -u)` or `$(id -g)` is not equal to 1000 then this would cause the zwift container to re-map all files (`chown`, -`chgrp`) within the container so there is no uid/gid conflicts. So if speed is a concern of yours, consider changing your user -to match the containers uid and gid using `usermod` or contribute a better solution for handling uid/gid remapping in containers -:smiley: - -
From 12e81e2af54bb1204238bdf0f82d76bb8f8fac93 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 20:24:37 +0100 Subject: [PATCH 52/65] Update index --- docs/todo/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/todo/index.md b/docs/todo/index.md index 41f4aa2b..0db675cf 100644 --- a/docs/todo/index.md +++ b/docs/todo/index.md @@ -1,6 +1,6 @@ --- title: TODO -nav_order: 4 +nav_order: 5 description: "Stuff that needs to be moved to a proper location in the documentation" permalink: /todo --- From fd6642af0aae2d6d7cedc0f059783a487b64efb5 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Fri, 30 Jan 2026 20:26:20 +0100 Subject: [PATCH 53/65] Minor tweaks --- docs/troubleshooting/wifi-devices.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/troubleshooting/wifi-devices.md b/docs/troubleshooting/wifi-devices.md index f8f2ef61..c424eada 100644 --- a/docs/troubleshooting/wifi-devices.md +++ b/docs/troubleshooting/wifi-devices.md @@ -37,7 +37,7 @@ to allow multicast traffic on your network instead of disabling it entirely: **Via CLI**: - ```console + ```bash nmcli connection modify "" connection.zone home ``` @@ -45,7 +45,7 @@ to allow multicast traffic on your network instead of disabling it entirely: The zone "home" might already be pre-configured with multicast support. If not, manually allow multicast with: - ```console + ```bash firewall-cmd --permanent --zone=home --add-rich-rule='rule family="ipv4" destination address="224.0.0.0/4" protocol value="udp" accept' ``` @@ -53,12 +53,12 @@ to allow multicast traffic on your network instead of disabling it entirely: **Reload configuration** (recommended, no service interruption): - ```console + ```bash firewall-cmd --reload ``` **Restart the service**: - ```console + ```bash systemctl restart firewalld ``` From 921a1ba6de06759d4ab8d8dd20254333480d78e5 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 14:42:58 +0100 Subject: [PATCH 54/65] Make it possible to serve docs website locally --- .github/workflows/github_pages.yaml | 19 +- docs/.gitignore | 15 ++ docs/Gemfile | 14 ++ docs/Gemfile.lock | 330 ++++++++++++++++++++++++++++ docs/_config.yml | 15 +- docs/configuration/index.md | 1 - docs/getting-started/index.md | 1 - docs/index.md | 1 - docs/todo/index.md | 1 - docs/troubleshooting/index.md | 1 - 10 files changed, 386 insertions(+), 12 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index 4b6ad576..21a54a9a 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -11,20 +11,27 @@ permissions: id-token: write concurrency: group: "pages" - cancel-in-progress: false + cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - name: Checkout repository code uses: actions/checkout@v6 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.4' + bundler-cache: true + cache-version: 0 - name: Setup Pages uses: actions/configure-pages@v5 - - name: Build site - uses: actions/jekyll-build-pages@v1 - with: - source: ./docs - destination: ./docs/_site + - name: Build with Jekyll + run: | + cd ./docs + bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production - name: Upload pages artifact uses: actions/upload-pages-artifact@v4 with: diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..f9f1d493 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,15 @@ +# Not sure what a .gitignore is? +# See: https://git-scm.com/docs/gitignore + +# These are directly copied from Jekyll's first-party docs on `.gitignore` files: +# https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control + +# Ignore the default location of the built site, and caches and metadata generated by Jekyll +_site/ +.sass-cache/ +.jekyll-cache/ +.jekyll-metadata + +# Ignore folders generated by Bundler +.bundle/ +vendor/ diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 00000000..c18265ea --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,14 @@ +source 'https://rubygems.org' + +gem "jekyll", "~> 4.4.1" +gem "jekyll-coffeescript" +gem "jekyll-default-layout" +gem "jekyll-gist" +gem "jekyll-github-metadata" +gem "jekyll-optional-front-matter" +gem "jekyll-paginate" +gem "jekyll-readme-index" +gem "jekyll-titles-from-headings" +gem "jekyll-relative-links" +gem "jemoji" +gem "just-the-docs" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 00000000..71723195 --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,330 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (8.1.2) + base64 + bigdecimal + concurrent-ruby (~> 1.0, >= 1.3.1) + connection_pool (>= 2.2.5) + drb + i18n (>= 1.6, < 2) + json + logger (>= 1.4.2) + minitest (>= 5.1) + securerandom (>= 0.3) + tzinfo (~> 2.0, >= 2.0.5) + uri (>= 0.13.1) + addressable (2.8.8) + public_suffix (>= 2.0.2, < 8.0) + base64 (0.3.0) + bigdecimal (4.0.1) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.12.2) + colorator (1.1.0) + concurrent-ruby (1.3.6) + connection_pool (3.0.2) + csv (3.3.5) + drb (2.2.3) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + execjs (2.10.0) + faraday (2.14.0) + faraday-net_http (>= 2.0, < 3.5) + json + logger + faraday-net_http (3.4.2) + net-http (~> 0.5) + ffi (1.17.3-aarch64-linux-gnu) + ffi (1.17.3-aarch64-linux-musl) + ffi (1.17.3-arm-linux-gnu) + ffi (1.17.3-arm-linux-musl) + ffi (1.17.3-arm64-darwin) + ffi (1.17.3-x86_64-darwin) + ffi (1.17.3-x86_64-linux-gnu) + ffi (1.17.3-x86_64-linux-musl) + forwardable-extended (2.6.0) + gemoji (4.1.0) + google-protobuf (4.33.4) + bigdecimal + rake (>= 13) + google-protobuf (4.33.4-aarch64-linux-gnu) + bigdecimal + rake (>= 13) + google-protobuf (4.33.4-aarch64-linux-musl) + bigdecimal + rake (>= 13) + google-protobuf (4.33.4-arm64-darwin) + bigdecimal + rake (>= 13) + google-protobuf (4.33.4-x86_64-darwin) + bigdecimal + rake (>= 13) + google-protobuf (4.33.4-x86_64-linux-gnu) + bigdecimal + rake (>= 13) + google-protobuf (4.33.4-x86_64-linux-musl) + bigdecimal + rake (>= 13) + html-pipeline (2.14.3) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.8.1) + i18n (1.14.8) + concurrent-ruby (~> 1.0) + jekyll (4.4.1) + addressable (~> 2.4) + base64 (~> 0.2) + colorator (~> 1.0) + csv (~> 3.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + json (~> 2.6) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (~> 0.3, >= 0.3.6) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-coffeescript (2.0.0) + coffee-script (~> 2.2) + coffee-script-source (~> 1.12) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.16.1) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-relative-links (0.7.0) + jekyll (>= 3.3, < 5.0) + jekyll-sass-converter (3.1.0) + sass-embedded (~> 1.75) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.13.0) + gemoji (>= 3, < 5) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + json (2.18.0) + just-the-docs (0.12.0) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.10.0) + logger + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) + mercenary (0.3.6) + minitest (6.0.1) + prism (~> 1.5) + net-http (0.9.1) + uri (>= 0.11.1) + nokogiri (1.19.0-aarch64-linux-gnu) + racc (~> 1.4) + nokogiri (1.19.0-aarch64-linux-musl) + racc (~> 1.4) + nokogiri (1.19.0-arm-linux-gnu) + racc (~> 1.4) + nokogiri (1.19.0-arm-linux-musl) + racc (~> 1.4) + nokogiri (1.19.0-arm64-darwin) + racc (~> 1.4) + nokogiri (1.19.0-x86_64-darwin) + racc (~> 1.4) + nokogiri (1.19.0-x86_64-linux-gnu) + racc (~> 1.4) + nokogiri (1.19.0-x86_64-linux-musl) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + prism (1.9.0) + public_suffix (5.1.1) + racc (1.8.1) + rake (13.3.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.4.4) + rouge (3.30.0) + safe_yaml (1.0.5) + sass-embedded (1.97.3-aarch64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.97.3-aarch64-linux-musl) + google-protobuf (~> 4.31) + sass-embedded (1.97.3-arm-linux-gnueabihf) + google-protobuf (~> 4.31) + sass-embedded (1.97.3-arm-linux-musleabihf) + google-protobuf (~> 4.31) + sass-embedded (1.97.3-arm64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.97.3-x86_64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.97.3-x86_64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.97.3-x86_64-linux-musl) + google-protobuf (~> 4.31) + sawyer (0.9.3) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + securerandom (0.4.1) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + tzinfo (2.0.6) + concurrent-ruby (~> 1.0) + unicode-display_width (2.6.0) + uri (1.1.1) + webrick (1.9.2) + +PLATFORMS + aarch64-linux-gnu + aarch64-linux-musl + arm-linux-gnu + arm-linux-musl + arm64-darwin + x86_64-darwin + x86_64-linux-gnu + x86_64-linux-musl + +DEPENDENCIES + jekyll (~> 4.4.1) + jekyll-coffeescript + jekyll-default-layout + jekyll-gist + jekyll-github-metadata + jekyll-optional-front-matter + jekyll-paginate + jekyll-readme-index + jekyll-relative-links + jekyll-titles-from-headings + jemoji + just-the-docs + +CHECKSUMS + activesupport (8.1.2) sha256=88842578ccd0d40f658289b0e8c842acfe9af751afee2e0744a7873f50b6fdae + addressable (2.8.8) sha256=7c13b8f9536cf6364c03b9d417c19986019e28f7c00ac8132da4eb0fe393b057 + base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b + bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7 + coffee-script (2.4.1) sha256=82fe281e11b93c8117b98c5ea8063e71741870f1c4fbb27177d7d6333dd38765 + coffee-script-source (1.12.2) sha256=e12b16fd8927fbbf8b87cb2e9a85a6cf457c6881cc7ff8b1af15b31f70da07a4 + colorator (1.1.0) sha256=e2f85daf57af47d740db2a32191d1bdfb0f6503a0dfbc8327d0c9154d5ddfc38 + concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab + connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a + csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f + drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373 + em-websocket (0.5.3) sha256=f56a92bde4e6cb879256d58ee31f124181f68f8887bd14d53d5d9a292758c6a8 + eventmachine (1.2.7) sha256=994016e42aa041477ba9cff45cbe50de2047f25dd418eba003e84f0d16560972 + execjs (2.10.0) sha256=6bcb8be8f0052ff9d370b65d1c080f2406656e150452a0abdb185a133048450d + faraday (2.14.0) sha256=8699cfe5d97e55268f2596f9a9d5a43736808a943714e3d9a53e6110593941cd + faraday-net_http (3.4.2) sha256=f147758260d3526939bf57ecf911682f94926a3666502e24c69992765875906c + ffi (1.17.3-aarch64-linux-gnu) sha256=28ad573df26560f0aedd8a90c3371279a0b2bd0b4e834b16a2baa10bd7a97068 + ffi (1.17.3-aarch64-linux-musl) sha256=020b33b76775b1abacc3b7d86b287cef3251f66d747092deec592c7f5df764b2 + ffi (1.17.3-arm-linux-gnu) sha256=5bd4cea83b68b5ec0037f99c57d5ce2dd5aa438f35decc5ef68a7d085c785668 + ffi (1.17.3-arm-linux-musl) sha256=0d7626bb96265f9af78afa33e267d71cfef9d9a8eb8f5525344f8da6c7d76053 + ffi (1.17.3-arm64-darwin) sha256=0c690555d4cee17a7f07c04d59df39b2fba74ec440b19da1f685c6579bb0717f + ffi (1.17.3-x86_64-darwin) sha256=1f211811eb5cfaa25998322cdd92ab104bfbd26d1c4c08471599c511f2c00bb5 + ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f + ffi (1.17.3-x86_64-linux-musl) sha256=086b221c3a68320b7564066f46fed23449a44f7a1935f1fe5a245bd89d9aea56 + forwardable-extended (2.6.0) sha256=1bec948c469bbddfadeb3bd90eb8c85f6e627a412a3e852acfd7eaedbac3ec97 + gemoji (4.1.0) sha256=734434020cbe964ea9d19086798797a47d23a170892de0ce55b74aa65d2ddc1a + google-protobuf (4.33.4) sha256=86921935b023ed0d872d6e84382e79016c91689be0520d614c74426778f13c16 + google-protobuf (4.33.4-aarch64-linux-gnu) sha256=7b091ec8a80520738a4dbff59458e2a7ed4304d7fc20fd779b3d019ff52fbead + google-protobuf (4.33.4-aarch64-linux-musl) sha256=c017371e6fe8144285a3dd5d1ae2776f92892f7455bea26537f0f3072b6d894c + google-protobuf (4.33.4-arm64-darwin) sha256=63bb57e3d7108986f961546a536adaa38bd9ab5b1ebc39a1741a16c6eba3e869 + google-protobuf (4.33.4-x86_64-darwin) sha256=72906abcb572b324eba760b0abdbb827ab781b8e26f718fa3f7f49485295c8d3 + google-protobuf (4.33.4-x86_64-linux-gnu) sha256=a8cff953d742bc804ece78bd96e82d88cf65a7d8c1910e045359e2f53074e55d + google-protobuf (4.33.4-x86_64-linux-musl) sha256=265e6e5bbcc0ba1367268739e31c4cc84ff310b56e8d738d2a3245b5cccfc2e7 + html-pipeline (2.14.3) sha256=8a1d4d7128b2141913387cac0f8ba898bb6812557001acc0c2b46910f59413a0 + http_parser.rb (0.8.1) sha256=9ae8df145b39aa5398b2f90090d651c67bd8e2ebfe4507c966579f641e11097a + i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5 + jekyll (4.4.1) sha256=4c1144d857a5b2b80d45b8cf5138289579a9f8136aadfa6dd684b31fe2bc18c1 + jekyll-coffeescript (2.0.0) sha256=329c72fb62843056a5d6711514d4ff7f17a799169e88167d1d3a83ea1698d29d + jekyll-default-layout (0.1.5) sha256=c626be4e4a5deafca123539da2cd22ff873be350cafd4da134039efdf24320af + jekyll-gist (1.5.0) sha256=495b6483552a3e2975a2752964ea7acddd545bc6e13ce2be15a50cec8d4c9f0f + jekyll-github-metadata (2.16.1) sha256=4cf29988bdaf24774a7bc07fae71e54424ddfaa2895f742d8fa3036d0db65b4c + jekyll-include-cache (0.2.1) sha256=c7d4b9e551732a27442cb2ce853ba36a2f69c66603694b8c1184c99ab1a1a205 + jekyll-optional-front-matter (0.3.2) sha256=ecdc061d711472469fcf04da617653b553e914c038a17df3b6a5f6f92aeb761b + jekyll-paginate (1.1.0) sha256=880aadf4b02529a93541d508c5cbb744f014cbfc071d0263a31f25ec9066eb64 + jekyll-readme-index (0.3.0) sha256=d74cc4de46b2d350229be7409495149e656a31fb5a5fe3fe6135dbf7435e1e32 + jekyll-relative-links (0.7.0) sha256=831e54c348eeae751845c0d4ac4b244bd73b664341f0e8c9f1803b16f4570835 + jekyll-sass-converter (3.1.0) sha256=83925d84f1d134410c11d0c6643b0093e82e3a3cf127e90757a85294a3862443 + jekyll-seo-tag (2.8.0) sha256=3f2ed1916d56f14ebfa38e24acde9b7c946df70cb183af2cb5f0598f21ae6818 + jekyll-titles-from-headings (0.5.3) sha256=77366754e361ea7b5d87881f5b1380835f5ce910c240a4d9ac2d7afe86d28481 + jekyll-watch (2.2.1) sha256=bc44ed43f5e0a552836245a54dbff3ea7421ecc2856707e8a1ee203a8387a7e1 + jemoji (0.13.0) sha256=5d4c3e8e2cbbb2b73997c31294f6f70c94e4d4fade039373e86835bcf5529e7c + json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505 + just-the-docs (0.12.0) sha256=15f2839ac9082898d60f33b978aa6f8e46fc50ba8fac20ae7a7f0e1fb295523e + kramdown (2.4.0) sha256=b62e5bcbd6ea20c7a6730ebbb2a107237856e14f29cebf5b10c876cc1a2481c5 + kramdown-parser-gfm (1.1.0) sha256=fb39745516427d2988543bf01fc4cf0ab1149476382393e0e9c48592f6581729 + liquid (4.0.4) sha256=4fcfebb1a045e47918388dbb7a0925e7c3893e58d2bd6c3b3c73ec17a2d8fdb3 + listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2 + logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203 + mercenary (0.3.6) sha256=2a084b18f5692c86a633e185d5311ba6d11fc46c802eb414ae05368178078a82 + minitest (6.0.1) sha256=7854c74f48e2e975969062833adc4013f249a4b212f5e7b9d5c040bf838d54bb + net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996 + nokogiri (1.19.0-aarch64-linux-gnu) sha256=11a97ecc3c0e7e5edcf395720b10860ef493b768f6aa80c539573530bc933767 + nokogiri (1.19.0-aarch64-linux-musl) sha256=eb70507f5e01bc23dad9b8dbec2b36ad0e61d227b42d292835020ff754fb7ba9 + nokogiri (1.19.0-arm-linux-gnu) sha256=572a259026b2c8b7c161fdb6469fa2d0edd2b61cd599db4bbda93289abefbfe5 + nokogiri (1.19.0-arm-linux-musl) sha256=23ed90922f1a38aed555d3de4d058e90850c731c5b756d191b3dc8055948e73c + nokogiri (1.19.0-arm64-darwin) sha256=0811dfd936d5f6dd3f6d32ef790568bf29b2b7bead9ba68866847b33c9cf5810 + nokogiri (1.19.0-x86_64-darwin) sha256=1dad56220b603a8edb9750cd95798bffa2b8dd9dd9aa47f664009ee5b43e3067 + nokogiri (1.19.0-x86_64-linux-gnu) sha256=f482b95c713d60031d48c44ce14562f8d2ce31e3a9e8dd0ccb131e9e5a68b58c + nokogiri (1.19.0-x86_64-linux-musl) sha256=1c4ca6b381622420073ce6043443af1d321e8ed93cc18b08e2666e5bd02ffae4 + octokit (4.25.1) sha256=c02092ee82dcdfe84db0e0ea630a70d32becc54245a4f0bacfd21c010df09b96 + pathutil (0.16.2) sha256=e43b74365631cab4f6d5e4228f812927efc9cb2c71e62976edcb252ee948d589 + prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85 + public_suffix (5.1.1) sha256=250ec74630d735194c797491c85e3c6a141d7b5d9bd0b66a3fa6268cf67066ed + racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f + rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c + rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe + rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e + rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142 + rouge (3.30.0) sha256=a3d353222aa72e49e2c86726c0bcfd719f82592f57d494474655f48e669eceb6 + safe_yaml (1.0.5) sha256=a6ac2d64b7eb027bdeeca1851fe7e7af0d668e133e8a88066a0c6f7087d9f848 + sass-embedded (1.97.3-aarch64-linux-gnu) sha256=81915bb19ce7e224eae534e75e828f4ab5acddcb17e54da0b5ef91d932462836 + sass-embedded (1.97.3-aarch64-linux-musl) sha256=508c92fa2f9e58f9072325e02f011bd22c7e428465c67fafaee570d0bc40563b + sass-embedded (1.97.3-arm-linux-gnueabihf) sha256=ce443b57f3d7f03740267cf0f2cdff13e8055dd5938488967746f29f230222da + sass-embedded (1.97.3-arm-linux-musleabihf) sha256=be3972424616f916ce1f4f41228266d57339e490dfd7ca0cea5588579564d4c0 + sass-embedded (1.97.3-arm64-darwin) sha256=8897d3503efe75c30584070a7104095545f5157665029aeb9bff3fa533a73861 + sass-embedded (1.97.3-x86_64-darwin) sha256=578f167907ee2a4d355a5a40bcf35d2e3eb90c87008dcd9ce31a2c4a877697f6 + sass-embedded (1.97.3-x86_64-linux-gnu) sha256=173a4d0dbe2fffdf7482bd3e82fb597dfc658c18d1e8fd746aa7d5077ed4e850 + sass-embedded (1.97.3-x86_64-linux-musl) sha256=fcc0dcb253ef174ea25283f8781ce9ce95a492663f4bdbb1d66bfae99267a9f7 + sawyer (0.9.3) sha256=0d0f19298408047037638639fe62f4794483fb04320269169bd41af2bdcf5e41 + securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1 + terminal-table (3.0.2) sha256=f951b6af5f3e00203fb290a669e0a85c5dd5b051b3b023392ccfd67ba5abae91 + tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b + unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a + uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6 + webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131 + +BUNDLED WITH + 4.0.5 diff --git a/docs/_config.yml b/docs/_config.yml index 06a79472..421f9093 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,5 +1,6 @@ title: netbrain/zwift description: Easily Zwift on Linux +theme: just-the-docs repository: netbrain/zwift color_scheme: dark permalink: pretty @@ -8,10 +9,10 @@ back_to_top_text: "Back to top" aux_links: "netbrain/zwift on GitHub": - "https://github.com/netbrain/zwift" +nav_enabled: true nav_external_links: - title: netbrain/zwift on GitHub url: https://github.com/netbrain/zwift -remote_theme: just-the-docs/just-the-docs@v0.12.0 callouts: highlight: color: yellow @@ -28,4 +29,16 @@ callouts: title: Warning color: red plugins: + - jekyll-coffeescript + - jekyll-default-layout + - jekyll-gist + - jekyll-github-metadata + - jekyll-optional-front-matter + - jekyll-paginate + - jekyll-readme-index + - jekyll-titles-from-headings + - jekyll-relative-links - jemoji +sass: + quiet_deps: true # https://github.com/just-the-docs/just-the-docs/issues/1541 + silence_deprecations: ['import'] # https://github.com/just-the-docs/just-the-docs/issues/1607 diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 0b17787e..64440748 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -2,7 +2,6 @@ title: Configuration nav_order: 3 description: "Learn how to set up and run Zwift on Linux using Podman or Docker" -permalink: /configuration --- # Configuration diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index bb22f7ca..4107fc33 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -2,7 +2,6 @@ title: Getting Started nav_order: 2 description: "Learn how to set up and run Zwift on Linux using Podman or Docker" -permalink: /getting-started --- # Getting Started with Zwift Docker Container diff --git a/docs/index.md b/docs/index.md index 304f3314..9aa2c6bd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,6 @@ title: Home layout: home nav_order: 1 description: "Easily Zwift on Linux!" -permalink: / --- # netbrain/zwift diff --git a/docs/todo/index.md b/docs/todo/index.md index 0db675cf..4558195d 100644 --- a/docs/todo/index.md +++ b/docs/todo/index.md @@ -2,7 +2,6 @@ title: TODO nav_order: 5 description: "Stuff that needs to be moved to a proper location in the documentation" -permalink: /todo --- # TODO diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md index 8f3cf14f..643b78ee 100644 --- a/docs/troubleshooting/index.md +++ b/docs/troubleshooting/index.md @@ -2,7 +2,6 @@ title: Troubleshooting nav_order: 4 description: "Solve common issues with Zwift Docker Container" -permalink: /troubleshooting --- # Troubleshooting From 6e71119fd2857d586dba4f5a79482cde7057c526 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 14:44:19 +0100 Subject: [PATCH 55/65] Add missing bundle install --- .github/workflows/github_pages.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index 21a54a9a..39fdb825 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -29,6 +29,7 @@ jobs: - name: Build with Jekyll run: | cd ./docs + bundle install bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" env: JEKYLL_ENV: production From d76b130014eba09d249ed70af870288221ae8b26 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 14:46:00 +0100 Subject: [PATCH 56/65] Also regenerate github pages if workflow changed --- .github/workflows/github_pages.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index 39fdb825..c8e3120b 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -3,6 +3,7 @@ on: push: branches: ["gp-docs"] paths: + - '.github/workflows/github_pages.yaml' - 'docs/**' workflow_dispatch: permissions: From 58f06b1ff2102092f04529efc79f19e8929db32a Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 14:52:05 +0100 Subject: [PATCH 57/65] Try empty base url --- .github/workflows/github_pages.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index c8e3120b..9e06b09a 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -31,7 +31,7 @@ jobs: run: | cd ./docs bundle install - bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + bundle exec jekyll build env: JEKYLL_ENV: production - name: Upload pages artifact From 1eaa18b4a0f55aa704b8867b5c88a4ddf4355941 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 14:56:31 +0100 Subject: [PATCH 58/65] Echo base_path for testing --- .github/workflows/github_pages.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index 9e06b09a..4fa2ab9e 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -29,9 +29,10 @@ jobs: uses: actions/configure-pages@v5 - name: Build with Jekyll run: | + echo "${{ steps.pages.outputs.base_path }}" cd ./docs bundle install - bundle exec jekyll build + bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" env: JEKYLL_ENV: production - name: Upload pages artifact From 426a8112b06f6e830b15b8a25dc06bead4b58286 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 15:00:59 +0100 Subject: [PATCH 59/65] Set working directory --- .github/workflows/github_pages.yaml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index 4fa2ab9e..14cffbe2 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -16,6 +16,9 @@ concurrency: jobs: build: runs-on: ubuntu-latest + defaults: + run: + working-directory: docs steps: - name: Checkout repository code uses: actions/checkout@v6 @@ -25,12 +28,11 @@ jobs: ruby-version: '3.4' bundler-cache: true cache-version: 0 + working-directory: '${{ github.workspace }}/docs' - name: Setup Pages uses: actions/configure-pages@v5 - name: Build with Jekyll run: | - echo "${{ steps.pages.outputs.base_path }}" - cd ./docs bundle install bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" env: @@ -38,7 +40,7 @@ jobs: - name: Upload pages artifact uses: actions/upload-pages-artifact@v4 with: - path: ./docs/_site + path: docs/_site deploy: runs-on: ubuntu-latest needs: build From bb4ba93df14bc21e0a4e38e8918463b303a95c03 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 15:01:50 +0100 Subject: [PATCH 60/65] Add missing step id --- .github/workflows/github_pages.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index 14cffbe2..b717f106 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -30,6 +30,7 @@ jobs: cache-version: 0 working-directory: '${{ github.workspace }}/docs' - name: Setup Pages + id: pages uses: actions/configure-pages@v5 - name: Build with Jekyll run: | From 1760d9d746b10fe27a8cfb188dbc3341c2b5c950 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 15:07:07 +0100 Subject: [PATCH 61/65] Remove unused callout types --- docs/_config.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 421f9093..995a523b 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -14,14 +14,9 @@ nav_external_links: - title: netbrain/zwift on GitHub url: https://github.com/netbrain/zwift callouts: - highlight: - color: yellow important: title: Important color: yellow - new: - title: New - color: green note: title: Note color: yellow From 2b1e097759236a60de2ee9b715117ac882a4a496 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 15:16:00 +0100 Subject: [PATCH 62/65] Cleanup --- .github/workflows/github_pages.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml index b717f106..57e0f383 100644 --- a/.github/workflows/github_pages.yaml +++ b/.github/workflows/github_pages.yaml @@ -1,7 +1,8 @@ name: Build Jekyll site on: push: - branches: ["gp-docs"] + branches: + - 'gp-docs' paths: - '.github/workflows/github_pages.yaml' - 'docs/**' From fe7574b08493d47c6201417b55deb7b2e14f8c93 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 15:33:50 +0100 Subject: [PATCH 63/65] Add documentation how to connect devices --- docs/getting-started/installation.md | 7 ++++++ docs/getting-started/prerequisites.md | 6 +++++ docs/getting-started/setup.md | 16 +++++++++++++ docs/todo/more.md | 34 --------------------------- 4 files changed, 29 insertions(+), 34 deletions(-) create mode 100644 docs/getting-started/setup.md diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 1f533db3..8453831f 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -38,3 +38,10 @@ This script will: ```bash docker pull netbrain/zwift:$VERSION # or simply latest ``` + +## How can I update Zwift? + +The `zwift.sh` script will update zwift by checking for new image versions on every launch, however if you are not using this +then you will have to pull `netbrain/zwift:latest` from time to time in order to be on the latest version. + +There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md index 17b73638..00341d35 100644 --- a/docs/getting-started/prerequisites.md +++ b/docs/getting-started/prerequisites.md @@ -41,3 +41,9 @@ Ubuntu 22.04 and related builds such as PopOS! 22.04. {: .note } **Podman and NVIDIA Container Toolkit before v1.18.0**: The cdi specification file needs to be generated manually each time the NVIDIA driver is updated using the following command: `sudo nvidia-ctk cdi generate --output=/var/run/cdi/nvidia.yaml` + +{: .note } +> If you're running Docker with cdi and Zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` +> (instead of `"--gpus=all"`). +> +> See for context. diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md new file mode 100644 index 00000000..3dfdb666 --- /dev/null +++ b/docs/getting-started/setup.md @@ -0,0 +1,16 @@ +--- +title: Connecting Devices +parent: Getting Started +nav_order: 3 +--- + +# How do I connect my trainer, heart rate monitor, etc? + +You can [use your phone as a bridge](https://support.zwift.com/using-the-zwift-companion-app-Hybn8qzPr). + +For example, your Wahoo Kickr and Apple Watch connect to the Zwift Companion app on your iPhone; then the Companion app connects +over wifi to your PC running Zwift. + +{: .note } +If you are using a direct connect (wifi or ethernet) enabled trainer, you may need to set `NETWORKING="host"` for Zwift to be +able to communicate to the device. diff --git a/docs/todo/more.md b/docs/todo/more.md index 8c2268a7..55a40b39 100644 --- a/docs/todo/more.md +++ b/docs/todo/more.md @@ -21,13 +21,6 @@ From Podman 4.3 this became automatic by providing the Container UID/GID and pod NOTE: Using ZWIFT_UID/GID will only work if the user starting podman has access to the `/run/user/$ZWIFT_UID` resources and does not work the same way as in Docker so is not supported. -## How do I connect my trainer, heart rate monitor, etc? - -You can [use your phone as a bridge](https://support.zwift.com/using-the-zwift-companion-app-Hybn8qzPr). - -For example, your Wahoo Kickr and Apple Watch connect to the Zwift Companion app on your iPhone; then the Companion app connects -over wifi to your PC running Zwift. - ## How can I add custom .zwo files? You can map the zwift Workout folder using the environment variable `ZWIFT_WORKOUT_DIR`, for example if your workout directory @@ -50,30 +43,3 @@ To add a new workout just copy the zwo file to this directory {: .note } Deleting files from the directory will not delete them, they will be re-added when re-starting zwift, you must delete from the zwift menu - -## How can I build the image myself? - -```console -./bin/build-image.sh -``` - -## How can I fetch the image from docker hub? - - - -```console -docker pull netbrain/zwift:$VERSION # or simply latest -``` - -## How can I update Zwift? - -The `zwift.sh` script will update zwift by checking for new image versions on every launch, however if you are not using this -then you will have to pull `netbrain/zwift:latest` from time to time in order to be on the latest version. - -There is a github action in place that will update zwift on a scheduled basis and publish new versions to docker hub. - -{: .note } -> If you're running Docker with CDI and Zwift fails to launch, try the long form `VGA_DEVICE_FLAG="--device=nvidia.com/gpu=all"` -> (instead of `"--gpus=all"`). -> -> See for context. From 37ea1163ce8b17070f863ac88cb994e7222e08b0 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 15:42:00 +0100 Subject: [PATCH 64/65] Create advanced documentation section --- .../more.md => advanced/custom-workouts.md} | 25 +++---------------- docs/advanced/index.md | 7 ++++++ docs/{todo => advanced}/nixos.md | 4 +-- docs/advanced/podman-support.md | 21 ++++++++++++++++ docs/advanced/screensaver.md | 10 ++++++++ docs/todo/index.md | 7 ------ 6 files changed, 44 insertions(+), 30 deletions(-) rename docs/{todo/more.md => advanced/custom-workouts.md} (50%) create mode 100644 docs/advanced/index.md rename docs/{todo => advanced}/nixos.md (99%) create mode 100644 docs/advanced/podman-support.md create mode 100644 docs/advanced/screensaver.md delete mode 100644 docs/todo/index.md diff --git a/docs/todo/more.md b/docs/advanced/custom-workouts.md similarity index 50% rename from docs/todo/more.md rename to docs/advanced/custom-workouts.md index 55a40b39..56e09f5f 100644 --- a/docs/todo/more.md +++ b/docs/advanced/custom-workouts.md @@ -1,27 +1,10 @@ --- -title: More stuff -nav_order: 5 -parent: TODO +title: Custom Workouts +nav_order: 1 +parent: Advanced --- -If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or -other programs listening on the bus from inhibiting the screen. - -## Podman Support - -When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need -to map the container id 1000 to the host id using `uidmap` and `gidmap`. - -For example if the host uid/gid is 1001/1001 then we need to map the host resources from `/run/user/1001` to the container -resource `/run/user/1000` and map the user and group id's the same. This had to be done manually on the host podman start using -`--uidmap` and `--gidmap` (not covered here). - -From Podman 4.3 this became automatic by providing the Container UID/GID and podman automatically sets up this mapping. - -NOTE: Using ZWIFT_UID/GID will only work if the user starting podman has access to the `/run/user/$ZWIFT_UID` resources and does -not work the same way as in Docker so is not supported. - -## How can I add custom .zwo files? +# How can I add custom .zwo files? You can map the zwift Workout folder using the environment variable `ZWIFT_WORKOUT_DIR`, for example if your workout directory is in `$HOME/zwift_workouts` then you would provide the environment variable `ZWIFT_WORKOUT_DIR="$HOME/zwift_workouts"`. diff --git a/docs/advanced/index.md b/docs/advanced/index.md new file mode 100644 index 00000000..4811038e --- /dev/null +++ b/docs/advanced/index.md @@ -0,0 +1,7 @@ +--- +title: Advanced +nav_order: 5 +description: "More advanced use cases" +--- + +# Advanced diff --git a/docs/todo/nixos.md b/docs/advanced/nixos.md similarity index 99% rename from docs/todo/nixos.md rename to docs/advanced/nixos.md index 1eddca31..cebc00a6 100644 --- a/docs/todo/nixos.md +++ b/docs/advanced/nixos.md @@ -1,7 +1,7 @@ --- title: NixOS -parent: TODO -nav_order: 3 +parent: Advanced +nav_order: 2 --- # NixOS diff --git a/docs/advanced/podman-support.md b/docs/advanced/podman-support.md new file mode 100644 index 00000000..5273836f --- /dev/null +++ b/docs/advanced/podman-support.md @@ -0,0 +1,21 @@ +--- +title: Podman Support +parent: Advanced +nav_order: 3 +--- + +# Podman Support + +When running Zwift with podman, the user and group in the container is 1000 (user). To access the resources on the host we need +to map the container id 1000 to the host id using `uidmap` and `gidmap`. + +{: .note } +From Podman 4.3 this became automatic by providing the Container UID/GID and podman automatically sets up this mapping. + +For example if the host uid/gid is 1001/1001 then we need to map the host resources from `/run/user/1001` to the container +resource `/run/user/1000` and map the user and group id's the same. This had to be done manually on the host podman start using +`--uidmap` and `--gidmap` (not covered here). + +{: .warning } +Using ZWIFT_UID/GID will only work if the user starting podman has access to the `/run/user/$ZWIFT_UID` resources and does +not work the same way as in Docker so is not supported. diff --git a/docs/advanced/screensaver.md b/docs/advanced/screensaver.md new file mode 100644 index 00000000..eb214843 --- /dev/null +++ b/docs/advanced/screensaver.md @@ -0,0 +1,10 @@ +--- +title: Inhibiting Screensaver +parent: Advanced +nav_order: 4 +--- + +# Inhibiting the Screensaver + +If `dbus` is available through a unix socket, the screensaver will be inhibited every 30 seconds to prevent `xscreensaver` or +other programs listening on the bus from inhibiting the screen. diff --git a/docs/todo/index.md b/docs/todo/index.md deleted file mode 100644 index 4558195d..00000000 --- a/docs/todo/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: TODO -nav_order: 5 -description: "Stuff that needs to be moved to a proper location in the documentation" ---- - -# TODO From 24e441ce4846255047524c3a240272918db76106 Mon Sep 17 00:00:00 2001 From: Glenn Van Loon Date: Sun, 1 Feb 2026 15:48:36 +0100 Subject: [PATCH 65/65] Move manual installation to advanced --- docs/advanced/manual-installation.md | 21 +++++++++++++++++++++ docs/getting-started/installation.md | 18 +----------------- 2 files changed, 22 insertions(+), 17 deletions(-) create mode 100644 docs/advanced/manual-installation.md diff --git a/docs/advanced/manual-installation.md b/docs/advanced/manual-installation.md new file mode 100644 index 00000000..1963e6ef --- /dev/null +++ b/docs/advanced/manual-installation.md @@ -0,0 +1,21 @@ +--- +title: Manual Installation +parent: Advanced +nav_order: 5 +--- + +# Manual Installation Steps + +## How can I build the image myself? + +```bash +./bin/build-image.sh +``` + +## How can I fetch the image from docker hub? + + + +```bash +docker pull netbrain/zwift:$VERSION # or simply latest +``` diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 8453831f..77cd474e 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -6,7 +6,7 @@ nav_order: 2 # Installation Methods -## Automatic Installation Script +## Automatic Installation ### One-Line Installation @@ -23,22 +23,6 @@ This script will: - Add zwift command to your system path - Create desktop shortcut -## Manual Installation Steps - -### How can I build the image myself? - -```bash -./bin/build-image.sh -``` - -### How can I fetch the image from docker hub? - - - -```bash -docker pull netbrain/zwift:$VERSION # or simply latest -``` - ## How can I update Zwift? The `zwift.sh` script will update zwift by checking for new image versions on every launch, however if you are not using this