|
| 1 | +:_content-type: CONCEPT |
| 2 | +:description: Persistent user home preserves the /home/user directory across workspace restarts |
| 3 | +:keywords: administration guide, {prod-id-short}, persistent, user, home |
| 4 | +:navtitle: Persistent user home |
| 5 | +:page-aliases: about-persistent-user-home.adoc |
| 6 | + |
| 7 | +[id="persistent-user-home"] |
| 8 | += Persistent user home |
| 9 | + |
| 10 | +[role="_abstract"] |
| 11 | +{prod} preserves the `/home/user` directory across workspace restarts for each non-ephemeral workspace, so that user-specific configurations, shell history, and tooling settings persist between sessions. |
| 12 | + |
| 13 | +This feature is enabled by default. To disable it, set `spec.devEnvironments.persistUserHome.enabled` to `false` in the CheCluster custom resource. |
| 14 | + |
| 15 | +For newly started workspaces, this feature creates a persistent volume claim (PVC) mounted to the `/home/user` path of the tools container. |
| 16 | +The tools container is the first container defined in the devfile. |
| 17 | +This is the container that includes the project source code by default. |
| 18 | + |
| 19 | +When the PVC is mounted for the first time, the persistent volume's contents are empty and therefore must be populated with the `/home/user` directory content. |
| 20 | + |
| 21 | +By default, the `persistUserHome` feature creates an init container for each new workspace pod named `init-persistent-home`. |
| 22 | +This init container is created with the tools container image. |
| 23 | +It runs a `stow` command to create symbolic links in the persistent volume, populating the `/home/user` directory. |
| 24 | + |
| 25 | +[NOTE] |
| 26 | +==== |
| 27 | +For files that cannot be symbolically linked to the `/home/user` directory, such as `.viminfo` and `.bashrc`, `cp` is used instead of `stow`. |
| 28 | +==== |
| 29 | + |
| 30 | +The primary function of the `stow` command is to run: |
| 31 | + |
| 32 | +[source,bash,subs="+quotes,+attributes"] |
| 33 | +---- |
| 34 | +stow -t /home/user/ -d /home/tooling/ --no-folding |
| 35 | +---- |
| 36 | + |
| 37 | +This command creates symbolic links in `/home/user` for files and directories located in `/home/tooling`. This populates the persistent volume with symbolic links to the content in `/home/tooling`. As a result, the `persistUserHome` feature expects the tooling image to have its `/home/user/` content within `/home/tooling`. |
| 38 | + |
| 39 | +For example, if the tools container image contains `.config` and `.config-folder/another-file` in the `/home/tooling` directory, `stow` creates symbolic links as follows: |
| 40 | + |
| 41 | +.Tools container with `persistUserHome` enabled |
| 42 | +image::persistent-user-home/tools-container-example.png[Persistent user home example scenario] |
| 43 | + |
| 44 | +The init container writes the output of the `stow` command to `/home/user/.stow.log` and only runs `stow` the first time the persistent volume is mounted to the workspace. |
| 45 | + |
| 46 | +Using the `stow` command to populate `/home/user` content in the persistent volume provides two main advantages: |
| 47 | + |
| 48 | +. Creating symbolic links is faster and consumes less storage than creating copies of the `/home/user` directory content in the persistent volume. The persistent volume contains symbolic links, not the actual files. |
| 49 | +. If the tools image is updated with newer versions of existing binaries, configs, and files, the init container does not need to rerun `stow`. The existing symbolic links already point to the newer versions in `/home/tooling`. |
| 50 | + |
| 51 | +[NOTE] |
| 52 | +==== |
| 53 | +If the tooling image is updated with additional binaries or files, they are not symbolically linked to the `/home/user` directory. The `stow` command does not run again automatically. |
| 54 | +
|
| 55 | +To rerun `stow`, delete the `/home/user/.stow_completed` file and restart the workspace. |
| 56 | +==== |
| 57 | + |
| 58 | +== `persistUserHome` tools image requirements |
| 59 | + |
| 60 | +The `persistUserHome` depends on the tools image used for the workspace. By default {prod-short} uses the Universal Developer Image (UDI) for sample workspaces, which supports `persistUserHome` out of the box. |
| 61 | + |
| 62 | +If you are using a custom image, the tools image must meet three requirements to support the `persistUserHome` feature. |
| 63 | + |
| 64 | +* The tools image must contain `stow` version >= 2.4.0. |
| 65 | +* The `$HOME` environment variable is set to `/home/user`. |
| 66 | +* The directory intended to contain the `/home/user` content is `/home/tooling`. |
| 67 | + |
| 68 | +Because the `/home/user` content must reside in `/home/tooling`, the default UDI image for example adds the `/home/user` content to `/home/tooling` instead, and runs: |
| 69 | + |
| 70 | +[source,dockerfile,subs="+quotes,+attributes"] |
| 71 | +---- |
| 72 | +RUN stow -t /home/user/ -d /home/tooling/ --no-folding |
| 73 | +---- |
| 74 | + |
| 75 | +This `RUN` instruction in the Dockerfile ensures that files in `/home/tooling` are accessible from `/home/user` even when the `persistUserHome` feature is not enabled. |
0 commit comments