Volume-based Zwift installation to eliminate per-launch chown

[netbrain]

Problem

When using Docker with a uid/gid that differs from the container default (1000:1000), the entrypoint runs chown on every launch. The container is ephemeral, so /home/user is recreated from the image layer each time with 1000:1000 ownership. Currently only ZWIFT_DOCS is persisted as a volume.

Suggested solution

Decouple the Zwift installation from the container image. Instead of baking Zwift into the image, offer a volume-based installation mode:

• Minimal container image: only wine + dependencies, no Zwift pre-installed
• First run: user runs zwift --install, which mounts an empty volume at /home/user and runs the Zwift installer into it
• Subsequent runs: mount the same volume, launch directly. No chown needed since ownership persists in the volume
• Updates: Zwift's own updater handles it, or user runs zwift --update

This approach:

• Eliminates the per-launch chown entirely
• Shrinks the container image (no bundled Zwift installation)
• Mirrors how Zwift works on a real machine (install once, self-update)
• Could coexist with the current pre-installed approach as an opt-in alternative

This aligns with the second variant described in issue #28 (minimal container with volume-based Zwift download on first run).

[netbrain]

Related to #311

[glennvl]

Let me start out by saying I can see you already put a lot of thought and effort into this. And I appreciate your effort and that you created this great project that allows us to easily run Zwift on Linux!

My humble opinion

What we have now is a simple and elegant solution:

• A container with Zwift installed that just works
• Zwift updates are handled server side, the end user does not have to worry about anything

Are we sure adding (potentially more fragile) variants fits within the philosophy of this project?

• Letting the user handle Zwift installation and updates moves unnecessary responsibility to the end user
• The other variant that uses native wine especially sounds like an entirely different project to me

Issues with doing installs and updates on the end-user's setup

The launcher does not work to actually start Zwift. But we still need it to update Zwift. So when installing or updating Zwift we have to wait for the launcher to finish the update, then start Zwift ourselves. We do so by waiting until the local Zwift version is the same as the version in the https://cdn.zwift.com/gameassets/Zwift_Updates_Root/Zwift_ver_cur.xml file (referred to as Zwift_ver_cur.xml file from here on).

When updating Zwift automatically server-side using a github action, this is a great solution! But only because we only trigger the update only after checking the value of that same Zwift_ver_cur.xml file.

To understand why this is a problem when manually installing or updating Zwift, we have to look at how Zwift deploys its updates. It uses a phased rollout process. Only after the phased rollout is completed do they update the Zwift_ver_cur.xml file. Which means that between the release of a new Zwift version (the start of the phased rollout) and the time the Zwift_ver_cur.xml file is updated (the end of the phased rollout), the version in the Zwift_ver_cur.xml file will be different from the version the launcher is trying to update to (depending at which point in the phased rollout the user is at the time he opens the Zwift launcher, the version in Zwift_ver_cur.xml will be correct, too low or too high).

