diff --git a/antora.yml b/antora.yml index b9bc4318b7..0dd2d0a21d 100644 --- a/antora.yml +++ b/antora.yml @@ -7,7 +7,8 @@ start_page: discover:what-is-che.adoc nav: - modules/discover/nav.adoc - modules/install/nav.adoc - - modules/get-started/nav.adoc + - modules/get-started-admin/nav.adoc + - modules/get-started-user/nav.adoc - modules/troubleshoot/nav.adoc - modules/end-user-guide/nav.adoc - modules/upgrade/nav.adoc diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 1150670d1f..28bc8bf1b6 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -1,5 +1,6 @@ .User Guide +* xref:starting-a-workspace-from-a-raw-devfile-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[] @@ -38,7 +39,7 @@ * xref:using-credentials-and-configurations-in-workspaces.adoc[] ** xref:mounting-secrets.adoc[] *** xref:creating-image-pull-secrets.adoc[] -*** xref:get-started:using-a-git-provider-access-token.adoc[] +*** xref:get-started-user:using-a-git-provider-access-token.adoc[] ** xref:mounting-configmaps.adoc[] *** xref:mounting-git-configuration.adoc[] *** xref:mounting-ssh-configuration.adoc[] diff --git a/modules/end-user-guide/pages/starting-a-workspace-from-a-raw-devfile-url.adoc b/modules/end-user-guide/pages/starting-a-workspace-from-a-raw-devfile-url.adoc new file mode 100644 index 0000000000..fdc5a6c33b --- /dev/null +++ b/modules/end-user-guide/pages/starting-a-workspace-from-a-raw-devfile-url.adoc @@ -0,0 +1,76 @@ +:_content-type: PROCEDURE +:description: Start a cloud development environment from a raw devfile URL +:keywords: start-new-workspace, start-a-new-workspace, how-to-start-new-workspace, how-to-start-a-new-workspace, starting-a-new-workspace, how-to-start-workspace, how-to-start-a-workspace +:navtitle: Start a cloud development environment from a raw devfile URL +:page-aliases: get-started:starting-a-workspace-from-a-raw-devfile-url.adoc + +[id="starting-a-workspace-from-a-raw-devfile-url"] += Start a cloud development environment from a raw devfile URL + +[role="_abstract"] +Start a cloud development environment from a devfile hosted outside your Git repository so that you can share a standard development environment across teams or test devfile changes before committing them. + +// vale RedHat.Spelling = NO + +TIP: You can also 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 cloud development environment. + +// vale RedHat.Spelling = YES + +.Prerequisites + +* You have a running instance of {prod-short}. +* You know the Fully Qualified Domain Name (FQDN) URL of your organization's {prod-short} instance: `pass:c,a,q[{prod-url}]`. +* You have a devfile that includes project information to clone the Git repository. See https://devfile.io/docs/2.2.0/adding-projects. + +.Procedure + +. Optional: Open the {prod-short} dashboard to authenticate to your organization's instance of {prod-short}. + +. Enter the devfile URL in your browser to start a new cloud development environment. ++ +For a public repository: ++ +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#____ +---- ++ +For a private repository, include your personal access token in the URL: ++ +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#__https://____@____/__ +---- ++ +where: ++ +`____`:: Your personal access token that you generated on the Git provider's website. This method works for GitHub, GitLab, Bitbucket, Microsoft Azure, and other providers that support Personal Access Token. ++ +[IMPORTANT] +==== +Automated Git credential injection does not work with token-embedded URLs. To configure Git credentials separately, see xref:get-started-user:using-a-git-provider-access-token.adoc[]. +==== ++ +To append optional parameters, add `?____` to the URL. See xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for cloud development environment URLs] for supported parameters. ++ +For example: ++ +* Public repository: `pass:c,a,q[{prod-url}#https://raw.githubusercontent.com/che-samples/cpp-hello-world/main/devfile.yaml]` +* Private repository: `pass:c,a,q[{prod-url}#https://____@raw.githubusercontent.com/che-samples/cpp-hello-world/main/devfile.yaml]` + +.Verification + +* After you enter the URL, the starting page is displayed in the browser tab. +* When the cloud development environment is ready, the IDE loads automatically. +* The cloud development environment has a unique URL: `pass:c,a,q[{prod-url}]/____/____`. + +[role="_additional-resources"] +.Additional resources + +* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for cloud development environment URLs] +* xref:get-started-user:basic-actions-you-can-perform-on-a-workspace.adoc[] +* xref:get-started-user:using-a-git-provider-access-token.adoc[] +* xref:mounting-git-configuration.adoc[] +// vale RedHat.GitLinks = NO +* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] +// vale RedHat.GitLinks = YES diff --git a/modules/get-started-admin/nav.adoc b/modules/get-started-admin/nav.adoc new file mode 100644 index 0000000000..90f8f5f4da --- /dev/null +++ b/modules/get-started-admin/nav.adoc @@ -0,0 +1,6 @@ +.Get Started as an Administrator +* Prepare the platform for developers +** xref:your-first-week-as-administrator.adoc[] +** xref:verify-the-platform-end-to-end.adoc[] +** xref:configure-github-oauth-for-your-team.adoc[] +** xref:what-to-configure-next.adoc[] diff --git a/modules/get-started-admin/pages/configure-github-oauth-for-your-team.adoc b/modules/get-started-admin/pages/configure-github-oauth-for-your-team.adoc new file mode 100644 index 0000000000..e7d80ea128 --- /dev/null +++ b/modules/get-started-admin/pages/configure-github-oauth-for-your-team.adoc @@ -0,0 +1,71 @@ +:_content-type: PROCEDURE +:description: Configure GitHub OAuth for your team +:keywords: github, oauth, authentication, credentials +:navtitle: Configure GitHub OAuth for your team + +[id="configure-github-oauth-for-your-team"] += Configure GitHub OAuth for your team + +[role="_abstract"] +Configure a GitHub OAuth application so that developers can clone repositories and push code from {prod-short} workspaces without manually entering credentials. This procedure covers GitHub.com and GitHub Enterprise Cloud. For other providers, see the Additional resources. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. +* You are logged in to GitHub with an account that has permission to create OAuth applications for your organization. + +.Procedure + +. Go to the link:https://github.com/settings/applications/new[GitHub OAuth application registration page]. + +. Enter the following values: ++ +.. *Application name*: `pass:c,a,q[{prod-short}]` +.. *Homepage URL*: `pass:c,a,q[{prod-url}]/` +.. *Authorization callback URL*: `pass:c,a,q[{prod-url}]/api/oauth/callback` + +. Click *Register application*. + +. Click *Generate new client secret*. + +. Copy the *Client ID* and the *Client Secret*. You need both values in the next step. + +. Prepare and apply the {orch-name} Secret: ++ +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +kind: Secret +apiVersion: v1 +metadata: + name: github-oauth-config + namespace: {prod-namespace} + labels: + app.kubernetes.io/part-of: che.eclipse.org + app.kubernetes.io/component: oauth-scm-configuration + annotations: + che.eclipse.org/oauth-scm-server: github +type: Opaque +stringData: + id: ____ + secret: ____ +---- + +. Apply the Secret: ++ +[source,bash,subs="+quotes,+attributes"] +---- +$ {orch-cli} apply -f - < +EOF +---- + +.Verification + +* The output displays `secret/github-oauth-config created`. +* A developer creates a new workspace from a private GitHub repository and is not prompted for credentials. + +[role="_additional-resources"] +.Additional resources + +* xref:administration-guide:configuring-oauth-for-git-providers.adoc[Connect Git providers with OAuth for GitHub, GitLab, Bitbucket, and Azure DevOps] +* link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub Docs: Creating an OAuth App] diff --git a/modules/get-started-admin/pages/verify-the-platform-end-to-end.adoc b/modules/get-started-admin/pages/verify-the-platform-end-to-end.adoc new file mode 100644 index 0000000000..3db3d9a2c4 --- /dev/null +++ b/modules/get-started-admin/pages/verify-the-platform-end-to-end.adoc @@ -0,0 +1,62 @@ +:_content-type: PROCEDURE +:description: Verify the platform works end-to-end +:keywords: verify, installation, dashboard, test workspace +:navtitle: Verify the platform works end-to-end + +[id="verify-the-platform-end-to-end"] += Verify the platform works end-to-end + +[role="_abstract"] +Verify that {prod-short} is operational by checking the Operator status, opening the dashboard, and creating a test workspace. This confirms that the full pipeline works before you invite developers. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. +* You have installed {prod-short} on an {orch-name} cluster. See xref:install:installing-che.adoc[Install {prod-short}]. + +.Procedure + +. Verify that the {prod-short} Operator pod is running: ++ +[source,bash,subs="+attributes"] +---- +$ {orch-cli} get pods -n {prod-namespace} -l app.kubernetes.io/component={prod-id-short}-operator +---- + +. Verify that the `CheCluster` custom resource reports no errors: ++ +[source,bash,subs="+attributes"] +---- +$ {orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.chePhase}' +---- ++ +The expected output is `Active`. + +. Retrieve the {prod-short} dashboard URL: ++ +[source,bash,subs="+attributes"] +---- +$ {orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.cheURL}' +---- + +. Open the URL in a web browser and log in with your {orch-name} credentials. + +. On the *Create Workspace* page, click any sample (for example, *Python*) to start a test workspace. + +. Wait for the workspace to start. The first start takes 2-3 minutes while container images are pulled to the cluster node. + +. Confirm that the IDE loads in your browser tab and that you can open a terminal. + +. Return to the *Workspaces* page and stop the test workspace by selecting *⋮* > *Stop Workspace*. + +.Verification + +* The {prod-short} dashboard loads and displays the *Create Workspace* page. +* A test workspace starts and the IDE loads in the browser. +* You can open a terminal in the workspace. + +[role="_additional-resources"] +.Additional resources + +* xref:install:proc_verifying-the-installation.adoc[Confirm {prod-short} is running] +* xref:install:proc_finding-the-fully-qualified-domain-name-fqdn.adoc[Get the dashboard URL to share with your team] diff --git a/modules/get-started-admin/pages/what-to-configure-next.adoc b/modules/get-started-admin/pages/what-to-configure-next.adoc new file mode 100644 index 0000000000..57f4e7c426 --- /dev/null +++ b/modules/get-started-admin/pages/what-to-configure-next.adoc @@ -0,0 +1,39 @@ +:_content-type: REFERENCE +:description: What to configure next after verifying the platform and configuring Git access +:keywords: configuration, next steps, post-installation +:navtitle: What to configure next + +[id="what-to-configure-next"] += What to configure next + +[role="_abstract"] +After verifying the platform and configuring Git access, continue with these configuration tasks based on your organization's priorities. + +.Post-installation configuration tasks +[cols="1,2,1",options="header"] +|=== +| Priority | Task | Guide + +| Recommended +| Speed up workspace starts by pre-caching container images on cluster nodes. +| xref:optimize:caching-images-for-faster-workspace-start.adoc[Speed up workspace starts with image caching] + +| Recommended +| Configure workspace resource limits, idle timeouts, and the number of workspaces per user. +| xref:administration-guide:configuring-workspaces-globally.adoc[Set workspace policies for all users] + +| Recommended +| Configure OAuth for additional Git providers (GitLab, Bitbucket, Azure DevOps). +| xref:administration-guide:configuring-oauth-for-git-providers.adoc[Connect Git providers with OAuth] + +| As needed +| Control access to {prod-short} with role-based access control. +| xref:secure:managing-identities-and-authorizations.adoc[Control access to {prod-short}] + +| As needed +| Customize the `CheCluster` custom resource to change {prod-short} behavior. +| xref:administration-guide:understanding-the-checluster-custom-resource.adoc[Customize the central configuration] + +|=== + +Share the {prod-short} dashboard URL with your developers. They can find their first-day instructions in the xref:get-started-user:your-first-workspace.adoc[Get started as a developer] guide. diff --git a/modules/get-started-admin/pages/your-first-week-as-administrator.adoc b/modules/get-started-admin/pages/your-first-week-as-administrator.adoc new file mode 100644 index 0000000000..f5a30464dd --- /dev/null +++ b/modules/get-started-admin/pages/your-first-week-as-administrator.adoc @@ -0,0 +1,29 @@ +:_content-type: CONCEPT +:description: Your first week as a platform administrator +:keywords: getting started, administrator, post-installation, onboarding +:navtitle: Your first week as a platform administrator + +[id="your-first-week-as-administrator"] += Your first week as a platform administrator + +[role="_abstract"] +After installing {prod-short}, complete a short sequence of configuration tasks before inviting developers to the platform. Each task builds on the previous one and takes you from a fresh deployment to a production-ready environment. + +Your post-installation tasks follow this order: + +. *Verify the platform works end-to-end.* Confirm that the Operator is healthy, the dashboard loads, and a test workspace starts successfully. + +. *Configure Git provider access.* Connect {prod-short} to your organization's Git provider with OAuth so that developers can clone repositories and push code without manually configuring credentials. + +. *Share the dashboard URL with developers.* After verification and Git configuration, share the {prod-short} dashboard URL with your team. Developers can start coding immediately by entering a Git repository URL on the *Create Workspace* page. + +. *Tune the platform for your environment.* Adjust workspace resource limits, enable image caching for faster starts, and configure security policies based on your organization's requirements. + +The first three tasks are covered in this guide. The fourth task is covered across the Secure, Optimize, and Configure guides. + +[role="_additional-resources"] +.Additional resources + +* xref:secure:managing-identities-and-authorizations.adoc[Secure {prod-short}] +* xref:optimize:caching-images-for-faster-workspace-start.adoc[Speed up workspace starts with image caching] +* xref:administration-guide:understanding-the-checluster-custom-resource.adoc[Customize the central configuration] diff --git a/modules/get-started-user/nav.adoc b/modules/get-started-user/nav.adoc new file mode 100644 index 0000000000..61d1895052 --- /dev/null +++ b/modules/get-started-user/nav.adoc @@ -0,0 +1,8 @@ +.Get Started as a Developer +* Create your first cloud workspace +** xref:your-first-workspace.adoc[] +** xref:starting-a-workspace-from-a-git-repository-url.adoc[] +** xref:basic-actions-you-can-perform-on-a-workspace.adoc[] +* Connect to your Git repositories +** xref:authenticating-to-a-git-server-from-a-workspace.adoc[] +*** xref:using-a-git-provider-access-token.adoc[] diff --git a/modules/get-started-user/pages/authenticating-to-a-git-server-from-a-workspace.adoc b/modules/get-started-user/pages/authenticating-to-a-git-server-from-a-workspace.adoc new file mode 100644 index 0000000000..c3b9bff73d --- /dev/null +++ b/modules/get-started-user/pages/authenticating-to-a-git-server-from-a-workspace.adoc @@ -0,0 +1,29 @@ +:_content-type: CONCEPT +:description: How Git authentication works in cloud development environments +:keywords: authentication, authenticate, github, gitlab, bitbucket +:navtitle: How Git authentication works in cloud development environments +:page-aliases: end-user-guide:authenticating-to-a-git-server-from-a-workspace.adoc, get-started:authenticating-to-a-git-server-from-a-workspace.adoc + +[id="authenticating-to-a-git-server-from-a-workspace"] += How Git authentication works in cloud development environments + +// vale RedHat.CaseSensitiveTerms = NO + +[role="_abstract"] +When you clone a private repository or push code from a cloud development environment, {prod-short} needs credentials to access your Git provider. Authentication can be configured at the platform level by your administrator or individually with a personal access token. + +User authentication to a Git server from a cloud development environment is configured by the administrator or, in some cases, by the individual user: + +* Your administrator configures an OAuth application on GitHub, GitLab, Bitbucket, or Microsoft Azure Repos for your {prod} instance. + +* Alternatively, individual users create their own {kubernetes} Secrets for personal Git-provider access tokens or configure SSH keys. + +[role="_additional-resources"] +.Additional resources +* xref:using-a-git-provider-access-token.adoc[Using a Git-provider access token] +// vale RedHat.GitLinks = NO +* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] +// vale RedHat.GitLinks = YES +* xref:administration-guide:configuring-oauth-for-git-providers.adoc[Give developers credential-free Git access] + +// vale RedHat.CaseSensitiveTerms = YES \ No newline at end of file diff --git a/modules/get-started-user/pages/basic-actions-you-can-perform-on-a-workspace.adoc b/modules/get-started-user/pages/basic-actions-you-can-perform-on-a-workspace.adoc new file mode 100644 index 0000000000..a31278c2b2 --- /dev/null +++ b/modules/get-started-user/pages/basic-actions-you-can-perform-on-a-workspace.adoc @@ -0,0 +1,35 @@ +:_content-type: REFERENCE +:description: Manage your cloud development environments from the dashboard +:keywords: workspace, workspaces, reopen, restart, stop, start, delete +:navtitle: Manage your cloud development environments +:page-aliases: end-user-guide:basic-actions-you-can-perform-on-a-workspace.adoc, get-started:basic-actions-you-can-perform-on-a-workspace.adoc + +[id="basic-actions-you-can-perform-on-a-workspace"] += Manage your cloud development environments + +[role="_abstract"] +Stop, restart, and delete cloud development environments from the {prod-short} dashboard to control resource usage and keep your environment organized. Access the *Workspaces* page at `pass:c,a,q[{prod-url}]/dashboard/#/workspaces`. + +.Cloud development environment actions +[cols="1,2",options="header"] +|=== +| Action | GUI steps in the *Workspaces* page + +| _Reopen a running cloud development environment_ +| Click *Open*. + +| _Restart a running cloud development environment_ +| Go to *⋮* *>* *Restart Workspace*. + +| _Stop a running cloud development environment_ +| Go to *⋮* *>* *Stop Workspace*. + +| _Start a stopped cloud development environment_ +| Click *Open*. + +| _Delete a cloud development environment_ +| Go to *⋮* *>* *Delete Workspace*. + +|=== + +NOTE: Each cloud development environment is an {orch-name} `DevWorkspace` custom resource. You can also manage cloud development environments from the command line with `{orch-cli}` or `kubectl`. See xref:end-user-guide:managing-workspaces-with-apis.adoc[]. diff --git a/modules/get-started-user/pages/starting-a-workspace-from-a-git-repository-url.adoc b/modules/get-started-user/pages/starting-a-workspace-from-a-git-repository-url.adoc new file mode 100644 index 0000000000..9a8c76b353 --- /dev/null +++ b/modules/get-started-user/pages/starting-a-workspace-from-a-git-repository-url.adoc @@ -0,0 +1,106 @@ +:_content-type: PROCEDURE +:description: Open your project in a cloud development environment from a Git repository URL +:keywords: start-new-workspace, start-a-new-workspace, how-to-start-new-workspace, how-to-start-a-new-workspace, starting-a-new-workspace, clone-git-repository, clone-a-git-repository, how-to-start-workspace, how-to-start-a-workspace +:navtitle: Open your project in a cloud development environment +:page-aliases: end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc, get-started:starting-a-workspace-from-a-git-repository-url.adoc + +[id="starting-a-workspace-from-a-git-repository-url"] += Open your project in a cloud development environment + +[role="_abstract"] +Open your team's Git repository in a cloud development environment so that you can start coding without installing tools, cloning repositories, or configuring your local environment. {prod-short} handles all of this automatically. + +TIP: You can also use the *Git Repository URL* field on the *Create Workspace* page of your {prod-short} dashboard to enter the URL of a Git repository to start a new cloud development environment. + +.Prerequisites + +* You have a running instance of {prod-short}. +* You know the Fully Qualified Domain Name (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. +* Optional: You have a `devfile.yaml` or `.devfile.yaml` file in the root directory of the Git repository. Without a devfile, the cloud development environment starts with the Universal Developer Image and the default IDE. +* For private repositories: you have configured a personal access token or accepted the SCM authentication page to access the repository content. See xref:using-a-git-provider-access-token.adoc[]. +// vale RedHat.GitLinks = NO +* For Git+SSH URLs: you have configured an SSH key for Git operations. See link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations]. +// vale RedHat.GitLinks = YES + +.Procedure + +. Optional: Open the {prod-short} dashboard to authenticate to your organization's instance of {prod-short}. + +. Enter the URL in your browser or in the *Git Repository URL* field on the *Create Workspace* page to start a new cloud development environment: ++ +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#____ +---- ++ +To append optional parameters, add `?____` to the URL. See xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for workspace URLs] for supported parameters. ++ +For example: ++ +* `pass:c,a,q[{prod-url}#https://github.com/che-samples/cpp-hello-world]` +* `pass:c,a,q[{prod-url}#git@github.com:che-samples/cpp-hello-world.git]` ++ +URL syntax per Git provider: ++ +.GitHub +[cols="1",options="header"] +|=== +| URL pattern + +| Default branch: `pass:c,a,q[{prod-url}#https://____/____/____]` +| Specified branch: `pass:c,a,q[{prod-url}#https://____/____/____/tree/____]` +| Pull request branch: `pass:c,a,q[{prod-url}#https://____/____/____/pull/____]` +| Git+SSH: `pass:c,a,q[{prod-url}#git@____:____/____.git]` +|=== ++ +For GitHub, you can also use a URL of a directory containing a devfile, or a direct URL to the devfile. The devfile name must be `devfile.yaml` or `.devfile.yaml`. Other Git providers do not support this feature. ++ +.GitLab +[cols="1",options="header"] +|=== +| URL pattern + +| Default branch: `pass:c,a,q[{prod-url}#https://____/____/____]` +| Specified branch: `pass:c,a,q[{prod-url}#https://____/____/____/-/tree/____]` +| Git+SSH: `pass:c,a,q[{prod-url}#git@____:____/____.git]` +|=== ++ +.Bitbucket Server +[cols="1",options="header"] +|=== +| URL pattern + +| Default branch: `pass:c,a,q[{prod-url}#https://____/scm/____/____.git]` +| Default branch (user profile repository): `pass:c,a,q[{prod-url}#https://____/users/____/repos/____/]` +| Specified branch: `pass:c,a,q[{prod-url}#https://____/users/____/repos/____/browse?at=refs%2Fheads%2F____]` +| Git+SSH: `pass:c,a,q[{prod-url}#git@____:____/____.git]` +|=== ++ +.Microsoft Azure DevOps +[cols="1",options="header"] +|=== +| URL pattern + +| Default branch: `pass:c,a,q[{prod-url}#https://____@dev.azure.com/____/____/_git/____]` +| Specified branch: `pass:c,a,q[{prod-url}#https://____@dev.azure.com/____/____/_git/____?version=GB____]` +| Git+SSH: `pass:c,a,q[{prod-url}#git@ssh.dev.azure.com:v3/____/____/____]` +|=== + +.Verification + +* After you enter the URL to start a new cloud development environment in a browser tab, the starting page is displayed. +* When the new cloud development environment is ready, the IDE loads in the browser tab. +* A clone of the Git repository is present in the filesystem of the new cloud development environment. +* The cloud development environment has a unique URL: `pass:c,a,q[{prod-url}]/____/____`. + +[role="_additional-resources"] +.Additional resources + +* xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[Optional parameters for workspace URLs] +* xref:basic-actions-you-can-perform-on-a-workspace.adoc[] +* xref:using-a-git-provider-access-token.adoc[] +* xref:end-user-guide:mounting-git-configuration.adoc[] +// vale RedHat.GitLinks = NO +* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] +// vale RedHat.GitLinks = YES diff --git a/modules/get-started/pages/using-a-git-provider-access-token.adoc b/modules/get-started-user/pages/using-a-git-provider-access-token.adoc similarity index 50% rename from modules/get-started/pages/using-a-git-provider-access-token.adoc rename to modules/get-started-user/pages/using-a-git-provider-access-token.adoc index df1bd3fcab..fc7ad9ac57 100644 --- a/modules/get-started/pages/using-a-git-provider-access-token.adoc +++ b/modules/get-started-user/pages/using-a-git-provider-access-token.adoc @@ -1,45 +1,32 @@ :_content-type: PROCEDURE -:description: Using a Git-provider access token +:description: Access private repositories with a personal access token :keywords: Git, credentials, access-token :navtitle: Access private repositories with a personal access token -:page-aliases: end-user-guide:using-a-git-provider-access-token.adoc, using-a-Git-credentials-store.adoc, using-git-credentials.adoc, +:page-aliases: end-user-guide:using-a-git-provider-access-token.adoc, using-a-Git-credentials-store.adoc, using-git-credentials.adoc, get-started:using-a-git-provider-access-token.adoc [id="using-a-git-provider-access-token"] = Access private repositories with a personal access token -pass:[] +// vale RedHat.CaseSensitiveTerms = NO -include::partial$snip_persona-developer.adoc[] +[role="_abstract"] +Set up a personal access token so that you can clone private repositories and push code from your cloud development environment when your administrator has not configured OAuth for your Git provider. You can also 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`. -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. +Mounting your access token as a Secret enables the {prod-short} Server to access the remote repository that is cloned during cloud development environment creation, including access to the repository's `/.che` and `/.vscode` folders. -Mounting your access token as a Secret enables the {prod-short} Server to access the remote repository that is cloned during workspace creation, including access to the repository's `/.che` and `/.vscode` folders. - -Apply the Secret in your user {orch-namespace} of the {orch-name} cluster of your organization's {prod-short} instance. - -After applying the Secret, you can create workspaces with clones of private Git repositories that are hosted on GitHub, GitLab, Bitbucket Server, or Microsoft Azure Repos. - -You can create and apply multiple access-token Secrets per Git provider. You must apply each of those Secrets in your user {orch-namespace}. +You can create and apply multiple access-token Secrets per Git provider. You must apply each Secret in your user {orch-namespace}. .Prerequisites -* You have logged in to the cluster. -+ -[TIP] -==== -On OpenShift, you can use the `oc` command-line tool to log in to the cluster: - -`$ oc login pass:c,a,q[{prod-url}] --username=____` - -==== - -.Procedure - -. Generate your access token on your Git provider's website. +* You have a personal access token from your Git provider: +** link:https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token[GitHub Personal Access Token] +** link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html[GitLab Personal Access Token] +** link:https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/[Bitbucket App Password] +** link:https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate[Azure DevOps Personal Access Token] + [IMPORTANT] ==== -Personal access tokens are sensitive information. Treat them like passwords. If you are having trouble with authentication, verify the token locally before applying it as a Secret: +Personal access tokens are sensitive information. Treat them as you would passwords. If you are having trouble with authentication, verify the token locally before applying it as a Secret: [source,bash] ---- @@ -51,11 +38,15 @@ Replace `` with your personal access token, and `username/repo` with the ap For GitHub Enterprise Cloud, verify that the token is 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[authorized for use within your organization with SAML single sign-on]. ==== -. Go to `pass:c,a,q[{prod-url}]/api/user/id` in the web browser to get your {prod-short} user ID. +* You have an active `{orch-cli}` session with your {orch-namespace}. See {orch-cli-link}. + +.Procedure -. Prepare a new {orch-name} Secret. +. Open `pass:c,a,q[{prod-url}]/api/user/id` in a browser to get your {prod-short} user ID. + +. Create a {orch-name} Secret with your access token: + -[source,yaml,subs="+quotes,+attributes,+macros"] +[source,yaml,subs="+quotes,+attributes"] ---- kind: Secret apiVersion: v1 @@ -80,7 +71,9 @@ che.eclipse.org/che-userid:: Your {prod-short} user ID. + che.eclipse.org/scm-personal-access-token-name:: The Git provider name (`github`, `gitlab`, `bitbucket-server`, or `azure-devops`). + +// vale RedHat.CaseSensitiveTerms = NO che.eclipse.org/scm-url:: The Git provider URL endpoint, for example `https://github.com` or `https://gitlab.com`. +// vale RedHat.CaseSensitiveTerms = YES + che.eclipse.org/scm-organization:: Required only for Azure DevOps: your Git provider user organization, or collection if Azure DevOps Server is used. + @@ -88,6 +81,7 @@ token:: Your personal access token. + Example for GitHub: + +// vale RedHat.GitLinks = NO [source,yaml,subs="+quotes,+attributes"] ---- kind: Secret @@ -105,71 +99,55 @@ type: Opaque stringData: token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ---- +// vale RedHat.GitLinks = YES -. Visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. - -. Switch to your {prod-short} user namespace in the cluster. -+ -[TIP] -==== -On OpenShift: - -* The `oc` command-line tool can return the namespace you are currently on in the cluster, which you can use to check your current namespace: -+ -`$ oc project` +. Open `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. -* You can switch to your {prod-short} user namespace on a command line if needed: +. Apply the Secret to your {prod-short} user {orch-namespace}: + -`$ oc project ____` - -==== - -. Apply the Secret. -+ -[TIP] -==== -On OpenShift, you can use the `oc` command-line tool: -[source,subs="+quotes,+attributes"] +[source,bash,subs="+quotes,+attributes"] ---- -$ oc apply -f - <__ -EOF +$ {orch-cli} apply -f personal-access-token.yaml -n ____ ---- -==== - ++ [IMPORTANT] ==== -If you are using Azure DevOps Server, you must also modify the xref:end-user-guide:mounting-git-configuration.adoc[workspace's -gitconfig] with the following section: +If you are using Azure DevOps Server, you must also modify the xref:end-user-guide:mounting-git-configuration.adoc[cloud development environment gitconfig] with the following section: [source,http] ---- - extraheader = "Authorization: Basic " +extraheader = "Authorization: Basic " ---- + To generate the key-value pair, use the following command: -[source,commandline] +[source,bash] ---- echo -n "extraheader = \"Authorization: Basic "$(printf ":%s" | base64)\" ---- -see link:https://learn.microsoft.com/en-us/azure/devops/repos/git/auth-overview?view=azure-devops&tabs=Linux#personal-access-tokens[the documentation page] for more information. -The `extraheader` configuration is needed for remote git operations to Azure Devops Server, for example `git clone`. This authorization method has a higher priority over the git credentials store, and as a result, the remote operations to other Git providers will fail. +The `extraheader` configuration is needed for remote git operations to Azure DevOps Server, for example `git clone`. This authorization method has a higher priority over the git credentials store, and as a result, remote operations to other Git providers will fail. ==== +. Start or restart your cloud development environment. + .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. -. Make some changes and push to the remote Git repository from the workspace. +. Open a terminal in your cloud development environment. +. Clone a private repository or push to a repository to verify authentication: ++ +// vale RedHat.GitLinks = NO +[source,bash,subs="+quotes,+attributes"] +---- +$ git clone https://github.com/____/____.git +---- +// vale RedHat.GitLinks = YES +[role="_additional-resources"] .Additional resources -* 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] +* xref:authenticating-to-a-git-server-from-a-workspace.adoc[] +* xref:administration-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[Deploy 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/get-started-user/pages/your-first-workspace.adoc b/modules/get-started-user/pages/your-first-workspace.adoc new file mode 100644 index 0000000000..915b605094 --- /dev/null +++ b/modules/get-started-user/pages/your-first-workspace.adoc @@ -0,0 +1,85 @@ +:_content-type: CONCEPT +:description: Your first-day experience with {prod-short}: from login to coding in about three minutes. +:keywords: getting started, first workspace, onboarding +:navtitle: Your first-day experience +:page-aliases: get-started:your-first-workspace.adoc + +[id="your-first-workspace"] += Your first-day experience + +[role="_abstract"] +{prod-short} creates a cloud development environment (CDE) for your project. The dashboard and CLI refer to each CDE as a *workspace*. Each cloud development environment runs as a {orch-name} `DevWorkspace` custom resource on your cluster. You go from login to coding in about three minutes. + +== From URL to code in four steps + +When your administrator shares the {prod-short} dashboard URL, you go from login to coding in four steps: + +. *Authenticate with {orch-name}* -- {prod-short} redirects you to the {orch-name} OAuth login page. Enter your {orch-name} credentials and authorize {prod-short} to access your account. + +. *Create Workspace page* -- After authentication, you land on the Create Workspace page. The page has two main sections: ++ +** *Git Repo URL* -- A field where you paste the HTTPS or SSH URL of your Git repository. +** *Select a Sample* -- Pre-configured samples for languages and frameworks such as Java, Node.js, Python, and Go. Use these to explore {prod-short} without connecting your own repository. + +. *Start your cloud development environment* -- When you enter a Git URL and click *Create & Open*, {prod-short} asks you to confirm that you trust the repository authors, then provisions the cloud development environment. + +. *IDE loads in your browser* -- The default IDE, Microsoft Visual Studio Code - Open Source, opens in your browser tab with the repository already cloned. + +== Why the first start takes longer + +The first cloud development environment start takes approximately 2-3 minutes because {prod-short} pulls container images to the cluster node. The starting page displays real-time progress, including: + +* Volume provisioning for persistent storage +* Container image pulls for the development tools and IDE +* Initialization of the project clone, home directory, and IDE server + +Subsequent starts are faster because {orch-name} caches the container images on the node. If your administrator has deployed the {image-puller-name-short}, images are pre-cached across all nodes for near-instant starts. + +[NOTE] +==== +Administrators can reduce first-start times by pre-caching container images on cluster nodes. +==== + +== What you can do in a cloud development environment + +A running cloud development environment provides: + +Terminal:: A `bash` terminal in the IDE with your project directory as the working directory. The terminal prompt shows the current Git branch. + +Git integration:: Your repository is cloned into the cloud development environment filesystem. If your administrator has configured OAuth for your Git provider, you can push commits without re-entering credentials. + +Development tools:: The Universal Developer Image (UDI) includes compilers, runtimes, and build tools for common languages. Your project's `devfile.yaml` can define additional tools and commands. + +CDE URL:: Each cloud development environment has a unique URL in the format `pass:c,a,q[{prod-url}]/____/____/`. Bookmark this URL to return to a running cloud development environment. + +== Troubleshoot common issues + +Cloud development environment fails to start with `OOMKilled` or `FailedScheduling`:: +Your {orch-namespace} exceeded its resource quota, or the cloud development environment requested more memory or CPU than the cluster allows. Contact your administrator to adjust resource limits. + +Git push returns `401 Unauthorized` or `403 Forbidden`:: +OAuth is not configured for your Git provider, or your token has expired. Configure authentication to resolve this issue. + +Blank IDE with a `Could not register service workers` error:: +This error occurs in Google Chrome Incognito mode or Mozilla Firefox Private Browsing mode. Use a regular browser window instead. + +[role="_additional-resources"] +.Additional resources + +* xref:administration-guide:caching-images-for-faster-workspace-start.adoc[Speed up workspace starts with image caching] +* xref:authenticating-to-a-git-server-from-a-workspace.adoc[] + +== Joining the community + +Public chat:: +Join the public link:https://communityinviter.com/apps/ecd-tools/join-the-community[Eclipse Cloud Dev Tools Working Group on Slack] +and the link:https://ecd-tools.slack.com/archives/C05SD64M85R[#forum-che channel] +to chat with the developers. + +// vale RedHat.GitLinks = NO +GitHub project repositories:: +Report bugs, request features, and contribute in the main link:https://github.com/eclipse/che[{prod} repository]. + +Community meetings:: +Join us in the link:https://github.com/eclipse/che/wiki/{prod-id}-community-meetings[{prod-short} community meeting], available on-demand. +// vale RedHat.GitLinks = YES diff --git a/modules/get-started/nav.adoc b/modules/get-started/nav.adoc deleted file mode 100644 index c68111b649..0000000000 --- a/modules/get-started/nav.adoc +++ /dev/null @@ -1,7 +0,0 @@ -.Get Started -* xref:your-first-workspace.adoc[] -* xref:starting-a-workspace-from-a-git-repository-url.adoc[] -* xref:basic-actions-you-can-perform-on-a-workspace.adoc[] -* xref:authenticating-to-a-git-server-from-a-workspace.adoc[] -** xref:using-a-git-provider-access-token.adoc[] -* xref:starting-a-workspace-from-a-raw-devfile-url.adoc[] diff --git a/modules/get-started/pages/authenticating-to-a-git-server-from-a-workspace.adoc b/modules/get-started/pages/authenticating-to-a-git-server-from-a-workspace.adoc deleted file mode 100644 index 2193cf388c..0000000000 --- a/modules/get-started/pages/authenticating-to-a-git-server-from-a-workspace.adoc +++ /dev/null @@ -1,27 +0,0 @@ -:_content-type: CONCEPT -:description: Authenticating to a Git server from a workspace -:keywords: authentication, authenticate, github, gitlab, bitbucket -:navtitle: How Git authentication works in Cloud Development Environments -:page-aliases: end-user-guide:authenticating-to-a-git-server-from-a-workspace.adoc - -[id="authenticating-to-a-git-server-from-a-workspace"] -= How Git authentication works in Cloud Development Environments - -pass:[] - -include::partial$snip_persona-developer.adoc[] - -In a workspace, you can run Git commands that require user authentication like cloning a remote private Git repository or pushing to a remote public or private Git repository. - -User authentication to a Git server from a workspace is configured by the administrator or, in some cases, by the individual user: - -* Your administrator sets up an xref:administration-guide:configuring-oauth-for-git-providers.adoc[OAuth application on GitHub, GitLab, Bitbucket, or Microsoft Azure Repos] for your organization's {prod} instance. - -* As a workaround, some users create and apply their own {kubernetes} Secrets for their personal xref:using-a-git-provider-access-token.adoc[Git-provider access tokens] or link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[configure SSH keys for Git operations]. - -.Additional resources -* xref:administration-guide:configuring-oauth-for-git-providers.adoc[Administration Guide: Configuring OAuth for Git providers] -* xref:using-a-git-provider-access-token.adoc[User Guide: Using a Git-provider access token] -* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] - -pass:[] \ No newline at end of file diff --git a/modules/get-started/pages/basic-actions-you-can-perform-on-a-workspace.adoc b/modules/get-started/pages/basic-actions-you-can-perform-on-a-workspace.adoc deleted file mode 100644 index f90f38ede8..0000000000 --- a/modules/get-started/pages/basic-actions-you-can-perform-on-a-workspace.adoc +++ /dev/null @@ -1,37 +0,0 @@ -:_content-type: REFERENCE -:description: Basic actions you can perform on a workspace -:keywords: workspace, workspaces, reopen, restart, stop, start, delete -:navtitle: Manage your Cloud Development Environments -:page-aliases: end-user-guide:basic-actions-you-can-perform-on-a-workspace.adoc - -[id="basic-actions-you-can-perform-on-a-workspace"] -= Manage your Cloud Development Environments - -You manage your workspaces and verify their current states in the *Workspaces* page (`pass:c,a,q[{prod-url}]/dashboard/#/workspaces`) of your {prod-short} dashboard. - -include::partial$snip_persona-developer.adoc[] - -After you start a new workspace, you can perform the following actions on it in the *Workspaces* page: - -.Basic actions you can perform on a workspace -|=== -| Action | GUI steps in the Workspaces page - -| _Reopen a running workspace_ -| Click *Open*. - -| _Restart a running workspace_ -| Go to *⋮* *>* *Restart Workspace*. - -| _Stop a running workspace_ -| Go to *⋮* *>* *Stop Workspace*. - -| _Start a stopped workspace_ -| Click *Open*. - -| _Delete a workspace_ -| Go to *⋮* *>* *Delete Workspace*. - -|=== - -NOTE: Each workspace is a {orch-name} `DevWorkspace` custom resource. You can also manage workspaces from the command line with `{orch-cli}` or `kubectl`. See xref:end-user-guide:managing-workspaces-with-apis.adoc[]. diff --git a/modules/get-started/pages/starting-a-workspace-from-a-git-repository-url.adoc b/modules/get-started/pages/starting-a-workspace-from-a-git-repository-url.adoc deleted file mode 100644 index 49845efd9d..0000000000 --- a/modules/get-started/pages/starting-a-workspace-from-a-git-repository-url.adoc +++ /dev/null @@ -1,137 +0,0 @@ -:_content-type: PROCEDURE -:description: Starting a workspace from a Git repository URL -:keywords: start-new-workspace, start-a-new-workspace, how-to-start-new-workspace, how-to-start-a-new-workspace, starting-a-new-workspace, clone-git-repository, clone-a-git-repository, how-to-start-workspace, how-to-start-a-workspace -:navtitle: Open your project in a Cloud Development Environment -:page-aliases: end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc - -[id="starting-a-workspace-from-a-git-repository-url"] -= Open your project in a Cloud Development Environment - -In the context of this procedure, "Git repository URL" refers to a git clone URL of a repository. Usually, you can fetch this URL by clicking on the *Clone* button in the SCM repository's main page. -Alternatively, you can copy the URL from the address bar of your browser when you are on the main page of the repository. -Selecting a branch or a tag will add the reference parameter to the URL. -[NOTE] -==== -For GitHub, you can also use a repository URL of a directory with a devfile, or a repository URL of the devfile. -The name of the devfile must be `devfile.yaml` or `.devfile.yaml`. - -include::partial$snip_persona-developer.adoc[] - -This feature is not supported for other Git providers. -==== - -With {prod-short}, you can use a URL in your browser to start -a new workspace that contains a clone of a Git repository. -This way, you can clone a Git repository that is hosted on GitHub, GitLab, Bitbucket or Microsoft Azure DevOps server instances. - -TIP: You can also use the *Git Repository URL* field on the *Create Workspace* page of your {prod-short} dashboard to enter the URL of a Git repository to start a new workspace. - -[IMPORTANT] -==== -* If you use an SSH URL to start a new workspace, you must propagate the SSH key. See link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] for more information. -* If the SSH URL points to a private repository, you must apply an access token to be able to fetch the `devfile.yaml` content. You can do this either by accepting an SCM authentication page or following a xref:using-a-git-provider-access-token.adoc[Personal Access Token] procedure. -==== - -[IMPORTANT] -==== -Configure personal access token to access private repositories. See xref:using-a-git-provider-access-token.adoc[]. -==== - -.Prerequisites - -* 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:end-user-guide: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 - -.Procedure - -To start a new workspace with a clone of a Git repository: - -. Optional: Visit your {prod-short} dashboard pages to authenticate to your organization's instance of {prod-short}. - -. Visit the URL to start a new workspace using the basic syntax: -[source,subs="+quotes,+attributes,+macros"] -+ ----- -pass:c,a,q[{prod-url}]#____ ----- -+ -[TIP] -==== -You can extend this URL with optional parameters: -[source,subs="+quotes,+attributes,+macros"] ----- -pass:c,a,q[{prod-url}]#____?____ <1> ----- -<1> See xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]. -==== -+ -[TIP] -==== -You can use Git+SSH URLs to start a new workspace. -See link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] -==== -+ -.A URL for starting a new workspace -==== -* `pass:c,a,q[{prod-url}#https://github.com/che-samples/cpp-hello-world]` -* `pass:c,a,q[{prod-url}#git@github.com:che-samples/cpp-hello-world.git]` -==== - -+ -.The URL syntax for starting a new workspace with a clone of a GitHub instance repository -==== - -* `pass:c,a,q[{prod-url}#https://____/____/____]` starts a new workspace with a clone of the default branch. -* `pass:c,a,q[{prod-url}#https://____/____/____/tree/____]` starts a new workspace with a clone of the specified branch. -* `pass:c,a,q[{prod-url}#https://____/____/____/pull/____]` starts a new workspace with a clone of the branch of the pull request. -* `pass:c,a,q[{prod-url}#git@____:____/____.git]` starts a new workspace from Git+SSH URL. -==== - -+ -.The URL syntax for starting a new workspace with a clone of a GitLab instance repository -==== - -* `pass:c,a,q[{prod-url}#https://____/____/____]` starts a new workspace with a clone of the default branch. -* `pass:c,a,q[{prod-url}#https://____/____/____/-/tree/____]` starts a new workspace with a clone of the specified branch. -* `pass:c,a,q[{prod-url}#git@____:____/____.git]` starts a new workspace from Git+SSH URL. -==== - -+ -.The URL syntax for starting a new workspace with a clone of a BitBucket Server repository -==== - -* `pass:c,a,q[{prod-url}#https://____/scm/____/____.git]` starts a new workspace with a clone of the default branch. -* `pass:c,a,q[{prod-url}#https://____/users/____/repos/____/]` starts a new workspace with a clone of the default branch, if a repository was created under the user profile. -* `pass:c,a,q[{prod-url}#https://____/users/____/repos/____/browse?at=refs%2Fheads%2F____]` starts a new workspace with a clone of the specified branch. -* `pass:c,a,q[{prod-url}#git@____:____/____.git]` starts a new workspace from Git+SSH URL. - -==== -+ -.The URL syntax for starting a new workspace with a clone of a Microsoft Azure DevOps Git repository -==== -* `pass:c,a,q[{prod-url}#https://____@dev.azure.com/____/____/_git/____]` starts a new workspace with a clone of the default branch. -* `pass:c,a,q[{prod-url}#https://____@dev.azure.com/____/____/_git/____?version=GB____]` starts a new workspace with a clone of the specific branch. -* `pass:c,a,q[{prod-url}#git@ssh.dev.azure.com:v3/____/____/____]` starts a new workspace from Git+SSH URL. -==== - -+ -After you enter the URL to start a new workspace in a browser tab, the workspace starting page appears. -+ -When the new workspace is ready, the workspace IDE loads in the browser tab. -+ -A clone of the Git repository is present in the filesystem of the new workspace. -+ -The workspace has a unique URL: `pass:c,a,q[{prod-url}]/____/____`. - -.Additional resources - -* xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] -* xref:basic-actions-you-can-perform-on-a-workspace.adoc[] -* xref:using-a-git-provider-access-token.adoc[] -* xref:end-user-guide:mounting-git-configuration.adoc[] -* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] diff --git a/modules/get-started/pages/starting-a-workspace-from-a-raw-devfile-url.adoc b/modules/get-started/pages/starting-a-workspace-from-a-raw-devfile-url.adoc deleted file mode 100644 index 0fd9770059..0000000000 --- a/modules/get-started/pages/starting-a-workspace-from-a-raw-devfile-url.adoc +++ /dev/null @@ -1,98 +0,0 @@ -:_content-type: PROCEDURE -:description: Starting a workspace from a raw devfile URL -:keywords: start-new-workspace, start-a-new-workspace, how-to-start-new-workspace, how-to-start-a-new-workspace, starting-a-new-workspace, how-to-start-workspace, how-to-start-a-workspace -:navtitle: Start a Cloud Development Environment from a raw devfile URL -:page-aliases: end-user-guide:starting-a-workspace-from-a-raw-devfile-url.adoc - -[id="starting-a-workspace-from-a-raw-devfile-url"] -= Start a Cloud Development Environment from a raw devfile URL - -With {prod-short}, you can open a *devfile* URL in your browser to start a new workspace. - -include::partial$snip_persona-developer.adoc[] - -pass:[] - -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:[] - -[IMPORTANT] -==== -To initiate a clone of the Git repository in the filesystem of a new workspace, the devfile must contain project info. - -See https://devfile.io/docs/2.2.0/adding-projects. -==== - -.Prerequisites - -* 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}]`. - -.Procedure - -To start a new workspace from a devfile URL: - -. Optional: Visit your {prod-short} dashboard pages to authenticate to your organization's instance of {prod-short}. - -. Visit the URL to start a new workspace from a *public* repository using the basic syntax: -[source,subs="+quotes,+attributes,+macros"] -+ ----- -pass:c,a,q[{prod-url}]#____ ----- -+ -You can pass your personal access token to the URL to access a devfile from *private* repositories: -[source,subs="+quotes,+attributes,+macros"] -+ ----- -pass:c,a,q[{prod-url}]#__https://____@____/__ <1> ----- -<1> Your personal access token that you generated on the Git provider's website. - -+ -This works for GitHub, GitLab, Bitbucket, Microsoft Azure, and other providers that support Personal Access Token. -+ -[IMPORTANT] -==== -Automated Git credential injection does not work in this case. -To configure the Git credentials, use the xref:using-a-git-provider-access-token.adoc[configure personal access token] guide. -==== -+ -[TIP] -==== -You can extend this URL with optional parameters: -[source,subs="+quotes,+attributes,+macros"] ----- -pass:c,a,q[{prod-url}]#____?____ <1> ----- -<1> See xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]. -==== -+ -.A URL for starting a new workspace from a public repository -==== - -`pass:c,a,q[{prod-url}#https://raw.githubusercontent.com/che-samples/cpp-hello-world/main/devfile.yaml]` - -==== -+ -.A URL for starting a new workspace from a private repository -==== - -`pass:c,a,q[{prod-url}#https://____@raw.githubusercontent.com/che-samples/cpp-hello-world/main/devfile.yaml]` - -==== -+ -.Verification - -After you enter the URL to start a new workspace in a browser tab, the workspace starting page appears. When the new workspace is ready, the workspace IDE loads in the browser tab. -+ -The workspace has a unique URL: `pass:c,a,q[{prod-url}]/____/____`. - -.Additional resources - -* xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] -* xref:basic-actions-you-can-perform-on-a-workspace.adoc[] -* xref:using-a-git-provider-access-token.adoc[] -* xref:end-user-guide:mounting-git-configuration.adoc[] -* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations] diff --git a/modules/get-started/pages/your-first-workspace.adoc b/modules/get-started/pages/your-first-workspace.adoc deleted file mode 100644 index 662d5e389f..0000000000 --- a/modules/get-started/pages/your-first-workspace.adoc +++ /dev/null @@ -1,79 +0,0 @@ -:_content-type: CONCEPT -:description: Go from opening the {prod-short} URL to coding in about three minutes. -:keywords: getting started, first workspace, onboarding -:navtitle: Your first-day experience - -[id="your-first-workspace"] -= Your first-day experience - -[role="_abstract"] -{prod-short} creates a Cloud Development Environment (CDE) for your project. The dashboard and CLI refer to each CDE as a *workspace*. Each Cloud Development Environment runs as a {orch-name} `DevWorkspace` custom resource on your cluster. You go from login to coding in about three minutes. - -include::partial$snip_persona-developer.adoc[] - -== From URL to code in four steps - -When your administrator shares the {prod-short} dashboard URL, you go from login to coding in four steps: - -. *Authenticate* -- {prod-short} redirects you to the login page. Enter your credentials and authorize {prod-short} to access your account. - -. *Create Workspace page* -- After authentication, you land on the Create Workspace page. The page has two main sections: -+ -** *Git Repo URL* -- A field where you paste the HTTPS or SSH URL of your Git repository. -** *Select a Sample* -- Pre-configured workspace samples for languages and frameworks such as Java, Node.js, Python, and Go. Use these to explore {prod-short} without connecting your own repository. - -. *Start your workspace* -- When you enter a Git URL and click *Create & Open*, {prod-short} asks you to confirm that you trust the repository authors, then provisions the workspace. - -. *IDE loads in your browser* -- The default IDE, Microsoft Visual Studio Code - Open Source, opens in your browser tab with the repository already cloned. - -== Why does the first start take longer? - -The first workspace start takes approximately 2-3 minutes because {prod-short} pulls container images to the cluster node. The workspace starting page displays real-time progress, including: - -* Volume provisioning for persistent storage -* Container image pulls for the development tools and IDE -* Initialization of the project clone, home directory, and IDE server - -Subsequent starts are faster because {platforms-name} caches the container images on the node. If your administrator has deployed the {image-puller-name-short}, images are pre-cached across all nodes for near-instant starts. - -NOTE: Administrators can reduce first-start times by pre-caching container images on cluster nodes. See xref:administration-guide:caching-images-for-faster-workspace-start.adoc[]. - -== What can you do in a Cloud Development Environment? - -A running {prod-short} workspace provides: - -Terminal:: A `bash` terminal in the IDE with your project directory as the working directory. The terminal prompt shows the current Git branch. - -Git integration:: Your repository is cloned into the workspace filesystem. If your administrator has configured OAuth for your Git provider, you can push commits without re-entering credentials. - -Development tools:: The Universal Developer Image (UDI) includes compilers, runtimes, and build tools for common languages. Your project's `devfile.yaml` can define additional tools and commands. - -Workspace URL:: Each workspace has a unique URL in the format `pass:c,a,q[{prod-url}]/____/____/`. Bookmark this URL to return to a running workspace. - -== Something went wrong? - -Workspace fails to start with `OOMKilled` or `FailedScheduling`:: -Your {orch-namespace} exceeded its resource quota, or the workspace requested more memory or CPU than the cluster allows. Contact your administrator to adjust resource limits. - -Git push returns `401 Unauthorized` or `403 Forbidden`:: -OAuth is not configured for your Git provider, or your token has expired. Configure authentication to resolve this issue. - -Blank IDE with a `Could not register service workers` error:: -This error occurs in Google Chrome Incognito mode or Mozilla Firefox Private Browsing mode. Use a regular browser window instead. - -.Additional resources - -* xref:authenticating-to-a-git-server-from-a-workspace.adoc[] - -== Joining the community - -Public chat:: -Join the public link:https://communityinviter.com/apps/ecd-tools/join-the-community[Eclipse Cloud Dev Tools Working Group on Slack] -and the link:https://ecd-tools.slack.com/archives/C05SD64M85R[#forum-che channel] -to chat with the developers. - -GitHub project repositories:: -Report bugs, request features, and contribute in the main link:https://github.com/eclipse/che[{prod} repository]. - -Community meetings:: -Join us in the link:https://github.com/eclipse/che/wiki/{prod-id}-community-meetings[{prod-short} community meeting], available on-demand. diff --git a/modules/get-started/partials/snip_persona-developer.adoc b/modules/get-started/partials/snip_persona-developer.adoc deleted file mode 100644 index 1253e99a96..0000000000 --- a/modules/get-started/partials/snip_persona-developer.adoc +++ /dev/null @@ -1 +0,0 @@ -This page is for developers who create and use cloud development environments. To learn more about common roles and example tasks referenced in {prod-short} documentation, see xref:discover:roles-and-tasks.adoc[]. diff --git a/modules/hosted-che/partials/assembly_hosted-che.adoc b/modules/hosted-che/partials/assembly_hosted-che.adoc index dbdc0f8b51..8a55e5ce93 100644 --- a/modules/hosted-che/partials/assembly_hosted-che.adoc +++ b/modules/hosted-che/partials/assembly_hosted-che.adoc @@ -21,5 +21,5 @@ include::partial$ref_hosted-che-faq-and-troubleshooting.adoc[leveloffset=+1] .Additional resources -* For general end-user guidance, see xref:get-started:your-first-workspace.adoc[]. +* For general end-user guidance, see xref:get-started-user:your-first-workspace.adoc[]. diff --git a/modules/install/pages/con_next-steps-after-installation.adoc b/modules/install/pages/con_next-steps-after-installation.adoc index 9ebe9a1557..d8093aca62 100644 --- a/modules/install/pages/con_next-steps-after-installation.adoc +++ b/modules/install/pages/con_next-steps-after-installation.adoc @@ -18,4 +18,5 @@ Prepare {prod-short} for your team by completing these configuration tasks befor * xref:administration-guide:understanding-the-checluster-custom-resource.adoc[] * xref:administration-guide:configuring-oauth-for-git-providers.adoc[] -* xref:get-started:starting-a-workspace-from-a-git-repository-url.adoc[] +* xref:get-started-user:starting-a-workspace-from-a-git-repository-url.adoc[] +* xref:get-started-admin:verify-the-platform-end-to-end.adoc[]