feat: persistent user home documentation #2822

dkwon17 · 2024-11-19T20:56:03Z

What does this pull request change?

This PR adds documentation about the persistent user home feature.

What issues does this pull request fix or reference?

Specify the version of the product this pull request applies to

7.94.x, next

Pull Request checklist

The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.

Any procedure:
- Successfully tested.
Any page or link rename:
- The page contains a redirection for the previous URL.
- Propagate the URL change in:
  - Dashboard default branding data
Builds on Eclipse Che hosted by Red Hat.
the Validate language on files added or modified step reports no vale warnings.

Signed-off-by: dkwon17 <[email protected]>

github-actions · 2024-11-19T20:56:17Z

🎊 Navigate the preview: https://674de45580bda81538b4acb0--eclipse-che-docs-pr.netlify.app 🎊

github-actions · 2024-11-19T20:56:17Z

Click here to review and test in web IDE:

deerskindoll

a couple of tweaks

modules/administration-guide/pages/about-persistent-user-home.adoc

…adoc Co-authored-by: Jana Vrbkova <[email protected]>

dkwon17 · 2024-11-21T21:13:47Z

Thank you @deerskindoll for the review, I've applied the changes

deerskindoll

lgtm

AObuchow

@dkwon17 this looks great to me, you did a really good job at concisely and clearly explaining how the home persistence feature works and its requirements, which is a very difficult thing to do.

I left some very minor feedback :)

modules/administration-guide/pages/about-persistent-user-home.adoc

AObuchow · 2024-11-29T16:45:42Z

modules/administration-guide/pages/about-persistent-user-home.adoc

+.Tools container with `persistUserHome` enabled
+image::persistent-user-home/tools-container-example.png[Persistent user home example scenario]
+
+The init container writes the output of the `stow` command to `/home/user/.stow.log` and will only run `stow` the first time the PVC is mounted to the workspace. 


Technical nitpick: Isin't the stow command run only the first time when the workspace is started up? When aa workspace pod gets terminated (if the workspace shuts down) won't it unmount to the PVC and then get mounted again?

Right, what I mean is it runs the first time it's mounted, in the second/third/fourth workspace starts, it's the second/third/fourth time it's mounted, so it doesn't run.

Is the wording is a bit unclear?

In my latest commit, I've updated it to:

The init container writes the output of the `stow` command to `/home/user/.stow.log` and will only run `stow` the first time the persistent volume is mounted to the workspace.

AObuchow · 2024-11-29T16:51:10Z

modules/administration-guide/pages/about-persistent-user-home.adoc

+Using the `stow` command to populate `/home/user` content in the persistent volume provides two main advantages.
+
+. Creating symbolic links is faster than creating copies of the `/home/user` folder content in the persistent volume. To put it differently, the persistent volume in this case contains symbolic links and not the actual files themselves.
+. If the tools image is updated with newer versions of existing binaries, configs, and files, the init container does not need to `stow` the new versions, as the existing symbolic links will link to the newer versions in `/home/tooling` already.


Something that just occurred to me: if the tooling image is updated with additional binaries, files etc. they won't be copied to the /home/user/ directory since the stow command won't be run again.

This may be something we want to document in the future (or somewhere in this document as a small note that the user should delete the /home/user/.stow_completed file and restart the workspace to pick up these additional files)

I've added this note:

Perfect! Thank you :)

modules/administration-guide/pages/about-persistent-user-home.adoc

Signed-off-by: dkwon17 <[email protected]>

dkwon17 · 2024-11-29T19:43:57Z

Thank you for the review @AObuchow , I've made updates

modules/administration-guide/pages/about-persistent-user-home.adoc

Signed-off-by: dkwon17 <[email protected]>

ibuziuk · 2024-12-02T12:09:53Z

@deerskindoll once merged, please backport to 7.95.x for 3.18

* feat: persistent user home documentation Signed-off-by: dkwon17 <[email protected]> * Update modules/administration-guide/pages/about-persistent-user-home.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/about-persistent-user-home.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/about-persistent-user-home.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/about-persistent-user-home.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/about-persistent-user-home.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/pages/about-persistent-user-home.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update based on PR feedback Signed-off-by: dkwon17 <[email protected]> * Update stow version Signed-off-by: dkwon17 <[email protected]> * Update PR typo Signed-off-by: dkwon17 <[email protected]> --------- Signed-off-by: dkwon17 <[email protected]> Co-authored-by: Jana Vrbkova <[email protected]>