• Problem 1: If the user runs zwift -- --update when an update is available for him, but the Zwift_ver_cur.xml file is not yet updated, the update script ends in an infinite loop (the expected version will never be reached since after update it's too high, the loop keeps looping).
• Problem 2: Assuming we want to automatically update when new version is available as well. If we fix the above by ending the loop if the new zwift version is different from the original, the next time Zwift will be automatically downgraded again (because the version in the Zwift_ver_cur.xml file will be lower than the installed version). We cannot just disable downgrades since downgrades is something Zwift has already done multiple times in the past.

The same issue is also present when performing a clean install.

• Problem 3: If the user runs zwift -- --install because he's using Zwift for the first time. If this happens to be during the phased rollout period of a new Zwift release when the user already has the new version available, but Zwift_ver_cur.xml is not yet updated (rollout not complete) he ends up in the same situation as above. The update script will loop forever (expected version is never reached) or if we work around that, the updater will downgrade Zwift again.

The underlying issue is that we have no way to know what the latest Zwift version is for a specific user because of the phased rollout process. On the server this is not a huge issue since we only update for everyone at the same time when the phased rollout is complete. We could try to build in some safeguards to do the same when running the update locally, but it'll be fragile at best (potentially expect the user to do the right thing).

Let's say we can live with that, it's somewhat of an inconvenience but not really a dealbreak to ask the user to play nice and follow instructions for updating Zwift.

Performing a clean install is a different beast though. A clean install has to work at any time if we expect the user to perform it himself. And we can't control which Zwift version will be installed when performing a clean install.

This same problem exists with our github workflows btw:

• If we do a rebuild from scratch during a phased rollout when we already receive the update, the script will loop forever. (I think this is not a huge issue, we can be careful not to make changes that require a rebuild from scratch during a phased rollout. And if that cron triggered job fails, that's not a big issue either, the image just remains at its current version.)
• If we would fix that loop by exiting if the version changed instead of when it reaches the expected version, the hourly running zwift updater action would downgrade Zwift again. (I would consider this less optimal than the current situation.)

TL;DR: Things will break and I'm not sure we can fix them.

A possible alternative

In the PR where a proof-of-concept of the proposed change is implemented, a little meta-data file is used to keep track of the container version to see if an update of the volume is required.

Could we instead keep such a meta-data file to keep track of whether a chown is required instead?

Would something like the following be a viable alternative?

• If the container tool is docker
• When a new version of the image is pulled
  • Run chown if needed
  • Add/Update a little meta-data file with the image hash
  • Tag the image locally
• Use the local tag instead of docker.io/netbrain/zwift:latest to start zwift
  • No chown required!
• The tag name should include the uid and gid
• The base zwift image hash can be stored in a label or as a metadata file

That way only the first start after an image update is slow because of chown. And everything else keeps working as is.

Is it worth it

In the OP three advantages are given for the proposed approach:

1. Eliminates the per-launch chown entirely
   • This can also be achieved through the alternative solution.
2. Shrinks the container image (no bundled Zwift installation)
   • Zwift has to be downloaded and installed anyway. Whether it's by pulling the docker image or by using the Zwift launcher.
3. Mirrors how Zwift works on a real machine (install once, self-update)
   • It will only somewhat approach how Zwift works on a real machine, due to the launcher not being fully operational under Wine and the aforementioned difficulties that causes.

Let's get back to why this change is proposed.

When using docker and user ids different from 1000:1000, the container is slow to start

What does slow to start in this context mean? Anecdotally for some user it takes a minute or two to launch Zwift. When I personally try on my pc, the chown is done in a couple of seconds.

To me this solution looks like we'll add a lot of complexity and introduce potential issues to solve an inconvenience that is only faced by a minority of users.

• Should we gather more evidence about how slow it is on average first?
• Should we look into alternative solutions that stay within the philosophy of the project?

[netbrain]

Thanks for the thorough analysis — these are all valid concerns and I appreciate you taking the time to think through the edge cases.

I've been doing some deeper analysis of both approaches and I think you've identified real issues with the volume variant as currently implemented. A few specific bugs I've found:

First-run ownership is broken for the exact users it targets. Docker auto-populates a named volume from the image with uid 1000 ownership. But the volume variant skips the chown in the entrypoint (ZWIFT_VOLUME=1). So a user with uid 1001 gets files owned by 1000 and no mechanism to fix them. This defeats the purpose.

The rsync --delete flag is dangerous. The exclude list is hardcoded to known user-data directories. If Zwift adds new directories (crash dumps, telemetry caches, cp data — which they have done historically), a sync will silently wipe them. This is a maintenance burden that requires tracking Zwift's internal changes forever.

The OCI version label is fragile. The zwift_push.yaml workflow (script-only updates) doesn't set org.opencontainers.image.version — only zwift_updater.yaml does. So the sync logic can skip necessary syncs or run unnecessary ones after script-only image updates.

That said, I still think the volume approach has independent value beyond the chown fix — Wine prefix persistence (registry tweaks, shader caches, DLL overrides surviving restarts) is something users have asked about, and it aligns with how other containerized applications handle persistent state.

Your local tag idea is clever and solves the chown problem specifically with minimal changes. What I like about it: ~25 lines in zwift.sh, zero changes to entrypoint/Dockerfile, worst-case failure is just one slow start (today's status quo), and no fragile exclude lists.

Here's what I'm thinking: all three approaches could coexist behind ZWIFT_VARIANT:

• container (default) — current behavior, unchanged
• cached — your local tag approach. After pulling a new image, chown once, commit as a local tag with uid/gid baked in, use that for subsequent launches. Minimal code change, low risk, solves the chown problem cleanly
• volume — persistent /home/user volume for users who want full Wine prefix persistence, with the identified bugs fixed

Each solves a different problem at a different layer. cached is a targeted chown fix with minimal blast radius. volume is an architectural change for users who want persistent Wine state. Real-world usage will determine which ones earn their keep long-term — we can always deprecate what doesn't work.

What do you think — would you be interested in taking a crack at the cached variant? You clearly have a good mental model of how the pieces fit together.

[glennvl]

What do you think — would you be interested in taking a crack at the cached variant? You clearly have a good mental model of how the pieces fit together.

I've been experimenting with it a bit and what I'm working on is slightly different from what I first proposed. Expect a draft PR soon so we can discuss more easily.