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 6e8ed367..322a487e 100644 --- a/.config/.markdownlint-cli2.jsonc +++ b/.config/.markdownlint-cli2.jsonc @@ -10,10 +10,13 @@ "no-duplicate-heading": { "siblings_only": true }, - "no-inline-html": false + "no-inline-html": false, + "single-title": { + "front_matter_title": "" + } }, "gitignore": true, "globs": [ - "README.md" + "**/*.md" ] } 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. diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml new file mode 100644 index 00000000..57e0f383 --- /dev/null +++ b/.github/workflows/github_pages.yaml @@ -0,0 +1,55 @@ +name: Build Jekyll site +on: + push: + branches: + - 'gp-docs' + paths: + - '.github/workflows/github_pages.yaml' + - 'docs/**' + workflow_dispatch: +permissions: + contents: read + pages: write + id-token: write +concurrency: + group: "pages" + cancel-in-progress: true +jobs: + build: + runs-on: ubuntu-latest + defaults: + run: + working-directory: docs + 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 + working-directory: '${{ github.workspace }}/docs' + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + run: | + bundle install + 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: + 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/.github/workflows/lint_readme.yaml b/.github/workflows/lint_markdown.yaml similarity index 77% rename from .github/workflows/lint_readme.yaml rename to .github/workflows/lint_markdown.yaml index ff5d045a..7b13c07a 100644 --- a/.github/workflows/lint_readme.yaml +++ b/.github/workflows/lint_markdown.yaml @@ -2,27 +2,27 @@ name: Validate markdown on: pull_request: paths: - - 'README.md' + - '**.md' push: paths: - - 'README.md' + - '**.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' diff --git a/README.md b/README.md index 2d74a18c..91f51a5b 100644 --- a/README.md +++ b/README.md @@ -16,28 +16,27 @@ 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 -> :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 +### 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 +44,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/.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 new file mode 100644 index 00000000..995a523b --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,39 @@ +title: netbrain/zwift +description: Easily Zwift on Linux +theme: just-the-docs +repository: netbrain/zwift +color_scheme: dark +permalink: pretty +back_to_top: true +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 +callouts: + important: + title: Important + color: yellow + note: + title: Note + color: yellow + warning: + 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/advanced/custom-workouts.md b/docs/advanced/custom-workouts.md new file mode 100644 index 00000000..56e09f5f --- /dev/null +++ b/docs/advanced/custom-workouts.md @@ -0,0 +1,28 @@ +--- +title: Custom Workouts +nav_order: 1 +parent: Advanced +--- + +# 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 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/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/advanced/nixos.md b/docs/advanced/nixos.md new file mode 100644 index 00000000..cebc00a6 --- /dev/null +++ b/docs/advanced/nixos.md @@ -0,0 +1,101 @@ +--- +title: NixOS +parent: Advanced +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]; + }; +}; +``` 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/configuration/authentication.md b/docs/configuration/authentication.md new file mode 100644 index 00000000..399351b1 --- /dev/null +++ b/docs/configuration/authentication.md @@ -0,0 +1,30 @@ +--- +title: Authentication +parent: Configuration +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/configuration/graphics.md b/docs/configuration/graphics.md new file mode 100644 index 00000000..99055d23 --- /dev/null +++ b/docs/configuration/graphics.md @@ -0,0 +1,81 @@ +--- +title: Graphics Settings +parent: Configuration +nav_order: 3 +--- + +# 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/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 00000000..64440748 --- /dev/null +++ b/docs/configuration/index.md @@ -0,0 +1,7 @@ +--- +title: Configuration +nav_order: 3 +description: "Learn how to set up and run Zwift on Linux using Podman or Docker" +--- + +# Configuration diff --git a/docs/configuration/options.md b/docs/configuration/options.md new file mode 100644 index 00000000..a4135167 --- /dev/null +++ b/docs/configuration/options.md @@ -0,0 +1,149 @@ +--- +title: Configuration Options +parent: Configuration +nav_order: 1 +--- + +# Configuration Options + +## 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` | +| `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`) | + +{: .important } +`ZWIFT_UID` and `ZWIFT_GID` can only used in X11. They do not work in wayland! + +### 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. + +## 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 `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. 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'` +> +> 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 `ZWIFT_PASSWORD='p'"'"'as'` (replace `'` with `'"'"'`) +> +> 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'`) + +## Configuration files + +You can also save these in a configuration file that is automatically loaded by the zwift script. + +- `$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 +ZWIFT_USERNAME='user@mail.com' +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. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 00000000..4107fc33 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,22 @@ +--- +title: Getting Started +nav_order: 2 +description: "Learn how to set up and run Zwift on Linux using Podman or Docker" +--- + +# 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. + +## 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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 00000000..77cd474e --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,31 @@ +--- +title: Installation +parent: Getting Started +nav_order: 2 +--- + +# Installation Methods + +## Automatic Installation + +### 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)" +``` + +This script will: + +- Download the Zwift Docker image +- Create necessary configuration files +- Add zwift command to your system path +- Create desktop shortcut + +## 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 new file mode 100644 index 00000000..00341d35 --- /dev/null +++ b/docs/getting-started/prerequisites.md @@ -0,0 +1,49 @@ +--- +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 (integrated or discrete) | +| **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) + +{: .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]( + https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) + - Podman: Also follow the [Container Device Interface guide]( + https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html) + +{: .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/index.md b/docs/index.md new file mode 100644 index 00000000..9aa2c6bd --- /dev/null +++ b/docs/index.md @@ -0,0 +1,24 @@ +--- +title: Home +layout: home +nav_order: 1 +description: "Easily Zwift on Linux!" +--- + +# 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)" +``` + +![example.gif](https://raw.githubusercontent.com/netbrain/zwift/master/example.gif) + +## Key Features + +- **Easy installation** +- **Comprehensive configuration options** +- **Multi-instance support** 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..643b78ee --- /dev/null +++ b/docs/troubleshooting/index.md @@ -0,0 +1,7 @@ +--- +title: Troubleshooting +nav_order: 4 +description: "Solve common issues with Zwift Docker Container" +--- + +# 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/troubleshooting/wifi-devices.md b/docs/troubleshooting/wifi-devices.md new file mode 100644 index 00000000..c424eada --- /dev/null +++ b/docs/troubleshooting/wifi-devices.md @@ -0,0 +1,64 @@ +--- +title: WiFi Device Detection +parent: Troubleshooting +nav_order: 1 +--- + +# 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**: + + ```bash + 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: + + ```bash + 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): + + ```bash + firewall-cmd --reload + ``` + + **Restart the service**: + + ```bash + systemctl restart firewalld + ```