feat: persistent user home documentation

a3e03a5

Signed-off-by: dkwon17 <[email protected]>

dkwon17 requested review from deerskindoll and a team as code owners November 19, 2024 20:56

dkwon17 requested a review from ibuziuk November 19, 2024 20:56

deerskindoll reviewed Nov 20, 2024

View reviewed changes

dkwon17 and others added 6 commits November 21, 2024 16:03

Update modules/administration-guide/pages/about-persistent-user-home.…

a56a495

…adoc Co-authored-by: Jana Vrbkova <[email protected]>

Update modules/administration-guide/pages/about-persistent-user-home.…

856825e

…adoc Co-authored-by: Jana Vrbkova <[email protected]>

Update modules/administration-guide/pages/about-persistent-user-home.…

1d81147

…adoc Co-authored-by: Jana Vrbkova <[email protected]>

Update modules/administration-guide/pages/about-persistent-user-home.…

ff3dd33

…adoc Co-authored-by: Jana Vrbkova <[email protected]>

Update modules/administration-guide/pages/about-persistent-user-home.…

2ee1ff1

…adoc Co-authored-by: Jana Vrbkova <[email protected]>

Update modules/administration-guide/pages/about-persistent-user-home.…

86cb9c3

…adoc Co-authored-by: Jana Vrbkova <[email protected]>

deerskindoll approved these changes Nov 21, 2024

View reviewed changes

AObuchow reviewed Nov 29, 2024

View reviewed changes

dkwon17 added 2 commits November 29, 2024 19:34

Update based on PR feedback

ac55753

Signed-off-by: dkwon17 <[email protected]>

Update stow version

c287389

Signed-off-by: dkwon17 <[email protected]>

AObuchow approved these changes Nov 29, 2024

View reviewed changes

AObuchow reviewed Nov 29, 2024

View reviewed changes

modules/administration-guide/pages/about-persistent-user-home.adoc Outdated Show resolved Hide resolved

Update PR typo

77b838d

Signed-off-by: dkwon17 <[email protected]>

ibuziuk approved these changes Dec 2, 2024

View reviewed changes

dkwon17 merged commit fc0dbec into eclipse-che:main Dec 3, 2024
6 checks passed

deerskindoll added the backported to 7.95.x label Dec 4, 2024

dkwon17 mentioned this pull request Dec 4, 2024

Create documentation for devEnvironments.persistentUserHome.enabled eclipse-che/che#23075

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: persistent user home documentation #2822

feat: persistent user home documentation #2822

dkwon17 commented Nov 19, 2024 •

edited

Loading

github-actions bot commented Nov 19, 2024 •

edited

Loading

github-actions bot commented Nov 19, 2024 •

edited

Loading

deerskindoll left a comment

dkwon17 commented Nov 21, 2024

deerskindoll left a comment

AObuchow left a comment

AObuchow Nov 29, 2024

dkwon17 Nov 29, 2024

AObuchow Nov 29, 2024

dkwon17 Nov 29, 2024

AObuchow Nov 29, 2024

dkwon17 commented Nov 29, 2024

ibuziuk commented Dec 2, 2024

feat: persistent user home documentation #2822

feat: persistent user home documentation #2822

Conversation

dkwon17 commented Nov 19, 2024 • edited Loading

What does this pull request change?

What issues does this pull request fix or reference?

Specify the version of the product this pull request applies to

Pull Request checklist

github-actions bot commented Nov 19, 2024 • edited Loading

github-actions bot commented Nov 19, 2024 • edited Loading

deerskindoll left a comment

Choose a reason for hiding this comment

dkwon17 commented Nov 21, 2024

deerskindoll left a comment

Choose a reason for hiding this comment

AObuchow left a comment

Choose a reason for hiding this comment

AObuchow Nov 29, 2024

Choose a reason for hiding this comment

dkwon17 Nov 29, 2024

Choose a reason for hiding this comment

AObuchow Nov 29, 2024

Choose a reason for hiding this comment

dkwon17 Nov 29, 2024

Choose a reason for hiding this comment

AObuchow Nov 29, 2024

Choose a reason for hiding this comment

dkwon17 commented Nov 29, 2024

ibuziuk commented Dec 2, 2024

dkwon17 commented Nov 19, 2024 •

edited

Loading

github-actions bot commented Nov 19, 2024 •

edited

Loading

github-actions bot commented Nov 19, 2024 •

edited

Loading