diff --git a/antora.yml b/antora.yml index 38635b88fa..14c2a3dd12 100644 --- a/antora.yml +++ b/antora.yml @@ -7,6 +7,7 @@ start_page: discover:what-is-che.adoc nav: - modules/discover/nav.adoc - modules/install/nav.adoc + - modules/develop/nav.adoc - modules/end-user-guide/nav.adoc - modules/upgrade/nav.adoc - modules/secure/nav.adoc diff --git a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc index c66835c0ba..7c83558093 100644 --- a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc +++ b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc @@ -104,5 +104,5 @@ EOF .Additional resources * xref:configuring-ai-providers.adoc[] -* xref:end-user-guide:mounting-secrets.adoc[Mounting secrets (end-user guide)] +* xref:develop:mounting-secrets.adoc[Mounting secrets (end-user guide)] * link:https://devfile.io/docs/2.2.0/what-is-a-devfile[Devfile documentation] diff --git a/modules/administration-guide/pages/configuring-a-user-namespace.adoc b/modules/administration-guide/pages/configuring-a-user-namespace.adoc index a67f0d99cc..ed32d0b344 100644 --- a/modules/administration-guide/pages/configuring-a-user-namespace.adoc +++ b/modules/administration-guide/pages/configuring-a-user-namespace.adoc @@ -265,9 +265,9 @@ NOTE: Creating Template Kubernetes resources is supported only on OpenShift. ==== .Additional resources -* xref:end-user-guide:mounting-configmaps.adoc[] -* xref:end-user-guide:mounting-secrets.adoc[] -* xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[] +* xref:develop:mounting-configmaps.adoc[] +* xref:develop:mounting-secrets.adoc[] +* xref:develop:requesting-persistent-storage-for-workspaces.adoc[] * link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets] * link:https://docs.openshift.com/container-platform/latest/rest_api/template_apis/template-template-openshift-io-v1.html[OpenShift API reference for `Template`] * link:https://docs.openshift.com/container-platform/latest/applications/projects/configuring-project-creation.html[Configuring OpenShift project creation] \ No newline at end of file diff --git a/modules/administration-guide/pages/configuring-ai-providers.adoc b/modules/administration-guide/pages/configuring-ai-providers.adoc index 8be4bd5f88..00f82d210b 100644 --- a/modules/administration-guide/pages/configuring-ai-providers.adoc +++ b/modules/administration-guide/pages/configuring-ai-providers.adoc @@ -151,4 +151,4 @@ When you update the registry (for example, to remove a tool or change the inject .Additional resources * xref:ai-provider-api-key-secret-reference.adoc[] -* xref:end-user-guide:using-ai-assistants-in-workspaces.adoc[] +* xref:develop:using-ai-assistants-in-workspaces.adoc[] diff --git a/modules/administration-guide/pages/configuring-fuse.adoc b/modules/administration-guide/pages/configuring-fuse.adoc index b6da34436e..cfbe23c885 100644 --- a/modules/administration-guide/pages/configuring-fuse.adoc +++ b/modules/administration-guide/pages/configuring-fuse.adoc @@ -18,4 +18,4 @@ This is not necessary for OpenShift versions 4.15 and later, since the `/dev/fus After enabling `/dev/fuse` access, fuse-overlayfs can be enabled in two ways: . For all user workspaces within the cluster. See xref:administration-guide:enabling-fuse-for-all-workspaces.adoc[]. -. For workspaces belonging to certain users. See xref:end-user-guide:using-the-fuse-overlay-storage-driver.adoc[]. +. For workspaces belonging to certain users. See xref:develop:using-the-fuse-overlay-storage-driver.adoc[]. diff --git a/modules/administration-guide/pages/configuring-the-storage-strategy.adoc b/modules/administration-guide/pages/configuring-the-storage-strategy.adoc index dcbc6256b9..ad88d3d4fd 100644 --- a/modules/administration-guide/pages/configuring-the-storage-strategy.adoc +++ b/modules/administration-guide/pages/configuring-the-storage-strategy.adoc @@ -7,7 +7,7 @@ [id="configuring-the-storage-strategy"] = Configuring the storage strategy -{prod-short} can be configured to provide persistent or non-persistent storage to workspaces by selecting a storage strategy. The selected storage strategy will be applied to all newly created workspaces by default. Users can opt for a non-default storage strategy for their workspace in their xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[devfile] or through the xref:end-user-guide:url-parameter-for-the-workspace-storage.adoc[URL parameter]. +{prod-short} can be configured to provide persistent or non-persistent storage to workspaces by selecting a storage strategy. The selected storage strategy will be applied to all newly created workspaces by default. Users can opt for a non-default storage strategy for their workspace in their xref:develop:requesting-persistent-storage-for-workspaces.adoc[devfile] or through the xref:develop:url-parameter-for-the-workspace-storage.adoc[URL parameter]. Available storage strategies: diff --git a/modules/administration-guide/pages/devworkspace-backup.adoc b/modules/administration-guide/pages/devworkspace-backup.adoc index c4fc4ef0aa..877089c41c 100644 --- a/modules/administration-guide/pages/devworkspace-backup.adoc +++ b/modules/administration-guide/pages/devworkspace-backup.adoc @@ -14,7 +14,7 @@ integrated registry or link:https://quay.io[Quay.io], to store backup archives a The backup makes a snapshot of *stopped* Workspace PVCs and stores them as tar.gz archives in the specified OCI registry. -Users can restore backups from the {prod-short} dashboard. See xref:end-user-guide:restoring-workspaces-from-backups.adoc[]. +Users can restore backups from the {prod-short} dashboard. See xref:develop:restoring-workspaces-from-backups.adoc[]. NOTE: By default, the {devworkspace} backup job is disabled. diff --git a/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc b/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc index f0ede58afc..5f7c9875d7 100644 --- a/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc +++ b/modules/administration-guide/pages/enabling-access-to-dev-fuse-for-openshift.adoc @@ -139,4 +139,4 @@ sh-4.4# stat /host/etc/crio/crio.conf.d/99-podman-fuse ---- == Using fuse-overlayfs for Podman and Buildah within a workspace -Users can follow xref:end-user-guide:using-the-fuse-overlay-storage-driver.adoc[] to update existing workspaces to use the fuse-overlayfs storage driver for Podman and Buildah. +Users can follow xref:develop:using-the-fuse-overlay-storage-driver.adoc[] to update existing workspaces to use the fuse-overlayfs storage driver for Podman and Buildah. diff --git a/modules/end-user-guide/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc b/modules/develop/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc similarity index 100% rename from modules/end-user-guide/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc rename to modules/develop/examples/con_customizing-ide-selection-with-the-che-editor-file.adoc diff --git a/modules/end-user-guide/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc b/modules/develop/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc similarity index 100% rename from modules/end-user-guide/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc rename to modules/develop/examples/proc_using-the-che-prod-editor-file-to-select-an-ide.adoc diff --git a/modules/end-user-guide/examples/snip_che-ide-default-yaml-file.adoc b/modules/develop/examples/snip_che-ide-default-yaml-file.adoc similarity index 100% rename from modules/end-user-guide/examples/snip_che-ide-default-yaml-file.adoc rename to modules/develop/examples/snip_che-ide-default-yaml-file.adoc diff --git a/modules/end-user-guide/examples/snip_che-supported-languages.adoc b/modules/develop/examples/snip_che-supported-languages.adoc similarity index 100% rename from modules/end-user-guide/examples/snip_che-supported-languages.adoc rename to modules/develop/examples/snip_che-supported-languages.adoc diff --git a/modules/end-user-guide/examples/snip_github-action-yaml-example-activity-types.adoc b/modules/develop/examples/snip_github-action-yaml-example-activity-types.adoc similarity index 100% rename from modules/end-user-guide/examples/snip_github-action-yaml-example-activity-types.adoc rename to modules/develop/examples/snip_github-action-yaml-example-activity-types.adoc diff --git a/modules/end-user-guide/examples/snip_github-action-yaml-example.adoc b/modules/develop/examples/snip_github-action-yaml-example.adoc similarity index 100% rename from modules/end-user-guide/examples/snip_github-action-yaml-example.adoc rename to modules/develop/examples/snip_github-action-yaml-example.adoc diff --git a/modules/end-user-guide/images/contribute.svg b/modules/develop/images/contribute.svg similarity index 100% rename from modules/end-user-guide/images/contribute.svg rename to modules/develop/images/contribute.svg diff --git a/modules/end-user-guide/images/github-action-comment.png b/modules/develop/images/github-action-comment.png similarity index 100% rename from modules/end-user-guide/images/github-action-comment.png rename to modules/develop/images/github-action-comment.png diff --git a/modules/end-user-guide/images/github-action-status-check.png b/modules/develop/images/github-action-status-check.png similarity index 100% rename from modules/end-user-guide/images/github-action-status-check.png rename to modules/develop/images/github-action-status-check.png diff --git a/modules/end-user-guide/images/vscode-remote/cli-create-tunnel.png b/modules/develop/images/vscode-remote/cli-create-tunnel.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/cli-create-tunnel.png rename to modules/develop/images/vscode-remote/cli-create-tunnel.png diff --git a/modules/end-user-guide/images/vscode-remote/confirm-opening-vscode-desktop.png b/modules/develop/images/vscode-remote/confirm-opening-vscode-desktop.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/confirm-opening-vscode-desktop.png rename to modules/develop/images/vscode-remote/confirm-opening-vscode-desktop.png diff --git a/modules/end-user-guide/images/vscode-remote/login-with-provider.png b/modules/develop/images/vscode-remote/login-with-provider.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/login-with-provider.png rename to modules/develop/images/vscode-remote/login-with-provider.png diff --git a/modules/end-user-guide/images/vscode-remote/login.png b/modules/develop/images/vscode-remote/login.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/login.png rename to modules/develop/images/vscode-remote/login.png diff --git a/modules/end-user-guide/images/vscode-remote/open-visual-studio-code.png b/modules/develop/images/vscode-remote/open-visual-studio-code.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/open-visual-studio-code.png rename to modules/develop/images/vscode-remote/open-visual-studio-code.png diff --git a/modules/end-user-guide/images/vscode-remote/select-editor.png b/modules/develop/images/vscode-remote/select-editor.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/select-editor.png rename to modules/develop/images/vscode-remote/select-editor.png diff --git a/modules/end-user-guide/images/vscode-remote/vscode-remote-explorer.png b/modules/develop/images/vscode-remote/vscode-remote-explorer.png similarity index 100% rename from modules/end-user-guide/images/vscode-remote/vscode-remote-explorer.png rename to modules/develop/images/vscode-remote/vscode-remote-explorer.png diff --git a/modules/end-user-guide/images/workspace-backup/backups_tab.png b/modules/develop/images/workspace-backup/backups_tab.png similarity index 100% rename from modules/end-user-guide/images/workspace-backup/backups_tab.png rename to modules/develop/images/workspace-backup/backups_tab.png diff --git a/modules/end-user-guide/images/workspace-backup/restore_section_1.png b/modules/develop/images/workspace-backup/restore_section_1.png similarity index 100% rename from modules/end-user-guide/images/workspace-backup/restore_section_1.png rename to modules/develop/images/workspace-backup/restore_section_1.png diff --git a/modules/end-user-guide/images/workspace-backup/restore_section_2.png b/modules/develop/images/workspace-backup/restore_section_2.png similarity index 100% rename from modules/end-user-guide/images/workspace-backup/restore_section_2.png rename to modules/develop/images/workspace-backup/restore_section_2.png diff --git a/modules/develop/nav.adoc b/modules/develop/nav.adoc new file mode 100644 index 0000000000..15556dc51c --- /dev/null +++ b/modules/develop/nav.adoc @@ -0,0 +1,44 @@ +.Develop +* xref:using-credentials-and-configurations-in-workspaces.adoc[] +** xref:mounting-secrets.adoc[] +*** xref:creating-image-pull-secrets.adoc[] +** xref:mounting-configmaps.adoc[] +*** xref:mounting-git-configuration.adoc[] +*** xref:mounting-ssh-configuration.adoc[] +* xref:using-the-fuse-overlay-storage-driver.adoc[] +** xref:accessing-fuse.adoc[] +** xref:enabling-overlay-with-a-configmap.adoc[] +** xref:running-containers-with-kubedock.adoc[] +* xref:using-che-in-team-workflow.adoc[] +** xref:first-time-contributors.adoc[] +** xref:benefits-of-pull-requests-review-in-che.adoc[] +** xref:try-in-web-ide-github-action.adoc[] +* xref:requesting-persistent-storage-for-workspaces.adoc[] +** xref:restoring-workspaces-from-backups.adoc[] +*** xref:proc-restoring-a-workspace-from-backup.adoc[] +*** xref:proc-viewing-backups-in-the-dashboard.adoc[] +* xref:proc_preventing-workspace-idling-for-long-running-commands.adoc[] +* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] +** xref:url-parameter-concatenation.adoc[] +** xref:url-parameter-for-the-ide.adoc[] +** xref:url-parameter-for-the-ide-image.adoc[] +** xref:url-parameter-for-starting-duplicate-workspaces.adoc[] +** xref:url-parameter-for-the-existing-workspace-name.adoc[] +** xref:url-parameter-for-the-devfile-file-name.adoc[] +** xref:url-parameter-for-the-devfile-file-path.adoc[] +** xref:url-parameter-for-the-workspace-storage.adoc[] +** xref:url-parameter-for-additional-remotes.adoc[] +** xref:url-parameter-for-container-image.adoc[] +** xref:url-parameter-for-memory-limit.adoc[] +** xref:url-parameter-for-cpu-limit.adoc[] +** xref:url-parameter-for-the-ai-provider.adoc[] +* Set up your development tools +** xref:customizing-workspace-components.adoc[] +*** xref:devfile-introduction.adoc[] +** xref:ides-in-workspaces.adoc[] +*** xref:microsoft-visual-studio-code-open-source-ide.adoc[] +*** xref:connect-visual-studio-code-to-che-workspace.adoc[] +*** xref:defining-a-common-ide.adoc[] +** xref:using-ai-assistants-in-workspaces.adoc[] +*** xref:configuring-an-ai-provider-api-key.adoc[] +*** xref:changing-the-ai-tool-on-a-workspace.adoc[] diff --git a/modules/develop/pages/accessing-fuse.adoc b/modules/develop/pages/accessing-fuse.adoc new file mode 100644 index 0000000000..908d1a30b7 --- /dev/null +++ b/modules/develop/pages/accessing-fuse.adoc @@ -0,0 +1,60 @@ +:_content-type: PROCEDURE +:description: Enable access to /dev/fuse in workspace containers to use fuse-overlayfs as a storage driver for Podman. +:keywords: user-guide, fuse, overlay, device, /dev/fuse, pod, overrides +:navtitle: Access /dev/fuse in workspace containers +:page-aliases: + +[id="accessing-fuse"] += Access /dev/fuse in workspace containers + +[role="_abstract"] +Enable access to `/dev/fuse` in workspace containers to use fuse-overlayfs as a storage driver for Podman. + + +.Prerequisites + +* For {orch-name} versions older than 4.15: you have administrator-enabled access to `/dev/fuse`. See xref:administration-guide:configuring-fuse.adoc[Configuring fuse-overlayfs]. +* You have identified a workspace to use with fuse-overlayfs. + +.Procedure + +. Use the `pod-overrides` attribute to add the required annotations defined in xref:administration-guide:configuring-fuse.adoc[Configuring fuse-overlayfs] to the workspace. The `pod-overrides` attribute allows merging certain fields in the workspace pod's `spec`. ++ +*For {orch-name} versions older than 4.15:* ++ +[source,bash,subs="+quotes,+attributes,+macros"] +---- +$ {orch-cli} patch devworkspace ____ \ + --patch '{"spec":{"template":{"attributes":{"pod-overrides":{"metadata":{"annotations":{"io.kubernetes.cri-o.Devices":"/dev/fuse","io.openshift.podman-fuse":""}}}}}}}' \ + --type=merge +---- ++ +*For {orch-name} version 4.15 and later:* ++ +[source,bash,subs="+quotes,+attributes,+macros"] +---- +$ {orch-cli} patch devworkspace ____ \ + --patch '{"spec":{"template":{"attributes":{"pod-overrides":{"metadata":{"annotations":{"io.kubernetes.cri-o.Devices":"/dev/fuse"}}}}}}}' \ + --type=merge +---- + +.Verification + +. Start the workspace and verify that `/dev/fuse` is available in the workspace container: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ stat /dev/fuse +---- + +[role="_additional-resources"] +.Next steps + +* xref:enabling-overlay-with-a-configmap.adoc[] + +[role="_additional-resources"] +.Additional resources + +* xref:using-the-fuse-overlay-storage-driver.adoc[] +* xref:running-containers-with-kubedock.adoc[] +* xref:enabling-overlay-with-a-configmap.adoc[] diff --git a/modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc b/modules/develop/pages/benefits-of-pull-requests-review-in-che.adoc similarity index 50% rename from modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc rename to modules/develop/pages/benefits-of-pull-requests-review-in-che.adoc index e09b1c4fc0..288a6abee6 100644 --- a/modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc +++ b/modules/develop/pages/benefits-of-pull-requests-review-in-che.adoc @@ -1,20 +1,23 @@ :_content-type: PROCEDURE :description: {prod} workspace contains all tools you need to review pull and merge requests from start to finish. :keywords: user-guide, reviewing, pull request, merge request -:navtitle: Reviewing pull and merge requests +:navtitle: Review pull and merge requests :page-aliases: [id="title"] -= Benefits of reviewing pull and merge requests in {prod} += Review pull and merge requests [role="_abstract"] -{prod} workspace contains all tools you need to review pull and merge requests from start to finish. By clicking a {prod-short} link, you get access to {prod}-supported web IDE with a ready-to-use workspace where you can run a linter, unit tests, the build and more. +Review pull and merge requests in a {prod}-supported web IDE with a ready-to-use workspace to run a linter, unit tests, the build, and more. + .Prerequisites + * You have access to the repository hosted by your Git provider. -* You have access to a {prod-short} instance. +* You have access to an {prod-short} instance. .Procedure + . Open the feature branch to review in {prod-short}. A clone of the branch opens in a workspace with tools for debugging and testing. . Check the pull or merge request changes. . Run your desired debugging and testing tools: @@ -22,11 +25,14 @@ ** Run unit tests. ** Run the build. ** Run the application to check for problems. -. Navigate to UI of your Git provider to leave comment and pull or merge your assigned request. +. Navigate to the UI of your Git provider to leave a comment and pull or merge your assigned request. .Verification -* (optional) Open a second workspace using the main branch of the repository to reproduce a problem. +* Optional: Open a second workspace using the main branch of the repository to reproduce a problem. + +[role="_additional-resources"] +.Additional resources -// [role="_additional-resources"] -// .Additional resources +* xref:try-in-web-ide-github-action.adoc[] +* xref:first-time-contributors.adoc[] diff --git a/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc b/modules/develop/pages/changing-the-ai-tool-on-a-workspace.adoc similarity index 91% rename from modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc rename to modules/develop/pages/changing-the-ai-tool-on-a-workspace.adoc index 8d6e8c3ebe..13431bb076 100644 --- a/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc +++ b/modules/develop/pages/changing-the-ai-tool-on-a-workspace.adoc @@ -1,7 +1,7 @@ :_content-type: PROCEDURE :description: Switch or remove the AI coding assistant on a stopped workspace without recreating it. :keywords: user-guide, ai, ai tool, ai provider, workspace, change, update -:navtitle: Changing the AI tool on a workspace +:navtitle: Change the AI tool on a workspace :page-aliases: [id="changing-the-ai-tool-on-a-workspace"] @@ -12,7 +12,7 @@ Switch or remove the AI coding assistant on a stopped workspace without recreati .Prerequisites -* The workspace is stopped. +* You have a stopped workspace. .Procedure diff --git a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc b/modules/develop/pages/configuring-an-ai-provider-api-key.adoc similarity index 97% rename from modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc rename to modules/develop/pages/configuring-an-ai-provider-api-key.adoc index b0582299d9..7013e4fdb9 100644 --- a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc +++ b/modules/develop/pages/configuring-an-ai-provider-api-key.adoc @@ -1,7 +1,7 @@ :_content-type: PROCEDURE :description: Store your AI provider API key so that it is automatically available as an environment variable in all your workspaces. :keywords: user-guide, ai, api key, ai provider, environment variable, secret -:navtitle: Configuring an AI provider API key +:navtitle: Configure an AI provider API key :page-aliases: [id="configuring-an-ai-provider-api-key"] diff --git a/modules/end-user-guide/pages/connect-visual-studio-code-to-che-workspace.adoc b/modules/develop/pages/connect-visual-studio-code-to-che-workspace.adoc similarity index 95% rename from modules/end-user-guide/pages/connect-visual-studio-code-to-che-workspace.adoc rename to modules/develop/pages/connect-visual-studio-code-to-che-workspace.adoc index cf16ab617c..b187677960 100644 --- a/modules/end-user-guide/pages/connect-visual-studio-code-to-che-workspace.adoc +++ b/modules/develop/pages/connect-visual-studio-code-to-che-workspace.adoc @@ -1,6 +1,9 @@ -[id="connect-visual-studio-code-to-che-workspace"] +:_content-type: PROCEDURE +:navtitle: Connect Visual Studio Code to a {prod-short} workspace +:page-aliases: end-user-guide:connect-visual-studio-code-to-che-workspace.adoc -= Connecting Visual Studio Code to a {prod-short} workspace +[id="connect-visual-studio-code-to-che-workspace"] += Connect Visual Studio Code to a {prod-short} workspace {prod} supports connecting your desktop Visual Studio Code to a running {prod-short} workspace over link:https://code.visualstudio.com/docs/remote/tunnels/[Remote Tunnels]. diff --git a/modules/end-user-guide/pages/creating-image-pull-secrets.adoc b/modules/develop/pages/creating-image-pull-secrets.adoc similarity index 51% rename from modules/end-user-guide/pages/creating-image-pull-secrets.adoc rename to modules/develop/pages/creating-image-pull-secrets.adoc index 754a42e74c..b21363b8ee 100644 --- a/modules/end-user-guide/pages/creating-image-pull-secrets.adoc +++ b/modules/develop/pages/creating-image-pull-secrets.adoc @@ -1,13 +1,13 @@ :_content-type: ASSEMBLY -:description: To allow the `{devworkspace}` Pods in the {orch-name} cluster of your organization's {prod-short} instance to access container registries that require authentication, create an image pull Secret. +:description: Create an image pull Secret with {orch-cli} to allow DevWorkspace Pods to access container registries that require authentication. :keywords: user-guide, configuring, user, secrets -:navtitle: Creating image pull Secrets +:navtitle: Create image pull Secrets :page-aliases: [id="image-pull-secrets"] -= Creating image pull Secrets += Create image pull Secrets -To allow the `{devworkspace}` Pods in the {orch-name} cluster of your organization's {prod-short} instance to access container registries that require authentication, create an image pull Secret. +Create an image pull Secret with `{orch-cli}` to allow `{devworkspace}` Pods to access container registries that require authentication. You can create image pull Secrets by using `{orch-cli}` or a `.dockercfg` file or a `config.json` file. diff --git a/modules/end-user-guide/pages/customizing-workspace-components.adoc b/modules/develop/pages/customizing-workspace-components.adoc similarity index 73% rename from modules/end-user-guide/pages/customizing-workspace-components.adoc rename to modules/develop/pages/customizing-workspace-components.adoc index 00ac0c63f0..8b321c078b 100644 --- a/modules/end-user-guide/pages/customizing-workspace-components.adoc +++ b/modules/develop/pages/customizing-workspace-components.adoc @@ -1,19 +1,18 @@ :_content-type: PROCEDURE -:description: Customizing workspace components +:description: {prod-short} provides several options to customize your workspaces to match project requirements and team standards. :keywords: user-guide, customizing-developer-environments -:navtitle: Customizing workspace components +:navtitle: What you can customize in a Cloud Development Environment :page-aliases: configuring-a-workspace-using-a-devfile.adoc, making-a-workspace-portable-using-a-devfile.adoc, authoring-devfiles-version-1.adoc, authoring-devfiles-version-2.adoc, authoring-devfiles.adoc, defining-custom-commands-for-che-theia.adoc, adding-a-vs-code-extension-to-a-workspace.adoc, adding-a-vs-code-extension-to-the-che-plugin-registry.adoc, adding-tools-to-che-after-creating-a-workspace.adoc, using-private-container-registries.adoc, customizing-developer-environments.adoc, what-is-a-che-theia-plug-in.adoc, testing-a-visual-studio-code-extension-in-che.adoc, publishing-metadata-for-a-vs-code-extension.adoc, contributor-guide:developing-che-theia-plug-ins.adoc, contributor-guide:testing-che-theia-plug-ins.adoc, contributor-guide:publishing-che-theia-plug-ins.adoc, contributor-guide:adding-support-for-a-new-language.adoc, contributor-guide:adding-support-for-a-new-debugger.adoc, contributor-guide:che-extensibility-reference.adoc, contributor-guide:che-extension-points.adoc, contributor-guide:che-theia-plug-in-api.adoc, contributor-guide:debug-adapter-protocol.adoc, contributor-guide:language-server-protocol.adoc, customizing-workspaces-components.adoc // The application dashboard requires the presence of the `customizing-workspaces` id. [id="customizing-workspaces"] -= Customizing workspace components += What you can customize in a Cloud Development Environment -To customize workspace components: +{prod-short} provides several options to customize your workspaces to match project requirements and team standards. -* xref:starting-a-workspace-from-a-git-repository-url.adoc[Choose a Git repository for your workspace]. - -* xref:devfile-introduction.adoc[Use a devfile]. - -* xref:ides-in-workspaces.adoc[Configure an IDE]. +You can customize your {prod-short} workspaces in a variety of ways: +* Choose a Git repository for your workspace. +* Use a devfile. +* Configure an IDE. * Add {prod-short} specific attributes in addition to the generic devfile specification. diff --git a/modules/develop/pages/defining-a-common-ide.adoc b/modules/develop/pages/defining-a-common-ide.adoc new file mode 100644 index 0000000000..8fa9cd1466 --- /dev/null +++ b/modules/develop/pages/defining-a-common-ide.adoc @@ -0,0 +1,21 @@ +:_content-type: PROCEDURE +:navtitle: Define a common IDE +:description: Define a common IDE for all workspaces in a Git repository by using a che-editor.yaml file. +:keywords: select-IDE, che-editor, che-editor-yaml +:page-aliases: specifying-an-in-browser-ide-for-a-git-repository-by-using-che-editor.yaml.adoc, selecting-an-in-browser-ide-for-all-workspaces-that-clone-the-same-git-repository.adoc + +[id="defining-a-common-ide"] += Define a common IDE + +Define a common IDE for all workspaces in a Git repository by using a `che-editor.yaml` file so that all team members and new contributors use the most suitable IDE for the project. You can also use this file to override the {prod-short} instance default IDE for a particular Git repository. + +To use an IDE other than the default Microsoft Visual Studio Code - Open Source for most or all workspaces in your organization, an administrator can set `.spec.devEnvironments.defaultEditor` in the `CheCluster` Custom Resource to apply the change at the instance level. + +.Prerequisites + +* You have a project source code repository hosted on a Git provider. + +include::partial$proc_setting-up-che-editor-yaml.adoc[leveloffset=+1] + +include::partial$ref_parameters-for-che-editor-yaml.adoc[leveloffset=+1] + diff --git a/modules/end-user-guide/pages/devfile-introduction.adoc b/modules/develop/pages/devfile-introduction.adoc similarity index 94% rename from modules/end-user-guide/pages/devfile-introduction.adoc rename to modules/develop/pages/devfile-introduction.adoc index 3400c3cb8d..f45d1e5475 100644 --- a/modules/end-user-guide/pages/devfile-introduction.adoc +++ b/modules/develop/pages/devfile-introduction.adoc @@ -1,3 +1,7 @@ +:_content-type: CONCEPT +:navtitle: Introduction to devfile in {prod-short} +:page-aliases: end-user-guide:devfile-introduction.adoc + [id="introduction-to-devfile"] = Introduction to devfile in {prod-short} diff --git a/modules/develop/pages/enabling-overlay-with-a-configmap.adoc b/modules/develop/pages/enabling-overlay-with-a-configmap.adoc new file mode 100644 index 0000000000..60eed3d0d4 --- /dev/null +++ b/modules/develop/pages/enabling-overlay-with-a-configmap.adoc @@ -0,0 +1,128 @@ +:_content-type: PROCEDURE +:description: Enable fuse-overlayfs as the storage driver for Podman and Buildah by mounting a storage.conf ConfigMap into all workspaces in your namespace. +:keywords: overlay, configmap, podman, storage, driver, fuse-overlayfs +:navtitle: Enable fuse-overlayfs with a ConfigMap +:page-aliases: + +[id="enabling-fuse-overlay-with-a-configmap"] += Enable fuse-overlayfs with a ConfigMap + +[role="_abstract"] +Enable fuse-overlayfs as the storage driver for Podman and Buildah by mounting a `storage.conf` ConfigMap into all workspaces in your {orch-namespace}. + + +Here are the default contents of the `/home/user/.config/containers/storage.conf` file in the UDI container: + +[source,toml,subs="+quotes"] +---- +# storage.conf +[storage] +driver = "vfs" +---- + +To use fuse-overlayfs, `storage.conf` can be set to the following: + +[source,toml,subs="+quotes"] +---- +# storage.conf +[storage] +driver = "overlay" + +[storage.options.overlay] +mount_program="/usr/bin/fuse-overlayfs" +---- + +where: + +`mount_program`:: The absolute path to the `fuse-overlayfs` binary. The `/usr/bin/fuse-overlayfs` path is the default for the UDI. + +You can do this manually after starting a workspace. Another option is to build a new image based on the UDI with changes to `storage.conf` and use the new image for workspaces. + +Otherwise, you can update the `/home/user/.config/containers/storage.conf` for all workspaces in your {orch-namespace} by creating a ConfigMap that mounts the updated file. See xref:mounting-configmaps.adoc[]. + + +.Prerequisites + +* For {orch-name} versions older than 4.15, the administrator has enabled access to `/dev/fuse`. See xref:administration-guide:configuring-fuse.adoc[Configuring fuse-overlayfs]. +* You have a workspace with the required annotations as described in xref:accessing-fuse.adoc[]. ++ +[NOTE] +==== +ConfigMaps mounted by following xref:mounting-configmaps.adoc[this guide] apply to all workspaces and set the storage driver to fuse-overlayfs globally. Verify that your workspaces contain the required annotations to use fuse-overlayfs as described in xref:accessing-fuse.adoc[]. +==== + +.Procedure + +. Create a ConfigMap that mounts a `/home/user/.config/containers/storage.conf` file: ++ +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: fuse-overlay + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: subpath + controller.devfile.io/mount-path: /home/user/.config/containers +data: + storage.conf: | + [storage] + driver = "overlay" + + [storage.options.overlay] + mount_program = "/usr/bin/fuse-overlayfs" +---- + +. Apply the ConfigMap to your {orch-namespace}: ++ +[WARNING] +==== +Applying this ConfigMap causes all running workspaces in the {orch-namespace} to restart. +==== ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ {orch-cli} apply -f fuse-overlay.yaml -n ____ +---- + +. Start or restart your workspace. + +.Verification + +* Verify that the storage driver is `overlay`: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ podman info | grep overlay +---- ++ +Example output: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +graphDriverName: overlay + overlay.mount_program: + Executable: /usr/bin/fuse-overlayfs + Package: fuse-overlayfs-1.12-1.module+el8.9.0+20326+387084d0.x86_64 + fuse-overlayfs: version 1.12 + Backing Filesystem: overlayfs +---- + +[NOTE] +==== +The following error might occur for existing workspaces: + +`ERRO[0000] User-selected graph driver "overlay" overwritten by graph driver "vfs" from database - delete libpod local files ("/home/user/.local/share/containers/storage") to resolve. May prevent use of images created by other tools` + +In this case, delete the libpod local files shown in the error message. +==== + +[role="_additional-resources"] +.Additional resources + +* xref:using-the-fuse-overlay-storage-driver.adoc[] +* xref:running-containers-with-kubedock.adoc[] +* xref:accessing-fuse.adoc[] diff --git a/modules/develop/pages/first-time-contributors.adoc b/modules/develop/pages/first-time-contributors.adoc new file mode 100644 index 0000000000..d0afd133ba --- /dev/null +++ b/modules/develop/pages/first-time-contributors.adoc @@ -0,0 +1,39 @@ +:_content-type: PROCEDURE +:description: Badge for first-time contributors +:keywords: user-guide, first-time contributor +:navtitle: Add a factory badge for first-time contributors +:page-aliases: + +[id="using-a-badge-with-a-link-to-enable-a-first-time-contributor-to-start-a-workspace"] += Add a factory badge for first-time contributors + +[role="_abstract"] +Add a badge with a link to your {prod-short} instance to enable first-time contributors to start a workspace with a project. + + +.Factory badge +image::contribute.svg[Factory badge] + +.Prerequisites + +* You have a running {prod-short} instance. +* You have a project repository hosted on a Git provider. + +.Procedure + +* Substitute your {prod-short} URL (`pass:c,a,q[{prod-url}]`) and repository URL (`____`), and add the link to your repository in the project `README.md` file. ++ +[subs="+attributes,+macros,+quotes"] +---- +[![Contribute](https://www.eclipse.org/che/contribute.svg)](pass:c,a,q[{prod-url}]/#https://____) +---- + +.Verification + +* The `README.md` file in your Git provider web interface displays the image:contribute.svg[Factory badge] factory badge. Click the badge to open a workspace with your project in your {prod-short} instance. + +[role="_additional-resources"] +.Additional resources + +* xref:try-in-web-ide-github-action.adoc[] +* xref:benefits-of-pull-requests-review-in-che.adoc[] diff --git a/modules/end-user-guide/pages/ides-in-workspaces.adoc b/modules/develop/pages/ides-in-workspaces.adoc similarity index 78% rename from modules/end-user-guide/pages/ides-in-workspaces.adoc rename to modules/develop/pages/ides-in-workspaces.adoc index ff9b342dd7..615f375cbb 100644 --- a/modules/end-user-guide/pages/ides-in-workspaces.adoc +++ b/modules/develop/pages/ides-in-workspaces.adoc @@ -1,11 +1,13 @@ :_content-type: PROCEDURE -:description: IDEs in workspaces +:description: {prod-short} supports multiple Integrated Development Environments (IDEs) that can be used in workspaces. The default IDE is Microsoft Visual Studio Code - Open Source. :keywords: configuring, workspace, editor, ide, cloud ide -:navtitle: IDEs in workspaces +:navtitle: IDEs in Cloud Development Environments :page-aliases: [id="ides-in-workspaces"] -= IDEs in workspaces += IDEs in Cloud Development Environments + +{prod-short} supports multiple Integrated Development Environments (IDEs) that can be used in workspaces. The default IDE is Microsoft Visual Studio Code - Open Source. == Supported IDEs diff --git a/modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc b/modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc similarity index 97% rename from modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc rename to modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc index 046b3d954c..ba86a31d1b 100644 --- a/modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc +++ b/modules/develop/pages/microsoft-visual-studio-code-open-source-ide.adoc @@ -1,7 +1,7 @@ :_content-type: CONCEPT :description: Microsoft Visual Studio Code - Open Source IDE :keywords: user-guide, selecting, IDE, select, selecting, editor, ide, vs-code, visual-studio, visual-studio-code, jetbrains, intellij, pycharm, theia, che-theia -:navtitle: Microsoft Visual Studio Code - Open Source +:navtitle: Microsoft Visual Studio Code - Open Source IDE :page-aliases: [id="microsoft-visual-studio-code-open-source-ide"] diff --git a/modules/develop/pages/mounting-configmaps.adoc b/modules/develop/pages/mounting-configmaps.adoc new file mode 100644 index 0000000000..8a9aff204f --- /dev/null +++ b/modules/develop/pages/mounting-configmaps.adoc @@ -0,0 +1,136 @@ +:_content-type: PROCEDURE +:description: Mount {kubernetes} ConfigMaps into workspace containers to provide non-sensitive configuration data. +:keywords: user-guide, configuring, user, configmaps, configmap, mounting, mount +:navtitle: Mount ConfigMaps +:page-aliases: + +[id="mounting-configmaps"] += Mount ConfigMaps + +[role="_abstract"] +Mount {kubernetes} ConfigMaps into workspace containers to provide non-sensitive configuration data. + + +.Prerequisites + +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. ++ +[WARNING] +==== +By default, applying a `ConfigMap` with the `controller.devfile.io/mount-to-devworkspace: 'true'` label restarts all running workspaces in the {orch-namespace}. To mount the ConfigMap only at workspace start and prevent automatic restarts, add the `controller.devfile.io/mount-on-start: 'true'` annotation. +==== + +.Procedure + +. Create a ConfigMap with the required labels and annotations: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: my-config + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: file + controller.devfile.io/mount-path: /etc/my-config +data: + settings.json: | + { + "editor.fontSize": 14, + "editor.tabSize": 2 + } +---- ++ +where: ++ +`controller.devfile.io/mount-to-devworkspace`:: Required label to mount the ConfigMap to all workspaces. ++ +`controller.devfile.io/watch-configmap`:: Watch the ConfigMap for changes and update mounted files. ++ +`controller.devfile.io/mount-as`:: Mount type: `file`, `subpath`, or `env`. ++ +`controller.devfile.io/mount-path`:: Path where the ConfigMap data is mounted. + +. Apply the ConfigMap to your {orch-namespace}: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ {orch-cli} apply -f my-config.yaml -n ____ +---- + +. Optional: Add annotations to the ConfigMap to customize the mounting behavior. ++ +.ConfigMap mounting annotations +[cols="1,2",options="header"] +|=== +| Annotation | Description + +| `controller.devfile.io/mount-path: ____` +| Overrides the default mount path. The default mount path is `/etc/config/____`. + +| `controller.devfile.io/mount-as: file` +| Each key in the ConfigMap data becomes a file in the mount path directory. + +| `controller.devfile.io/mount-as: subpath` +| Similar to `file`, but uses subPath volumes for better compatibility. + +| `controller.devfile.io/mount-as: env` +| Each key-value pair becomes an environment variable in all workspace containers. + +| `controller.devfile.io/mount-on-start: 'true'` +| When set to `true`, the ConfigMap is mounted only when a workspace starts, not while it is already running. This prevents workspace restarts when the ConfigMap is created. + +| `controller.devfile.io/mount-to-devworkspace-include:` +| Specifies a comma-separated list of `{devworkspace}` name patterns. When set, the ConfigMap is mounted only to workspaces whose names match at least one pattern. + +| `controller.devfile.io/mount-to-devworkspace-exclude:` +| Specifies a comma-separated list of `{devworkspace}` name patterns. When set, the ConfigMap is mounted to all workspaces except those whose names match a pattern. +|=== ++ +NOTE: When both `controller.devfile.io/mount-to-devworkspace-include` and `controller.devfile.io/mount-to-devworkspace-exclude` annotations are set, the ConfigMap is mounted only to workspaces that match the include pattern and do not match the exclude pattern. ++ +For example, to mount ConfigMap data as environment variables: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: my-env-config + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: env +data: + LOG_LEVEL: debug + MAX_CONNECTIONS: "100" +---- + +. Start or restart your workspace to apply the mounted ConfigMap. + +.Verification + +* For `file` or `subpath` mounts, verify the ConfigMap data is available at the mount path: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ cat /etc/my-config/settings.json +---- + +* For `env` mounts, verify the environment variables are set: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ echo $LOG_LEVEL +---- + +[role="_additional-resources"] +.Additional resources + +* xref:using-credentials-and-configurations-in-workspaces.adoc[] +* xref:mounting-secrets.adoc[] +* xref:creating-image-pull-secrets.adoc[] diff --git a/modules/develop/pages/mounting-git-configuration.adoc b/modules/develop/pages/mounting-git-configuration.adoc new file mode 100644 index 0000000000..b1b3877b1c --- /dev/null +++ b/modules/develop/pages/mounting-git-configuration.adoc @@ -0,0 +1,74 @@ +:_content-type: PROCEDURE +:description: Mount your Git configuration into workspaces to set your Git identity and preferences. +:keywords: Git, config +:navtitle: Mount Git configuration +:page-aliases: + +[id="mounting-git-configuration"] += Mount Git configuration + +[role="_abstract"] +Mount your Git configuration into workspaces to set your Git identity and preferences. + + +[NOTE] +==== +The `user.name` and `user.email` fields are set automatically to the `gitconfig` content from a git provider that is connected to {prod-short}. This connection requires a xref:end-user-guide:using-a-git-provider-access-token.adoc[Git-provider access token] or a token generated via OAuth, and you must set the username and email on the provider's user profile page. +==== + +.Prerequisites + +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. + +.Procedure + +. Create a ConfigMap with your Git configuration: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: workspace-userdata-gitconfig-configmap + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: subpath + controller.devfile.io/mount-path: /home/user +data: + .gitconfig: | + [user] + name = Your Name + email = your.email@example.com + [core] + editor = vim + [pull] + rebase = true +---- + +. Apply the ConfigMap to your {orch-namespace}: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ {orch-cli} apply -f gitconfig.yaml -n ____ +---- + +. Start or restart your workspace. + +.Verification + +. Open a terminal in your workspace. +. Verify the Git configuration: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ git config --list +---- + +[role="_additional-resources"] +.Additional resources + +* xref:using-credentials-and-configurations-in-workspaces.adoc[] +* xref:mounting-secrets.adoc[] +* xref:creating-image-pull-secrets.adoc[] diff --git a/modules/develop/pages/mounting-secrets.adoc b/modules/develop/pages/mounting-secrets.adoc new file mode 100644 index 0000000000..f45d07a280 --- /dev/null +++ b/modules/develop/pages/mounting-secrets.adoc @@ -0,0 +1,159 @@ +:_content-type: PROCEDURE +:description: Mount {kubernetes} Secrets into workspace containers to provide sensitive configuration data such as credentials, API keys, and certificates. +:keywords: user-guide, configuring, user, configmap, secret, secrets, mounting, mount +:navtitle: Mount Secrets +:page-aliases: + +[id="mounting-secrets"] += Mount Secrets + +[role="_abstract"] +Mount {kubernetes} Secrets into workspace containers to provide sensitive configuration data such as credentials, API keys, and certificates. + + +.Prerequisites + +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. ++ +[WARNING] +==== +By default, applying a `Secret` with the `controller.devfile.io/mount-to-devworkspace: 'true'` label restarts all running workspaces in the {orch-namespace}. To mount the Secret only at workspace start and prevent automatic restarts, add the `controller.devfile.io/mount-on-start: 'true'` annotation. +==== + +.Procedure + +. Create a Secret with the required labels and annotations: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: Secret +apiVersion: v1 +metadata: + name: my-credentials + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-secret: 'true' + annotations: + controller.devfile.io/mount-as: file + controller.devfile.io/mount-path: /etc/my-credentials +type: Opaque +data: + api-key: ____ +---- ++ +where: ++ +`controller.devfile.io/mount-to-devworkspace`:: Required label to mount the Secret to all workspaces. ++ +`controller.devfile.io/watch-secret`:: Watch the Secret for changes and update mounted files. ++ +`controller.devfile.io/mount-as`:: Mount type: `file`, `subpath`, or `env`. ++ +`controller.devfile.io/mount-path`:: Path where the Secret data is mounted. + +. Apply the Secret to your {orch-namespace}: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ {orch-cli} apply -f my-credentials.yaml -n ____ +---- + +. Optional: Add annotations to the Secret to customize the mounting behavior. ++ +.Secret mounting annotations +[cols="1,2",options="header"] +|=== +| Annotation | Description + +| `controller.devfile.io/mount-path: ____` +| Overrides the default mount path. The default mount path is `/etc/secret/____`. + +| `controller.devfile.io/mount-as: file` +| Each key in the Secret data becomes a file in the mount path directory. + +| `controller.devfile.io/mount-as: subpath` +| Similar to `file`, but uses subPath volumes for better compatibility. + +| `controller.devfile.io/mount-as: env` +| Each key-value pair becomes an environment variable in all workspace containers. + +| `controller.devfile.io/mount-on-start: 'true'` +| When set to `true`, the Secret is mounted only when a workspace starts, not while it is already running. This prevents workspace restarts when the Secret is created. + +| `controller.devfile.io/mount-to-devworkspace-include:` +| Specifies a comma-separated list of `{devworkspace}` name patterns. When set, the Secret is mounted only to workspaces whose names match at least one pattern. + +| `controller.devfile.io/mount-to-devworkspace-exclude:` +| Specifies a comma-separated list of `{devworkspace}` name patterns. When set, the Secret is mounted to all workspaces except those whose names match a pattern. +|=== ++ +NOTE: When both `controller.devfile.io/mount-to-devworkspace-include` and `controller.devfile.io/mount-to-devworkspace-exclude` annotations are set, the Secret is mounted only to workspaces that match the include pattern and do not match the exclude pattern. ++ +For example, to mount Secret data as environment variables: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: Secret +apiVersion: v1 +metadata: + name: my-env-secret + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-secret: 'true' + annotations: + controller.devfile.io/mount-as: env +type: Opaque +stringData: + DATABASE_URL: postgresql://localhost:5432/mydb + API_SECRET: my-secret-key +---- ++ +For example, to mount a Maven `settings.xml` file to the `/home/user/.m2/` path using `subpath`: ++ +[source,yaml] +---- +kind: Secret +apiVersion: v1 +metadata: + name: maven-settings + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-secret: 'true' + annotations: + controller.devfile.io/mount-path: /home/user/.m2/ + controller.devfile.io/mount-as: subpath +type: Opaque +stringData: + settings.xml: | + + +---- ++ +After the workspace starts, the `/home/user/.m2/settings.xml` file is available in the `{devworkspace}` containers. To use a custom path with Maven, run `mvn --settings /home/user/.m2/settings.xml clean install`. + +. Start or restart your workspace to apply the mounted Secret. + +.Verification + +* For `file` or `subpath` mounts, verify the Secret data is available at the mount path: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ ls /etc/my-credentials +---- + +* For `env` mounts, verify the environment variables are set: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ echo $DATABASE_URL +---- + +[role="_additional-resources"] +.Additional resources + +* xref:configuring-an-ai-provider-api-key.adoc[] +* xref:using-credentials-and-configurations-in-workspaces.adoc[] +* xref:creating-image-pull-secrets.adoc[] +* xref:end-user-guide:using-a-git-provider-access-token.adoc[Use a Git provider access token] diff --git a/modules/develop/pages/mounting-ssh-configuration.adoc b/modules/develop/pages/mounting-ssh-configuration.adoc new file mode 100644 index 0000000000..31ba05cc11 --- /dev/null +++ b/modules/develop/pages/mounting-ssh-configuration.adoc @@ -0,0 +1,86 @@ +:_content-type: PROCEDURE +:description: Mount custom SSH configurations into workspaces by using a ConfigMap. +:keywords: SSH, config +:navtitle: Mount SSH configuration +:page-aliases: + +[id="mounting-ssh-configuration"] += Mount SSH configuration + +[role="_abstract"] +Mount custom SSH configurations into workspaces by using a ConfigMap. Extend the default SSH settings with additional parameters or host-specific configurations. + + +[NOTE] +==== +The system sets the default SSH configuration automatically from the SSH secret in User Preferences. You can extend it by mounting an additional `.conf` file to `/etc/ssh/ssh_config.d/`. +==== + +.Prerequisites + +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. + +.Procedure + +. Create a ConfigMap with the SSH configuration: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: workspace-userdata-sshconfig-configmap + namespace: ____ + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: subpath + controller.devfile.io/mount-path: /etc/ssh/ssh_config.d/ +data: + ssh-config.conf: | + ____ +---- ++ +where: ++ +`____`:: Your {orch-namespace} name. To find your {orch-namespace}, go to `{prod-url}/api/kubernetes/namespace`. ++ +`____`:: The SSH configuration file content, for example `Host`, `IdentityFile`, or `ProxyCommand` directives. + +. Apply the ConfigMap: ++ +[source,bash,subs="+attributes,+quotes",options="nowrap"] +---- +{orch-cli} apply -f - <__ + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: subpath + controller.devfile.io/mount-path: /etc/ssh/ssh_config.d/ +data: + ssh-config.conf: | + ____ +EOF +---- + +.Verification + +* Start a workspace and verify the SSH configuration file is mounted: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +$ cat /etc/ssh/ssh_config.d/ssh-config.conf +---- + +[role="_additional-resources"] +.Additional resources + +* xref:mounting-configmaps.adoc[] +* xref:administration-guide:configuring-a-user-namespace.adoc[Configuring a user namespace] diff --git a/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc b/modules/develop/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc similarity index 100% rename from modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc rename to modules/develop/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc diff --git a/modules/end-user-guide/pages/proc-restoring-a-workspace-from-backup.adoc b/modules/develop/pages/proc-restoring-a-workspace-from-backup.adoc similarity index 63% rename from modules/end-user-guide/pages/proc-restoring-a-workspace-from-backup.adoc rename to modules/develop/pages/proc-restoring-a-workspace-from-backup.adoc index 4ab6925206..ec845c8ee7 100644 --- a/modules/end-user-guide/pages/proc-restoring-a-workspace-from-backup.adoc +++ b/modules/develop/pages/proc-restoring-a-workspace-from-backup.adoc @@ -1,25 +1,45 @@ -:_mod-docs-content-type: PROCEDURE -[id="restoring-a-workspace-from-backup_{context}"] -= Restoring a workspace from a backup +:_content-type: PROCEDURE +:navtitle: Restore a workspace from a backup +:page-aliases: +[id="restoring-a-workspace-from-backup"] += Restore a workspace from a backup + +[role="_abstract"] Recover uncommitted changes or recreate a workspace environment by restoring from a backup snapshot through the {prod-short} dashboard. When the restoration is complete, the dashboard opens the new workspace in a browser tab. + .Prerequisites -* Backups are enabled for your cluster. -* You know which default registry or external registry backup image to use. + +* You have backups enabled for your cluster. * You have identified a default registry or external registry backup image to use. .Procedure . On the Restore page, select the backup source: -** Default registry: Select a backup from the list. -** External registry: Provide a backup image URL. ++ +-- +** *Default registry*: Select a backup from the list. +** *External registry*: Provide a backup image URL. +-- + .Restore mode and backup source selection image::workspace-backup/restore_section_1.png[Selecting the backup source during restoration,link="{imagesdir}/workspace-backup/restore_section_1.png"] + . Enter a name for the restored workspace. + . Optional: Configure the memory limits, CPU limits, and the editor. + .Resource limits and editor selection image::workspace-backup/restore_section_2.png[Configuring resources and editors for a restored workspace,link="{imagesdir}/workspace-backup/restore_section_2.png"] + . Click *Restore Workspace* and wait for the workspace to start. + +.Verification + +* Verify that the restored workspace opens in a new browser tab with the recovered source code. + +[role="_additional-resources"] +.Additional resources + +* xref:proc-viewing-backups-in-the-dashboard.adoc[] diff --git a/modules/develop/pages/proc-viewing-backups-in-the-dashboard.adoc b/modules/develop/pages/proc-viewing-backups-in-the-dashboard.adoc new file mode 100644 index 0000000000..9c6eccaaa4 --- /dev/null +++ b/modules/develop/pages/proc-viewing-backups-in-the-dashboard.adoc @@ -0,0 +1,30 @@ +:_content-type: PROCEDURE +:navtitle: View backups in the dashboard +:page-aliases: + +[id="viewing-backups-in-the-dashboard"] += View backups in the dashboard + +[role="_abstract"] +Inspect the status of your workspace backups by viewing the list of available backups in the {prod-short} dashboard. The dashboard displays backups available in the default registry set by the administrator. + + +.Prerequisites + +* You have a running {prod-short} instance. +* You have backups enabled for your cluster. + +.Procedure + +. In the {prod-short} dashboard, click *Workspaces*. +. Select the *Backups* tab to view available backups. ++ +.The Backups tab in the Workspace view +image::workspace-backup/backups_tab.png[The Backups tab in the Workspace view of the dashboard,link="{imagesdir}/workspace-backup/backups_tab.png"] ++ +The *Active* tag represents backups for workspaces that still exist in the current cluster. The *Deleted* tag represents backups for workspaces that no longer exist in the current cluster. + +[role="_additional-resources"] +.Additional resources + +* xref:proc-restoring-a-workspace-from-backup.adoc[] diff --git a/modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc b/modules/develop/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc similarity index 96% rename from modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc rename to modules/develop/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc index fde4f464a2..443a554829 100644 --- a/modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc +++ b/modules/develop/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc @@ -10,6 +10,7 @@ [role="_abstract"] Prevent a workspace from stopping while long-running CLI tools such as `helm`, `odo`, or `sleep` are active, so that unattended tasks can complete without interruption. + The CLI Watcher periodically checks for running processes that match the commands you specify. When it detects an active watched command, it resets the workspace idle timer. This configuration works entirely in user space and does not require administrator privileges. .Prerequisites @@ -30,13 +31,13 @@ watchedCommands: checkPeriodSeconds: 60 ---- + -Where: +where: + --- `enabled`:: Enables or disables the CLI Watcher. Set to `true` to activate it. ++ `watchedCommands`:: A list of command names to monitor. When any of these commands are detected as a running process, the workspace idle timer is reset. ++ `checkPeriodSeconds`:: The polling interval in seconds. The default value is `60`. --- . Place the `.noidle` file in one of the following locations, listed from highest to lowest priority: + @@ -48,7 +49,7 @@ If the CLI Watcher finds no configuration file, it waits and checks again on the .Verification -. Start a watched command in the terminal (for example, `sleep 600`). +. Start a watched command in the terminal. For example: `sleep 600`. . Verify that the workspace remains active beyond the configured idle timeout. [NOTE] diff --git a/modules/end-user-guide/pages/requesting-persistent-storage-for-workspaces.adoc b/modules/develop/pages/requesting-persistent-storage-for-workspaces.adoc similarity index 59% rename from modules/end-user-guide/pages/requesting-persistent-storage-for-workspaces.adoc rename to modules/develop/pages/requesting-persistent-storage-for-workspaces.adoc index 79290f9ad1..2dbff79200 100644 --- a/modules/end-user-guide/pages/requesting-persistent-storage-for-workspaces.adoc +++ b/modules/develop/pages/requesting-persistent-storage-for-workspaces.adoc @@ -1,17 +1,19 @@ :_content-type: PROCEDURE -:description: Requesting persistent storage for workspaces +:description: Persistent storage for workspaces :keywords: user-guide, configuring, user, volumes, persistent, volume, claim, mounting, mount -:navtitle: Requesting persistent storage for workspaces +:navtitle: Persistent storage for workspaces :page-aliases: [id="requesting-persistent-storage-for-workspaces"] -= Requesting persistent storage for workspaces += Persistent storage for workspaces -pass:[] +// vale RedHat.CaseSensitiveTerms = NO +[role="_abstract"] {prod-short} workspaces and workspace data are ephemeral and are lost when the workspace stops. -To preserve the workspace state in persistent storage while the workspace is stopped, request a {kubernetes} PersistentVolume (PV) for the `{devworkspace}` containers in the {orch-name} cluster of your organization's {prod-short} instance. + +To preserve the workspace state in persistent storage while the workspace is stopped, request a {kubernetes} PersistentVolume (PV). The PV is requested for the `{devworkspace}` containers in the {orch-name} cluster of your organization's {prod-short} instance. You can request a PV by using the devfile or a {kubernetes} PersistentVolumeClaim (PVC). @@ -21,15 +23,16 @@ Persistent Volumes come at a cost: attaching a persistent volume slows workspace [WARNING] ==== -Starting another, concurrently running workspace with a link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes[`ReadWriteOnce` PV] might fail. +Starting another, concurrently running workspace with a `ReadWriteOnce` PV might fail. ==== +[role="_additional-resources"] .Additional resources -* link:https://docs.openshift.com/container-platform/latest/storage/understanding-persistent-storage.html[Red Hat OpenShift Documentation: Understanding persistent storage] +* link:https://docs.openshift.com/container-platform/{ocp4-ver}/storage/understanding-persistent-storage.html[Red Hat OpenShift Documentation: Understanding persistent storage] * link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/[Kubernetes Documentation: Persistent Volumes] include::partial$proc_requesting-persistent-storage-in-a-devfile.adoc[leveloffset=+1] include::partial$proc_requesting-persistent-storage-in-a-pvc.adoc[leveloffset=+1] -pass:[] \ No newline at end of file +// vale RedHat.CaseSensitiveTerms = YES diff --git a/modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc b/modules/develop/pages/restoring-workspaces-from-backups.adoc similarity index 90% rename from modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc rename to modules/develop/pages/restoring-workspaces-from-backups.adoc index b320e23e5f..8d4e5df3c1 100644 --- a/modules/end-user-guide/pages/restoring-workspaces-from-backups.adoc +++ b/modules/develop/pages/restoring-workspaces-from-backups.adoc @@ -1,11 +1,11 @@ :_content-type: CONCEPT -:description: Restoring a Che workspace from a DevWorkspace backup +:description: Restore a workspace from a DevWorkspace backup :keywords: workspace, backup, restore, devworkspace, dashboard -:navtitle: Restoring workspaces from backups +:navtitle: Restore workspaces from backups :page-aliases: [id="restoring-workspaces-from-backups"] -= Restoring workspaces from backups += Restore workspaces from backups When backups are enabled for {devworkspace} instances on your cluster, a cron job backs up workspace data for stopped workspaces. diff --git a/modules/end-user-guide/pages/running-containers-with-kubedock.adoc b/modules/develop/pages/running-containers-with-kubedock.adoc similarity index 69% rename from modules/end-user-guide/pages/running-containers-with-kubedock.adoc rename to modules/develop/pages/running-containers-with-kubedock.adoc index e40ceab606..e739fbe192 100644 --- a/modules/end-user-guide/pages/running-containers-with-kubedock.adoc +++ b/modules/develop/pages/running-containers-with-kubedock.adoc @@ -1,29 +1,33 @@ :_content-type: PROCEDURE -:description: Running containers with kubedock +:description: How kubedock works :keywords: kubedock, container -:navtitle: Running containers with kubedock +:navtitle: How kubedock works :page-aliases: [id="running-containers-with-kubedock"] -= Running containers with kubedock += How kubedock works -link:https://github.com/joyrex2001/kubedock[Kubedock] is a minimal container engine implementation that gives you a Podman-/docker-like experience inside a {prod-short} workspace. Kubedock is especially useful when dealing with ad-hoc, ephemeral, and testing containers, such as in the use cases listed below: +[role="_abstract"] +Kubedock is a minimal container engine implementation that gives you a Podman-/docker-like experience inside an {prod-short} workspace. -* Executing application tests which rely on link:https://testcontainers.com/[Testcontainers] framework. -* Using link:https://quarkus.io/guides/dev-services[Quarkus Dev Services]. +Kubedock is especially useful when dealing with ad-hoc, ephemeral, and testing containers, such as in the use cases listed below: + +* Executing application tests which rely on the Testcontainers framework. + +* Using Quarkus Dev Services. * Running a container stored in remote container registry, for local development purposes [IMPORTANT] ==== -The image you want to use with kubedock must be compliant with link:https://docs.openshift.com/container-platform/{ocp4-ver}/openshift_images/create-images.html#images-create-guide-openshift_create-images[Openshift Container Platform guidelines]. -Otherwise, running the image with kubedock will result in a failure even if the same image runs locally without issues. +The image you want to use with kubedock must be compliant with {ocp} image creation guidelines. +Otherwise, running the image with kubedock results in a failure even if the same image runs locally without issues. ==== -.Enabling kubedock +== Supported commands -After enabling the kubedock environment variable, kubedock will run the following `podman` commands: +After enabling the kubedock environment variable, kubedock runs the following `podman` commands: * `podman run` * `podman ps` @@ -41,9 +45,9 @@ Other commands such as `podman build` are started by the local Podman. [IMPORTANT] ==== -Using `podman` commands with kubedock has following limitations +Using `podman` commands with kubedock has the following limitations: -* The `podman build -t . && podman run ` command will fail. Use `podman build -t . && podman push && podman run ` instead. +* The `podman build -t . && podman run ` command fails. Use `podman build -t . && podman push && podman run ` instead. * The `podman generate kube` command is not supported. * `--env` option causes the `podman run` command to fail. ==== @@ -123,3 +127,10 @@ You must configure the Podman or docker API to point to kubedock setting At the same time, you must configure Podman to point to local Podman when building the container. ==== +[role="_additional-resources"] +.Additional resources + +* link:https://github.com/joyrex2001/kubedock[Kubedock GitHub repository] +* link:https://testcontainers.com/[Testcontainers] +* link:https://quarkus.io/guides/dev-services[Quarkus Dev Services] +* link:https://docs.openshift.com/container-platform/{ocp4-ver}/openshift_images/create-images.html#images-create-guide-openshift_create-images[{ocp} image creation guidelines] diff --git a/modules/end-user-guide/pages/try-in-web-ide-github-action.adoc b/modules/develop/pages/try-in-web-ide-github-action.adoc similarity index 100% rename from modules/end-user-guide/pages/try-in-web-ide-github-action.adoc rename to modules/develop/pages/try-in-web-ide-github-action.adoc diff --git a/modules/end-user-guide/pages/url-parameter-concatenation.adoc b/modules/develop/pages/url-parameter-concatenation.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-concatenation.adoc rename to modules/develop/pages/url-parameter-concatenation.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-additional-remotes.adoc b/modules/develop/pages/url-parameter-for-additional-remotes.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-additional-remotes.adoc rename to modules/develop/pages/url-parameter-for-additional-remotes.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-container-image.adoc b/modules/develop/pages/url-parameter-for-container-image.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-container-image.adoc rename to modules/develop/pages/url-parameter-for-container-image.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-cpu-limit.adoc b/modules/develop/pages/url-parameter-for-cpu-limit.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-cpu-limit.adoc rename to modules/develop/pages/url-parameter-for-cpu-limit.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-memory-limit.adoc b/modules/develop/pages/url-parameter-for-memory-limit.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-memory-limit.adoc rename to modules/develop/pages/url-parameter-for-memory-limit.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-starting-duplicate-workspaces.adoc b/modules/develop/pages/url-parameter-for-starting-duplicate-workspaces.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-starting-duplicate-workspaces.adoc rename to modules/develop/pages/url-parameter-for-starting-duplicate-workspaces.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc b/modules/develop/pages/url-parameter-for-the-ai-provider.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc rename to modules/develop/pages/url-parameter-for-the-ai-provider.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-devfile-file-name.adoc b/modules/develop/pages/url-parameter-for-the-devfile-file-name.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-devfile-file-name.adoc rename to modules/develop/pages/url-parameter-for-the-devfile-file-name.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-devfile-file-path.adoc b/modules/develop/pages/url-parameter-for-the-devfile-file-path.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-devfile-file-path.adoc rename to modules/develop/pages/url-parameter-for-the-devfile-file-path.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-existing-workspace-name.adoc b/modules/develop/pages/url-parameter-for-the-existing-workspace-name.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-existing-workspace-name.adoc rename to modules/develop/pages/url-parameter-for-the-existing-workspace-name.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-ide-image.adoc b/modules/develop/pages/url-parameter-for-the-ide-image.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-ide-image.adoc rename to modules/develop/pages/url-parameter-for-the-ide-image.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-ide.adoc b/modules/develop/pages/url-parameter-for-the-ide.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-ide.adoc rename to modules/develop/pages/url-parameter-for-the-ide.adoc diff --git a/modules/end-user-guide/pages/url-parameter-for-the-workspace-storage.adoc b/modules/develop/pages/url-parameter-for-the-workspace-storage.adoc similarity index 100% rename from modules/end-user-guide/pages/url-parameter-for-the-workspace-storage.adoc rename to modules/develop/pages/url-parameter-for-the-workspace-storage.adoc diff --git a/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc b/modules/develop/pages/using-ai-assistants-in-workspaces.adoc similarity index 84% rename from modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc rename to modules/develop/pages/using-ai-assistants-in-workspaces.adoc index 03c84cece4..a6dfd3b958 100644 --- a/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc +++ b/modules/develop/pages/using-ai-assistants-in-workspaces.adoc @@ -1,11 +1,11 @@ :_content-type: CONCEPT -:description: Select and configure AI coding assistants for your workspaces to get AI-powered development help in the terminal. +:description: {prod-short} supports AI coding assistants that are injected into workspaces and available from the terminal. :keywords: user-guide, ai, ai assistant, ai provider, ai selector -:navtitle: Using AI assistants in workspaces +:navtitle: AI assistants in Cloud Development Environments :page-aliases: [id="using-ai-assistants-in-workspaces"] -= AI assistants in workspaces += AI assistants in Cloud Development Environments [role="_abstract"] {prod-short} supports AI coding assistants that are injected into workspaces and available from the terminal. You can select one or more AI providers when creating a workspace, and your administrator controls which providers are available. diff --git a/modules/develop/pages/using-che-in-team-workflow.adoc b/modules/develop/pages/using-che-in-team-workflow.adoc new file mode 100644 index 0000000000..3a88850447 --- /dev/null +++ b/modules/develop/pages/using-che-in-team-workflow.adoc @@ -0,0 +1,18 @@ +:_content-type: CONCEPT +:description: Team workflow with {prod-short} +:keywords: adopt, adopting, adoption +:navtitle: Team workflow with {prod-short} +//:page-aliases:adopting-che + +[id="using-che-in-team-workflow"] += Team workflow with {prod-short} + +[role="_abstract"] +Share workspace configurations with your team and simplify code review with {prod-short}. + + +Add a factory badge to your repository README so that contributors can start a pre-configured workspace with one click. You can also use the "Try in Web IDE" GitHub Action to add workspace links to pull requests. + +* xref:first-time-contributors.adoc[] +* xref:benefits-of-pull-requests-review-in-che.adoc[] +* xref:try-in-web-ide-github-action.adoc[] diff --git a/modules/develop/pages/using-credentials-and-configurations-in-workspaces.adoc b/modules/develop/pages/using-credentials-and-configurations-in-workspaces.adoc new file mode 100644 index 0000000000..8cf35afb9e --- /dev/null +++ b/modules/develop/pages/using-credentials-and-configurations-in-workspaces.adoc @@ -0,0 +1,48 @@ +:_content-type: CONCEPT +:navtitle: Credentials and configurations in workspaces +:description: Mount credentials and configurations into your workspaces so that tools such as Git, Maven, and cloud CLIs authenticate automatically without manual setup each time you start a workspace. +:keywords: user-guide, configuring, user, configmaps, secrets, volumes, mounting, mount +:page-aliases: + +[id="using-credentials-and-configurations-in-workspaces"] += Credentials and configurations in workspaces + +// vale RedHat.CaseSensitiveTerms = NO + +[role="_abstract"] +Mount credentials and configurations into your workspaces so that tools such as Git, Maven, and cloud CLIs authenticate automatically without manual setup each time you start a workspace. + + +To do so, mount your credentials and configurations to the `{devworkspace}` containers in the {orch-name} cluster of your organization's {prod-short} instance: + +* Mount your credentials and sensitive configurations as {kubernetes} Secrets. + +* Mount your non-sensitive configurations as {kubernetes} ConfigMaps. + +If you need to allow the `{devworkspace}` Pods in the cluster to access container registries that require authentication, create an image pull Secret for the `{devworkspace}` Pods. + +The mounting process uses the standard {kubernetes} mounting mechanism and requires applying additional labels and annotations to your existing resources. Resources are mounted when starting a new workspace or restarting an existing one. + +You can create permanent mount points for various components: + +* Maven configuration, such as the user-specific `settings.xml` file +* Secure Shell (SSH) key pairs +* Git-provider access tokens +* Git configuration +* AWS authorization tokens +* Configuration files +* Persistent storage + +[role="_additional-resources"] +.Additional resources + +* xref:mounting-secrets.adoc[Mounting Secrets] +* xref:mounting-configmaps.adoc[Mounting ConfigMaps] +* xref:creating-image-pull-secrets.adoc[Creating image pull Secrets] +* xref:end-user-guide:using-a-git-provider-access-token.adoc[Using a Git-provider access token] +* xref:mounting-git-configuration.adoc[Mounting Git configuration] +* link:https://maven.apache.org/settings.html[Apache Maven Settings reference] +* link:https://kubernetes.io/docs/concepts/configuration/secret/[{kubernetes} Documentation: Secrets] +* link:https://kubernetes.io/docs/concepts/configuration/configmap/[{kubernetes} Documentation: ConfigMaps] + +// vale RedHat.CaseSensitiveTerms = YES diff --git a/modules/develop/pages/using-the-fuse-overlay-storage-driver.adoc b/modules/develop/pages/using-the-fuse-overlay-storage-driver.adoc new file mode 100644 index 0000000000..5019f26310 --- /dev/null +++ b/modules/develop/pages/using-the-fuse-overlay-storage-driver.adoc @@ -0,0 +1,31 @@ +:_content-type: CONCEPT +:description: By default, newly created workspaces that do not specify a devfile use the Universal Developer Image (UDI). +:keywords: fuse, overlay, fuse-overlayfs, podman, buildah, storage, driver +:navtitle: How fuse-overlayfs works in Cloud Development Environments +:page-aliases: + +[id="using-the-fuse-overlay-storage-driver-for-podman-and-buildah"] += How fuse-overlayfs works in Cloud Development Environments + +[role="_abstract"] +By default, newly created workspaces that do not specify a devfile use the Universal Developer Image (UDI). +The UDI contains common development tools and dependencies commonly used by developers. + + +Podman and Buildah are included in the UDI, allowing developers to build and push container images from their workspace. + +By default, Podman and Buildah in the UDI are configured to use the `vfs` storage driver. +For more efficient image management, use the fuse-overlayfs storage driver which supports copy-on-write in rootless environments. + +You must meet the following requirements to use fuse-overlayfs in a workspace: + +* For {orch-name} versions older than 4.15, the administrator has enabled `/dev/fuse` access on the cluster. +* The workspace has the necessary annotations for using the `/dev/fuse` device. +* The `storage.conf` file in the workspace container is configured to use fuse-overlayfs. + +[role="_additional-resources"] +.Additional resources +* xref:accessing-fuse.adoc[Accessing /dev/fuse] +* xref:enabling-overlay-with-a-configmap.adoc[Enabling the overlay storage driver with a ConfigMap] +* xref:administration-guide:configuring-fuse.adoc[Configuring fuse-overlayfs] +* link:https://github.com/devfile/developer-images[Universal Developer Image] diff --git a/modules/end-user-guide/partials/assembly_try-in-web-ide-github-action.adoc b/modules/develop/partials/assembly_try-in-web-ide-github-action.adoc similarity index 100% rename from modules/end-user-guide/partials/assembly_try-in-web-ide-github-action.adoc rename to modules/develop/partials/assembly_try-in-web-ide-github-action.adoc diff --git a/modules/end-user-guide/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc b/modules/develop/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc similarity index 96% rename from modules/end-user-guide/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc rename to modules/develop/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc index 51ae53c771..75c227f007 100644 --- a/modules/end-user-guide/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc +++ b/modules/develop/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc @@ -3,7 +3,7 @@ // hosted-che [id="adding-the-action-to-a-github-repository-workflow"] -= Adding the action to a GitHub repository workflow += Add the action to a GitHub repository workflow This section describes how to integrate the Try in Web IDE GitHub action to a GitHub repository workflow. diff --git a/modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc b/modules/develop/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc similarity index 89% rename from modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc rename to modules/develop/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc index a00e2c5f11..3150a6b81a 100644 --- a/modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc +++ b/modules/develop/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc @@ -1,6 +1,6 @@ [id="automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup"] -= Automating installation of Microsoft Visual Studio Code extensions at workspace startup += Automate installation of Microsoft Visual Studio Code extensions at workspace startup To have the Microsoft Visual Studio Code - Open Source IDE automatically install chosen extensions, you can add an `extensions.json` file to the remote Git repository that contains your project source code and that will be cloned into workspaces. @@ -48,7 +48,7 @@ https://www.open-vsx.org/extension/____/____ .Verification -. xref:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace by using the URL of the remote Git repository] that contains the created `extensions.json` file. +. xref:end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace by using the URL of the remote Git repository] that contains the created `extensions.json` file. . In the IDE of the workspace, press kbd:[Ctrl+Shift+X] or go to *Extensions* to find each of the extensions listed in the file. . The extension has the label *This extension is enabled globally*. diff --git a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc b/modules/develop/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc similarity index 73% rename from modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc rename to modules/develop/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc index f581362b28..f4ad6e5117 100644 --- a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc +++ b/modules/develop/partials/proc_creating-an-image-pull-secret-from-a-.dockercfg-file.adoc @@ -1,13 +1,13 @@ [id="creating-an-image-pull-secret-from-a-.dockercfg-file"] -= Creating an image pull Secret from a `.dockercfg` file += Create an image pull Secret from a `.dockercfg` file If you already store the credentials for the private container registry in a `.dockercfg` file, you can use that file to create an image pull Secret. .Prerequisites -* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. -* link:https://www.gnu.org/software/coreutils/base64[`base64`] command line tools are installed in the operating system you are using. +* You have link:https://www.gnu.org/software/coreutils/base64[`base64`] command-line tools installed. .Procedure diff --git a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc b/modules/develop/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc similarity index 74% rename from modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc rename to modules/develop/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc index 794e230415..4870c135a6 100644 --- a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc +++ b/modules/develop/partials/proc_creating-an-image-pull-secret-from-a-config.json-file.adoc @@ -1,13 +1,13 @@ [id="creating-an-image-pull-secret-from-a-config.json-file"] -= Creating an image pull Secret from a `config.json` file += Create an image pull Secret from a `config.json` file If you already store the credentials for the private container registry in a `$HOME/.docker/config.json` file, you can use that file to create an image pull Secret. .Prerequisites -* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. -* link:https://www.gnu.org/software/coreutils/base64[`base64`] command line tools are installed in the operating system you are using. +* You have link:https://www.gnu.org/software/coreutils/base64[`base64`] command-line tools installed. .Procedure diff --git a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-with-cli.adoc b/modules/develop/partials/proc_creating-an-image-pull-secret-with-cli.adoc similarity index 80% rename from modules/end-user-guide/partials/proc_creating-an-image-pull-secret-with-cli.adoc rename to modules/develop/partials/proc_creating-an-image-pull-secret-with-cli.adoc index 5505fc0e97..2f46f942c6 100644 --- a/modules/end-user-guide/partials/proc_creating-an-image-pull-secret-with-cli.adoc +++ b/modules/develop/partials/proc_creating-an-image-pull-secret-with-cli.adoc @@ -1,9 +1,9 @@ [id="creating-an-image-pull-secret-with-cli"] -= Creating an image pull Secret with `{orch-cli}` += Create an image pull Secret with `{orch-cli}` .Prerequisites -* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. .Procedure diff --git a/modules/end-user-guide/partials/proc_providing-a-devfile.adoc b/modules/develop/partials/proc_providing-a-devfile.adoc similarity index 96% rename from modules/end-user-guide/partials/proc_providing-a-devfile.adoc rename to modules/develop/partials/proc_providing-a-devfile.adoc index 1b38d483b5..0d93c08b61 100644 --- a/modules/end-user-guide/partials/proc_providing-a-devfile.adoc +++ b/modules/develop/partials/proc_providing-a-devfile.adoc @@ -3,7 +3,7 @@ // hosted-che [id="providing-a-devfile"] -= Providing a devfile += Provide a devfile Providing a link:https://devfile.io/[devfile] in the root directory of the repository is recommended to define the development environment of the workspace created by the factory URL. In this way, the workspace contains everything users need to review pull requests, such as plugins, development commands, and other environment setup. diff --git a/modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-devfile.adoc b/modules/develop/partials/proc_requesting-persistent-storage-in-a-devfile.adoc similarity index 96% rename from modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-devfile.adoc rename to modules/develop/partials/proc_requesting-persistent-storage-in-a-devfile.adoc index f87004c91a..d2ce14aaab 100644 --- a/modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-devfile.adoc +++ b/modules/develop/partials/proc_requesting-persistent-storage-in-a-devfile.adoc @@ -1,5 +1,5 @@ [id="requesting-persistent-storage-in-a-devfile"] -= Requesting persistent storage in a devfile += Request persistent storage in a devfile When a workspace requires its own persistent storage, request a PersistentVolume (PV) in the devfile, and {prod-short} will automatically manage the necessary PersistentVolumeClaims. diff --git a/modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-pvc.adoc b/modules/develop/partials/proc_requesting-persistent-storage-in-a-pvc.adoc similarity index 88% rename from modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-pvc.adoc rename to modules/develop/partials/proc_requesting-persistent-storage-in-a-pvc.adoc index a5d8cc2b74..7bbdf6d311 100644 --- a/modules/end-user-guide/partials/proc_requesting-persistent-storage-in-a-pvc.adoc +++ b/modules/develop/partials/proc_requesting-persistent-storage-in-a-pvc.adoc @@ -1,5 +1,5 @@ [id="requesting-persistent-storage-in-a-pvc"] -= Requesting persistent storage in a PVC += Request persistent storage in a PVC You can opt to apply a PersistentVolumeClaim (PVC) to request a PersistentVolume (PV) for your workspaces in the following cases: @@ -13,9 +13,9 @@ TIP: You can apply a PVC to the `{devworkspace}` containers even if the workspac * You have not started the workspace. -* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. -* A PVC is created in your user {orch-namespace} to mount to all `{devworkspace}` containers. +* You have a PVC created in your user {orch-namespace} to mount to all `{devworkspace}` containers. .Procedure diff --git a/modules/end-user-guide/partials/proc_setting-up-che-editor-yaml.adoc b/modules/develop/partials/proc_setting-up-che-editor-yaml.adoc similarity index 80% rename from modules/end-user-guide/partials/proc_setting-up-che-editor-yaml.adoc rename to modules/develop/partials/proc_setting-up-che-editor-yaml.adoc index 375c67a723..2864a95885 100644 --- a/modules/end-user-guide/partials/proc_setting-up-che-editor-yaml.adoc +++ b/modules/develop/partials/proc_setting-up-che-editor-yaml.adoc @@ -1,5 +1,5 @@ [id="setting-up-che-editor-yaml"] -= Setting up che-editor.yaml += Set up che-editor.yaml By using the `che-editor.yaml` file, you can set a common default IDE for your team and provide new contributors with the most suitable IDE for your project source code. You can also use the `che-editor.yaml` file when you need to set a different IDE default for a particular source code Git repository rather than the default IDE of your organization's {prod-short} instance. @@ -9,6 +9,6 @@ By using the `che-editor.yaml` file, you can set a common default IDE for your t .Verification -. xref:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace with a clone of the Git repository]. +. xref:end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace with a clone of the Git repository]. . Verify that the specified IDE loads in the browser tab of the started workspace. diff --git a/modules/develop/partials/ref_about-try-in-web-ide-github-action.adoc b/modules/develop/partials/ref_about-try-in-web-ide-github-action.adoc new file mode 100644 index 0000000000..f44377e437 --- /dev/null +++ b/modules/develop/partials/ref_about-try-in-web-ide-github-action.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// hosted-che + + +[id="about-try-on-web-ide-github-action"] + +The Try in Web IDE GitHub action adds a factory URL to pull requests, enabling reviewers to quickly test changes in a {prod} workspace. + +[NOTE] +==== +The Che documentation repository is a real-life example where the Try in Web IDE GitHub action helps reviewers quickly test pull requests. Experience the workflow by navigating to a recent pull request and opening a factory URL. +==== + +.Pull request comment created by the Try in Web IDE GitHub action. Clicking the badge opens a new workspace for reviewers to test the pull request. +image::github-action-comment.png[Pull request comment created by the Try in Web IDE GitHub action] + +.Pull request status check created by the Try in Web IDE GitHub action. Clicking the "Details" link opens a new workspace for reviewers to test the pull request. +image::github-action-status-check.png[Pull request status check created by the Try in Web IDE GitHub action] + +Providing a devfile in the root directory of the repository is recommended to define the development environment of the workspace created by the factory URL. +In this way, the workspace contains everything users need to review pull requests, such as plugins, development commands, and other environment setup. + +The Che documentation repository devfile is an example of a well-defined and effective devfile. + +.Additional resources + +* link:https://github.com/marketplace/actions/try-in-web-ide[Try in Web IDE GitHub action] +* link:https://github.com/eclipse/che-docs[Che documentation repository] +* link:https://github.com/eclipse/che-docs/blob/main/devfile.yaml[Che documentation repository devfile] +* link:https://devfile.io/[Devfile.io] diff --git a/modules/end-user-guide/partials/ref_parameters-for-che-editor-yaml.adoc b/modules/develop/partials/ref_parameters-for-che-editor-yaml.adoc similarity index 100% rename from modules/end-user-guide/partials/ref_parameters-for-che-editor-yaml.adoc rename to modules/develop/partials/ref_parameters-for-che-editor-yaml.adoc diff --git a/modules/discover/pages/roles-and-tasks.adoc b/modules/discover/pages/roles-and-tasks.adoc index c487c1a27b..bb69b1ba93 100644 --- a/modules/discover/pages/roles-and-tasks.adoc +++ b/modules/discover/pages/roles-and-tasks.adoc @@ -31,4 +31,4 @@ Common tasks include: * Create a workspace from a Git repository. See xref:end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc[]. * Authenticate to Git servers. See xref:end-user-guide:using-a-git-provider-access-token.adoc[]. -* Configure IDE extensions. See xref:end-user-guide:microsoft-visual-studio-code-open-source-ide.adoc[]. +* Configure IDE extensions. See xref:develop:microsoft-visual-studio-code-open-source-ide.adoc[]. diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index af660602bd..eda913c5b1 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -2,51 +2,15 @@ * xref:getting-started-with-che.adoc[] ** xref:starting-a-workspace-from-a-git-repository-url.adoc[] -*** xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] -**** xref:url-parameter-concatenation.adoc[] -**** xref:url-parameter-for-the-ide.adoc[] -**** xref:url-parameter-for-the-ide-image.adoc[] -**** xref:url-parameter-for-starting-duplicate-workspaces.adoc[] -**** xref:url-parameter-for-the-devfile-file-name.adoc[] -**** xref:url-parameter-for-the-devfile-file-path.adoc[] -**** xref:url-parameter-for-the-workspace-storage.adoc[] -**** xref:url-parameter-for-additional-remotes.adoc[] -**** xref:url-parameter-for-container-image.adoc[] -**** xref:url-parameter-for-memory-limit.adoc[] -**** xref:url-parameter-for-cpu-limit.adoc[] -**** xref:url-parameter-for-the-existing-workspace-name.adoc[] -**** xref:url-parameter-for-the-ai-provider.adoc[] ** xref:starting-a-workspace-from-a-raw-devfile-url.adoc[] ** xref:basic-actions-you-can-perform-on-a-workspace.adoc[] -** xref:restoring-workspaces-from-backups.adoc[] -*** xref:proc-restoring-a-workspace-from-backup.adoc[] -*** xref:proc-viewing-backups-in-the-dashboard.adoc[] ** xref:authenticating-to-a-git-server-from-a-workspace.adoc[] -** xref:using-the-fuse-overlay-storage-driver.adoc[] -*** xref:accessing-fuse.adoc[] -*** xref:enabling-overlay-with-a-configmap.adoc[] -** xref:running-containers-with-kubedock.adoc[] -** xref:proc_preventing-workspace-idling-for-long-running-commands.adoc[] -* xref:using-che-in-team-workflow.adoc[] -** xref:first-time-contributors.adoc[] -** xref:benefits-of-pull-requests-review-in-che.adoc[] -** xref:try-in-web-ide-github-action.adoc[] -* xref:customizing-workspace-components.adoc[] -* xref:devfile-introduction.adoc[] -* xref:ides-in-workspaces.adoc[] -** xref:microsoft-visual-studio-code-open-source-ide.adoc[] -** xref:connect-visual-studio-code-to-che-workspace.adoc[] -** xref:defining-a-common-ide.adoc[] -* xref:using-ai-assistants-in-workspaces.adoc[] -** xref:configuring-an-ai-provider-api-key.adoc[] -** xref:changing-the-ai-tool-on-a-workspace.adoc[] -* xref:using-credentials-and-configurations-in-workspaces.adoc[] -** xref:mounting-secrets.adoc[] -*** xref:creating-image-pull-secrets.adoc[] -*** xref:using-a-git-provider-access-token.adoc[] -** xref:mounting-configmaps.adoc[] -*** xref:mounting-git-configuration.adoc[] -*** xref:mounting-ssh-configuration.adoc[] +* xref:integrating-with-kubernetes.adoc[] +** xref:managing-workspaces-with-apis.adoc[] +** xref:automatic-token-injection.adoc[] +** xref:navigating-che-from-openshift-developer-perspective.adoc[] +** xref:navigating-openshift-web-console-from-che.adoc[] +** xref:using-a-git-provider-access-token.adoc[] ** xref:enabling-artifact-repositories-in-a-restricted-environment.adoc[] *** xref:enabling-maven-artifact-repositories.adoc[] *** xref:enabling-gradle-artifact-repositories.adoc[] @@ -54,12 +18,6 @@ *** xref:enabling-python-artifact-repositories.adoc[] *** xref:enabling-go-artifact-repositories.adoc[] *** xref:enabling-nuget-artifact-repositories.adoc[] -* xref:requesting-persistent-storage-for-workspaces.adoc[] -* xref:integrating-with-kubernetes.adoc[] -** xref:managing-workspaces-with-apis.adoc[] -** xref:automatic-token-injection.adoc[] -** xref:navigating-che-from-openshift-developer-perspective.adoc[] -** xref:navigating-openshift-web-console-from-che.adoc[] * xref:troubleshooting-che.adoc[] ** xref:viewing-che-workspaces-logs.adoc[] *** xref:viewing-workspace-logs-in-cli.adoc[] diff --git a/modules/end-user-guide/pages/accessing-fuse.adoc b/modules/end-user-guide/pages/accessing-fuse.adoc deleted file mode 100644 index 0ae1cf5d92..0000000000 --- a/modules/end-user-guide/pages/accessing-fuse.adoc +++ /dev/null @@ -1,48 +0,0 @@ -:_content-type: PROCEDURE -:description: Accessing /dev/fuse from your workspaces. -:keywords: user-guide, fuse, overlay, device, /dev/fuse, pod, overrides -:navtitle: Accessing /dev/fuse -:page-aliases: - -[id="accessing-fuse"] -= Accessing /dev/fuse from a workspace - -You must have access to `/dev/fuse` to use fuse-overlayfs. This section describes how to make `/dev/fuse` accessible to workspace containers. - -.Prerequisites - -* For OpenShift versions older than 4.15, the administrator has enabled access to `/dev/fuse` by following xref:administration-guide:configuring-fuse.adoc[]. -* Determine a workspace to use fuse-overlayfs with. - -.Procedure - -. Use the `pod-overrides` attribute to add the required annotations defined in xref:administration-guide:configuring-fuse.adoc[] to the workspace. The `pod-overrides` attribute allows merging certain fields in the workspace pod's `spec`. -+ -For OpenShift versions older than 4.15: -+ -[subs="+quotes,+attributes,+macros"] ----- -$ {orch-cli} patch devworkspace ____ \ - --patch '{"spec":{"template":{"attributes":{"pod-overrides":{"metadata":{"annotations":{"io.kubernetes.cri-o.Devices":"/dev/fuse","io.openshift.podman-fuse":""}}}}}}}' \ - --type=merge ----- -+ -For OpenShift version 4.15 and later: -+ -[subs="+quotes,+attributes,+macros"] ----- -$ {orch-cli} patch devworkspace ____ \ - --patch '{"spec":{"template":{"attributes":{"pod-overrides":{"metadata":{"annotations":{"io.kubernetes.cri-o.Devices":"/dev/fuse"}}}}}}}' \ - --type=merge ----- - -.Verification steps - -. Start the workspace and verify that `/dev/fuse` is available in the workspace container. -+ -[subs="+attributes,+quotes"] ----- -$ stat /dev/fuse ----- - -After completing this procedure, follow the steps in xref:enabling-overlay-with-a-configmap.adoc[] to use fuse-overlayfs for Podman. diff --git a/modules/end-user-guide/pages/defining-a-common-ide.adoc b/modules/end-user-guide/pages/defining-a-common-ide.adoc deleted file mode 100644 index e8d5be354d..0000000000 --- a/modules/end-user-guide/pages/defining-a-common-ide.adoc +++ /dev/null @@ -1,17 +0,0 @@ -:_content-type: PROCEDURE -:navtitle : Defining a common IDE -:description: Defining a common IDE -:keywords: select-IDE, che-editor, che-editor-yaml -:page-aliases: specifying-an-in-browser-ide-for-a-git-repository-by-using-che-editor.yaml.adoc, selecting-an-in-browser-ide-for-all-workspaces-that-clone-the-same-git-repository.adoc - -[id="defining-a-common-ide"] -= Defining a common IDE - -While the xref:url-parameter-for-the-ide.adoc[URL parameter for the IDE] enables you to start a workspace with your personal choice of the supported IDE, you might find it more convenient to define the same IDE for all workspaces for the same source code Git repository. To do so, use the `che-editor.yaml` file. This file supports even a detailed IDE configuration. - -TIP: If you intend to start most or all of your organization's workspaces with the same IDE other than Microsoft Visual Studio Code - Open Source, an alternative is for the administrator of your organization's {prod-short} instance to specify another supported IDE as the default IDE at the {prod-short} instance level. This can be done with `.spec.devEnvironments.defaultEditor` in the `CheCluster` Custom Resource. - -include::partial$proc_setting-up-che-editor-yaml.adoc[leveloffset=+1] - -include::partial$ref_parameters-for-che-editor-yaml.adoc[leveloffset=+1] - diff --git a/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc b/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc deleted file mode 100644 index 8726c0853d..0000000000 --- a/modules/end-user-guide/pages/enabling-overlay-with-a-configmap.adoc +++ /dev/null @@ -1,107 +0,0 @@ -:_content-type: PROCEDURE -:description: You can enable fuse-overlayfs storage driver for Podman -:keywords: overlay, configmap, podman, storage, driver, fuse-overlayfs -:navtitle: Enabling fuse-overlayfs with a ConfigMap -:page-aliases: - -[id="enabling-fuse-overlay-with-a-configmap"] -= Enabling fuse-overlayfs with a Configmap - -You can define the storage driver for Podman and Buildah in the `~/.config/containers/storage.conf` file. Here are the default contents of the `/home/user/.config/containers/storage.conf` file in the UDI container: - -.`storage.conf` -[source] ----- -[storage] -driver = "vfs" ----- - -To use fuse-overlayfs, `storage.conf` can be set to the following: - -.`storage.conf` -[source] ----- -[storage] -driver = "overlay" - -[storage.options.overlay] -mount_program="/usr/bin/fuse-overlayfs" <1> ----- -<1> The absolute path to the `fuse-overlayfs` binary. The `/usr/bin/fuse-overlayfs` path is the default for the UDI. - -You can do this manually after starting a workspace. Another option is to build a new image based on the UDI with changes to `storage.conf` and use the new image for workspaces. - -Otherwise, you can update the `/home/user/.config/containers/storage.conf` for all workspaces in your {orch-namespace} by creating a ConfigMap that mounts the updated file. See xref:mounting-configmaps.adoc[]. - -.Prerequisites - -* For OpenShift versions older than 4.15, the administrator has enabled access to `/dev/fuse` by following xref:administration-guide:configuring-fuse.adoc[]. - -* A workspace with the required annotations are set by following xref:accessing-fuse.adoc[] - - -[NOTE] -==== -Since ConfigMaps mounted by following xref:mounting-configmaps.adoc[this guide] mounts the ConfigMap's data to all workspaces, following this procedure will set the storage driver to fuse-overlayfs for all workspaces. Ensure that your workspaces contain the required annotations to use fuse-overlayfs by following xref:accessing-fuse.adoc[]. -==== - -.Procedure - -. Apply a ConfigMap that mounts a `/home/user/.config/containers/storage.conf` file in your {orch-namespace}. -+ -[source,yaml,subs="+quotes,+attributes,+macros"] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: fuse-overlay - labels: - controller.devfile.io/mount-to-devworkspace: 'true' - controller.devfile.io/watch-configmap: 'true' - annotations: - controller.devfile.io/mount-as: subpath - controller.devfile.io/mount-path: /home/user/.config/containers -data: - storage.conf: | - [storage] - driver = "overlay" - - [storage.options.overlay] - mount_program="/usr/bin/fuse-overlayfs" ----- -+ -WARNING: Creating this ConfigMap will cause all of your running workspaces to restart. - -.Verification steps - -. Start the workspace containing the required annotations and verify that the storage driver is `overlay`. -+ -[subs="+attributes,+quotes"] ----- -$ podman info | grep overlay ----- - -+ -Example output: -+ -[subs="+attributes,+quotes"] ----- -graphDriverName: overlay - overlay.mount_program: - Executable: /usr/bin/fuse-overlayfs - Package: fuse-overlayfs-1.12-1.module+el8.9.0+20326+387084d0.x86_64 - fuse-overlayfs: version 1.12 - Backing Filesystem: overlayfs ----- -+ -[NOTE] -==== -The following error might occur for existing workspaces: - -[source] ----- -ERRO[0000] User-selected graph driver "overlay" overwritten by graph driver "vfs" from database - delete libpod local files ("/home/user/.local/share/containers/storage") to resolve. May prevent use of images created by other tools ----- - -In this case, delete the libpod local files as mentioned in the error message. -==== diff --git a/modules/end-user-guide/pages/first-time-contributors.adoc b/modules/end-user-guide/pages/first-time-contributors.adoc deleted file mode 100644 index d537375464..0000000000 --- a/modules/end-user-guide/pages/first-time-contributors.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:_content-type: PROCEDURE -:description: Badge for first-time contributors -:keywords: user-guide, first-time contributor -:navtitle: Badge for first-time contributors -:page-aliases: - -[id="using-a-badge-with-a-link-to-enable-a-first-time-contributor-to-start-a-workspace"] -= Using a badge with a link to enable a first-time contributor to start a workspace - -To enable a first-time contributor to start a workspace with a project, add a badge with a link to your {prod-short} instance. - -.Factory badge -image::contribute.svg[Factory badge] - -.Procedure - -. Substitute your {prod-short} URL (`pass:c,a,q[{prod-url}]`) and repository URL (`____`), and add the link to your repository in the project `README.md` file. -+ -[subs="+attributes,+macros,+quotes"] ----- -[![Contribute](https://www.eclipse.org/che/contribute.svg)](pass:c,a,q[{prod-url}]/#https://____) ----- - -. The `README.md` file in your Git provider web interface displays the image:contribute.svg[Factory badge] factory badge. Click the badge to open a workspace with your project in your {prod-short} instance. diff --git a/modules/end-user-guide/pages/getting-started-with-che.adoc b/modules/end-user-guide/pages/getting-started-with-che.adoc index 1c8d3bef3a..51393eefb2 100644 --- a/modules/end-user-guide/pages/getting-started-with-che.adoc +++ b/modules/end-user-guide/pages/getting-started-with-che.adoc @@ -10,9 +10,9 @@ If your organization is already running a {prod-short} instance, you can get started as a new user by learning how to start a new workspace, manage your workspaces, and authenticate yourself to a Git server from a workspace: * xref:starting-a-workspace-from-a-git-repository-url.adoc[] -* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] +* xref:develop:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] * xref:starting-a-workspace-from-a-raw-devfile-url.adoc[] * xref:basic-actions-you-can-perform-on-a-workspace.adoc[] -* xref:restoring-workspaces-from-backups.adoc[] +* xref:develop:restoring-workspaces-from-backups.adoc[] * xref:authenticating-to-a-git-server-from-a-workspace.adoc[] -* xref:using-the-fuse-overlay-storage-driver.adoc[] +* xref:develop:using-the-fuse-overlay-storage-driver.adoc[] diff --git a/modules/end-user-guide/pages/mounting-configmaps.adoc b/modules/end-user-guide/pages/mounting-configmaps.adoc deleted file mode 100644 index 07cc90f877..0000000000 --- a/modules/end-user-guide/pages/mounting-configmaps.adoc +++ /dev/null @@ -1,95 +0,0 @@ -:_content-type: PROCEDURE -:description: To mount non-confidential configuration data into your workspaces, use {kubernetes} ConfigMaps. -:keywords: user-guide, configuring, user, configmaps, configmap, mounting, mount -:navtitle: Mounting ConfigMaps -:page-aliases: - -[id="mounting-configmaps"] -= Mounting ConfigMaps - -To mount non-confidential configuration data into your workspaces, use {kubernetes} ConfigMaps. - -Using {kubernetes} ConfigMaps, you can mount non-sensitive data such as configuration values for an application. - -Mount {kubernetes} ConfigMaps to the `{devworkspace}` containers in the {orch-name} cluster of your organization's {prod-short} instance. - -.Prerequisites - -* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. - -* In your user {orch-namespace}, you created a new ConfigMap or determined an existing ConfigMap to mount to all `{devworkspace}` containers. - -[WARNING] -==== -By default, applying a `ConfigMap` with the `controller.devfile.io/mount-to-devworkspace: 'true'` label restarts all running workspaces in the {namespace}. To mount the ConfigMap only at workspace start and prevent automatic restarts, add the `controller.devfile.io/mount-on-start: 'true'` annotation. -==== - -.Procedure - -. Add the labels, which are required for mounting the ConfigMap, to the ConfigMap. -+ -[subs="+quotes,+attributes,+macros"] ----- -$ {orch-cli} label configmap ____ \ - controller.devfile.io/mount-to-devworkspace=true \ - controller.devfile.io/watch-configmap=true ----- - -. Optional: Use the annotations to configure how the ConfigMap is mounted. -+ -.Optional annotations -|=== -|Annotation | Description - -|`controller.devfile.io/mount-path:` -| Specifies the mount path. - -Defaults to `/etc/config/____`. - -|`controller.devfile.io/mount-as:` -| Specifies how the resource should be mounted: `file`, `subpath`, or `env`. - -Defaults to `file`. - -`mount-as:file` mounts the keys and values as files within the mount path. - -`mount-as:subpath` mounts the keys and values within the mount path using subpath volume mounts. - -`mount-as:env` mounts the keys and values as environment variables in all `{devworkspace}` containers. - -|`controller.devfile.io/mount-on-start:` -| When set to `true`, the ConfigMap is mounted only when a workspace starts, not while it is already running. - -This prevents workspace restarts when the ConfigMap is created. - -|`controller.devfile.io/mount-to-devworkspace-include:` -| Specifies a comma-separated list of `{devworkspace}` name patterns. When set, the ConfigMap is mounted only to workspaces whose names match at least one pattern. - -|`controller.devfile.io/mount-to-devworkspace-exclude:` -| Specifies a comma-separated list of `{devworkspace}` name patterns. When set, the ConfigMap is mounted to all workspaces except those whose names match a pattern. - -|=== - -.Mounting a ConfigMap as environment variables -==== -[source,yaml,subs="+quotes"] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: my-settings - labels: - controller.devfile.io/mount-to-devworkspace: 'true' - controller.devfile.io/watch-configmap: 'true' - annotations: - controller.devfile.io/mount-as: env -data: - ____: ____ - ____: ____ ----- - -When you start a workspace, the `____` and `____` environment variables will be available in the `{devworkspace}` containers. -==== - -.Additional resources -* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets] diff --git a/modules/end-user-guide/pages/mounting-git-configuration.adoc b/modules/end-user-guide/pages/mounting-git-configuration.adoc deleted file mode 100644 index bfd075b00a..0000000000 --- a/modules/end-user-guide/pages/mounting-git-configuration.adoc +++ /dev/null @@ -1,58 +0,0 @@ -:_content-type: PROCEDURE -:description: Mounting Git configuration -:keywords: Git, config -:navtitle: Mounting Git configuration -:page-aliases: - -[id="mounting-git-configuration"] -= Mounting Git configuration - -[NOTE] -==== -The `user.name` and `user.email` fields will be set automatically to the `gitconfig` content from a git provider, connected to {prod-short} by a xref:using-a-git-provider-access-token.adoc[Git-provider access token] or a token generated via OAuth, if username and email are set on the provider's user profile page. -==== -Follow the instructions below to mount a Git config file in a workspace. - -.Prerequisites - -* You have logged in to the cluster. - -.Procedure - -. Prepare a new {orch-name} ConfigMap. -+ -[source,yaml,subs="+quotes,+attributes,+macros"] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: workspace-userdata-gitconfig-configmap - namespace: ____ <1> - labels: - controller.devfile.io/mount-to-devworkspace: 'true' - controller.devfile.io/watch-configmap: 'true' - annotations: - controller.devfile.io/mount-as: subpath - controller.devfile.io/mount-path: /etc/ -data: - gitconfig: <2> ----- -+ -<1> A user namespace. Visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. -<2> The content of your gitconfig file content. - -. Apply the ConfigMap. -+ -[source,subs="+quotes,+attributes"] ----- -$ {orch-cli} apply -f - <__ -EOF ----- - -.Verification - -. xref:starting-a-workspace-from-a-git-repository-url.adoc[Start a new workspace by using the URL of a remote Git repository] that the Git provider hosts. -. Once the workspace is started, open a new terminal in the `tools` container and run `git config --get-regexp user.*`. Your Git user name and email should appear in the output. - - diff --git a/modules/end-user-guide/pages/mounting-secrets.adoc b/modules/end-user-guide/pages/mounting-secrets.adoc deleted file mode 100644 index f21f96482a..0000000000 --- a/modules/end-user-guide/pages/mounting-secrets.adoc +++ /dev/null @@ -1,106 +0,0 @@ -:_content-type: PROCEDURE -:description: To mount confidential data into your workspaces, use {kubernetes} Secrets. -:keywords: user-guide, configuring, user, configmap, secret, secrets, mounting, mount -:navtitle: Mounting Secrets -:page-aliases: - -[id="mounting-secrets"] -= Mounting Secrets - -To mount confidential data into your workspaces, use {kubernetes} Secrets. - -Using {kubernetes} Secrets, you can mount usernames, passwords, SSH key pairs, authentication tokens (for example, for AWS), and sensitive configurations. - -Mount {kubernetes} Secrets to the `{devworkspace}` containers in the {orch-name} cluster of your organization's {prod-short} instance. - -.Prerequisites - -* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. - -* In your user {orch-namespace}, you created a new Secret or determined an existing Secret to mount to all `{devworkspace}` containers. - -[WARNING] -==== -By default, applying a `Secret` with the `controller.devfile.io/mount-to-devworkspace: 'true'` label restarts all running workspaces in the {namespace}. To mount the Secret only at workspace start and prevent automatic restarts, add the `controller.devfile.io/mount-on-start: 'true'` annotation. -==== - -.Procedure - -. Add the labels, which are required for mounting the Secret, to the Secret. -+ -[subs="+quotes,+attributes,+macros"] ----- -$ {orch-cli} label secret ____ \ - controller.devfile.io/mount-to-devworkspace=true \ - controller.devfile.io/watch-secret=true ----- - -. Optional: Use the annotations to configure how the Secret is mounted. -+ -.Optional annotations -|=== -|Annotation | Description - -|`controller.devfile.io/mount-path:` -| Specifies the mount path. - -Defaults to `/etc/secret/____`. - -|`controller.devfile.io/mount-as:` -| Specifies how the resource should be mounted: `file`, `subpath`, or `env`. - -Defaults to `file`. - -`mount-as: file` mounts the keys and values as files within the mount path. - -`mount-as: subpath` mounts the keys and values within the mount path using subpath volume mounts. - -`mount-as: env` mounts the keys and values as environment variables in all `{devworkspace}` containers. - -|`controller.devfile.io/mount-on-start:` -| When set to `true`, the Secret is mounted only when a workspace starts, not while it is already running. - -This prevents workspace restarts when the Secret is created. - -|`controller.devfile.io/mount-to-devworkspace-include:` -| Specifies a comma-separated list of `{devworkspace}` name patterns. When set, the Secret is mounted only to workspaces whose names match at least one pattern. - -|`controller.devfile.io/mount-to-devworkspace-exclude:` -| Specifies a comma-separated list of `{devworkspace}` name patterns. When set, the Secret is mounted to all workspaces except those whose names match a pattern. - -|=== - -.Mounting a Secret as a file -==== - -[source,yaml,subs="+quotes,+attributes"] ----- -apiVersion: v1 -kind: Secret -metadata: - name: mvn-settings-secret - labels: - controller.devfile.io/mount-to-devworkspace: 'true' - controller.devfile.io/watch-secret: 'true' - annotations: - controller.devfile.io/mount-path: '/home/user/.m2' -data: - settings.xml: ____ ----- - -When you start a workspace, the `/home/user/.m2/settings.xml` file will be available in the `{devworkspace}` containers. - -With Maven, you can set a custom path for the `settings.xml` file. -For example: -[subs="+quotes,+attributes"] ----- -$ mvn --settings /home/user/.m2/settings.xml clean install ----- - -==== - - -.Additional resources - -* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets] -* xref:configuring-an-ai-provider-api-key.adoc[] (the {prod-short} dashboard uses this same auto-mount mechanism to inject AI provider API keys into workspaces) diff --git a/modules/end-user-guide/pages/mounting-ssh-configuration.adoc b/modules/end-user-guide/pages/mounting-ssh-configuration.adoc deleted file mode 100644 index b4a71d1509..0000000000 --- a/modules/end-user-guide/pages/mounting-ssh-configuration.adoc +++ /dev/null @@ -1,54 +0,0 @@ -:_content-type: PROCEDURE -:description: Mounting SSH configuration -:keywords: SSH, config -:navtitle: Mounting SSH configuration -:page-aliases: - -[id="mounting-ssh-configuration"] -= Mounting SSH configuration - -[role="_abstract"] -This procedure describes how to mount custom SSH configurations into your workspaces. By creating and applying a **ConfigMap**, you can extend the default SSH settings with additional parameters or host-specific configurations. This ensures that your development environment maintains consistent connectivity to remote repositories and servers. Use this method to automate the propagation of SSH credentials and settings across multiple workspaces within your cluster. - -[NOTE] -==== -The system sets the default SSH configuration automatically based on the `ssh_config` content from the SSH secret added in the **User Preferences** menu. You can extend this configuration by mounting an additional SSH configuration file with a `.conf` extension to the `/etc/ssh/ssh_config.d/` directory. -==== -To mount an SSH configuration file in a workspace, complete the following steps. - -.Prerequisites - -* You are logged in to the cluster. - -.Procedure - -. Create a new {orch-name} **ConfigMap**. -+ -[source,yaml,subs="+quotes,+attributes,+macros"] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: workspace-userdata-sshconfig-configmap - namespace: ____ <1> - labels: - controller.devfile.io/mount-to-devworkspace: 'true' - controller.devfile.io/watch-configmap: 'true' - annotations: - controller.devfile.io/mount-as: subpath - controller.devfile.io/mount-path: /etc/ssh/ssh_config.d/ -data: - ssh-config.conf: <2> ----- -+ -<1> A user namespace. Visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to retrieve your {prod-short} user namespace `name`. -<2> The content of your SSH configuration file. - -. Apply the **ConfigMap**. -+ -[source,subs="+quotes,+attributes"] ----- -$ {orch-cli} apply -f - <__ -EOF ----- diff --git a/modules/end-user-guide/pages/proc-viewing-backups-in-the-dashboard.adoc b/modules/end-user-guide/pages/proc-viewing-backups-in-the-dashboard.adoc deleted file mode 100644 index e0ae5c77fb..0000000000 --- a/modules/end-user-guide/pages/proc-viewing-backups-in-the-dashboard.adoc +++ /dev/null @@ -1,17 +0,0 @@ -:_mod-docs-content-type: PROCEDURE -[id="viewing-backups-in-the-dashboard_{context}"] -= Viewing backups in the dashboard - -To inspect the status of your workspace backups, view the list of available backups in the {prod-short} dashboard. -Backups displayed in the {prod-short} dashboard are backups available in the default registry set by the administrator. - -.Procedure - -. In the {prod-short} dashboard, click Workspace. -. In the {prod-short} dashboard, click *Workspaces*. -. Select the *Backups* tab to view available backups. - -.The Backups tab in the Workspace view -image::workspace-backup/backups_tab.png[The Backups tab in the Workspace view of the dashboard,link="{imagesdir}/workspace-backup/backups_tab.png"] - -The *Active* tag represents backups for workspaces that still exist in the current cluster. Conversely, the *Deleted* tag represents backups for workspaces that no longer exist in the current cluster. \ No newline at end of file diff --git a/modules/end-user-guide/pages/starting-a-workspace-from-a-git-repository-url.adoc b/modules/end-user-guide/pages/starting-a-workspace-from-a-git-repository-url.adoc index b04364aa3e..6f7d7060d9 100644 --- a/modules/end-user-guide/pages/starting-a-workspace-from-a-git-repository-url.adoc +++ b/modules/end-user-guide/pages/starting-a-workspace-from-a-git-repository-url.adoc @@ -40,7 +40,7 @@ Configure personal access token to access private repositories. See xref:using-a * Your organization has a running instance of {prod-short}. * You know the FQDN URL of your organization's {prod-short} instance: `pass:c,a,q[{prod-url}]`. * Optional: You have xref:authenticating-to-a-git-server-from-a-workspace.adoc[authentication to the Git server] configured. -* Your Git repository maintainer keeps the `devfile.yaml` or `.devfile.yaml` file in the root directory of the Git repository. (For alternative file names and file paths, see xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[].) +* Your Git repository maintainer keeps the `devfile.yaml` or `.devfile.yaml` file in the root directory of the Git repository. (For alternative file names and file paths, see xref:develop:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[].) + TIP: You can also start a new workspace by supplying the URL of a Git repository that contains no devfile. Doing so results in a workspace with Universal Developer Image and with Microsoft Visual Studio Code - Open Source as the workspace IDE. //provide a link to a page about the Universal Developer Image similar to https://developers.redhat.com/products/rhel/ubi for UBI and, if applicable, devfile-less defaults for new workspaces. max-cx @@ -65,7 +65,7 @@ You can extend this URL with optional parameters: ---- pass:c,a,q[{prod-url}]#____?____ <1> ---- -<1> See xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]. +<1> See xref:develop:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]. ==== + [TIP] @@ -128,8 +128,8 @@ The workspace has a unique URL: `pass:c,a,q[{prod-url}]/____/__] +// vale RedHat.Spelling = NO TIP: You can use the *Git Repo URL* field on the *Create Workspace* page of your {prod-short} dashboard to enter the URL of a *devfile* to start a new workspace. -pass:[] +// vale RedHat.Spelling = YES [IMPORTANT] ==== @@ -64,7 +64,7 @@ You can extend this URL with optional parameters: ---- pass:c,a,q[{prod-url}]#____?____ <1> ---- -<1> See xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]. +<1> See xref:develop:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]. ==== + .A URL for starting a new workspace from a public repository @@ -89,8 +89,8 @@ The workspace has a unique URL: `pass:c,a,q[{prod-url}]/____/__] +// vale RedHat.CaseSensitiveTerms = NO OAuth for GitHub, GitLab, Bitbucket, or Microsoft Azure Repos needs to be xref:administration-guide:configuring-oauth-for-git-providers.adoc[configured by the administrator] of your organization's {prod-short} instance. If your administrator could not configure it for {prod-short} users, the workaround is for you to use a personal access token. You can configure personal access tokens on the *User Preferences* page of your {prod-short} dashboard: `pass:c,a,q[{prod-url}]/dashboard/#/user-preferences?tab=personal-access-tokens`, or apply it manually as a {kubernetes} Secret in the namespace. @@ -119,7 +119,7 @@ EOF [IMPORTANT] ==== -If you are using Azure DevOps Server, you must also modify the xref:mounting-git-configuration.adoc[workspace's +If you are using Azure DevOps Server, you must also modify the xref:develop:mounting-git-configuration.adoc[workspace's gitconfig] with the following section: [source,http] @@ -147,7 +147,7 @@ The `extraheader` configuration is needed for remote git operations to Azure Dev * xref:administration-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[Deploying Che with support for Git repositories with self-signed certificates] * link:https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on[Authorizing a personal access token for use with SAML single sign-on] -pass:[] +// vale RedHat.CaseSensitiveTerms = YES diff --git a/modules/end-user-guide/pages/using-che-in-team-workflow.adoc b/modules/end-user-guide/pages/using-che-in-team-workflow.adoc deleted file mode 100644 index 00a9670c43..0000000000 --- a/modules/end-user-guide/pages/using-che-in-team-workflow.adoc +++ /dev/null @@ -1,14 +0,0 @@ -:_content-type: CONCEPT -:description: Using {prod-short} in team workflow -:keywords: adopt, adopting, adoption -:navtitle: Using {prod-short} in team workflow -//:page-aliases:adopting-che - -[id="using-che-in-team-workflow"] -= Using {prod-short} in team workflow - -Learn about the benefits of using {prod-short} in your organization in the following articles: - -* xref:first-time-contributors.adoc[] -* xref:benefits-of-pull-requests-review-in-che.adoc[] - diff --git a/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc b/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc deleted file mode 100644 index 3e6e5afdfa..0000000000 --- a/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc +++ /dev/null @@ -1,40 +0,0 @@ -:_content-type: CONCEPT -:navtitle: Using credentials and configurations in workspaces -:description: Using credentials and configurations in workspaces -:keywords: user-guide, configuring, user, configmaps, secrets, volumes, mounting, mount -:page-aliases: - -[id="using-credentials-and-configurations-in-workspaces"] -= Using credentials and configurations in workspaces - -pass:[] - -You can use your credentials and configurations in your workspaces. - -To do so, mount your credentials and configurations to the `{devworkspace}` containers in the {orch-name} cluster of your organization's {prod-short} instance: - -* Mount your credentials and sensitive configurations as {kubernetes} xref:mounting-secrets.adoc[Secrets]. - -* Mount your non-sensitive configurations as {kubernetes} xref:mounting-configmaps.adoc[ConfigMaps]. - -If you need to allow the `{devworkspace}` Pods in the cluster to access container registries that require authentication, create an xref:creating-image-pull-secrets.adoc[image pull Secret] for the `{devworkspace}` Pods. - -The mounting process uses the standard {kubernetes} mounting mechanism and requires applying additional labels and annotations to your existing resources. Resources are mounted when starting a new workspace or restarting an existing one. - -You can create permanent mount points for various components: - -* Maven configuration, such as the link:https://maven.apache.org/settings.html[user-specific] `settings.xml` file -* SSH key pairs -* xref:using-a-git-provider-access-token.adoc[Git-provider access tokens] -* xref:mounting-git-configuration.adoc[Git configuration] -* AWS authorization tokens -* Configuration files -* Persistent storage -* xref:configuring-an-ai-provider-api-key.adoc[AI provider API keys] for AI coding assistants such as Gemini or Claude - -.Additional resources - -* link:https://kubernetes.io/docs/concepts/configuration/secret/[Kubernetes Documentation: Secrets] -* link:https://kubernetes.io/docs/concepts/configuration/configmap/[Kubernetes Documentation: ConfigMaps] - -pass:[] diff --git a/modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc b/modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc deleted file mode 100644 index 54ec0af6f5..0000000000 --- a/modules/end-user-guide/pages/using-the-fuse-overlay-storage-driver.adoc +++ /dev/null @@ -1,25 +0,0 @@ -:_content-type: CONCEPT -:description: Using the fuse-overlayfs storage driver for Podman and Buildah -:keywords: fuse, overlay, fuse-overlayfsm, podman, buildah, storage, driver -:navtitle: Using the fuse-overlayfs storage driver for Podman and Buildah -:page-aliases: - -[id="using-the-fuse-overlay-storage-driver-for-podman-and-buildah"] -= Using the fuse-overlayfs storage driver for Podman and Buildah - -By default, newly created workspaces that do not specify a devfile will use the Universal Developer Image (UDI). -The UDI contains common development tools and dependencies commonly used by developers. - -Podman and Buildah are included in the UDI, allowing developers to build and push container images from their workspace. - -By default, Podman and Buildah in the UDI are configured to use the `vfs` storage driver. -For more efficient image management, use the fuse-overlayfs storage driver which supports copy-on-write in rootless environments. - -You must meet the following requirements to use fuse-overlayfs in a workspace: - -. For OpenShift versions older than 4.15, the administrator has enabled `/dev/fuse` access on the cluster by following xref:administration-guide:configuring-fuse.adoc[]. -. The workspace has the necessary annotations for using the `/dev/fuse` device. See xref:accessing-fuse.adoc[]. -. The `storage.conf` file in the workspace container has been configured to use fuse-overlayfs. See xref:enabling-overlay-with-a-configmap.adoc[]. - -.Additional resources -* link:https://github.com/devfile/developer-images[Universal Developer Image] diff --git a/modules/end-user-guide/partials/ref_about-try-in-web-ide-github-action.adoc b/modules/end-user-guide/partials/ref_about-try-in-web-ide-github-action.adoc deleted file mode 100644 index 198cb09cf4..0000000000 --- a/modules/end-user-guide/partials/ref_about-try-in-web-ide-github-action.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// hosted-che - - -[id="about-try-on-web-ide-github-action"] - -The link:https://github.com/marketplace/actions/try-in-web-ide[Try in Web IDE GitHub action] can be added to a GitHub repository workflow to help reviewers quickly test pull requests on Eclipse Che hosted by Red Hat. -The action achieves this by listening to pull request events and providing a factory URL by creating a comment, a status check, or both. -This factory URL creates a new workspace from the pull request branch on Eclipse Che hosted by Red Hat. - -NOTE: The Che documentation repository (https://github.com/eclipse/che-docs) is a real-life example where the Try in Web IDE GitHub action helps reviewers quickly test pull requests. Experience the workflow by navigating to a recent pull request and opening a factory URL. - -.Pull request comment created by the Try in Web IDE GitHub action. Clicking the badge opens a new workspace for reviewers to test the pull request. -image::github-action-comment.png[test] - -.Pull request status check created by the Try in Web IDE GitHub action. Clicking the "Details" link opens a new workspace for reviewers to test the pull request. -image::github-action-status-check.png[test]