diff --git a/.github/workflows/build-and-validate-on-pr.yaml b/.github/workflows/build-and-validate-on-pr.yaml index ca4a83d8e8..db9b0944c2 100644 --- a/.github/workflows/build-and-validate-on-pr.yaml +++ b/.github/workflows/build-and-validate-on-pr.yaml @@ -8,14 +8,14 @@ # # Name is reused in `publish-netlify.yml` -name: "Build and validate PR" +name: "Build and validate pull request" on: - pull_request jobs: build: - name: link checker # This job name is set as mandatory in the GitHub configuration. + name: "Build and validate pull request" runs-on: ubuntu-20.04 container: "quay.io/eclipse/che-docs:latest" steps: @@ -24,50 +24,56 @@ jobs: with: fetch-depth: 0 # Necessary for git diff in vale step - - name: Build using antora # and fail on warning - id: antora-build - run: CI=true antora generate antora-playbook-for-development.yml --stacktrace 2>&1 | (tee | grep WARNING && exit 42 || exit 0) + # Cache for Antora UI and Htmltest. + # See: https://docs.github.com/en/actions/guides/caching-dependencies-to-speed-up-workflows + # Htmltest accepts 2 weeks old cache for the status code of checked external URLs + # See: https://github.com/wjdp/htmltest + # Refresh the cache every week to avoid a stale cache for htmltest + # See: https://github.com/actions/cache + # See: http://man7.org/linux/man-pages/man1/date.1.html + - name: Get Date + id: get-date + run: | + echo "::set-output name=yearweek::$(/bin/date -u "+%Y%U")" + shell: bash - - name: Upload artifact doc-content - uses: actions/upload-artifact@v2 + - name: Restore cache + uses: actions/cache@v2 + env: + cache-name: cache with: - name: doc-content - path: build/site + path: .cache + key: ${{ steps.get-date.outputs.yearweek }} + + - name: Build using antora # and fail on warning + id: antora-build + run: CI=true antora generate antora-playbook-for-development.yml --stacktrace --log-failure-level=warn - - name: Store PR info for publish-netlify + - name: Store pull request details for publish-netlify run: | echo "${{ github.event.number }}" > PR_NUMBER echo "${{ github.event.pull_request.head.sha }}" > PR_SHA - - name: Upload artifact pull-request-number for publish-netlify - uses: actions/upload-artifact@v2 - with: - name: pull-request-number - path: PR_NUMBER - - - name: Upload artifact pull-request-sha for publish-netlify + - name: Upload artifact doc-content uses: actions/upload-artifact@v2 with: - name: pull-request-sha - path: PR_SHA - - - name: Cache htmltest status code of checked external URLs # See: https://docs.github.com/en/actions/guides/caching-dependencies-to-speed-up-workflows - uses: actions/cache@v2 - env: - cache-name: cache-htmltest - with: - key: refcache.json - path: .cache/htmltest + name: doc-content + path: | + build/site + PR_NUMBER + PR_SHA - name: Validate links using htmltest id: validate-links run: htmltest - - name: Report Unused Images - run: tools/detect-unused-images.sh + - name: Report unused content + run: tools/detect-unused-content.sh - name: Validate language on files added or modified - run: tools/validate_language_changes.sh + run: | + tools/get_vale_styles.sh + tools/validate_language_changes.sh - - name: Count Vale infringements - run: tools/count_vale_errors.sh + - name: Validate conversion to plain asciidoc + run: tools/antora-to-plain-asciidoc.sh diff --git a/.github/workflows/build-and-validate-on-push.yaml b/.github/workflows/build-and-validate-on-push.yaml index 2a332d3d30..55ea08cbd4 100644 --- a/.github/workflows/build-and-validate-on-push.yaml +++ b/.github/workflows/build-and-validate-on-push.yaml @@ -12,7 +12,10 @@ name: Build and validate on: - - push + push: + branches: + - main + - master jobs: build: name: Build and validate @@ -24,60 +27,44 @@ jobs: with: fetch-depth: 0 + # Cache for Antora UI and Htmltest. + # See: https://docs.github.com/en/actions/guides/caching-dependencies-to-speed-up-workflows + # Htmltest accepts 2 weeks old cache for the status code of checked external URLs + # See: https://github.com/wjdp/htmltest + # Refresh the cache every week to avoid a stale cache for htmltest + # See: https://github.com/actions/cache + # See: http://man7.org/linux/man-pages/man1/date.1.html + - name: Get Date + id: get-date + run: | + echo "::set-output name=yearweek::$(/bin/date -u "+%Y%U")" + shell: bash + - name: Restore cache + uses: actions/cache@v2 + env: + cache-name: cache + with: + path: .cache + key: ${{ steps.get-date.outputs.yearweek }} + - name: Build using antora id: antora-build - run: CI=true antora generate antora-playbook-for-development.yml --stacktrace + run: CI=true antora generate antora-playbook-for-development.yml --stacktrace --log-failure-level=warn - - name: Upload artifact + - name: Upload artifact doc-content uses: actions/upload-artifact@v2 with: name: doc-content path: build/site - # htmltest: - # name: link checker # This name is set as mandatory in the GitHub configuration. - # runs-on: ubuntu-20.04 - # container: "quay.io/eclipse/che-docs:latest" - # needs: build - # steps: - # - name: Checkout code - # uses: actions/checkout@v2 - - - name: Cache htmltest status code of checked external URLs # See: https://docs.github.com/en/actions/guides/caching-dependencies-to-speed-up-workflows - uses: actions/cache@v2 - env: - cache-name: cache-htmltest - with: - key: refcache.json - path: .cache/htmltest - - # - name: Download artifacts - # uses: actions/download-artifact@v2 - # with: - # name: doc-content - - name: Validate links using htmltest id: validate-links run: htmltest - # unusedimages: - # name: Report unused images - # runs-on: ubuntu-20.04 - # steps: - # - name: Checkout code - # uses: actions/checkout@v2 - - - name: Report Unused Images - run: tools/detect-unused-images.sh + - name: Report unused content + run: tools/detect-unused-content.sh - # vale-all-content: - # name: Validate style on all content on push - # runs-on: ubuntu-20.04 - # container: "quay.io/eclipse/che-docs:latest" - # steps: - # - name: Checkout code - # uses: actions/checkout@v2 - # with: - # fetch-depth: 0 - - name: Count Vale infringements - run: tools/count_vale_errors.sh + - name: Count Vale alerts + run: | + tools/get_vale_styles.sh + tools/count_vale_errors.sh diff --git a/.github/workflows/call-publication-builder.yaml b/.github/workflows/call-publication-builder.yaml new file mode 100644 index 0000000000..555d1a581c --- /dev/null +++ b/.github/workflows/call-publication-builder.yaml @@ -0,0 +1,24 @@ +# +# Copyright (c) 2020 Red Hat, Inc. +# This program and the accompanying materials are made +# available under the terms of the Eclipse Public License 2.0 +# which is available at https://www.eclipse.org/legal/epl-2.0/ +# +# SPDX-License-Identifier: EPL-2.0 +# + +name: "Call publication builder" + +on: + push: + branches: + - "7.*.x" + - main + - master + +jobs: + call-publication-builder: + name: "Call publication builder" + uses: eclipse/che-docs/.github/workflows/publication-builder.yaml@publication-builder + secrets: + CHE_BOT_GITHUB_TOKEN: ${{ secrets.CHE_BOT_GITHUB_TOKEN }} diff --git a/.github/workflows/che-variables-update.yml b/.github/workflows/che-variables-update.yml deleted file mode 100644 index cc88f56791..0000000000 --- a/.github/workflows/che-variables-update.yml +++ /dev/null @@ -1,37 +0,0 @@ -# This Workflow performs an update of Che variables -name: Update Che variables in the docs -on: - workflow_dispatch: - inputs: - branch: - description: 'Branch in which to update variables' - required: true - default: '' -jobs: - build: - name: Create Release - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - name: Create Release - run: | - git config --global user.name "Mykhailo Kuznietsov" - git config --global user.email "mkuznets@redhat.com" - export GITHUB_TOKEN=${{ secrets.CHE_BOT_GITHUB_TOKEN }} - - BASE_BRANCH=${{ github.event.inputs.branch }} - git checkout ${BASE_BRANCH} - ./tools/environment_docs_gen.sh - - if git diff --name-status --exit-code; then - echo "[INFO] no changes detected, pull request will not be created" - else - PR_BRANCH="pr-update-base-images-$(date +%s)" - git checkout -b ${PR_BRANCH} - git add -A - git commit -sm "chore: Update Che variables" - git push origin ${PR_BRANCH} - hub pull-request --base ${BASE_BRANCH} --head ${PR_BRANCH} -m "chore: Update Che variables in ${PR_BRANCH}" - fi \ No newline at end of file diff --git a/.github/workflows/publish-netlify.yml b/.github/workflows/publish-netlify.yml index d21beded39..220eaba847 100644 --- a/.github/workflows/publish-netlify.yml +++ b/.github/workflows/publish-netlify.yml @@ -15,7 +15,7 @@ name: Publish doc-content using netlify on: workflow_run: workflows: - - "Build and validate PR" + - "Build and validate pull request" types: - completed diff --git a/.github/workflows/pull-request-drafts.yml b/.github/workflows/pull-request-drafts.yml new file mode 100644 index 0000000000..818dd39f19 --- /dev/null +++ b/.github/workflows/pull-request-drafts.yml @@ -0,0 +1,26 @@ +# +# Copyright (c) 2021 Red Hat, Inc. +# This program and the accompanying materials are made +# available under the terms of the Eclipse Public License 2.0 +# which is available at https://www.eclipse.org/legal/epl-2.0/ +# +# SPDX-License-Identifier: EPL-2.0 +# +# Automate pull requests triage + +name: Pull request opened + +on: + pull_request_target: + types: + - converted_to_draft + +jobs: + automate-project-columns: + runs-on: ubuntu-latest + steps: + - uses: alex-page/github-project-automation-plus@v0.8.1 + with: + project: Reviews + column: Drafts + repo-token: ${{ secrets.CHE_BOT_GITHUB_TOKEN }} diff --git a/.github/workflows/pull-request-opened.yml b/.github/workflows/pull-request-opened.yml index 33634b19cf..2515681cb9 100644 --- a/.github/workflows/pull-request-opened.yml +++ b/.github/workflows/pull-request-opened.yml @@ -14,6 +14,8 @@ on: pull_request_target: types: - opened + - ready_for_review + - unassigned jobs: automate-project-columns: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index 75cca9a8fd..0000000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,64 +0,0 @@ -# This Workflow performs a release of che docs -name: Release Che Docs -on: - workflow_dispatch: - inputs: - version: - description: 'The version that is going to be released. Should be in format 7.y.z' - required: true - default: '' - forceRecreateTags: - description: If true, tags will be recreated. Use with caution - required: false - default: 'false' -jobs: - build: - name: Create Release - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - name: Check existing tags - run: | - set +e - RECREATE_TAGS=${{ github.event.inputs.forceRecreateTags }} - git ls-remote --exit-code origin refs/tags/${{ github.event.inputs.version}} - TAG_EXISTS=$? - if [[ $TAG_EXISTS -eq 0 ]]; then - if [[ $RECREATE_TAGS == "true" ]]; then - echo "[INFO] Recreating tags for ${{ github.event.inputs.version}} version" - git push origin :${{ github.event.inputs.version}} - else - echo "[ERROR] Cannot proceed with release - tag already exists" - fi - fi - - name: Set up Python 3.6 - uses: actions/setup-python@v2 - with: - python-version: 3.6 - - name: Set up yq - run: | - python -m pip install --upgrade pip - pip install yq - - name: Create Release - run: | - git config --global user.name "Mykhailo Kuznietsov" - git config --global user.email "mkuznets@redhat.com" - export GITHUB_TOKEN=${{ secrets.CHE_BOT_GITHUB_TOKEN }} - /bin/bash make-release.sh --version ${{ github.event.inputs.version }} --trigger-release - - name: Create failure MM message - if: ${{ failure() }} - run: | - echo "{\"text\":\":no_entry_sign: Che Docs ${{ github.event.inputs.version }} release PR creation failed: https://github.com/eclipse/che-docs/actions/workflows/release.yml\"}" > mattermost.json - - name: Create success MM message - run: | - echo "{\"text\":\":white_check_mark: Che Docs ${{ github.event.inputs.version }} release PR has been created: https://github.com/eclipse/che-docs/pulls?q=is%3Apr+${{ github.event.inputs.version }}\"}" > mattermost.json - - name: Send MM message - if: ${{ success() }} || ${{ failure() }} - uses: mattermost/action-mattermost-notify@1.1.0 - env: - MATTERMOST_WEBHOOK_URL: ${{ secrets.MATTERMOST_WEBHOOK_URL }} - MATTERMOST_CHANNEL: eclipse-che-releases - MATTERMOST_USERNAME: che-bot - diff --git a/.gitignore b/.gitignore index 934d633ebb..5bf728aef1 100644 --- a/.gitignore +++ b/.gitignore @@ -26,10 +26,14 @@ vendor # Antora .cache node_modules/ +build/plain-asciidoc build/site build/site.zip build/site-unbranded +# Keep Vale styles external +.vale/styles/ + linkchecker-out.html .ash_history .bash_history diff --git a/.htmltest.yml b/.htmltest.yml index 5cd32bc97b..59514dc0ea 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -11,14 +11,16 @@ # Configuration file for htmltest # See: https://github.com/wjdp/htmltest -DirectoryPath: build/site/che-7 # Not build/site to avoid false positives on 404.html +DirectoryPath: build/site # Not build/site to avoid false positives on 404.html # IgnoreInternalEmptyHash: true # Legit empty hash present in every page OutputDir: .cache/htmltest CacheExpires: "12h" # Default is 2 weeks. ExternalTimeout: 60 # (seconds) default is 15. IgnoreURLs: - https://cse.google.com/cse.js + - https://docs.github.com/en/* - https://marketplace.visualstudio.com - - https://github.com/eclipse/che-docs/edit/master/ + - https://github.com/eclipse-che/che-docs/edit/master/ - https://www.eclipse.org/che/docs/che-7/ - https://projectlombok.org/ + - https://velero.io/* diff --git a/.vale.ini b/.vale.ini index 9fed981741..9c514d1662 100644 --- a/.vale.ini +++ b/.vale.ini @@ -4,20 +4,15 @@ # The relative path to the folder containing linting rules (styles). StylesPath = .vale/styles -# Vocab define the exceptions to use in *all* `BasedOnStyles`. -# accept.txt triggers `Vale.Terms` -# reject.txt triggers `Vale.Avoid` -# See: https://docs.errata.ai/vale/vocab -; Vocab = Che - # Minimum alert level # ------------------- # The minimum alert level in the output (suggestion, warning, or error). # If integrated into CI, builds fail by default on error-level alerts, unless you run Vale with the --no-exit flag -MinAlertLevel = suggestion +; MinAlertLevel = suggestion +MinAlertLevel = warning # IgnoredScopes specifies inline-level HTML tags to ignore. -# These tags may occur in an active scope (unlike SkippedScopes, skipped entirely) but their content still won't raise any alerts. +# These tags may occur in an active scope (unlike SkippedScopes, skipped entirely) but their content still will not raise any alerts. # Default: ignore `code` and `tt`. IgnoredScopes = code, tt, img, url, a, body.id # SkippedScopes specifies block-level HTML tags to ignore. Ignore any content in these scopes. @@ -32,13 +27,7 @@ SkippedScopes = script, style, pre, figure, code, tt, blockquote, listingblock, # Project specific (CheDocs) # IBM Style Guide (IBM) # Generic (Vale) -BasedOnStyles = CheDocs,IBM - -# Altering rules severity (error, warning, suggestion) -CheDocs.ReadabilityGrade = suggestion -IBM.Annotations = suggestion -IBM.Slash = warning -IBM.Usage = suggestion +BasedOnStyles = CheDocs,RedHat # Ignore attributes definition, id statements TokenIgnores = (:[^\n]+: [^\n]+), (\[id=[^\n]+) @@ -49,17 +38,20 @@ properties = md # Define specific rules for the `md` format, hijacked to process `che.properties`. [*.md] -BasedOnStyles = CheDocs,IBM +BasedOnStyles = RedHat # Ignore code surrounded by backticks or plus sign, parameters defaults, URLs. TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[) -IBM.Annotations = suggestion -IBM.HeadingPunctuation = NO -IBM.Headings = NO -IBM.Slash = warning -IBM.Usage = suggestion +RedHat.Annotations = suggestion +RedHat.HeadingPunctuation = NO +RedHat.Headings = NO +RedHat.Slash = warning +RedHat.Usage = suggestion [*.ini] -BasedOnStyles = CheDocs,IBM -IBM.Slash = NO -IBM.Spacing = NO -CheDocs.Spelling = NO +BasedOnStyles = RedHat +RedHat.CaseSensitiveTerms = NO +RedHat.ConfigMap = NO +RedHat.Slash = NO +RedHat.Spacing = NO +RedHat.Spelling = NO + diff --git a/.vale/fixtures/AnchorInXref/.vale.ini b/.vale/fixtures/AnchorInXref/.vale.ini new file mode 100644 index 0000000000..6ff0643018 --- /dev/null +++ b/.vale/fixtures/AnchorInXref/.vale.ini @@ -0,0 +1,5 @@ +; Vale configuration file to check only antora2asciidoc rules +StylesPath = ../../styles +MinAlertLevel = suggestion +[*.adoc] +PlainAsciiDoc.AnchorInXref = YES diff --git a/.vale/fixtures/AnchorInXref/testinvalid.adoc b/.vale/fixtures/AnchorInXref/testinvalid.adoc new file mode 100644 index 0000000000..b9b1950c3e --- /dev/null +++ b/.vale/fixtures/AnchorInXref/testinvalid.adoc @@ -0,0 +1 @@ +xref:something#invalid[] \ No newline at end of file diff --git a/.vale/fixtures/AnchorInXref/testvalid.adoc b/.vale/fixtures/AnchorInXref/testvalid.adoc new file mode 100644 index 0000000000..7d58f3788b --- /dev/null +++ b/.vale/fixtures/AnchorInXref/testvalid.adoc @@ -0,0 +1,9 @@ +legit AnchorInCrossGuideLink link:{legit}#legit[] +legit AnchorInCrossGuideLink link:{legit}legit#legit[] +legit AnchorInCrossGuideLink link:{prod-legit-url}legit[] link:{legit}legit[] +legit DoubleAnchorsInLink link:legit#legit[] link:legit#legit[] +legit FilenameInLink link:legit[] legit.adoc +legit FilenameInLink link:legit#legit[] legit.adoc +legit FilenameInXref xref:legit[] legit.adoc +legit AnchorInXref xref:legit[] link:legit#legit[] + diff --git a/.vale/fixtures/AnchorsInCrossGuideLink/.vale.ini b/.vale/fixtures/AnchorsInCrossGuideLink/.vale.ini new file mode 100644 index 0000000000..8832c88d94 --- /dev/null +++ b/.vale/fixtures/AnchorsInCrossGuideLink/.vale.ini @@ -0,0 +1,5 @@ +; Vale configuration file to check only antora2asciidoc rules +StylesPath = ../../styles +MinAlertLevel = suggestion +[*.adoc] +PlainAsciiDoc.AnchorsInCrossGuideLink = YES diff --git a/.vale/fixtures/AnchorsInCrossGuideLink/testinvalid.adoc b/.vale/fixtures/AnchorsInCrossGuideLink/testinvalid.adoc new file mode 100644 index 0000000000..ac1d685cda --- /dev/null +++ b/.vale/fixtures/AnchorsInCrossGuideLink/testinvalid.adoc @@ -0,0 +1 @@ +link:{prod-something-url}something#invalid[] \ No newline at end of file diff --git a/.vale/fixtures/AnchorsInCrossGuideLink/testvalid.adoc b/.vale/fixtures/AnchorsInCrossGuideLink/testvalid.adoc new file mode 100644 index 0000000000..7d58f3788b --- /dev/null +++ b/.vale/fixtures/AnchorsInCrossGuideLink/testvalid.adoc @@ -0,0 +1,9 @@ +legit AnchorInCrossGuideLink link:{legit}#legit[] +legit AnchorInCrossGuideLink link:{legit}legit#legit[] +legit AnchorInCrossGuideLink link:{prod-legit-url}legit[] link:{legit}legit[] +legit DoubleAnchorsInLink link:legit#legit[] link:legit#legit[] +legit FilenameInLink link:legit[] legit.adoc +legit FilenameInLink link:legit#legit[] legit.adoc +legit FilenameInXref xref:legit[] legit.adoc +legit AnchorInXref xref:legit[] link:legit#legit[] + diff --git a/.vale/fixtures/AnchorsInLink/.vale.ini b/.vale/fixtures/AnchorsInLink/.vale.ini new file mode 100644 index 0000000000..194102c588 --- /dev/null +++ b/.vale/fixtures/AnchorsInLink/.vale.ini @@ -0,0 +1,5 @@ +; Vale configuration file to check only antora2asciidoc rules +StylesPath = ../../styles +MinAlertLevel = suggestion +[*.adoc] +PlainAsciiDoc.AnchorsInLink = YES diff --git a/.vale/fixtures/AnchorsInLink/testinvalid.adoc b/.vale/fixtures/AnchorsInLink/testinvalid.adoc new file mode 100644 index 0000000000..c5e3a56c83 --- /dev/null +++ b/.vale/fixtures/AnchorsInLink/testinvalid.adoc @@ -0,0 +1,2 @@ +link:https://something#something#invalid[] +link:something#something#invalid[] diff --git a/.vale/fixtures/AnchorsInLink/testvalid.adoc b/.vale/fixtures/AnchorsInLink/testvalid.adoc new file mode 100644 index 0000000000..7d58f3788b --- /dev/null +++ b/.vale/fixtures/AnchorsInLink/testvalid.adoc @@ -0,0 +1,9 @@ +legit AnchorInCrossGuideLink link:{legit}#legit[] +legit AnchorInCrossGuideLink link:{legit}legit#legit[] +legit AnchorInCrossGuideLink link:{prod-legit-url}legit[] link:{legit}legit[] +legit DoubleAnchorsInLink link:legit#legit[] link:legit#legit[] +legit FilenameInLink link:legit[] legit.adoc +legit FilenameInLink link:legit#legit[] legit.adoc +legit FilenameInXref xref:legit[] legit.adoc +legit AnchorInXref xref:legit[] link:legit#legit[] + diff --git a/.vale/fixtures/CheDocs/Attributes/.vale.ini b/.vale/fixtures/CheDocs/Attributes/.vale.ini deleted file mode 100644 index 532eaaf0ec..0000000000 --- a/.vale/fixtures/CheDocs/Attributes/.vale.ini +++ /dev/null @@ -1,10 +0,0 @@ -StylesPath = ../../../styles - -MinAlertLevel = suggestion - -# Use the file extension testadoc, to avoid testing this files in the GitHub workflow. -[formats] -testadoc = adoc - -[*.{adoc,testadoc}] -CheDocs.Attributes = YES diff --git a/.vale/fixtures/CheDocs/Attributes/invalid.testadoc b/.vale/fixtures/CheDocs/Attributes/invalid.testadoc deleted file mode 100644 index ac745b8b9e..0000000000 --- a/.vale/fixtures/CheDocs/Attributes/invalid.testadoc +++ /dev/null @@ -1,28 +0,0 @@ -`kubectl` or `oc` -Image Puller -identity provider -Keycloak -kubectl -kubernetes -Kubernetes -Kubernetes and OpenShift -Kubernetes Image Puller -Kubernetes Image Puller Operator -Kubernetes Ingress or OpenShift Route -Kubernetes or OpenShift -kubernetes-image-puller -namespace -OpenShift and Kubernetes -OpenShift or Kubernetes -prod-shor -Kubernetes Ingress or OpenShift route -Kubernetes Ingress - namespace -namespace} -namespace: -namespace -namespace or project -RH-SSO -RHSSO -Keycloak or RH-SSO -Keycloak or RHSSO diff --git a/.vale/fixtures/CheDocs/Attributes/valid.testadoc b/.vale/fixtures/CheDocs/Attributes/valid.testadoc deleted file mode 100644 index 6eb1650c42..0000000000 --- a/.vale/fixtures/CheDocs/Attributes/valid.testadoc +++ /dev/null @@ -1,20 +0,0 @@ -{identity-provider} -{image-puller-cr-name} -{image-puller-deployment-name} -{image-puller-image-name} -{image-puller-name-short} -{image-puller-name} -{image-puller-operator-name} -{kubernetes} -{namespace} -{orch-cli} -{orch-family-cli} -{orch-ingress} -{orch-name} -{orch-namespace} -{platforms-identity-provider} -{platforms-ingress} -{platforms-name} -{platforms-namespace} -{prod-short} -{prod-url} diff --git a/.vale/fixtures/CheDocs/CommonTerms/.vale.ini b/.vale/fixtures/CheDocs/CommonTerms/.vale.ini deleted file mode 100644 index 8e1a5a7bfa..0000000000 --- a/.vale/fixtures/CheDocs/CommonTerms/.vale.ini +++ /dev/null @@ -1,6 +0,0 @@ -StylesPath = ../../../styles - -MinAlertLevel = suggestion - -[*.adoc] -CheDocs.CommonTerms = YES diff --git a/.vale/fixtures/CheDocs/CommonTerms/testinvalid.adoc b/.vale/fixtures/CheDocs/CommonTerms/testinvalid.adoc deleted file mode 100644 index 283115db5e..0000000000 --- a/.vale/fixtures/CheDocs/CommonTerms/testinvalid.adoc +++ /dev/null @@ -1,3 +0,0 @@ -invalid content: Che -invalid content: che - diff --git a/.vale/fixtures/CheDocs/CommonTerms/testvalid.adoc b/.vale/fixtures/CheDocs/CommonTerms/testvalid.adoc deleted file mode 100644 index 0c0ddf8eed..0000000000 --- a/.vale/fixtures/CheDocs/CommonTerms/testvalid.adoc +++ /dev/null @@ -1 +0,0 @@ -valid content: Che-Theia diff --git a/.vale/fixtures/CheDocs/InternalLinks/.vale.ini b/.vale/fixtures/CheDocs/InternalLinks/.vale.ini deleted file mode 100644 index a63dcc5114..0000000000 --- a/.vale/fixtures/CheDocs/InternalLinks/.vale.ini +++ /dev/null @@ -1,6 +0,0 @@ -StylesPath = ../../../styles - -MinAlertLevel = suggestion - -[*.adoc] -CheDocs.InternalLinks = YES diff --git a/.vale/fixtures/CheDocs/InternalLinks/testinvalid.adoc b/.vale/fixtures/CheDocs/InternalLinks/testinvalid.adoc deleted file mode 100644 index 070663b41e..0000000000 --- a/.vale/fixtures/CheDocs/InternalLinks/testinvalid.adoc +++ /dev/null @@ -1,5 +0,0 @@ -invalid content: link:#internal-link[] -invalid content: link:internal-link[] -invalid content: link:about-invalid-links[] -invalid content: link:chrome-invalid-link[] - diff --git a/.vale/fixtures/CheDocs/InternalLinks/testvalid.adoc b/.vale/fixtures/CheDocs/InternalLinks/testvalid.adoc deleted file mode 100644 index 3cb5108993..0000000000 --- a/.vale/fixtures/CheDocs/InternalLinks/testvalid.adoc +++ /dev/null @@ -1,7 +0,0 @@ -valid content: link:http://external.link[] -valid content: link:https://external.link[] -valid content: link:{untestable-attribute}[] -valid content: this is a definition link:: valid content -valid content: this is a sentence with a link: valid content -valid content: link:chrome:// -valid content: link:about:preferences diff --git a/.vale/fixtures/CheDocs/Spelling/.vale.ini b/.vale/fixtures/CheDocs/Spelling/.vale.ini deleted file mode 100644 index f4e266d364..0000000000 --- a/.vale/fixtures/CheDocs/Spelling/.vale.ini +++ /dev/null @@ -1,11 +0,0 @@ -; Vale configuration file to test only one rule. -; For details the `.vale.ini` file at the root of the repository. -StylesPath = ../../../styles -MinAlertLevel = suggestion -IgnoredScopes = code, tt, img, url, a, body.id -SkippedScopes = script, style, pre, figure, code, tt, blockquote, listingblock, literalblock - -[[!.]*.adoc] -TokenIgnores = (:[^\n]+: [^\n]+), (\[id=[^\n]+) -; Enable only one rule -CheDocs.Spelling = YES diff --git a/.vale/fixtures/CheDocs/Spelling/testinvalid.adoc b/.vale/fixtures/CheDocs/Spelling/testinvalid.adoc deleted file mode 100644 index 83944245a4..0000000000 --- a/.vale/fixtures/CheDocs/Spelling/testinvalid.adoc +++ /dev/null @@ -1,90 +0,0 @@ -Adoc -ansible -antora -Api -api -Asciidoc -asciidoc -aws -bitbucket -Btn -btrfs -Centos -centos -ceph -che -Configmap -Configmaps -Crd -crd -Crds -crds -Crs -crs -ctrl -Daemonset -daemonset -dev -devworkspace -dns -dockerfile -dotnet -endevor -fabrice -github -gitlab -gluster -gradle -grafana -gui -homebrew -ide -intelephense -Intellij -intellij -jetbrains -jvm -keycloak -kibana -kubespray -lombok -mattermost -microsoft azure -minikube -Mysql -mysql -Netcoredebugoutput -netcoredebugoutput -nginx -Npm -Nuget -nuget -Oauth -oauth -Ocp -Omnisharp -omnisharp -Openshift -openshift -Opentracing -opentracing -Osd -php -Php -podman -Postgresql -quarkus -rolfe -scm -svg -uber -uri -uris -urls -velero -Vsix -webview -webviews -woopra -yana -zowe \ No newline at end of file diff --git a/.vale/fixtures/CheDocs/Spelling/testvalid.adoc b/.vale/fixtures/CheDocs/Spelling/testvalid.adoc deleted file mode 100644 index 6a715a8b7e..0000000000 --- a/.vale/fixtures/CheDocs/Spelling/testvalid.adoc +++ /dev/null @@ -1,136 +0,0 @@ -adoc -Ansible -Antora -API -AsciiDoc -autostart -AWS -bindable -Bitbucket -boolean -breakpoint -btn -Btrfs -CentOS -Ceph -Che -Che-Theia -classloading -config map -config # to enable config map, because spelling rule applies to individual words -ConfigMap -ConfigMaps -CR -CRD -CRDs -CRs -Ctrl -DaemonSet -Dev -Dev Workspace -Developer Perspective -devfile -Devfile -DevWorkspace -DNS -Docker -Dockerfile -Dotnet -Endevor -endif -exposal -Fabrice -Git -GitHub -GitLab -Gluster -Gradle -Grafana -GUI -heatmap -Helm -Homebrew -https -I/O -IDE -IDEs -Intelephense -IntelliJ -IntelliJ IDEA -item -Java -Java Lombok -Jetbrains -JVM -kbd -Keycloak -Kibana -Kubespray -Let's Encrypt -liveness -Lombok -loopback -Mattermost -Maven -mebibytes -Microsoft Azure -millicores -Minikube -mixin -mixins -multiuser -MySQL -namespace -namespaces -NetcoredebugOutput -Nginx -npm -NuGet -OAuth -ocp -OmniSharp -onboarding -OpenShift -OpenTracing -Operator -osd -PHP -Podman -PostgreSQL -preconfigured -Quarkus -rebalancing -Rolfe -Runtime -runtime -Runtimes -runtimes -SCM -serializer -serverless -sharding -Sharding -Spring Boot -subnetwork -subpath -subpaths -SVG -the .NET language -Theia -tolerations -truststore -Uber -uninstallation -unstaged -untrusted -URI -URIs -URLs -Velero -vsix -Webview -Webviews -Woopra -Yana -Yeoman -Zowe diff --git a/.vale/fixtures/CheDocs/TechnicalTerms/.vale.ini b/.vale/fixtures/CheDocs/TechnicalTerms/.vale.ini deleted file mode 100644 index 813d5d9a9c..0000000000 --- a/.vale/fixtures/CheDocs/TechnicalTerms/.vale.ini +++ /dev/null @@ -1,11 +0,0 @@ -; Vale configuration file to test only one rule. -; For details the `.vale.ini` file at the root of the repository. -StylesPath = ../../../styles -MinAlertLevel = suggestion -IgnoredScopes = code, tt, img, url, a, body.id -SkippedScopes = script, style, pre, figure, code, tt, blockquote, listingblock, literalblock - -[[!.]*.adoc] -TokenIgnores = (:[^\n]+: [^\n]+), (\[id=[^\n]+) -; Enable only one rule -CheDocs.TechnicalTerms = YES diff --git a/.vale/fixtures/CheDocs/TechnicalTerms/testinvalid.adoc b/.vale/fixtures/CheDocs/TechnicalTerms/testinvalid.adoc deleted file mode 100644 index 0cf23f296e..0000000000 --- a/.vale/fixtures/CheDocs/TechnicalTerms/testinvalid.adoc +++ /dev/null @@ -1,7 +0,0 @@ -invalid content: config that -invalid content: config file -invalid content: config. -invalid content: config, -invalid content: config: -invalid content: config; - diff --git a/.vale/fixtures/CheDocs/TechnicalTerms/testvalid.adoc b/.vale/fixtures/CheDocs/TechnicalTerms/testvalid.adoc deleted file mode 100644 index eaecd29e69..0000000000 --- a/.vale/fixtures/CheDocs/TechnicalTerms/testvalid.adoc +++ /dev/null @@ -1 +0,0 @@ -valid content: config map diff --git a/.vale/fixtures/CrossGuideContext/.vale.ini b/.vale/fixtures/CrossGuideContext/.vale.ini new file mode 100644 index 0000000000..6baecc82e2 --- /dev/null +++ b/.vale/fixtures/CrossGuideContext/.vale.ini @@ -0,0 +1,5 @@ +; Vale configuration file to check only antora2asciidoc rules +StylesPath = ../../styles +MinAlertLevel = suggestion +[*.adoc] +PlainAsciiDoc.CrossGuideContext = YES diff --git a/.vale/fixtures/CrossGuideContext/testinvalid.adoc b/.vale/fixtures/CrossGuideContext/testinvalid.adoc new file mode 100644 index 0000000000..131d0edf36 --- /dev/null +++ b/.vale/fixtures/CrossGuideContext/testinvalid.adoc @@ -0,0 +1,2 @@ +link:{prod-something-url}something_{context}[] +link:{prod-something-url}something_invalid[] \ No newline at end of file diff --git a/.vale/fixtures/CrossGuideContext/testvalid.adoc b/.vale/fixtures/CrossGuideContext/testvalid.adoc new file mode 100644 index 0000000000..7d58f3788b --- /dev/null +++ b/.vale/fixtures/CrossGuideContext/testvalid.adoc @@ -0,0 +1,9 @@ +legit AnchorInCrossGuideLink link:{legit}#legit[] +legit AnchorInCrossGuideLink link:{legit}legit#legit[] +legit AnchorInCrossGuideLink link:{prod-legit-url}legit[] link:{legit}legit[] +legit DoubleAnchorsInLink link:legit#legit[] link:legit#legit[] +legit FilenameInLink link:legit[] legit.adoc +legit FilenameInLink link:legit#legit[] legit.adoc +legit FilenameInXref xref:legit[] legit.adoc +legit AnchorInXref xref:legit[] link:legit#legit[] + diff --git a/.vale/fixtures/LinkToFileName/.vale.ini b/.vale/fixtures/LinkToFileName/.vale.ini new file mode 100644 index 0000000000..4de50674fc --- /dev/null +++ b/.vale/fixtures/LinkToFileName/.vale.ini @@ -0,0 +1,5 @@ +; Vale configuration file to check only antora2asciidoc rules +StylesPath = ../../styles +MinAlertLevel = suggestion +[*.adoc] +PlainAsciiDoc.LinkToFileName = YES diff --git a/.vale/fixtures/LinkToFileName/testinvalid.adoc b/.vale/fixtures/LinkToFileName/testinvalid.adoc new file mode 100644 index 0000000000..3acb1bfcdc --- /dev/null +++ b/.vale/fixtures/LinkToFileName/testinvalid.adoc @@ -0,0 +1,3 @@ +link:invalid.adoc[] +link:invalid.adoc#something[] + diff --git a/.vale/fixtures/LinkToFileName/testvalid.adoc b/.vale/fixtures/LinkToFileName/testvalid.adoc new file mode 100644 index 0000000000..7d58f3788b --- /dev/null +++ b/.vale/fixtures/LinkToFileName/testvalid.adoc @@ -0,0 +1,9 @@ +legit AnchorInCrossGuideLink link:{legit}#legit[] +legit AnchorInCrossGuideLink link:{legit}legit#legit[] +legit AnchorInCrossGuideLink link:{prod-legit-url}legit[] link:{legit}legit[] +legit DoubleAnchorsInLink link:legit#legit[] link:legit#legit[] +legit FilenameInLink link:legit[] legit.adoc +legit FilenameInLink link:legit#legit[] legit.adoc +legit FilenameInXref xref:legit[] legit.adoc +legit AnchorInXref xref:legit[] link:legit#legit[] + diff --git a/.vale/fixtures/XrefToFileName/.vale.ini b/.vale/fixtures/XrefToFileName/.vale.ini new file mode 100644 index 0000000000..d497f8ad7d --- /dev/null +++ b/.vale/fixtures/XrefToFileName/.vale.ini @@ -0,0 +1,5 @@ +; Vale configuration file to check only antora2asciidoc rules +StylesPath = ../../styles +MinAlertLevel = suggestion +[*.adoc] +PlainAsciiDoc.XrefToFileName = YES diff --git a/.vale/fixtures/XrefToFileName/testinvalid.adoc b/.vale/fixtures/XrefToFileName/testinvalid.adoc new file mode 100644 index 0000000000..b48084099c --- /dev/null +++ b/.vale/fixtures/XrefToFileName/testinvalid.adoc @@ -0,0 +1,5 @@ +xref:something.adoc[] +xref:something.adoc#something[] +xref:something-something.adoc[] +xref:something:something.adoc[] +xref:something:something.adoc#something[] \ No newline at end of file diff --git a/.vale/fixtures/XrefToFileName/testvalid.adoc b/.vale/fixtures/XrefToFileName/testvalid.adoc new file mode 100644 index 0000000000..7d58f3788b --- /dev/null +++ b/.vale/fixtures/XrefToFileName/testvalid.adoc @@ -0,0 +1,9 @@ +legit AnchorInCrossGuideLink link:{legit}#legit[] +legit AnchorInCrossGuideLink link:{legit}legit#legit[] +legit AnchorInCrossGuideLink link:{prod-legit-url}legit[] link:{legit}legit[] +legit DoubleAnchorsInLink link:legit#legit[] link:legit#legit[] +legit FilenameInLink link:legit[] legit.adoc +legit FilenameInLink link:legit#legit[] legit.adoc +legit FilenameInXref xref:legit[] legit.adoc +legit AnchorInXref xref:legit[] link:legit#legit[] + diff --git a/modules/administration-guide/pages/.placeholder b/.vale/styles/.placeholder similarity index 100% rename from modules/administration-guide/pages/.placeholder rename to .vale/styles/.placeholder diff --git a/.vale/styles/CheDocs/Attributes.yml b/.vale/styles/CheDocs/Attributes.yml deleted file mode 100644 index afa216c4b7..0000000000 --- a/.vale/styles/CheDocs/Attributes.yml +++ /dev/null @@ -1,37 +0,0 @@ ---- -extends: substitution -ignorecase: true -level: error -message: Use the attribute %s instead of '%s'. -scope: sentence -# scope: raw -# swap maps tokens in form of bad: good -swap: - '\s[^[:punct:]]keycloak[^[:punct:]\.]': "{identity-provider}" - '\s[^[:punct:]]kubectl[^[:punct:]]': "{orch-cli}" - '\s[Dd]ev[Ww]orkspace[^\}]': "{devworkspace}" - '\s[Dd]ev[Ww]orkspaces': "{devworkspace}" - '\s[Dd]ev [Ww]orkspace': "{devworkspace}" - '\s[^[:punct:]]kubernetes[^[:punct:]]': "{orch-name}, {platforms-name}, or {kubernetes}" - '\sche[^-] ': "{prod-short}" - '\skubernetes[ ]': "{orch-name}, {platforms-name}, or {kubernetes}" - '\snamespace[, ]': "{orch-namespace}, {platforms-namespace}, or {namespace}" - "`kubectl` or `oc`": "{orch-family-cli}" - "Image Puller": "{image-puller-name-short}" - '\sIdentity Provider[^\}]': "{identity-provider} or {platforms-identity-provider}" - "Keycloak or RH-SSO": "{platforms-identity-provider}" - "Kubernetes (?:and|or) OpenShift": "{platforms-name}" - "Kubernetes Image Puller Operator": "{image-puller-operator-name}" - "Kubernetes Image Puller": "{image-puller-name}" - "Kubernetes Ingress or OpenShift Route": "{platforms-ingress}" - "Kubernetes Ingress": "{orch-ingress} or {platforms-ingress}" - "Kubernetes namespace": "{orch-namespace}, {platforms-namespace}, or {namespace}" - "kubernetes-image-puller": "{image-puller-deployment-name}" - "KubernetesImagePuller": "{image-puller-cr-name}" - "namespace or project": "{platforms-namespace}" - "OpenShift (?:and|or) Kubernetes": "{platforms-name}" - "prod-url-secure": prod-url - "quay.io/eclipse/kubernetes-image-puller": "{image-puller-image-name}" - "RH-SSO": "{identity-provider}" - "RHSSO": "{identity-provider}" - # '\s[^[:punct:]]namespace[^[:punct:]]': "{platforms-namespace} or {orch-namespace}" diff --git a/.vale/styles/CheDocs/CommonTerms.yml b/.vale/styles/CheDocs/CommonTerms.yml deleted file mode 100644 index 7ae943fc51..0000000000 --- a/.vale/styles/CheDocs/CommonTerms.yml +++ /dev/null @@ -1,10 +0,0 @@ ---- -extends: substitution -ignorecase: false -level: warning -message: Consider using '%s' instead of '%s' -swap: - '\s[^n] binary': tool - '\sis installed': is available - '\spresent': available - '\sprogram': tool diff --git a/.vale/styles/CheDocs/InternalLinks.yml b/.vale/styles/CheDocs/InternalLinks.yml deleted file mode 100644 index 71d0cf1661..0000000000 --- a/.vale/styles/CheDocs/InternalLinks.yml +++ /dev/null @@ -1,9 +0,0 @@ ---- -extends: existence -ignorecase: false -level: error -message: Use xref statement for internal links instead of '%s' -scope: raw -tokens: - - '(link\:(?!h|\{|\:| |chrome\:\/\/|about\:preferences).*)' - - '(link\:#.*)' diff --git a/.vale/styles/CheDocs/Links.yml b/.vale/styles/CheDocs/Links.yml deleted file mode 100644 index 723ef7c630..0000000000 --- a/.vale/styles/CheDocs/Links.yml +++ /dev/null @@ -1,11 +0,0 @@ ---- -extends: substitution -ignorecase: true -level: error -message: Use '%s' instead of '%s.' -swap: - \slink\:https\://www.eclipse.org\S*\s: link:{site-baseurl}che-7/ - \shttps\://www.eclipse.org\S*\s: link:{site-baseurl}che-7/ - github.com/eclipse/che/blob: github.com/eclipse-che/che-server/blob - github.com/eclipse/che/tree: github.com/eclipse-che/che-server/tree - github.com/eclipse/che-theia: github.com/eclipse-che/che-theia diff --git a/.vale/styles/CheDocs/LinksChe6.yml b/.vale/styles/CheDocs/LinksChe6.yml deleted file mode 100644 index 280eeea587..0000000000 --- a/.vale/styles/CheDocs/LinksChe6.yml +++ /dev/null @@ -1,8 +0,0 @@ ---- -code: false -extends: existence -ignorecase: true -level: error -message: Eclipse Che 6 is obsolete. Consider removing '%s' -tokens: - - www.eclipse.org\S*che-6 diff --git a/.vale/styles/CheDocs/ReadabilityGrade.yml b/.vale/styles/CheDocs/ReadabilityGrade.yml deleted file mode 100644 index dc4c71924a..0000000000 --- a/.vale/styles/CheDocs/ReadabilityGrade.yml +++ /dev/null @@ -1,11 +0,0 @@ ---- -extends: readability -message: "Grade level (%s) too high!" -level: warning -grade: 21 -metrics: - - Flesch-Kincaid - - Gunning Fog - - Coleman-Liau - - SMOG - - Automated Readability diff --git a/.vale/styles/CheDocs/SentenceLength.yml b/.vale/styles/CheDocs/SentenceLength.yml deleted file mode 100644 index a70539f22d..0000000000 --- a/.vale/styles/CheDocs/SentenceLength.yml +++ /dev/null @@ -1,9 +0,0 @@ ---- -extends: occurrence -message: 'Keep sentences short and to the point' -description: 'A good rule-of-thumb is to break up any sentence longer than 21 words into two or more separate thoughts.' -scope: sentence -source: PLainLanguage -level: suggestion -max: 21 -token: '\b(\w+)\b' diff --git a/.vale/styles/CheDocs/Spelling.yml b/.vale/styles/CheDocs/Spelling.yml deleted file mode 100644 index d655cb15fd..0000000000 --- a/.vale/styles/CheDocs/Spelling.yml +++ /dev/null @@ -1,215 +0,0 @@ -extends: spelling -message: "Did you really mean '%s'?" -level: error -link: https://vale-at-red-hat.github.io/vale-at-red-hat/docs/contributor-guide/extending-the-spelling-rule/ -# A "filter" is a case-sensitive regular expression specifying words -# to ignore during spell checking. -# Spelling rule applies to individual words -filters: - - '\.NET' - - 'I/O' - - 'Node\.js' - - "[aA]utostart" - - "[bB]ackfilling" - - "[bB]indable" - - "[bB]oolean" - - "[bB]reakpoint" - - "[bB]reakpoints" - - "[cC]he" - - "[cC]lassloading" - - "[cC]olocate" - - "[cC]onfig" # to enable "config map" - - "[dD]evfile" - - "[dD]evfiles" - - "[dD]ev[wW]orkspace" - - "[dD]ownstream" - - "[dD]ownstreaming" - - "[eE]xposal" - - "[Ff]actories" - - "[Ff]actory" - - "[fF]ailback" - - "[fF]ailover" - - "[gG]it" - - "[gG]rafana" - - "[hH]eatmap" - - "[hH]yperconverged" - - "[iI]node" - - "[iI]tem" - - "[jJ]ournald" - - "[jJ]ournaling" - - "[kK]eycloak" - - "[kK]eyring" - - "[kK]eyrings" - - "[lL]icensor" - - "[lL]iveness" - - "[lL]oopback" - - "[mM]ebibytes" - - "[mM]illicores" - - "[mM]ixin" - - "[mM]ixins" - - "[mM]odularization" - - "[mM]ulticluster" - - "[mM]ultihost" - - "[mM]ultinode" - - "[mM]ultitenant" - - "[mM]ultiuser" - - "[mM]ultizone" - - "[nN]amespace" - - "[nN]amespaces" - - "[oO]nboarding" - - "[oO]perator" - - "[pP]reconfigured" - - "[rR]eadonly" - - "[rR]ebalance" - - "[rR]ebalances" - - "[rR]ebalancing" - - "[rR]ebase" - - "[rR]ebased" - - "[rR]eshard" - - "[rR]esharding" - - "[rR]eshards" - - "[rR]esyncing" - - "[rR]ollout" - - "[rR]ollouts" - - "[rR]untime" - - "[rR]untimes" - - "[sS]erializer" - - "[sS]erverless" - - "[sS]harding" - - "[sS]ubnetwork" - - "[sS]ubpath" - - "[sS]ubpaths" - - "[sS]ubstep" - - "[sS]ubsteps" - - "[sS]ubuser" - - "[sS]ubusers" - - "[sS]ubvolume" - - "[sS]ubvolumes" - - "[sS]ystemd" - - "[tT]heia" - - "[tT]olerations" - - "[tT]ruststore" - - "[uU]ncomment" - - "[uU]ndercloud" - - "[uU]ninstallation" - - "[uU]nmount" - - "[uU]nmounting" - - "[uU]nported" - - "[uU]nstaged" - - "[uU]ntrusted" - - "Let\'s Encrypt" - - adoc - - Ansible - - Antora - - API - - AsciiDoc - - aws - - AWS - - Azure - - Bierner - - Bitbucket - - btn - - Btrfs - - Bugzilla - - CentOS - - Ceph - - cephfs - - Che-Theia - - Civetweb - - ConfigMap - - ConfigMaps - - Cookiecutter - - CR - - CRD - - CRDs - - CRs - - Ctrl - - DaemonSet - - Datadog - - Dev - - DevWorkspace - - DNS - - Docker - - Dockerfile - - Dockerfiles - - Dotnet - - Endevor - - endif - - Fabrice - - GitHub - - GitLab - - Gluster - - Gradle - - GUI - - Hashicorp - - Helm - - Homebrew - - htmltest - - http - - HTTP - - https - - HTTPS - - IDE - - IDEs - - Intelephense - - IntelliJ - - Java - - Jetbrains - - Joyent - - jvm - - JVM - - kbd - - Kibana - - Kubespray - - Kylin - - Laravel - - Lombok - - Mattermost - - Maven - - Microsoft - - Minikube - - Minishift - - Mirantis - - MySQL - - Nagios - - NetcoredebugOutput - - Newdoc - - Nginx - - npm - - NuGet - - OAuth - - ocp - - OmniSharp - - OpenShift - - OpenTracing - - osd - - PHP - - Podman - - PostgreSQL - - Prometheus - - Pytorch - - Quarkus - - Redistributions - - Rolfe - - SCM - - Shadowman - - Suchow - - SVG - - Telekom - - Tensorflow - - Traefik - - Uber - - URI - - URIs - - url - - URL - - URLs - - Velero - - vsix - - Webview - - Webviews - - Woopra - - Wordpress - - Yana - - Yeoman - - Zowe diff --git a/.vale/styles/CheDocs/TechnicalTerms.yml b/.vale/styles/CheDocs/TechnicalTerms.yml deleted file mode 100644 index d28ff40ef1..0000000000 --- a/.vale/styles/CheDocs/TechnicalTerms.yml +++ /dev/null @@ -1,29 +0,0 @@ ---- -extends: substitution -ignorecase: false -level: error -message: Use '%s' instead of '%s' -scope: sentence -swap: - '\sContainer Registry': Red Hat Ecosystem Catalog - '\sContainer Catalog': Red Hat Ecosystem Catalog - '\sconfig map': ConfigMap - '\sconfig maps': ConfigMaps - '\sDotnet': .NET - '\sdotnet': .NET - '\sgithub': GitHub - '\side': IDE - '\sjetbrains': Jetbrains - '\sjava': Java - '\netcoredebugoutput': NetcoredebugOutput - '\soperator': Operator - '\spod': Pod - '\spostgres': PostgreSQL - '\sPostgres': PostgreSQL - '\sSsl': TLS - '\sssl': TLS - '\sSSL': TLS - '\syaml': YAML - url: URL - urls: URLs - URLS: URLs diff --git a/.vale/styles/IBM/Abbreviations.yml b/.vale/styles/IBM/Abbreviations.yml deleted file mode 100644 index e7b85f2359..0000000000 --- a/.vale/styles/IBM/Abbreviations.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "Do not use periods in all-uppercase abbreviations such as '%s'." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N100DC' -level: error -nonword: true -tokens: - - '\b(?:[A-Z]\.){3,5}' diff --git a/.vale/styles/IBM/Annotations.yml b/.vale/styles/IBM/Annotations.yml deleted file mode 100644 index a8c06f5c3b..0000000000 --- a/.vale/styles/IBM/Annotations.yml +++ /dev/null @@ -1,11 +0,0 @@ ---- -extends: existence -message: "'%s' left in text." -ignorecase: false -level: error -source: proselint -tokens: - - XXX - - FIXME - - TODO - - NOTE diff --git a/.vale/styles/IBM/DashSpacing.yml b/.vale/styles/IBM/DashSpacing.yml deleted file mode 100644 index ea9a103b73..0000000000 --- a/.vale/styles/IBM/DashSpacing.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: existence -message: "Add spaces around the dash in '%s'." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N106BF' -ignorecase: true -nonword: true -level: error -action: - name: edit - params: - - remove - - ' ' -tokens: - - '[^\s][—–][^\s]' diff --git a/.vale/styles/IBM/Definitions.yml b/.vale/styles/IBM/Definitions.yml deleted file mode 100644 index ec9f6f0de9..0000000000 --- a/.vale/styles/IBM/Definitions.yml +++ /dev/null @@ -1,65 +0,0 @@ -extends: conditional -message: "Define acronyms and abbreviations (such as '%s') on first occurrence if they're likely to be unfamiliar." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N100DC' -level: suggestion -ignorecase: false -# Ensures that the existence of 'first' implies the existence of 'second'. -first: '\b([A-Z]{3,5}s?)\b' -second: '\(([A-Z]{3,5}s?)\)' -# ... with the exception of these: -exceptions: - - API - - ASP - - CLI - - CPU - - CSS - - CSV - - DEBUG - - DOM - - DPI - - FAQ - - GCC - - GDB - - GET - - GPU - - GTK - - GUI - - HTML - - HTTP - - HTTPS - - IDE - - JAR - - JSON - - JSX - - LESS - - LLDB - - NET - - NOTE - - NVDA - - OSS - - PATH - - PDF - - PHP - - POST - - RAM - - REPL - - RSA - - SCM - - SCSS - - SDK - - SQL - - SSH - - SSL - - SVG - - SWAT - - TBD - - TCP - - TODO - - URI - - URL - - USB - - UTF - - XML - - XSS - - YAML - - ZIP diff --git a/.vale/styles/IBM/Ellipses.yml b/.vale/styles/IBM/Ellipses.yml deleted file mode 100644 index b313155d3a..0000000000 --- a/.vale/styles/IBM/Ellipses.yml +++ /dev/null @@ -1,10 +0,0 @@ -extends: existence -message: "Avoid the ellipsis (...) except to indicate omitted words." -link: https://www.ibm.com/developerworks/library/styleguidelines/index.html -nonword: true -level: warning -action: - name: remove -tokens: - - '\.\.\.' - - '…' diff --git a/.vale/styles/IBM/Foreign.yml b/.vale/styles/IBM/Foreign.yml deleted file mode 100644 index 6bd25e67ad..0000000000 --- a/.vale/styles/IBM/Foreign.yml +++ /dev/null @@ -1,12 +0,0 @@ -extends: substitution -message: "Use '%s' instead of '%s'." -link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words -ignorecase: true -level: error -nonword: true -action: - name: replace -source: Microsoft -swap: - '\b(?:eg|e\.g\.)[\s,]': for example - '\b(?:ie|i\.e\.)[\s,]': that is diff --git a/.vale/styles/IBM/HeadingPunctuation.yml b/.vale/styles/IBM/HeadingPunctuation.yml deleted file mode 100644 index f47bd827ab..0000000000 --- a/.vale/styles/IBM/HeadingPunctuation.yml +++ /dev/null @@ -1,14 +0,0 @@ -extends: existence -message: "Don't use end punctuation in headings." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods -nonword: true -level: warning -scope: heading -source: Microsoft -action: - name: edit - params: - - remove - - '.?!' -tokens: - - '[a-z0-9][.?!](?:\s|$)' diff --git a/.vale/styles/IBM/Headings.yml b/.vale/styles/IBM/Headings.yml deleted file mode 100644 index d471140000..0000000000 --- a/.vale/styles/IBM/Headings.yml +++ /dev/null @@ -1,10 +0,0 @@ -extends: capitalization -message: "'%s' should use sentence-style capitalization." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N1030C' -level: suggestion -scope: heading -match: $sentence -indicators: - - ':' -exceptions: - - IBM diff --git a/.vale/styles/IBM/Latin.yml b/.vale/styles/IBM/Latin.yml deleted file mode 100644 index b0d2b2b1cc..0000000000 --- a/.vale/styles/IBM/Latin.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: substitution -message: "Use '%s' instead of '%s'." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist' -ignorecase: true -level: error -nonword: true -action: - name: replace -swap: - '\b(?:eg|e\.g\.)[\s,]': for example - '\b(?:ie|i\.e\.)[\s,]': that is - '\betc\.': and so on - '\bvs\.': versus diff --git a/.vale/styles/IBM/OxfordComma.yml b/.vale/styles/IBM/OxfordComma.yml deleted file mode 100644 index 6e7f76c7aa..0000000000 --- a/.vale/styles/IBM/OxfordComma.yml +++ /dev/null @@ -1,6 +0,0 @@ -extends: existence -message: "Use the Oxford comma in '%s'." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N106BF' -level: suggestion -tokens: - - '(?:[^,]+,){1,}\s\w+\sand' diff --git a/.vale/styles/IBM/PassiveVoice.yml b/.vale/styles/IBM/PassiveVoice.yml deleted file mode 100644 index e66876eb59..0000000000 --- a/.vale/styles/IBM/PassiveVoice.yml +++ /dev/null @@ -1,184 +0,0 @@ ---- -extends: existence -message: "'%s' is passive voice. Consider rewording in active voice." -ignorecase: true -level: suggestion -raw: - - \b(am|are|were|being|is|been|was|be)\b\s* -tokens: - - '[\w]+ed' - - awoken - - beat - - become - - been - - begun - - bent - - beset - - bet - - bid - - bidden - - bitten - - bled - - blown - - born - - bought - - bound - - bred - - broadcast - - broken - - brought - - built - - burnt - - burst - - cast - - caught - - chosen - - clung - - come - - cost - - crept - - cut - - dealt - - dived - - done - - drawn - - dreamt - - driven - - drunk - - dug - - eaten - - fallen - - fed - - felt - - fit - - fled - - flown - - flung - - forbidden - - foregone - - forgiven - - forgotten - - forsaken - - fought - - found - - frozen - - given - - gone - - gotten - - ground - - grown - - heard - - held - - hidden - - hit - - hung - - hurt - - kept - - knelt - - knit - - known - - laid - - lain - - leapt - - learnt - - led - - left - - lent - - let - - lighted - - lost - - made - - meant - - met - - misspelt - - mistaken - - mown - - overcome - - overdone - - overtaken - - overthrown - - paid - - pled - - proven - - put - - quit - - read - - rid - - ridden - - risen - - run - - rung - - said - - sat - - sawn - - seen - - sent - - set - - sewn - - shaken - - shaven - - shed - - shod - - shone - - shorn - - shot - - shown - - shrunk - - shut - - slain - - slept - - slid - - slit - - slung - - smitten - - sold - - sought - - sown - - sped - - spent - - spilt - - spit - - split - - spoken - - spread - - sprung - - spun - - stolen - - stood - - stridden - - striven - - struck - - strung - - stuck - - stung - - stunk - - sung - - sunk - - swept - - swollen - - sworn - - swum - - swung - - taken - - taught - - thought - - thrived - - thrown - - thrust - - told - - torn - - trodden - - understood - - upheld - - upset - - wed - - wept - - withheld - - withstood - - woken - - won - - worn - - wound - - woven - - written - - wrung diff --git a/.vale/styles/IBM/README-proselint.md b/.vale/styles/IBM/README-proselint.md deleted file mode 100644 index b08cef98d5..0000000000 --- a/.vale/styles/IBM/README-proselint.md +++ /dev/null @@ -1,13 +0,0 @@ - -Copyright © 2014–2015, Jordan Suchow, Michael Pacer, and Lara A. Ross -All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/.vale/styles/IBM/README-write-good.md b/.vale/styles/IBM/README-write-good.md deleted file mode 100644 index ba919b6fe1..0000000000 --- a/.vale/styles/IBM/README-write-good.md +++ /dev/null @@ -1,28 +0,0 @@ - -Based on [write-good](https://github.com/btford/write-good). - -> Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too. - -``` -The MIT License (MIT) - -Copyright (c) 2014 Brian Ford - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -``` diff --git a/.vale/styles/IBM/README.md b/.vale/styles/IBM/README.md deleted file mode 100644 index 35f651fa41..0000000000 --- a/.vale/styles/IBM/README.md +++ /dev/null @@ -1,5 +0,0 @@ - -IBM style guide was created by IBM: https://www.ibm.com/developerworks/library/styleguidelines/index.html -All rights for the style guide belong to IBM. - -Rules were compiled at: https://github.com/errata-ai/IBM diff --git a/.vale/styles/IBM/SentenceLength.yml b/.vale/styles/IBM/SentenceLength.yml deleted file mode 100644 index 0946cf559f..0000000000 --- a/.vale/styles/IBM/SentenceLength.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: occurrence -message: "Try to keep sentences less than 25 words." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N106FB' -scope: sentence -level: suggestion -max: 25 -token: \b(\w+)\b diff --git a/.vale/styles/IBM/Slash.yml b/.vale/styles/IBM/Slash.yml deleted file mode 100644 index 07df5ba8fc..0000000000 --- a/.vale/styles/IBM/Slash.yml +++ /dev/null @@ -1,8 +0,0 @@ ---- -extends: existence -message: "Use either 'or' or 'and' in '%s'" -ignorecase: true -level: error -source: PlainLanguage -tokens: - - '\w+/\w+' diff --git a/.vale/styles/IBM/Spacing.yml b/.vale/styles/IBM/Spacing.yml deleted file mode 100644 index c86a760eff..0000000000 --- a/.vale/styles/IBM/Spacing.yml +++ /dev/null @@ -1,9 +0,0 @@ -extends: existence -message: "'%s' should have one space." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods -level: error -nonword: true -source: Microsoft -tokens: - - '[a-z][.?!] {2,}[A-Z]' - - '[a-z][.?!][A-Z]' diff --git a/.vale/styles/IBM/Spelling.yml b/.vale/styles/IBM/Spelling.yml deleted file mode 100644 index 4fd8054fc0..0000000000 --- a/.vale/styles/IBM/Spelling.yml +++ /dev/null @@ -1,20 +0,0 @@ ---- -extends: consistency -message: "Use General American spelling of '%s'." -level: error -ignorecase: true -source: proselint -either: - advisor: adviser - analyse: analyze - centre: center - colour: color - emphasise: emphasize - finalise: finalize - focussed: focused - labour: labor - learnt: learned - organise: organize - organised: organized - organising: organizing - recognise: recognize diff --git a/.vale/styles/IBM/Terms.yml b/.vale/styles/IBM/Terms.yml deleted file mode 100644 index 87222d8e20..0000000000 --- a/.vale/styles/IBM/Terms.yml +++ /dev/null @@ -1,204 +0,0 @@ ---- -extends: substitution -message: Consider using '%s' instead of '%s' -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist' -level: error -ignorecase: true -action: - name: replace -# swap maps tokens in form of bad: good -swap: - '(?:Ctrl|control)-click': press Ctrl and click - 'a lot(?: of)?': many|much - 'backward(?:-)?compatible': compatible with earlier versions - 'bottom(?:-)?left': lower left|lower-left - 'bottom(?:-)?right': lower right|lower-right - 'down(?:-)?level': earlier|previous|not at the latest level - 'mash(?: )?up': create - 'pop-up (?:blocker|killer)': software to block pop-up ad windows - 're(?:-)?occur': recur - 'sort(?:-|/)?merge': sort|merge - 'top(?:-)?left': upper left|upper right|upper-left|upper-right - 'top(?:-)?right': upper left|upper right|upper-left|upper-right - - # These need to be implemented in a separate file since they include word - # boundaries ('.'). - # - # See https://github.com/errata-ai/Microsoft/blob/master/Microsoft/Foreign.yml - # - # e.g.: for example|such as - # etc.: and so on - # i.e.: that is - # vs.: versus|compared to - - # These are currenly invalid patterns. - # - # dismiss (a window, a dialog box): close - # position (a cursor): move - # spawn (a process): create - # strike (a key): press|type - # touch (a key): press|type - - a number of: several - abort: cancel|stop - administrate: administer - all caps: uppercase - and/or: a or b|a, b, or both - as long as: if|provided that - as per: according to|as|as in - back-level: earlier|previous|not at the latest level - Big Blue: IBM - blink: flash - blue screen of death: stop error - breadcrumbing: breadcrumb trail - canned: preplanned|preconfigured|predefined - case insensitive: not case-sensitive - catastrophic error: unrecoverable error - CBE: Common Base Event - CBTS: CICS BTS|BTS - cold boot: hardware restart - cold start: hardware restart - comes with: includes - componentization: component-based development|component model|component architecture|shared components - componentize: develop components - comprised of: consist of - connect with: connect to - context menu: menu|pop-up menu - contextual help: help|context-sensitive help - crash: fail|lock up|stop|stop responding - CRUD: create retrieve update and delete - #customer: client COMMENT: needs better implementation to avoid `Customer Portal` - datum: data - debuggable: debug - deconfigure: unconfigure - deinstall: uninstall - deinstallation: uninstallation - demilitarized zone: DMZ - demo: demonstration - depress: press|type - deregister: unregister - desire: want|required - destroy: delete from the database - dismount: demount|unmount|remove - #do: complete|perform COMMENT: needs better implementation to avoid `do not` - downgrade: upgrade|fallback|fall back|rollback|roll back - downward compatible: compatible with earlier versions - drag and drop: drag - drill up: navigate - e-fix: fix|interim fix - eFix: fix|interim fix - end user: user - end-user interface: graphical interface|interface - EUI: graphical user interface|interface - #expose: display|show|make available COMMENT: too many false positives w/ "expose the route" - fill in: complete|enter|specify - fixed disk drive: hard disk drive - flavor: version|method - floppy disk: diskette|diskette drive - floppy drive: diskette|diskette drive - floppy: diskette|diskette drive - forward compatible: compatible with later versions - gzip: compress - gzipped: archive|compressed file - hard drive: hard disk|hard disk drive - hard file: hard disk|hard disk drive - hence: therefore - i-fix: interim fix - i-Fix: interim fix - IBM's: IBM's|IBM's AIX - ifix: interim fix - iFix: interim fix - in order to: to - in other words: for example|that is - in spite of: regardless of|despite - in the event: in case|if|when - inactivate: deactivate - information on: information about - information technology: IT - instead of: rather than - insure: ensure - Internet address: IP address|URL|Internet email address|web address - irrecoverable: unrecoverable - jar: compress|archive - keep in mind: remember - #key: type|press COMMENT: too many false positives - laptop: notebook - launch: start|open - left-hand: left - let's: let us - leverage: use - line cord: power cable|power cord - main directory: root directory - memory stick: USB flash drive - microcomputer: PC - motherboard: system board - mouse over: point to|move the mouse pointer over|Mouse|mouse over - network-centric computing: network computing - non-English: in languages other than English|non-English-language - nonrecoverable: unrecoverable - notion: concept - off-premise: on-premises|off-premises|onsite|offsite - offline storage: auxiliary storage - on ramp: access method - on the fly: dynamically|as needed|in real time|immediately - on the other hand: however|alternatively|conversely - on-premise: on-premises|off-premises|onsite|offsite - on-ramp: access method - pain point: challenge|concern|difficulty|issue - parent task: parent process - perimeter network: DMZ - phone: telephone|cell phone|mobile phone - power down: turn on|turn off - power off: turn on|turn off - power on: turn on|turn off - preload: preinstall|preinstalled - preloaded: preinstall|preinstalled - prepend: add a prefix to - recommend: suggest - retry: retry|try again - right double-click: double right-click - right-hand: right - rule of thumb: rule - sanity check: test|evaluate - secondary storage: auxiliary storage - selection button: left mouse button - serial database: nonpartitioned database environment - shift-click: press Shift and click - ship: include|included - Simple Object Access Protocol: SOAP - single quote mark: single quotation mark - single quote: single quotation mark - SME routine: session management exit routine - start up: start - sunset: withdraw from service|withdraw from marketing|discontinue|no longer support - switch off: power on|turn on|power off|turn off - switch on: power on|turn on|power off|turn off - tar: compress|archive - tarball: tar file - terminate: end|stop - thru: through - thumbstick: USB flash drive - thus: therefore - toggle off: toggle - tooling: tools - touchscreen: touch-sensitive screen - transition: make the transition|move|migrate|change - typo: typing error|typographical error - uncheck: clear - uncompress: decompress - undeploy: remove|withdraw - unjar: extract - unselect: clear|deselect - untar: extract - unzip: unzip - upward compatible: compatible with later versions - utilize: use - #version: create a version|assign a version number COMMENT: too many false positives - versus: compared to - via: through - warning notice: attention notice - web-enable: enable for the web - webinar: webinar|webcast|web seminar|web-based event - wish: want - zero out: zero - zip: zip|compress diff --git a/.vale/styles/IBM/ThereIs.yml b/.vale/styles/IBM/ThereIs.yml deleted file mode 100644 index 6a4002b903..0000000000 --- a/.vale/styles/IBM/ThereIs.yml +++ /dev/null @@ -1,8 +0,0 @@ ---- -extends: existence -message: "Don't start a sentence with '%s'" -ignorecase: true -level: error -source: write-good -raw: - - '(?:^[^\w]*|[;-]\s)There\b\s(is|are)\b' diff --git a/.vale/styles/IBM/Usage.yml b/.vale/styles/IBM/Usage.yml deleted file mode 100644 index 05b7789753..0000000000 --- a/.vale/styles/IBM/Usage.yml +++ /dev/null @@ -1,174 +0,0 @@ ---- -extends: existence -message: "Verify your use of '%s' with the word usage guidelines." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist' -ignorecase: true -level: warning -tokens: - # This need its own rule since it doesn't have a left-hand word boundary. - # - (s) - - # These also need their own rule: - # - neither ... nor - # - if...then - - - 'pop-up (?:help|menu)' - - 'redbook(:s)?' - - about - - above - - across - - actionable - - allow - - alpha - - alphabetic - - alphabetical - - and so on - - architect - - architected - - as - - as well as - - assembler - - attach - - below - - best-of-breed - - between - - billion - - bitness - - black box - - board - - both - - bring up - - business partner - - cache - - camel case - - carry out - - catch - - central processing unit - - check - - choose - - combination box - - combo box - - command console - - Common Base Event - - complete - - congratulations - - connect - - consumability - - consume - - could - - CPU - - customers - - daughterboard - - decompress - - decompressed - - deploy - - designed to - - display - - domestic - - done - - due to - - either - - EPUB - - execute - - fatal - - foo - - foobar - - foreign - - free - - freeze - - fubar - - functionality - - geography - - green screen - - guarantee - - hard boot - - hash - - hash sign - - higher - - hit - - hover help - - illegal - - impact - - info center - - infocenter - - information center - - ingest - - internationalize - - invoke - - itself - - Java Development Kit \(JDK\) - - kill - - latest - - legacy - - let - - like - - lite - - localize - - look and feel - - look-and-feel - - machine - - master and slave - - migrate - - native - - new - - once - - out-of-the-box - - overhead - - panel - - partner - - permit - - please - - pound sign - - program temporary fix - - proper - - pull-down - - quote - - quoted - - refer to - - repair - - reside - - respective - - respectively - - select - - selected - - should - - simply - - since - - slave - - so - - soft boot - - Solution Partnership Centers - - some - - store - - system - - tab - - text entry field - - text field - - that - - themselves - - then - - there are - - there is - - this means - - through - - throw - - throwable - - time to value - - time-tested - - translate - - trillion - - twistie - - twisty - - uncompressed - - unmount - - updatable - - upgrade - - users - - using - - very - - we - - where - - whether or not - - which - - while - - would diff --git a/.vale/styles/IBM/Very.yml b/.vale/styles/IBM/Very.yml deleted file mode 100644 index b3f50c3be3..0000000000 --- a/.vale/styles/IBM/Very.yml +++ /dev/null @@ -1,8 +0,0 @@ ---- -extends: existence -message: "Remove '%s'." -ignorecase: true -level: error -source: proselint -tokens: - - very diff --git a/.vale/styles/IBM/Wordiness.yml b/.vale/styles/IBM/Wordiness.yml deleted file mode 100644 index 9d0535c2f4..0000000000 --- a/.vale/styles/IBM/Wordiness.yml +++ /dev/null @@ -1,121 +0,0 @@ ---- -extends: substitution -message: Consider using '%s' instead of '%s' -ignorecase: true -level: warning -source: PlainLanguage -swap: - (?:give|gave) rise to: lead to - (?:previous|prior) to: before - a (?:large)? majority of: most - a (?:large)? number of: many - a myriad of: myriad - adequate number: enough - adversely impact: hurt - all across: across - all of a sudden: suddenly - all of these: these - all of: all - all-time record: record - almost all: most - almost never: seldom - along the lines of: similar to - an appreciable number of: many - an estimated: about - any and all: all - are in agreement: agree - as a matter of fact: in fact - as a means of: to - as a result of: because of - as of yet: yet - as per: per - at a later date: later - at all times: always - at the present time: now - at this point in time: at this point - based in large part on: based on - based on the fact that: because - basic necessity: necessity - because of the fact that: because - came to a realization: realized - came to an abrupt end: end[ed] abruptly - carry out an evaluation of: evaluate - close down: close - closed down: closed - complete stranger: stranger - completely separate: separate - concerning the matter of: regarding - conduct a review of: review - conduct an investigation: investigate - conduct experiments: experiment - continue on: continue - despite the fact that: although - disappear from sight: disappear - doomed to fail: doomed - due to the fact that: because - during the period of: during - during the time that: while - emergency situation: emergency - except when: unless - excessive number: too many - extend an invitation: invite - fall down: fall - fell down: fell - for the duration of: during - gather together: gather - has the ability: can - has the capacity to: can - has the opportunity to: could - hold a meeting: meet - if this is not the case: if not - in a careful manner: carefully - in a thoughtful manner: thoughtfully - in a timely manner: timely - in an effort to: to - in between: between - in lieu of: instead of - in many cases: often - in most cases: usually - in order to: to - in some cases: sometimes - in spite of the fact that: although - in spite of: despite - in the (?:very)? near future: soon - in the event that: if - in the neighborhood of: roughly - in the vicinity of: close to - it would appear that: apparently - lift up: lift - made reference to: referred to - make reference to: refer to - mix together: mix - none at all: none - not in a position to: unable - not possible: impossible - of major importance: important - perform an assessment of: assess - pertaining to: about - place an order: order - plays a key role in: is essential to - present time: now - readily apparent: apparent - some of the: some - span across: span - subsequent to: after - successfully complete: complete - sufficient number (?:of)?: enough - take action: act - take into account: consider - the question as to whether: whether - there is no doubt but that: doubtless - this day and age: this age - this is a subject that: this subject - time (?:frame|period): time - under the provisions of: under - until such time as: until - used for fuel purposes: used for fuel - whether or not: whether - with reference to: about - with regard to: regarding - with respect to: about or on - with the exception of: except for diff --git a/.vale/styles/IBM/Words.yml b/.vale/styles/IBM/Words.yml deleted file mode 100644 index 8aae769367..0000000000 --- a/.vale/styles/IBM/Words.yml +++ /dev/null @@ -1,8 +0,0 @@ ---- -extends: substitution -message: Use '%s' instead of '%s.' -level: error -ignorecase: true -source: PlainLanguage -swap: - shall: must diff --git a/.vale/styles/PlainAsciiDoc/.vale.ini b/.vale/styles/PlainAsciiDoc/.vale.ini new file mode 100644 index 0000000000..3293356eb3 --- /dev/null +++ b/.vale/styles/PlainAsciiDoc/.vale.ini @@ -0,0 +1,5 @@ +; Vale configuration file to check only PlainAsciiDoc rules +StylesPath = .. +MinAlertLevel = suggestion +[*.adoc] +BasedOnStyles = PlainAsciiDoc diff --git a/.vale/styles/PlainAsciiDoc/AnchorInXref.yml b/.vale/styles/PlainAsciiDoc/AnchorInXref.yml new file mode 100644 index 0000000000..8a46caf1c8 --- /dev/null +++ b/.vale/styles/PlainAsciiDoc/AnchorInXref.yml @@ -0,0 +1,9 @@ +--- +extends: existence +message: "Avoid anchor in xref: '%s'" +ignorecase: true +level: error +nonword: true +scope: raw +tokens: + - 'xref:[[:graph:]]*#[[:graph:]]*\[' diff --git a/.vale/styles/PlainAsciiDoc/AnchorsInCrossGuideLink.yml b/.vale/styles/PlainAsciiDoc/AnchorsInCrossGuideLink.yml new file mode 100644 index 0000000000..90d50d12bd --- /dev/null +++ b/.vale/styles/PlainAsciiDoc/AnchorsInCrossGuideLink.yml @@ -0,0 +1,9 @@ +--- +extends: existence +message: "Use at most one anchor in cross-guide link '%s'" +ignorecase: true +level: error +nonword: true +scope: raw +tokens: + - 'link:{prod-[[:alpha:]]*-url}[[:graph:]]*#[[:graph:]]*\[' diff --git a/.vale/styles/PlainAsciiDoc/AnchorsInLink.yml b/.vale/styles/PlainAsciiDoc/AnchorsInLink.yml new file mode 100644 index 0000000000..216960aa89 --- /dev/null +++ b/.vale/styles/PlainAsciiDoc/AnchorsInLink.yml @@ -0,0 +1,9 @@ +--- +extends: existence +message: "Use at most one anchor in link: '%s'" +ignorecase: true +level: error +nonword: true +scope: raw +tokens: + - 'link:[[:alpha:-_]]*#[[:alpha:-_]]*#[[:alpha:-_]]*\[' diff --git a/.vale/styles/PlainAsciiDoc/CrossGuideContext.yml b/.vale/styles/PlainAsciiDoc/CrossGuideContext.yml new file mode 100644 index 0000000000..efd686d2b3 --- /dev/null +++ b/.vale/styles/PlainAsciiDoc/CrossGuideContext.yml @@ -0,0 +1,9 @@ +--- +extends: existence +message: "Context suffix in cross-guide link should be ds: '%s'" +ignorecase: true +level: error +nonword: true +scope: raw +tokens: + - 'link:{prod-[[:alpha:]]*-url}[[:graph:]]*_[[:graph:]]*[^d][^s]\[' diff --git a/.vale/styles/PlainAsciiDoc/LinkToFileName.yml b/.vale/styles/PlainAsciiDoc/LinkToFileName.yml new file mode 100644 index 0000000000..ae994e0efb --- /dev/null +++ b/.vale/styles/PlainAsciiDoc/LinkToFileName.yml @@ -0,0 +1,10 @@ +--- +extends: existence +message: "Point link to an URL rather than a file name: '%s'" +ignorecase: true +level: error +nonword: true +scope: raw +tokens: + - 'link:.*adoc\[' + - 'link:.*adoc#.*\[' diff --git a/.vale/styles/PlainAsciiDoc/XrefToFileName.yml b/.vale/styles/PlainAsciiDoc/XrefToFileName.yml new file mode 100644 index 0000000000..9151b6eabc --- /dev/null +++ b/.vale/styles/PlainAsciiDoc/XrefToFileName.yml @@ -0,0 +1,10 @@ +--- +extends: existence +message: "In plain AsciiDoc, point xref to an id rather than a file name: '%s'" +ignorecase: true +level: error +nonword: true +scope: raw +tokens: + - 'xref:.*adoc\[' + - 'xref:.*adoc#.*\[' diff --git a/.vale/styles/Vocab/Che/accept.txt b/.vale/styles/Vocab/Che/accept.txt deleted file mode 100644 index dfdeeb1e95..0000000000 --- a/.vale/styles/Vocab/Che/accept.txt +++ /dev/null @@ -1,133 +0,0 @@ -[Aa]nsible -[Aa]utostart -[Bb]oolean -[Bb]reakpoint -[B]reakpoints -[Cc]lassloading -[Cc]he -[Dd]evfile|[Dd]evfiles -[Dd]ownstream -[Dd]ownstreaming -[Ff]actories|[Ff]actory -[Gg]it -[Gg]rafana -[Hh]eatmap -[Hh]elm -[Hh]ostname -[Ii]tem -[Jj]etbrains -[Kk]eycloak -[Ll]iveness -[Ll]ombok -[Ll]oopback -[Mm]aven -[Mm]inikube -[Mm]inishift -[Mm]ixin|[Mm]ixins -[Mm]odularization -[Mm]ulticluster -[Mm]ultihost -[Mm]ultinode -[Mm]ultitenant -[Mm]ultiuser -[Mm]ultizone -[Nn]amespace|[Nn]amespaces -[Nn]etcoredebug[Oo]utput -[Nn]ginx -[Oo]nboarding -[Pp]podman -[Pp]reconfigured -[Rr]eadonly -[Rr]ollout|[Rr]ollouts -[Rr]untime|[Rr]untimes -[Ss]erializer -[Ss]erverless -[Ss]ubnetwork -[Ss]ubpath|[Ss]ubpaths -[Tt]heia -[Tt]olerations -[Tt]ruststore -[Uu]ninstallation -[Uu]nstaged -[Uu]ntrusted -[Uu]sing -[Ww]orkspace|[Ww]orkspaces -[Yy]eoman -\.NET -adoc -Antora -API -AsciiDoc -AWS|aws -Bierner -Bitbucket -btn -Btrfs -CentOS -Ceph -Che-Theia -ConfigMap|ConfigMaps -Ctrl -DaemonSet -Dev Workspace -Developer Perspective -DNS -Docker -Dockerfile -Dotnet -Endevor -endif -GitHub|github -GitLab -Gluster -Gradle -Grafana -GUI -HTTPS|https -I/O -IDE|ide|IDEs -Intelephense -IntelliJ -IntelliJ IDEA -Java -Java Lombok -JVM|jvm -kbd -Kubespray -Laravel -Let\'s Encrypt -Mattermost -mebibytes -Microsoft Azure -millicores -MySQL -Node.js -npm -NuGet -OAuth -ocp -OmniSharp -OpenShift -OpenTracing -Operator -OperatorHub -osd -PHP -PostgreSQL -Quarkus -SCM -Sharding -SonarLint -Spring Boot -SVG -Traefik -Uber -URI|URIs -URL|url|URLs -Velero -Visual Studio Code -vsix -Webview|Webviews -Woopra -YAML|yaml -Zowe diff --git a/.vale/styles/Vocab/Che/reject.txt b/.vale/styles/Vocab/Che/reject.txt deleted file mode 100644 index e210e00db8..0000000000 --- a/.vale/styles/Vocab/Che/reject.txt +++ /dev/null @@ -1,27 +0,0 @@ -[Kk]8[Ss] -[Pp]lease -admin -almost -clicking -grab -info -Kube -look up -maybe -mostly -[Mm]ulti-cluster -[Mm]ulti-host -[Mm]ulti-node -[Mm]ulti-tenant -[Mm]ulti-zone -now -our -out of the box -probably -refer -repo -set up -Stack -start up -take care of -we diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index bb01d2551e..c48cfc978f 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,8 +1,12 @@ :toc: -= Contributing to the Eclipse Che Documentation +pass:[] -== Understanding Che Documentation ecosystem += Contributing to the Eclipse Che documentation + +== Understanding the Che documentation ecosystem + +pass:[] * See the xref:CODE_OF_CONDUCT.adoc[Code of conduct]. @@ -13,36 +17,36 @@ *** link:https://youtu.be/s3Em8QSXyn8[The Wisdom of Crowds video] *** link:https://www.nngroup.com/articles/chunking/[Chunking]. -** _IBM Style Guide_. +** Style Guide + +*** link:https://redhat-documentation.github.io/supplementary-style-guide/[Red Hat Style Guide] -*** link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[The IBM Style Guide, Conventions for Writers and Editors] +*** https://redhat-documentation.github.io/vale-at-red-hat/[Vale for writers at Red Hat] -*** link:https://github.com/errata-ai/IBM[A Vale-compatible implementation of IBM's _Developer Editorial Style Guide_] +pass:[] ** Guidelines from the link:https://redhat-documentation.github.io/modular-docs/[Modular Documentation Initiative]. + -TIP: For Antora, a link:https://docs.antora.org/antora/2.3/module-directories/#module[_module_] is a collection of content in a component version. This project is referring to Modular Documentation modules as _topics_. To understand the nature of topics, see the link:https://redhat-documentation.github.io/modular-docs/#modular-docs-terms-definitions[Appendix A: Modular Documentation Terms and Definitions]. +TIP: For Antora, a https://docs.antora.org/antora/latest/module-directories/[_module_] is a collection of content in a component version. This project is referring to Modular Documentation modules as _content type_. To understand the nature of topics, see the link:https://redhat-documentation.github.io/modular-docs/#modular-docs-terms-definitions[Appendix A: Modular Documentation Terms and Definitions]. + +pass:[] * Use the link:https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow[Git Forking Workflow]. * link:https://www.eclipse.org/che/docs/che-7/hosted-che/[Eclipse Che hosted by Red Hat] is the recommended IDE to edit and builds the content. -* The relevant tools for editing, validation, and publication workflows are built in the link:https://quay.io/repository/eclipse/che-docs[`che-docs` container]. +* The relevant tools for editing, validation, and publication workflows are available in the link:https://quay.io/repository/eclipse/che-docs[`che-docs` container]. ** link:https://docs.antora.org[Antora] builds the documentation. ** link:https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc] is the markup language. -** link:https://github.com/redhat-documentation/newdoc[Newdoc] generates the topics templates. - ** link:https://github.com/wjdp/htmltest[htmltest] validates the links. -** link:https://docs.errata.ai/vale/about/[Vale] validates the language. - -** link:https://www.shellcheck.net/[ShellCheck] validates the shell scripts. +** link:https://docs.errata.ai/vale/about/[Vale] validates the language. -** link:https://github.com/jhradilek/check-links[Test-adoc] validates the topic files. +** link:https://www.shellcheck.net/[ShellCheck] validates the shell scripts. [id="documentation-workflow"] @@ -50,31 +54,55 @@ TIP: For Antora, a link:https://docs.antora.org/antora/2.3/module-directories/#m .Procedure +pass:[] + . Contributor submits a code pull request in one of the Che repositories with a `status/doc-impact` label. . The author of the code pull request or the reviewer ensures the code pull request contains a reference to a documentation pull request for the `master` branch of the `che-docs` repository: -.. The author of the code pull request or the reviewer provides a complete documentation pull request that can then be merged by the members of the documentation team without further editing. +.. The author of the code pull request or the reviewer provides a documentation pull request that the members of the documentation team can merge without further editing. -.. Or, the author of the code pull request or the reviewer provides at least an initial draft of the content and reaches out to the documentation-team members for assistance with editing, so that the documentation pull request can be finalized. +.. Or, the author of the code pull request or the reviewer provides at least an initial draft of the content and reaches out to the documentation-team members for assistance with editing, to help finalizing the documentation pull request. .. Or, the author of the code pull request or the reviewer reaches out to the members of the documentation team and work with them on submitting a documentation pull request. -. Review the documentation pull request. See xref:editing-submitting-and-reviewing-new-content[]. +. xref:reviewing-a-documentation-pull-request[Review the documentation pull request]. . Merge the code pull request into the `che` repository, for next milestone `x.y.z`. -. The documentation pull request, validated, stays in the queue in the `che-docs` repository. +. Merge the documentation content for next milestone `x.y.z` into the `master` branch of the `che-docs` repository. . Release `che` milestone `x.y.z`. -. Merge the documentation content for milestone `x.y.z` into the `master` branch of the `che-docs` repository. +. link:https://github.com/eclipse/che-docs/blob/main/RELEASE.adoc[Release Eclipse Che documentation]. + +. https://github.com/eclipse-che/che-docs/blob/publication-builder/README.adoc[Publish Eclipse Che documentation]. + +pass:[] + +[id="reviewing-a-documentation-pull-request"] +== Reviewing a documentation pull request + +Review the pull request in the Eclipse Che hosted by Red Hat IDE. -. Publish the `che-docs` `master` branch to https://www.eclipse.org/che/docs. +.Procedure + +. Navigate to the pull request + +. Click on the _Eclipse Che hosted by Red Hat_ link in the comments. + +. Build and validate the documentation, and start the preview server: open _My Workspace > User Runtimes > che-docs > Start preview server_. + +. Watch the output of the _Start preview server_ task to validate the build: internal and external links, language on created and changed files. + +. Navigate to the preview: open _Preview_. +. Open created and changed files, and examine the _Problems Panel_ to validate the language. Toggle the view of the _Problems Panel_ using the _View > Problems_ menu entry. -[id="editing-submitting-and-reviewing-new-content"] -== Editing, submitting and reviewing new content +. Review the pull request. See the xref:code_review_checklist.adoc[code review checklist]. + +[id="editing-submitting-and-reviewing-content"] +== Editing, submitting and reviewing content .Prerequisites @@ -87,195 +115,218 @@ TIP: For Antora, a link:https://docs.antora.org/antora/2.3/module-directories/#m . Create a branch `____` for your work. . Edit the content. ++ +* xref:creating-a-page[] +* xref:creating-a-partial[] +* xref:creating-a-partial[] +* xref:adding-a-contextual-example[] +* xref:adding-an-image[] +* xref:using-special-characters[] -. Build and validate the new content. See: xref:building-and-validating-the-documentation-using-che[]. +. Build and validate the documentation, and start the preview server: open _My Workspace > User Runtimes > che-docs > Start preview server_. -. To merge the content, open a pull request. Submit the pull request against the default `+master+` branch. Specify as much information as possible in the pull request template. +. Watch the output of the _Start preview server_ task to validate the build: internal and external links, language on created and changed files. -. When you intend to review a pull request, click Assignees in the GitHub pull request view. This indicates you are the reviewer and avoids duplication of efforts. +. Navigate to the preview: open _Preview_. -. To review the pull request: +. Open created and changed files, and examine the _Problems Panel_ to validate the language. Toggle the view of the _Problems Panel_ using the _View > Problems_ menu entry. -.. See the xref:code_review_checklist.adoc[code review checklist]. +. To merge the content, open a pull request to the default `+main+` branch. -.. For documentation updates containing testable steps, the documentation pull request needs to have the `team/che-qe` label set and get reviewed by both the documentation team and the Che QA team. +. When you intend to review a pull request, assign yourself in the GitHub pull request view. -.. For documentation updates not containing testable steps, the documentation pull request needs to get reviewed by the documentation team. +. Review the pull request. See xref:reviewing-a-documentation-pull-request[Reviewing a documentation pull request]. -.. For more information, see xref:building-and-validating-the-documentation-using-che[]. +. The documentation pull request needs a review by the documentation team and by engineering. -. The continuous integration process is publishing content once merged in the `+master+` publication branch. +. The continuous integration process is publishing content after merge in the release branch. .Verification steps * Navigate to the publication URL of Eclipse Che Documentation: link:https://www.eclipse.org/che/docs/[] and search for your changes. -[id="building-and-validating-the-documentation-using-che"] -== Building and validating the documentation using Che - -To build the Eclipse Che documentation from a Che workspace, follow the steps below. +[id="creating-a-page"] +== Creating a page -.Prerequisites +Create a link:https://docs.antora.org/antora/2.3/page/[page] and add it to the navigation when it is meaningful to have a navigation entry, or when it may receive link:https://docs.antora.org/antora/2.3/page/page-id/[cross references]. Avoid cross references to a page link:https://docs.antora.org/antora/2.3/page/page-id/#id-fragment[fragment]. The file name determines the page URL. Therefore an AsciiDoc attribute defines the content type, rather than a file name prefix. +The page content type can be: -* Open a Che workspace containing a fork of the documentation. See xref:editing-submitting-and-reviewing-new-content[]. +* link:https://redhat-documentation.github.io/modular-docs/#forming-assemblies[:_content-type: ASSEMBLY] +* link:https://redhat-documentation.github.io/modular-docs/#creating-concept-modules[:_content-type: CONCEPT] +* link:https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules[:_content-type: PROCEDURE] +* link:https://redhat-documentation.github.io/modular-docs/#creating-reference-modules[:_content-type: REFERENCE] .Procedure -pass:[] - -. To build the documentation and start the preview server: open _My Workspace / User Runtimes / che-docs / Start preview server_. - -. To navigate to the preview, open _Preview_. - -. To validate the links: open _User Runtimes / che-docs / Validate links_. - -. To validate the language changes: open _My Workspace / User Runtimes / che-docs / Validate language changes_. - -. To validate the language of the currently open files, look at the _Problems_ tab in the _Bottom Panel_. To toggle the view of this tab use the _View > Problems_ menu entry. +. Copy one of the templates in the `templates/pages` directory to `modules/____/pages/____.adoc`. ++ +* link:https://github.com/eclipse/che-docs/blob/main/templates/pages/assembly.adoc[Assembly page template] +* link:https://github.com/eclipse/che-docs/blob/main/templates/pages/concept.adoc[Concept page template] +* https://github.com/eclipse/che-docs/blob/main/templates/pages/procedure.adoc[Procedure page template] +* https://github.com/eclipse/che-docs/blob/main/templates/pages/reference.adoc[Reference page template] -. To validate the compliance of an AsciiDoc file with Modular Documentation guidelines: +. Add a cross reference to the page in the `modules/____/nav.adoc` navigation file to create the link:https://docs.antora.org/antora/2.3/navigation/xrefs-and-link-text/#default-link-text[navigation entry]. ++ +.Navigation entry +==== +[subs="+attributes,quotes"] +---- +* xref:____.adoc[] +---- +==== -.. In the _Explorer_, right-click on file to validate and select _Copy Path_. +. Edit the metadata in the file. ++ +.Template metadata for a page +==== +[subs="+attributes,quotes"] +---- +:description: A description of the page stored in an HTML meta tag. +:keywords: comma-separated values, stored, in an HTML, meta, tag +:navtitle: Title +// :page-aliases: -.. Open _My Workspace / User Runtimes / che-docs / Validate Modular Doc_. +[id="title_{context}"] += Title +---- +==== -.. In the _Validate Modular Doc_ panel in the _Bottom Panel_, paste the path of the file to validate. +. Author the content. -.. The tool `+test-adoc+` tests the file and produces some output. +[id="creating-a-partial"] +== Creating a partial -[id="creating-a-new-topic-using-che"] -== Creating a new topic using Che +Create a link:https://docs.antora.org/antora/2.3/page/partials-and-content-snippets/[partial] and add it to an assembly page when it may not receive cross references. For consistency with the pages, an AsciiDoc attribute defines the content type. +The partial content type can be: -To create a new topic using a Che workspace: +* link:https://redhat-documentation.github.io/modular-docs/#creating-concept-modules[:_content-type: CONCEPT] +* link:https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules[:_content-type: PROCEDURE] +* link:https://redhat-documentation.github.io/modular-docs/#creating-reference-modules[:_content-type: REFERENCE] .Procedure -. Open _My Workspace_. -. Open _User Runtimes / tools / Create a new topic_. -. Choose the target guide among the available guides: +. Copy one of the templates in the `templates/partials` directory to `modules/____/partials/____.adoc`. + -* `+overview+`: introductory section -* `+end-user-guide+`: documentation for developers: navigating -dashboard, working in Che-Theia, and so on -* `+installation-guide+`: installation guides -* `+administration-guide+`: documentation for administrators of the -clusters: configuring Che on a cluster, managing users, monitoring -resources, security and data recovery -* `+contributor-guide+`: how to develop plug-ins for Che, add new -debuggers, languages, and so on -* `+extensions+`: documentation about extensions for Che, such as -Eclipse Che4z, OpenShift Connector. - -. Choose the topic nature: +* link:https://github.com/eclipse/che-docs/blob/main/templates/partials/concept.adoc[Concept partial template] +* https://github.com/eclipse/che-docs/blob/main/templates/partials/procedure.adoc[Procedure partial template] +* https://github.com/eclipse/che-docs/blob/main/templates/partials/reference.adoc[Reference partial template] + +. Add an include statement in the corresponding page `modules/____/pages/____.adoc`: + -* `+assembly+` -* `+concept+` -* `+procedure+` -* `+reference+` +.Include statement to a partial, in a page +==== +`pass:a,c,m[include::partial$__<file_name>__.adoc[leveloffset=+1]]` +==== -. Enter the title for the new topic. +. Edit the metadata in the file. ++ +.Template metadata for a partial +==== +[subs="+attributes,quotes"] +---- +[id="title_{context}"] += Title +---- +==== -.Verification steps +. Author the content. -. The file is generated in the `+src/main/pages-che-7/<guide_name>/+` directory and the script displays related information. -pass:[<!-- vale IBM.Slash = YES -->] +[id="adding-a-contextual-example"] +== Adding a contextual example -== Adding images +Create a contextual link:https://docs.antora.org/antora/2.3/page/examples-and-source-snippets/[example] when upstream and downstream need a different content. The include statement contains the `project-context` attribute to ensure upstream and downstream use a different file. +These link:https://redhat-documentation.github.io/modular-docs/#using-text-snippets[snippets] have no content type. .Procedure -. Add images to one of the subdirectories in the `+src/main/che/docs/images/+` directory. Create a new subdirectory if none of the existing ones fits the new image. +. Create an empty file `modules/__<guide_name>__/examples/snip_che___<lowercase_title>__.adoc`. -. To publish an image, use the following syntax: -+ -.... -image::directory/img.png[alt text] -.... -+ -Images are sized automatically. You can provide a URL to a full-size image, as well as a caption and alt text: +. Add an include statement in the corresponding page `templates` directory to `modules/__<guide_name>__/pages/__<title>__.adoc`. + -.... -.Click to view a larger image -[link=che/docs/images/devel/js_flow.png -image::devel/js_flow.png[Alt text] -.... - -Do not post too many images unless it is absolutely necessary. Animated `+.gif+` images are preferred, especially when explaining how to use complex UI features. - -== Using special characters - -* To prevent special characters from being interpreted as formatting mark-up, use pass-through macros. -+ -.To escape underscores, asterisks, or backticks, use: ==== -.... -pass:[VARIABLE_NAME__WITH__UNDERSCORES] -.... +`pass:a,c,m[include::example$snip_{project-context_}__<file_name>__.adoc[leveloffset=+1]]` ==== -== Building and validating Documentation on a local environment using the `che-docs` container +. Author the content. -This section describes how to build and validate the documentation on a local environment. -WARNING: This is not the preferred method. For the supported method, see: xref:building-and-validating-the-documentation-using-che[]. +[id="adding-an-image"] +== Adding an image -.Prerequisites: - -* A running installation of link:http://podman.io[podman] or link:http://docker.io[docker]. +Avoid using images unless necessary. .Procedure -. Open a terminal into the project directory, and build the documentation using and instance of the `che-docs` container: -+ ----- -$ ./tools/runnerpreview.sh ----- - -. Navigate to `+localhost:4000+` in your browser. +. Add the image to the `+modules/__<guide_name>__/images/+` directory corresponding to the guide including the image. -. Open a second terminal, and attach to the running `che-docs` container. Run all following steps from this context. +. To publish a block image, use the following syntax. See link:https://docs.antora.org/antora/2.3/page/block-images/[Antora documentation - Add block images] and link:https://docs.asciidoctor.org/asciidoc/latest/macros/images/[Asciidoctor documantation - Images]. + +.Block image +==== ---- -$ podman exec -ti che-docs bash +.__<Image caption>__ +image::__<image_name>__.png[__<Image title>__] ---- +==== -. To validate links, run: +. The publication tool resizes images. To provide a link to a full-size image, add a `link` attribute: + +.Block image with a link to the full size image +==== ---- -$ htmltest +.__<Image caption>__ +image::__<image_file_name>__[__<Image title>__,link="../_images/__<image_file_name>__"] ---- +==== -. To validate language on changed files, run: -+ ----- -$ ./tools/validate_language_changes.sh ----- +[id="using-special-characters"] +== Using special characters -. To create a new topic using templates, run following command: +.Procedure + +* To exclude special characters from markup substitutions, use the link:https://docs.asciidoctor.org/asciidoc/latest/pass/pass-macro/#custom-substitutions[inline `pass` macro]. + +.Displaying a variable name containing underscores +==== ---- -$ ./tools/newtopic.sh +pass:a,c,m[VARIABLE_NAME__WITH__UNDERSCORES] ---- +Result:: +pass:a,c,m[VARIABLE_NAME__WITH__UNDERSCORES] +==== + +== Building and validating Documentation on a local environment + +This section describes how to build and validate the documentation on a local environment using the `che-docs` container. -. To validate the compliance of an AsciiDoc file with Modular Documentation standards, run: +WARNING: This is not the preferred method. For the supported method, see: xref:editing-submitting-and-reviewing-content[]. + +.Prerequisites: + +* A running installation of link:http://podman.io[podman] or link:http://docker.io[docker]. + +.Procedure + +. Open a shell prompt into the project directory, and build and validate the documentation using and instance of the `che-docs` container. + ---- -$ ./tools/test-adoc.sh <PATH_TO_THE_FILE> ----- +$ ./tools/runnerpreview.sh +---- +. Read the output for the results of the links and language validation steps. + +. Navigate to `+localhost:4000+` in your browser. == Getting support .GitHub issue -* https://github.com/eclipse/che/issues/new?labels=area/doc,kind/question[image:https://img.shields.io/badge/New-question-blue.svg?style=flat-curved[New -questions]] +* https://github.com/eclipse/che/issues/new?labels=area/doc,kind/question[image:https://img.shields.io/badge/New-question-blue.svg?style=flat-curved[Ask a question]] -* https://github.com/eclipse/che/issues/new?labels=area/doc,kind/bug[image:https://img.shields.io/badge/New-bug-red.svg?style=flat-curved[New -bug]] +* https://github.com/eclipse/che/issues/new?labels=area/doc,kind/bug[image:https://img.shields.io/badge/New-bug-red.svg?style=flat-curved[Open a bug]] .Public Chat diff --git a/Jenkinsfile b/Jenkinsfile deleted file mode 100644 index 3f0c774b03..0000000000 --- a/Jenkinsfile +++ /dev/null @@ -1,140 +0,0 @@ -/* groovylint-disable NestedBlockDepth */ -pipeline { - agent { - kubernetes { - label 'che-docs-pod' - yaml ''' -apiVersion: v1 -metadata: - labels: - run: che-docs-pod - name: che-docs-pod -spec: - containers: - - name: jnlp - volumeMounts: - - mountPath: /home/jenkins/.ssh - name: volume-known-hosts - env: - - name: "HOME" - value: "/home/jenkins/agent" - resources: - limits: - memory: "512Mi" - cpu: "100m" - requests: - memory: "512Mi" - cpu: "100m" - - name: che-docs - image: quay.io/eclipse/che-docs - command: - - cat - resources: - limits: - memory: "512Mi" - cpu: "100m" - requests: - memory: "512Mi" - cpu: "100m" - tty: true - volumes: - - configMap: - name: known-hosts - name: volume-known-hosts -''' - } - } - - environment { - PROJECT_NAME = 'che' - PROJECT_BOT_NAME = 'CHE Bot' - CI = true - } - - triggers { cron('@daily') - // The Jenkins Pipeline builds Eclipse Che documentation for the publication - // to Eclipse website https://www.eclipse.org/che/docs/. - // - // It is: - // * Executing the build from the *Execution branch*. - // * Using the content from the *Publication branches*. - // * Pushing the build artifacts to the `che` repository on Eclipse Git server. - // - // Eclipse infrastructure then publishes to Eclipse website: https://www.eclipse.org/che/docs/. - // - // Execution branch:: - // - // The build runs on a branch containing at least the `Jenkinsfile` and `antora-playbook.yml` files. - // It does not need to run at all on other branches. - // By convention: restrict the build to the `main`, `master` and `publication` branches. - // - // Publication branch(es):: - // - // The build is using the content from the publication branch(es) defined in the `antora-playbook.yml` file. - // - // Triggers:: - // - // Ideally, run the build when a change in the publication branch happened. - // But it impossible to implement in current context with the available - // `pollSCM` or `upstream` triggers https://www.jenkins.io/doc/book/pipeline/syntax/#triggers - // It would be possible to implement using the `upstream` trigger with a dedicated - // Jenkins job for the Publication branch, and a dedicated Jenkins job for the Execution branch. - // Pragmatic solution: run daily with the `cron` trigger. - // - } - - options { - buildDiscarder(logRotator(numToKeepStr: '5')) - checkoutToSubdirectory('che-docs') - disableConcurrentBuilds(abortPrevious: true) - timeout(time: 30, unit: 'MINUTES') - } - - stages { - stage('Build che-docs website') { - when { - anyOf { - branch 'main' - branch 'master' - branch 'publication' - } - beforeAgent true - } - steps { - milestone 21 - container('che-docs') { - dir('che-docs') { - sh './tools/build-for-publication.sh' - } - } - milestone 22 - } - post { - always { - archiveArtifacts artifacts: 'che-docs/build/**', fingerprint: true - } - } - } - - stage('Push to Eclipse repository') { - when { - anyOf { - branch 'main' - branch 'master' - branch 'publication' - } - beforeAgent true - } - steps { - milestone 41 - sh 'ls -la' - dir('www') { - sshagent(['git.eclipse.org-bot-ssh']) { - sh '../che-docs/tools/push-to-eclipse-repository.sh' - } - } - milestone 42 - } - } - } -} diff --git a/RELEASE.adoc b/RELEASE.adoc new file mode 100644 index 0000000000..bbc821628d --- /dev/null +++ b/RELEASE.adoc @@ -0,0 +1,5 @@ +:toc: + += Releasing Eclipse Che documentation + +See link:https://github.com/eclipse/che-docs/blob/main/RELEASE.adoc[] \ No newline at end of file diff --git a/RELEASE.md b/RELEASE.md deleted file mode 100644 index 76f0ccfcbf..0000000000 --- a/RELEASE.md +++ /dev/null @@ -1,3 +0,0 @@ -# Eclipse Che Docs release - -See `release.yml` workflow, which performs release procedures for Che Docs. \ No newline at end of file diff --git a/antora-playbook-for-development.yml b/antora-playbook-for-development.yml index 65472a35e1..3a5ded8b8d 100644 --- a/antora-playbook-for-development.yml +++ b/antora-playbook-for-development.yml @@ -4,13 +4,18 @@ site: title: Eclipse Che Documentation # Disabling url on purpose to avoid htmltest crawling the live website. # url: https://www.eclipse.org/che/docs - start_page: che-7:overview:introduction-to-eclipse-che.adoc + start_page: docs:overview:introduction-to-eclipse-che.adoc robots: allow content: sources: - url: ./ branches: HEAD - edit_url: "https://github.com/eclipse/che-docs/edit/master/{path}" + edit_url: "https://github.com/eclipse-che/che-docs/edit/master/{path}" +antora: + extensions: + - require: "@antora/lunr-extension" +asciidoc: + sourcemap: true output: destinations: - provider: fs @@ -21,8 +26,15 @@ ui: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable snapshot: true supplemental_files: ./supplemental-ui + output_dir: docs/_ urls: html_extension_style: indexify redirect_facility: static + # latest_prerelease_version_segment: next + # latest_version_segment: stable + latest_version_segment_strategy: replace runtime: cache_dir: ./.cache/antora + log: + failure_level: warn + level: info diff --git a/antora-playbook-for-publication.yml b/antora-playbook-for-publication.yml deleted file mode 100644 index d2e716b06d..0000000000 --- a/antora-playbook-for-publication.yml +++ /dev/null @@ -1,30 +0,0 @@ ---- -# Use this Antora Playbook for publication, to build the released version branch. -site: - title: Eclipse Che Documentation - # The url property is mandatory to generate the 404 and sitemap files. - url: https://www.eclipse.org/che/docs - start_page: che-7:overview:introduction-to-eclipse-che.adoc - keys: - google_analytics: "UA-37306001-2" - robots: allow -content: - sources: - - url: ./ - branches: "7.40.x" - edit_url: "https://github.com/eclipse/che-docs/edit/7.40.x/{path}" -output: - destinations: - - provider: fs - clean: true - path: build/site -ui: - bundle: - url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable - snapshot: true - supplemental_files: ./supplemental-ui -urls: - html_extension_style: indexify - redirect_facility: static -runtime: - cache_dir: ./.cache/antora diff --git a/antora-playbook-unbranded.yml b/antora-playbook-unbranded.yml deleted file mode 100644 index 7714f2e64f..0000000000 --- a/antora-playbook-unbranded.yml +++ /dev/null @@ -1,23 +0,0 @@ ---- -site: - title: Unbranded Documentation - start_page: che-7:overview:introduction-to-eclipse-che.adoc - robots: allow -content: - sources: - - url: ./ - branches: HEAD - edit_url: 'https://github.com/eclipse/che-docs/edit/master/{path}' - title: Unbranded Documentation -output: - destinations: - - provider: fs - clean: true - path: build/site-unbranded -ui: - bundle: - url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable - snapshot: true - supplemental_files: ./supplemental-ui -runtime: - cache_dir: ./.cache/antora diff --git a/antora.yml b/antora.yml index 6727aa4501..64307a4539 100644 --- a/antora.yml +++ b/antora.yml @@ -1,16 +1,14 @@ --- -name: che-7 +name: docs title: Documentation -version: master -display_version: master +version: next +prerelease: true start_page: overview:introduction-to-eclipse-che.adoc nav: - modules/overview/nav.adoc - modules/hosted-che/nav.adoc - modules/end-user-guide/nav.adoc - - modules/installation-guide/nav.adoc - modules/administration-guide/nav.adoc - - modules/contributor-guide/nav.adoc - modules/extensions/nav.adoc - modules/glossary/nav.adoc asciidoc: @@ -22,11 +20,9 @@ asciidoc: icons: font # for the project broker-ver: "v3.4.0" - che-devfile-registry-container-image: quay.io/eclipse/che-devfile-registry - che-devfile-registry-directory: che-devfile-registry - che-plugin-registry-container-image: quay.io/eclipse/che-plugin-registry che-plugin-registry-directory: che-plugin-registry devworkspace: DevWorkspace + hosted-che-docs: xref:hosted-che:hosted-che.adoc[] identity-provider-docs-url: https://www.keycloak.org/docs/ identity-provider-id: keycloak identity-provider-image-url: quay.io/eclipse/che-keycloak @@ -46,25 +42,16 @@ asciidoc: image-puller-operator-name: Kubernetes Image Puller Operator image-puller-operator-repository-name: kubernetes-image-puller-operator image-puller-repository-name: kubernetes-image-puller - kube-ver-min: "1.19" + kube-ver-min: "1.21" kubernetes: Kubernetes - link-accessing-a-git-repository-via-https: xref:end-user-guide:version-control.adoc#accessing-a-git-repository-via-https_che[Accessing a Git repository using HTTPS] - link-advanced-configuration-options-for-the-che-server: xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[] - link-advanced-configuration-options: xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[] - link-building-a-custom-plug-in-registry: xref:administration-guide:building-and-running-a-custom-registry-image.adoc#building-a-custom-devfile-registry_che[Building a custom devfile registry] - link-cli-github: https://github.com/che-incubator/chectl - link-identity-provider-documentation-openshift-3: https://www.keycloak.org/docs/latest/server_admin/#openshift-3 - link-identity-provider-documentation-openshift-4: https://www.keycloak.org/docs/latest/server_admin/#openshift-4 - link-identity-provider-github: "https://www.keycloak.org/docs/15.0//server_admin/#github" - link-identity-provider-oidc: "https://www.keycloak.org/docs/15.0/server_admin/#_oidc" - link-identity-provider-saml: "https://www.keycloak.org/docs/15.0/server_admin/#saml-v2-0-identity-providers" - link-installing-an-instance: xref:installation-guide:installing-che.adoc[] - link-server-identity-provider-dockerfile-location: https://github.com/eclipse-che/che-server/tree/main/dockerfiles/keycloak - link-viewing-the-state-of-the-cluster-deployment-using-openshift-4-cli-tools: xref:overview:installing-che-on-openshift-4-using-operatorhub.adoc[] + link-oauth2-proxy: link:https://github.com/oauth2-proxy/oauth2-proxy[OAuth2 Proxy] + link-kube-rbac-proxy: link:https://github.com/brancz/kube-rbac-proxy[kube-rbac-proxy] + link-understanding-custom-resources: "link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[Kubernetes - Understanding Custom Resources]" + link-installing-orch-cli: "link:https://kubernetes.io/docs/tasks/tools/#kubectl[Kubernetes - Install Tools: kubectl]" + link-manage-compute-resources-container: "link:https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/[{kubernetes} - Resource management for pods and containers]" + link-prod-cli-documentation: "link:https://github.com/che-incubator/chectl/[`chectl` reference documentation]" namespace: namespace # In context: API namespace - nodejs-stack: nodejs ocp: OpenShift Container Platform - ocp3-ver: "3.11" ocp4-ver: "4.6" orch-cli-link: link:https://kubernetes.io/docs/reference/kubectl/overview/[Overview of kubectl] orch-cli: kubectl @@ -82,26 +69,29 @@ asciidoc: prod-cli: chectl prod-deployment: che prod-docs-url: https://www.eclipse.org/che/docs + prod-docs-url-backup-recovery: link:https://www.eclipse.org/che/docs/che-7/administration-guide/backup-and-recovery/[Backup and recovery] + prod-docs-url-enable-oauth: link:https://www.eclipse.org/che/docs/che-7/administration-guide/configuring-openshift-oauth/[Configuring OpenShift OAuth] prod-home: /home/user prod-host: che-host prod-id-short: che prod-id: eclipse-che + prod-last-version-pre-dwo: v7.41 prod-namespace: eclipse-che prod-operator-image-name: che-operator prod-operator: che-operator - prod-prev-ver-major: "6" - prod-prev-ver: "7.39" + prod-prev-ver: "previous minor version" prod-short: Che + prod-stable-channel: stable + prod-stable-channel-catalog-source: community-operators + prod-stable-channel-package: eclipse-che prod-upstream: Eclipse{nbsp}Che - prod-url: https://che-host:che-port + prod-url: "https://__<che_fqdn>__" prod-ver-major: "7" - prod-ver-patch: "7.40.0" - prod-ver: "7.40" + prod-ver-patch: main + prod-ver: main prod-workspace: che-ws prod: Eclipse Che prod2: Eclipse Che project-context: che repo-path: "" theia-endpoint-image: eclipse/che-theia-endpoint-runtime:next - url-devfile-registry-repo: https://github.com/eclipse/che-devfile-registry - url-plug-in-registry-repo: https://github.com/eclipse/che-plugin-registry diff --git a/devfile.yaml b/devfile.yaml index 6c3cdfe693..d9e2373f11 100644 --- a/devfile.yaml +++ b/devfile.yaml @@ -20,7 +20,7 @@ components: - name: Open-Preview-server port: 4000 attributes: - path: /che-7/overview/introduction-to-eclipse-che/ + path: /docs/next/overview/introduction-to-eclipse-che/ - type: chePlugin reference: https://che-plugin-registry-main.surge.sh/v3/plugins/errata-ai/vale-server/latest/meta.yaml alias: vale-vscode @@ -70,15 +70,6 @@ commands: component: che-docs workdir: /projects/che-docs command: bash tools/newtopic.sh - - name: Validate Modular Doc - actions: - - type: exec - component: che-docs - workdir: /projects/che-docs - command: >- - echo 'Enter path to the file to validate and press Enter:'; - read file; - bash tools/test-adoc.sh $file; - name: Validate links actions: - type: exec @@ -91,9 +82,9 @@ commands: component: che-docs workdir: /projects/che-docs command: sh tools/validate_language_changes.sh - - name: Detect unused images + - name: Detect unused content actions: - type: exec component: che-docs workdir: /projects/che-docs - command: bash tools/detect-unused-images.sh + command: bash tools/detect-unused-content.sh diff --git a/gulpfile.js b/gulpfile.js index a264bd29e5..9766de004d 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -10,7 +10,7 @@ const { parallel, series, src, watch } = require('gulp') const yaml = require('js-yaml') const playbookFilename = 'antora-playbook-for-development.yml' -const playbook = yaml.safeLoad(fs.readFileSync(playbookFilename, 'utf8')) +const playbook = yaml.load(fs.readFileSync(playbookFilename, 'utf8')) const outputDir = (playbook.output || {}).dir || './build/site' const serverConfig = { name: 'Preview Site', livereload, host: '0.0.0.0', port: 4000, root: outputDir } const antoraArgs = ['--playbook', playbookFilename] @@ -32,7 +32,7 @@ function generate(done) { async function serve(done) { connect.server(serverConfig, function () { this.server.on('close', done) - watch(watchPatterns, series(generate, testlang, testhtml)) + watch(watchPatterns, series(generate, testlang, testhtml, detect_unused_content, antora_to_plain_asciidoc)) if (livereload) watch(this.root).on('change', (filepath) => src(filepath, { read: false }).pipe(livereload())) }) } @@ -55,12 +55,10 @@ async function environment_docs_gen() { // Report script errors but don't make gulp fail. try { const { stdout, stderr } = await exec('tools/environment_docs_gen.sh') - console.log(stdout); - console.error(stderr); + console.log(stdout, stderr); } catch (error) { - console.log(error.stdout); - console.log(error.stderr); + console.log(error.stdout, error.stderr); return; } } @@ -69,12 +67,10 @@ async function testhtml() { // Report links errors but don't make gulp fail. try { const { stdout, stderr } = await exec('htmltest') - console.log(stdout); - console.error(stderr); + console.log(stdout, stderr); } catch (error) { - console.log(error.stdout); - console.log(error.stderr); + console.log(error.stdout, error.stderr); return; } } @@ -83,12 +79,34 @@ async function testlang() { // Report language errors but don't make gulp fail. try { const { stdout, stderr } = await exec('./tools/validate_language_changes.sh') - console.log(stdout); - console.error(stderr); + console.log(stdout, stderr); } catch (error) { - console.log(error.stdout); - console.log(error.stderr); + console.log(error.stdout, error.stderr); + return; + } +} + +async function detect_unused_content() { + // Report unused images but don't make gulp fail. + try { + const { stdout, stderr } = await exec('./tools/detect-unused-content.sh') + console.log(stdout, stderr); + } + catch (error) { + console.log(error.stdout, error.stderr); + return; + } +} + +async function antora_to_plain_asciidoc() { + // Report unused images but don't make gulp fail. + try { + const { stdout, stderr } = await exec('./tools/antora-to-plain-asciidoc.sh') + console.log(stdout, stderr); + } + catch (error) { + console.log(error.stdout, error.stderr); return; } } @@ -97,5 +115,5 @@ exports.default = series( parallel(checluster_docs_gen, environment_docs_gen), generate, serve, - parallel(testlang, testhtml) + parallel(testlang, testhtml, detect_unused_content, antora_to_plain_asciidoc) ); diff --git a/make-release.sh b/make-release.sh deleted file mode 100755 index 21232febc5..0000000000 --- a/make-release.sh +++ /dev/null @@ -1,246 +0,0 @@ -#!/bin/bash -# -# Copyright (c) 2021 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# -# Release process automation script. -# 0. Verify VERSION is defined as X.Y.Z -# 1. Start from the accurate branch -# * If Z = 0, start from master branch. -# * Else, start from X.Y.x release branch -# 2. Update versions in `antora.yml`: -# * `prod-ver` = version to release -# * Set other `ver` attributes accordingly. -# 3. Run scripts generating doc -# * checluster_docs_gen.sh -# * environment_docs_gen.sh -# 4. Commit and push to the release branch. -# 5. (If defined) Tag the release - -# Fail on error -set -e - -# set to 1 to actually trigger changes in the release branch -TAG_RELEASE=0 -DOCOMMIT=1 # by default DO commit the change -DOPUSH=1 # by default DO push the change -REPO=git@github.com:eclipse/che-docs -MAIN_BRANCH="master" -USE_TMP_DIR=0 - -while [[ "$#" -gt 0 ]]; do - case $1 in - '-t'|'--trigger-release') - TAG_RELEASE=1 - DOCOMMIT=1 - shift 0 - ;; - '-v'|'--version') - VERSION="$2" - shift 1 - ;; - '-n'|'--nocommit') - DOCOMMIT=0 - DOPUSH=0 - shift 0 - ;; - '--nopush') - DOPUSH=0 - shift 0 - ;; - '-tmp'|'--use-tmp-dir') - USE_TMP_DIR=1 - shift 0 - ;; - esac - shift 1 -done - -usage () -{ - echo " -Usage: $0 --version [VERSION TO RELEASE] -Example: $0 --version 7.25.2 -t - -Options: - --trigger-release, -t Tag this release - --nocommit, -n Do not commit changes to git branches - --nopush Do not push changes to git remote - -tmp, --use-tmp-dir Use a fresh git clone in a temporary directory -" -} - -if [[ ! ${VERSION} ]]; then - usage - exit 1 -fi - -gitClone() { - if [[ ${USE_TMP_DIR} -eq 1 ]]; then - # Getting a local copy with all ta - cd /tmp/ - TMPDIR=tmp-${0##*/}-$VERSION - rm -rf "${TMPDIR}" - git clone $REPO "${TMPDIR}" - cd "/tmp/${TMPDIR}" - git pull - fi -} - -gitBranch() { - # Handle the version branch: create it or update it. - # Check if the branch exists, locally or on the remote. - EXISTING_BRANCH=0 - git fetch - EXISTING_BRANCH=$(git ls-remote --heads origin "${TARGET_BRANCH}") - case ${EXISTING_BRANCH} in - "") echo "[INFO] Creating new branch: ${TARGET_BRANCH} from branch: ${MAIN_BRANCH}." - git checkout "${MAIN_BRANCH}" - git checkout -b "${TARGET_BRANCH}" - ;; - *) echo "[INFO] Updating branch: ${TARGET_BRANCH} from branch: ${MAIN_BRANCH}." - git checkout "${TARGET_BRANCH}" - ;; - esac -} - -gitCommit() { - if [[ ${DOCOMMIT} -eq 1 ]]; then - git add "antora*.yml" "modules/installation-guide/examples/*" - git commit -s -m "release: Bump version to ${VERSION}" - fi -} - -gitPush() { - if [[ ${DOPUSH} -eq 1 ]]; then - git pull origin "${TARGET_BRANCH}" || true - git push origin "${TARGET_BRANCH}" - fi -} - -gitPullRequest() { - if [[ ${DOCOMMIT} -eq 1 ]]; then - git pull origin "${TARGET_BRANCH}" || true - git push origin "${TARGET_BRANCH}" - LASTCOMMITCOMMENT="$(git log -1 --pretty=%B)" - hub pull-request --force --message "${LASTCOMMITCOMMENT}" --base "${MAIN_BRANCH}" --head "${TARGET_BRANCH}" - fi -} - -gitTag() { - if [[ ${TAG_RELEASE} -eq 1 ]]; then - echo "[INFO] Creating release tag" - git checkout "${TARGET_BRANCH}" - git pull origin "${TARGET_BRANCH}" || true - git tag "${VERSION}" - git push origin "${VERSION}" || true - fi -} - -versionFormatIsValid() { -# Validating version format -[[ ${VERSION} =~ ^([0-9]+)\.([0-9]+)\.([0-9]+) ]] && MAJOR="${BASH_REMATCH[1]}" ; MINOR="${BASH_REMATCH[2]}"; PATCH="${BASH_REMATCH[3]}" -case ${MAJOR} in - "") echo "[ERROR] Version ${VERSION} is not in form MAJOR.MINOR.PATCH." - exit 1 - ;; -esac -case ${MINOR} in - "") echo "[ERROR] Version ${VERSION} is not in form MAJOR.MINOR.PATCH." - exit 1 - ;; -esac -case ${PATCH} in - "") echo "[ERROR] Version ${VERSION} is not in form MAJOR.MINOR.PATCH." - exit 1 - ;; -esac -echo "[INFO] Version format for: ${VERSION} is in form MAJOR.MINOR.PATCH." -} - -versionIsIncremented() { - # Validation version is incremented, never decremented - OLDVERSION="$(yq -r '.asciidoc.attributes."prod-ver-patch"' "${YAMLFILE}")" # existing prod-ver-patch version 7.yy.z - VERSIONS="${OLDVERSION} ${VERSION}" - VERSIONS_SORTED="$(echo "${VERSIONS}" | tr " " "\n" | sort -V | tr "\n" " ")" - # echo "Compare '${VERSIONS_SORTED}' with '${VERSIONS} '" - if [[ "${VERSIONS_SORTED}" != "${VERSIONS} " ]] || [[ "${OLDVERSION}" == "${VERSION}" ]]; then # note trailing space after VERSIONS is required! - echo "[ERROR] Target version ${VERSION} is smaller than existing version: ${OLDVERSION}. Version should not go backwards, so nothing to do!" - return 1 - fi - echo "[INFO] Target version: ${VERSION} is an increment for current version: ${OLDVERSION}." -} - -replaceFieldSed() -{ - YAMLFILE=$1 - YAMLKEY=$2 - YAMLVALUE=$3 - echo "[INFO] Updating file: ${YAMLFILE} on branch: ${TARGET_BRANCH}: setting attribute: ${YAMLKEY}: ${YAMLVALUE}" - sed -i "${YAMLFILE}" -r -e "s#( ${YAMLKEY}: ).+#\1${YAMLVALUE}#" -} - -versionUpdate() { - # Update the version, defined in the antora.yml file, in following keys: - # prod-prev-ver-major: "6" [never changes] - # prod-ver-major: "7" [never changes] - # prod-prev-ver: "7.24" [always prod-ver - 1] - # prod-ver: "7.25" - # prod-ver-patch: "7.25.2" - # Major version upgrade is expected to fail. - YAMLFILE=antora.yml - # prod-ver should never go down, only up - versionIsIncremented - replaceFieldSed "${YAMLFILE}" 'prod-ver-major' "\"${MAJOR}\"" - replaceFieldSed "${YAMLFILE}" 'prod-ver' "\"${MAJOR}.${MINOR}\"" - replaceFieldSed "${YAMLFILE}" 'prod-ver-patch' "\"${MAJOR}.${MINOR}.${PATCH}\"" - replaceFieldSed "${YAMLFILE}" 'prod-prev-ver' "\"${MAJOR}.$((MINOR - 1))\"" - # Update the version, defined in the antora-playbook-for-publication.yml file, in following keys: - # branches: 7.32.x - # edit_url: "https://github.com/eclipse/che-docs/edit/7.35.x/{path}" - YAMLFILE=antora-playbook-for-publication.yml - if [ -f "${YAMLFILE}" ] - then - replaceFieldSed "${YAMLFILE}" 'branches' "\"${MAJOR}.${MINOR}.x\"" - replaceFieldSed "${YAMLFILE}" 'edit_url' "\"https://github.com/eclipse/che-docs/edit/${MAJOR}.${MINOR}.x/{path}\"" - else - echo "[WARNING] Cannot find file: ${YAMLFILE} on branch: ${TARGET_BRANCH}. Skipping." - fi - echo "[INFO] Generating single-sourced docs on branch: ${TARGET_BRANCH}." - ./tools/checluster_docs_gen.sh - ./tools/environment_docs_gen.sh - echo "[INFO] Finished handling version update on branch: ${TARGET_BRANCH}.." -} - -# Validate the version format. -versionFormatIsValid - -# Get a working copy if necessary. -gitClone - -# Update version in the version branch and in the main branch. -for TARGET_BRANCH in "${MAJOR}.${MINOR}.x" "release-${VERSION}" -do - gitBranch - versionUpdate - gitCommit - gitPush - case ${TARGET_BRANCH} in - "${MAJOR}.${MINOR}.x") - gitTag - ;; - "release-${VERSION}") - gitPullRequest - ;; - esac -done - -echo "[INFO] Project version has been updated" - -if [[ ${USE_TMP_DIR} -eq 1 ]]; then - rm -fr "/tmp/${TMPDIR}" -fi diff --git a/modules/administration-guide/attachments/migration/1-prepare.sh b/modules/administration-guide/attachments/migration/1-prepare.sh new file mode 100755 index 0000000000..f9c43c1cee --- /dev/null +++ b/modules/administration-guide/attachments/migration/1-prepare.sh @@ -0,0 +1,127 @@ +#!/usr/bin/env bash +set -o errexit +set -o nounset +set -o pipefail + +K8S_CLI=${K8S_CLI:-oc} # {orch-cli} +PRODUCT_DEPLOYMENT_NAME=${PRODUCT_DEPLOYMENT_NAME:-che} # {prod-deployment} +PRODUCT_ID=${PRODUCT_ID:-eclipse-che} # {prod-id} +INSTALLATION_NAMESPACE=${INSTALLATION_NAMESPACE:-eclipse-che} # {prod-namespace} +CHE_CLUSTER_CR_NAME=${CHE_CLUSTER_CR_NAME:-eclipse-che} # {prod-checluster} +IDENTITY_PROVIDER_DEPLOYMENT_NAME=${IDENTITY_PROVIDER_DEPLOYMENT_NAME:-keycloak} # {identity-provider-id} + +ALL_USERS_DUMP="${PRODUCT_ID}"-users.txt +DB_DUMP="${PRODUCT_ID}"-original-db.sql +MIGRATED_DB_DUMP="${PRODUCT_ID}"-migrated-db.sql + +echo "[INFO] Getting identity provider information" + +IDENTITY_PROVIDER_URL=$("${K8S_CLI}" get checluster "${CHE_CLUSTER_CR_NAME}" -n "${INSTALLATION_NAMESPACE}" -o jsonpath="{.status.keycloakURL}" ) +IDENTITY_PROVIDER_SECRET=$("${K8S_CLI}" get checluster/"${CHE_CLUSTER_CR_NAME}" -n "${INSTALLATION_NAMESPACE}" -o jsonpath="{.spec.auth.identityProviderSecret}") +IDENTITY_PROVIDER_PASSWORD=$(if [ -z "${IDENTITY_PROVIDER_SECRET}" ] || [ "${IDENTITY_PROVIDER_SECRET}" == "null" ]; then "${K8S_CLI}" get checluster/"${CHE_CLUSTER_CR_NAME}" -n "${INSTALLATION_NAMESPACE}" -o jsonpath="{.spec.auth.identityProviderPassword}"; else "${K8S_CLI}" get secret "${IDENTITY_PROVIDER_SECRET}" -n "${INSTALLATION_NAMESPACE}" -o jsonpath="{.data.password}" | base64 -d; fi) +IDENTITY_PROVIDER_USERNAME=$(if [ -z "${IDENTITY_PROVIDER_SECRET}" ] || [ "${IDENTITY_PROVIDER_SECRET}" == "null" ]; then "${K8S_CLI}" get checluster/"${CHE_CLUSTER_CR_NAME}" -n "${INSTALLATION_NAMESPACE}" -o jsonpath="{.spec.auth.IdentityProviderAdminUserName}"; else "${K8S_CLI}" get secret "${IDENTITY_PROVIDER_SECRET}" -n "${INSTALLATION_NAMESPACE}" -o jsonpath="{.data.user}" | base64 -d; fi) +IDENTITY_PROVIDER_REALM=$("${K8S_CLI}" get checluster "${CHE_CLUSTER_CR_NAME}" -n "${INSTALLATION_NAMESPACE}" -o jsonpath="{.spec.auth.identityProviderRealm}") + +echo "[INFO] IDENTITY_PROVIDER_URL: ${IDENTITY_PROVIDER_URL}" +echo "[INFO] IDENTITY_PROVIDER_SECRET: ${IDENTITY_PROVIDER_SECRET}" +echo "[INFO] IDENTITY_PROVIDER_USERNAME: ${IDENTITY_PROVIDER_USERNAME}" +echo "[INFO] IDENTITY_PROVIDER_REALM: ${IDENTITY_PROVIDER_REALM}" + +sed_in_place() { + SHORT_UNAME=$(uname -s) + if [ "$(uname)" == "Darwin" ]; then + sed -i '' "$@" + elif [ "${SHORT_UNAME:0:5}" == "Linux" ]; then + sed -i "$@" + fi +} + +refreshToken() { + echo "[INFO] Refreshing identity provier token" + IDENTITY_PROVIDER_TOKEN=$(curl -ks \ + -d "client_id=admin-cli" \ + -d "username=${IDENTITY_PROVIDER_USERNAME}" \ + -d "password=${IDENTITY_PROVIDER_PASSWORD}" \ + -d "grant_type=password" \ + "${IDENTITY_PROVIDER_URL}/realms/master/protocol/openid-connect/token" | jq -r ".access_token") +} + +scaleDownCheServer() { + echo "[INFO] Scaling down ${PRODUCT_DEPLOYMENT_NAME}" + "${K8S_CLI}" scale deployment "${PRODUCT_DEPLOYMENT_NAME}" --replicas=0 -n "${INSTALLATION_NAMESPACE}" +} + +scaleDownKeycloak() { + echo "[INFO] Scaling down ${IDENTITY_PROVIDER_DEPLOYMENT_NAME}" + "${K8S_CLI}" scale deployment "${IDENTITY_PROVIDER_DEPLOYMENT_NAME}" --replicas=0 -n "${INSTALLATION_NAMESPACE}" +} + +getUsers() { + rm -f "${ALL_USERS_DUMP}" + refreshToken + echo "[INFO] Dumping users list in file ${ALL_USERS_DUMP}" + ALL_USERS=$(curl -ks -H "Authorization: bearer ${IDENTITY_PROVIDER_TOKEN}" "${IDENTITY_PROVIDER_URL}/${IDENTITY_PROVIDER_USERNAME}/realms/${IDENTITY_PROVIDER_REALM}/users") + IFS=" " read -r -a ALL_USERS_IDS <<< "$(echo "${ALL_USERS}" | jq ".[] | .id" | tr "\r\n" " ")" + + for USER_ID in "${ALL_USERS_IDS[@]}"; do + refreshToken + + USER_ID=$(echo "${USER_ID}" | tr -d "\"") + FEDERATED_IDENTITY=$(curl -ks -H "Authorization: bearer ${IDENTITY_PROVIDER_TOKEN}" "${IDENTITY_PROVIDER_URL}/${IDENTITY_PROVIDER_USERNAME}/realms/${IDENTITY_PROVIDER_REALM}/users/${USER_ID}/federated-identity") + IDENTITY_PROVIDER=$(echo "${FEDERATED_IDENTITY}" | jq -r ".[] | select(.identityProvider == \"openshift-v4\")") + if [ -n "${IDENTITY_PROVIDER}" ]; then + USER_PROFILE=$(echo "${ALL_USERS}" | jq -r ".[] | select(.id == \"${USER_ID}\")") + USER_EMAIL=$(echo "${USER_PROFILE}" | jq -r ".email") + USER_NAME=$(echo "${USER_PROFILE}" | jq -r ".username") + USER_FIRST_NAME=$(echo "${USER_PROFILE}" | jq -r ".firstName") + USER_LAST_NAME=$(echo "${USER_PROFILE}" | jq -r ".lastName") + + OPENSHIFT_USER_ID=$(echo "${IDENTITY_PROVIDER}" | jq ".userId" | tr -d "\"") + echo "[INFO] Found ${PRODUCT_ID} user: ${USER_ID} and corresponding OpenShift user: ${OPENSHIFT_USER_ID}" + echo "${USER_ID} ${OPENSHIFT_USER_ID} username:$(echo "${USER_NAME}" | base64) email:$(echo "${USER_EMAIL}" | base64) firstName:$(echo "${USER_FIRST_NAME}" | base64) lastName:$(echo "${USER_LAST_NAME}" | base64) " >> "${ALL_USERS_DUMP}" + fi + done + echo "[INFO] Users list dump completed." + +} + +dumpDB() { + echo "[INFO] Dumping database in file ${DB_DUMP}" + + echo "[INFO] Retriving database name" + CHE_POSTGRES_DB=$("${K8S_CLI}" get cm/che -n "${INSTALLATION_NAMESPACE}" -o jsonpath='{.data.CHE_JDBC_URL}' | awk -F '/' '{print $NF}') + if [ -z "${CHE_POSTGRES_DB}" ] || [ "${CHE_POSTGRES_DB}" = "null" ]; then CHE_POSTGRES_DB="dbche"; fi + echo "[INFO] Database name is ${CHE_POSTGRES_DB}" + + echo "[INFO] Executing pg_dump" + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "pg_dump $CHE_POSTGRES_DB > /tmp/che.sql" + + echo "[INFO] Downloading the dump" + "${K8S_CLI}" cp "${INSTALLATION_NAMESPACE}"/"$("${K8S_CLI}" get pods -l app.kubernetes.io/component=postgres -n "${INSTALLATION_NAMESPACE}" --no-headers=true -o custom-columns=":metadata.name")":/tmp/che.sql "${DB_DUMP}" > /dev/null + + echo "[INFO] Database dump completed" +} + +replaceUserIDsInDBDump() { + echo "[INFO] Replacing USER_IDs in ${DB_DUMP} and saving it in ${MIGRATED_DB_DUMP}." + cp "${DB_DUMP}" "${MIGRATED_DB_DUMP}" + while IFS= read -r line + do + IFS=" " read -r -a IDS <<< "${line}" + USER_ID=${IDS[0]} + OPENSHIFT_USER_ID=${IDS[1]} + + sed_in_place -e "s|${USER_ID}|${OPENSHIFT_USER_ID}|g" "${MIGRATED_DB_DUMP}" + + echo "[INFO] Replaced User ID \"${USER_ID}\" with \"${OPENSHIFT_USER_ID}\"." + done < "${ALL_USERS_DUMP}" + echo "[INFO] USER_IDs replaced." +} + +scaleDownCheServer +getUsers +scaleDownKeycloak +dumpDB +replaceUserIDsInDBDump + +echo "[INFO] Done." diff --git a/modules/administration-guide/attachments/migration/2-migrate.sh b/modules/administration-guide/attachments/migration/2-migrate.sh new file mode 100755 index 0000000000..f6e7c4fd85 --- /dev/null +++ b/modules/administration-guide/attachments/migration/2-migrate.sh @@ -0,0 +1,66 @@ +#!/usr/bin/env bash +set -o errexit +set -o nounset +set -o pipefail + +K8S_CLI=${K8S_CLI:-oc} # {orch-cli} +PRODUCT_ID=${PRODUCT_ID:-eclipse-che} # {prod-id} +INSTALLATION_NAMESPACE=${INSTALLATION_NAMESPACE:-eclipse-che} # {prod-namespace} + +ALL_USERS_DUMP="${PRODUCT_ID}"-users.txt +MIGRATED_DB_DUMP="${PRODUCT_ID}"-migrated-db.sql + +echo "[INFO] Retriving ${PRODUCT_ID} database name." +CHE_POSTGRES_DB=$("${K8S_CLI}" get cm/che -n "${INSTALLATION_NAMESPACE}" -o jsonpath='{.data.CHE_JDBC_URL}' | awk -F '/' '{print $NF}') + +terminatePostgresConnections() { + echo "[INFO] Terminating ${PRODUCT_ID} database connections." + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "psql -c \"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '${CHE_POSTGRES_DB}'\"" +} + +dropExistingDatabase() { + echo "[INFO] Dropping ${PRODUCT_ID} database." + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "dropdb ${CHE_POSTGRES_DB}" +} + +createDatabase() { + echo "[INFO] Creating a new ${PRODUCT_ID} database." + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "psql postgres -tAc \"CREATE DATABASE ${CHE_POSTGRES_DB}\"" +} + +restoreDatabase() { + echo "[INFO] Uploading ${MIGRATED_DB_DUMP} to the postgreSQL pod." + "${K8S_CLI}" cp "${MIGRATED_DB_DUMP}" "${INSTALLATION_NAMESPACE}"/"$("${K8S_CLI}" get pods -l app.kubernetes.io/component=postgres -n "${INSTALLATION_NAMESPACE}" --no-headers=true -o custom-columns=":metadata.name")":/tmp/che.sql + + echo "[INFO] Populating ${CHE_POSTGRES_DB} database with the new content." + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "psql ${CHE_POSTGRES_DB} < /tmp/che.sql" +} + +migrateUserProfiles() { + echo "[INFO] Extract users profiles from ${ALL_USERS_DUMP} and insert them in ${CHE_POSTGRES_DB} database." + while IFS= read -r line + do + IFS=" " read -r -a IDS <<< "${line}" + OPENSHIFT_USER_ID=${IDS[1]} + USER_NAME=$(echo "${IDS[2]}" | cut -d ":" -f 2- | base64 -d) + USER_EMAIL=$(echo "${IDS[3]}" | cut -d ":" -f 2- | base64 -d) + USER_FIRST_NAME=$(echo "${IDS[4]}" | cut -d ":" -f 2- | base64 -d) + USER_LAST_NAME=$(echo "${IDS[5]}" | cut -d ":" -f 2- | base64 -d) + + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile(userid) VALUES ('${OPENSHIFT_USER_ID}');\"" + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'preferred_username', '${USER_NAME}');\"" + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'email', '${USER_EMAIL}');\"" + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'firstName', '${USER_FIRST_NAME}');\"" + "${K8S_CLI}" exec deploy/postgres -n "${INSTALLATION_NAMESPACE}" -- bash -c "psql ${CHE_POSTGRES_DB} -tAc \"INSERT INTO profile_attributes(user_id,name, value) VALUES ('${OPENSHIFT_USER_ID}', 'lastName', '${USER_LAST_NAME}');\"" + + echo "[INFO] Added profile for \"${OPENSHIFT_USER_ID}\"." + done < "${ALL_USERS_DUMP}" +} + +terminatePostgresConnections +dropExistingDatabase +createDatabase +restoreDatabase +migrateUserProfiles + +echo "[INFO] Done." diff --git a/modules/administration-guide/attachments/migration/3-subscribe.sh b/modules/administration-guide/attachments/migration/3-subscribe.sh new file mode 100755 index 0000000000..003b4beeb8 --- /dev/null +++ b/modules/administration-guide/attachments/migration/3-subscribe.sh @@ -0,0 +1,83 @@ +#!/usr/bin/env bash +set -o errexit +set -o nounset +set -o pipefail + +K8S_CLI=${K8S_CLI:-oc} # {orch-cli} +PRODUCT_ID=${PRODUCT_ID:-eclipse-che} # {prod-id} +INSTALLATION_NAMESPACE=${INSTALLATION_NAMESPACE:-eclipse-che} # {prod-namespace} +CHE_CLUSTER_CR_NAME=${CHE_CLUSTER_CR_NAME:-eclipse-che} # {prod-checluster} + +OLM_STABLE_CHANNEL=${OLM_STABLE_CHANNEL:-stable} # {prod-stable-channel} +OLM_CATALOG_SOURCE=${OLM_CATALOG_SOURCE:-community-operators} # {prod-stable-channel-catalog-source} +OLM_PACKAGE=${OLM_PACKAGE:-eclipse-che} # {prod-stable-channel-package} +PRODUCT_OPERATOR_NAME=${PRODUCT_OPERATOR_NAME:-che-operator} # {prod-operator} + +IDENTITY_PROVIDER_DEPLOYMENT_NAME=${IDENTITY_PROVIDER_DEPLOYMENT_NAME:-keycloak} # {identity-provider-id} + +deleteOperatorCSV() { + if "${K8S_CLI}" get subscription "${PRODUCT_ID}" -n "${INSTALLATION_NAMESPACE}" > /dev/null 2>&1 ; then + echo "[INFO] Deleting operator cluster service version." + "${K8S_CLI}" delete csv "$("${K8S_CLI}" get subscription "${PRODUCT_ID}" -n "${INSTALLATION_NAMESPACE}" -o jsonpath="{.status.currentCSV}")" -n "${INSTALLATION_NAMESPACE}" + else + echo "[INFO] Skipping CSV deletion. No ${PRODUCT_ID} operator subscription found." + fi +} + +deleteOperatorSubscription() { + if "${K8S_CLI}" get subscription "${PRODUCT_ID}" -n "${INSTALLATION_NAMESPACE}" > /dev/null 2>&1 ; then + echo "[INFO] Deleting ${PRODUCT_ID} operator subscription." + "${K8S_CLI}" delete subscription "${PRODUCT_ID}" -n "${INSTALLATION_NAMESPACE}" + else + echo "[INFO] Skipping subscription deletion as no ${PRODUCT_ID} operator subscription was found." + echo "[INFO] Deleting the ${PRODUCT_ID} operator deployment instead." + "${K8S_CLI}" delete deployment "${PRODUCT_OPERATOR_NAME}" -n "${INSTALLATION_NAMESPACE}" + fi + echo "[INFO] Waiting 30s for the old ${PRODUCT_ID} operator deletion." + sleep 30 +} + +patchCheCluster() { + echo "[INFO] Updating ${CHE_CLUSTER_CR_NAME} CheCluster CR to switch to DevWorkspace and single-host." + "${K8S_CLI}" patch checluster/"${CHE_CLUSTER_CR_NAME}" -n "${INSTALLATION_NAMESPACE}" --type=json -p \ + '[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}]' + "${K8S_CLI}" patch checluster/"${CHE_CLUSTER_CR_NAME}" -n "${INSTALLATION_NAMESPACE}" --type=json -p \ + '[{"op": "replace", "path": "/spec/server/serverExposureStrategy", "value": "single-host"}]' +} + +cleanupIdentityProviderObjects() { + echo "[INFO] Deleting ${IDENTITY_PROVIDER_DEPLOYMENT_NAME} resources." + "${K8S_CLI}" delete route "${IDENTITY_PROVIDER_DEPLOYMENT_NAME}" -n "${INSTALLATION_NAMESPACE}" > /dev/null 2>&1 || echo "[INFO] Route ${IDENTITY_PROVIDER_DEPLOYMENT_NAME} not found." + "${K8S_CLI}" delete service "${IDENTITY_PROVIDER_DEPLOYMENT_NAME}" -n "${INSTALLATION_NAMESPACE}" > /dev/null 2>&1 || echo "[INFO] Service ${IDENTITY_PROVIDER_DEPLOYMENT_NAME} not found." + "${K8S_CLI}" delete deployment "${IDENTITY_PROVIDER_DEPLOYMENT_NAME}" -n "${INSTALLATION_NAMESPACE}" > /dev/null 2>&1 || echo "[INFO] Deployment ${IDENTITY_PROVIDER_DEPLOYMENT_NAME} not found." +} + +createOperatorSubscription() { + echo "[INFO] Creating new ${PRODUCT_ID} operator subscription." + echo "[INFO] New subscription source: ${OLM_CATALOG_SOURCE}." + echo "[INFO] New subscription channel: ${OLM_STABLE_CHANNEL}." + echo "[INFO] New subscription name: ${OLM_PACKAGE}." + + "${K8S_CLI}" apply -f - <<EOF +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: "${PRODUCT_ID}" + namespace: openshift-operators +spec: + channel: "${OLM_STABLE_CHANNEL}" + installPlanApproval: Automatic + name: "${OLM_PACKAGE}" + source: "${OLM_CATALOG_SOURCE}" + sourceNamespace: openshift-marketplace +EOF + +} + +deleteOperatorCSV +deleteOperatorSubscription +patchCheCluster +cleanupIdentityProviderObjects +createOperatorSubscription + +echo "[INFO] Done." diff --git a/modules/administration-guide/attachments/migration/4-wait.sh b/modules/administration-guide/attachments/migration/4-wait.sh new file mode 100755 index 0000000000..a38134c866 --- /dev/null +++ b/modules/administration-guide/attachments/migration/4-wait.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +set -o errexit +set -o nounset +set -o pipefail + +K8S_CLI=${K8S_CLI:-oc} # {orch-cli} +PRODUCT_DEPLOYMENT_NAME=${PRODUCT_DEPLOYMENT_NAME:-che} # {prod-deployment} +INSTALLATION_NAMESPACE=${INSTALLATION_NAMESPACE:-eclipse-che} # {prod-namespace} + +PRODUCT_OPERATOR_NAME=${PRODUCT_OPERATOR_NAME:-che-operator} # {prod-operator} +OPERATOR_NAMESPACE=${OPERATOR_NAMESPACE:-openshift-operators} # {?} + +waitForComponent() { + component=$1 + namespace=$2 + echo "[INFO] Waiting for ${component} Pod to be created" + while [[ $("${K8S_CLI}" get pod -l app.kubernetes.io/component="${component}" -n "${namespace}" -o go-template='{{len .items}}') == 0 ]] + do + echo "[INFO] Waiting..." + sleep 10 + done + echo "[INFO] Waiting for ${component} Pod to be ready" + "${K8S_CLI}" wait --for=condition=ready pod -l app.kubernetes.io/component="${component}" -n "${namespace}" --timeout=120s +} + +waitForComponent "${PRODUCT_DEPLOYMENT_NAME}" "${INSTALLATION_NAMESPACE}" +waitForComponent "${PRODUCT_OPERATOR_NAME}" "${OPERATOR_NAMESPACE}" + +echo "[INFO] Done." diff --git a/modules/installation-guide/examples/checluster-custom-resource.yaml b/modules/administration-guide/examples/checluster-custom-resource.yaml similarity index 100% rename from modules/installation-guide/examples/checluster-custom-resource.yaml rename to modules/administration-guide/examples/checluster-custom-resource.yaml diff --git a/modules/installation-guide/examples/checluster-properties.adoc b/modules/administration-guide/examples/checluster-properties.adoc similarity index 68% rename from modules/installation-guide/examples/checluster-properties.adoc rename to modules/administration-guide/examples/checluster-properties.adoc index 5bedbe68a7..f756e722ff 100644 --- a/modules/installation-guide/examples/checluster-properties.adoc +++ b/modules/administration-guide/examples/checluster-properties.adoc @@ -11,7 +11,7 @@ airGapContainerRegistryOrganization: Optional repository name of an alternate co allowUserDefinedWorkspaceNamespaces: Deprecated. The value of this flag is ignored. Defines that a user is allowed to specify a Kubernetes namespace, or an OpenShift project, which differs from the default. It's NOT RECOMMENDED to set to `true` without OpenShift OAuth configured. The OpenShift infrastructure also uses this property. cheClusterRoles: A comma-separated list of ClusterRoles that will be assigned to Che ServiceAccount. Each role must have `app.kubernetes.io/part-of=che.eclipse.org` label. Be aware that the Che Operator has to already have all permissions in these ClusterRoles to grant them. cheDebug: Enables the debug mode for Che server. Defaults to `false`. -cheFlavor: Specifies a variation of the installation. The options are `che` for upstream Che installations, or `codeready` for link\:https\://developers.redhat.com/products/codeready-workspaces/overview[CodeReady Workspaces] installation. Override the default value only on necessary occasions. +cheFlavor: Deprecated. The value of this flag is ignored. Specifies a variation of the installation. The options are `che` for upstream Che installations, or `devspaces` for link\:https\://developers.redhat.com/products/codeready-workspaces/overview[Red Hat OpenShift Dev Spaces] installation. Override the default value only on necessary occasions. cheHost: Public host name of the installed Che server. When value is omitted, the value it will be automatically set by the Operator. See the `cheHostTLSSecret` field. cheHostTLSSecret: Name of a secret containing certificates to secure ingress or route for the custom host name of the installed Che server. The secret must have `app.kubernetes.io/part-of=che.eclipse.org` label. See the `cheHost` field. cheImage: Overrides the container image used in Che deployment. This does NOT include the container image tag. Omit it or leave it empty to use the default container image provided by the Operator. @@ -26,20 +26,20 @@ dashboardCpuLimit: Overrides the CPU limit used in the dashboard deployment. In dashboardCpuRequest: Overrides the CPU request used in the dashboard deployment. In cores. (500m = .5 cores). Default to 100m. dashboardImage: Overrides the container image used in the dashboard deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. dashboardImagePullPolicy: Overrides the image pull policy used in the dashboard deployment. Default value is `Always` for `nightly`, `next` or `latest` images, and `IfNotPresent` in other cases. -dashboardIngress: Dashboard ingress custom settings. +dashboardIngress: Deprecated. The value of this flag is ignored. Dashboard ingress custom settings. dashboardMemoryLimit: Overrides the memory limit used in the dashboard deployment. Defaults to 256Mi. dashboardMemoryRequest: Overrides the memory request used in the dashboard deployment. Defaults to 16Mi. -dashboardRoute: Dashboard route custom settings. +dashboardRoute: Deprecated. The value of this flag is ignored. Dashboard route custom settings. devfileRegistryCpuLimit: Overrides the CPU limit used in the devfile registry deployment. In cores. (500m = .5 cores). Default to 500m. devfileRegistryCpuRequest: Overrides the CPU request used in the devfile registry deployment. In cores. (500m = .5 cores). Default to 100m. devfileRegistryImage: Overrides the container image used in the devfile registry deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. -devfileRegistryIngress: The devfile registry ingress custom settings. +devfileRegistryIngress: Deprecated. The value of this flag is ignored. The devfile registry ingress custom settings. devfileRegistryMemoryLimit: Overrides the memory limit used in the devfile registry deployment. Defaults to 256Mi. devfileRegistryMemoryRequest: Overrides the memory request used in the devfile registry deployment. Defaults to 16Mi. devfileRegistryPullPolicy: Overrides the image pull policy used in the devfile registry deployment. Default value is `Always` for `nightly`, `next` or `latest` images, and `IfNotPresent` in other cases. -devfileRegistryRoute: The devfile registry route custom settings. +devfileRegistryRoute: Deprecated. The value of this flag is ignored. The devfile registry route custom settings. devfileRegistryUrl: Deprecated in favor of `externalDevfileRegistries` fields. -disableInternalClusterSVCNames: Disable internal cluster SVC names usage to communicate between components to speed up the traffic and avoid proxy issues. +disableInternalClusterSVCNames: Deprecated. The value of this flag is ignored. Disable internal cluster SVC names usage to communicate between components to speed up the traffic and avoid proxy issues. externalDevfileRegistries: External devfile registries, that serves sample, ready-to-use devfiles. Configure this in addition to a dedicated devfile registry (when `externalDevfileRegistry` is `false`) or instead of it (when `externalDevfileRegistry` is `true`) externalDevfileRegistry: Instructs the Operator on whether to deploy a dedicated devfile registry server. By default, a dedicated devfile registry server is started. When `externalDevfileRegistry` is `true`, no such dedicated server will be started by the Operator and configure at least one devfile registry with `externalDevfileRegistries` field. externalPluginRegistry: Instructs the Operator on whether to deploy a dedicated plugin registry server. By default, a dedicated plugin registry server is started. When `externalPluginRegistry` is `true`, no such dedicated server will be started by the Operator and you will have to manually set the `pluginRegistryUrl` field. @@ -48,11 +48,11 @@ nonProxyHosts: List of hosts that will be reached directly, bypassing the proxy. pluginRegistryCpuLimit: Overrides the CPU limit used in the plugin registry deployment. In cores. (500m = .5 cores). Default to 500m. pluginRegistryCpuRequest: Overrides the CPU request used in the plugin registry deployment. In cores. (500m = .5 cores). Default to 100m. pluginRegistryImage: Overrides the container image used in the plugin registry deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. -pluginRegistryIngress: Plugin registry ingress custom settings. +pluginRegistryIngress: Deprecated. The value of this flag is ignored. Plugin registry ingress custom settings. pluginRegistryMemoryLimit: Overrides the memory limit used in the plugin registry deployment. Defaults to 256Mi. pluginRegistryMemoryRequest: Overrides the memory request used in the plugin registry deployment. Defaults to 16Mi. pluginRegistryPullPolicy: Overrides the image pull policy used in the plugin registry deployment. Default value is `Always` for `nightly`, `next` or `latest` images, and `IfNotPresent` in other cases. -pluginRegistryRoute: Plugin registry route custom settings. +pluginRegistryRoute: Deprecated. The value of this flag is ignored. Plugin registry route custom settings. pluginRegistryUrl: Public URL of the plugin registry that serves sample ready-to-use devfiles. Set this ONLY when a use of an external devfile registry is needed. See the `externalPluginRegistry` field. By default, this will be automatically calculated by the Operator. proxyPassword: Password of the proxy server. Only use when proxy configuration is required. See the `proxyURL`, `proxyUser` and `proxySecret` fields. proxyPort: Port of the proxy server. Only use when configuring a proxy is required. See also the `proxyURL` and `nonProxyHosts` fields. @@ -62,7 +62,7 @@ proxyUser: User name of the proxy server. Only use when configuring a proxy is r selfSignedCert: Deprecated. The value of this flag is ignored. The Che Operator will automatically detect whether the router certificate is self-signed and propagate it to other components, such as the Che server. serverCpuLimit: Overrides the CPU limit used in the Che server deployment In cores. (500m = .5 cores). Default to 1. serverCpuRequest: Overrides the CPU request used in the Che server deployment In cores. (500m = .5 cores). Default to 100m. -serverExposureStrategy: Sets the server and workspaces exposure type. Possible values are `multi-host`, `single-host`, `default-host`. Defaults to `multi-host`, which creates a separate ingress, or OpenShift routes, for every required endpoint. `single-host` makes Che exposed on a single host name with workspaces exposed on subpaths. Read the docs to learn about the limitations of this approach. Also consult the `singleHostExposureType` property to further configure how the Operator and the Che server make that happen on Kubernetes. `default-host` exposes the Che server on the host of the cluster. Read the docs to learn about the limitations of this approach. +serverExposureStrategy: Deprecated. The value of this flag is ignored. Sets the server and workspaces exposure type. Possible values are `multi-host`, `single-host`, `default-host`. Defaults to `multi-host`, which creates a separate ingress, or OpenShift routes, for every required endpoint. `single-host` makes Che exposed on a single host name with workspaces exposed on subpaths. Read the docs to learn about the limitations of this approach. Also consult the `singleHostExposureType` property to further configure how the Operator and the Che server make that happen on Kubernetes. `default-host` exposes the Che server on the host of the cluster. Read the docs to learn about the limitations of this approach. serverMemoryLimit: Overrides the memory limit used in the Che server deployment. Defaults to 1Gi. serverMemoryRequest: Overrides the memory request used in the Che server deployment. Defaults to 512Mi. serverTrustStoreConfigMapName: Name of the ConfigMap with public certificates to add to Java trust store of the Che server. This is often required when adding the OpenShift OAuth provider, which has HTTPS endpoint signed with self-signed cert. The Che server must be aware of its CA cert to be able to request it. This is disabled by default. The Config Map must have `app.kubernetes.io/part-of=che.eclipse.org` label. @@ -72,6 +72,9 @@ singleHostGatewayImage: The image used for the gateway in the single host mode. tlsSupport: Deprecated. Instructs the Operator to deploy Che in TLS mode. This is enabled by default. Disabling TLS sometimes cause malfunction of some Che components. useInternalClusterSVCNames: Deprecated in favor of `disableInternalClusterSVCNames`. workspaceNamespaceDefault: Defines Kubernetes default namespace in which user's workspaces are created for a case when a user does not override it. It's possible to use `<username>`, `<userid>` and `<workspaceid>` placeholders, such as che-workspace-<username>. In that case, a new namespace will be created for each user or workspace. +workspacePodNodeSelector: The node selector that limits the nodes that can run the workspace pods. +workspacePodTolerations: The pod tolerations put on the workspace pods to limit where the workspace pods can run. +workspacesDefaultPlugins: Default plug-ins applied to Devworkspaces. :=== [id="checluster-custom-resource-database-settings_{context}"] @@ -85,7 +88,7 @@ chePostgresDb: PostgreSQL database name that the Che server uses to connect to t chePostgresHostName: PostgreSQL Database host name that the Che server uses to connect to. Defaults is `postgres`. Override this value ONLY when using an external database. See field `externalDb`. In the default case it will be automatically set by the Operator. chePostgresPassword: PostgreSQL password that the Che server uses to connect to the DB. When omitted or left blank, it will be set to an automatically generated value. chePostgresPort: PostgreSQL Database port that the Che server uses to connect to. Defaults to 5432. Override this value ONLY when using an external database. See field `externalDb`. In the default case it will be automatically set by the Operator. -chePostgresSecret: The secret that contains PostgreSQL`user` and `password` that the Che server uses to connect to the DB. When the secret is defined, the `chePostgresUser` and `chePostgresPassword` are ignored. When the value is omitted or left blank, the one of following scenarios applies\: 1. `chePostgresUser` and `chePostgresPassword` are defined, then they will be used to connect to the DB. 2. `chePostgresUser` or `chePostgresPassword` are not defined, then a new secret with the name `che-postgres-secret` will be created with default value of `pgche` for `user` and with an auto-generated value for `password`. The secret must have `app.kubernetes.io/part-of=che.eclipse.org` label. +chePostgresSecret: The secret that contains PostgreSQL`user` and `password` that the Che server uses to connect to the DB. When the secret is defined, the `chePostgresUser` and `chePostgresPassword` are ignored. When the value is omitted or left blank, the one of following scenarios applies\: 1. `chePostgresUser` and `chePostgresPassword` are defined, then they will be used to connect to the DB. 2. `chePostgresUser` or `chePostgresPassword` are not defined, then a new secret with the name `postgres-credentials` will be created with default value of `pgche` for `user` and with an auto-generated value for `password`. The secret must have `app.kubernetes.io/part-of=che.eclipse.org` label. chePostgresUser: PostgreSQL user that the Che server uses to connect to the DB. Defaults to `pgche`. externalDb: Instructs the Operator on whether to deploy a dedicated database. By default, a dedicated PostgreSQL database is deployed as part of the Che installation. When `externalDb` is `true`, no dedicated database will be deployed by the Operator and you will need to provide connection details to the external DB you are about to use. See also all the fields starting with\: `chePostgres`. postgresImage: Overrides the container image used in the PostgreSQL database deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. @@ -100,30 +103,30 @@ pvcClaimSize: Size of the persistent volume claim for database. Defaults to `1Gi [cols="2,5", options="header"] :=== Property: Description -debug: Debug internal identity provider. -externalIdentityProvider: Instructs the Operator on whether or not to deploy a dedicated Identity Provider (Keycloak or RH SSO instance). Instructs the Operator on whether to deploy a dedicated Identity Provider (Keycloak or RH-SSO instance). By default, a dedicated Identity Provider server is deployed as part of the Che installation. When `externalIdentityProvider` is `true`, no dedicated identity provider will be deployed by the Operator and you will need to provide details about the external identity provider you are about to use. See also all the other fields starting with\: `identityProvider`. +debug: Deprecated. The value of this flag is ignored. Debug internal identity provider. +externalIdentityProvider: Deprecated. The value of this flag is ignored. Instructs the Operator on whether or not to deploy a dedicated Identity Provider (Keycloak or RH SSO instance). Instructs the Operator on whether to deploy a dedicated Identity Provider (Keycloak or RH-SSO instance). By default, a dedicated Identity Provider server is deployed as part of the Che installation. When `externalIdentityProvider` is `true`, no dedicated identity provider will be deployed by the Operator and you will need to provide details about the external identity provider you are about to use. See also all the other fields starting with\: `identityProvider`. gatewayAuthenticationSidecarImage: Gateway sidecar responsible for authentication when NativeUserMode is enabled. See link\:https\://github.com/oauth2-proxy/oauth2-proxy[oauth2-proxy] or link\:https\://github.com/openshift/oauth-proxy[openshift/oauth-proxy]. gatewayAuthorizationSidecarImage: Gateway sidecar responsible for authorization when NativeUserMode is enabled. See link\:https\://github.com/brancz/kube-rbac-proxy[kube-rbac-proxy] or link\:https\://github.com/openshift/kube-rbac-proxy[openshift/kube-rbac-proxy] gatewayHeaderRewriteSidecarImage: Deprecated. The value of this flag is ignored. Sidecar functionality is now implemented in Traefik plugin. -identityProviderAdminUserName: Overrides the name of the Identity Provider administrator user. Defaults to `admin`. -identityProviderClientId: Name of a Identity provider, Keycloak or RH-SSO, `client-id` that is used for Che. Override this when an external Identity Provider is in use. See the `externalIdentityProvider` field. When omitted or left blank, it is set to the value of the `flavour` field suffixed with `-public`. -identityProviderContainerResources: Identity provider container custom settings. -identityProviderImage: Overrides the container image used in the Identity Provider, Keycloak or RH-SSO, deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. -identityProviderImagePullPolicy: Overrides the image pull policy used in the Identity Provider, Keycloak or RH-SSO, deployment. Default value is `Always` for `nightly`, `next` or `latest` images, and `IfNotPresent` in other cases. -identityProviderIngress: Ingress custom settings. -identityProviderPassword: Overrides the password of Keycloak administrator user. Override this when an external Identity Provider is in use. See the `externalIdentityProvider` field. When omitted or left blank, it is set to an auto-generated password. -identityProviderPostgresPassword: Password for a Identity Provider, Keycloak or RH-SSO, to connect to the database. Override this when an external Identity Provider is in use. See the `externalIdentityProvider` field. When omitted or left blank, it is set to an auto-generated password. -identityProviderPostgresSecret: The secret that contains `password` for the Identity Provider, Keycloak or RH-SSO, to connect to the database. When the secret is defined, the `identityProviderPostgresPassword` is ignored. When the value is omitted or left blank, the one of following scenarios applies\: 1. `identityProviderPostgresPassword` is defined, then it will be used to connect to the database. 2. `identityProviderPostgresPassword` is not defined, then a new secret with the name `che-identity-postgres-secret` will be created with an auto-generated value for `password`. The secret must have `app.kubernetes.io/part-of=che.eclipse.org` label. -identityProviderRealm: Name of a Identity provider, Keycloak or RH-SSO, realm that is used for Che. Override this when an external Identity Provider is in use. See the `externalIdentityProvider` field. When omitted or left blank, it is set to the value of the `flavour` field. -identityProviderRoute: Route custom settings. -identityProviderSecret: The secret that contains `user` and `password` for Identity Provider. When the secret is defined, the `identityProviderAdminUserName` and `identityProviderPassword` are ignored. When the value is omitted or left blank, the one of following scenarios applies\: 1. `identityProviderAdminUserName` and `identityProviderPassword` are defined, then they will be used. 2. `identityProviderAdminUserName` or `identityProviderPassword` are not defined, then a new secret with the name `che-identity-secret` will be created with default value `admin` for `user` and with an auto-generated value for `password`. The secret must have `app.kubernetes.io/part-of=che.eclipse.org` label. +identityProviderAdminUserName: Deprecated. The value of this flag is ignored. Overrides the name of the Identity Provider administrator user. Defaults to `admin`. +identityProviderClientId: Deprecated. The value of this flag is ignored. Name of a Identity provider, Keycloak or RH-SSO, `client-id` that is used for Che. Override this when an external Identity Provider is in use. See the `externalIdentityProvider` field. When omitted or left blank, it is set to the value of the `flavour` field suffixed with `-public`. +identityProviderContainerResources: Deprecated. The value of this flag is ignored. Identity provider container custom settings. +identityProviderImage: Deprecated. The value of this flag is ignored. Overrides the container image used in the Identity Provider, Keycloak or RH-SSO, deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. +identityProviderImagePullPolicy: Deprecated. The value of this flag is ignored. Overrides the image pull policy used in the Identity Provider, Keycloak or RH-SSO, deployment. Default value is `Always` for `nightly`, `next` or `latest` images, and `IfNotPresent` in other cases. +identityProviderIngress: Deprecated. The value of this flag is ignored. Ingress custom settings. +identityProviderPassword: Deprecated. The value of this flag is ignored. Overrides the password of Keycloak administrator user. Override this when an external Identity Provider is in use. See the `externalIdentityProvider` field. When omitted or left blank, it is set to an auto-generated password. +identityProviderPostgresPassword: Deprecated. The value of this flag is ignored. Password for a Identity Provider, Keycloak or RH-SSO, to connect to the database. Override this when an external Identity Provider is in use. See the `externalIdentityProvider` field. When omitted or left blank, it is set to an auto-generated password. +identityProviderPostgresSecret: Deprecated. The value of this flag is ignored. The secret that contains `password` for the Identity Provider, Keycloak or RH-SSO, to connect to the database. When the secret is defined, the `identityProviderPostgresPassword` is ignored. When the value is omitted or left blank, the one of following scenarios applies\: 1. `identityProviderPostgresPassword` is defined, then it will be used to connect to the database. 2. `identityProviderPostgresPassword` is not defined, then a new secret with the name `che-identity-postgres-secret` will be created with an auto-generated value for `password`. The secret must have `app.kubernetes.io/part-of=che.eclipse.org` label. +identityProviderRealm: Deprecated. The value of this flag is ignored. Name of a Identity provider, Keycloak or RH-SSO, realm that is used for Che. Override this when an external Identity Provider is in use. See the `externalIdentityProvider` field. When omitted or left blank, it is set to the value of the `flavour` field. +identityProviderRoute: Deprecated. The value of this flag is ignored. Route custom settings. +identityProviderSecret: Deprecated. The value of this flag is ignored. The secret that contains `user` and `password` for Identity Provider. When the secret is defined, the `identityProviderAdminUserName` and `identityProviderPassword` are ignored. When the value is omitted or left blank, the one of following scenarios applies\: 1. `identityProviderAdminUserName` and `identityProviderPassword` are defined, then they will be used. 2. `identityProviderAdminUserName` or `identityProviderPassword` are not defined, then a new secret with the name `che-identity-secret` will be created with default value `admin` for `user` and with an auto-generated value for `password`. The secret must have `app.kubernetes.io/part-of=che.eclipse.org` label. identityProviderURL: Public URL of the Identity Provider server (Keycloak / RH-SSO server). Set this ONLY when a use of an external Identity Provider is needed. See the `externalIdentityProvider` field. By default, this will be automatically calculated and set by the Operator. -initialOpenShiftOAuthUser: For operating with the OpenShift OAuth authentication, create a new user account since the kubeadmin can not be used. If the value is true, then a new OpenShift OAuth user will be created for the HTPasswd identity provider. If the value is false and the user has already been created, then it will be removed. If value is an empty, then do nothing. The user's credentials are stored in the `openshift-oauth-user-credentials` secret in 'openshift-config' namespace by Operator. Note that this solution is Openshift 4 platform-specific. -nativeUserMode: Enables native user mode. Currently works only on OpenShift and DevWorkspace engine. Native User mode uses OpenShift OAuth directly as identity provider, without Keycloak. +initialOpenShiftOAuthUser: Deprecated. The value of this flag is ignored. For operating with the OpenShift OAuth authentication, create a new user account since the kubeadmin can not be used. If the value is true, then a new OpenShift OAuth user will be created for the HTPasswd identity provider. If the value is false and the user has already been created, then it will be removed. If value is an empty, then do nothing. The user's credentials are stored in the `openshift-oauth-user-credentials` secret in 'openshift-config' namespace by Operator. Note that this solution is Openshift 4 platform-specific. +nativeUserMode: Deprecated. The value of this flag is ignored. Enables native user mode. Currently works only on OpenShift and DevWorkspace engine. Native User mode uses OpenShift OAuth directly as identity provider, without Keycloak. oAuthClientName: Name of the OpenShift `OAuthClient` resource used to setup identity federation on the OpenShift side. Auto-generated when left blank. See also the `OpenShiftoAuth` field. oAuthSecret: Name of the secret set in the OpenShift `OAuthClient` resource used to setup identity federation on the OpenShift side. Auto-generated when left blank. See also the `OAuthClientName` field. -openShiftoAuth: Enables the integration of the identity provider (Keycloak / RHSSO) with OpenShift OAuth. Empty value on OpenShift by default. This will allow users to directly login with their OpenShift user through the OpenShift login, and have their workspaces created under personal OpenShift namespaces. WARNING\: the `kubeadmin` user is NOT supported, and logging through it will NOT allow accessing the Che Dashboard. -updateAdminPassword: Forces the default `admin` Che user to update password on first login. Defaults to `false`. +openShiftoAuth: Deprecated. The value of this flag is ignored. Enables the integration of the identity provider (Keycloak / RHSSO) with OpenShift OAuth. Empty value on OpenShift by default. This will allow users to directly login with their OpenShift user through the OpenShift login, and have their workspaces created under personal OpenShift namespaces. WARNING\: the `kubeadmin` user is NOT supported, and logging through it will NOT allow accessing the Che Dashboard. +updateAdminPassword: Deprecated. The value of this flag is ignored. Forces the default `admin` Che user to update password on first login. Defaults to `false`. :=== [id="checluster-custom-resource-storage-settings_{context}"] @@ -148,10 +151,10 @@ workspacePVCStorageClassName: Storage class for the Persistent Volume Claims ded Property: Description ingressClass: Ingress class that will define the which controller will manage ingresses. Defaults to `nginx`. NB\: This drives the `kubernetes.io/ingress.class` annotation on Che-related ingresses. ingressDomain: Global ingress domain for a Kubernetes cluster. This MUST be explicitly specified\: there are no defaults. -ingressStrategy: Strategy for ingress creation. Options are\: `multi-host` (host is explicitly provided in ingress), `single-host` (host is provided, path-based rules) and `default-host` (no host is provided, path-based rules). Defaults to `multi-host` Deprecated in favor of `serverExposureStrategy` in the `server` section, which defines this regardless of the cluster type. When both are defined, the `serverExposureStrategy` option takes precedence. +ingressStrategy: Deprecated. The value of this flag is ignored. Strategy for ingress creation. Options are\: `multi-host` (host is explicitly provided in ingress), `single-host` (host is provided, path-based rules) and `default-host` (no host is provided, path-based rules). Defaults to `multi-host` Deprecated in favor of `serverExposureStrategy` in the `server` section, which defines this regardless of the cluster type. When both are defined, the `serverExposureStrategy` option takes precedence. securityContextFsGroup: The FSGroup in which the Che Pod and workspace Pods containers runs in. Default value is `1724`. securityContextRunAsUser: ID of the user the Che Pod and workspace Pods containers run as. Default value is `1724`. -singleHostExposureType: When the serverExposureStrategy is set to `single-host`, the way the server, registries and workspaces are exposed is further configured by this property. The possible values are `native`, which means that the server and workspaces are exposed using ingresses on K8s or `gateway` where the server and workspaces are exposed using a custom gateway based on link\:https\://doc.traefik.io/traefik/[Traefik]. All the endpoints whether backed by the ingress or gateway `route` always point to the subpaths on the same domain. Defaults to `native`. +singleHostExposureType: Deprecated. The value of this flag is ignored. When the serverExposureStrategy is set to `single-host`, the way the server, registries and workspaces are exposed is further configured by this property. The possible values are `native`, which means that the server and workspaces are exposed using ingresses on K8s or `gateway` where the server and workspaces are exposed using a custom gateway based on link\:https\://doc.traefik.io/traefik/[Traefik]. All the endpoints whether backed by the ingress or gateway `route` always point to the subpaths on the same domain. Defaults to `native`. tlsSecretName: Name of a secret that will be used to setup ingress TLS termination when TLS is enabled. When the field is empty string, the default cluster certificate will be used. See also the `tlsSupport` field. :=== diff --git a/modules/installation-guide/examples/con_che-understanding-network-connectivity-in-restricted-environments.adoc b/modules/administration-guide/examples/con_che-understanding-network-connectivity-in-restricted-environments.adoc similarity index 83% rename from modules/installation-guide/examples/con_che-understanding-network-connectivity-in-restricted-environments.adoc rename to modules/administration-guide/examples/con_che-understanding-network-connectivity-in-restricted-environments.adoc index 5e02bc7b94..1a4deef366 100644 --- a/modules/installation-guide/examples/con_che-understanding-network-connectivity-in-restricted-environments.adoc +++ b/modules/administration-guide/examples/con_che-understanding-network-connectivity-in-restricted-environments.adoc @@ -1,4 +1,3 @@ -[id="understanding-network-connectivity-in-restricted-environments_{context}"] = Understanding network connectivity in restricted environments {prod-short} requires that each {platforms-ingress} created for {prod-short} is accessible from inside the {platforms-name} cluster. @@ -8,7 +7,7 @@ Consider the network topology of the environment to determine how best to accomp .Network owned by a company or an organization, disconnected from the public Internet ==== -The network administrators must ensure that it is possible to route traffic bound from the cluster to {platforms-ingress} host names. +The network administrators must ensure that it is possible to route traffic bound from the cluster to {platforms-ingress} hostnames. ==== .Private subnetwork in a cloud provider diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/AnalyticsManagerSkeleton.java b/modules/administration-guide/examples/creating-a-telemetry-plug-in/AnalyticsManagerSkeleton.java new file mode 100644 index 0000000000..8a59ab363d --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/AnalyticsManagerSkeleton.java @@ -0,0 +1,52 @@ +package org.my.group; + +import java.util.HashMap; +import java.util.Map; + +import javax.enterprise.context.Dependent; +import javax.enterprise.inject.Alternative; +import javax.inject.Inject; + +import org.eclipse.che.incubator.workspace.telemetry.base.AbstractAnalyticsManager; +import org.eclipse.che.incubator.workspace.telemetry.base.AnalyticsEvent; +import org.eclipse.che.incubator.workspace.telemetry.finder.DevWorkspaceFinder; +import org.eclipse.che.incubator.workspace.telemetry.finder.UsernameFinder; +import org.eclipse.microprofile.rest.client.inject.RestClient; +import org.slf4j.Logger; + +import static org.slf4j.LoggerFactory.getLogger; + +@Dependent +@Alternative +public class AnalyticsManager extends AbstractAnalyticsManager { + + private static final Logger LOG = getLogger(AbstractAnalyticsManager.class); + + public AnalyticsManager(MainConfiguration mainConfiguration, DevWorkspaceFinder devworkspaceFinder, UsernameFinder usernameFinder) { + super(mainConfiguration, devworkspaceFinder, usernameFinder); + + mainConfiguration.welcomeMessage.ifPresentOrElse( <1> + (str) -> LOG.info("The welcome message is: {}", str), + () -> LOG.info("No welcome message provided") + ); + } + + @Override + public boolean isEnabled() { + return true; + } + + @Override + public void destroy() {} + + @Override + public void onEvent(AnalyticsEvent event, String ownerId, String ip, String userAgent, String resolution, Map<String, Object> properties) { + LOG.info("The received event is: {}", event); <2> + } + + @Override + public void increaseDuration(AnalyticsEvent event, Map<String, Object> properties) { } + + @Override + public void onActivity() {} +} diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/Dockerfile.jvm b/modules/administration-guide/examples/creating-a-telemetry-plug-in/Dockerfile.jvm new file mode 100644 index 0000000000..0b1df0c4f8 --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/Dockerfile.jvm @@ -0,0 +1,13 @@ +FROM registry.access.redhat.com/ubi8/openjdk-11:1.11 + +ENV LANG='en_US.UTF-8' LANGUAGE='en_US:en' + +COPY --chown=185 target/quarkus-app/lib/ /deployments/lib/ +COPY --chown=185 target/quarkus-app/*.jar /deployments/ +COPY --chown=185 target/quarkus-app/app/ /deployments/app/ +COPY --chown=185 target/quarkus-app/quarkus/ /deployments/quarkus/ + +EXPOSE 8080 +USER 185 + +ENTRYPOINT ["java", "-Dquarkus.http.host=0.0.0.0", "-Djava.util.logging.manager=org.jboss.logmanager.LogManager", "-Dquarkus.http.port=${DEVWORKSPACE_TELEMETRY_BACKEND_PORT}", "-jar", "/deployments/quarkus-run.jar"] diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/Dockerfile.native b/modules/administration-guide/examples/creating-a-telemetry-plug-in/Dockerfile.native new file mode 100644 index 0000000000..1ca112934a --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/Dockerfile.native @@ -0,0 +1,11 @@ +FROM registry.access.redhat.com/ubi8/ubi-minimal:8.5 +WORKDIR /work/ +RUN chown 1001 /work \ + && chmod "g+rwX" /work \ + && chown 1001:root /work +COPY --chown=1001:root target/*-runner /work/application + +EXPOSE 8080 +USER 1001 + +CMD ["./application", "-Dquarkus.http.host=0.0.0.0", "-Dquarkus.http.port=$DEVWORKSPACE_TELEMETRY_BACKEND_PORT}"] diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/MainConfiguration.java b/modules/administration-guide/examples/creating-a-telemetry-plug-in/MainConfiguration.java new file mode 100644 index 0000000000..b2a9bf0027 --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/MainConfiguration.java @@ -0,0 +1,16 @@ +package org.my.group; + +import java.util.Optional; + +import javax.enterprise.context.Dependent; +import javax.enterprise.inject.Alternative; + +import org.eclipse.che.incubator.workspace.telemetry.base.BaseConfiguration; +import org.eclipse.microprofile.config.inject.ConfigProperty; + +@Dependent +@Alternative +public class MainConfiguration extends BaseConfiguration { + @ConfigProperty(name = "welcome.message") <1> + Optional<String> welcomeMessage; <2> +} diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/TelemetryService.java b/modules/administration-guide/examples/creating-a-telemetry-plug-in/TelemetryService.java new file mode 100644 index 0000000000..99c25aaa33 --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/TelemetryService.java @@ -0,0 +1,19 @@ +package org.my.group; + +import java.util.Map; + +import javax.ws.rs.Consumes; +import javax.ws.rs.POST; +import javax.ws.rs.Path; +import javax.ws.rs.core.MediaType; +import javax.ws.rs.core.Response; + +import org.eclipse.microprofile.rest.client.inject.RegisterRestClient; + +@RegisterRestClient +public interface TelemetryService { + @POST + @Path("/event") <1> + @Consumes(MediaType.APPLICATION_JSON) + Response sendEvent(Map<String, Object> payload); +} diff --git a/modules/extensions/examples/telemetry/destroy.java b/modules/administration-guide/examples/creating-a-telemetry-plug-in/destroy.java similarity index 100% rename from modules/extensions/examples/telemetry/destroy.java rename to modules/administration-guide/examples/creating-a-telemetry-plug-in/destroy.java diff --git a/modules/extensions/examples/telemetry/increaseDuration.java b/modules/administration-guide/examples/creating-a-telemetry-plug-in/increaseDuration.java similarity index 100% rename from modules/extensions/examples/telemetry/increaseDuration.java rename to modules/administration-guide/examples/creating-a-telemetry-plug-in/increaseDuration.java diff --git a/modules/extensions/examples/telemetry/isEnabled.java b/modules/administration-guide/examples/creating-a-telemetry-plug-in/isEnabled.java similarity index 100% rename from modules/extensions/examples/telemetry/isEnabled.java rename to modules/administration-guide/examples/creating-a-telemetry-plug-in/isEnabled.java diff --git a/modules/extensions/examples/telemetry/main.go b/modules/administration-guide/examples/creating-a-telemetry-plug-in/main.go similarity index 100% rename from modules/extensions/examples/telemetry/main.go rename to modules/administration-guide/examples/creating-a-telemetry-plug-in/main.go diff --git a/modules/extensions/examples/telemetry/onActivity.java b/modules/administration-guide/examples/creating-a-telemetry-plug-in/onActivity.java similarity index 64% rename from modules/extensions/examples/telemetry/onActivity.java rename to modules/administration-guide/examples/creating-a-telemetry-plug-in/onActivity.java index 2abdb204e1..7b11cce6e2 100644 --- a/modules/extensions/examples/telemetry/onActivity.java +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/onActivity.java @@ -2,14 +2,13 @@ public class AnalyticsManager extends AbstractAnalyticsManager { ... - private long inactiveTimeLimt = 60000 * 3; + private long inactiveTimeLimit = 60000 * 3; ... - @Override public void onActivity() { - if (System.currentTimeMillis() - lastEventTime >= inactiveTimeLimt) { - onEvent(WORKSPACE_INACTIVE, lastOwnerId, lastIp, lastUserAgent, lastResolution, commonProperties); - } - } + if (System.currentTimeMillis() - lastEventTime >= inactiveTimeLimit) { + onEvent(WORKSPACE_INACTIVE, lastOwnerId, lastIp, lastUserAgent, lastResolution, commonProperties); + } + } diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/onEvent.java b/modules/administration-guide/examples/creating-a-telemetry-plug-in/onEvent.java new file mode 100644 index 0000000000..17454b31c0 --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/onEvent.java @@ -0,0 +1,15 @@ +@Dependent +@Alternative +public class AnalyticsManager extends AbstractAnalyticsManager { + @Inject + @RestClient + TelemetryService telemetryService; + +... + +@Override +public void onEvent(AnalyticsEvent event, String ownerId, String ip, String userAgent, String resolution, Map<String, Object> properties) { + Map<String, Object> payload = new HashMap<String, Object>(properties); + payload.put("event", event); + telemetryService.sendEvent(payload); +} diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/plugin.yaml b/modules/administration-guide/examples/creating-a-telemetry-plug-in/plugin.yaml new file mode 100644 index 0000000000..8af5c3f623 --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/plugin.yaml @@ -0,0 +1,17 @@ +schemaVersion: 2.1.0 +metadata: + name: devworkspace-telemetry-backend-plugin + version: 0.0.1 + description: A Demo telemetry backend + displayName: Devworkspace Telemetry Backend +components: + - name: devworkspace-telemetry-backend-plugin + attributes: + workspaceEnv: + - name: DEVWORKSPACE_TELEMETRY_BACKEND_PORT + value: '4167' + container: + image: YOUR IMAGE <1> + env: + - name: WELCOME_MESSAGE <2> + value: 'hello world!' diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/pom_snippet.xml b/modules/administration-guide/examples/creating-a-telemetry-plug-in/pom_snippet.xml new file mode 100644 index 0000000000..dc20f6bd85 --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/pom_snippet.xml @@ -0,0 +1,17 @@ +<!-- Required --> +<dependency> + <groupId>org.eclipse.che.incubator.workspace-telemetry</groupId> + <artifactId>backend-base</artifactId> + <version>LATEST VERSION FROM PREVIOUS STEP</version> +</dependency> + + +<!-- Used to make http requests to the telemetry server --> +<dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-rest-client</artifactId> +</dependency> +<dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-rest-client-jackson</artifactId> +</dependency> diff --git a/modules/administration-guide/examples/creating-a-telemetry-plug-in/project_scaffolding.sh b/modules/administration-guide/examples/creating-a-telemetry-plug-in/project_scaffolding.sh new file mode 100644 index 0000000000..31cb0c2ab3 --- /dev/null +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/project_scaffolding.sh @@ -0,0 +1,3 @@ +mvn io.quarkus:quarkus-maven-plugin:2.7.1.Final:create \ + -DprojectGroupId=mygroup -DprojectArtifactId=devworkspace-telemetry-example-plugin \ +-DprojectVersion=1.0.0-SNAPSHOT diff --git a/modules/extensions/examples/telemetry/settings.xml b/modules/administration-guide/examples/creating-a-telemetry-plug-in/settings.xml similarity index 50% rename from modules/extensions/examples/telemetry/settings.xml rename to modules/administration-guide/examples/creating-a-telemetry-plug-in/settings.xml index 61388ad365..745912d00a 100644 --- a/modules/extensions/examples/telemetry/settings.xml +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/settings.xml @@ -5,8 +5,8 @@ http://maven.apache.org/xsd/settings-1.0.0.xsd"> <servers> <server> <id>che-incubator</id> - <username>${env.GITHUB_USERNAME}</username> - <password>${env.GITHUB_TOKEN}</password> + <username>YOUR GITHUB USERNAME</username> + <password>YOUR GITHUB TOKEN</password> </server> </servers> @@ -20,15 +20,14 @@ http://maven.apache.org/xsd/settings-1.0.0.xsd"> <repository> <id>central</id> <url>https://repo1.maven.org/maven2</url> - <releases><enabled>true</enabled></releases> - <snapshots><enabled>false</enabled></snapshots> - </repository> - <repository> - <id>che-incubator</id> - <name>GitHub navikt Apache Maven Packages</name> - <url>https://maven.pkg.github.com/che-incubator/che-workspace-telemetry-client</url> - </repository> - </repositories> - </profile> - </profiles> - </settings> + <releases><enabled>true</enabled></releases> + <snapshots><enabled>false</enabled></snapshots> + </repository> + <repository> + <id>che-incubator</id> + <url>https://maven.pkg.github.com/che-incubator/che-workspace-telemetry-client</url> + </repository> + </repositories> + </profile> + </profiles> +</settings> diff --git a/modules/extensions/examples/telemetry/webserver.yaml b/modules/administration-guide/examples/creating-a-telemetry-plug-in/webserver.yaml similarity index 83% rename from modules/extensions/examples/telemetry/webserver.yaml rename to modules/administration-guide/examples/creating-a-telemetry-plug-in/webserver.yaml index 8867408933..1d856db1ae 100644 --- a/modules/extensions/examples/telemetry/webserver.yaml +++ b/modules/administration-guide/examples/creating-a-telemetry-plug-in/webserver.yaml @@ -2,7 +2,6 @@ kind: Deployment apiVersion: apps/v1 metadata: name: apache - namespace: __<{prod-namespace}>__ spec: replicas: 1 selector: @@ -14,9 +13,9 @@ spec: app: apache spec: volumes: - - name: plugin-meta-yaml + - name: plugin-yaml configMap: - name: telemetry-plugin-meta + name: telemetry-plugin-yaml defaultMode: 420 containers: - name: apache @@ -26,7 +25,7 @@ spec: protocol: TCP resources: {} volumeMounts: - - name: plugin-meta-yaml + - name: plugin-yaml mountPath: /var/www/html strategy: type: RollingUpdate @@ -40,7 +39,6 @@ kind: Service apiVersion: v1 metadata: name: apache - namespace: __<{prod-namespace}>__ spec: ports: - protocol: TCP @@ -54,7 +52,6 @@ kind: Route apiVersion: route.openshift.io/v1 metadata: name: apache - namespace: __<{prod-namespace}>__ spec: host: apache-che.apps-crc.testing to: diff --git a/modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc b/modules/administration-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc similarity index 75% rename from modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc rename to modules/administration-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc index 1a260bb959..74f7a89282 100644 --- a/modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc +++ b/modules/administration-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc @@ -1,6 +1,3 @@ -[id="configuring-{prod-id-short}-to-run-in-a-restricted-environment_{context}"] -= Configuring {prod-short} to run in a restricted environment - This section describes how to configure {prod-short} and related containers to use images in a restricted environment rather than the default images in an online registry. .Prerequisites @@ -15,16 +12,16 @@ This procedure uses the following placeholders: [cols="1,2"] |=== | `<my-internal-registry>` -| a host name of the container-image registry, accessible in the restricted environment, see xref:preparing-a-private-registry_{context}[] +| a hostname of the container-image registry, accessible in the restricted environment, see xref:preparing-a-restricted-environment.adoc[] | `<my-organization>` | organization of the container-image registry | `<my-offline-plug-in-registry>` -| offline plug-in registry, see xref:building-an-offline-plug-in-registry-image_{context}[] +| offline plug-in registry, see xref:preparing-a-restricted-environment.adoc[] | `<my-offline-devfile-registry>` -| offline devfile registry, see xref:building-an-offline-devfile-registry-image_{context}[] +| offline devfile registry, see xref:preparing-a-restricted-environment.adoc[] | `<ver>` | release of {prod-short} that is being deployed diff --git a/modules/administration-guide/partials/proc_developing-grafana-dashboards.adoc b/modules/administration-guide/examples/proc_che-developing-grafana-dashboards.adoc similarity index 88% rename from modules/administration-guide/partials/proc_developing-grafana-dashboards.adoc rename to modules/administration-guide/examples/proc_che-developing-grafana-dashboards.adoc index b19ed0dbe6..ae46030617 100644 --- a/modules/administration-guide/partials/proc_developing-grafana-dashboards.adoc +++ b/modules/administration-guide/examples/proc_che-developing-grafana-dashboards.adoc @@ -13,12 +13,12 @@ To add a custom panel, use the *New dashboard* view. . In the first section, define *Queries to*. Use the _Prometheus Query Language_ to construct a specific metric, as well as to modify it with various aggregation operators. + .New Grafana dashboard: Queries to -image::monitoring/monitoring-che-new-grafana-dashboard-queries.png[Grafana Dashboard queries, link="../_images/monitoring/monitoring-che-new-grafana-dashboard-queries.png"] +image::monitoring/monitoring-che-new-grafana-dashboard-queries.png[Grafana Dashboard queries, link="{imagesdir}/monitoring/monitoring-che-new-grafana-dashboard-queries.png"] . In the *Visualisation* section, choose a metric to be shown in the following visual in the form of a graph, gauge, heatmap, or others. + .New Grafana dashboard: Visualization -image::monitoring/monitoring-che-new-grafana-dashboard-visualization.png[Grafana dashboard visualization, link="../_images/monitoring/monitoring-che-new-grafana-dashboard-visualization.png"] +image::monitoring/monitoring-che-new-grafana-dashboard-visualization.png[Grafana dashboard visualization, link="{imagesdir}/monitoring/monitoring-che-new-grafana-dashboard-visualization.png"] . Save changes to the dashboard using the btn:[Save] button, and copy and paste the JSON code to the deployment. diff --git a/modules/installation-guide/partials/proc_installing-the-chectl-management-tool-on-linux-or-macos.adoc b/modules/administration-guide/examples/proc_che-installing-the-chectl-management-tool-on-linux-or-macos.adoc similarity index 100% rename from modules/installation-guide/partials/proc_installing-the-chectl-management-tool-on-linux-or-macos.adoc rename to modules/administration-guide/examples/proc_che-installing-the-chectl-management-tool-on-linux-or-macos.adoc diff --git a/modules/installation-guide/partials/proc_installing-the-chectl-management-tool-on-windows.adoc b/modules/administration-guide/examples/proc_che-installing-the-chectl-management-tool-on-windows.adoc similarity index 100% rename from modules/installation-guide/partials/proc_installing-the-chectl-management-tool-on-windows.adoc rename to modules/administration-guide/examples/proc_che-installing-the-chectl-management-tool-on-windows.adoc diff --git a/modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc b/modules/administration-guide/examples/proc_che-preparing-a-private-registry.adoc similarity index 82% rename from modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc rename to modules/administration-guide/examples/proc_che-preparing-a-private-registry.adoc index 539990790a..a5dbc49dbc 100644 --- a/modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc +++ b/modules/administration-guide/examples/proc_che-preparing-a-private-registry.adoc @@ -20,14 +20,14 @@ Running any workspace requires these _essential_ images: | {identity-provider} Pod for user authentication | `quay.io/eclipse/che-jwtproxy` -| JWT proxy image for enabling authentication between services. See xref:administration-guide:che-workspaces-architecture-with-che-server.adoc#che-workspace-jwt-proxy_{context}[Che workspace JWT proxy]. +| JWT proxy image for enabling authentication between services. | `quay.io/eclipse/che-plugin-artifacts-broker` + `quay.io/eclipse/che-plugin-metadata-broker` -| Images for adding plug-ins to workspaces. See xref:administration-guide:che-workspaces-architecture-with-che-server.adoc#che-plug-in-broker_{context}[Che plug-ins broker]. +| Images for adding plug-ins to workspaces. | `quay.io/eclipse/che-plugin-registry` -| Plug-in registry that store information about plugins and the runtime containers they require. See xref:building-an-offline-plug-in-registry-image_{context}[]. +| Plug-in registry that store information about plug-ins and the runtime containers they require. See xref:building-an-offline-plug-in-registry-image_{context}[]. | `quay.io/eclipse/che-devfile-registry` | Devfile registry that stores descriptions of the sample projects and how to load them as workspaces through the Getting Started tab in the dashboard. See xref:building-an-offline-devfile-registry-image_{context}[]. @@ -37,7 +37,7 @@ Running any workspace requires these _essential_ images: The images described in this section are required for running a workspace. Any one workspace uses a subset of the images below. It is only necessary to include the images that are used in workspaces created. For example, when using {prod-short} only for developing in Java, many images can be omitted. -To avoid issues when only a subset of the images described in this section is needed, remove unnecessary plug-ins and devfiles when building custom registries (see xref:administration-guide:customizing-the-registries.adoc[] for more information). +To avoid issues when only a subset of the images described in this section is needed, remove unnecessary plug-ins and devfiles when building custom registries. .Plug-in sidecar images diff --git a/modules/installation-guide/partials/proc_upgrading-the-chectl-management-tool.adoc b/modules/administration-guide/examples/proc_che-upgrading-the-chectl-management-tool.adoc similarity index 61% rename from modules/installation-guide/partials/proc_upgrading-the-chectl-management-tool.adoc rename to modules/administration-guide/examples/proc_che-upgrading-the-chectl-management-tool.adoc index ab45177871..dcfb233f9c 100644 --- a/modules/installation-guide/partials/proc_upgrading-the-chectl-management-tool.adoc +++ b/modules/administration-guide/examples/proc_che-upgrading-the-chectl-management-tool.adoc @@ -9,9 +9,7 @@ This section describes how to upgrade the `{prod-cli}` management tool. .Prerequisites -* The `{prod-cli}` tool is available. See: -** xref:using-the-chectl-management-tool.adoc#installing-the-{prod-cli}-management-tool-on-windows_{context}[Installing the {prod-cli} management tool on Windows] -** xref:using-the-chectl-management-tool.adoc#installing-the-{prod-cli}-management-tool-on-linux-or-macos_{context}[Installing the {prod-cli} management tool on Linux or macOS] +* The `{prod-cli}` tool is available. See: xref:using-the-chectl-management-tool.adoc[] .Procedure @@ -29,7 +27,7 @@ The command updates `{prod-cli}` based on its current channel. Two update channels are available for `{prod-cli}`: `stable` and `next`. * `stable` is for the latest released version of {prod}. -* `next` is updated after each activity in master branch of the link:https://github.com/che-incubator/{prod-cli}[{prod-cli} repository]. +* `next` is updated after each activity in the `main` branch of the link:https://github.com/che-incubator/{prod-cli}[{prod-cli} repository]. To move to a different channel, invoke the update with the name of the channel as an optional argument. diff --git a/modules/administration-guide/partials/proc_viewing-che-metrics-on-grafana-dashboards.adoc b/modules/administration-guide/examples/proc_che-viewing-che-metrics-on-grafana-dashboards.adoc similarity index 100% rename from modules/administration-guide/partials/proc_viewing-che-metrics-on-grafana-dashboards.adoc rename to modules/administration-guide/examples/proc_che-viewing-che-metrics-on-grafana-dashboards.adoc diff --git a/modules/administration-guide/examples/proc_che-viewing-dev-workspace-operator-metrics-on-grafana-dashboards.adoc b/modules/administration-guide/examples/proc_che-viewing-dev-workspace-operator-metrics-on-grafana-dashboards.adoc new file mode 100644 index 0000000000..9f0477a10a --- /dev/null +++ b/modules/administration-guide/examples/proc_che-viewing-dev-workspace-operator-metrics-on-grafana-dashboards.adoc @@ -0,0 +1,30 @@ +[id="proc_viewing-dev-workspace-operator-metrics-on-grafana-dashboards_{context}"] += Viewing {devworkspace} operator metrics on Grafana dashboards + +This section describes how to view {devworkspace} operator metrics on Grafana with the example dashboard. +Grafana version 7 or later is required to support all panels in the example dashboard. + +.Prerequisites + +* Prometheus is collecting metrics. See xref:proc_collecting-dev-workspace-operator-metrics-with-prometheus_{context}[]. + +* Grafana is running on port `3000` with a corresponding *service* and *route*. See link:https://grafana.com/docs/installation/[Installing Grafana]. + + +.Procedure + +. Add the data source for the Prometheus instance. +See link:https://prometheus.io/docs/visualization/grafana/#creating-a-prometheus-data-source[Creating a Prometheus data source]. + +. Import the example link:https://github.com/devfile/devworkspace-operator/blob/main/docs/grafana/grafana-dashboard.json[grafana-dashboard.json] dashboard. + + +.Verification steps + +* Use the Grafana console to view the {devworkspace} operator metrics dashboard. See xref:ref_grafana-dashboards-for-the-dev-workspace-operator_{context}[]. + +.Additional resources + +* link:https://grafana.com/docs/installation/[Installing Grafana]. +* link:https://grafana.com/docs/grafana/latest/datasources/prometheus/#prometheus-data-source[Prometheus data source]. +* link:https://grafana.com/docs/grafana/latest/dashboards/export-import/#import-dashboard[Import dashboard]. diff --git a/modules/administration-guide/partials/ref_grafana-dashboards-for-che.adoc b/modules/administration-guide/examples/ref_che-grafana-dashboards-for-che.adoc similarity index 70% rename from modules/administration-guide/partials/ref_grafana-dashboards-for-che.adoc rename to modules/administration-guide/examples/ref_che-grafana-dashboards-for-che.adoc index a896df75dc..67221b0587 100644 --- a/modules/administration-guide/partials/ref_grafana-dashboards-for-che.adoc +++ b/modules/administration-guide/examples/ref_che-grafana-dashboards-for-che.adoc @@ -11,7 +11,7 @@ image::monitoring/monitoring-che-che-server-dashboard-general-panel.png[] The *General* panel contains basic information, such as the total number of users and workspaces in the {prod-short} database. .The *Workspaces* panel -image::monitoring/monitoring-che-che-server-dashboard-workspace-panel.png[The *Workspaces* panel,link="../_images/monitoring/monitoring-che-che-server-dashboard-workspace-panel.png"] +image::monitoring/monitoring-che-che-server-dashboard-workspace-panel.png[The *Workspaces* panel,link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-workspace-panel.png"] * *Workspace start rate* -- the ratio between successful and failed started workspaces * *Workspace stop rate* -- the ratio between successful and failed stopped workspaces @@ -26,13 +26,13 @@ image::monitoring/monitoring-che-che-server-dashboard-workspace-panel.png[The *W * *Workspace start attempts* -- the number of attempts to start a workspace comparing regular attempts with start-debug mode .The *Users* panel -image::monitoring/monitoring-che-che-server-dashboard-users-panel.png[The *Users* panel,link="../_images/monitoring/monitoring-che-che-server-dashboard-users-panel.png"] +image::monitoring/monitoring-che-che-server-dashboard-users-panel.png[The *Users* panel,link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-users-panel.png"] * *Number of Users* -- the number of users known to {prod-short} over time .The *Tomcat* panel -image::monitoring/monitoring-che-che-server-dashboard-tomcat-panel.png[The *Tomcat* panel,link="../_images/monitoring/monitoring-che-che-server-dashboard-tomcat-panel.png"] +image::monitoring/monitoring-che-che-server-dashboard-tomcat-panel.png[The *Tomcat* panel,link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-tomcat-panel.png"] * *Max number of active sessions* -- the max number of active sessions that have been active at the same time * *Number of current active sessions* -- the number of currently active sessions @@ -42,12 +42,12 @@ image::monitoring/monitoring-che-che-server-dashboard-tomcat-panel.png[The *Tomc * *Longest time of an expired session* -- the longest time (in seconds) that an expired session had been alive .The *Request* panel -image::monitoring/monitoring-che-che-server-dashboard-requests-panel.png[The *Request* panel,link="../_images/monitoring/monitoring-che-che-server-dashboard-requests-panel.png"] +image::monitoring/monitoring-che-che-server-dashboard-requests-panel.png[The *Request* panel,link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-requests-panel.png"] The *Requests* panel displays HTTP requests in a graph that shows the average number of requests per minute. .The *Executors* panel, part 1 -image::monitoring/monitoring-che-che-server-dashboard-executors-panel-1.png[The *Executors* panel part 1,link="../_images/monitoring/monitoring-che-che-server-dashboard-executors-panel-1.png"] +image::monitoring/monitoring-che-che-server-dashboard-executors-panel-1.png[The *Executors* panel part 1,link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-executors-panel-1.png"] * *Threads running* - the number of threads that are not terminated aka alive. May include threads that are in a waiting or blocked state. * *Threads terminated* - the number of threads that was finished its execution. @@ -55,7 +55,7 @@ image::monitoring/monitoring-che-che-server-dashboard-executors-panel-1.png[The * *Created thread per minute* - Speed of thread creating for the given executor service. .The *Executors* panel, part 2 -image::monitoring/monitoring-che-che-server-dashboard-executors-panel-2.png[The *Executors* panel part 2, link="../_images/monitoring/monitoring-che-che-server-dashboard-executors-panel-2.png"] +image::monitoring/monitoring-che-che-server-dashboard-executors-panel-2.png[The *Executors* panel part 2, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-executors-panel-2.png"] * *Executor threads active* - number of threads that actively execute tasks. * *Executor pool size* - number of threads that actively execute tasks. @@ -63,7 +63,7 @@ image::monitoring/monitoring-che-che-server-dashboard-executors-panel-2.png[The * *Queued occupancy* - the percent of the queue used by the tasks that are waiting for execution. .The *Executors* panel, part 3 -image::monitoring/monitoring-che-che-server-dashboard-executors-panel-3.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-executors-panel-3.png"] +image::monitoring/monitoring-che-che-server-dashboard-executors-panel-3.png[The *Executors* panel part 3, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-executors-panel-3.png"] * *Rejected task* - the number of tasks that were rejected from execution. * *Rejected task per minute* - the speed of task rejections @@ -71,7 +71,7 @@ image::monitoring/monitoring-che-che-server-dashboard-executors-panel-3.png[link * *Completed tasks per minute* - the speed of task execution .The *Executors* panel, part 4 -image::monitoring/monitoring-che-che-server-dashboard-executors-panel-4.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-executors-panel-4.png"] +image::monitoring/monitoring-che-che-server-dashboard-executors-panel-4.png[The *Executors* panel part 4, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-executors-panel-4.png"] * *Task execution seconds max* - 5min moving maximum of task execution * *Tasks execution seconds avg* - 1h moving average of task execution @@ -79,7 +79,7 @@ image::monitoring/monitoring-che-che-server-dashboard-executors-panel-4.png[link * *Executor idle seconds avg* - 1h moving average of executor idle state. .The *Traces* panel, part 1 -image::monitoring/monitoring-che-che-server-dashboard-trace-panel-1.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-trace-panel-1.png"] +image::monitoring/monitoring-che-che-server-dashboard-trace-panel-1.png[The *Trace* panel part 1, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-trace-panel-1.png"] * *Workspace start Max* - maximum workspace start time * *Workspace start Avg* - 1h moving average of the workspace start time components @@ -87,23 +87,35 @@ image::monitoring/monitoring-che-che-server-dashboard-trace-panel-1.png[link=".. * *Workspace stop Avg* - 1h moving average of the workspace stop time components .The *Traces* panel, part 2 -image::monitoring/monitoring-che-che-server-dashboard-trace-panel-2.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-trace-panel-2.png"] +image::monitoring/monitoring-che-che-server-dashboard-trace-panel-2.png[The *Trace* panel part 2, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-trace-panel-2.png"] + * *OpenShiftInternalRuntime#start Max* - maximum time of OpenShiftInternalRuntime#start operation * *OpenShiftInternalRuntime#start Avg* - 1h moving average time of OpenShiftInternalRuntime#start operation + +pass:[<!-- vale RedHat.TermsErrors = NO -->] + * *Plugin Brokering Execution Max* - maximum time of PluginBrokerManager#getTooling operation * *Plugin Brokering Execution Avg* - 1h moving average of PluginBrokerManager#getTooling operation +pass:[<!-- vale RedHat.TermsErrors = YES -->] + .The *Traces* panel, part 3 -image::monitoring/monitoring-che-che-server-dashboard-trace-panel-3.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-trace-panel-3.png"] +image::monitoring/monitoring-che-che-server-dashboard-trace-panel-3.png[The *Trace* panel part 3, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-trace-panel-3.png"] * *OpenShiftEnvironmentProvisioner#provision Max* - maximum time of OpenShiftEnvironmentProvisioner#provision operation * *OpenShiftEnvironmentProvisioner#provision Avg* -1h moving average of OpenShiftEnvironmentProvisioner#provision operation + + +pass:[<!-- vale RedHat.TermsErrors = NO -->] + * *Plugin Brokering Execution Max* - maximum time of PluginBrokerManager#getTooling components execution time * *Plugin Brokering Execution Avg* - 1h moving average of time of PluginBrokerManager#getTooling components execution time +pass:[<!-- vale RedHat.TermsErrors = YES -->] + .The *Traces* panel, part 4 -image::monitoring/monitoring-che-che-server-dashboard-trace-panel-4.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-trace-panel-4.png"] +image::monitoring/monitoring-che-che-server-dashboard-trace-panel-4.png[The *Trace* panel part 4, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-trace-panel-4.png"] * *WaitMachinesStart Max* - maximum time of WaitMachinesStart operations * *WaitMachinesStart Avg* - 1h moving average time of WaitMachinesStart operations @@ -111,12 +123,12 @@ image::monitoring/monitoring-che-che-server-dashboard-trace-panel-4.png[link=".. * *OpenShiftInternalRuntime#startMachines Avg* - 1h moving average of the time of OpenShiftInternalRuntime#startMachines operations .The *Workspace detailed* panel, part 1 -image::monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel.png"] +image::monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel.png[The *Workspace detailed* panel part 1, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel.png"] The *Workspace Detailed* panel contains heat maps, which illustrate the average time of workspace starts or fails. The row shows some period of time. .The *Workspace detailed* panel, part 2 -image::monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel-2.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel-2.png"] +image::monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel-2.png[The *Workspace detailed* panel part 2, link="{imagesdir}/monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel-2.png"] * *Messages sent to runtime log* - Number of messages sent to the workspace startup log. * *Bytes sent to runtime log* - Number of bytes of the messages sent to the workspace startup log. @@ -128,28 +140,28 @@ image::monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel-2 Use case: JVM metrics of the {prod-short} server, such as JVM memory or class loading. .{prod-short} server JVM dashboard -image::monitoring/monitoring-che-che-server-jvm-dashboard.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard.png[The *{prod-short} server JVM* dashboard, link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard.png"] .Quick Facts -image::monitoring/monitoring-che-che-server-jvm-dashboard-quick-facts.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-quick-facts.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard-quick-facts.png[The *JVM quick facts* panel, link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard-quick-facts.png"] .JVM Memory -image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory.png[The *JVM Memory* panel , link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory.png"] .JVM Misc -image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-misc.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-jvm-misc.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-misc.png[The *JVM Misc* panel, link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard-jvm-misc.png"] .JVM Memory Pools (heap) -image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-heap.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-heap.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-heap.png[The *JVM Memory Pools (heap)* panel, link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-heap.png"] .JVM Memory Pools (Non-Heap) -image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-non-heap.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-non-heap.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-non-heap.png[The *JVM Memory Pools (non-heap)* panel, link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-non-heap.png"] .Garbage Collection -image::monitoring/monitoring-che-che-server-jvm-dashboard-garbage-collection.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-garbage-collection.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard-garbage-collection.png[The *JVM garbage collection* panel, link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard-garbage-collection.png"] .Class loading -image::monitoring/monitoring-che-che-server-jvm-dashboard-classloading.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-classloading.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard-classloading.png[The *JVM class loading* panel, link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard-classloading.png"] .Buffer Pools -image::monitoring/monitoring-che-che-server-jvm-dashboard-buffer-pools.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-buffer-pools.png"] +image::monitoring/monitoring-che-che-server-jvm-dashboard-buffer-pools.png[The *JVM buffer pools* panel, link="{imagesdir}/monitoring/monitoring-che-che-server-jvm-dashboard-buffer-pools.png"] diff --git a/modules/administration-guide/examples/ref_che-grafana-dashboards-for-the-dev-workspace-operator.adoc b/modules/administration-guide/examples/ref_che-grafana-dashboards-for-the-dev-workspace-operator.adoc new file mode 100644 index 0000000000..11225808bc --- /dev/null +++ b/modules/administration-guide/examples/ref_che-grafana-dashboards-for-the-dev-workspace-operator.adoc @@ -0,0 +1,34 @@ +[id="ref_grafana-dashboards-for-the-dev-workspace-operator_{context}"] += Grafana dashboards for the {devworkspace} operator + +This section describes the example Grafana dashboard, see link:https://github.com/devfile/devworkspace-operator/blob/main/docs/grafana/grafana-dashboard.json[grafana-dashboard.json], which displays metrics collected from the {devworkspace} operator. + +.The *{devworkspace}-specific metrics* panel +image::monitoring/monitoring-dev-workspace-metrics-panel.png[Grafana dashboard panels that contain metrics related to `DevWorkspace startup] +The *{devworkspace}-specific metrics* panel contains information related to `DevWorkspace` startup. + +Average workspace start time:: The average start time of a workspace. +Workspace starts:: The number successful and failed workspace starts. +Workspace startup duration:: A heatmap that displays workspace startup duration. +{devworkspace} successes / failures:: A comparison between successful and failed {devworkspace} startups +{devworkspace} failure rate:: The ratio between the number of failed workspace startups and the number of total workspace startups. +{devworkspace} startup failure reasons:: A pie chart that displays the distribution of workspace startup failures. The possible failure reasons are: +* `BadRequest` +* `InfrastructureFailure` +* `Unknown` + +.The *Operator metrics* panel, part 1 +image::monitoring/monitoring-dev-workspace-operator-metrics-panel-1.png[Grafana dashboard panels that contain Operator metrics part 1] + +Webhooks in flight:: A comparison between the number of different webhook requests. +Work queue duration:: A heatmap that displays how long the reconcile requests stay in the work queue before they are handled. +Webhooks latency (/mutate):: A heatmap that displays `/mutate` webhook latency. +Reconcile time:: A heatmap that displays the reconcile duration. + +.The *Operator metrics* panel, part 2 +image::monitoring/monitoring-dev-workspace-operator-metrics-panel-2.png[Grafana dashboard panels that contain Operator metrics part 2] + +Webhooks latency (/convert):: A heatmap that displays `/convert` webhook latency. +Work queue depth:: The number of reconcile requests that are in the work queue. +Memory:: Memory usage for the {devworkspace} controller and the {devworkspace} webhook server. +Reconcile counts (DWO):: The average per-second number of reconcile counts for the {devworkspace} controller. \ No newline at end of file diff --git a/modules/administration-guide/examples/ref_che-supported-platforms-and-installation-methods.adoc b/modules/administration-guide/examples/ref_che-supported-platforms-and-installation-methods.adoc new file mode 100644 index 0000000000..b752373650 --- /dev/null +++ b/modules/administration-guide/examples/ref_che-supported-platforms-and-installation-methods.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// supported_platforms + +The following section provides information about the availability of {prod-short} {prod-ver} on {platforms-name} infrastructures. + +{prod} can be installed on: + +* {kubernetes} infrastructures starting at version {kube-ver-min} +* {ocp} starting at version 4.8 + +{prod} can be installed on all major Public Clouds such as: + +* Amazon Web Services +* Google Cloud +* IBM Cloud +* Microsoft Azure +* Rancher + +WARNING: Setting up link:https://kubernetes.io/docs/reference/access-authn-authz/authentication/[Users' Authentication] is required for deploying {prod-short} on {kubernetes} infrastructures. For {ocp} no additional setup is needed. + +The following options are available for the local installation: + +* link:https://minikube.sigs.k8s.io/docs/[minikube] +* link:https://developers.redhat.com/products/codeready-containers/overview[CodeReady Containers] + +.Additional resources + +* xref:installing-che.adoc[] diff --git a/modules/administration-guide/examples/snip_a-che-workspace-example.adoc b/modules/administration-guide/examples/snip_a-che-workspace-example.adoc index 75f92a7638..ee9ab9711f 100644 --- a/modules/administration-guide/examples/snip_a-che-workspace-example.adoc +++ b/modules/administration-guide/examples/snip_a-che-workspace-example.adoc @@ -1,24 +1,23 @@ [source,yaml] ---- -apiVersion: 1.0.0 +schemaVersion: 2.1.0 metadata: - generateName: nodejs-web-app- -projects: - - - name: react-web-app - source: - type: git - location: "https://github.com/che-samples/react-web-app" + name: bash components: - - - type: chePlugin - id: vscode/typescript-language-features/latest - - - type: dockerimage - alias: nodejs - image: quay.io/eclipse/che-nodejs12-community:ce0526f - endpoints: - - name: 'nodejs' - port: 3000 - mountSources: true + - name: tools + container: + image: quay.io/devfile/universal-developer-image:ubi8-0e189d9 + memoryLimit: 4Gi + +commands: + - id: run-main-script + exec: + label: "Run main.sh script" + component: tools + workingDir: '${PROJECT_SOURCE}' + commandLine: | + ./main.sh + group: + kind: run + isDefault: true ---- diff --git a/modules/installation-guide/examples/snip_che-build-an-offline-devfile-registry.adoc b/modules/administration-guide/examples/snip_che-build-an-offline-devfile-registry.adoc similarity index 100% rename from modules/installation-guide/examples/snip_che-build-an-offline-devfile-registry.adoc rename to modules/administration-guide/examples/snip_che-build-an-offline-devfile-registry.adoc diff --git a/modules/installation-guide/examples/snip_che-build-an-offline-plug-in-registry.adoc b/modules/administration-guide/examples/snip_che-build-an-offline-plug-in-registry.adoc similarity index 100% rename from modules/installation-guide/examples/snip_che-build-an-offline-plug-in-registry.adoc rename to modules/administration-guide/examples/snip_che-build-an-offline-plug-in-registry.adoc diff --git a/modules/installation-guide/examples/snip_che-clone-the-devfile-registry-repository.adoc b/modules/administration-guide/examples/snip_che-clone-the-devfile-registry-repository copy.adoc similarity index 100% rename from modules/installation-guide/examples/snip_che-clone-the-devfile-registry-repository.adoc rename to modules/administration-guide/examples/snip_che-clone-the-devfile-registry-repository copy.adoc diff --git a/modules/installation-guide/examples/snip_che-clone-the-plug-in-registry-repository.adoc b/modules/administration-guide/examples/snip_che-clone-the-plug-in-registry-repository copy.adoc similarity index 100% rename from modules/installation-guide/examples/snip_che-clone-the-plug-in-registry-repository.adoc rename to modules/administration-guide/examples/snip_che-clone-the-plug-in-registry-repository copy.adoc diff --git a/modules/administration-guide/examples/snip_che-getting-the-list-of-relevant-images.adoc b/modules/administration-guide/examples/snip_che-getting-the-list-of-relevant-images.adoc deleted file mode 100644 index 73e7c8789a..0000000000 --- a/modules/administration-guide/examples/snip_che-getting-the-list-of-relevant-images.adoc +++ /dev/null @@ -1,19 +0,0 @@ -.Getting the list of all relevant images for {kubernetes} -==== -[subs="+attributes,+quotes,+macros"] ----- -$ curl -sSLo- https://raw.githubusercontent.com/eclipse-che/che-operator/{prod-ver}.x/deploy/olm-catalog/stable/eclipse-che-preview-kubernetes/manifests/che-operator.clusterserviceversion.yaml | \ -yq -r '.spec.install.spec.deployments[].spec.template.spec.containers[].env[] | select(.name | test("RELATED_IMAGE_.*"; "g")) | .value' | \ -sort -u ----- -==== -+ -.Getting the list of all relevant images for OpenShift -==== -[subs="+attributes,+quotes,+macros"] ----- -$ curl -sSLo- https://raw.githubusercontent.com/eclipse-che/che-operator/{prod-ver}.x/deploy/olm-catalog/stable/eclipse-che-preview-openshift/manifests/che-operator.clusterserviceversion.yaml | \ -yq -r '.spec.install.spec.deployments[].spec.template.spec.containers[].env[] | select(.name | test("RELATED_IMAGE_.*"; "g")) | .value' | \ -sort -u ----- -==== diff --git a/modules/administration-guide/examples/snip_che-installing-che.adoc b/modules/administration-guide/examples/snip_che-installing-che.adoc new file mode 100644 index 0000000000..4e124963fb --- /dev/null +++ b/modules/administration-guide/examples/snip_che-installing-che.adoc @@ -0,0 +1,24 @@ +The installation method depends on the target platform and the environment restrictions. + +.Using {prod-short} as a service + +* link:https://www.eclipse.org/che/docs/che-7/hosted-che/hosted-che/[{prod-short} hosted by RedHat] + +.Installing {prod-short} in cloud + +You can deploy only one instance of {prod-short} per cluster. + +* xref:installing-che-on-openshift-4-using-operatorhub.adoc[] +* xref:installing-che-on-openshift-4-using-cli.adoc[] + +.Installing {prod-short} on a local single-node cluster + +Single-node clusters are suited only for testing or development. Do *not* use such clusters to run {prod-short} for organizations or developer teams. + +* xref:installing-che-on-codeready-containers.adoc[] +* xref:installing-che-on-minikube.adoc[] + +.Installing {prod-short} in a restricted environment + +* xref:installing-che-in-a-restricted-environment.adoc[] + diff --git a/modules/administration-guide/examples/snip_che-list-of-images-for-faster-workspace-start.adoc b/modules/administration-guide/examples/snip_che-list-of-images-for-faster-workspace-start.adoc deleted file mode 100644 index dbf90dd1ba..0000000000 --- a/modules/administration-guide/examples/snip_che-list-of-images-for-faster-workspace-start.adoc +++ /dev/null @@ -1,5 +0,0 @@ -* `che-theia` -* `che-theia-endpoint-runtime-binary` -* `che-machine-exec` -* `che-plugin-artifacts-broker` -* `che-plugin-metadata-broker` diff --git a/modules/installation-guide/examples/snip_importing-untrusted-tls-certificates_1.adoc b/modules/administration-guide/examples/snip_importing-untrusted-tls-certificates_1.adoc similarity index 100% rename from modules/installation-guide/examples/snip_importing-untrusted-tls-certificates_1.adoc rename to modules/administration-guide/examples/snip_importing-untrusted-tls-certificates_1.adoc diff --git a/modules/installation-guide/examples/snip_installing-che-on-openshift-4-using-the-cli.adoc b/modules/administration-guide/examples/snip_installing-che-on-openshift-4-using-the-cli.adoc similarity index 100% rename from modules/installation-guide/examples/snip_installing-che-on-openshift-4-using-the-cli.adoc rename to modules/administration-guide/examples/snip_installing-che-on-openshift-4-using-the-cli.adoc diff --git a/modules/administration-guide/examples/snip_using-devworkspace-warning.adoc b/modules/administration-guide/examples/snip_using-devworkspace-warning.adoc deleted file mode 100644 index 65ab7e647f..0000000000 --- a/modules/administration-guide/examples/snip_using-devworkspace-warning.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[WARNING] -.Technology preview feature -==== -Managing workspaces with the {devworkspace} engine is an experimental feature. Don't use this workspace engine in production. - -.Known limitations - -Workspaces are not secured. Whoever knows the URL of a workspace can have access to it and leak the user credentials. -==== - diff --git a/modules/installation-guide/examples/system-variables.adoc b/modules/administration-guide/examples/system-variables.adoc similarity index 97% rename from modules/installation-guide/examples/system-variables.adoc rename to modules/administration-guide/examples/system-variables.adoc index b2bdca34f8..504cf21290 100644 --- a/modules/installation-guide/examples/system-variables.adoc +++ b/modules/administration-guide/examples/system-variables.adoc @@ -387,18 +387,18 @@ Default::: empty ''' -== `+CHE_OAUTH_GITHUB_CLIENTID+` +== `+CHE_OAUTH2_GITHUB_CLIENTID__FILEPATH+` -Configuration of GitHub OAuth client. You can setup GitHub OAuth to automate authentication to remote repositories. You need to first register this application with GitHub OAuth. GitHub OAuth client ID. +Configuration of GitHub OAuth2 client. Used to obtain Personal access tokens. Location of the file with GitHub client id. Default::: `+NULL+` ''' -== `+CHE_OAUTH_GITHUB_CLIENTSECRET+` +== `+CHE_OAUTH2_GITHUB_CLIENTSECRET__FILEPATH+` -GitHub OAuth client secret. +Location of the file with GitHub client secret. Default::: `+NULL+` @@ -899,42 +899,6 @@ Default::: `+0+` ''' -== `+CHE_INFRA_KUBERNETES_CLIENT_HTTP_ASYNC__REQUESTS_MAX+` - -Number of maximum concurrent asynchronous web requests (HTTP requests or ongoing WebSocket calls) supported in the underlying shared HTTP client of the `KubernetesClient` instances. Default values: `max=64`, and `max_per_host:5`. Default values are not suitable for multi-user scenarios, as {prod-short} keeps open connections, for example for command or ws-agent logs. - -Default::: `+1000+` - -''' - - -== `+CHE_INFRA_KUBERNETES_CLIENT_HTTP_ASYNC__REQUESTS_MAX__PER__HOST+` - -Number of maximum concurrent asynchronous web requests per host. - -Default::: `+1000+` - -''' - - -== `+CHE_INFRA_KUBERNETES_CLIENT_HTTP_CONNECTION__POOL_MAX__IDLE+` - -Max number of idle connections in the connection pool of the Kubernetes-client shared HTTP client. - -Default::: `+5+` - -''' - - -== `+CHE_INFRA_KUBERNETES_CLIENT_HTTP_CONNECTION__POOL_KEEP__ALIVE__MIN+` - -Keep-alive timeout of the connection pool of the Kubernetes-client shared HTTP client in minutes. - -Default::: `+5+` - -''' - - == `+CHE_INFRA_KUBERNETES_TLS__ENABLED+` Creates Ingresses with Transport Layer Security (TLS) enabled. In OpenShift infrastructure, Routes will be TLS-enabled. @@ -1332,7 +1296,7 @@ Default::: `+devfile.yaml,.devfile.yaml+` Editor that will be used for factories that are created from a remote Git repository which does not contain any {prod-short}-specific workspace descriptor. -Default::: `+eclipse/che-theia/latest+` +Default::: `+eclipse/che-theia/next+` ''' @@ -1359,7 +1323,7 @@ Default::: `+.che/che-editor.yaml,.che/che-theia-plugins.yaml,.vscode/extensions Default Editor that should be provisioned into Devfile if there is no specified Editor Format is `editorPublisher/editorName/editorVersion` value. `NULL` or absence of value means that default editor should not be provisioned. -Default::: `+eclipse/che-theia/latest+` +Default::: `+eclipse/che-theia/next+` ''' @@ -1458,6 +1422,24 @@ Default::: `+NULL+` Address of the GitLab server with configured OAuth 2 integration +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH2_GITLAB_CLIENTID__FILEPATH+` + +Configuration of GitLab OAuth2 client. Used to obtain Personal access tokens. Location of the file with GitLab client id. + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH2_GITLAB_CLIENTSECRET__FILEPATH+` + +Location of the file with GitLab client secret. + Default::: `+NULL#+` ''' diff --git a/modules/administration-guide/images/architecture/che-architecture-with-che-server-engine.png b/modules/administration-guide/images/architecture/che-architecture-with-che-server-engine.png deleted file mode 100644 index 6066c14103..0000000000 Binary files a/modules/administration-guide/images/architecture/che-architecture-with-che-server-engine.png and /dev/null differ diff --git a/modules/administration-guide/images/architecture/che-architecture-with-devworkspace.drawio b/modules/administration-guide/images/architecture/che-architecture-with-devworkspace.drawio deleted file mode 100644 index 380d4d50ba..0000000000 --- a/modules/administration-guide/images/architecture/che-architecture-with-devworkspace.drawio +++ /dev/null @@ -1 +0,0 @@ -<mxfile modified="2021-08-26T08:49:26.563Z" host="app.diagrams.net" agent="5.0 (Macintosh)" etag="2gGJI3zB6UIUOT4b8DAK" version="14.9.5" type="google" pages="3"><diagram id="pjOetxjZ0gYZK28orpWn" name="Page-1">7V1bd6M4Ev41OWf3wRxxx4+xk8z2ds9OzvTOdM+8zMEg22ww8oKcy/z6kUDiJiWQDNjEkbv7tCmEMF99VSqpytaFudw9/pD6++2PKITxhQHCxwvz6sIwdGPukf+o5KmQuI5TCDZpFLJGleBr9CdkQsCkhyiEWaMhRijG0b4pDFCSwAA3ZH6aoodmszWKm3fd+xsoCL4GfixKv0Uh3hZSz3Ar+b9gtNnyO+vOvDiz83lj9iTZ1g/RQ01kXl+YyxQhXLzbPS5hTMHjuBTX3TxztvxgKUxwnwt+f3j49A1/T51//wGC+0/fZ+Z/r2esl3s/PrAHZh8WP3EEYBJeUiDJ0SpGwd2FudjiXUwOdfKW3Dx9+k4OgGbzw9/oIT+4emwcPZVH4U0Ul708RrjWCTn6rXam6oIe8B7E52cPk6FDGsAXHpo9I/bTDcQvgcM6hGGDIwzeHyDaQfJIpMFDxQybaXtbIwWXpTD2cXTfZJbPCLopuyvvcIsi8mgGYMZk6eyDP3GucSPhfRRPzi6rU6GzJ7PVU4GN0BN5U3vwSpRT7RW0MwTafUPpXbb3A2LrhuPv9kTBySrb53p2YgLkYpWSdxv67itM72EqEDVFhySEISPOwzbC8CvtkQgeiHNq8nZNyLdEMUrza83Qhl5oEXmGU3QHa2c8Y2USn/UC38hnwfDxRYKws4YLGrjPuW+oEahsU2eQA54nS0M3r1WEJ7F3wvav7BCleIs2KPHj60q6qICmdli1+YLQnsH7P4jxE/Pm/gGjltN4g7m/1dGsUYJr6gT562+5D+4WOv2H4fX0H70dw9/StS5z9m1bA1MVfT6sYJpATB0EuLz9NKz5+9BbBzLzdwIPrtbkjB9Hm4TIYrjGQ3kDwQvbJ3YHuuiYBZxDP9uWxs/CLn+VnwUvgmzrnnVjCiAnKKFOhYRHe9rH7nFDI0ltE+wN7a5U+h8x8TGkGUEcs+5jfwXjW5RFOEJUM2kB0IJqICIR3JfW+V0Uhrn/aqmSt79k4rIdHY+iZPMlb3Zli85knr+YnHk7AuEw7PDa7LBsDQBrXr4Erli2SBXL1Bz7tZGG3bizqzmuDapXyz+h9TqDo0QJuimw8Qrel5GCGBigPUx9jN5jaGCZrqBuQcE6kDgDazRnYHU7gz0lTn5je0H+Ao26sCXI/9mkwTIX0kngkozbekOeH2mu3mrsECCWLWHRcm5LpE4pJH+fN/4VwhjtmopuGz6m4cvCz/bFRHIdPVLKlO4iINolYSfxQfShYXp9D4tn1yXuK4iyAOlz7ZDll0hdXotoNzeLweikW2aTTubcEej00lxleDZ53WziIEa7fFberatObedjxMIP7ja5C6ihvc5fpEl+s0uudCBjAPs8V1uM6bLDJUXCuAnCBGgRGQHXEXEuqRaQOxo3oY998h+Vk0jl5k+UhPw9jWtuAhRCMs562j7ZiBxYLrvC01dwwG1xwDJEDugSDrSnlYNxgKu8GYHmTpx49KS63Pn/gS6LLEIUZLPc2Mj0YkbXgmaOb64s6AQzl6hv5oC1PrNdAGdeGDqrtQ4NaMOqAz4y8Nvs6VJUlDZuEuO0fkGNkGWLKIEzjhDRPtA1+hhF8x2ZBkTJLCckPQf2uH2O07E8/dzHYyiIn4AGGLO1v4vip6KbMkImpDGtnEipT++IEiScy9sv2Vk2drJPGBTco12mm9U/dDpnYY1B9e6fZftVaUuz2qU49ZOMkZW35LY5Y/7zMr86gxRMEQF/H/0K0yxCHApCsAKNqSFkG6dBqGgwbXBITFQ2br0fH6DisSaNz7xsqpMr+XvvCOAYmq51wUPE+7asCq6VC524CyXxx54EljQmnbgZnMyHdrtQmQ0oxk/a68vTBYr7LaBmU0dGBQ8THVgSfwcnD85Jh5TJcwdIwDFse3x4NmhG6zW6QhI17L47fykMu13HkzaQE0btCfbJmVTFpspIlBG9DehigX7q6Ex31ntybFTsP9n4LfZpoupS13RrluEU4mB7fuOUuMwpe4gwup8cM07mc1+E7hlaSAAUGrdzwnnmnNde0+KaWla4nXVfx+gh2Pop1kIUHHbk4egFsnqPrKjWAZohqespiwTr2VmWtB++DsxpVYW6PAdfLwPjBbqNPO1oyXpDrLxpEV4laj+o2atErUrUnn+8pRK1yoWqRO2Up6zvcJJxcnVObTFMcV8las8weFCJ2imalUrUvgiPStSeq79UOaZBgFSJWmUkyohUonbsEGXa2KjYf7Lxm0rUljKVqO0LnUrUvj1RO/dOn6iVfUdfJWqV2atErUrUfoR4SyVqlQtVidopT1nf4STj5Oqc2mKY4r5K1J5h8KAStVM0K5WofREelag9V3+pckyDAKkStcpIlBGpRO3YIcq0sVGx/2TjN5WoLWUqUdsXOpWofXuiVtfnPTO14/2aOv9R/VqmNoT3BA6oPfkE/raWyKPipmqE3yF/duOCFBJl1PZkaP5KO/2ZdLonC1NYrnXpz5O/dueU/gry9KaCXFPUjydTz2jacQTtNLcaAMtDRh2fAX6GbIeYD6Uxt6WxuSOxKNn2BOOpzBVUdovCrPDWtzTznWHyvL+imLgtJqY7R0X5HlOAjLqapn0sJYp+0e3rF0fTYo9tAd68ewdDtNyxRh8GRqO9fZoJRBjNuQTGsuHwOM4HxnEAnExenVTh5Ak46bYn4mSbI8HEuV2DaYlC6t+vw2jonWPWNv0j2Dk54+Qv0diL10DoW22W6pYm2VPGkPB0tCjINLppykPQ4CnON9boxn1VKOnLqhSUEfpPB5wH21IFQT20oUs9N8I+2zoEPOeXB1CJxTdtqlQiiXscifsdrYCQW9r0NwAcfiM/7jO7N/JjDSeykZ8tFn1C5r1AtfjdHdl0bkrUmqB1R0AyO22S5dl5Id1BjX1YYwjv5+ktU3MM0fcdNWC1xRngBIZoW2vu9qZbkmBGOkjro21DaIuzsbMamEEbcUcyMBueJtvPbzTMxekUSzMrn1L6FLNtLLZkGnxcr+KIEe052YorQD4Ja3F6bJz+flG3gDtFzHvMHd4x5haYJtNlPwV5NqiLY7FsXfPIiPfYd/UdIy7x6BPAfOjYfFKYi/58AoifdYwv8+YTwFyM8c8Ic9NqTfltyerasREfM71xesRdS5gQTQDzoVMhk8Lc4jmUCSHunvUc1LL0CbLcFaNEnsIC+/iwieiW429brjnK2kxLw3w39iG8ktMeeXXZPIovEB9llcYV48svfrI5+Ju8GCE9JDjKqxQ+psasdnwqqUvQdcka9HgKE0Ol5ZdPRMAWRT+mnlyz5QcNUU+OLH85mprEsX5flv5cVFXIVUnlfV4P9FYFnslKtjVvGVzvdWxzLE16shiiT0UwE9PS2gSlOz8WC2t5wV6bC0Fe+tGvavZjEcTWhchePora8yNau9djLfJ41SPErRpBcHG06pFahDmd+hFPDGyyssjyQ5sQOf/mbOF4Xla26jaQl/0GV9IR99PV9cBO9vh0GDWsMoRKPUvkiczRmmXxxvBEkS0VDkSUn+EOYVpzeQVXh82G1hW8lR5DM+FkGpd8QUWqcW8sfcsWKgfS9y8ZVTEo/MPlfh8TBeXj5YdXu2X1janGU3yP1VKYhJdpih4qD1xfq3vGgTaq7glm6ROt+JwBDegul9CqT6CZc5MLqtLP/OipfnQL04g8M9X31YuFn931nCyO7KznrCtFMkxzWe+yT3aHW/rFkNpsrPXdGh20Vw2LCQy7rFK40JPjdPVUYCP0lFOnfPC3s2neYyV4YDaBeZNNBvCOzCZrWmxqJwiENejebLK7ehqOTTj7ZWEsPv/nM1h8z+i85nfvp1mPIqsamVYxCu6abCqJwgrNS5Z0MiS8ieLOOtvJaLz5tQKvPQHvq/B2R/N2RyPr2zi7oWgqDGmNMB73Wa8fYDwNePPq1erW1Ob2QJQhhymicWTVnH4j/UcUQtriLw==</diagram><diagram id="6Aux8Oo_KE3ukIRY6s5_" name="Page-2">7Vxbd5s4EP41eawPCMTl0ddszqZdt8k2aV96ZJAxDUZekB27v34lEBgQtZ0EGx83ND1Bgy7mm29Go5GcK60/X19HaDH7SFwcXAHFXV9pgysAVGBb7BeXbFKJaRipwIt8V1TaCu78X1gIFSFd+i6OSxUpIQH1F2WhQ8IQO7QkQ1FEnsvVpiQoj7pAHpYEdw4KZOmD79JZKrWAuZX/hX1vlo2sGnb6ZI6yyuJN4hlyyXNBpA2vtH5ECE3v5us+Djh4GS7KR+DcPfa0a3eyubmDcPmJoA9pZ6OXNMlfIcIhfXXXXz+P6fXq/tZd3nzu3ns/fz7Yq6zrmG4yvLDL4BNFEtEZ8UiIguFW2ovIMnQx71VhpW2dW0IWTKgy4U9M6UZwAS0pYaIZnQfiKV779FE05/ff+H0HitJgXXg02GSFkEabx6wDXii04sVts6SUtTsQugwHsowcAcSD/vipd/1BGf7r3o+JNdbt0bWAWKEo8jDdUU/0x8Es0FAo5hqTOWYfklWIcICovypzFQnKe3m9rVrZjdBsvZZ3feoVCpZipP4MM8EAxbMJQZErsWCrY47388yn+G6BEmiemZ8o63PqB0GfBCRK2mouxJarM3lMI/KEC08sMNGY+3ipVlY4oni9E0fxVIPiVYWzArYoP29NX83seVYwe0N5O/S1BmZcuoElpTGOfIYXjo5jddm8UbC6WrCVs7K6jL1Vq7vDEWP0pZicasH2TK4WdyDhPsArBhjH/gv2/DgbpCn0p5aDHacO/YkFdfhygzgcfaCVHZ5qtI2+JqE/DpaeH14g+Do8N/BtCXx5+gndLg+rWWkSEOfpNzNHx4TFyWPP1OGO/CDrImZummZDhCTEmUzUKU02SgfA4nyj7plt2grn7ANnloLmYY3iM9nBE5AYYUx89r7bMMcoE0/TKoRKX1y0Kq4Jqh0pezpKkZE6SsiZv/Ybpkg5Mn01YcFLCJvTz3wR/cpMb4uM5lmRUbcaIiPUWyaj/mYyluixpWaRmepOZh6HUmfKFGC+kim6WmGKqZ+WKYbElEsOMfVKlKO3HOVkDnAX/D6OL0cBVkUBVtsKsCQFXHCQX6U/bBt9Ocqvon9B7Ndhhf1m24ssIAetDyR6ihMwG0Ud8n91qBvJxVuQkBbk6XXMbI+ulrShG2bb2pDTbH+MNoB1dtqQk29/jDZ0cHbakJNxf4w2oHF22njZ+tIJUBz7TnWFmWcuSomLbaqi6byZOv86v9bJ0+Dx+2f3sfctJP8tsyTv3lQFOK8FaL43kXFCfeUCVK10BE+cqgCwASrl6Qlbtw5OULyWgLyT5nYJ30ZK7axICbWGSAnUqsc7MSnlrMjF+zdwVlTSzQqVwCupZGgtU0nO8Fw8lQ49MnSiLSbYFJWqK8Zq0rc5Ku3Cv8QkA815PBtO4kWicOVcRX8vJzgK2ZQZs0J3fCMZwZsOjSBsTWuTOoZj4cmUPUGB74VMFuApPeY6tuK3NFPOseV1mo7Va1lzQKjuoniWH9ISp1fRJHmq7MQdqpY+0iTcs63yGVrwPuZrjx/I7XjOAnSech78CIjHT3sxJVDRfYAmOBiT2Kc+4cqKUnx6HH/fQcFt5fncd93knFlFu1n9rhDn9fh60Q+926TaAMqLOTu5hFycSlPBURMfFcJYsKMoup1f8haFDmX66Fony+a+IF4rjWx2DBMq26viaMl0GuOj+DV5BTDAq8Lq3gi4TicRu/P4HVngCFGmsUZdSHvnznQNVikg6VxVanyG3oDP2HX6sKCRBYmpF9Xk4jMjdzaBz8CPtP3IT1I13U5yAXKevER5/ywp6wYLeSzsDx4RfNssYZ+bYwF7owZ661jQy1lHCfIFt+JkXNhjP0qH86evJP8hq9BPhPzbDn0WMKoleVLqmGqlMs8o9SvCtKYNa6RGLmQ/v3fPE0IpmZeVX3XNlB8E7qF4kX5jYuqvuQHnDt1h6uar7F7y0jgarnD67mrNBOP4sUNUu7OMkya1k1LF7Eej3pEPlVaMG6oywXYFv40TrC6KfCfY0QhmDrvG8Kh76pWdk9YJdkDA+U6w5gimKLatHHXbGpwZwQ7IGL8TrDmC9ft8NXDC/a1TEuzmNgbU3JgGUMwf37+Mh/fLm5rw97dhrz9PvrS5X317CZCsfXt5JFzckkwuViUZrJvxQKkjhfg8gxml/FupXQ4EGDluqHR8trKfJjF6x2EjgpGLKGK/uJzF9aNfJHSze57CGTnExR9UYHUWodcCLfLjSRktdJkWag0tqpsOjdFCPp7xTovT00JT7Aot1HZpccCK7Z0WR6eFrlvnRYsD1lnvtDh+bGGdzFuw4vYvKKS50e3fodCG/wM=</diagram><diagram id="CDJe3pgTB3aK1YOTjmKl" name="Page-3">7Zpbb6s4EIB/TR6LuF8eU5J0d0+r7aqr0/bpyIADVglGxrm0v35tMITbSZM2NNE2NFXwYAY88zEZjxlp7mJzQ0Aa3eEAxiNVDjYjbTJSVUV1bPbFJa+FxDLNQhASFIhOW8EDeoNCKAvpEgUwa3SkGMcUpU2hj5ME+rQhA4TgdbPbHMfNq6YghB3Bgw/irvQRBTQqpLZqbeV/QBRG5ZUV0ymOLEDZWYwki0CA1zWRNh1pLsGYFnuLjQtjbrzSLrIWPabhryd3Zf20H+/Vv/6era8KZbNDTqmGQGBCP6x6/GBMXXgTe3eZM35Sbu8mr/9cKXqhewXipTCYGCx9LS0Ik2DMHcFaXoz9l5F2HdFFzJoK22W3RF6fWEOWjLL5zJtlY7JptF6rVjBDcaVlg2hNCWs9145sVfBGqWFPqwjrZXhJfLjDFKoAnQISQqEwffKenrOHzb/yj4jevt141uruSvABgwZ4wug3EC8gGyfrsN7iZgiEohpppYzAGFC0auIKBPVhpa66wj1GbLyqLJ5QvXzQxPOplXpLFcXAxVl1Pt5TZLUUFYbpKGI7tWFvRTl+B6BY2r+GohtB7jlIVpDkIWKR4oR5O+swSvAyCWAgmFlHiMKHFOT+XrO41kR2zrhzcYxJfq4WGNAOdCbPKMEvsHbEVj2NhbtDUWN3S+FmJxviqKYbDZurjrB5jR1F7YHHlH/PScMxO7zQC7fSccIjJi9ZbstjGn1u8L8+o5v5xs/ACa3Ji21AZyi60nCGblondob6fZ2h2ufmDO37OkNXz80Z3bTl2zjDMM/NGUbHGR0f1HJIPwZZhvzjZJGHGbmeA+5K7d5NAYW+M0kBq6yhJEL5YAqotBQZ2mApYK9ZzSOAVE0kHN3eeyrx4UkMU3IPCWIDh+S0SOpnhWRFzmeRZBPyVrT7WiStbxfbtLMCSbdaIKkfBMnUTgtSd3b7fwdJPSuQqrrIp0FqTxOHq5PsMn8DJBMseB6beFma+1s+V9GPpQdJwn4tM9YY3//ZeQY+VcgB0J77vcm6b0Nvzo6AGIUJk8VwToecvbailmaJHLnGetXna+o68vvxJwBZlJueBw1RjwdeflTeaXhDsfWZ1jF8ghPIhRFIuY7FJuRLDFLop6r0UoHwK8YhZt2YF6hQHwMPxvc4QxRh7i1SGOiaOwD5IL5tHV+gIOC32XZv2X8sxFU/PlFESXibd5sY3Vmck29CLhY1FHXQekeLGNuQZFl3qk3vAFTWDuv86JpkGgcna40rW5JpGfJ2a0VaPJ9ncJDAVmZ6NUQncFWb15sxd6pH2F7I93AKCaDMZUcNIqerBuua0Wag43RF7oka+mBRo1uB7Bg75TDlFzau2UeW+ChcOf83WAc3F/JlRJflLUpDnrckS2l15hUNtyUsejpGj9SshOzz+yjhYUrxoun8doSgmNMBsrRYipyjDceoiis+8zif6F3ng4ZkuoLF2JWeOOejzMeKIy2z/JTe2NiCbza7HhYxpYWYUf4u7JmEHZ+wbln1QtiAhFnTsTk9fFLw8cL96QnbY4n7QtjxCJNlx5GHJKy9GnF6wvYogF8IOx5hrsvz0i9cYjk9YXtUxkvDokX+RtT7/nuXgHwadg38lzBPqOvLYvnGuuQXG5cgyH1UiPuZRJTyV77G3BLqzA8SWUJskjlHLFUnks+uqM4CQAH74vKMfb/hJCj3eTlh5uMAsqTUltIkPAEXitnKnvQuF0oPF+3i9/G42KM8feFicC402WlxoZyYiz2qzRcuBudC1+0z46KveHzh4svzC/vL4gVrbt9QLip12/e8tel/</diagram></mxfile> diff --git a/modules/administration-guide/images/architecture/che-dashboard-interactions.png b/modules/administration-guide/images/architecture/che-dashboard-interactions.png index 76332e435e..a2e6ee3ae9 100644 Binary files a/modules/administration-guide/images/architecture/che-dashboard-interactions.png and b/modules/administration-guide/images/architecture/che-dashboard-interactions.png differ diff --git a/modules/administration-guide/images/architecture/che-deployments-interacting-with-devworkspace.png b/modules/administration-guide/images/architecture/che-deployments-interacting-with-devworkspace.png index 107bce3ec0..c289636968 100644 Binary files a/modules/administration-guide/images/architecture/che-deployments-interacting-with-devworkspace.png and b/modules/administration-guide/images/architecture/che-deployments-interacting-with-devworkspace.png differ diff --git a/modules/administration-guide/images/architecture/che-devfile-registry-interactions.png b/modules/administration-guide/images/architecture/che-devfile-registry-interactions.png index e11a7bb91c..67fd546126 100644 Binary files a/modules/administration-guide/images/architecture/che-devfile-registry-interactions.png and b/modules/administration-guide/images/architecture/che-devfile-registry-interactions.png differ diff --git a/modules/administration-guide/images/architecture/che-gateway-interactions.png b/modules/administration-guide/images/architecture/che-gateway-interactions.png index 953d76179f..2c8174a615 100644 Binary files a/modules/administration-guide/images/architecture/che-gateway-interactions.png and b/modules/administration-guide/images/architecture/che-gateway-interactions.png differ diff --git a/modules/administration-guide/images/architecture/che-interacting-with-devworkspace.png b/modules/administration-guide/images/architecture/che-interacting-with-devworkspace.png index 9ec7675930..29abc42de9 100644 Binary files a/modules/administration-guide/images/architecture/che-interacting-with-devworkspace.png and b/modules/administration-guide/images/architecture/che-interacting-with-devworkspace.png differ diff --git a/modules/administration-guide/images/architecture/che-plugin-registry-interactions.png b/modules/administration-guide/images/architecture/che-plugin-registry-interactions.png index 77c4dd4b79..c808193d36 100644 Binary files a/modules/administration-guide/images/architecture/che-plugin-registry-interactions.png and b/modules/administration-guide/images/architecture/che-plugin-registry-interactions.png differ diff --git a/modules/administration-guide/images/architecture/che-postgresql-interactions.png b/modules/administration-guide/images/architecture/che-postgresql-interactions.png index 1db96b51a4..5ab1b254fb 100644 Binary files a/modules/administration-guide/images/architecture/che-postgresql-interactions.png and b/modules/administration-guide/images/architecture/che-postgresql-interactions.png differ diff --git a/modules/administration-guide/images/architecture/che-server-interactions.png b/modules/administration-guide/images/architecture/che-server-interactions.png index 5f2a4355e6..47ec11f4db 100644 Binary files a/modules/administration-guide/images/architecture/che-server-interactions.png and b/modules/administration-guide/images/architecture/che-server-interactions.png differ diff --git a/modules/administration-guide/images/architecture/che-user-workspaces-interactions.png b/modules/administration-guide/images/architecture/che-user-workspaces-interactions.png index 3a66b8666d..53fe862d4e 100644 Binary files a/modules/administration-guide/images/architecture/che-user-workspaces-interactions.png and b/modules/administration-guide/images/architecture/che-user-workspaces-interactions.png differ diff --git a/modules/administration-guide/images/architecture/che-workspace-creation-flow.png b/modules/administration-guide/images/architecture/che-workspace-creation-flow.png deleted file mode 100644 index e8699fe57d..0000000000 Binary files a/modules/administration-guide/images/architecture/che-workspace-creation-flow.png and /dev/null differ diff --git a/modules/administration-guide/images/architecture/che-workspaces-controllers.png b/modules/administration-guide/images/architecture/che-workspaces-controllers.png deleted file mode 100644 index f8eb60c4c3..0000000000 Binary files a/modules/administration-guide/images/architecture/che-workspaces-controllers.png and /dev/null differ diff --git a/modules/administration-guide/images/architecture/che-workspaces.png b/modules/administration-guide/images/architecture/che-workspaces.png deleted file mode 100644 index 2487a99fe9..0000000000 Binary files a/modules/administration-guide/images/architecture/che-workspaces.png and /dev/null differ diff --git a/modules/contributor-guide/images/branding/about-dark.png b/modules/administration-guide/images/branding/about-dark.png similarity index 100% rename from modules/contributor-guide/images/branding/about-dark.png rename to modules/administration-guide/images/branding/about-dark.png diff --git a/modules/contributor-guide/images/branding/about-light.png b/modules/administration-guide/images/branding/about-light.png similarity index 100% rename from modules/contributor-guide/images/branding/about-light.png rename to modules/administration-guide/images/branding/about-light.png diff --git a/modules/contributor-guide/images/branding/welcome-dark.png b/modules/administration-guide/images/branding/welcome-dark.png similarity index 100% rename from modules/contributor-guide/images/branding/welcome-dark.png rename to modules/administration-guide/images/branding/welcome-dark.png diff --git a/modules/contributor-guide/images/branding/welcome-light.png b/modules/administration-guide/images/branding/welcome-light.png similarity index 100% rename from modules/contributor-guide/images/branding/welcome-light.png rename to modules/administration-guide/images/branding/welcome-light.png diff --git a/modules/administration-guide/images/contribute.svg b/modules/administration-guide/images/contribute.svg new file mode 100644 index 0000000000..576ba53f16 --- /dev/null +++ b/modules/administration-guide/images/contribute.svg @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + Copyright (c) 2012-2020 Red Hat, Inc. + This program and the accompanying materials are made + available under the terms of the Eclipse Public License 2.0 + which is available at https://www.eclipse.org/legal/epl-2.0/ + + SPDX-License-Identifier: EPL-2.0 + + Contributors: + Red Hat, Inc. - initial API and implementation + +--> +<svg width="147px" height="20px" viewBox="0 0 147 20" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"> + <g id="contribute-button"> + <g id="che-contribute"> + <rect fill="#292C2F" fill-rule="nonzero" x="0" y="0" width="117" height="20" rx="4"/> + <g id="Che-logo" transform="translate(8.000000, 2.000000)" fill="#FFFFFF"> + <polygon id="Path-1" points="0.00849162302 8.43339117 0 3.76684272 6.28508764 0 12.5555079 3.76444243 8.68435713 6.08858226 6.29640981 4.69321826"/> + <polygon id="Path-2" points="0 11.8401916 6.29139203 15.5603621 12.6082589 11.7541815 12.6082589 7.13817228 6.29139203 10.8266058 0 7.13817228"/> + </g> + <rect id="Rectangle-path" fill="#525D84" fill-rule="nonzero" x="30" y="0" width="117" height="20" rx="4"/> + <polygon id="Shape" fill="#525D84" fill-rule="nonzero" points="30 0 34 0 34 20 30 20"/> + <path d="M41.788,10.062 C41.788,10.6523363 41.6945009,11.1894976 41.5075,11.6735 C41.3204991,12.1575024 41.0565017,12.5718316 40.7155,12.9165 C40.3744983,13.2611684 39.9656691,13.5279157 39.489,13.71675 C39.0123309,13.9055843 38.4843362,14 37.905,14 L34.957,14 L34.957,6.1185 L37.905,6.1185 C38.4843362,6.1185 39.0123309,6.21291572 39.489,6.40175 C39.9656691,6.59058428 40.3744983,6.85824827 40.7155,7.20475 C41.0565017,7.55125173 41.3204991,7.96649758 41.5075,8.4505 C41.6945009,8.93450242 41.788,9.47166371 41.788,10.062 L41.788,10.062 Z M40.6935,10.062 C40.6935,9.57799758 40.6275007,9.14533524 40.4955,8.764 C40.3634993,8.38266476 40.1765012,8.06000132 39.9345,7.796 C39.6924988,7.53199868 39.3991684,7.33033403 39.0545,7.191 C38.7098316,7.05166597 38.3266688,6.982 37.905,6.982 L36.0295,6.982 L36.0295,13.1365 L37.905,13.1365 C38.3266688,13.1365 38.7098316,13.066834 39.0545,12.9275 C39.3991684,12.788166 39.6924988,12.587418 39.9345,12.32525 C40.1765012,12.063082 40.3634993,11.7413352 40.4955,11.36 C40.6275007,10.9786648 40.6935,10.5460024 40.6935,10.062 L40.6935,10.062 Z M45.2915,8.3405 C45.6251683,8.3405 45.9331653,8.39641611 46.2155,8.50825 C46.4978347,8.62008389 46.7416656,8.78141561 46.947,8.99225 C47.1523344,9.20308439 47.3127494,9.46341512 47.42825,9.77325 C47.5437506,10.0830849 47.6015,10.435998 47.6015,10.832 C47.6015,10.9860008 47.5850002,11.0886664 47.552,11.14 C47.5189998,11.1913336 47.4566671,11.217 47.365,11.217 L43.658,11.217 C43.6653334,11.5690018 43.7129996,11.8751654 43.801,12.1355 C43.8890004,12.3958346 44.0099992,12.6130825 44.164,12.78725 C44.3180008,12.9614175 44.5013323,13.0915829 44.714,13.17775 C44.9266677,13.2639171 45.1649987,13.307 45.429,13.307 C45.6746679,13.307 45.8864158,13.2785836 46.06425,13.22175 C46.2420842,13.1649164 46.395166,13.1035003 46.5235,13.0375 C46.651834,12.9714997 46.7590829,12.9100836 46.84525,12.85325 C46.9314171,12.7964164 47.0056664,12.768 47.068,12.768 C47.1486671,12.768 47.2109998,12.7991664 47.255,12.8615 L47.53,13.219 C47.4089994,13.3656674 47.2641675,13.4930828 47.0955,13.60125 C46.9268325,13.7094172 46.746251,13.798333 46.55375,13.868 C46.361249,13.937667 46.1623344,13.9899165 45.957,14.02475 C45.7516656,14.0595835 45.5481677,14.077 45.3465,14.077 C44.9614981,14.077 44.6067516,14.0119173 44.28225,13.88175 C43.9577484,13.7515827 43.6772512,13.5609179 43.44075,13.30975 C43.2042488,13.0585821 43.0200007,12.7478352 42.888,12.3775 C42.7559993,12.0071648 42.69,11.5818357 42.69,11.1015 C42.69,10.7128314 42.7495827,10.349835 42.86875,10.0125 C42.9879173,9.67516498 43.1593322,9.38275124 43.383,9.13525 C43.6066678,8.88774876 43.8798317,8.69341737 44.2025,8.55225 C44.5251683,8.41108263 44.8881647,8.3405 45.2915,8.3405 L45.2915,8.3405 Z M45.3135,9.061 C44.8404976,9.061 44.4683347,9.19758197 44.197,9.47075 C43.9256653,9.74391803 43.7570003,10.1224976 43.691,10.6065 L46.7215,10.6065 C46.7215,10.3791655 46.6903336,10.1710843 46.628,9.98225 C46.5656664,9.79341572 46.4740006,9.63025069 46.353,9.49275 C46.2319994,9.35524931 46.0844175,9.24891704 45.91025,9.17375 C45.7360825,9.09858296 45.5371678,9.061 45.3135,9.061 L45.3135,9.061 Z M48.003,8.4285 L48.806,8.4285 C48.8830004,8.4285 48.9471664,8.44866646 48.9985,8.489 C49.0498336,8.52933353 49.0864999,8.57699972 49.1085,8.632 L50.522,12.218 C50.5733336,12.3500007 50.6136665,12.4819993 50.643,12.614 C50.6723335,12.7460007 50.6998332,12.876166 50.7255,13.0045 C50.7548335,12.876166 50.7859998,12.7460007 50.819,12.614 C50.8520002,12.4819993 50.8941664,12.3500007 50.9455,12.218 L52.3755,8.632 C52.3975001,8.57333304 52.4332498,8.52475019 52.48275,8.48625 C52.5322502,8.44774981 52.5936663,8.4285 52.667,8.4285 L53.4315,8.4285 L51.16,14 L50.2745,14 L48.003,8.4285 Z M56.4015,8.3405 C56.7351683,8.3405 57.0431653,8.39641611 57.3255,8.50825 C57.6078347,8.62008389 57.8516656,8.78141561 58.057,8.99225 C58.2623344,9.20308439 58.4227494,9.46341512 58.53825,9.77325 C58.6537506,10.0830849 58.7115,10.435998 58.7115,10.832 C58.7115,10.9860008 58.6950002,11.0886664 58.662,11.14 C58.6289998,11.1913336 58.5666671,11.217 58.475,11.217 L54.768,11.217 C54.7753334,11.5690018 54.8229996,11.8751654 54.911,12.1355 C54.9990004,12.3958346 55.1199992,12.6130825 55.274,12.78725 C55.4280008,12.9614175 55.6113323,13.0915829 55.824,13.17775 C56.0366677,13.2639171 56.2749987,13.307 56.539,13.307 C56.7846679,13.307 56.9964158,13.2785836 57.17425,13.22175 C57.3520842,13.1649164 57.505166,13.1035003 57.6335,13.0375 C57.761834,12.9714997 57.8690829,12.9100836 57.95525,12.85325 C58.0414171,12.7964164 58.1156664,12.768 58.178,12.768 C58.2586671,12.768 58.3209998,12.7991664 58.365,12.8615 L58.64,13.219 C58.5189994,13.3656674 58.3741675,13.4930828 58.2055,13.60125 C58.0368325,13.7094172 57.856251,13.798333 57.66375,13.868 C57.471249,13.937667 57.2723344,13.9899165 57.067,14.02475 C56.8616656,14.0595835 56.6581677,14.077 56.4565,14.077 C56.0714981,14.077 55.7167516,14.0119173 55.39225,13.88175 C55.0677484,13.7515827 54.7872512,13.5609179 54.55075,13.30975 C54.3142488,13.0585821 54.1300007,12.7478352 53.998,12.3775 C53.8659993,12.0071648 53.8,11.5818357 53.8,11.1015 C53.8,10.7128314 53.8595827,10.349835 53.97875,10.0125 C54.0979173,9.67516498 54.2693322,9.38275124 54.493,9.13525 C54.7166678,8.88774876 54.9898317,8.69341737 55.3125,8.55225 C55.6351683,8.41108263 55.9981646,8.3405 56.4015,8.3405 L56.4015,8.3405 Z M56.4235,9.061 C55.9504976,9.061 55.5783347,9.19758197 55.307,9.47075 C55.0356653,9.74391803 54.8670003,10.1224976 54.801,10.6065 L57.8315,10.6065 C57.8315,10.3791655 57.8003336,10.1710843 57.738,9.98225 C57.6756664,9.79341572 57.5840006,9.63025069 57.463,9.49275 C57.3419994,9.35524931 57.1944175,9.24891704 57.02025,9.17375 C56.8460825,9.09858296 56.6471678,9.061 56.4235,9.061 L56.4235,9.061 Z M61.049,5.8985 L61.049,14 L60.07,14 L60.07,5.8985 L61.049,5.8985 Z M65.031,8.3405 C65.438002,8.3405 65.8055817,8.40833265 66.13375,8.544 C66.4619183,8.67966734 66.7405822,8.87216542 66.96975,9.1215 C67.1989178,9.37083458 67.3749161,9.6724149 67.49775,10.02625 C67.6205839,10.3800851 67.682,10.7751645 67.682,11.2115 C67.682,11.6515022 67.6205839,12.0474982 67.49775,12.3995 C67.3749161,12.7515018 67.1989178,13.0521654 66.96975,13.3015 C66.7405822,13.5508346 66.4619183,13.742416 66.13375,13.87625 C65.8055817,14.010084 65.438002,14.077 65.031,14.077 C64.623998,14.077 64.2564183,14.010084 63.92825,13.87625 C63.6000817,13.742416 63.3205012,13.5508346 63.0895,13.3015 C62.8584988,13.0521654 62.6806673,12.7515018 62.556,12.3995 C62.4313327,12.0474982 62.369,11.6515022 62.369,11.2115 C62.369,10.7751645 62.4313327,10.3800851 62.556,10.02625 C62.6806673,9.6724149 62.8584988,9.37083458 63.0895,9.1215 C63.3205012,8.87216542 63.6000817,8.67966734 63.92825,8.544 C64.2564183,8.40833265 64.623998,8.3405 65.031,8.3405 L65.031,8.3405 Z M65.031,13.3125 C65.5810027,13.3125 65.9916653,13.1282518 66.263,12.75975 C66.5343347,12.3912482 66.67,11.8770033 66.67,11.217 C66.67,10.55333 66.5343347,10.0363352 66.263,9.666 C65.9916653,9.29566481 65.5810027,9.1105 65.031,9.1105 C64.7523319,9.1105 64.5103344,9.15816619 64.305,9.2535 C64.0996656,9.34883381 63.9282507,9.48633243 63.79075,9.666 C63.6532493,9.84566756 63.5505837,10.066582 63.48275,10.32875 C63.4149163,10.590918 63.381,10.8869984 63.381,11.217 C63.381,11.5470016 63.4149163,11.8421654 63.48275,12.1025 C63.5505837,12.3628346 63.6532493,12.5819158 63.79075,12.75975 C63.9282507,12.9375842 64.0996656,13.0741662 64.305,13.1695 C64.5103344,13.2648338 64.7523319,13.3125 65.031,13.3125 L65.031,13.3125 Z M68.892,15.8865 L68.892,8.4285 L69.475,8.4285 C69.614334,8.4285 69.7023332,8.49633265 69.739,8.632 L69.8215,9.292 C70.0598345,9.00233188 70.3320818,8.76950088 70.63825,8.5935 C70.9444182,8.41749912 71.2973313,8.3295 71.697,8.3295 C72.0160016,8.3295 72.3056654,8.39091605 72.566,8.51375 C72.8263346,8.63658395 73.0481657,8.81808213 73.2315,9.05825 C73.4148342,9.29841787 73.5559995,9.59633155 73.655,9.952 C73.7540005,10.3076684 73.8035,10.7164977 73.8035,11.1785 C73.8035,11.5891687 73.7485006,11.9714149 73.6385,12.32525 C73.5284994,12.6790851 73.3708344,12.9852487 73.1655,13.24375 C72.9601656,13.5022513 72.7080848,13.7057493 72.40925,13.85425 C72.1104152,14.0027507 71.7740019,14.077 71.4,14.077 C71.0553316,14.077 70.7610846,14.0201672 70.51725,13.9065 C70.2734154,13.7928328 70.0580009,13.631501 69.871,13.4225 L69.871,15.8865 L68.892,15.8865 Z M71.3725,9.1215 C71.0534984,9.1215 70.7739179,9.1948326 70.53375,9.3415 C70.2935821,9.4881674 70.0726677,9.69533199 69.871,9.963 L69.871,12.658 C70.0506676,12.9000012 70.2477489,13.0704995 70.46225,13.1695 C70.6767511,13.2685005 70.9159987,13.318 71.18,13.318 C71.6970026,13.318 72.0948319,13.1328352 72.3735,12.7625 C72.6521681,12.3921648 72.7915,11.8641701 72.7915,11.1785 C72.7915,10.8154982 72.759417,10.5038346 72.69525,10.2435 C72.631083,9.98316536 72.5385006,9.76958417 72.4175,9.60275 C72.2964994,9.43591583 72.1480009,9.31400038 71.972,9.237 C71.7959991,9.15999961 71.5961678,9.1215 71.3725,9.1215 L71.3725,9.1215 Z M77.1695,8.3405 C77.5031683,8.3405 77.8111653,8.39641611 78.0935,8.50825 C78.3758347,8.62008389 78.6196656,8.78141561 78.825,8.99225 C79.0303344,9.20308439 79.1907494,9.46341512 79.30625,9.77325 C79.4217506,10.0830849 79.4795,10.435998 79.4795,10.832 C79.4795,10.9860008 79.4630002,11.0886664 79.43,11.14 C79.3969998,11.1913336 79.3346671,11.217 79.243,11.217 L75.536,11.217 C75.5433334,11.5690018 75.5909996,11.8751654 75.679,12.1355 C75.7670004,12.3958346 75.8879992,12.6130825 76.042,12.78725 C76.1960008,12.9614175 76.3793323,13.0915829 76.592,13.17775 C76.8046677,13.2639171 77.0429987,13.307 77.307,13.307 C77.5526679,13.307 77.7644158,13.2785836 77.94225,13.22175 C78.1200842,13.1649164 78.273166,13.1035003 78.4015,13.0375 C78.529834,12.9714997 78.6370829,12.9100836 78.72325,12.85325 C78.8094171,12.7964164 78.8836664,12.768 78.946,12.768 C79.0266671,12.768 79.0889998,12.7991664 79.133,12.8615 L79.408,13.219 C79.2869994,13.3656674 79.1421675,13.4930828 78.9735,13.60125 C78.8048325,13.7094172 78.624251,13.798333 78.43175,13.868 C78.239249,13.937667 78.0403344,13.9899165 77.835,14.02475 C77.6296656,14.0595835 77.4261677,14.077 77.2245,14.077 C76.8394981,14.077 76.4847516,14.0119173 76.16025,13.88175 C75.8357484,13.7515827 75.5552512,13.5609179 75.31875,13.30975 C75.0822488,13.0585821 74.8980007,12.7478352 74.766,12.3775 C74.6339993,12.0071648 74.568,11.5818357 74.568,11.1015 C74.568,10.7128314 74.6275827,10.349835 74.74675,10.0125 C74.8659173,9.67516498 75.0373322,9.38275124 75.261,9.13525 C75.4846678,8.88774876 75.7578317,8.69341737 76.0805,8.55225 C76.4031683,8.41108263 76.7661647,8.3405 77.1695,8.3405 L77.1695,8.3405 Z M77.1915,9.061 C76.7184976,9.061 76.3463347,9.19758197 76.075,9.47075 C75.8036653,9.74391803 75.6350003,10.1224976 75.569,10.6065 L78.5995,10.6065 C78.5995,10.3791655 78.5683336,10.1710843 78.506,9.98225 C78.4436664,9.79341572 78.3520006,9.63025069 78.231,9.49275 C78.1099994,9.35524931 77.9624175,9.24891704 77.78825,9.17375 C77.6140825,9.09858296 77.4151678,9.061 77.1915,9.061 L77.1915,9.061 Z M80.728,14 L80.728,8.4285 L81.289,8.4285 C81.3953339,8.4285 81.4686665,8.44866646 81.509,8.489 C81.5493335,8.52933353 81.5768333,8.5989995 81.5915,8.698 L81.6575,9.567 C81.8481676,9.17833139 82.0837486,8.87491776 82.36425,8.65675 C82.6447514,8.43858224 82.9738314,8.3295 83.3515,8.3295 C83.5055008,8.3295 83.6448327,8.34691649 83.7695,8.38175 C83.8941673,8.41658351 84.0096661,8.46516635 84.116,8.5275 L83.9895,9.259 C83.9638332,9.35066712 83.9070004,9.3965 83.819,9.3965 C83.7676664,9.3965 83.6888339,9.37908351 83.5825,9.34425 C83.4761661,9.30941649 83.3276676,9.292 83.137,9.292 C82.7959983,9.292 82.5109178,9.39099901 82.28175,9.589 C82.0525822,9.78700099 81.8610008,10.0748314 81.707,10.4525 L81.707,14 L80.728,14 Z M86.558,6.1185 L87.4435,6.1185 C87.5388338,6.1185 87.6176664,6.14233309 87.68,6.19 C87.7423336,6.2376669 87.7844999,6.2981663 87.8065,6.3715 L89.4345,11.8495 C89.4638335,11.9485005 89.4904165,12.0548328 89.51425,12.1685 C89.5380835,12.2821672 89.5609999,12.4013327 89.583,12.526 C89.6086668,12.4013327 89.6343332,12.2812506 89.66,12.16575 C89.6856668,12.0502494 89.7149998,11.9448338 89.748,11.8495 L91.6015,6.3715 C91.6235001,6.30916635 91.666583,6.25141693 91.73075,6.19825 C91.794917,6.14508307 91.8728329,6.1185 91.9645,6.1185 L92.2725,6.1185 C92.3678338,6.1185 92.4457497,6.14233309 92.50625,6.19 C92.5667503,6.2376669 92.6098332,6.2981663 92.6355,6.3715 L94.478,11.8495 C94.5440003,12.0401676 94.6026664,12.2583321 94.654,12.504 C94.6760001,12.3829994 94.6961666,12.2675005 94.7145,12.1575 C94.7328334,12.0474994 94.7566665,11.9448338 94.786,11.8495 L96.4195,6.3715 C96.4378334,6.30549967 96.479083,6.24683359 96.54325,6.1955 C96.607417,6.14416641 96.6853329,6.1185 96.777,6.1185 L97.6075,6.1185 L95.149,14 L94.192,14 L92.1955,7.9885 C92.1551665,7.87483276 92.1185002,7.74283408 92.0855,7.5925 C92.0671666,7.6658337 92.0497501,7.73641633 92.03325,7.80425 C92.0167499,7.87208367 91.9993334,7.93349972 91.981,7.9885 L89.9735,14 L89.0165,14 L86.558,6.1185 Z M100.572,8.3405 C100.979002,8.3405 101.346582,8.40833265 101.67475,8.544 C102.002918,8.67966734 102.281582,8.87216542 102.51075,9.1215 C102.739918,9.37083458 102.915916,9.6724149 103.03875,10.02625 C103.161584,10.3800851 103.223,10.7751645 103.223,11.2115 C103.223,11.6515022 103.161584,12.0474982 103.03875,12.3995 C102.915916,12.7515018 102.739918,13.0521654 102.51075,13.3015 C102.281582,13.5508346 102.002918,13.742416 101.67475,13.87625 C101.346582,14.010084 100.979002,14.077 100.572,14.077 C100.164998,14.077 99.7974183,14.010084 99.46925,13.87625 C99.1410817,13.742416 98.8615012,13.5508346 98.6305,13.3015 C98.3994988,13.0521654 98.2216673,12.7515018 98.097,12.3995 C97.9723327,12.0474982 97.91,11.6515022 97.91,11.2115 C97.91,10.7751645 97.9723327,10.3800851 98.097,10.02625 C98.2216673,9.6724149 98.3994988,9.37083458 98.6305,9.1215 C98.8615012,8.87216542 99.1410817,8.67966734 99.46925,8.544 C99.7974183,8.40833265 100.164998,8.3405 100.572,8.3405 L100.572,8.3405 Z M100.572,13.3125 C101.122003,13.3125 101.532665,13.1282518 101.804,12.75975 C102.075335,12.3912482 102.211,11.8770033 102.211,11.217 C102.211,10.55333 102.075335,10.0363352 101.804,9.666 C101.532665,9.29566481 101.122003,9.1105 100.572,9.1105 C100.293332,9.1105 100.051334,9.15816619 99.846,9.2535 C99.6406656,9.34883381 99.4692507,9.48633243 99.33175,9.666 C99.1942493,9.84566756 99.0915837,10.066582 99.02375,10.32875 C98.9559163,10.590918 98.922,10.8869984 98.922,11.217 C98.922,11.5470016 98.9559163,11.8421654 99.02375,12.1025 C99.0915837,12.3628346 99.1942493,12.5819158 99.33175,12.75975 C99.4692507,12.9375842 99.6406656,13.0741662 99.846,13.1695 C100.051334,13.2648338 100.293332,13.3125 100.572,13.3125 L100.572,13.3125 Z M104.433,14 L104.433,8.4285 L104.994,8.4285 C105.100334,8.4285 105.173666,8.44866646 105.214,8.489 C105.254334,8.52933353 105.281833,8.5989995 105.2965,8.698 L105.3625,9.567 C105.553168,9.17833139 105.788749,8.87491776 106.06925,8.65675 C106.349751,8.43858224 106.678831,8.3295 107.0565,8.3295 C107.210501,8.3295 107.349833,8.34691649 107.4745,8.38175 C107.599167,8.41658351 107.714666,8.46516635 107.821,8.5275 L107.6945,9.259 C107.668833,9.35066712 107.612,9.3965 107.524,9.3965 C107.472666,9.3965 107.393834,9.37908351 107.2875,9.34425 C107.181166,9.30941649 107.032668,9.292 106.842,9.292 C106.500998,9.292 106.215918,9.39099901 105.98675,9.589 C105.757582,9.78700099 105.566001,10.0748314 105.412,10.4525 L105.412,14 L104.433,14 Z M109.8835,5.8985 L109.8835,10.667 L110.1365,10.667 C110.209834,10.667 110.270333,10.6569168 110.318,10.63675 C110.365667,10.6165832 110.418833,10.5753336 110.4775,10.513 L112.2375,8.6265 C112.2925,8.56783304 112.3475,8.52016685 112.4025,8.4835 C112.4575,8.44683315 112.530833,8.4285 112.6225,8.4285 L113.5135,8.4285 L111.462,10.612 C111.410666,10.6743336 111.36025,10.7293331 111.31075,10.777 C111.26125,10.8246669 111.205334,10.8668332 111.143,10.9035 C111.209,10.9475002 111.268583,10.9979164 111.32175,11.05475 C111.374917,11.1115836 111.425333,11.1766663 111.473,11.25 L113.651,14 L112.771,14 C112.690333,14 112.621584,13.9844168 112.56475,13.95325 C112.507916,13.9220832 112.453834,13.8735003 112.4025,13.8075 L110.571,11.525 C110.516,11.4479996 110.461,11.3975835 110.406,11.37375 C110.351,11.3499165 110.268501,11.338 110.1585,11.338 L109.8835,11.338 L109.8835,14 L108.899,14 L108.899,5.8985 L109.8835,5.8985 Z M117.82,9.347 C117.776,9.42766707 117.708167,9.468 117.6165,9.468 C117.5615,9.468 117.499167,9.44783353 117.4295,9.4075 C117.359833,9.36716646 117.274584,9.32225025 117.17375,9.27275 C117.072916,9.22324975 116.952834,9.17741688 116.8135,9.13525 C116.674166,9.09308312 116.509168,9.072 116.3185,9.072 C116.153499,9.072 116.005001,9.09308312 115.873,9.13525 C115.740999,9.17741688 115.62825,9.2351663 115.53475,9.3085 C115.44125,9.3818337 115.36975,9.46708285 115.32025,9.56425 C115.27075,9.66141715 115.246,9.76683276 115.246,9.8805 C115.246,10.0235007 115.28725,10.1426662 115.36975,10.238 C115.45225,10.3333338 115.561333,10.415833 115.697,10.4855 C115.832667,10.555167 115.986666,10.6165831 116.159,10.66975 C116.331334,10.7229169 116.508249,10.7797497 116.68975,10.84025 C116.871251,10.9007503 117.048166,10.9676663 117.2205,11.041 C117.392834,11.1143337 117.546833,11.2059994 117.6825,11.316 C117.818167,11.4260005 117.92725,11.5607492 118.00975,11.72025 C118.09225,11.8797508 118.1335,12.0713322 118.1335,12.295 C118.1335,12.5516679 118.087667,12.7890822 117.996,13.00725 C117.904333,13.2254178 117.768668,13.4142492 117.589,13.57375 C117.409332,13.7332508 117.189335,13.8588329 116.929,13.9505 C116.668665,14.0421671 116.368002,14.088 116.027,14.088 C115.638331,14.088 115.286335,14.0247506 114.971,13.89825 C114.655665,13.7717494 114.388001,13.609501 114.168,13.4115 L114.399,13.0375 C114.428333,12.9898331 114.463166,12.9531668 114.5035,12.9275 C114.543834,12.9018332 114.597,12.889 114.663,12.889 C114.729,12.889 114.798666,12.9146664 114.872,12.966 C114.945334,13.0173336 115.034249,13.0741664 115.13875,13.1365 C115.243251,13.1988336 115.369749,13.2556664 115.51825,13.307 C115.666751,13.3583336 115.852832,13.384 116.0765,13.384 C116.267168,13.384 116.433999,13.3592502 116.577,13.30975 C116.720001,13.2602498 116.839166,13.1933338 116.9345,13.109 C117.029834,13.0246662 117.100416,12.9275005 117.14625,12.8175 C117.192084,12.7074994 117.215,12.5901673 117.215,12.4655 C117.215,12.3114992 117.17375,12.1840838 117.09125,12.08325 C117.00875,11.9824162 116.899667,11.8962504 116.764,11.82475 C116.628333,11.7532496 116.473418,11.6909169 116.29925,11.63775 C116.125082,11.5845831 115.947251,11.528667 115.76575,11.47 C115.584249,11.411333 115.406418,11.344417 115.23225,11.26925 C115.058082,11.194083 114.903167,11.0996672 114.7675,10.986 C114.631833,10.8723328 114.52275,10.7320842 114.44025,10.56525 C114.35775,10.3984158 114.3165,10.1958345 114.3165,9.9575 C114.3165,9.74483227 114.3605,9.54041765 114.4485,9.34425 C114.5365,9.14808235 114.664832,8.97575074 114.8335,8.82725 C115.002168,8.67874926 115.209332,8.56050044 115.455,8.4725 C115.700668,8.38449956 115.981165,8.3405 116.2965,8.3405 C116.663168,8.3405 116.992249,8.39824942 117.28375,8.51375 C117.575251,8.62925058 117.827332,8.78783232 118.04,8.9895 L117.82,9.347 Z M119.404,15.8865 L119.404,8.4285 L119.987,8.4285 C120.126334,8.4285 120.214333,8.49633265 120.251,8.632 L120.3335,9.292 C120.571835,9.00233188 120.844082,8.76950088 121.15025,8.5935 C121.456418,8.41749912 121.809331,8.3295 122.209,8.3295 C122.528002,8.3295 122.817665,8.39091605 123.078,8.51375 C123.338335,8.63658395 123.560166,8.81808213 123.7435,9.05825 C123.926834,9.29841787 124.068,9.59633155 124.167,9.952 C124.266,10.3076684 124.3155,10.7164977 124.3155,11.1785 C124.3155,11.5891687 124.260501,11.9714149 124.1505,12.32525 C124.040499,12.6790851 123.882834,12.9852487 123.6775,13.24375 C123.472166,13.5022513 123.220085,13.7057493 122.92125,13.85425 C122.622415,14.0027507 122.286002,14.077 121.912,14.077 C121.567332,14.077 121.273085,14.0201672 121.02925,13.9065 C120.785415,13.7928328 120.570001,13.631501 120.383,13.4225 L120.383,15.8865 L119.404,15.8865 Z M121.8845,9.1215 C121.565498,9.1215 121.285918,9.1948326 121.04575,9.3415 C120.805582,9.4881674 120.584668,9.69533199 120.383,9.963 L120.383,12.658 C120.562668,12.9000012 120.759749,13.0704995 120.97425,13.1695 C121.188751,13.2685005 121.427999,13.318 121.692,13.318 C122.209003,13.318 122.606832,13.1328352 122.8855,12.7625 C123.164168,12.3921648 123.3035,11.8641701 123.3035,11.1785 C123.3035,10.8154982 123.271417,10.5038346 123.20725,10.2435 C123.143083,9.98316536 123.050501,9.76958417 122.9295,9.60275 C122.808499,9.43591583 122.660001,9.31400038 122.484,9.237 C122.307999,9.15999961 122.108168,9.1215 121.8845,9.1215 L121.8845,9.1215 Z M129.568,14 L129.1335,14 C129.038166,14 128.961167,13.9853335 128.9025,13.956 C128.843833,13.9266665 128.805333,13.8643338 128.787,13.769 L128.677,13.252 C128.530333,13.3840007 128.387334,13.5022495 128.248,13.60675 C128.108666,13.7112505 127.962001,13.7992496 127.808,13.87075 C127.653999,13.9422504 127.489918,13.9963331 127.31575,14.033 C127.141582,14.0696668 126.948168,14.088 126.7355,14.088 C126.519166,14.088 126.316584,14.0577503 126.12775,13.99725 C125.938916,13.9367497 125.774834,13.8460006 125.6355,13.725 C125.496166,13.6039994 125.38525,13.4509176 125.30275,13.26575 C125.22025,13.0805824 125.179,12.8615013 125.179,12.6085 C125.179,12.3884989 125.239499,12.176751 125.3605,11.97325 C125.481501,11.769749 125.676749,11.5891675 125.94625,11.4315 C126.215751,11.2738325 126.568664,11.1445838 127.005,11.04375 C127.441336,10.9429162 127.97483,10.8851667 128.6055,10.8705 L128.6055,10.436 C128.6055,10.0033312 128.512918,9.67608444 128.32775,9.45425 C128.142582,9.23241556 127.868502,9.1215 127.5055,9.1215 C127.267165,9.1215 127.066417,9.1517497 126.90325,9.21225 C126.740083,9.2727503 126.598917,9.34058296 126.47975,9.41575 C126.360583,9.49091704 126.257917,9.5587497 126.17175,9.61925 C126.085583,9.6797503 126.000334,9.71 125.916,9.71 C125.85,9.71 125.79225,9.69258351 125.74275,9.65775 C125.69325,9.62291649 125.653833,9.57983359 125.6245,9.5285 L125.4485,9.215 C125.756502,8.91799851 126.088332,8.6961674 126.444,8.5495 C126.799668,8.4028326 127.193831,8.3295 127.6265,8.3295 C127.938168,8.3295 128.214999,8.38083282 128.457,8.4835 C128.699001,8.58616718 128.902499,8.72916575 129.0675,8.9125 C129.232501,9.09583425 129.357166,9.31766536 129.4415,9.578 C129.525834,9.83833463 129.568,10.1243318 129.568,10.436 L129.568,14 Z M127.027,13.4005 C127.199334,13.4005 127.356999,13.3830835 127.5,13.34825 C127.643001,13.3134165 127.777749,13.263917 127.90425,13.19975 C128.030751,13.135583 128.151749,13.0576671 128.26725,12.966 C128.382751,12.8743329 128.495499,12.7698339 128.6055,12.6525 L128.6055,11.492 C128.154498,11.5066667 127.771335,11.5424164 127.456,11.59925 C127.140665,11.6560836 126.884001,11.7303329 126.686,11.822 C126.487999,11.9136671 126.344084,12.0218327 126.25425,12.1465 C126.164416,12.2711673 126.1195,12.4104992 126.1195,12.5645 C126.1195,12.7111674 126.143333,12.8376661 126.191,12.944 C126.238667,13.0503339 126.302833,13.1374163 126.3835,13.20525 C126.464167,13.2730837 126.559499,13.3225832 126.6695,13.35375 C126.779501,13.3849168 126.898666,13.4005 127.027,13.4005 L127.027,13.4005 Z M134.8535,9.4185 C134.824167,9.45883353 134.794833,9.48999989 134.7655,9.512 C134.736167,9.53400011 134.694,9.545 134.639,9.545 C134.584,9.545 134.524417,9.52208356 134.46025,9.47625 C134.396083,9.43041644 134.3145,9.38000027 134.2155,9.325 C134.1165,9.26999972 133.996417,9.21958356 133.85525,9.17375 C133.714083,9.12791644 133.540834,9.105 133.3355,9.105 C133.064165,9.105 132.824001,9.15358285 132.615,9.25075 C132.405999,9.34791715 132.230917,9.48816575 132.08975,9.6715 C131.948583,9.85483425 131.84225,10.0766654 131.77075,10.337 C131.69925,10.5973346 131.6635,10.8888317 131.6635,11.2115 C131.6635,11.548835 131.702,11.848582 131.779,12.11075 C131.856,12.372918 131.964166,12.5929158 132.1035,12.77075 C132.242834,12.9485842 132.412416,13.0842495 132.61225,13.17775 C132.812084,13.2712505 133.036665,13.318 133.286,13.318 C133.524335,13.318 133.720499,13.2895836 133.8745,13.23275 C134.028501,13.1759164 134.156833,13.112667 134.2595,13.043 C134.362167,12.973333 134.4465,12.9100836 134.5125,12.85325 C134.5785,12.7964164 134.6445,12.768 134.7105,12.768 C134.794834,12.768 134.857166,12.7991664 134.8975,12.8615 L135.1725,13.219 C134.930499,13.5160015 134.628002,13.7332493 134.265,13.87075 C133.901998,14.0082507 133.518835,14.077 133.1155,14.077 C132.767165,14.077 132.443585,14.012834 132.14475,13.8845 C131.845915,13.756166 131.586501,13.5700846 131.3665,13.32625 C131.146499,13.0824154 130.973251,12.7826684 130.84675,12.427 C130.720249,12.0713316 130.657,11.6661689 130.657,11.2115 C130.657,10.7971646 130.714749,10.4140018 130.83025,10.062 C130.945751,9.70999824 131.114416,9.40658461 131.33625,9.15175 C131.558084,8.89691539 131.832165,8.69800071 132.1585,8.555 C132.484835,8.41199928 132.858831,8.3405 133.2805,8.3405 C133.669169,8.3405 134.013832,8.40374937 134.3145,8.53025 C134.615168,8.65675063 134.880999,8.83549884 135.112,9.0665 L134.8535,9.4185 Z M138.3955,8.3405 C138.729168,8.3405 139.037165,8.39641611 139.3195,8.50825 C139.601835,8.62008389 139.845666,8.78141561 140.051,8.99225 C140.256334,9.20308439 140.416749,9.46341512 140.53225,9.77325 C140.647751,10.0830849 140.7055,10.435998 140.7055,10.832 C140.7055,10.9860008 140.689,11.0886664 140.656,11.14 C140.623,11.1913336 140.560667,11.217 140.469,11.217 L136.762,11.217 C136.769333,11.5690018 136.817,11.8751654 136.905,12.1355 C136.993,12.3958346 137.113999,12.6130825 137.268,12.78725 C137.422001,12.9614175 137.605332,13.0915829 137.818,13.17775 C138.030668,13.2639171 138.268999,13.307 138.533,13.307 C138.778668,13.307 138.990416,13.2785836 139.16825,13.22175 C139.346084,13.1649164 139.499166,13.1035003 139.6275,13.0375 C139.755834,12.9714997 139.863083,12.9100836 139.94925,12.85325 C140.035417,12.7964164 140.109666,12.768 140.172,12.768 C140.252667,12.768 140.315,12.7991664 140.359,12.8615 L140.634,13.219 C140.512999,13.3656674 140.368168,13.4930828 140.1995,13.60125 C140.030832,13.7094172 139.850251,13.798333 139.65775,13.868 C139.465249,13.937667 139.266334,13.9899165 139.061,14.02475 C138.855666,14.0595835 138.652168,14.077 138.4505,14.077 C138.065498,14.077 137.710752,14.0119173 137.38625,13.88175 C137.061748,13.7515827 136.781251,13.5609179 136.54475,13.30975 C136.308249,13.0585821 136.124001,12.7478352 135.992,12.3775 C135.859999,12.0071648 135.794,11.5818357 135.794,11.1015 C135.794,10.7128314 135.853583,10.349835 135.97275,10.0125 C136.091917,9.67516498 136.263332,9.38275124 136.487,9.13525 C136.710668,8.88774876 136.983832,8.69341737 137.3065,8.55225 C137.629168,8.41108263 137.992165,8.3405 138.3955,8.3405 L138.3955,8.3405 Z M138.4175,9.061 C137.944498,9.061 137.572335,9.19758197 137.301,9.47075 C137.029665,9.74391803 136.861,10.1224976 136.795,10.6065 L139.8255,10.6065 C139.8255,10.3791655 139.794334,10.1710843 139.732,9.98225 C139.669666,9.79341572 139.578001,9.63025069 139.457,9.49275 C139.335999,9.35524931 139.188418,9.24891704 139.01425,9.17375 C138.840082,9.09858296 138.641168,9.061 138.4175,9.061 L138.4175,9.061 Z" id="Developer-Workspace" fill="#FFFFFF" fill-rule="nonzero"/> + </g> + </g> + </g> +</svg> \ No newline at end of file diff --git a/modules/administration-guide/images/creating-a-telemetry-plug-in/devworkspace_telemetry_plugin.png b/modules/administration-guide/images/creating-a-telemetry-plug-in/devworkspace_telemetry_plugin.png new file mode 100644 index 0000000000..150aee9539 Binary files /dev/null and b/modules/administration-guide/images/creating-a-telemetry-plug-in/devworkspace_telemetry_plugin.png differ diff --git a/modules/installation-guide/images/installation/specifying-upgrade-strategy.png b/modules/administration-guide/images/installation/specifying-upgrade-strategy.png similarity index 100% rename from modules/installation-guide/images/installation/specifying-upgrade-strategy.png rename to modules/administration-guide/images/installation/specifying-upgrade-strategy.png diff --git a/modules/administration-guide/images/keycloak/external_keycloak_public_client.png b/modules/administration-guide/images/keycloak/external_keycloak_public_client.png deleted file mode 100644 index bd498377c6..0000000000 Binary files a/modules/administration-guide/images/keycloak/external_keycloak_public_client.png and /dev/null differ diff --git a/modules/administration-guide/images/keycloak/external_keycloak_realm.png b/modules/administration-guide/images/keycloak/external_keycloak_realm.png deleted file mode 100644 index 11fa2054c3..0000000000 Binary files a/modules/administration-guide/images/keycloak/external_keycloak_realm.png and /dev/null differ diff --git a/modules/administration-guide/images/keycloak/keycloak_realm.png b/modules/administration-guide/images/keycloak/keycloak_realm.png deleted file mode 100644 index ad488ffebf..0000000000 Binary files a/modules/administration-guide/images/keycloak/keycloak_realm.png and /dev/null differ diff --git a/modules/administration-guide/images/logs/kubernetes-events.png b/modules/administration-guide/images/logs/kubernetes-events.png deleted file mode 100644 index 8e411e1200..0000000000 Binary files a/modules/administration-guide/images/logs/kubernetes-events.png and /dev/null differ diff --git a/modules/administration-guide/images/monitoring/monitoring-dev-workspace-metrics-panel.png b/modules/administration-guide/images/monitoring/monitoring-dev-workspace-metrics-panel.png new file mode 100644 index 0000000000..25213a2da6 Binary files /dev/null and b/modules/administration-guide/images/monitoring/monitoring-dev-workspace-metrics-panel.png differ diff --git a/modules/administration-guide/images/monitoring/monitoring-dev-workspace-operator-metrics-panel-1.png b/modules/administration-guide/images/monitoring/monitoring-dev-workspace-operator-metrics-panel-1.png new file mode 100644 index 0000000000..c380067ed2 Binary files /dev/null and b/modules/administration-guide/images/monitoring/monitoring-dev-workspace-operator-metrics-panel-1.png differ diff --git a/modules/administration-guide/images/monitoring/monitoring-dev-workspace-operator-metrics-panel-2.png b/modules/administration-guide/images/monitoring/monitoring-dev-workspace-operator-metrics-panel-2.png new file mode 100644 index 0000000000..e987fb481c Binary files /dev/null and b/modules/administration-guide/images/monitoring/monitoring-dev-workspace-operator-metrics-panel-2.png differ diff --git a/modules/administration-guide/images/security/che-authentication-inside-the-workspace.png b/modules/administration-guide/images/security/che-authentication-inside-the-workspace.png deleted file mode 100644 index 21b2a92492..0000000000 Binary files a/modules/administration-guide/images/security/che-authentication-inside-the-workspace.png and /dev/null differ diff --git a/modules/administration-guide/images/telemetry/telemetry_diagram.png b/modules/administration-guide/images/telemetry/telemetry_diagram.png new file mode 100644 index 0000000000..f6d3531740 Binary files /dev/null and b/modules/administration-guide/images/telemetry/telemetry_diagram.png differ diff --git a/modules/administration-guide/images/tracing/trace-search.png b/modules/administration-guide/images/tracing/trace-search.png deleted file mode 100644 index e1a5282b14..0000000000 Binary files a/modules/administration-guide/images/tracing/trace-search.png and /dev/null differ diff --git a/modules/administration-guide/images/tracing/trace-tree-expanded.png b/modules/administration-guide/images/tracing/trace-tree-expanded.png deleted file mode 100644 index 695d98f5e8..0000000000 Binary files a/modules/administration-guide/images/tracing/trace-tree-expanded.png and /dev/null differ diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index f638e6d110..e967dcf6ce 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -1,10 +1,8 @@ .Administration Guide -* xref:che-architecture-overview.adoc[] -** xref:architecture-overview-with-che-server.adoc[] -*** xref:server-components-with-che-server.adoc[] -*** xref:che-workspaces-architecture-with-che-server.adoc[] -** xref:architecture-overview-with-devworkspace.adoc[] +* xref:preparing-the-installation.adoc[] +** xref:supported-platforms.adoc[] +** xref:architecture-overview.adoc[] *** xref:server-components.adoc[] **** xref:che-operator.adoc[] **** xref:devworkspace-operator.adoc[] @@ -15,56 +13,66 @@ **** xref:postgresql.adoc[] **** xref:plug-in-registry.adoc[] *** xref:user-workspaces.adoc[] - -* xref:calculating-che-resource-requirements.adoc[] - -* xref:customizing-the-registries.adoc[] -** xref:building-custom-registry-images.adoc[] -** xref:running-custom-registries.adoc[] - -* xref:retrieving-che-logs.adoc[] -** xref:configuring-server-logging.adoc[] -** xref:viewing-kubernetes-events.adoc[] -** xref:viewing-operator-events.adoc[] -** xref:viewing-che-server-logs.adoc[] -** xref:viewing-external-service-logs.adoc[] -** xref:viewing-plug-in-broker-logs.adoc[] -** xref:collecting-logs-using-chectl.adoc[] - -* xref:monitoring-che.adoc[] - -* xref:tracing-che.adoc[] - -* xref:backup-and-disaster-recovery.adoc[] -** xref:setup-backup-server.adoc[] -** xref:managing-backups-using-cli.adoc[] -*** xref:configuring-cli-to-use-backup-server.adoc[] -** xref:managing-backups-using-custom-resources.adoc[] -*** xref:define-backup-server-for-operator.adoc[] -** xref:persistent-volumes-backups.adoc[] -** xref:external-database-setup.adoc[] - -* xref:migration-from-postgresql-9-to-postgresql-13.adoc[] - -* xref:readiness-init-containers.adoc[] -** xref:enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[] -*** xref:enabling-readiness-init-containers-for-the-operator-installer.adoc[] -*** xref:disabling-readiness-init-containers-for-the-operator-installer.adoc[] -** xref:enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[] -*** xref:enabling-readiness-init-containers-for-the-olm-installer.adoc[] -*** xref:disabling-readiness-init-containers-for-the-olm-installer.adoc[] - -* xref:caching-images-for-faster-workspace-start.adoc[] -** xref:defining-the-list-of-images-to-pull.adoc[] -** xref:defining-the-memory-parameters-for-the-image-puller.adoc[] -** xref:installing-image-puller-using-che-operator.adoc[] -** xref:installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc[] -** xref:installing-image-puller-on-openshift-using-operatorhub.adoc[] -** xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[] - -* xref:managing-identities-and-authorizations.adoc[] -** xref:authenticating-users.adoc[] -** xref:authorizing-users.adoc[] -** xref:configuring-authorization.adoc[] -** xref:configuring-openshift-oauth.adoc[] -** xref:removing-user-data.adoc[] +** xref:calculating-che-resource-requirements.adoc[] +* xref:installing-che.adoc[] +** xref:installing-che-on-openshift-4-using-operatorhub.adoc[] +** xref:using-the-chectl-management-tool.adoc[] +** xref:installing-che-on-openshift-4-using-cli.adoc[] +** xref:installing-che-locally.adoc[] +*** xref:installing-che-on-codeready-containers.adoc[] +*** xref:installing-che-on-minikube.adoc[] +** xref:installing-che-in-a-restricted-environment.adoc[] +*** xref:preparing-a-restricted-environment.adoc[] +*** xref:configuring-che-to-run-in-a-restricted-environment.adoc[] +* xref:configuring-che.adoc[] +** xref:understanding-the-checluster-custom-resource.adoc[] +*** xref:using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc[] +*** xref:using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc[] +*** xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] +*** xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +*** xref:checluster-custom-resource-fields-reference.adoc[] +** xref:configuring-server-components.adoc[] +*** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[] +*** xref:advanced-configuration-options-for-the-che-server-component.adoc[] +** xref:configuring-workspaces-globally.adoc[] +*** xref:configuring-the-number-of-workspaces-that-a-user-can-create.adoc[] +*** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] +*** xref:configuring-namespace-strategies.adoc[] +*** xref:configuring-workspaces-nodeselector.adoc[] +** xref:caching-images-for-faster-workspace-start.adoc[] +*** xref:defining-the-list-of-images-to-pull.adoc[] +*** xref:defining-the-memory-parameters-for-the-image-puller.adoc[] +*** xref:installing-image-puller-on-openshift-using-operatorhub.adoc[] +*** xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[] +** xref:configuring-observability.adoc[] +*** xref:che-theia-workspaces.adoc[] +**** xref:the-woopra-telemetry-plugin.adoc[] +**** xref:creating-a-telemetry-plugin.adoc[] +*** xref:configuring-server-logging.adoc[] +*** xref:collecting-logs-using-chectl.adoc[] +*** xref:monitoring-che.adoc[] +*** xref:monitoring-the-dev-workspace-operator.adoc[] +** xref:configuring-networking.adoc[] +*** xref:configuring-che-hostname.adoc[] +*** xref:importing-untrusted-tls-certificates.adoc[] +*** xref:configuring-ingresses.adoc[] +*** xref:configuring-routes.adoc[] +** xref:configuring-storage.adoc[] +*** xref:installing-che-using-storage-classes.adoc[] +** xref:branding.adoc[] +*** xref:branding-che-theia.adoc[] +** xref:managing-identities-and-authorizations.adoc[] +*** xref:oauth-for-github-gitlab-or-bitbucket.adoc[] +**** xref:configuring-oauth-2-for-github.adoc[] +**** xref:configuring-oauth-2-for-gitlab.adoc[] +**** xref:configuring-oauth-1-for-bitbucket.adoc[] +*** xref:removing-user-data.adoc[] +* xref:upgrading-che.adoc[] +** xref:upgrading-che-7-41-on-openshift.adoc[] +** xref:upgrading-che-using-operatorhub.adoc[] +** xref:upgrading-che-using-the-cli-management-tool.adoc[] +** xref:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc[] +* xref:uninstalling-che.adoc[] +** xref:uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc[] +** xref:uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc[] +** xref:uninstalling-che-after-chectl-installation.adoc[] diff --git a/modules/installation-guide/partials/assembly_advanced-configuration-options-for-the-che-server-component.adoc b/modules/administration-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc similarity index 63% rename from modules/installation-guide/partials/assembly_advanced-configuration-options-for-the-che-server-component.adoc rename to modules/administration-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc index 2f84a6aaf4..399f0c0716 100644 --- a/modules/installation-guide/partials/assembly_advanced-configuration-options-for-the-che-server-component.adoc +++ b/modules/administration-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc @@ -1,27 +1,19 @@ +:_content-type: ASSEMBLY +:navtitle: Advanced configuration options for {prod-short} server +:keywords: administration guide, configuring, configuration, {prod-short} server +:page-aliases: installation-guide:advanced-configuration-options-for-the-che-server-component, installation-guide:configuring-system-variables :parent-context-of-advanced-configuration-options-for-the-che-server-component: {context} - [id="advanced-configuration-options-for-the-{prod-id-short}-server-component_{context}"] = Advanced configuration options for the {prod-short} server component :context: advanced-configuration-options-for-the-che-server-component - The following section describes advanced deployment and configuration methods for the {prod-short} server component. -include::partial$con_understanding-che-server-advanced-configuration-using-the-operator.adoc[leveloffset=+1] - - -ifeval::["{project-context}" == "che"] -include::partial$con_understanding-che-server-advanced-configuration-not-using-the-operator.adoc[leveloffset=+1] -endif::[] - +include::partial$con_understanding-che-server-advanced-configuration.adoc[leveloffset=+1] include::partial$ref_che-server-component-system-properties-reference.adoc[leveloffset=+1] -.Additional resources - -* xref:administration-guide:configuring-authorization.adoc#configuring-che-to-use-external-keycloak_{context}[Configuring Che to use an external Keycloak installation] - :context: {parent-context-of-advanced-configuration-options-for-the-che-server-component} diff --git a/modules/administration-guide/pages/architecture-overview-with-che-server.adoc b/modules/administration-guide/pages/architecture-overview-with-che-server.adoc deleted file mode 100644 index d75ce5cfa1..0000000000 --- a/modules/administration-guide/pages/architecture-overview-with-che-server.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="che-architecture-overview-with-che-server"] -// = Che architecture with Che server as workspace engine -:navtitle: Che server based -:keywords: administration-guide, che-architecture-overview -:page-aliases: .:che-architecture-overview-with-che-server, .:high-level-che-architecture-with-che-server, overview:high-level-che-architecture-with-che-server, administration-guide:high-level-che-architecture-with-che-server -include::partial$con_architecture-overview-with-che-server.adoc[] diff --git a/modules/administration-guide/pages/architecture-overview-with-devworkspace.adoc b/modules/administration-guide/pages/architecture-overview-with-devworkspace.adoc deleted file mode 100644 index 1225376596..0000000000 --- a/modules/administration-guide/pages/architecture-overview-with-devworkspace.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-architecture-overview-with-devworkspace"] -// = Che architecture with {devworkspace} -:navtitle: {devworkspace} based -:keywords: administration-guide, che-architecture-overview, devworkspace -:page-aliases: .:che-architecture-overview-with-devworkspace, .:high-level-che-architecture-with-devworkspace, overview:high-level-che-architecture-with-devworkspace, administration-guide:high-level-che-architecture-with-devworkspace - -include::partial$con_architecture-overview-with-devworkspace.adoc[] diff --git a/modules/administration-guide/pages/architecture-overview.adoc b/modules/administration-guide/pages/architecture-overview.adoc index 98a2638921..2853614d63 100644 --- a/modules/administration-guide/pages/architecture-overview.adoc +++ b/modules/administration-guide/pages/architecture-overview.adoc @@ -1,7 +1,39 @@ -[id="che-architecture-overview"] -// = Che architecture overview -:navtitle: Architecture overview -:keywords: administration-guide, che-architecture-overview -:page-aliases: .:che-architecture-overview, .:high-level-che-architecture, overview:high-level-che-architecture, administration-guide:high-level-che-architecture, che-architecture-overview +:_content-type: CONCEPT +:navtitle: Architecture +:keywords: administration-guide, architecture +:page-aliases: .:che-architecture-overview, .:high-level-che-architecture, overview:high-level-che-architecture, administration-guide:high-level-che-architecture, che-architecture-overview, .:che-architecture-overview-with-che-server, .:high-level-che-architecture-with-che-server, overview:high-level-che-architecture-with-che-server, administration-guide:high-level-che-architecture-with-che-server, .:che-architecture-overview-with-devworkspace, .:high-level-che-architecture-with-devworkspace, overview:high-level-che-architecture-with-devworkspace, administration-guide:high-level-che-architecture-with-devworkspace, architecture-overview-with-devworkspace, architecture-overview-with-che-server, server-components-with-che-server, che-workspaces-architecture-with-che-server, backup-and-recovery, supported-restic-compatible-backup-servers, backing-up-of-che-instances-to-an-sftp-backup-server, backing-up-of-che-instances-to-amazon-s3, backing-up-of-che-instances-to-a-rest-backup-server, backing-up-of-che-instances-to-the-internal-backup-server, restoring-a-che-instance-from-a-backup, backups-of-persistent-volumes, backups-of-postgresql, migration-from-postgresql-9-to-postgresql-13, readiness-init-containers, enabling-and-disabling-readiness-init-containers-for-the-operator-installer, enabling-readiness-init-containers-for-the-operator-installer, disabling-readiness-init-containers-for-the-operator-installer, enabling-and-disabling-readiness-init-containers-for-the-olm-installer, enabling-readiness-init-containers-for-the-olm-installer, disabling-readiness-init-containers-for-the-olm-installer, overview:architecture-overview, overview:che-architecture + +[id="architecture_{context}"] += {prod-short} architecture + +.High-level {prod-short} architecture with the {devworkspace} operator +image::architecture/che-interacting-with-devworkspace.png[] + +{prod-short} runs on three groups of components: + +{prod-short} server components:: +Manage User {orch-namespace} and workspaces. The main component is the User dashboard, from which users control their workspaces. + +{devworkspace} operator:: +Creates and controls the necessary {orch-name} objects to run User workspaces. Including `Pods`, `Services`, and `PeristentVolumes`. + +User workspaces:: +Container-based development environments, the IDE included. + +The role of these {orch-name} features is central: + +{devworkspace} Custom Resources:: +Valid {orch-name} objects representing the User workspaces and manipulated by {prod-short}. It is the communication channel for the three groups of components. + +{orch-name} role-based access control (RBAC):: +Controls access to all resources. + +.Additional resources + +* xref:server-components.adoc[] +* xref:devworkspace-operator.adoc[] +* xref:user-workspaces.adoc[] +* link:https://github.com/devfile/devworkspace-operator[{devworkspace} Operator repository] + +include::example$snip_che-architecture-overview-with-devworkspace-additional-resources.adoc[] -include::partial$con_architecture-overview.adoc[] diff --git a/modules/administration-guide/pages/authenticating-users.adoc b/modules/administration-guide/pages/authenticating-users.adoc deleted file mode 100644 index 680522e367..0000000000 --- a/modules/administration-guide/pages/authenticating-users.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authenticating-users"] -// = Authenticating users -:navtitle: Authenticating users -:keywords: administration-guide, authenticating-users -:page-aliases: .:authenticating-users - -include::partial$assembly_authenticating-users.adoc[] diff --git a/modules/administration-guide/pages/authorizing-users.adoc b/modules/administration-guide/pages/authorizing-users.adoc deleted file mode 100644 index 3ed331452d..0000000000 --- a/modules/administration-guide/pages/authorizing-users.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authorizing-users"] -// = Authorizing users -:navtitle: Authorizing users -:keywords: administration-guide, authorizing-users -:page-aliases: .:authorizing-users - -include::partial$assembly_authorizing-users.adoc[] diff --git a/modules/administration-guide/pages/backup-and-disaster-recovery.adoc b/modules/administration-guide/pages/backup-and-disaster-recovery.adoc deleted file mode 100644 index 412b4709b3..0000000000 --- a/modules/administration-guide/pages/backup-and-disaster-recovery.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="backup-and-disaster-recovery"] -// = Backup and disaster recovery -:navtitle: Backup and disaster recovery -:keywords: administration-guide, backup-and-disaster-recovery -:page-aliases: .:backup-and-disaster-recovery - -include::partial$assembly_backup-and-disaster-recovery.adoc[] diff --git a/modules/contributor-guide/partials/assembly_branding-che-theia.adoc b/modules/administration-guide/pages/branding-che-theia.adoc similarity index 86% rename from modules/contributor-guide/partials/assembly_branding-che-theia.adoc rename to modules/administration-guide/pages/branding-che-theia.adoc index c41e0e426f..6a2533511c 100644 --- a/modules/contributor-guide/partials/assembly_branding-che-theia.adoc +++ b/modules/administration-guide/pages/branding-che-theia.adoc @@ -1,5 +1,7 @@ - - +:_content-type: PROCEDURE +:navtitle: Branding Che-Theia +:keywords: contributor-guide, branding-che-theia +:page-aliases: contributor-guide:branding-che-theia :parent-context-of-branding-che-theia: {context} [id="branding-che-theia_{context}"] diff --git a/modules/administration-guide/pages/branding.adoc b/modules/administration-guide/pages/branding.adoc new file mode 100644 index 0000000000..764a0b5055 --- /dev/null +++ b/modules/administration-guide/pages/branding.adoc @@ -0,0 +1,9 @@ +:_content-type: ASSEMBLY +:navtitle: Branding +:keywords: administration-guide, branding +:page-aliases: + +[id="branding_{context}"] += Branding + +* xref:branding-che-theia.adoc[] diff --git a/modules/administration-guide/pages/building-custom-registry-images.adoc b/modules/administration-guide/pages/building-custom-registry-images.adoc deleted file mode 100644 index 9903fdd06a..0000000000 --- a/modules/administration-guide/pages/building-custom-registry-images.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="building-custom-registry-images"] -// = Customizing custom registry images -:navtitle: Building custom registry images -:keywords: contributor-guide, customizing-the-devfile-and-plug-in-registries, building-and-running-a-custom-devfile-registry-image -:page-aliases: .:building-and-running-a-custom-devfile-registry-image, contributor-guide:building-and-running-a-custom-devfile-registry-image, .:building-and-running-a-custom-plugin-registry-image, contributor-guide:building-and-running-a-custom-plugin-registry-image, administration-guide:including-the-plug-in-binaries-in-the-registry-image - -include::partial$assembly_building-custom-registry-images.adoc[] - diff --git a/modules/administration-guide/pages/caching-images-for-faster-workspace-start.adoc b/modules/administration-guide/pages/caching-images-for-faster-workspace-start.adoc index 87927ee2ba..42b8a7240f 100644 --- a/modules/administration-guide/pages/caching-images-for-faster-workspace-start.adoc +++ b/modules/administration-guide/pages/caching-images-for-faster-workspace-start.adoc @@ -1,7 +1,79 @@ -[id="caching-images-for-faster-workspace-start"] -// = Caching images for faster workspace start +:_content-type: REFERENCE :navtitle: Caching images for faster workspace start :keywords: administration-guide, caching-images-for-faster-workspace-start :page-aliases: .:caching-images-for-faster-workspace-start -include::partial$con_caching-images-for-faster-workspace-start.adoc[] + +[id="caching-images-for-faster-workspace-start_{context}"] += Caching images for faster workspace start + +To improve the start time performance of {prod-short} workspaces, use the {image-puller-name-short}, a {prod-short}-agnostic component that can be used to pre-pull images for {platforms-name} clusters. The {image-puller-name-short} is an additional {platforms-name} deployment which creates a _DaemonSet_ that can be configured to pre-pull relevant {prod-short} workspace images on each node. These images would already be available when a {prod-short} workspace starts, therefore improving the workspace start time. + +The {image-puller-name-short} provides the following parameters for configuration. + +[id="image-puller-configuration_{context}"] +.{image-puller-name-short} parameters +[options="header"] +|=== +|Parameter |Usage |Default + +|`CACHING_INTERVAL_HOURS` + +|DaemonSets health checks interval in hours +|`"1"` + +|`CACHING_MEMORY_REQUEST` +|The memory request for each cached image when the puller is running. See xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. +|`10Mi` + +|`CACHING_MEMORY_LIMIT` +|The memory limit for each cached image when the puller is running. See xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. +|`20Mi` + +|`CACHING_CPU_REQUEST` +|The processor request for each cached image when the puller is running +|`.05` or 50 millicores + +|`CACHING_CPU_LIMIT` +|The processor limit for each cached image when the puller is running +|`.2` or 200 millicores + +|`DAEMONSET_NAME` +|Name of DaemonSet to create +|`{image-puller-deployment-name}` + +|`DEPLOYMENT_NAME` +|Name of the Deployment to create +|`{image-puller-deployment-name}` + +|`NAMESPACE` +|{platforms-namespace} containing DaemonSet to create +|`k8s-image-puller` + +|`IMAGES` +|Semicolon separated list of images to pull, in the format `__<name1>__=__<image1>__;__<name2>__=__<image2>__` See xref:defining-the-list-of-images-to-pull.adoc[]. +| + +|`NODE_SELECTOR` +|Node selector to apply to the Pods created by the DaemonSet +|`'{}'` + +| `AFFINITY` +| Affinity applied to pods created by the DaemonSet +| `'{}'` + +|`IMAGE_PULL_SECRETS` +| List of image pull secrets, in the format `pullsecret1;...` to add to pods created by the DaemonSet. Those secrets need to be in the image puller's namespace and a cluster administrator must create them. +| `""` +|=== + + +.Additional resources + +* xref:defining-the-list-of-images-to-pull.adoc[] +* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. +* xref:installing-image-puller-on-openshift-using-operatorhub.adoc[] +* xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[] + +* link:https://github.com/che-incubator/{image-puller-repository-name}[{image-puller-name} source code repository] + diff --git a/modules/administration-guide/pages/calculating-che-resource-requirements.adoc b/modules/administration-guide/pages/calculating-che-resource-requirements.adoc index a4c2bdd680..2a071cb3ee 100644 --- a/modules/administration-guide/pages/calculating-che-resource-requirements.adoc +++ b/modules/administration-guide/pages/calculating-che-resource-requirements.adoc @@ -1,7 +1,32 @@ -[id="calculating-che-resource-requirements"] -// = Calculating Che resource requirements +:_content-type: ASSEMBLY :navtitle: Calculating Che resource requirements :keywords: administration-guide, calculating-che-resource-requirements :page-aliases: .:calculating-che-resource-requirements -include::partial$assembly_calculating-che-resource-requirements.adoc[] +:parent-context-of-calculating-che-resource-requirements: {context} + +[id="calculating-{prod-id-short}-resource-requirements_{context}"] += Calculating {prod-short} resource requirements + +:context: calculating-{prod-id-short}-resource-requirements + +This section describes how to calculate resources, such as memory and CPU, required to run {prod}. + +The {prod-short} Operator, {devworkspace} Controller, and user workspaces consist of a set of pods. Those pods contribute to the resource consumption in terms of CPU and RAM limits and requests. + +include::partial$con_operator-requirements.adoc[leveloffset=+1] + +include::partial$con_controller-requirements.adoc[leveloffset=+1] + +include::partial$proc_workspaces-requirements.adoc[leveloffset=+1] + +include::partial$con_a-workspace-example.adoc[leveloffset=+1] + +.Additional resources + +* xref:architecture-overview.adoc[] +* xref:understanding-the-checluster-custom-resource.adoc[] +* link:https://github.com/eclipse-che/che-plugin-registry[{prod-short} plug-ins registry repository] +* {link-manage-compute-resources-container} + +:context: {parent-context-of-calculating-che-resource-requirements} diff --git a/modules/administration-guide/pages/che-operator.adoc b/modules/administration-guide/pages/che-operator.adoc index 73e4dece92..3d7698aa92 100644 --- a/modules/administration-guide/pages/che-operator.adoc +++ b/modules/administration-guide/pages/che-operator.adoc @@ -1,6 +1,33 @@ -[id="{prod-id-short}-operator"] +:_content-type: ASSEMBLY :navtitle: {prod-short} operator :keywords: administration-guide, architecture, operator -// :page-aliases: +:page-aliases: -include::partial$con_che-operator.adoc[] +[id="{prod-id-short}-operator_{context}"] += {prod-short} operator + +The {prod-short} operator ensure full lifecycle management of the {prod-short} server components. +It introduces: + +`CheCluster` custom resource definition (CRD):: +Defines the `CheCluster` {orch-name} object. + +{prod-short} controller:: + +Creates and controls the necessary {orch-name} objects to run a {prod-short} instance, such as pods, services, and persistent volumes. + +`CheCluster` custom resource (CR):: +On a cluster with the {prod-short} operator, it is possible to create a `CheCluster` custom resource (CR). The {prod-short} operator ensures the full lifecycle management of the {prod-short} server components on this {prod-short} instance: ++ +* xref:devworkspace-operator.adoc[] +* xref:gateway.adoc[] +* xref:dashboard.adoc[] +* xref:devfile-registries.adoc[] +* xref:che-server.adoc[] +* xref:postgresql.adoc[] +* xref:plug-in-registry.adoc[] + +.Additional resources + +* xref:understanding-the-checluster-custom-resource.adoc[] +* xref:installing-che.adoc[] diff --git a/modules/administration-guide/pages/che-server.adoc b/modules/administration-guide/pages/che-server.adoc index 43b7c535aa..dfbeafbaa5 100644 --- a/modules/administration-guide/pages/che-server.adoc +++ b/modules/administration-guide/pages/che-server.adoc @@ -1,6 +1,30 @@ -[id="{prod-id-short}-server"] +:_content-type: ASSEMBLY :navtitle: {prod-short} server :keywords: administration-guide, architecture, server, devworkspace -// :page-aliases: +:page-aliases: + +[id="{prod-id-short}-server-with-devworkspace_{context}"] += {prod-short} server + + +The {prod-short} server main functions are: + +* Creating user namespaces. +* Provisioning user namespaces with required secrets and config maps. +* Integrating with Git services providers, to fetch and validate devfiles and authentication. + +The {prod-short} server is a Java web service exposing an HTTP REST API and needs access to: + +* xref:postgresql.adoc[] +* Git service providers +* {orch-name} API + +.{prod-short} server interactions with other components +image::architecture/{project-context}-server-interactions.png[{prod-short} server interactions with other components] + +.Additional resources + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[] + +include::example$snip_{project-context}-che-server-additional-resources.adoc[] -include::partial$con_che-server-with-devworkspace.adoc[] diff --git a/modules/administration-guide/pages/che-theia-workspaces.adoc b/modules/administration-guide/pages/che-theia-workspaces.adoc new file mode 100644 index 0000000000..4893de1c9d --- /dev/null +++ b/modules/administration-guide/pages/che-theia-workspaces.adoc @@ -0,0 +1,45 @@ +[id="che-theia-workspaces"] +// = Che-Theia workspaces +:_content-type: CONCEPT +:navtitle: Che-Theia workspaces +:keywords: che-theia, workspaces +:page-aliases: extensions:che-theia-workspaces + += Che-Theia workspaces + +[id="telemetry-overview_{context}"] +== Telemetry overview +:context: telemetry-overview + +Telemetry is the explicit and ethical collection of operation data. By default, telemetry is not available in {prod}, but in the Che-Theia editor there is an abstract API that allows enabling telemetry using the plug-in mechanism and in the `chectl` command line tool usage data can be collected using segment. This approach is used in the {hosted-che-docs} service where telemetry is enabled for every Che-Theia workspace. + +This documentation includes a guide describing how to make your own telemetry client for {prod}, followed by an overview of the link:https://github.com/che-incubator/che-workspace-telemetry-woopra-plugin[{prod} Woopra Telemetry Plugin]. + +== Use cases +[id="use-cases_{context}"] + +{prod} telemetry API allows tracking: + +* Duration of a workspace utilization +* User-driven actions such as file editing, committing, and pushing to remote repositories. +* Programming languages and devfiles used in workspaces. + +== How it works +[id="how-it-works_{context}"] + +When a {devworkspace} starts, the `che-theia` container starts the telemetry plug-in which is responsible for sending telemetry events to a backend. If the `$DEVWORKSPACE_TELEMETRY_BACKEND_PORT` environment variable is set in the {devworkspace} Pod, the telemetry plug-in sends events to a backend listening at that port. The backend turns received events into a backend-specific representation of the events and sends them to the configured analytics backend (for example, Segment or Woopra). + +image::telemetry/telemetry_diagram.png[] + +== Events sent to the backend by the Che-Theia telemetry plug-in + +[cols="2,5", options="header"] +:=== + Event: Description +WORKSPACE_OPENED: Sent when Che-Theia starts running +COMMIT_LOCALLY: Sent when a commit was made locally with the `git.commit` Theia command +PUSH_TO_REMOTE: Sent when a Git push was made with the `git.push` Theia command +EDITOR_USED: Sent when a file was changed within the editor +:=== + +Other events such as `WORKSPACE_INACTIVE` and `WORKSPACE_STOPPED` can be detected within the back-end plug-in. diff --git a/modules/administration-guide/pages/che-workspaces-architecture-with-che-server.adoc b/modules/administration-guide/pages/che-workspaces-architecture-with-che-server.adoc deleted file mode 100644 index 1f3b20030a..0000000000 --- a/modules/administration-guide/pages/che-workspaces-architecture-with-che-server.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-workspaces-architecture-with-che-server"] -// = Che workspaces architecture -:navtitle: Workspace side components -:keywords: administration-guide, che-workspaces-architecture, che-server -:page-aliases: .:che-workspaces-architecture-with-che-server, .:che-workspaces-architecture, che-workspaces-architecture - -include::partial$assembly_understanding-che-workspaces-architecture-with-che-server.adoc[] diff --git a/modules/installation-guide/partials/ref_checluster-custom-resource-fields-reference.adoc b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc similarity index 81% rename from modules/installation-guide/partials/ref_checluster-custom-resource-fields-reference.adoc rename to modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc index 5260eb7197..c2e60f0d25 100644 --- a/modules/installation-guide/partials/ref_checluster-custom-resource-fields-reference.adoc +++ b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc @@ -1,6 +1,7 @@ -// Module included in the following assemblies: -// -// configuring-the-{prod-id-short}-installation +:_content-type: ASSEMBLY +:navtitle: `CheCluster` Custom Resource fields reference +:keywords: administration guide, checluster, custom resource +:page-aliases: installation-guide:checluster-custom-resource-fields-reference [id="checluster-custom-resources-fields-reference_{context}"] = `CheCluster` Custom Resource fields reference diff --git a/modules/administration-guide/pages/collecting-logs-using-chectl.adoc b/modules/administration-guide/pages/collecting-logs-using-chectl.adoc index 2876f5a86f..70ba8882e4 100644 --- a/modules/administration-guide/pages/collecting-logs-using-chectl.adoc +++ b/modules/administration-guide/pages/collecting-logs-using-chectl.adoc @@ -1,7 +1,41 @@ -[id="collecting-logs-using-chectl"] -// = Collecting logs using chectl -:navtitle: Collecting logs using chectl +:_content-type: REFERENCE +:navtitle: Collecting logs using {prod-cli} :keywords: administration-guide, collecting-logs-using-chectl :page-aliases: .:collecting-logs-using-chectl -include::partial$assembly_collecting-logs-using-chectl.adoc[] +[id="collecting-logs-using-{prod-cli}_{context}"] += Collecting logs using {prod-cli} + +An installation of {prod} consists of several containers running in the {orch-name} cluster. While it is possible to manually collect logs from each running container, `{prod-cli}` provides commands which automate the process. + +Following commands are available to collect {prod} logs from the {orch-name} cluster using the `{prod-cli}` tool: + +`{prod-cli} server:logs`:: +Collects existing {prod} server logs and stores them in a directory on the local machine. By default, logs are downloaded to a temporary directory on the machine. However, this can be overwritten by specifying the `-d` parameter. For example, to download Che logs to the `/home/user/che-logs/` directory, use the command ++ +[source,shell,subs="+attributes"] +---- +{prod-cli} server:logs -d /home/user/che-logs/ +---- ++ +When run, `{prod-cli} server:logs` prints a message in the console specifying the directory that will store the log files: ++ +[subs="+attributes"] +---- +{prod} logs will be available in '/tmp/chectl-logs/1648575098344' +---- ++ +If {prod} is installed in a non-default {orch-namespace}, `{prod-cli} server:logs` requires the `-n <NAMESPACE>` paremeter, where `<NAMESPACE>` is the {platforms-namespace} in which {prod} was installed. For example, to get logs from {prod-short} in the `my-namespace` {orch-namespace}, use the command ++ +[source,shell,subs="+attributes"] +---- +{prod-cli} server:logs -n my-namespace +---- + +`{prod-cli} server:deploy`:: +Logs are automatically collected during the {prod-short} installation when installed using `{prod-cli}`. As with `{prod-cli} server:logs`, the directory logs are stored in can be specified using the `-d` parameter. + +.Additional resources + +* {link-prod-cli-documentation} + diff --git a/modules/administration-guide/pages/configuring-authorization.adoc b/modules/administration-guide/pages/configuring-authorization.adoc deleted file mode 100644 index c28a40f3c7..0000000000 --- a/modules/administration-guide/pages/configuring-authorization.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-authorization"] -// = Configuring authorization -:navtitle: Configuring authorization -:keywords: administration-guide, configuring-authorization -:page-aliases: .:configuring-authorization - -include::partial$assembly_configuring-authorization.adoc[] diff --git a/modules/installation-guide/partials/proc_configuring-che-hostname.adoc b/modules/administration-guide/pages/configuring-che-hostname.adoc similarity index 75% rename from modules/installation-guide/partials/proc_configuring-che-hostname.adoc rename to modules/administration-guide/pages/configuring-che-hostname.adoc index 786373c2b3..2505de953a 100644 --- a/modules/installation-guide/partials/proc_configuring-che-hostname.adoc +++ b/modules/administration-guide/pages/configuring-che-hostname.adoc @@ -1,11 +1,12 @@ -:parent-context-of-customize-chehost: {context} +:_content-type: PROCEDURE +:navtitle: Configuring {prod-short} hostname +:keywords: administration guide, configuring, {prod}, {prod-short}, hostname +:page-aliases: installation-guide:configuring-che-hostname -[id="customize-chehost_{context}"] -= Configuring {prod} server host name +[id="configuring-{prod-id-short}-server-hostname_{context}"] += Configuring {prod} server hostname -:context: customize-chehost - -This procedure describes how to configure {prod-short} to use custom host name. +This procedure describes how to configure {prod-short} to use custom hostname. .Prerequisites @@ -14,7 +15,7 @@ This procedure describes how to configure {prod-short} to use custom host name. IMPORTANT: To generate the pair of a private key and certificate, the same certification authority (CA) must be used as for other {prod-short} hosts. -IMPORTANT: Ask a DNS provider to point the custom host name to the cluster ingress. +IMPORTANT: Ask a DNS provider to point the custom hostname to the cluster ingress. .Procedure @@ -56,9 +57,7 @@ spec: cheHost: <hostname> <1> cheHostTLSSecret: <secret> <2> ---- -<1> Custom {prod} server host name +<1> Custom {prod} server hostname <2> The TLS secret name . If {prod-short} has been already deployed, wait until the rollout of all {prod-short} components finishes. - -:context: {parent-context-of-customize-chehost} diff --git a/modules/administration-guide/pages/configuring-che-to-run-in-a-restricted-environment.adoc b/modules/administration-guide/pages/configuring-che-to-run-in-a-restricted-environment.adoc new file mode 100644 index 0000000000..839ebbcb7f --- /dev/null +++ b/modules/administration-guide/pages/configuring-che-to-run-in-a-restricted-environment.adoc @@ -0,0 +1,12 @@ +:_content-type: ASSEMBLY +:navtitle: Configuring {prod-short} to run in a restricted environment +:keywords: administration guide, configuring, restricted environment +:page-aliases: +:parent-context-of-installing-che-in-a-restricted-environment: {context} + +[id="configuring-{prod-id-short}-to-run-in-a-restricted-environment_{context}"] += Configuring {prod-short} to run in a restricted environment + +include::example$proc_{project-context}-configuring-che-to-run-in-a-restricted-environment.adoc[leveloffset=+1] + +:context: {parent-context-of-installing-che-in-a-restricted-environment} diff --git a/modules/administration-guide/pages/configuring-che.adoc b/modules/administration-guide/pages/configuring-che.adoc new file mode 100644 index 0000000000..4d56ed6d3e --- /dev/null +++ b/modules/administration-guide/pages/configuring-che.adoc @@ -0,0 +1,34 @@ +:_content-type: ASSEMBLY +:navtitle: Configuring {prod-short} +:keywords: administration guide, configuring, configuration +:page-aliases: installation-guide:configuring-che, installation-guide:advanced-configuration, installation-guide:advanced-configuration-options, installation-guide:setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page, installation-guide:configuring-communication-between-che-components, installation-guide:configuring-storage-strategies, installation-guide:configuring-storage-types, installation-guide:configuring-the-number-of-workspaces-that-a-user-can-run, installation-guide:configuring-workspace-exposure-strategies, installation-guide:enabling-dev-workspace-operator, running-custom-registries, building-custom-registry-images, customizing-the-registries, advanced-configuration + +[id="configuring-che_{context}"] += Configuring {prod-short} + +The following chapter describes configuration methods and options for {prod}. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[] describes advanced configuration methods to use when the previous method is not applicable. + +Specific use-cases: + +* xref:configuring-namespace-strategies.adoc[] + +* xref:configuring-the-number-of-workspaces-that-a-user-can-create.adoc[] + +* xref:configuring-workspaces-nodeselector.adoc[] + +* xref:configuring-che-hostname.adoc[] + +* xref:configuring-ingresses.adoc[] + +* xref:configuring-routes.adoc[] + +* xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] + +* xref:installing-che-using-storage-classes.adoc[] + +* xref:importing-untrusted-tls-certificates.adoc[] + +* xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[] + diff --git a/modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc b/modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc deleted file mode 100644 index 342f0ddc52..0000000000 --- a/modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-chectl-to-use-backup-server"] -// = Configuring chectl to use a backup server -:navtitle: Configuring chectl to use a backup server -:keywords: administration-guide, backup, recovery, cli, chectl -:page-aliases: .:configure-chectl-to-use-backup-server - -include::partial$proc_configuring-chectl-to-use-backup-server.adoc[] diff --git a/modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc b/modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc deleted file mode 100644 index 8eb95ee0b5..0000000000 --- a/modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-cli-to-use-backup-server"] -// = Managing backups through CLI -:navtitle: Configuring CLI to use a backup server -:keywords: administration-guide, backup, recovery, cli -:page-aliases: .:configure-cli-to-use-backup-server - -include::partial$proc_configuring-cli-to-use-backup-server.adoc[] diff --git a/modules/installation-guide/partials/proc_configuring-ingresses.adoc b/modules/administration-guide/pages/configuring-ingresses.adoc similarity index 88% rename from modules/installation-guide/partials/proc_configuring-ingresses.adoc rename to modules/administration-guide/pages/configuring-ingresses.adoc index 728b393a3d..5edae478a9 100644 --- a/modules/installation-guide/partials/proc_configuring-ingresses.adoc +++ b/modules/administration-guide/pages/configuring-ingresses.adoc @@ -1,8 +1,12 @@ +:_content-type: PROCEDURE +:navtitle: Configuring {orch-ingress} +:keywords: administration guide, configuring, ingress, ingresses +:page-aliases: installation-guide:configuring-ingresses -[id="configuring-ingresses_{context}"] -= Configuring {orch-ingress} +[id="adding-labels-and-annotations-to-ingresses_{context}"] += Adding labels and annotations to {orch-ingress} -By configuring labels and annotations for {orch-ingress} you can organize and categorize objects by scoping and selecting. +Some organizations require labels and annotations on each{orch-ingress}. This procedure describes how to configure labels and annotations. .Prerequisites diff --git a/modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc b/modules/administration-guide/pages/configuring-namespace-strategies.adoc similarity index 89% rename from modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc rename to modules/administration-guide/pages/configuring-namespace-strategies.adoc index 679016d199..edf8f38e0a 100644 --- a/modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc +++ b/modules/administration-guide/pages/configuring-namespace-strategies.adoc @@ -1,14 +1,14 @@ +:_content-type: CONCEPT +:navtitle: Configuring workspace target {orch-namespace} +:keywords: administration guide, configuring, namespace +:page-aliases: installation-guide:configuring-namespace-strategies [id="configuring-namespace-strategies_{context}"] = Configuring workspace target {orch-namespace} The {platforms-namespace} where a new workspace is deployed depends on the {prod-short} server configuration. {prod-short} deploys each workspace into a user's dedicated {orch-namespace}, which hosts all {prod-short} workspaces created by the user. The name of a {platforms-namespace} must be provided as a {prod-short} server configuration property or pre-created by {prod-short} administrator. -ifeval::["{project-context}" == "che"] -NOTE: The term _{orch-namespace}_ ({kubernetes}) is used interchangeably with _project_ (OpenShift). -endif::[] - -{platforms-namespace} strategies are configured using `server.workspaceNamespaceDefault` property. +{platforms-namespace} names are configured using `server.workspaceNamespaceDefault` property. *Operator CheCluster CR patch* [subs="+quotes,+attributes"] @@ -26,7 +26,7 @@ spec: NOTE: The underlying environment variable that {prod-short} server uses is `CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT`. -WARNING: By default, only one workspace in the same {orch-namespace} can be running at one time. See xref:configuring-the-number-of-workspaces-that-a-user-can-run.adoc[]. +WARNING: Only one workspace in the same {orch-namespace} can be running at one time. [WARNING] ==== @@ -91,7 +91,7 @@ metadata: ---- <1> target user's username -To configure the labels, set the `CHE_INFRA_KUBERNETES_NAMESPACE_LABELS` to desired labels. To configure the annotations, set the `CHE_INFRA_KUBERNETES_NAMESPACE_ANNOTATIONS` to desired annotations. See the xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc#{prod-id-short}-server-component-system-properties-reference_{context}[{prod-short} server component system properties reference] for more details. +To configure the labels, set the `CHE_INFRA_KUBERNETES_NAMESPACE_LABELS` to desired labels. To configure the annotations, set the `CHE_INFRA_KUBERNETES_NAMESPACE_ANNOTATIONS` to desired annotations. See the xref:advanced-configuration-options-for-the-che-server-component.adoc[] for more details. [WARNING] ==== diff --git a/modules/administration-guide/pages/configuring-networking.adoc b/modules/administration-guide/pages/configuring-networking.adoc new file mode 100644 index 0000000000..f671809668 --- /dev/null +++ b/modules/administration-guide/pages/configuring-networking.adoc @@ -0,0 +1,12 @@ +:_content-type: ASSEMBLY +:navtitle: Configuring networking +:keywords: administration-guide, configuring, networking +:page-aliases: + +[id="configuring-networking_{context}"] += Configuring networking + +* xref:configuring-che-hostname.adoc[] +* xref:importing-untrusted-tls-certificates.adoc[] +* xref:configuring-ingresses.adoc[] +* xref:configuring-routes.adoc[] diff --git a/modules/administration-guide/pages/configuring-oauth-1-for-bitbucket.adoc b/modules/administration-guide/pages/configuring-oauth-1-for-bitbucket.adoc new file mode 100644 index 0000000000..6c1ce26636 --- /dev/null +++ b/modules/administration-guide/pages/configuring-oauth-1-for-bitbucket.adoc @@ -0,0 +1,17 @@ +:_content-type: ASSEMBLY +:description: Configuring OAuth 1.0 for Bitbucket +:keywords: configuring-oauth, authorization, bitbucket, oauth-1, oauth-1.0 +:navtitle: Configuring OAuth 1.0 for Bitbucket +// :page-aliases: + +[id="configuring-oauth-1-for-bitbucket_{context}"] += Configuring OAuth 1.0 for Bitbucket + +To enable users to work with a remote Git repository that is hosted on a Bitbucket server: + +. Set up the Bitbucket application link (OAuth 1.0). +. Apply the Bitbucket application link Secret. + +include::partial$proc_setting-up-the-bitbucket-application-link.adoc[leveloffset=+1] + +include::partial$proc_applying-the-bitbucket-application-link-secret.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc b/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc new file mode 100644 index 0000000000..1b90b4c2b3 --- /dev/null +++ b/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc @@ -0,0 +1,17 @@ +:_content-type: ASSEMBLY +:description: Configuring OAuth 2.0 for GitHub +:keywords: configuring-oauth, authorization, github, oauth-2, oauth-2.0 +:navtitle: Configuring OAuth 2.0 for GitHub +// :page-aliases: + +[id="configuring-oauth-2-for-github_{context}"] += Configuring OAuth 2.0 for GitHub + +To enable users to work with a remote Git repository that is hosted on GitHub: + +. Set up the GitHub OAuth App (OAuth 2.0). +. Apply the GitHub OAuth App Secret. + +include::partial$proc_setting-up-the-github-oauth-app.adoc[leveloffset=+1] + +include::partial$proc_applying-the-github-oauth-app-secret.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/administration-guide/pages/configuring-oauth-2-for-gitlab.adoc b/modules/administration-guide/pages/configuring-oauth-2-for-gitlab.adoc new file mode 100644 index 0000000000..f9989fb159 --- /dev/null +++ b/modules/administration-guide/pages/configuring-oauth-2-for-gitlab.adoc @@ -0,0 +1,17 @@ +:_content-type: ASSEMBLY +:description: Configuring OAuth 2.0 for GitLab +:keywords: configuring-oauth, authorization, gitlab, oauth-2, oauth-2.0 +:navtitle: Configuring OAuth 2.0 for GitLab +// :page-aliases: + +[id="configuring-oauth-2-for-gitlab_{context}"] += Configuring OAuth 2.0 for GitLab + +To enable users to work with a remote Git repository that is hosted using a GitLab instance: + +. Set up the GitLab authorized application (OAuth 2.0). +. Apply the GitLab authorized application Secret. + +include::partial$proc_setting-up-the-gitlab-authorized-application.adoc[leveloffset=+1] + +include::partial$proc_applying-the-gitlab-authorized-application-secret.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/administration-guide/pages/configuring-observability.adoc b/modules/administration-guide/pages/configuring-observability.adoc new file mode 100644 index 0000000000..97b53771a2 --- /dev/null +++ b/modules/administration-guide/pages/configuring-observability.adoc @@ -0,0 +1,15 @@ +:_content-type: ASSEMBLY +:navtitle: Configuring observability +:keywords: administration-guide, configuring, observability, logs, monitoring +:page-aliases: .:retrieving-che-logs, .:viewing-kubernetes-events, viewing-kubernetes-events, .:viewing-plug-in-broker-logs, viewing-plug-in-broker-logs, retrieving-che-logs, viewing-che-server-logs, viewing-external-service-logs, + +[id="configuring-observability_{context}"] += Configuring observability + +To configure {prod-short} observability features, see: + +* xref:che-theia-workspaces.adoc[] +* xref:configuring-server-logging.adoc[] +* xref:collecting-logs-using-chectl.adoc[] +* xref:monitoring-che.adoc[] +* xref:monitoring-the-dev-workspace-operator.adoc[] diff --git a/modules/administration-guide/pages/configuring-openshift-oauth.adoc b/modules/administration-guide/pages/configuring-openshift-oauth.adoc deleted file mode 100644 index f234084068..0000000000 --- a/modules/administration-guide/pages/configuring-openshift-oauth.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-openshift-oauth"] -// = Configuring OpenShift OAuth -:navtitle: Configuring OpenShift OAuth -:keywords: end-user-guide, configuring-openshift-oauth -:page-aliases: .:configuring-openshift-oauth - -include::partial$proc_configuring-openshift-oauth.adoc[] diff --git a/modules/installation-guide/partials/proc_configuring-routes.adoc b/modules/administration-guide/pages/configuring-routes.adoc similarity index 96% rename from modules/installation-guide/partials/proc_configuring-routes.adoc rename to modules/administration-guide/pages/configuring-routes.adoc index ce11ef24c6..9ff2b8208b 100644 --- a/modules/installation-guide/partials/proc_configuring-routes.adoc +++ b/modules/administration-guide/pages/configuring-routes.adoc @@ -1,3 +1,7 @@ +:_content-type: PROCEDURE +:navtitle: Configuring OpenShift Route +:keywords: administration guide, configuring, routes +:page-aliases: installation-guide:configuring-routes [id="configuring-routes_{context}"] = Configuring OpenShift Route to work with Router Sharding @@ -12,7 +16,7 @@ This procedure describes how to configure labels, annotations, and domains for O * For a new OperatorHub installation: + -. Enter the {prod-short} Cluster using {ocp} and create CheCluster Custom Resource (CR). See, xref:installing-che-on-openshift-4-using-operatorhub#creating-an-instance-of-the-{prod-id-short}-operator_{context}[Creating an instance of the {prod} Operator] +. Enter the {prod-short} Cluster using {ocp} and create CheCluster Custom Resource (CR). See, xref:using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc[] + . Set the following values in {prod-checluster} Custom Resource (CR): @@ -247,8 +251,3 @@ $ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json '"value": __<annotations for a {identity-provider} ingress>__}]' ---- - - - - - diff --git a/modules/administration-guide/pages/configuring-server-components.adoc b/modules/administration-guide/pages/configuring-server-components.adoc new file mode 100644 index 0000000000..9fa28a9f56 --- /dev/null +++ b/modules/administration-guide/pages/configuring-server-components.adoc @@ -0,0 +1,9 @@ +:_content-type: ASSEMBLY +:navtitle: Configuring server components +:keywords: administration-guide, configuring, server components +:page-aliases: + +[id="configuring-server-components_{context}"] += Configuring server components + +* xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[] diff --git a/modules/administration-guide/pages/configuring-server-logging.adoc b/modules/administration-guide/pages/configuring-server-logging.adoc index c2d7e89d3e..018a865694 100644 --- a/modules/administration-guide/pages/configuring-server-logging.adoc +++ b/modules/administration-guide/pages/configuring-server-logging.adoc @@ -1,7 +1,22 @@ -[id=configuing-server-logging] -// = Configuring Server Logging +:_content-type: ASSEMBLY :navtitle: Configuring server logging :keywords: administration-guide, configuring-server-logging :page-aliases: .:configuring-server-logging -include::partial$assembly_configuring-server-logging.adoc[] +[id="configuring-sever-logging_{context}"] += Configuring server logging + +It is possible to fine-tune the log levels of individual loggers available in the {prod-short} server. + +The log level of the whole {prod-short} server is configured globally using the `cheLogLevel` configuration property of the Operator. See xref:checluster-custom-resource-fields-reference.adoc[]. +To set the global log level in installations not managed by the Operator, specify the `CHE_LOG_LEVEL` environment variable in the `che` +ConfigMap. + +It is possible to configure the log levels of the individual loggers in the {prod-short} server using the `CHE_LOGGER_CONFIG` environment +variable. + +include::partial$proc_configuring-server-logging.adoc[leveloffset=+1] + +include::partial$con_logger-naming.adoc[leveloffset=+1] + +include::partial$con_logging-http-traffic.adoc[leveloffset=+1] diff --git a/modules/administration-guide/pages/configuring-storage.adoc b/modules/administration-guide/pages/configuring-storage.adoc new file mode 100644 index 0000000000..2d402adc2f --- /dev/null +++ b/modules/administration-guide/pages/configuring-storage.adoc @@ -0,0 +1,9 @@ +:_content-type: ASSEMBLY +:navtitle: Configuring storage +:keywords: administration-guide, configuring, storage +:page-aliases: + +[id="configuring-storage_{context}"] += Configuring storage + +* xref:installing-che-using-storage-classes.adoc[] diff --git a/modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-create.adoc b/modules/administration-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-create.adoc similarity index 82% rename from modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-create.adoc rename to modules/administration-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-create.adoc index f29f3bec64..844f37359d 100644 --- a/modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-create.adoc +++ b/modules/administration-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-create.adoc @@ -1,3 +1,8 @@ +:_content-type: PROCEDURE +:navtitle: Configuring the number of workspaces that a user can create +:keywords: administration guide, number, workspaces +:page-aliases: installation-guide:configuring-the-number-of-workspaces-that-a-user-can-create + [id="configuring-the-number-of-workspaces-that-a-user-can-create_{context}"] = Configuring the number of workspaces that a user can create diff --git a/modules/administration-guide/pages/configuring-workspaces-globally.adoc b/modules/administration-guide/pages/configuring-workspaces-globally.adoc new file mode 100644 index 0000000000..b311685db2 --- /dev/null +++ b/modules/administration-guide/pages/configuring-workspaces-globally.adoc @@ -0,0 +1,12 @@ +:_content-type: ASSEMBLY +:navtitle: Configuring workspaces globally +:keywords: administration-guide, configuring, workspaces +:page-aliases: + +[id="configuring-workspaces-globally_{context}"] += Configuring workspaces globally + +* xref:configuring-the-number-of-workspaces-that-a-user-can-create.adoc[] +* xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] +* xref:configuring-namespace-strategies.adoc[] +* xref:configuring-workspaces-nodeselector.adoc[] diff --git a/modules/installation-guide/partials/proc_configuring-workspaces-nodeselector.adoc b/modules/administration-guide/pages/configuring-workspaces-nodeselector.adoc similarity index 86% rename from modules/installation-guide/partials/proc_configuring-workspaces-nodeselector.adoc rename to modules/administration-guide/pages/configuring-workspaces-nodeselector.adoc index d499c50361..39ec0bef41 100644 --- a/modules/installation-guide/partials/proc_configuring-workspaces-nodeselector.adoc +++ b/modules/administration-guide/pages/configuring-workspaces-nodeselector.adoc @@ -1,3 +1,7 @@ +:_content-type: PROCEDURE +:navtitle: Configuring workspaces nodeSelector +:keywords: administration guide, configuring-workspaces-nodeselector +:page-aliases: installation-guide:configuring-workspaces-nodeselector [id="configuring-workspaces-nodeselector"] = Configuring workspaces nodeSelector diff --git a/modules/administration-guide/pages/creating-a-telemetry-plugin.adoc b/modules/administration-guide/pages/creating-a-telemetry-plugin.adoc new file mode 100644 index 0000000000..543868f401 --- /dev/null +++ b/modules/administration-guide/pages/creating-a-telemetry-plugin.adoc @@ -0,0 +1,428 @@ +[id="creating-a-telemetry-plugin"] +// = Creating a telemetry plugin +:_content-type: REFERENCE +:navtitle: Creating a telemetry plug-in +:keywords: extensions, telemetry +:page-aliases: extensions:creating-a-telemetry-plug-in + +[id="creating-a-telemetry-plugin"] += Creating a telemetry plug-in + +This section shows how to create an `AnalyticsManager` class that extends link:https://github.com/che-incubator/che-workspace-telemetry-client/blob/master/backend-base/src/main/java/org/eclipse/che/incubator/workspace/telemetry/base/AbstractAnalyticsManager.java[`AbstractAnalyticsManager`] and implements the following methods: + +* `isEnabled()` - determines whether the telemetry backend is functioning correctly. This can mean always returning `true`, or have more complex checks, for example, returning `false` when a connection property is missing. +* `destroy()` - cleanup method that is run before shutting down the telemetry backend. This method sends the `WORKSPACE_STOPPED` event. +* `onActivity()` - notifies that some activity is still happening for a given user. This is mainly used to send `WORKSPACE_INACTIVE` events. +* `onEvent()` - submits telemetry events to the telemetry server, such as `WORKSPACE_USED` or `WORKSPACE_STARTED`. +* `increaseDuration()` - increases the duration of a current event rather than sending many events in a small frame of time. + +The following sections cover: + +* Creating a telemetry server to echo events to standard output. +* Extending the {prod-short} telemetry client and implementing a user's custom backend. +* Creating a `plugin.yaml` file representing a {devworkspace} plug-in for the custom backend. +* Specifying of a location of a custom plug-in to {prod-short} by setting the `workspacesDefaultPlugins` attribute from the `CheCluster` custom resource. + +== Getting started + +This document describes the steps required to extend the {prod-short} telemetry system to communicate with to a custom backend: + +. Creating a server process that receives events +. Extending {prod-short} libraries to create a backend that sends events to the server +. Packaging the telemetry backend in a container and deploying it to an image registry +. Adding a plug-in for your backend and instructing {prod-short} to load the plug-in in your {devworkspace}s + +A finished example of the telemetry backend is available link:https://github.com/che-incubator/devworkspace-telemetry-example-plugin[here]. + +[discrete] +== Creating a server that receives events + +For demonstration purposes, this example shows how to create a server that receives events from our telemetry plug-in and writes them to standard output. + +For production use cases, consider integrating with a third-party telemetry system (for example, Segment, Woopra) rather than creating your own telemetry server. In this case, use your provider's APIs to send events from your custom backend to their system. + +The following Go code starts a server on port `8080` and writes events to standard output: + +.`main.go` +==== +[source,go] +---- +include::example$creating-a-telemetry-plug-in/main.go[] +---- +==== + +Create a container image based on this code and expose it as a deployment in OpenShift in the {prod-namespace} {orch-namespace}. The code for the example telemetry server is available at link:https://github.com/che-incubator/telemetry-server-example[telemetry-server-example]. To deploy the telemetry server, clone the repository and build the container: + +---- +$ git clone https://github.com/che-incubator/telemetry-server-example +$ cd telemetry-server-example +$ docker build -t registry/organization/telemetry-server-example:latest . +$ docker push registry/organization/telemetry-server-example:latest +---- + +Both `manifest_with_ingress.yaml` and `manifest_with_route` contain definitions for a Deployment and Service. The former also defines a {kubernetes} Ingress, while the latter defines an OpenShift Route. + +In the manifest file, replace the `image` and `host` fields to match the image you pushed, and the public hostname of your {platforms-name} cluster. Then run: + +[subs="+quotes"] +---- +$ kubectl apply -f manifest_with_[ingress|route].yaml -n {prod-namespace} +---- + +== Creating the back-end project + +NOTE: For fast feedback when developing, it is recommended to do development inside a {devworkspace}. This way, you can run the application in a cluster and receive events from the front-end telemetry plug-in. + +. Maven Quarkus project scaffolding: ++ +---- +include::example$creating-a-telemetry-plug-in/project_scaffolding.sh[] +---- + +. Remove the files under `src/main/java/mygroup` and `src/test/java/mygroup`. + +. Consult the link:https://github.com/che-incubator/che-workspace-telemetry-client/packages[GitHub packages] for the latest version and Maven coordinates of `backend-base`. + +. Add the following dependencies to your `pom.xml`: ++ +.`pom.xml` +==== +[source,xml] +---- +include::example$creating-a-telemetry-plug-in/pom_snippet.xml[] +---- +==== + +. Create a personal access token with `read:packages` permissions to download the `org.eclipse.che.incubator.workspace-telemetry:backend-base` dependency from link:https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages[GitHub packages]. + +. Add your GitHub username, personal access token and `che-incubator` repository details in your `~/.m2/settings.xml` file: ++ +.`settings.xml` +==== +[source,xml] +---- +include::example$creating-a-telemetry-plug-in/settings.xml[] +---- +==== ++ + + +== Creating a concrete implementation of AnalyticsManager and adding specialized logic + +Create two files in your project under `src/main/java/mygroup`: + +* `MainConfiguration.java` - contains configuration provided to `AnalyticsManager`. +* `AnalyticsManager.java` - contains logic specific to the telemetry system. + +.`MainConfiguration.java` +==== +[source,java] +---- +include::example$creating-a-telemetry-plug-in/MainConfiguration.java[] +---- +==== +<1> A MicroProfile configuration annotation is used to inject the `welcome.message` configuration. + +For more details on how to set configuration properties specific to your backend, see the Quarkus link:https://quarkus.io/guides/config-reference[Configuration Reference Guide]. + +.`AnalyticsManager.java` +==== +[source,java] +---- +include::example$creating-a-telemetry-plug-in/AnalyticsManagerSkeleton.java[] +---- +==== +<1> Log the welcome message if it was provided. +<2> Log the event received from the front-end plug-in. + +Since `org.my.group.AnalyticsManager` and `org.my.group.MainConfiguration` are alternative beans, specify them using the `quarkus.arc.selected-alternatives` property in `src/main/resources/application.properties`. + +.`application.properties` +==== +---- +quarkus.arc.selected-alternatives=MainConfiguration,AnalyticsManager +---- +==== + +[id="running-the-application_{context}"] +== Running the application within a {devworkspace} + +. Set the `DEVWORKSPACE_TELEMETRY_BACKEND_PORT` environment variable in the {devworkspace}. Here, the value is set to `4167`. + ++ +---- +spec: + template: + attributes: + workspaceEnv: + - name: DEVWORKSPACE_TELEMETRY_BACKEND_PORT + value: '4167' +---- ++ + +. Restart the {devworkspace} from the {prod} dashboard. + +. Run the following command within a {devworkspace}'s terminal window to start the application. Use the `--settings` flag to specify path to the location of the `settings.xml` file that contains the GitHub access token. ++ +---- +$ mvn --settings=settings.xml quarkus:dev -Dquarkus.http.port=${DEVWORKSPACE_TELEMETRY_BACKEND_PORT} +---- + ++ +The application now receives telemetry events through port `4167` from the front-end plug-in. + +.Verification steps +. Verify that the following output is logged: + ++ +---- +INFO [org.ecl.che.inc.AnalyticsManager] (Quarkus Main Thread) No welcome message provided +INFO [io.quarkus] (Quarkus Main Thread) devworkspace-telemetry-example-plugin 1.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 0.323s. Listening on: http://localhost:4167 +INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated. +INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, kubernetes-client, rest-client, rest-client-jackson, resteasy, resteasy-jsonb, smallrye-context-propagation, smallrye-openapi, swagger-ui, vertx] +---- + +. To verify that the `onEvent()` method of `AnalyticsManager` receives events from the front-end plug-in, press the kbd:[l] key to disable Quarkus live coding and edit any file within the IDE. The following output should be logged: + ++ +---- +INFO [io.qua.dep.dev.RuntimeUpdatesProcessor] (Aesh InputStream Reader) Live reload disabled +INFO [org.ecl.che.inc.AnalyticsManager] (executor-thread-2) The received event is: Edit Workspace File in Che +---- + +== Implementing `isEnabled()` + +For the purposes of the example, this method always returns `true` whenever it is called. + +.`AnalyticsManager.java` +==== +[source,java] +---- +include::example$creating-a-telemetry-plug-in/isEnabled.java[] +---- +==== + +It is possible to put more complex logic in `isEnabled()`. For example, the link:https://github.com/che-incubator/devworkspace-telemetry-woopra-plugin/blob/main/src/main/java/com/redhat/devworkspace/services/telemetry/woopra/AnalyticsManager.java[hosted {prod-short} Woopra backend] checks that a configuration property exists before determining if the backend is enabled. + +== Implementing `onEvent()` + +`onEvent()` sends the event received by the backend to the telemetry system. For the example application, it sends an HTTP POST payload to the `/event` endpoint from the telemetry server. + +=== Sending a POST request to the example telemetry server +For the following example, the telemetry server application is deployed to OpenShift at the following URL: `++http://little-telemetry-server-che.apps-crc.testing++`, where `apps-crc.testing` is the ingress domain name of the OpenShift cluster. + +. Set up the RESTEasy REST Client by creating `TelemetryService.java` + ++ +.`TelemetryService.java` +==== +[source,java] +---- +include::example$creating-a-telemetry-plug-in/TelemetryService.java[] +---- +==== +<1> The endpoint to make the `POST` request to. ++ + +. Specify the base URL for `TelemetryService` in the `src/main/resources/application.properties` file: + ++ +.`application.properties` +==== +---- +org.my.group.TelemetryService/mp-rest/url=http://little-telemetry-server-che.apps-crc.testing +---- +==== ++ + +. Inject `TelemetryService` into `AnalyticsManager` and send a `POST` request in `onEvent()` + ++ +.`AnalyticsManager.java` +==== +[source,java] +---- +include::example$creating-a-telemetry-plug-in/onEvent.java[] +---- +==== ++ + +This sends an HTTP request to the telemetry server and automatically delays identical events for a small period of time. The default duration is 1500 milliseconds. + +== Implementing `increaseDuration()` + +Many telemetry systems recognize event duration. The `AbstractAnalyticsManager` merges similar events that happen in the same frame of time into one event. This implementation of `increaseDuration()` is a no-op. This method uses the APIs of the user's telemetry provider to alter the event or event properties to reflect the increased duration of an event. + +.`AnalyticsManager.java` +==== +[source,java] +---- +include::example$creating-a-telemetry-plug-in/increaseDuration.java[] +---- +==== + +== Implementing `onActivity()` + +Set an inactive timeout limit, and use `onActivity()` to send a `WORKSPACE_INACTIVE` event if the last event time is longer than the timeout. + +.`AnalyticsManager.java` +==== +[source,java] +---- +include::example$creating-a-telemetry-plug-in/onActivity.java[] +---- +==== + +== Implementing `destroy()` + +When `destroy()` is called, send a `WORKSPACE_STOPPED` event and shutdown any resources such as connection pools. + +.`AnalyticsManager.java` +==== +[source,java] +---- +include::example$creating-a-telemetry-plug-in/destroy.java[] +---- +==== + +Running `mvn quarkus:dev` as described in xref:running-the-application_{context}[] and terminating the application with kbd:[Ctrl+C] sends a `WORKSPACE_STOPPED` event to the server. + +[id="packaging-the-quarkus-application"] +== Packaging the Quarkus application + +See link:https://quarkus.io/guides/building-native-image#using-a-multi-stage-docker-build[the Quarkus documentation] for the best instructions to package the application in a container. Build and push the container to a container registry of your choice. + +=== Sample Dockerfile for building a Quarkus image running with JVM + +.`Dockerfile.jvm` +==== +[source,yaml] +---- +include::example$creating-a-telemetry-plug-in/Dockerfile.jvm[] +---- +==== +To build the image, run: +---- +mvn package && \ +docker build -f src/main/docker/Dockerfile.jvm -t image:tag . +---- + +=== Sample Dockerfile for building a Quarkus native image + +.`Dockerfile.native` +==== +[source,yaml] +---- +include::example$creating-a-telemetry-plug-in/Dockerfile.native[] +---- +==== +To build the image, run: +---- +mvn package -Pnative -Dquarkus.native.container-build=true && \ +docker build -f src/main/docker/Dockerfile.native -t image:tag . +---- + +== Creating a `plugin.yaml` for your plug-in + +Create a `plugin.yaml` devfile v2 file representing a {devworkspace} plug-in that runs your custom backend in a {devworkspace} Pod. For more information about devfile v2, see link:https://devfile.io/docs/[Devfile v2 documentation] + +.`plugin.yaml` +==== +[source,yaml] +---- +include::example$creating-a-telemetry-plug-in/plugin.yaml[] +---- +==== + +<1> Specify the container image built from xref:packaging-the-quarkus-application[]. +<2> Set the value for the `welcome.message` optional configuration property from Example 4. + +Typically, the user deploys this file to a corporate web server. This guide demonstrates how to create an Apache web server on OpenShift and host the plug-in there. + +Create a ConfigMap referencing the new `plugin.yaml` file. + +[subs="+attributes"] +---- +$ oc create configmap --from-file=plugin.yaml -n {prod-namespace} telemetry-plugin-yaml +---- + +Create a deployment, a service, and a route to expose the web server. The deployment references this ConfigMap and places it in the `/var/www/html` directory. + +.`manifest.yaml` +==== +[source,yaml,subs="+quotes,+attributes"] +---- +include::example$creating-a-telemetry-plug-in/webserver.yaml[] +---- +==== + +---- +$ oc apply -f manifest.yaml +---- + +.Verification steps + +pass:[<!-- vale RedHat.TermsErrors = NO -->] + +After the deployment has started, confirm that `plugin.yaml` is available in the web server: + +---- +$ curl apache-che.apps-crc.testing/plugin.yaml +---- + +[id="specifying-the-telemetry-plug-in-in-a-devworkspace"] +== Specifying the telemetry plug-in in a {devworkspace} +. Add the following to the `components` field of an existing {devworkspace}: + ++ +---- +components: + ... + - name: telemetry-plug-in + plugin: + uri: http://apache-che.apps-crc.testing/plugin.yaml +---- ++ + +. Start the {devworkspace} from the {prod-short} dashboard. + + +.Verification steps + +. Verify that the `telemetry-plug-in` container is running in the {devworkspace} pod. Here, this is verified by checking the Workspace view within the editor. + ++ +image::creating-a-telemetry-plug-in/devworkspace_telemetry_plugin.png[] + +. Edit files within the editor and observe their events in the example telemetry server's logs. + + +== Applying the telemetry plug-in for all {devworkspace}s + +Set the telemetry plug-in as a default plug-in in the `spec.server.workspaceDefaultPlugins` field for the `CheCluster` custom resource. Default plug-ins are applied on {devworkspace} startup for new and existing {devworkspace}s. +---- +spec: + ... + server: + ... + workspacesDefaultPlugins: + - editor: eclipse/che-theia/next <1> + plugins: <2> + - 'http://apache-che.apps-crc.testing/plugin.yaml' +---- + +<1> The editorId to set default plug-ins for. +<2> List of URLs to devfile v2 plug-ins. + +This can be accomplished by running `oc edit checluster -n {prod-namespace}` and typing in the change at the terminal, or by editing the CR in the OpenShift console (*Installed Operators -> {prod} -> {prod} Cluster -> {prod-checluster} -> YAML*). + +For more information about the Che Cluster custom resource, see +xref:understanding-the-checluster-custom-resource.adoc[]. + +.Verification steps + +. Start a new or existing {devworkspace} from the {prod} dashboard. + +. Verify that the telemetry plug-in is working by following the verification steps for xref:specifying-the-telemetry-plug-in-in-a-devworkspace[]. + +pass:[<!-- vale RedHat.TermsErrors = YES -->] diff --git a/modules/administration-guide/pages/customizing-the-registries.adoc b/modules/administration-guide/pages/customizing-the-registries.adoc deleted file mode 100644 index 65dd8d7b13..0000000000 --- a/modules/administration-guide/pages/customizing-the-registries.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="customizing-the-registries"] -// = Customizing the registries -:navtitle: Customizing the registries -:keywords: contributor-guide, customizing-the-devfile-and-plug-in-registries, including-the-plug-in-binaries-in-the-registry-image -:page-aliases: .:customizing-the-devfile-and-plug-in-registries, contributor-guide:customizing-the-devfile-and-plug-in-registries, administration-guide:building-and-running-a-custom-registry-image, customizing-the-devfile-and-plug-in-registries - -include::partial$assembly_customizing-the-registries.adoc[] diff --git a/modules/administration-guide/pages/dashboard.adoc b/modules/administration-guide/pages/dashboard.adoc index ce686998c4..5787e90e20 100644 --- a/modules/administration-guide/pages/dashboard.adoc +++ b/modules/administration-guide/pages/dashboard.adoc @@ -1,6 +1,39 @@ -[id="dashboard"] +:_content-type: ASSEMBLY :navtitle: User dashboard :keywords: administration-guide, architecture, server, devworkspace, user, dashboard -// :page-aliases: +:page-aliases: + +[id="dashboard_{context}"] += User dashboard + +The user dashboard is the landing page of {prod}. +{prod-short} users browse the user dashboard to access and manage their workspaces. +It is a React application. +The {prod-short} deployment starts it in the `{prod-deployment}-dashboard` Deployment. + +It need access to: + +* xref:devfile-registries.adoc[] +* xref:che-server.adoc[] +* xref:plug-in-registry.adoc[] +* {orch-name} API + +.User dashboard interactions with other components +image::architecture/{project-context}-dashboard-interactions.png[User dashboard interactions with other components] + +When the user requests the user dashboard to start a workspace, the user dashboard executes this sequence of actions: + +. Collects the devfile from the xref:devfile-registries.adoc[], when the user is creating a workspace from a code sample. +. Sends the repository URL to xref:che-server.adoc[] and expects a devfile in return, when the user is creating a workspace from a remote devfile. +. Reads the devfile describing the workspace. +. Collects the additional metadata from the xref:plug-in-registry.adoc[]. +. Converts the information into a {devworkspace} Custom Resource. +. Creates the {devworkspace} Custom Resource in the user {orch-namespace} using the {orch-name} API. +. Watches the {devworkspace} Custom Resource status. +. Redirects the user to the running workspace IDE. + + +.Additional resources + +include::example$snip_{project-context}-dashboard-additional-resources.adoc[] -include::partial$con_dashboard.adoc[] diff --git a/modules/administration-guide/pages/define-backup-server-for-operator.adoc b/modules/administration-guide/pages/define-backup-server-for-operator.adoc deleted file mode 100644 index e47705adfd..0000000000 --- a/modules/administration-guide/pages/define-backup-server-for-operator.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="define-backup-server-for-operator"] -// = Defining backup server for operator -:navtitle: Configuring {prod-short} Operator to use a backup server -:keywords: administration-guide, backup, recovery, operator -:page-aliases: .:define-backup-server-for-operator - -include::partial$con_define-backup-server-for-operator.adoc[] diff --git a/modules/administration-guide/pages/defining-the-list-of-images-to-pull.adoc b/modules/administration-guide/pages/defining-the-list-of-images-to-pull.adoc index e2023d827c..6fc1c7e96e 100644 --- a/modules/administration-guide/pages/defining-the-list-of-images-to-pull.adoc +++ b/modules/administration-guide/pages/defining-the-list-of-images-to-pull.adoc @@ -1,6 +1,24 @@ -[id="defining-the-list-of-images-to-pull"] +:_content-type: PROCEDURE :navtitle: Defining the list of images :keywords: administration-guide, image-puller, configuration :page-aliases: .:defining-the-list-of-images-to-pull -include::partial$proc_defining-the-list-of-images-to-pull.adoc[] +[id="defining-the-list-of-images-to-pull_{context}"] += Defining the list of images to pull + +The {image-puller-name-short} can pre-pull most images, including scratch images such as `che-machine-exec`. However, images that mount volumes in the Dockerfile, such as `traefik`, are not supported for pre-pulling on OpenShift 3.11. + +.Procedure + +. Gather a list of relevant container images for prepulling by navigating to the `pass:c,a,q[{prod-url}]/plugin-registry/v3/external_images.txt` URL. + +. Determine images from the list for pre-pulling. For faster workspace startup times, consider pre-pulling workspace related images such as `che-theia`, `che-machine-exec`, `che-theia-endpoint-runtime-binary`, and plug-in sidecar images. + +.Additional resources + +pass:[<!-- vale CheDocs.Attributes = NO -->] + +* xref:installing-image-puller-on-openshift-using-operatorhub.adoc[] +* xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[] + +pass:[<!-- vale CheDocs.Attributes = YES -->] diff --git a/modules/administration-guide/pages/defining-the-memory-parameters-for-the-image-puller.adoc b/modules/administration-guide/pages/defining-the-memory-parameters-for-the-image-puller.adoc index 67561bf99c..fda3cdda7c 100644 --- a/modules/administration-guide/pages/defining-the-memory-parameters-for-the-image-puller.adoc +++ b/modules/administration-guide/pages/defining-the-memory-parameters-for-the-image-puller.adoc @@ -1,6 +1,33 @@ -[id="defining-the-memory-parameters-for-the-image-puller"] +:_content-type: PROCEDURE :navtitle: Defining the memory settings :keywords: administration-guide, image-puller, configuration :page-aliases: .:defining-the-memory-parameters-for-the-image-puller -include::partial$proc_defining-the-memory-parameters-for-the-image-puller.adoc[] +[id="proc_defining-the-memory-parameters-for-the-image-puller_{context}"] += Defining the memory parameters for the {image-puller-name-short} + +[role="_abstract"] +Define the memory requests and limits parameters to ensure pulled containers and the platform have enough memory to run. + +.Prerequisites + +* xref:defining-the-list-of-images-to-pull.adoc[] + +.Procedure + +. To define the minimal value for `CACHING_MEMORY_REQUEST` or `CACHING_MEMORY_LIMIT`, consider the necessary amount of memory required to run each of the container images to pull. + +. To define the maximal value for `CACHING_MEMORY_REQUEST` or `CACHING_MEMORY_LIMIT`, consider the total memory allocated to the DaemonSet Pods in the cluster: ++ +---- +(memory limit) * (number of images) * (number of nodes in the cluster) +---- ++ +==== +Pulling 5 images on 20 nodes, with a container memory limit of `20Mi` requires `2000Mi` of memory. +==== + +.Additional resources + +* xref:installing-image-puller-on-openshift-using-operatorhub.adoc[] +* xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[] diff --git a/modules/installation-guide/partials/proc_deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc b/modules/administration-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc similarity index 85% rename from modules/installation-guide/partials/proc_deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc rename to modules/administration-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc index 1e4bf62e74..348c0a54c4 100644 --- a/modules/installation-guide/partials/proc_deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc +++ b/modules/administration-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc @@ -1,4 +1,7 @@ - +:_content-type: PROCEDURE +:navtitle: Deploying {prod-short} with support for Git repositories with self-signed certificates +:keywords: administration guide, deploying-che-with-support-for-git-repositories-with-self-signed-certificates +:page-aliases: installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates [id="deploying-{prod-id-short}-with-support-for-git-repositories-with-self-signed-certificates_{context}"] = Deploying {prod-short} with support for Git repositories with self-signed certificates @@ -38,7 +41,7 @@ $ {orch-cli} label configmap che-git-self-signed-cert \ app.kubernetes.io/part-of=che.eclipse.org -n {prod-namespace} ---- -. Configure {prod-short} to use self-signed certificates for git repositories: +. Configure {prod-short} to use self-signed certificates for Git repositories: + Update the `gitSelfSignedCert` property. To do that, execute: + diff --git a/modules/administration-guide/pages/devfile-registries.adoc b/modules/administration-guide/pages/devfile-registries.adoc index 3a7209478a..01c5391775 100644 --- a/modules/administration-guide/pages/devfile-registries.adoc +++ b/modules/administration-guide/pages/devfile-registries.adoc @@ -1,6 +1,23 @@ -[id="devfile-registries"] +:_content-type: ASSEMBLY :navtitle: Devfile registries :keywords: administration-guide, architecture, server, devworkspace, devfile, registry -// :page-aliases: +:page-aliases: + +[id="devfile-registries_{context}"] += Devfile registries + +The {prod-short} devfile registries are services providing a list of sample devfiles to create ready-to-use workspaces. +The xref:dashboard.adoc[] displays the samples list on the *Dashboard* -> *Create Workspace* page. +Each sample includes a Devfile v2. +The {prod-short} deployment starts one devfile registry instance in the `devfile-registry` deployment. + +.Devfile registries interactions with other components +image::architecture/{project-context}-devfile-registry-interactions.png[] + +.Additional resources + +* link:https://devfile.io/docs/[Devfile v2 documentation] +* link:https://eclipse-che.github.io/che-devfile-registry/main/devfiles/[devfile registry latest community version online instance] + +include::example$snip_che-devfile-registry-additional-resources.adoc[] -include::partial$con_devfile-registries.adoc[] diff --git a/modules/administration-guide/pages/devworkspace-operator.adoc b/modules/administration-guide/pages/devworkspace-operator.adoc index f39f8f9e2c..60711148da 100644 --- a/modules/administration-guide/pages/devworkspace-operator.adoc +++ b/modules/administration-guide/pages/devworkspace-operator.adoc @@ -1,7 +1,27 @@ -[id="devworkspace-operator"] +:_content-type: ASSEMBLY :navtitle: {devworkspace} operator :keywords: administration-guide, workspace operator, devworkspace :page-aliases: .:devworkspace-operator +[id="devworkspace-operator_{context}"] += {devworkspace} operator -include::partial$con_devworkspace-operator.adoc[] +The {devworkspace} operator extends {orch-name} to provide {devworkspace} support. It introduces: + +{devworkspace} custom resource definition:: + +Defines the {devworkspace} {orch-name} object from the Devfile v2 specification. + +{devworkspace} controller:: + +Creates and controls the necessary {orch-name} objects to run a {devworkspace}, such as pods, services, and persistent volumes. + +{devworkspace} custom resource:: + +On a cluster with the {devworkspace} operator, it is possible to create {devworkspace} custom resources (CR). A {devworkspace} CR is a {orch-name} representation of a Devfile. It defines a User workspaces in a {orch-name} cluster. + + +.Additional resources + +* link:https://github.com/devfile/api[Devfile API repository] +include::example$snip_{project-context}-devworkspace-additional-resources.adoc[] diff --git a/modules/administration-guide/pages/disabling-readiness-init-containers-for-the-olm-installer.adoc b/modules/administration-guide/pages/disabling-readiness-init-containers-for-the-olm-installer.adoc deleted file mode 100644 index 38570f22e0..0000000000 --- a/modules/administration-guide/pages/disabling-readiness-init-containers-for-the-olm-installer.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="disabling-readiness-init-containers-for-the-olm-installer"] -:navtitle: Disabling the readiness init containers for the OLM installer -:keywords: disable-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, olm -:page-aliases: .:disabling-readiness-init-containers-for-the-olm-installer - -include::partial$proc_disabling-readiness-init-containers-for-the-olm-installer.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/disabling-readiness-init-containers-for-the-operator-installer.adoc b/modules/administration-guide/pages/disabling-readiness-init-containers-for-the-operator-installer.adoc deleted file mode 100644 index 6c715efe5c..0000000000 --- a/modules/administration-guide/pages/disabling-readiness-init-containers-for-the-operator-installer.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="disabling-readiness-init-containers-for-the-operator-installer"] -:navtitle: Disabling the readiness init containers for the Operator installer -:keywords: disable-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, operator -:page-aliases: .:disabling-readiness-init-containers-for-the-operator-installer - -include::partial$proc_disabling-readiness-init-containers-for-the-operator-installer.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc b/modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc deleted file mode 100644 index 997c539a59..0000000000 --- a/modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="enabling-and-disabling-readiness-init-containers-for-the-olm-installer"] -:navtitle: Enabling and disabling the readiness init containers for the OLM installer -:keywords: enable-readiness-init-containers, disable-readiness-init-containers, enabling-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, olm -:page-aliases: .:enabling-and-disabling-readiness-init-containers-for-the-olm-installer - -include::partial$assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc b/modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc deleted file mode 100644 index 2971a5ac29..0000000000 --- a/modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="enabling-and-disabling-readiness-init-containers-for-the-operator-installer"] -:navtitle: Enabling and disabling the readiness init containers for the Operator installer -:keywords: enable-readiness-init-containers, disable-readiness-init-containers, enabling-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, operator -:page-aliases: .:enabling-and-disabling-readiness-init-containers-for-the-operator-installer - -include::partial$assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/enabling-readiness-init-containers-for-the-olm-installer.adoc b/modules/administration-guide/pages/enabling-readiness-init-containers-for-the-olm-installer.adoc deleted file mode 100644 index 7ecef17f45..0000000000 --- a/modules/administration-guide/pages/enabling-readiness-init-containers-for-the-olm-installer.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="enabling-readiness-init-containers-for-the-olm-installer"] -:navtitle: Enabling the readiness init containers for the OLM installer -:keywords: enable-readiness-init-containers, enabling-readiness-init-containers, init-container, readiness-init-container, startup, olm -:page-aliases: .:enabling-readiness-init-containers-for-the-olm-installer - -include::partial$proc_enabling-readiness-init-containers-for-the-olm-installer.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/enabling-readiness-init-containers-for-the-operator-installer.adoc b/modules/administration-guide/pages/enabling-readiness-init-containers-for-the-operator-installer.adoc deleted file mode 100644 index 0ca06760f5..0000000000 --- a/modules/administration-guide/pages/enabling-readiness-init-containers-for-the-operator-installer.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="enabling-readiness-init-containers-for-the-operator-installer"] -:navtitle: Enabling the readiness init containers for the Operator installer -:keywords: enable-readiness-init-containers, enabling-readiness-init-containers, init-container, readiness-init-container, startup, operator -:page-aliases: .:enabling-readiness-init-containers-for-the-operator-installer - -include::partial$proc_enabling-readiness-init-containers-for-the-operator-installer.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/external-database-setup.adoc b/modules/administration-guide/pages/external-database-setup.adoc deleted file mode 100644 index 480c796751..0000000000 --- a/modules/administration-guide/pages/external-database-setup.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="external-database-setup"] -// = External database setup -:navtitle: External database setup -:keywords: administration-guide, external-database-setup -:page-aliases: .:external-database-setup, .:database-setup - -include::partial$con_external-database-setup.adoc[] diff --git a/modules/administration-guide/pages/gateway.adoc b/modules/administration-guide/pages/gateway.adoc index 435535745b..79fe65bc8b 100644 --- a/modules/administration-guide/pages/gateway.adoc +++ b/modules/administration-guide/pages/gateway.adoc @@ -1,6 +1,32 @@ -[id="gateway"] +:_content-type: ASSEMBLY :navtitle: Gateway :keywords: administration-guide, architecture, server, devworkspace, gateway -// :page-aliases: +:page-aliases: -include::partial$con_gateway.adoc[] +[id="gateway_{context}"] += Gateway + +The {prod-short} gateway has following roles: + +* Routing requests. It uses link:https://github.com/traefik/traefik[Traefik]. + +* Authenticating users with OpenID Connect (OIDC). It uses {link-oauth2-proxy}. + +* Applying {orch-name} Role based access control (RBAC) policies to control access to any {prod-short} resource. It uses {link-kube-rbac-proxy}. + +The {prod-short} operator manages it as the `che-gateway` Deployment. + +It controls access to: + +* xref:dashboard.adoc[] +* xref:devfile-registries.adoc[] +* xref:che-server.adoc[] +* xref:plug-in-registry.adoc[] +* xref:user-workspaces.adoc[] + +.{prod-short} gateway interactions with other components +image::architecture/{project-context}-gateway-interactions.png[{prod-short} gateway interactions with other components] + +.Additional resources + +* xref:managing-identities-and-authorizations.adoc[] diff --git a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc b/modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc similarity index 91% rename from modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc rename to modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc index 622c022929..bbecdbf4f1 100644 --- a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc +++ b/modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc @@ -1,3 +1,7 @@ +:_content-type: CONCEPT +:navtitle: Importing untrusted TLS certificates to {prod-short} +:keywords: administration guide, tls, certificate +:page-aliases: installation-guide:importing-untrusted-tls-certificates, installation-guide:importing-untrusted-tls-certificates-old [id="importing-untrusted-tls-certificates_{context}"] = Importing untrusted TLS certificates to {prod-short} @@ -15,13 +19,7 @@ Typical cases that may require this addition are: [NOTE] ==== -ifeval::["{project-context}" == "che"] -On OpenShift, when -endif::[] -ifeval::["{project-context}" != "che"] -When -endif::[] -the cluster contains cluster-wide trusted CA certificates added through the link:https://docs.openshift.com/container-platform/4.4/networking/configuring-a-custom-pki.html#nw-proxy-configure-object_configuring-a-custom-pki[cluster-wide-proxy configuration], {prod-short} Operator detects them and automatically injects them into this ConfigMap: +When the OpenShift cluster contains cluster-wide trusted CA certificates added through the link:https://docs.openshift.com/container-platform/4.4/networking/configuring-a-custom-pki.html#nw-proxy-configure-object_configuring-a-custom-pki[cluster-wide-proxy configuration], {prod-short} Operator detects them and automatically injects them into this ConfigMap: - {prod-short} automatically labels the ConfigMap with the `config.openshift.io/inject-trusted-cabundle="true"` label. - Based on this annotation, OpenShift automatically injects the cluster-wide trusted CA certificates inside the `ca-bundle.crt` key of ConfigMap @@ -37,17 +35,6 @@ If the cluster is configured with an intermediate certificate, then the whole ch The following procedure is applicable for already installed and running instances and for instances that are to be installed. -==== -NOTE: If you are using {prod-short} version lower than -ifeval::["{project-context}" == "che"] -v7.23.0 -endif::[] -ifeval::["{project-context}" != "che"] -2.5.1 -endif::[] -see xref:importing-untrusted-tls-certificates-old.adoc[this guide] on how to apply additional TLS certificates. -==== - .Prerequisites * The `{orch-cli}` tool is available. diff --git a/modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc b/modules/administration-guide/pages/installing-che-in-a-restricted-environment.adoc similarity index 68% rename from modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc rename to modules/administration-guide/pages/installing-che-in-a-restricted-environment.adoc index fb96de4666..a10a073479 100644 --- a/modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc +++ b/modules/administration-guide/pages/installing-che-in-a-restricted-environment.adoc @@ -1,4 +1,7 @@ - +:_content-type: PROCEDURE +:navtitle: Installing {prod-short} in restricted environment +:keywords: administration guide, installing-che-in-a-restricted-environment, installing-che-in-restricted-environment +:page-aliases: installation-guide:installing-che-in-restricted-environment, installation-guide:installing-che-in-a-restricted-environment :parent-context-of-installing-che-in-a-restricted-environment: {context} @@ -17,20 +20,7 @@ By default, {prod-short} workspaces reference various external resources, includ * Block-based storage volume or NFS share available outside of the cluster to serve dynamic storage provisioning or PVs. Block-based storage is recommended for optimal performance. -include::example$con_{project-context}-understanding-network-connectivity-in-restricted-environments.adoc[leveloffset=+1] - - -include::partial$ref_understanding-the-registries.adoc[leveloffset=+1] - - -include::partial$assembly_building-offline-registry-images.adoc[leveloffset=+1] - - -include::example$proc_{project-context}-preparing-a-private-registry.adoc[leveloffset=+1] - - -include::example$proc_{project-context}-configuring-che-to-run-in-a-restricted-environment.adoc[leveloffset=+1] - +* xref:preparing-a-restricted-environment.adoc[] +* xref:configuring-che-to-run-in-a-restricted-environment.adoc[] :context: {parent-context-of-installing-che-in-a-restricted-environment} - diff --git a/modules/installation-guide/partials/assembly_installing-che-locally.adoc b/modules/administration-guide/pages/installing-che-locally.adoc similarity index 63% rename from modules/installation-guide/partials/assembly_installing-che-locally.adoc rename to modules/administration-guide/pages/installing-che-locally.adoc index 426a787c6f..f92a443f38 100644 --- a/modules/installation-guide/partials/assembly_installing-che-locally.adoc +++ b/modules/administration-guide/pages/installing-che-locally.adoc @@ -1,12 +1,11 @@ - - -:parent-context-of-running-che-locally: {context} +:_content-type: PROCEDURE +:navtitle: Installing {prod-short} locally +:keywords: overview, running-che-locally, installing-che-locally +:page-aliases: installation-guide:running-che-locally, installation-guide:installing-che-in-tls-mode-with-self-signed-certificates, overview:running-che-locally, installation-guide:installing-che-locally [id="installing-{prod-id-short}-locally_{context}"] = Installing {prod-short} locally -:context: running-{prod-id-short}-locally - This section contains instructions for deploying and running {prod} locally, on a personal workstation. .Prerequisites @@ -26,15 +25,5 @@ To run and manage {prod-short}: Choose one of the following procedures to start the {prod-short} Server using the `{prod-cli}` tool. * xref:installing-che-on-codeready-containers.adoc[] -* xref:installing-che-on-docker-desktop.adoc[] * xref:installing-che-on-minikube.adoc[] -* xref:installing-che-on-minishift.adoc[] -* xref:installing-che-on-kind.adoc[] -* xref:installing-che-on-kubespray.adoc[] - -.Additional resources - -* xref:end-user-guide:workspaces-overview.adoc[] -* xref:end-user-guide:importing-the-source-code-of-a-project-into-a-workspace.adoc[] -:context: {parent-context-of-running-che-locally} diff --git a/modules/installation-guide/partials/assembly_installing-che-on-codeready-containers.adoc b/modules/administration-guide/pages/installing-che-on-codeready-containers.adoc similarity index 74% rename from modules/installation-guide/partials/assembly_installing-che-on-codeready-containers.adoc rename to modules/administration-guide/pages/installing-che-on-codeready-containers.adoc index 535c47e0b7..95c18a9931 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-codeready-containers.adoc +++ b/modules/administration-guide/pages/installing-che-on-codeready-containers.adoc @@ -1,4 +1,7 @@ - +:_content-type: ASSEMBLY +:navtitle: Installing {prod-short} on CodeReady Containers +:keywords: overview, installing-che-on-codeready-containers +:page-aliases: installation-guide:installing-che-on-codeready-containers, overview:installing-che-on-codeready-containers :parent-context-of-installing-che-on-codeready-containers: {context} @@ -13,6 +16,4 @@ include::partial$proc_using-chectl-to-install-che-on-codeready-containers.adoc[l include::partial$proc_using-openshift-web-console-to-install-che-on-codeready-containers.adoc[leveloffset=+1] -include::end-user-guide:partial$proc_importing-certificates-to-browsers.adoc[leveloffset=+1] - :context: {parent-context-of-installing-che-on-codeready-containers} diff --git a/modules/installation-guide/partials/assembly_installing-che-on-minikube.adoc b/modules/administration-guide/pages/installing-che-on-minikube.adoc similarity index 78% rename from modules/installation-guide/partials/assembly_installing-che-on-minikube.adoc rename to modules/administration-guide/pages/installing-che-on-minikube.adoc index 9b45355f9a..5bc13d4e8b 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-minikube.adoc +++ b/modules/administration-guide/pages/installing-che-on-minikube.adoc @@ -1,4 +1,7 @@ - +:_content-type: ASSEMBLY +:navtitle: Installing {prod-short} on Minikube +:keywords: overview, installing-che-on-minikube +:page-aliases: installation-guide:installing-che-on-minikube, overview:installing-che-on-minikube :parent-context-of-installing-che-on-minikube: {context} @@ -15,8 +18,6 @@ include::partial$proc_using-minikube-to-set-up-kubernetes.adoc[leveloffset=+1] include::partial$proc_installing-che-on-minikube-using-chectl.adoc[leveloffset=+1] -include::end-user-guide:partial$proc_importing-certificates-to-browsers.adoc[leveloffset=+1] - include::partial$proc_using-minikube-and-lxc.adoc[leveloffset=+1] :context: {parent-context-of-installing-che-on-minikube} diff --git a/modules/installation-guide/partials/proc_installing-che-on-openshift-4-using-the-cli.adoc b/modules/administration-guide/pages/installing-che-on-openshift-4-using-cli.adoc similarity index 81% rename from modules/installation-guide/partials/proc_installing-che-on-openshift-4-using-the-cli.adoc rename to modules/administration-guide/pages/installing-che-on-openshift-4-using-cli.adoc index 37f1983c0d..f9bfc2533d 100644 --- a/modules/installation-guide/partials/proc_installing-che-on-openshift-4-using-the-cli.adoc +++ b/modules/administration-guide/pages/installing-che-on-openshift-4-using-cli.adoc @@ -1,3 +1,8 @@ +:_content-type: PROCEDURE +:navtitle: Installing {prod-short} on OpenShift 4 using CLI +:keywords: overview, installing-che-on-openshift-4-using-cli +:page-aliases: installation-guide:installing-che-on-openshift-4-using-cli, overview:installing-che-on-openshift-4-using-cli + [id="installing-{prod-id-short}-on-openshift-4-using-the-cli_{context}"] = Installing {prod-short} on OpenShift 4 using the CLI diff --git a/modules/installation-guide/partials/assembly_installing-che-on-openshift-4-using-operatorhub.adoc b/modules/administration-guide/pages/installing-che-on-openshift-4-using-operatorhub.adoc similarity index 70% rename from modules/installation-guide/partials/assembly_installing-che-on-openshift-4-using-operatorhub.adoc rename to modules/administration-guide/pages/installing-che-on-openshift-4-using-operatorhub.adoc index 8d9f1742a2..0f92b9b32a 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-openshift-4-using-operatorhub.adoc +++ b/modules/administration-guide/pages/installing-che-on-openshift-4-using-operatorhub.adoc @@ -1,6 +1,11 @@ +:_content-type: PROCEDURE +:navtitle: Installing {prod-short} on OpenShift 4 using OperatorHub +:keywords: overview, installing-che-on-openshift-4-using-operatorhub +:page-aliases: installation-guide:installing-che-on-openshift-4-using-operatorhub, overview:installing-che-on-openshift-4-using-operatorhub, creating-an-instance-of-the-che-operator + :parent-context-of-installing-che-using-the-che-operator-in-openshift-4-web-console: {context} -[id="installing-{prod-id-short}-on-openshiftt-4-using-operatorhub_{context}"] +[id="installing-{prod-id-short}-on-openshift-4-using-operatorhub_{context}"] = Installing {prod-short} on OpenShift 4 using OperatorHub This section describes how to install {prod-short} using the {prod-short} Operator available in OpenShift 4 web console. @@ -23,9 +28,4 @@ include::partial$proc_installing-the-che-operator.adoc[leveloffset=+1] include::partial$proc_creating-an-instance-of-the-che-operator.adoc[leveloffset=+1] -.Additional resources - -* xref:end-user-guide:navigating-che-using-the-dashboard.adoc[]. -* xref:administration-guide:viewing-operator-events.adoc[]. - :context: {parent-context-of-installing-che-using-the-che-operator-in-openshift-4-web-console} diff --git a/modules/installation-guide/partials/proc_installing-che-using-storage-classes.adoc b/modules/administration-guide/pages/installing-che-using-storage-classes.adoc similarity index 95% rename from modules/installation-guide/partials/proc_installing-che-using-storage-classes.adoc rename to modules/administration-guide/pages/installing-che-using-storage-classes.adoc index bc447d4cd4..c0a2077210 100644 --- a/modules/installation-guide/partials/proc_installing-che-using-storage-classes.adoc +++ b/modules/administration-guide/pages/installing-che-using-storage-classes.adoc @@ -1,6 +1,10 @@ +:_content-type: CONCEPT +:navtitle: Installing {prod-short} using storage classes +:keywords: administration guide, installing-che-using-storage-classes +:page-aliases: installation-guide:installing-che-using-storage-classes [id="installing-{prod-id-short}-using-storage-classes_{context}"] -= Installing {prod-short} using storage classes += Configuring storage classes To configure {prod-short} to use a configured infrastructure storage, install {prod-short} using storage classes. This is especially useful when a user wants to bind a persistent volume provided by a non-default provisioner. To do so, a user binds this storage for the {prod-short} data saving and sets the parameters for that storage. These parameters can determine the following: diff --git a/modules/administration-guide/pages/installing-che.adoc b/modules/administration-guide/pages/installing-che.adoc new file mode 100644 index 0000000000..2e3958c8f7 --- /dev/null +++ b/modules/administration-guide/pages/installing-che.adoc @@ -0,0 +1,12 @@ +:_content-type: ASSEMBLY +:navtitle: Installing Che +:keywords: administration guide, installing-che +:page-aliases: installation-guide:installing-che, installation-guide:3-minutes-to-che, overview:3-minutes-to-che, installation-guide:quick-starts, installation-guide:che-quick-starts, .:quick-start.html, overview:che-quick-start, installation-guide:installing-che-on-aws, installation-guide:installing-che-on-docker-desktop, installation-guide:installing-che-on-google-cloud-platform, installation-guide:installing-che-on-kind, installation-guide:installing-che-on-kubespray, installation-guide:installing-che-on-microsoft-azure, installation-guide:installing-che-on-openshift-3-using-the-operator + +[id="installing-{prod-id-short}_{context}"] += Installing {prod-short} + +This section contains instructions to install {prod}. + +include::example$snip_{project-context}-installing-che.adoc[] + diff --git a/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc b/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc deleted file mode 100644 index 2c0b306b35..0000000000 --- a/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="installing-image-puller-on-kubernetes-using-the-image-puller-operator"] -:navtitle: Installing using the {image-puller-operator-name} -:keywords: administration-guide, image-puller, kubernetes, operator -:page-aliases: .:installing-image-puller-on-kubernetes-using-image-puller-operator - -include::partial$proc_installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc[] diff --git a/modules/administration-guide/pages/installing-image-puller-on-openshift-using-openshift-templates.adoc b/modules/administration-guide/pages/installing-image-puller-on-openshift-using-openshift-templates.adoc index a905def9be..06c6f0e7cd 100644 --- a/modules/administration-guide/pages/installing-image-puller-on-openshift-using-openshift-templates.adoc +++ b/modules/administration-guide/pages/installing-image-puller-on-openshift-using-openshift-templates.adoc @@ -1,6 +1,141 @@ -[id="installing-image-puller-on-openshift-using-openshift-templates"] -:navtitle: Installing on OpenShift 3 +:_content-type: PROCEDURE +:navtitle: Installing using OpenShift templates :keywords: administration-guide, image-puller, openshift, openshift-templates, CLI :page-aliases: .:installing-image-puller-on-openshift-using-openshift-templates -include::partial$proc_installing-image-puller-using-openshift-templates.adoc[] +[id="installing-image-puller-on-openshift-using-openshift-templates_{context}"] += Installing {image-puller-name-short} on OpenShift using OpenShift templates + +This procedure describes how to install the {image-puller-name} on OpenShift using OpenShift templates. + +.Prerequisites + +* A running OpenShift cluster. +* The `oc` tool is available. +* xref:defining-the-list-of-images-to-pull.adoc[]. +* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. + +.Procedure + +. Clone the {image-puller-name-short} repository and get in the directory containing the OpenShift templates: ++ +include::example$snip_{project-context}-cloning-image-puller-project.adoc[] + + +. Configure the `app.yaml`, `configmap.yaml` and `serviceaccount.yaml` OpenShift templates using following parameters: ++ +.{image-puller-name-short} OpenShift templates parameters in `app.yaml` +[options="header"] +|=== +|Value |Usage |Default + +|`DEPLOYMENT_NAME` +|The value of `DEPLOYMENT_NAME` in the ConfigMap +|`{image-puller-deployment-name}` + +|`IMAGE` +|Image used for the `{image-puller-deployment-name}` deployment +|`{image-puller-image-name}` + +|`IMAGE_TAG` +|The image tag to pull +|`latest` + +|`SERVICEACCOUNT_NAME` +|The name of the ServiceAccount created and used by the deployment +|`kubernetes-image-puller` + +|=== ++ +.{image-puller-name-short} OpenShift templates parameters in `configmap.yaml` +[options="header"] +|=== +|Value |Usage |Default + +|`CACHING_CPU_LIMIT` +|The value of `CACHING_CPU_LIMIT` in the ConfigMap +|`.2` + +|`CACHING_CPU_REQUEST` +|The value of `CACHING_CPU_REQUEST` in the ConfigMap +|`.05` + +|`CACHING_INTERVAL_HOURS` +|The value of `CACHING_INTERVAL_HOURS` in the ConfigMap +|``"1"`` + +|`CACHING_MEMORY_LIMIT` +|The value of `CACHING_MEMORY_LIMIT` in the ConfigMap +|`"20Mi"` + +|`CACHING_MEMORY_REQUEST` +|The value of `CACHING_MEMORY_REQUEST` in the ConfigMap +|`"10Mi"` + +|`DAEMONSET_NAME` +|The value of `DAEMONSET_NAME` in the ConfigMap +|`{image-puller-deployment-name}` + +|`DEPLOYMENT_NAME` +|The value of `DEPLOYMENT_NAME` in the ConfigMap +|`{image-puller-deployment-name}` + +|`IMAGES` +|The value of `IMAGES` in the ConfigMap +|`{image-puller-images}` + +|`NAMESPACE` +|The value of `NAMESPACE` in the ConfigMap +|`{image-puller-namespace}` + +|`NODE_SELECTOR` +|The value of `NODE_SELECTOR` in the ConfigMap +|`"{}"` +|=== ++ +.{image-puller-name-short} OpenShift templates parameters in `serviceaccount.yaml` +[options="header"] +|=== +|Value |Usage |Default + +|`SERVICEACCOUNT_NAME` +|The name of the ServiceAccount created and used by the deployment +|`kubernetes-image-puller` + +|=== + + + +. Create an OpenShift project to host the {image-puller-name-short}: ++ +[subs="+attributes,+quotes"] +---- +$ oc new-project __<{image-puller-namespace}>__ +---- + +. Process and apply the templates to install the puller: ++ +[subs="+attributes,+quotes"] +---- +$ oc process -f serviceaccount.yaml | oc apply -f - +$ oc process -f configmap.yaml | oc apply -f - +$ oc process -f app.yaml | oc apply -f - +---- + + +.Verification steps + +. Verify the existence of a __<{image-puller-deployment-name}>__ deployment and a __<{image-puller-deployment-name}>__ DaemonSet. The DaemonSet needs to have a Pod for each node in the cluster: ++ +[source%nowrap,dummy,subs="+quotes,+attributes"] +---- +$ oc get deployment,daemonset,pod --namespace __<{image-puller-namespace}>__ +---- + +. Verify the values of the __<{image-puller-deployment-name}>__ `ConfigMap`. ++ +[source%nowrap,dummy,subs="+quotes,+attributes"] +---- +$ oc get configmap __<{image-puller-deployment-name}>__ --output yaml +---- + diff --git a/modules/administration-guide/pages/installing-image-puller-on-openshift-using-operatorhub.adoc b/modules/administration-guide/pages/installing-image-puller-on-openshift-using-operatorhub.adoc index 6aa0b7da8c..6f990097a7 100644 --- a/modules/administration-guide/pages/installing-image-puller-on-openshift-using-operatorhub.adoc +++ b/modules/administration-guide/pages/installing-image-puller-on-openshift-using-operatorhub.adoc @@ -1,6 +1,42 @@ -[id="installing-image-puller-on-openshift-using-operatorhub"] -:navtitle: Installing on OpenShift 4 +:_content-type: PROCEDURE +:navtitle: Installing using OperatorHub :keywords: administration-guide, image-puller, openshift, operator, operatorhub :page-aliases: .:installing-image-puller-on-openshift-using-operatorhub -include::partial$proc_installing-image-puller-on-openshift-using-operatorhub.adoc[] +[id="installing-image-puller-on-openshift-4-using-operatorhub_{context}"] += Installing {image-puller-name-short} on OpenShift 4 using OperatorHub + +This procedure describes how to install the {image-puller-operator-name} on OpenShift 4 using the Operator. + + +.Prerequisites + +* An administrator account on a running instance of OpenShift 4. +* xref:defining-the-list-of-images-to-pull.adoc[] +* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. + +.Procedure + +. To create an OpenShift project __<{image-puller-deployment-name}>__ to host the {image-puller-name-short}, open the OpenShift web console, navigate to the *Home* -> *Projects* section and click btn:[Create Project]. + +. Specify the project details: ++ +* *Name*: __<{image-puller-deployment-name}>__ +* *Display Name*: __<{image-puller-name-short}>__ +* *Description*: __<{image-puller-name}>__ + + +. Navigate to btn:[*Operators*] → btn:[*OperatorHub*]. + +. Use the btn:[*Filter by keyword*] box to search for `{image-puller-operator-name}`. Click the btn:[{image-puller-operator-name}]. + +. Read the description of the Operator. Click btn:[*Continue*] → btn:[*Install*]. + +. Select btn:[*A specific {orch-namespace} on the cluster*] for the btn:[*Installation Mode*]. In the drop-down find the OpenShift project __<{image-puller-deployment-name}>__. Click btn:[*Subscribe*]. + +. Wait for the {image-puller-operator-name} to install. Click the btn:[*{image-puller-cr-name}*] → btn:[*Create instance*]. + +. In a redirected window with a YAML editor, make modifications to the `{image-puller-cr-name}` Custom Resource and click btn:[*Create*]. + +. Navigate to the btn:[*Workloads*] and btn:[*Pods*] menu in the __<{image-puller-deployment-name}>__ OpenShift project. Verify that the {image-puller-name-short} is available. + diff --git a/modules/administration-guide/pages/installing-image-puller-using-che-operator.adoc b/modules/administration-guide/pages/installing-image-puller-using-che-operator.adoc deleted file mode 100644 index 5dc38ff4d9..0000000000 --- a/modules/administration-guide/pages/installing-image-puller-using-che-operator.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="installing-image-puller-using-che-operator"] -:navtitle: Installing using the Che Operator -:keywords: administration-guide, image-puller, kubernetes, operator -:page-aliases: .:installing-image-puller-using-che-operator - -include::partial$proc_installing-image-puller-using-che-operator.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/managing-backups-using-cli.adoc b/modules/administration-guide/pages/managing-backups-using-cli.adoc deleted file mode 100644 index dba9d41e7a..0000000000 --- a/modules/administration-guide/pages/managing-backups-using-cli.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="managing-backups-using-cli"] -// = Managing backups through cli -:navtitle: Managing backups using CLI -:keywords: administration-guide, backup, recovery -:page-aliases: .:managing-backups-through-cli, managing-backups-using-chectl - -include::partial$proc_managing-backups-through-cli.adoc[] diff --git a/modules/administration-guide/pages/managing-backups-using-custom-resources.adoc b/modules/administration-guide/pages/managing-backups-using-custom-resources.adoc deleted file mode 100644 index b6ab64fa56..0000000000 --- a/modules/administration-guide/pages/managing-backups-using-custom-resources.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="managing-backups-through-custom-resources"] -// = Managing backups through custom resources -:navtitle: Managing backups through custom resources -:keywords: administration-guide, backup, recovery -:page-aliases: .:managing-backups-through-custom-resources - -include::partial$proc_managing-backups-through-custom-resources.adoc[] diff --git a/modules/administration-guide/pages/managing-identities-and-authorizations.adoc b/modules/administration-guide/pages/managing-identities-and-authorizations.adoc index 8534724939..c5ea5a8750 100644 --- a/modules/administration-guide/pages/managing-identities-and-authorizations.adoc +++ b/modules/administration-guide/pages/managing-identities-and-authorizations.adoc @@ -1,7 +1,11 @@ -[id="managing-identities-and-authorizations"] -// = Managing identities and authorizations +:_content-type: ASSEMBLY :navtitle: Managing identities and authorizations -:keywords: end-user-guide, managing-identities-and-authorizations -:page-aliases: .:managing-identities-and-authorizations +:keywords: administration-guide, managing-identities-and-authorizations +:page-aliases: .:managing-identities-and-authorizations, authenticating-users, authorizing-users, configuring-authorization, configuring-openshift-oauth, configuring-minikube-github-authentication -include::partial$assembly_managing-identities-and-authorizations.adoc[] +[id="managing-identities-and-authorizations_{context}"] += Managing identities and authorizations + +This section describes different aspects of managing identities and authorizations of {prod}. + +* xref:removing-user-data.adoc[] diff --git a/modules/administration-guide/pages/migration-from-postgresql-9-to-postgresql-13.adoc b/modules/administration-guide/pages/migration-from-postgresql-9-to-postgresql-13.adoc deleted file mode 100644 index 628223e5dd..0000000000 --- a/modules/administration-guide/pages/migration-from-postgresql-9-to-postgresql-13.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="migration-from-postgresql-9-to-postgresql-13"] -:navtitle: Migration from PostgreSQL 9 to PostgreSQL 13 -:keywords: administration-guide, migration -:page-aliases: .:migration, .:database - -include::partial$proc_migration_from_postgresql_9_to_postgresql_13.adoc[] diff --git a/modules/administration-guide/pages/monitoring-che.adoc b/modules/administration-guide/pages/monitoring-che.adoc index 1b93b16b91..fcb9ce4fc0 100644 --- a/modules/administration-guide/pages/monitoring-che.adoc +++ b/modules/administration-guide/pages/monitoring-che.adoc @@ -1,7 +1,24 @@ -[id="monitoring-che"] -// = Monitoring Che -:navtitle: Monitoring Che +:_content-type: ASSEMBLY +:navtitle: Monitoring {prod-short} :keywords: administration-guide, monitoring-che -:page-aliases: .:monitoring-che +:page-aliases: .:monitoring-che, .:tracing-che, tracing-che + +[id="monitoring-{prod-id-short}_{context}"] += Monitoring {prod-short} + +This chapter describes how to configure {prod-short} to expose metrics and how to build an example monitoring stack with external tools to process data exposed as metrics by {prod-short}. + +include::partial$proc_enabling-and-exposing-che-metrics.adoc[leveloffset=+1] + + +include::partial$proc_collecting-che-metrics-with-prometheus.adoc[leveloffset=+1] + + +include::example$proc_{project-context}-viewing-che-metrics-on-grafana-dashboards.adoc[leveloffset=+1] + + +include::example$ref_{project-context}-grafana-dashboards-for-che.adoc[leveloffset=+1] + + +include::example$proc_{project-context}-developing-grafana-dashboards.adoc[leveloffset=+1] -include::partial$assembly_monitoring-che.adoc[] diff --git a/modules/administration-guide/pages/monitoring-the-dev-workspace-operator.adoc b/modules/administration-guide/pages/monitoring-the-dev-workspace-operator.adoc new file mode 100644 index 0000000000..be512067bf --- /dev/null +++ b/modules/administration-guide/pages/monitoring-the-dev-workspace-operator.adoc @@ -0,0 +1,26 @@ +:_content-type: ASSEMBLY +:navtitle: Monitoring the {devworkspace} operator +:keywords: administration-guide, monitoring-the-dev-workspace-operator +:page-aliases: .:monitoring-the-dev-workspace-operator + +:parent-context-of-monitoring-the-dev-workspace-operator: {context} + +[id="monitoring-the-dev-workspace-operator"] += Monitoring the {devworkspace} operator + +:context: monitoring-{prod-id-short} + +This chapter describes how to configure an example monitoring stack to process metrics exposed by the {devworkspace} operator. + +include::partial$proc_collecting-dev-workspace-operator-metrics-with-prometheus.adoc[leveloffset=+1] + +include::partial$ref_devworkspace-specific-metrics.adoc[leveloffset=+1] + + +include::example$proc_{project-context}-viewing-dev-workspace-operator-metrics-on-grafana-dashboards.adoc[leveloffset=+1] + + +include::example$ref_{project-context}-grafana-dashboards-for-the-dev-workspace-operator.adoc[leveloffset=+1] + + +:context: {parent-context-of-monitoring-the-dev-workspace-operator} diff --git a/modules/installation-guide/partials/assembly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc b/modules/administration-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc similarity index 72% rename from modules/installation-guide/partials/assembly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc rename to modules/administration-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc index 078144c9cc..c83c5411ac 100644 --- a/modules/installation-guide/partials/assembly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc +++ b/modules/administration-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc @@ -1,3 +1,8 @@ +:_content-type: ASSEMBLY +:navtitle: Mounting a Secret or a ConfigMap as a file or an environment variable into a {prod} container +:keywords: administration guide, mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container +:page-aliases: installation-guide:mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container, installation-guide:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container + :parent-context-of-mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container: {context} [id="mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container_{context}"] diff --git a/modules/administration-guide/pages/oauth-for-github-gitlab-or-bitbucket.adoc b/modules/administration-guide/pages/oauth-for-github-gitlab-or-bitbucket.adoc new file mode 100644 index 0000000000..e2e40820b3 --- /dev/null +++ b/modules/administration-guide/pages/oauth-for-github-gitlab-or-bitbucket.adoc @@ -0,0 +1,14 @@ +:_content-type: CONCEPT +:description: OAuth for GitHub, GitLab, or Bitbucket +:keywords: bitbucket +:navtitle: OAuth for GitHub, GitLab, or Bitbucket +// :page-aliases: + +[id="oauth-for-github-gitlab-or-bitbucket_{context}"] += OAuth for GitHub, GitLab, or Bitbucket + +To enable users to work with remote Git repositories: + +* xref:configuring-oauth-2-for-github.adoc[] +* xref:configuring-oauth-2-for-gitlab.adoc[] +* xref:configuring-oauth-1-for-bitbucket.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/persistent-volumes-backups.adoc b/modules/administration-guide/pages/persistent-volumes-backups.adoc deleted file mode 100644 index 62ef241fe7..0000000000 --- a/modules/administration-guide/pages/persistent-volumes-backups.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="persistent-volumes-backups"] -// = Persistent Volumes backups -:navtitle: Persistent Volumes backups -:keywords: administration-guide, persistent-volumes-backups -:page-aliases: .:persistent-volumes-backups - -include::partial$con_persistent-volumes-backups.adoc[] diff --git a/modules/administration-guide/pages/plug-in-registry.adoc b/modules/administration-guide/pages/plug-in-registry.adoc index 63ced1f6d2..175747d37e 100644 --- a/modules/administration-guide/pages/plug-in-registry.adoc +++ b/modules/administration-guide/pages/plug-in-registry.adoc @@ -1,6 +1,23 @@ -[id="plug-in-registry"] +:_content-type: CONCEPT :navtitle: Plug-in registry :keywords: administration-guide, architecture, server, devworkspace, plug-in, registry -// :page-aliases: +:page-aliases: + +[id="plug-in-registry_{context}"] += Plug-in registry + +Each {prod-short} workspace starts with a specific editor and set of associated extensions. +The {prod-short} plug-in registry provides the list of available editors and editor extensions. +A Devfile v2 describes each editor or extension. + +The xref:dashboard.adoc[] is reading the content of the registry. + +.Plug-in registries interactions with other components +image::architecture/{project-context}-plugin-registry-interactions.png[Plug-in registries interactions with other components] + +.Additional resources + +* link:https://github.com/eclipse-che/che-plugin-registry/blob/main/che-editors.yaml[Editors definitions in the {prod-short} plug-in registry repository] +* link:https://github.com/eclipse-che/che-plugin-registry/blob/main/che-theia-plugins.yaml[Plug-ins definitions in the {prod-short} plug-in registry repository] +* link:https://eclipse-che.github.io/che-plugin-registry/main/index.json[Plug-in registry latest community version online instance] -include::partial$con_plug-in-registry.adoc[] diff --git a/modules/administration-guide/pages/postgresql.adoc b/modules/administration-guide/pages/postgresql.adoc index 46fe96ba39..7b6c444dcf 100644 --- a/modules/administration-guide/pages/postgresql.adoc +++ b/modules/administration-guide/pages/postgresql.adoc @@ -1,6 +1,20 @@ -[id="postgresl"] +:_content-type: ASSEMBLY :navtitle: PostgreSQL :keywords: administration-guide, architecture, server, devworkspace, postgresql, database -// :page-aliases: +:page-aliases: + +[id="postgresql_{context}"] += PostgreSQL + +{prod-short} server uses the PostgreSQL database to persist user configurations such as workspaces metadata. + +The {prod-short} deployment starts a dedicated PostgreSQL instance in the `postgres` Deployment. +You can use an external database instead. + +.PostgreSQL interactions with other components +image::architecture/{project-context}-postgresql-interactions.png[PostgreSQL interactions with other components] + +.Additional resources + +include::example$snip_che-postgresql-additional-resources.adoc[] -include::partial$con_postgresql.adoc[] diff --git a/modules/administration-guide/pages/preparing-a-restricted-environment.adoc b/modules/administration-guide/pages/preparing-a-restricted-environment.adoc new file mode 100644 index 0000000000..99bd4e679f --- /dev/null +++ b/modules/administration-guide/pages/preparing-a-restricted-environment.adoc @@ -0,0 +1,15 @@ +:_content-type: ASSEMBLY +:navtitle: Preparing a restricted environment +:keywords: preparing, restricted environment +:page-aliases: + +[id="preparing-a-restricted-environment_{context}"] += Preparing a restricted environment + +include::example$con_{project-context}-understanding-network-connectivity-in-restricted-environments.adoc[leveloffset=+1] + +include::partial$ref_understanding-the-registries.adoc[leveloffset=+1] + +include::partial$assembly_building-offline-registry-images.adoc[leveloffset=+1] + +include::example$proc_{project-context}-preparing-a-private-registry.adoc[leveloffset=+1] diff --git a/modules/administration-guide/pages/preparing-the-installation.adoc b/modules/administration-guide/pages/preparing-the-installation.adoc new file mode 100644 index 0000000000..62a2799d00 --- /dev/null +++ b/modules/administration-guide/pages/preparing-the-installation.adoc @@ -0,0 +1,14 @@ +:_content-type: ASSEMBLY +:navtitle: Preparing the installation +:keywords: preparing, installation +:page-aliases: + +[id="preparing-the-installation_{context}"] += Preparing the installation + +To prepare a {prod-short} installation, learn about {prod-short} ecosystem and deployment constraints: + +** xref:supported-platforms.adoc[] +** xref:architecture-overview.adoc[] +** xref:calculating-che-resource-requirements.adoc[] +** xref:understanding-the-checluster-custom-resource.adoc[] diff --git a/modules/administration-guide/pages/readiness-init-containers.adoc b/modules/administration-guide/pages/readiness-init-containers.adoc deleted file mode 100644 index a22565c85a..0000000000 --- a/modules/administration-guide/pages/readiness-init-containers.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="readiness-init-containers"] -:navtitle: Readiness init containers -:keywords: init-container, readiness-init-container, startup -:page-aliases: .:readiness-init-containers - -include::partial$assembly_readiness-init-containers.adoc[] diff --git a/modules/administration-guide/pages/removing-user-data.adoc b/modules/administration-guide/pages/removing-user-data.adoc index caecb99cf7..86250f87e7 100644 --- a/modules/administration-guide/pages/removing-user-data.adoc +++ b/modules/administration-guide/pages/removing-user-data.adoc @@ -1,7 +1,148 @@ -[id="removing-user-data"] -// = Removing user data +:_content-type: PROCEDURE :navtitle: Removing user data :keywords: administration-guide, removing-user-data :page-aliases: .:removing-user-data -include::partial$proc_removing-user-data.adoc[] +[id="removing-user-data_{context}"] += Removing user data + +== Removing user data according to GDPR + +The General Data Protection Regulation (link:https://en.wikipedia.org/wiki/General_Data_Protection_Regulation[GDPR]) law enforces the right for individuals to have personal data erased. + +The following procedure describes how to remove the {prod-short} user’s data. + +[NOTE] +==== +The following commands use the default {platforms-namespace}, `{prod-namespace}`, as a user's example for the `-n` option. +==== + +.Prerequisites + +* A user or an administrator authorization token. To delete the {prod-short} data bound to a user account, `admin` privileges are required. The `admin` is a special {prod-short} administrator account that should be pre-created and enabled using the `pass:[CHE_SYSTEM_ADMIN__NAME]` and `pass:[CHE_SYSTEM_SUPER__PRIVILEGED__MODE = true]` properties of the {prod-short} Custom Resource. ++ +[subs="+quotes,macros"] +---- +spec: + server: + customCheProperties: + pass:[CHE_SYSTEM_SUPER__PRIVILEGED__MODE]: 'true' + pass:[CHE_SYSTEM_ADMIN__NAME]: '__<admin-name>__' +---- ++ +If needed, use {orch-cli} commands below for patching the {prod-short} Custom Resource: ++ +[subs="+quotes,macros,attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} \ + --type merge \ + -p '{ "spec": { "server": {"customCheProperties": {"pass:[CHE_SYSTEM_SUPER__PRIVILEGED__MODE]": "true"} } }}' \ + -n __{prod-namespace}__ +---- ++ +[subs="+quotes,macros,attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} \ + --type merge \ + -p '{ "spec": { "server": {"customCheProperties": {"pass:[CHE_SYSTEM_ADMIN__NAME]": "__<admin-name>__"} } }}' \ + -n __{prod-namespace}__ +---- ++ +[NOTE] +==== +All {prod-short} system permissions are granted to the administrative user. To configure the administrative user, use the `CHE_SYSTEM_ADMIN__NAME` property. The default value is `admin`. The system permissions are granted when the {prod-short} server starts. If the user record is not in the {prod-short} user database, the permissions are granted after the first login of the user. + +.Authorization token privileges: + +* `admin` - Can delete all personal data of all users +* `user` - Can delete only the data related to the user +==== + +* A user or an administrator is logged in the OpenShift cluster with deployed {prod-short}. + +* A user ID is obtained. Get the user ID using the commands below: + +** For the current user: ++ +[subs="+quotes,macros,attributes"] +---- +$ curl -X GET \ + --header 'Authorization: Bearer __<user-token>__' \ + 'pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user' +---- + +** To find a user by name: ++ +[subs="+quotes,macros,attributes"] +---- +$ curl -X GET \ + --header 'Authorization: Bearer __<user-token>__' \ + 'pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user/find?name=__<username>__' +---- + +.Example of obtaining a user ID + +This example uses `vparfono` as a local user name. + +==== +[subs="+quotes,macros,attributes"] +---- +$ curl -X GET \ + --header 'Authorization: Bearer __<user-token>__' \ + 'https://che-vp-che.apps.che-dev.x6e0.p1.openshiftapps.com/api/user/find?name=vparfono' +---- + +The user ID is at the bottom of the curl command output. + +[source,json] +---- +{ + "name": "vparfono", + "links": [ + { +. +. +. + } + ], + "email": "vparfono@redhat.com", + "id": "921b6f33-2657-407e-93a6-fb14cf2329ce" +} +---- +==== + +.Procedure + +* Remove the data using the API: ++ +[subs="+quotes,macros,attributes"] +---- +$ curl -i -X DELETE \ + --header 'Authorization: Bearer __<user-token>__' \ + pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user/__<user-id>__ +---- + +[NOTE] +==== +The procedure can be also executed using the Swagger UI available on pass:c,m,a,q[+https:+//__<{prod-host}>__]/swagger +==== + +.Verification + +Running the following command returns code `204` as the API response: + +[subs="+quotes,macros,attributes"] +---- +$ curl -i -X DELETE \ + --header 'Authorization: Bearer __<user-token>__' \ + pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user/__<user-id>__ +---- + +[WARNING] +==== +The following procedure only removes the user on the {prod-short} level. For removing all {orch-name} user data including namespaces from the cluster, the {orch-name} cluster-admin needs to explicitly remove the {orch-name} resources bound to the user. +==== + +.Additional resources + +To remove the data of all users, follow the instructions for xref:uninstalling-che.adoc[]. diff --git a/modules/administration-guide/pages/retrieving-che-logs.adoc b/modules/administration-guide/pages/retrieving-che-logs.adoc deleted file mode 100644 index a17f3a03c3..0000000000 --- a/modules/administration-guide/pages/retrieving-che-logs.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="retrieving-che-logs"] -// = Retrieving Che logs -:navtitle: Retrieving Che logs -:keywords: administration-guide, retrieving-che-logs -:page-aliases: .:retrieving-che-logs - -include::partial$assembly_retrieving-che-logs.adoc[] diff --git a/modules/administration-guide/pages/running-custom-registries.adoc b/modules/administration-guide/pages/running-custom-registries.adoc deleted file mode 100644 index 306716f6c8..0000000000 --- a/modules/administration-guide/pages/running-custom-registries.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="running-custom-registries"] -// = Running custom registries -:navtitle: Running custom registries -:keywords: contributor-guide, running-custom-registries -:page-aliases: .:running-custom-registries, - -include::partial$assembly_running-custom-registries.adoc[] - diff --git a/modules/administration-guide/pages/server-components-with-che-server.adoc b/modules/administration-guide/pages/server-components-with-che-server.adoc deleted file mode 100644 index e231e60072..0000000000 --- a/modules/administration-guide/pages/server-components-with-che-server.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="che-workspace-controller-with-che-server"] -// = Che server side components -:navtitle: Server side components -:keywords: administration-guide, che-workspace-controller, che-server -:page-aliases: .:che-workspace-controller-with-che-server, .:che-workspace-controller, che-workspace-controller - - -include::partial$assembly_server-components-with-che-server.adoc[] diff --git a/modules/administration-guide/pages/server-components.adoc b/modules/administration-guide/pages/server-components.adoc index 3ee4234777..478196c08f 100644 --- a/modules/administration-guide/pages/server-components.adoc +++ b/modules/administration-guide/pages/server-components.adoc @@ -1,7 +1,23 @@ -[id="server-components-with-the-devworkspace-engine"] +:_content-type: ASSEMBLY :navtitle: Server components :keywords: administration-guide, architecture, server, devworkspace -// :page-aliases: +:page-aliases: -include::partial$con_che-server-components.adoc[] +[id="{prod-id-short}-server-components_{context}"] += {prod-short} server components +The {prod-short} server components ensure multi-tenancy and workspaces management. + +.{prod-short} server components interacting with the {devworkspace} operator +image::architecture/{project-context}-deployments-interacting-with-devworkspace.png[] + +.Additional resources + +* xref:che-operator.adoc[] +* xref:devworkspace-operator.adoc[] +* xref:gateway.adoc[] +* xref:dashboard.adoc[] +* xref:devfile-registries.adoc[] +* xref:che-server.adoc[] +* xref:postgresql.adoc[] +* xref:plug-in-registry.adoc[] diff --git a/modules/administration-guide/pages/setup-backup-server.adoc b/modules/administration-guide/pages/setup-backup-server.adoc deleted file mode 100644 index 23d881dcfe..0000000000 --- a/modules/administration-guide/pages/setup-backup-server.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="setting-up-a-backup-server"] -// = Setting up a backup server -:navtitle: Setting up a backup server -:keywords: administration-guide, backup, recovery, backup-server -:page-aliases: .:setup-backup-server - -include::partial$con_setup-backup-server.adoc[] diff --git a/modules/installation-guide/partials/con_supported-platforms.adoc b/modules/administration-guide/pages/supported-platforms.adoc similarity index 50% rename from modules/installation-guide/partials/con_supported-platforms.adoc rename to modules/administration-guide/pages/supported-platforms.adoc index b31ad0a1d4..8ce5ddc2b1 100644 --- a/modules/installation-guide/partials/con_supported-platforms.adoc +++ b/modules/administration-guide/pages/supported-platforms.adoc @@ -1,3 +1,8 @@ +:_content-type: ASSEMBLY +:navtitle: Supported platforms +:keywords: administration guide, supported-platforms +:page-aliases: installation-guide:supported-platforms + [id="supported-platforms_{context}"] = Supported platforms diff --git a/modules/administration-guide/pages/the-woopra-telemetry-plugin.adoc b/modules/administration-guide/pages/the-woopra-telemetry-plugin.adoc new file mode 100644 index 0000000000..3ef24d3c41 --- /dev/null +++ b/modules/administration-guide/pages/the-woopra-telemetry-plugin.adoc @@ -0,0 +1,37 @@ +[id="the-woopra-telemetry-plugin"] +// = The Woopra telemetry plugin +:_content-type: REFERENCE +:navtitle: The Woopra telemetry plug-in +:keywords: extensions, telemetry +:page-aliases: extensions:the-woopra-telemetry-plug-in + +[id="the-woopra-telemetry-plugin"] + += The Woopra telemetry plug-in + +The link:https://github.com/che-incubator/devworkspace-telemetry-woopra-plugin[Woopra Telemetry Plugin] is a plug-in built to send telemetry from a {prod} installation to Segment and Woopra. +This plug-in is used by link:https://workspaces.openshift.com[Eclipse Che hosted by Red Hat], but any {prod} deployment can take advantage of this plug-in. +There are no dependencies other than a valid Woopra domain and Segment Write key. +The devfile v2 for the plug-in, link:https://raw.githubusercontent.com/che-incubator/devworkspace-telemetry-woopra-plugin/main/plugin.yaml[plugin.yaml], has four environment variables that can be passed to the plug-in: + +- `WOOPRA_DOMAIN` - The Woopra domain to send events to. +- `SEGMENT_WRITE_KEY` - The write key to send events to Segment and Woopra. +- `WOOPRA_DOMAIN_ENDPOINT` - If you prefer not to pass in the Woopra domain directly, the plug-in will get it from a supplied HTTP endpoint that returns the Woopra Domain. +- `SEGMENT_WRITE_KEY_ENDPOINT` - If you prefer not to pass in the Segment write key directly, the plug-in will get it from a supplied HTTP endpoint that returns the Segment write key. + +To enable the Woopra plug-in on the {prod} installation, deploy the `plugin.yaml` devfile v2 file to an HTTP server with the environment variables set correctly. Then, set the `spec.server.workspaceDefaultPlugins` field of your `CheCluster` custom resource: + +[source,yaml] +---- +spec: + ... + server: + ... + workspacesDefaultPlugins: + - editor: eclipse/che-theia/next <1> + plugins: <2> + - 'https://your-web-server/plugin.yaml' +---- + +<1> The `editorId` to set the telemetry plug-in for. +<2> The URL to the telemetry plug-in's devfile v2 definition. diff --git a/modules/administration-guide/pages/tracing-che.adoc b/modules/administration-guide/pages/tracing-che.adoc deleted file mode 100644 index 4418858cd8..0000000000 --- a/modules/administration-guide/pages/tracing-che.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="tracing-che"] -// = Tracing Che -:navtitle: Tracing Che -:keywords: administration-guide, tracing-che -:page-aliases: .:tracing-che - -include::partial$assembly_tracing-che.adoc[] diff --git a/modules/administration-guide/pages/understanding-the-checluster-custom-resource.adoc b/modules/administration-guide/pages/understanding-the-checluster-custom-resource.adoc new file mode 100644 index 0000000000..1cf0cc1fbc --- /dev/null +++ b/modules/administration-guide/pages/understanding-the-checluster-custom-resource.adoc @@ -0,0 +1,30 @@ +:_content-type: CONCEPT +:navtitle: Understanding the `CheCluster` Custom Resource +:keywords: administration guide, understanding-the-checluster-custom-resource, configuring-che +:page-aliases: installation-guide:understanding-the-checluster-custom-resource, installation-guide:configuring-the-che-installation + +[id="understanding-the-checluster-custom-resource_{context}"] += Understanding the `CheCluster` Custom Resource + +A default deployment of {prod-short} consists of a `CheCluster` Custom Resource parameterized by the {prod} Operator. + +The `CheCluster` Custom Resource is a {kubernetes} object. You can configure it by editing the `CheCluster` Custom Resource YAML file. This file contains sections to configure each component: `auth`, `database`, `server`, `storage`. + +The {prod} Operator translates the `CheCluster` Custom Resource into a config map usable by each component of the {prod-short} installation. + +The {orch-name} platform applies the configuration to each component, and creates the necessary Pods. When {orch-name} detects changes in the configuration of a component, it restarts the Pods accordingly. + +.Configuring the main properties of the {prod-short} server component +==== +. Apply the `CheCluster` Custom Resource YAML file with suitable modifications in the `server` component section. +. The Operator generates the `che` `ConfigMap`. +. {orch-name} detects changes in the `ConfigMap` and triggers a restart of the {prod-short} Pod. +==== + +.Additional resources + +* link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Understanding Operators] + +* {link-understanding-custom-resources} + + diff --git a/modules/installation-guide/examples/proc_che-uninstalling-che-after-chectl-installation.adoc b/modules/administration-guide/pages/uninstalling-che-after-chectl-installation.adoc similarity index 84% rename from modules/installation-guide/examples/proc_che-uninstalling-che-after-chectl-installation.adoc rename to modules/administration-guide/pages/uninstalling-che-after-chectl-installation.adoc index c8fa92a9f1..6192964708 100644 --- a/modules/installation-guide/examples/proc_che-uninstalling-che-after-chectl-installation.adoc +++ b/modules/administration-guide/pages/uninstalling-che-after-chectl-installation.adoc @@ -1,6 +1,7 @@ -// Module included in the following assemblies: -// -// uninstalling-{prod-id-short} +:_content-type: PROCEDURE +:navtitle: Using {prod-cli} +:keywords: administration guide, uninstalling-che, uninstalling-che-after-chectl-installation +:page-aliases: installation-guide:uninstalling-che-after-chectl-installation [id="uninstalling-{prod-id-short}-after-{prod-cli}-installation_{context}"] = Uninstalling {prod-short} after {prod-cli} installation diff --git a/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc b/modules/administration-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc similarity index 60% rename from modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc rename to modules/administration-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc index c406b37813..a81650db9f 100644 --- a/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc +++ b/modules/administration-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc @@ -1,6 +1,7 @@ -// Module included in the following assemblies: -// -// uninstalling-{prod-id-short} +:_content-type: PROCEDURE +:navtitle: Using OpenShift CLI +:keywords: administration guide, uninstalling-che, uninstalling-che-after-operatorhub-installation-using-openshift-cli +:page-aliases: installation-guide:uninstalling-che-after-operatorhub-installation-using-openshift-cli [id="uninstalling-{prod-id-short}-after-operatorhub-installation-using-openshift-cli_{context}"] = Uninstalling {prod-short} after OperatorHub installation using OpenShift CLI @@ -32,36 +33,36 @@ $ oc login -u _<username>_ -p _<password>_ _<cluster_URL>_ $ oc project _<{prod-id-short}_project>_ ---- -. Obtain the {prod-short} cluster name. The following shows a cluster named `{prod-id}`: +. Obtain the `checluster` Custom Resource name. The following shows a `checluster` Custom Resource named `{prod-checluster}`: + [subs="+quotes,attributes"] ---- $ oc get checluster NAME AGE -{prod-id} 27m +{prod-checluster} 27m ---- . Delete the {prod-short} cluster: + [subs="+quotes,attributes"] ---- -$ oc delete checluster {prod-id} -checluster.org.eclipse.che "{prod-id}" deleted +$ oc delete checluster {prod-checluster} +checluster.org.eclipse.che "{prod-checluster}" deleted ---- -. Obtain the name of the {prod-short} cluster service version (CSV) module. The following detects a CSV module named `{prod-id}.v{prod-ver}`: +. Obtain the name of the {prod-short} cluster service version (CSV) module. The following detects a CSV module named `{prod-deployment}.v{prod-ver}`: + [subs="+quotes,attributes"] ---- $ oc get csv NAME DISPLAY VERSION REPLACES PHASE -{prod-id}.v{prod-ver} {prod} {prod-ver} {prod-id}.v{prod-prev-ver} Succeeded +{prod-deployment}.v{prod-ver} {prod} {prod-ver} {prod-deployment}.v{prod-prev-ver} Succeeded ---- . Delete the {prod-short} CSV: + [subs="+quotes,attributes"] ---- -$ oc delete csv {prod-id}.v{prod-ver} -clusterserviceversion.operators.coreos.com "{prod-id}.v{prod-ver}" deleted +$ oc delete csv {prod-deployment}.v{prod-ver} +clusterserviceversion.operators.coreos.com "{prod-deployment}.v{prod-ver}" deleted ---- diff --git a/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc b/modules/administration-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc similarity index 75% rename from modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc rename to modules/administration-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc index 713c0ca352..d192ec9a59 100644 --- a/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc +++ b/modules/administration-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc @@ -1,6 +1,7 @@ -// Module included in the following assemblies: -// -// uninstalling-{prod-id-short} +:_content-type: PROCEDURE +:navtitle: Using the OpenShift web console +:keywords: administration guide, uninstalling-che, uninstalling-che-after-operatorhub-installation-using-openshift-web-console +:page-aliases: installation-guide:uninstalling-che-after-operatorhub-installation-using-openshift-web-console, installation-guide:installing-che-in-cloud [id="uninstalling-{prod-id-short}-after-operatorhub-installation-using-openshift-web-console_{context}"] = Uninstalling {prod-short} after OperatorHub installation using the OpenShift web console @@ -28,7 +29,7 @@ The default project name is __<{prod-namespace}>__. + [NOTE] ==== -The default {prod} Cluster name is __<{prod-id}>__. +The default {prod} `checluster` Custom Resource name is __<{prod-checluster}>__. ==== . In the *Operators > Installed Operators* section, click *{prod}* in the list of installed operators and select the *Uninstall Operator* option in the *Actions* drop-down menu on the top right. diff --git a/modules/installation-guide/partials/assembly_uninstalling-che.adoc b/modules/administration-guide/pages/uninstalling-che.adoc similarity index 85% rename from modules/installation-guide/partials/assembly_uninstalling-che.adoc rename to modules/administration-guide/pages/uninstalling-che.adoc index e0d3621567..7dd806cecb 100644 --- a/modules/installation-guide/partials/assembly_uninstalling-che.adoc +++ b/modules/administration-guide/pages/uninstalling-che.adoc @@ -1,4 +1,7 @@ - +:_content-type: PROCEDURE +:navtitle: Uninstalling Che +:keywords: administration guide, uninstalling-che +:page-aliases: installation-guide:uninstalling-che :parent-context-of-uninstalling-che: {context} diff --git a/modules/administration-guide/pages/upgrading-che-7-41-on-openshift.adoc b/modules/administration-guide/pages/upgrading-che-7-41-on-openshift.adoc new file mode 100644 index 0000000000..b13ae455fa --- /dev/null +++ b/modules/administration-guide/pages/upgrading-che-7-41-on-openshift.adoc @@ -0,0 +1,55 @@ +:_content-type: PROCEDURE +:navtitle: Upgrading {prod-short} {prod-last-version-pre-dwo} on OpenShift +:keywords: administration-guide, migration, devworkspace +:page-aliases: + +[id="upgrading-{prod-id-short}-{prod-last-version-pre-dwo}-on-openshift_{context}"] += Upgrading {prod-short} {prod-last-version-pre-dwo} on OpenShift + +The workspace engine and authentication system used until version {prod-last-version-pre-dwo} are deprecated. Upgrading from version {prod-last-version-pre-dwo} requires manual steps. + +.Prerequisites + +* An instance of {prod-short} deployed on xref:supported-platforms.adoc[], using the default internal PostgreSQL database, and with OpenShift OAuth enabled. See {prod-docs-url-enable-oauth}. +* Command line tools `oc`, `curl`, and `jq` are available. +* The host running the upgrade commands is running on Linux. + +.Procedure + +. Optionally push back changes to Git repositories in all workspaces, stop all workspaces to avoid user experience degradation, and backup {prod-short} data. See {prod-docs-url-backup-recovery}. + +. Set the environment variables to use in the migration scripts: ++ +[source,bash,subs="+attributes"] +---- +INSTALLATION_NAMESPACE={prod-namespace} #<1> +PRODUCT_DEPLOYMENT_NAME={prod-deployment} +PRODUCT_OPERATOR_NAME={prod-operator} +PRODUCT_ID={prod-id} +CHE_CLUSTER_CR_NAME={prod-checluster} +IDENTITY_PROVIDER_DEPLOYMENT_NAME={identity-provider-id} +OLM_STABLE_CHANNEL={prod-stable-channel} +OLM_CATALOG_SOURCE={prod-stable-channel-catalog-source} +OLM_PACKAGE={prod-stable-channel-package} +---- +<1> Adapt to the {orch-namespace} where {prod-short} is installed. + +. Download and execute the migration scripts: xref:attachment$migration/1-prepare.sh[1-prepare.sh], xref:attachment$migration/2-migrate.sh[2-migrate.sh], xref:attachment$migration/3-subscribe.sh[3-subscribe.sh], and xref:attachment$migration/4-wait.sh[4-wait.sh]. ++ +[source,bash,subs="+attributes"] +---- +chmod +x ./1-prepare.sh ./2-migrate.sh ./3-subscribe.sh ./4-wait.sh +./1-prepare.sh <1> +./2-migrate.sh <2> +./3-subscribe.sh <3> +./4-wait.sh <4> +---- +<1> Shuts down {prod-short} and {identity-provider}, fetch users data and dumps {prod-short} database. +<2> Fetches {prod-short} {identity-provider} and database data, and repopulates the database with updated data. +<3> Deletes {prod-short} Operator and {identity-provider} resources, updates CheCluster CR and creates a new Operator subscription. +<4> Waits until {prod-short} is ready (it can take more than 5 minutes). + +.Verification + +* Open {prod-short} dashboard and log in. + diff --git a/modules/installation-guide/partials/assembly_upgrading-che-using-operatorhub.adoc b/modules/administration-guide/pages/upgrading-che-using-operatorhub.adoc similarity index 81% rename from modules/installation-guide/partials/assembly_upgrading-che-using-operatorhub.adoc rename to modules/administration-guide/pages/upgrading-che-using-operatorhub.adoc index 81063dc1f6..0e8ed5cc87 100644 --- a/modules/installation-guide/partials/assembly_upgrading-che-using-operatorhub.adoc +++ b/modules/administration-guide/pages/upgrading-che-using-operatorhub.adoc @@ -1,6 +1,7 @@ -// Module included in the following assemblies: -// -// upgrading-{prod-id-short} +:_content-type: ASSEMBLY +:navtitle: Upgrading {prod-short} using OperatorHub +:keywords: administration guide, upgrading-che-using-operatorhub +:page-aliases: installation-guide:upgrading-che-using-operatorhub [id="upgrading-{prod-id-short}-using-operatorhub_{context}"] = Upgrading {prod-short} using OperatorHub diff --git a/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc b/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc new file mode 100644 index 0000000000..facad6a800 --- /dev/null +++ b/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc @@ -0,0 +1,51 @@ +:_content-type: PROCEDURE +:navtitle: Upgrading {prod-short} in restricted environment +:keywords: Upgrading {prod-short} in restricted environment +:page-aliases: installation-guide:upgrading-che-using-the-cli-management-tool-in-restricted-environment, installation-guide:upgrading-che-in-restricted-environment + +:parent-context-of-upgrading-prod-short-using-the-cli-management-tool-in-restricted-environment: {context} + +[id="upgrading-{prod-id-short}-using-the-cli-management-tool-in-restricted-environment_{context}"] += Upgrading {prod-short} using the CLI management tool in restricted environment + +:context: upgrading-prod-short-using-the-cli-management-tool-in-restricted-environment + +This section describes how to upgrade {prod} using the CLI management tool in restricted environment. The upgrade path supports minor version update, from {prod-short} {prod-prev-ver} to version {prod-ver}. + +.Prerequisites + +* An administrative account on an instance of {platforms-name}. + +* An instance running {prod-short} {prod-prev-ver}, installed using the CLI management tool on the same instance of {platforms-name}, with the {prod-cli} `--installer operator` method, in the `_<{prod-namespace}>_` project. See xref:installing-che-in-a-restricted-environment.adoc[]. + +* The `{prod-cli}` {prod-ver} management tool is available. See xref:using-the-chectl-management-tool.adoc[]. + +* Essential container images are available to the {prod-short} server running in the cluster. See xref:preparing-a-restricted-environment.adoc[]. + +.Procedure + +. In all running workspaces in the {prod-short} {prod-prev-ver} instance, save and push changes back to the Git repositories. + +. Stop all workspaces in the {prod-short} {prod-prev-ver} instance. + +. Run the following command: ++ +[subs="+attributes,+quotes"] +---- +$ {prod-cli} server:update --che-operator-image=__<image-registry>__/__<organization>__/{prod-operator-image-name}:{prod-ver} -n {prod-namespace} +---- ++ +* _<image-registry>_: A hostname and a port of the container-image registry accessible in the restricted environment. +* _<organization>_: An organization of the container-image registry. See: See xref:preparing-a-restricted-environment.adoc[]. + +.Verification steps + +. Navigate to the {prod-short} instance. + +. The {prod-ver} version number is visible at the bottom of the page. + +[NOTE] +==== +For slow systems or internet connections, add the `--k8spodwaittimeout=1800000` flag option to the `{prod-cli} server:update` command to extend the Pod timeout period to 1800000 ms or longer. +==== + diff --git a/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool.adoc b/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool.adoc similarity index 83% rename from modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool.adoc rename to modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool.adoc index 46c0e8e18b..5faa422eff 100644 --- a/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool.adoc +++ b/modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool.adoc @@ -1,6 +1,7 @@ -// Module included in the following assemblies: -// -// upgrading-{prod-id-short} +:_content-type: PROCEDURE +:navtitle: Upgrading {prod-short} using the CLI management tool +:keywords: administration guide, upgrading-che-using-the-cli-management-tool +:page-aliases: installation-guide:upgrading-che-using-the-cli-management-tool [id="upgrading-{prod-id-short}-using-the-cli-management-tool_{context}"] = Upgrading {prod-short} using the CLI management tool @@ -22,14 +23,6 @@ This section describes how to upgrade from the previous minor version using the . Shut down all workspaces in the {prod-short} {prod-prev-ver} instance. -ifeval::["{project-context}" == "che"] -. Update to the latest version of `{prod-cli}`: -+ ----- -$ chectl update ----- -endif::[] - . Upgrade {prod-short}: + [subs="+attributes,+quotes"] diff --git a/modules/installation-guide/partials/assembly_upgrading-che.adoc b/modules/administration-guide/pages/upgrading-che.adoc similarity index 59% rename from modules/installation-guide/partials/assembly_upgrading-che.adoc rename to modules/administration-guide/pages/upgrading-che.adoc index 26ec828b31..dab769a47d 100644 --- a/modules/installation-guide/partials/assembly_upgrading-che.adoc +++ b/modules/administration-guide/pages/upgrading-che.adoc @@ -1,3 +1,8 @@ +:_content-type: ASSEMBLY +:navtitle: Upgrading Che +:keywords: administration guide, upgrading-che +:page-aliases: installation-guide:upgrading-che, installation-guide:upgrading-che-known-issues, installation-guide:rolling-back-a-che-upgrade,installation-guide: upgrading-che-namespace-strategies-other-than-per-user + :parent-context-of-upgrading-che: {context} [id="upgrading-{prod-id-short}_{context}"] @@ -5,7 +10,7 @@ :context: upgrading-{prod-id-short} -This chapter describes how to upgrade a {prod-short} instance from version {prod-prev-ver} to {prod-short} {prod-ver}. +This chapter describes how to upgrade a {prod-short} instance from {prod-short} {prod-prev-ver} to {prod-short} {prod-ver}. The method used to install the {prod-short} instance determines the method to proceed with for the upgrade: diff --git a/modules/administration-guide/pages/user-workspaces.adoc b/modules/administration-guide/pages/user-workspaces.adoc index ae8e6de428..f145a8fb0a 100644 --- a/modules/administration-guide/pages/user-workspaces.adoc +++ b/modules/administration-guide/pages/user-workspaces.adoc @@ -1,6 +1,43 @@ -[id="user-workspaces"] +:_content-type: REFERENCE :navtitle: User workspaces :keywords: administration-guide, architecture, workspace, devworkspace -// :page-aliases: +:page-aliases: + +[id="user-workspaces_{context}"] += User workspaces + +.User workspaces interactions with other components +image::architecture/{project-context}-user-workspaces-interactions.png[User workspaces interactions with other components] + +User workspaces are web IDEs running in containers. + +A User workspace is a web application. It consists of microservices running in containers providing all the services of a modern IDE running in your browser: + +* Editor +* Language auto-completion +* Language server +* Debugging tools +* Plug-ins +* Application runtimes + +A workspace is one {orch-name} Deployment containing the workspace containers and enabled plug-ins, plus related {orch-name} components: + +* Containers +* ConfigMaps +* Services +* Endpoints +* Ingresses or Routes +* Secrets +* Persistent Volumes (PVs) + +A {prod-short} workspace contains the source code of the projects, persisted in a {platforms-name} Persistent Volume (PV). Microservices have read-write access to this shared directory. + +Use the devfile v2 format to specify the tools and runtime applications of a {prod-short} workspace. + +The following diagram shows one running {prod-short} workspace and its components. + +.{prod-short} workspace components +image::architecture/workspace-components-with-dw.png[] + +In the diagram, there is one running workspaces. -include::partial$con_user-workspaces.adoc[] diff --git a/modules/administration-guide/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc b/modules/administration-guide/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc new file mode 100644 index 0000000000..502b75ab04 --- /dev/null +++ b/modules/administration-guide/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc @@ -0,0 +1,51 @@ +:_content-type: PROCEDURE +:navtitle: Using {prod-cli} to configure the `CheCluster` Custom Resource during installation +:keywords: administration guide +:page-aliases: installation-guide:using-chectl-to-configure-the-checluster-custom-resource-during-installation + +[id="using-{prod-cli}-to-configure-the-checluster-custom-resource-during-installation_{context}"] += Using {prod-cli} to configure the `CheCluster` Custom Resource during installation + +To deploy {prod-short} with a suitable configuration, edit the `CheCluster` Custom Resource YAML file during the installation of {prod-short}. Otherwise, the {prod-short} deployment uses the default configuration parameterized by the Operator. + + +.Prerequisites +* Access to an administrator account on an instance of {platforms-name}. +* The {prod-cli} tool is available. See xref:using-the-chectl-management-tool.adoc[]. + +.Procedure +* Create a `che-operator-cr-patch.yaml` YAML file that contains the subset of the `CheCluster` Custom Resource to configure: ++ +==== +[source,yaml,subs="+quotes"] +---- +spec: + __<component>__: + __<property-to-configure>__: __<value>__ +---- +==== +* Deploy {prod-short} and apply the changes described in `che-operator-cr-patch.yaml` file: ++ +[subs="+quotes"] +---- +$ {prod-cli} server:deploy \ +--che-operator-cr-patch-yaml=che-operator-cr-patch.yaml \ +--platform __<chosen-platform>__ +---- + +.Verification + +. Verify the value of the configured property: ++ +[subs="+attributes,quotes"] +---- +$ oc get configmap che -o jsonpath='{.data._<configured-property>_}' \ +-n {prod-namespace} +---- + +[role="_additional-resources"] +.Additional resources + +* xref:understanding-the-checluster-custom-resource.adoc[]. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[]. \ No newline at end of file diff --git a/modules/administration-guide/pages/using-the-chectl-management-tool.adoc b/modules/administration-guide/pages/using-the-chectl-management-tool.adoc new file mode 100644 index 0000000000..1a58a5ad79 --- /dev/null +++ b/modules/administration-guide/pages/using-the-chectl-management-tool.adoc @@ -0,0 +1,26 @@ +:_content-type: ASSEMBLY +:navtitle: Using the chectl management tool +:keywords: overview, using-the-chectl-management-tool +:page-aliases: installation-guide:using-the-chectl-management-tool, overview:using-the-chectl-management-tool + +:parent-context-of-using-the-chectl-management-tool: {context} + +[id="using-the-{prod-cli}-management-tool_{context}"] += Using the {prod-cli} management tool + +:context: using-the-{prod-cli}-management-tool + +`{prod-cli}` is the {prod} command-line management tool. It is used for operations on the {prod-short} server (start, stop, update, delete) and on workspaces (list, start, stop, inject) and to generate devfiles. + +include::example$proc_{project-context}-installing-the-chectl-management-tool-on-windows.adoc[leveloffset=+1] + +include::example$proc_{project-context}-installing-the-chectl-management-tool-on-linux-or-macos.adoc[leveloffset=+1] + +include::example$proc_{project-context}-upgrading-the-chectl-management-tool.adoc[leveloffset=+1] + + +.Additional resources + +* {link-prod-cli-documentation} + +:context: {parent-context-of-using-the-chectl-management-tool} diff --git a/modules/administration-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc b/modules/administration-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc new file mode 100644 index 0000000000..6645673c9c --- /dev/null +++ b/modules/administration-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc @@ -0,0 +1,40 @@ +:_content-type: PROCEDURE +:navtitle: Using the CLI to configure the CheCluster Custom Resource +:keywords: administration guide +:page-aliases: installation-guide:using-the-cli-to-configure-the-checluster-custom-resource, installation-guide:using-cli-to-configure-the-checluster-custom-resource + +[id="using-the-cli-to-configure-the-checluster-custom-resource_{context}"] += Using the CLI to configure the CheCluster Custom Resource + +To configure a running instance of {prod-short}, edit the `CheCluster` Custom Resource YAML file. + +.Prerequisites +* An instance of {prod-short} on {platforms-name}. +* Access to an administrator account on the instance of {platforms-name}. +* The `oc` tool is available. + +.Procedure +. Edit the CheCluster Custom Resource on the cluster: ++ +[subs="+attributes"] +---- +$ oc edit checluster/eclipse-che -n {prod-namespace} +---- +. Save and close the file to apply the changes. + +.Verification + +. Verify the value of the configured property: ++ +[subs="+attributes,quotes"] +---- +$ oc get configmap che -o jsonpath='{.data._<configured-property>_}' \ +-n {prod-namespace} +---- + +[role="_additional-resources"] +.Additional resources + +* xref:understanding-the-checluster-custom-resource.adoc[]. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[]. diff --git a/modules/administration-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc b/modules/administration-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc new file mode 100644 index 0000000000..0b7d6ff81f --- /dev/null +++ b/modules/administration-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc @@ -0,0 +1,70 @@ +:_content-type: PROCEDURE +:navtitle: Using the OpenShift web console to configure the `CheCluster` Custom Resource during installation +:keywords: administration guide +:page-aliases: installation-guide:using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation + + + +[id="using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation_{context}"] += Using the OpenShift web console to configure the `CheCluster` Custom Resource during installation + +To deploy {prod-short} with a suitable configuration, edit the `CheCluster` Custom Resource YAML file during the installation of {prod-short}. Otherwise, the {prod-short} deployment uses the default configuration parameterized by the Operator. + +The `CheCluster` Custom Resource YAML file contains sections to configure each component: `auth`, `database`, `server`, `storage`. + +.Prerequisites +* Access to an administrator account on an instance of OpenShift. + +.Procedure + +// This procedure contains steps from proc_creating-an-instance-of-the-che-operator.adoc[]. + +. In the left panel, click *Operators*, then click *Installed Operators*. + +. On the *Installed Operators* page, click the *{prod}* name. + +. On the *Operator details* page, in the *Details* tab, click the *Create instance* link in the *Provided APIs* section. ++ +This navigates you to the *Create CheCluster* page, which contains the configuration needed to create a {prod-short} instance, stored in the `CheCluster` Custom Resource. + +. On the *Create CheCluster* page, click *YAML view*. + +. In the YAML file, find or add the property to configure. Set the property to a suitable value: ++ +==== +[source,yaml,subs="+quotes"] +---- +apiVersion: org.eclipse.che/v1 +kind: CheCluster +# ... +spec: + __<component>__: + # ... + __<property-to-configure>__: __<value>__ +---- +==== + +. Create the *{prod-checluster}* cluster by using the btn:[Create] button at the end of the page. + +. On the *Operator details* page, in the *{prod} Cluster* tab, click the *{prod-checluster}* link. + +. Navigate to the *{prod-checluster}* instance using the link displayed under the *{prod} URL* output. ++ +[NOTE] +==== +The installation might take more than 5 minutes. The URL appears when the {prod} installation finishes. +==== + +.Verification + +. In the left panel, click *Workloads*, then click *ConfigMaps*. +. On the *ConfigMaps* page, click *{prod-deployment}*. +. Navigate to the *YAML* tab. +. Verify that the YAML file contains the configured property and value. + +[role="_additional-resources"] +.Additional resources + +* xref:understanding-the-checluster-custom-resource.adoc[]. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[]. diff --git a/modules/administration-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc b/modules/administration-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc new file mode 100644 index 0000000000..d709e113aa --- /dev/null +++ b/modules/administration-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc @@ -0,0 +1,53 @@ +:_content-type: PROCEDURE +:navtitle: Using the OpenShift web console to configure the `CheCluster` Custom Resource +:keywords: administration guide +:page-aliases: installation-guide:using-the-openshift-web-console-to-configure-the-checluster-custom-resource + +[id="using-the-openshift-web-console-to-configure-the-checluster-custom-resource_{context}"] += Using the OpenShift web console to configure the `CheCluster` Custom Resource + +To configure a running instance of {prod-short}, edit the `CheCluster` Custom Resource YAML file. + +The `CheCluster` Custom Resource YAML file contains sections to configure each component: `auth`, `database`, `server`, `storage`. + +.Prerequisites + +* An instance of {prod-short} on OpenShift. +* Access to an administrator account on the instance of OpenShift and to the OpenShift web console. + +.Procedure + +. In the left panel, click *Operators*, then click *Installed Operators*. +. On the *Installed Operators* page, click *{prod}*. +. Navigate to the *{prod} instance Specification* tab and click *{prod-checluster}*. +. Navigate to the *YAML* tab. +. In the YAML file, find or add the property to configure. Set the property to a suitable value: ++ +==== +[source,yaml,subs="+quotes"] +---- +apiVersion: org.eclipse.che/v1 +kind: CheCluster +# ... +spec: + __<component>__: + # ... + __<property-to-configure>__: __<value>__ +---- +==== +. Click *Save* to apply the changes. + +.Verification + +. In the left panel, click *Workloads*, then click *ConfigMaps*. +. On the *ConfigMaps* page, click *{prod-deployment}*. +. Navigate to the *YAML* tab. +. Verify that the YAML file contains the configured property and value. + +[role="_additional-resources"] +.Additional resources + +* xref:understanding-the-checluster-custom-resource.adoc[]. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[]. + diff --git a/modules/administration-guide/pages/viewing-che-server-logs.adoc b/modules/administration-guide/pages/viewing-che-server-logs.adoc deleted file mode 100644 index 6245b76ad5..0000000000 --- a/modules/administration-guide/pages/viewing-che-server-logs.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="viewing-{prod-id-short}-server-logs"] -// = Viewing Che server logs -:navtitle: Viewing Che server logs -:keywords: administration-guide, viewing-che-server-logs -:page-aliases: .:viewing-che-server-logs - -include::partial$assembly_viewing-che-server-logs.adoc[] diff --git a/modules/administration-guide/pages/viewing-external-service-logs.adoc b/modules/administration-guide/pages/viewing-external-service-logs.adoc deleted file mode 100644 index 3a56b8583e..0000000000 --- a/modules/administration-guide/pages/viewing-external-service-logs.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="viewing-external-service-logs"] -// = Viewing external service logs -:navtitle: Viewing external service logs -:keywords: administration-guide, viewing-external-service-logs -:page-aliases: .:viewing-external-service-logs - -include::partial$assembly_viewing-external-service-logs.adoc[] diff --git a/modules/administration-guide/pages/viewing-kubernetes-events.adoc b/modules/administration-guide/pages/viewing-kubernetes-events.adoc deleted file mode 100644 index 1230afd7e9..0000000000 --- a/modules/administration-guide/pages/viewing-kubernetes-events.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="viewing-kubernetes-events"] -// = Accessing {kubernetes} events on OpenShift -:navtitle: Accessing {kubernetes} events on OpenShift -:keywords: administration-guide, viewing-kubernetes-events -:page-aliases: .:viewing-kubernetes-events - -include::partial$proc_viewing-kubernetes-events.adoc[] diff --git a/modules/administration-guide/pages/viewing-operator-events.adoc b/modules/administration-guide/pages/viewing-operator-events.adoc deleted file mode 100644 index 53bb6541a4..0000000000 --- a/modules/administration-guide/pages/viewing-operator-events.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="viewing-operator-events"] -// = Viewing the Operator events on OpenShift -:navtitle: Viewing the Operator events on OpenShift -:keywords: administration-guide, viewing-operator-events -:page-aliases: .:viewing-operator-events - -include::partial$proc_viewing-the-state-of-the-che-cluster-deployment-using-openshift-4-cli-tools.adoc[] diff --git a/modules/administration-guide/pages/viewing-plug-in-broker-logs.adoc b/modules/administration-guide/pages/viewing-plug-in-broker-logs.adoc deleted file mode 100644 index 5cdb91de02..0000000000 --- a/modules/administration-guide/pages/viewing-plug-in-broker-logs.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="viewing-plug-in-broker-logs"] -// = Viewing Plug-in broker logs -:navtitle: Viewing Plug-in broker logs -:keywords: administration-guide, viewing-plug-in-broker-logs -:page-aliases: .:viewing-plug-in-broker-logs - -include::partial$proc_viewing-plug-in-broker-logs.adoc[] diff --git a/modules/administration-guide/partials/assembly_authenticating-in-a-che-workspace.adoc b/modules/administration-guide/partials/assembly_authenticating-in-a-che-workspace.adoc deleted file mode 100644 index 9320cd58d6..0000000000 --- a/modules/administration-guide/partials/assembly_authenticating-in-a-che-workspace.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// authenticating-users - -:parent-context-of-authenticating-in-a-che-workspace: {context} - -[id="authenticating-in-a-{prod-id-short}-workspace_{context}"] -= Authenticating in a {prod-short} workspace - -:context: authenticating-in-a-{prod-id-short}-workspace - -Workspace containers may contain services that must be protected with authentication. Such protected services are called *secure*. To secure these services, use a machine authentication mechanism. - -JWT tokens avoid the need to pass {identity-provider} tokens to workspace containers (which can be insecure). Also, {identity-provider} tokens may have a relatively shorter lifetime and require periodic renewals or refreshes, which is difficult to manage and keep in sync with the same user session tokens on clients. - -.Authentication inside a workspace -image::security/{project-context}-authentication-inside-the-workspace.png[] - -include::partial$proc_creating-secure-servers.adoc[leveloffset=+1] - -include::partial$con_workspace-jwt-token.adoc[leveloffset=+1] - -include::partial$con_machine-token-validation.adoc[leveloffset=+1] - -:context: {parent-context-of-authenticating-in-a-che-workspace} diff --git a/modules/administration-guide/partials/assembly_authenticating-to-the-che-server.adoc b/modules/administration-guide/partials/assembly_authenticating-to-the-che-server.adoc deleted file mode 100644 index f488fec318..0000000000 --- a/modules/administration-guide/partials/assembly_authenticating-to-the-che-server.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// authenticating-users - -:parent-context-of-authenticating-to-the-che-server: {context} - -[id="authenticating-to-the-{prod-id-short}-server_{context}"] -= Authenticating to the {prod-short} server - -:context: authenticating-to-the-{prod-id-short}-server - - -include::partial$proc_authenticating-to-the-che-server-using-other-authentication-implementations.adoc[leveloffset=+1] - -include::partial$proc_authenticating-to-the-che-server-using-oauth.adoc[leveloffset=+1] - -include::partial$proc_using-swagger-or-rest-clients-to-execute-queries.adoc[leveloffset=+1] - -:context: {parent-context-of-authenticating-to-the-che-server} diff --git a/modules/administration-guide/partials/assembly_authenticating-users.adoc b/modules/administration-guide/partials/assembly_authenticating-users.adoc deleted file mode 100644 index 21779d22e4..0000000000 --- a/modules/administration-guide/partials/assembly_authenticating-users.adoc +++ /dev/null @@ -1,22 +0,0 @@ - -// securing-che - - -:parent-context-of-authenticating-users: {context} - -[id="authenticating-users_{context}"] -= Authenticating users - -:context: authenticating-users - -This document covers all aspects of user authentication in {prod}, both on the {prod-short} server and in workspaces. This includes securing all REST API endpoints, WebSocket or JSON RPC connections, and some web resources. - -All authentication types use the link:https://jwt.io/introduction/[JWT open standard] as a container for transferring user identity information. In addition, {prod-short} server authentication is based on the link:https://openid.net/connect/[OpenID Connect] protocol implementation, which is provided by default by {identity-provider-url}[{identity-provider}]. - -Authentication in workspaces implies the issuance of self-signed per-workspace JWT tokens and their verification on a dedicated service based on link:https://github.com/eclipse/che-jwtproxy/[JWTProxy]. - -include::partial$assembly_authenticating-to-the-che-server.adoc[leveloffset=+1] - -include::partial$assembly_authenticating-in-a-che-workspace.adoc[leveloffset=+1] - -:context: {parent-context-of-authenticating-users} diff --git a/modules/administration-guide/partials/assembly_authorizing-users.adoc b/modules/administration-guide/partials/assembly_authorizing-users.adoc deleted file mode 100644 index a8b4e04e0f..0000000000 --- a/modules/administration-guide/partials/assembly_authorizing-users.adoc +++ /dev/null @@ -1,37 +0,0 @@ - -// securing-che - -:parent-context-of-authorizing-users: {context} - -[id="authorizing-users_{context}"] -= Authorizing users - -:context: authorizing-users - -User authorization in {prod-short} is based on the permissions model. Permissions are used to control the allowed actions of users and establish a security model. Every request is verified for the presence of the required permission in the current user subject after it passes authentication. You can control resources managed by {prod-short} and allow certain actions by assigning permissions to users. - -Permissions can be applied to the following entities: - -* Workspace -* System - -All permissions can be managed using the provided REST API. The APIs are documented using Swagger at `pass:c,a,q[{prod-url}/swagger/#!/permissions]`. - -include::partial$con_che-workspace-permissions.adoc[leveloffset=+1] - -include::partial$con_che-system-permissions.adoc[leveloffset=+1] - -include::partial$ref_managesystem-permission.adoc[leveloffset=+1] - -include::partial$ref_monitorsystem-permission.adoc[leveloffset=+1] - -ifeval::["{project-context}" == "che"] -include::partial$con_super-privileged-mode.adoc[leveloffset=+1] -endif::[] - -include::partial$proc_listing-che-permissions.adoc[leveloffset=+1] - -include::partial$proc_assigning-che-permissions.adoc[leveloffset=+1] - - -:context: {parent-context-of-authorizing-users} diff --git a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc deleted file mode 100644 index f9b488b100..0000000000 --- a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc +++ /dev/null @@ -1,35 +0,0 @@ - - -:parent-context-of-backup-and-disaster-recovery: {context} - -[id="backup-and-disaster-recovery_{context}"] -= Backup and disaster recovery - -:context: backup-and-disaster-recovery - -{prod-short} Operator can create backups of {prod-short} instances and restore them from a backup snapshot if needed. The following chapter describes ways of preparing such backups and their use in the follow-up recovery phase: - -* xref:managing-backups-using-cli.adoc[] -* xref:managing-backups-using-custom-resources.adoc[] - - -[CAUTION] -==== -* The standard backup mechanism of {prod-short} does not back up the content of users' workspaces. To preserve local changes, see xref:persistent-volumes-backups.adoc[]. - -* Backup snapshots are bound to their own specific cluster and must be used only there. -==== - -* {prod-short} Operator creates a new backup on every {prod-short} update. -* xref:define-backup-server-for-operator.adoc[Configured] backup server is automatically used to store the backup. -* When a {prod-short} administrator configures more than one backup server, the {prod-short} Operator uses the server with the `che.eclipse.org/backup-before-update: true` annotation by default. -* {prod-short} Operator uses the internal backup server: -** Every time the {prod-short} administrator does not configure the backup server. -** When several backup servers do not have any annotation. - -.Additional resources - - -* xref:external-database-setup.adoc[] - -:context: {parent-context-of-backup-and-disaster-recovery} diff --git a/modules/administration-guide/partials/assembly_building-custom-registry-images.adoc b/modules/administration-guide/partials/assembly_building-custom-registry-images.adoc deleted file mode 100644 index f90d6471da..0000000000 --- a/modules/administration-guide/partials/assembly_building-custom-registry-images.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="building-custom-registry-images_{context}"] -= Building custom registry images - -include::partial$proc_building-a-custom-devfile-registry-image.adoc[leveloffset=+1] - - -include::partial$proc_building-a-custom-plug-in-registry-image.adoc[leveloffset=+1] - diff --git a/modules/installation-guide/partials/assembly_building-offline-registry-images.adoc b/modules/administration-guide/partials/assembly_building-offline-registry-images.adoc similarity index 100% rename from modules/installation-guide/partials/assembly_building-offline-registry-images.adoc rename to modules/administration-guide/partials/assembly_building-offline-registry-images.adoc diff --git a/modules/administration-guide/partials/assembly_calculating-che-resource-requirements.adoc b/modules/administration-guide/partials/assembly_calculating-che-resource-requirements.adoc deleted file mode 100644 index 6fdc6d9c9a..0000000000 --- a/modules/administration-guide/partials/assembly_calculating-che-resource-requirements.adoc +++ /dev/null @@ -1,31 +0,0 @@ - -:parent-context-of-calculating-che-resource-requirements: {context} - -[id="calculating-{prod-id-short}-resource-requirements_{context}"] -= Calculating {prod-short} resource requirements - -:context: calculating-{prod-id-short}-resource-requirements - -This section describes how to calculate resources, such as memory and CPU, required to run {prod}. - -Both the {prod-short} central controller and user workspaces consist of a set of containers. Those containers contribute to the resources consumption in terms of CPU and RAM limits and requests. - -include::partial$con_controller-requirements.adoc[leveloffset=+1] - -include::partial$proc_workspaces-requirements.adoc[leveloffset=+1] - -include::partial$con_a-workspace-example.adoc[leveloffset=+1] - -.Additional resources - -* xref:che-architecture-overview.adoc[] -ifeval::["{project-context}" == "che"] -* link:https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/[{kubernetes} compute resources management documentation] -endif::[] -* xref:installation-guide:configuring-the-che-installation.adoc[] -* xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[] -* xref:end-user-guide:authoring-devfiles-version-2.adoc[] -* xref:authenticating-users.adoc[] -* link:https://github.com/eclipse-che/che-plugin-registry[{prod-short} plug-ins registry repository] - -:context: {parent-context-of-calculating-che-resource-requirements} diff --git a/modules/administration-guide/partials/assembly_che-workspace-components.adoc b/modules/administration-guide/partials/assembly_che-workspace-components.adoc deleted file mode 100644 index f10a1282c5..0000000000 --- a/modules/administration-guide/partials/assembly_che-workspace-components.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspaces-architecture - -:parent-context-of-che-workspace-components: {context} - -[id="{prod-id-short}-workspace-components_{context}"] -= {prod-short} workspace components - -:context: {prod-id-short}-workspace-components - -This section describes the components of a {prod-short} workspace. - -ifeval::["{project-context}" == "che"] -include::partial$con_che-plug-ins.adoc[leveloffset=+1] -endif::[] - -include::partial$con_che-editor-plug-in.adoc[leveloffset=+1] - -include::partial$con_che-user-runtimes.adoc[leveloffset=+1] - -include::partial$con_che-workspace-jwt-proxy.adoc[leveloffset=+1] - -include::partial$con_che-plug-in-broker.adoc[leveloffset=+1] - -:context: {parent-context-of-che-workspace-components} diff --git a/modules/administration-guide/partials/assembly_collecting-logs-using-chectl.adoc b/modules/administration-guide/partials/assembly_collecting-logs-using-chectl.adoc deleted file mode 100644 index 221b3f93bf..0000000000 --- a/modules/administration-guide/partials/assembly_collecting-logs-using-chectl.adoc +++ /dev/null @@ -1,16 +0,0 @@ - - -:parent-context-of-collecting-logs-using-chectl: {context} - -[id="collecting-logs-using-{prod-cli}_{context}"] -= Collecting logs using {prod-cli} - -:context: collecting-logs-using-{prod-cli} - -It is possible to get all {prod} logs from a {orch-name} cluster using the `{prod-cli}` tool. - -- `{prod-cli} server:deploy` automatically starts collecting {prod} servers logs during installation of {prod} -- `{prod-cli} server:logs` collects existing {prod} server logs -- `{prod-cli} workspace:logs` collects workspace logs - -:context: {parent-context-of-collecting-logs-using-chectl} diff --git a/modules/administration-guide/partials/assembly_configuring-authorization.adoc b/modules/administration-guide/partials/assembly_configuring-authorization.adoc deleted file mode 100644 index c990619f6a..0000000000 --- a/modules/administration-guide/partials/assembly_configuring-authorization.adoc +++ /dev/null @@ -1,42 +0,0 @@ - - -:parent-context-of-configuring-authorization: {context} - -[id="configuring-authorization_{context}"] -= Configuring authorization - -`{prod-short}` uses the permissions model for user authorization. - -:context: configuring-authorization - -include::partial$con_authorization-and-user-management.adoc[leveloffset=+1] - -include::partial$proc_configuring-che-to-work-with-identity-provider.adoc[leveloffset=+1] - -include::partial$proc_configuring-identity-provider-tokens.adoc[leveloffset=+1] - -include::example$proc_{project-context}-setting-up-user-federation.adoc[leveloffset=+1] - -include::partial$proc_enabling-authentication-with-social-accounts-and-brokering.adoc[leveloffset=+1] - -include::partial$proc_configuring-github-oauth.adoc[leveloffset=+2] - -include::partial$proc_configuring-bitbucket-servers.adoc[leveloffset=+2] - -include::partial$proc_configuring-bitbucket-server-oauth1.adoc[leveloffset=+2] - -include::partial$proc_configuring-gitlab-servers.adoc[leveloffset=+2] - -include::partial$proc_configuring-gitlab-oauth2.adoc[leveloffset=+2] - -include::partial$proc_using-protocol-based-providers.adoc[leveloffset=+1] - -include::example$proc_{project-context}-managing-users-using-identity-provider.adoc[leveloffset=+1] - -include::partial$proc_configuring-che-to-use-external-identity-provider.adoc[leveloffset=+1] - -include::partial$proc_configuring-smtp-and-email-notifications.adoc[leveloffset=+1] - -include::partial$proc_enabling-self-registration.adoc[leveloffset=+1] - -:context: {parent-context-of-configuring-authorization} diff --git a/modules/administration-guide/partials/assembly_configuring-server-logging.adoc b/modules/administration-guide/partials/assembly_configuring-server-logging.adoc deleted file mode 100644 index 65d162fd29..0000000000 --- a/modules/administration-guide/partials/assembly_configuring-server-logging.adoc +++ /dev/null @@ -1,21 +0,0 @@ -:parent-context-of-configuring-server-logging: {context} - -[id="configuring-sever-logging_{context}"] -= Configuring server logging - -:context: configuring-server-logging - -It is possible to fine-tune the log levels of individual loggers available in the {prod-short} server. - -The log level of the whole {prod-short} server is configured globally using the xref:installation-guide:configuring-the-che-installation.adoc#checluster-custom-resources-fields-reference_{context}[`cheLogLevel` configuration property] of the Operator. -To set the global log level in installations not managed by the Operator, specify the `CHE_LOG_LEVEL` environment variable in the `che` -ConfigMap. - -It is possible to configure the log levels of the individual loggers in the {prod-short} server using the `CHE_LOGGER_CONFIG` environment -variable. - -include::partial$proc_configuring-server-logging.adoc[leveloffset=+1] - -include::partial$con_logger-naming.adoc[leveloffset=+1] - -include::partial$con_logging-http-traffic.adoc[leveloffset=+1] diff --git a/modules/administration-guide/partials/assembly_customizing-the-registries.adoc b/modules/administration-guide/partials/assembly_customizing-the-registries.adoc deleted file mode 100644 index e50cf131a1..0000000000 --- a/modules/administration-guide/partials/assembly_customizing-the-registries.adoc +++ /dev/null @@ -1,17 +0,0 @@ -:parent-context-of-customizing-the-registries: {context} - -[id="customizing-the-registries_{context}"] -= Customizing the registries - -:context: customizing-the-registries - -This chapter describes how to build and run custom registries for {prod-short}. - -include::installation-guide:partial$ref_understanding-the-registries.adoc[leveloffset=+1] - -.Additional resources - -* xref:building-custom-registry-images.adoc[] -* xref:running-custom-registries.adoc[] - -:context: {parent-context-of-customizing-the-registries} \ No newline at end of file diff --git a/modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc b/modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc deleted file mode 100644 index e9698f73e8..0000000000 --- a/modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc +++ /dev/null @@ -1,13 +0,0 @@ -:parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-olm-installer: {context} - -[id="enabling-and-disabling-readiness-init-containers-for-the-olm-installer_{context}"] -= Enabling and disabling the readiness init containers for the OLM installer - -:context: enabling-and-disabling-readiness-init-containers-for-the-olm-installer - -You can enable and disable the readiness init containers for the {prod-short} installed by the OLM installer. (Available through `{prod-cli}`, the OLM installer uses the Operator Lifecycle Manager to install {prod-short}.) - -* xref:enabling-readiness-init-containers-for-the-olm-installer.adoc[Enabling the readiness init containers for the OLM installer] -* xref:disabling-readiness-init-containers-for-the-olm-installer.adoc[Disabling the readiness init containers for the OLM installer] - -:context: {parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-olm-installer} \ No newline at end of file diff --git a/modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc b/modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc deleted file mode 100644 index c2c5f217da..0000000000 --- a/modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc +++ /dev/null @@ -1,13 +0,0 @@ -:parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-operator-installer: {context} - -[id="enabling-and-disabling-readiness-init-containers-for-the-operator-installer_{context}"] -= Enabling and disabling the readiness init containers for the Operator installer - -:context: enabling-and-disabling-readiness-init-containers-for-the-operator-installer - -You can enable and disable the readiness init containers for the {prod-short} installed by the Operator installer: - -* xref:enabling-readiness-init-containers-for-the-operator-installer.adoc[Enabling the readiness init containers for the Operator installer] -* xref:disabling-readiness-init-containers-for-the-operator-installer.adoc[Disabling the readiness init containers for the Operator installer] - -:context: {parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-operator-installer} diff --git a/modules/administration-guide/partials/assembly_installing-the-jaeger-tracing-tool.adoc b/modules/administration-guide/partials/assembly_installing-the-jaeger-tracing-tool.adoc deleted file mode 100644 index f74c6b084d..0000000000 --- a/modules/administration-guide/partials/assembly_installing-the-jaeger-tracing-tool.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// tracing-{prod-id-short} - -[id="installing-the-jaeger-tracing-tool_{context}"] -= Installing the Jaeger tracing tool - -:context: installing-the-jaeger-tracing-tool - -The following sections describe the installation methods for the Jaeger tracing tool. Jaeger can then be used for gathering metrics in {prod-short}. - -Installation methods available: - -* xref:tracing-che.adoc#installing-jaeger-using-operatorhub-on-openshift-4_{context}[] -* xref:tracing-che.adoc#installing-jaeger-using-cli-on-openshift-4_{context}[] - -For tracing a {prod-short} instance using Jaeger, version 1.12.0 or above is required. For additional information about Jaeger, see the link:https://www.jaegertracing.io/docs/latest/[Jaeger website]. - -include::partial$proc_installing-jaeger-using-operatorhub-on-openshift-4.adoc[leveloffset=+1] - -include::partial$proc_installing-jaeger-using-cli-on-openshift-4.adoc[leveloffset=+1] - diff --git a/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc b/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc deleted file mode 100644 index 019f0f8c68..0000000000 --- a/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc +++ /dev/null @@ -1,17 +0,0 @@ - -:parent-context-of-managing-identities-and-authorizations: {context} - -[id="managing-identities-and-authorizations_{context}"] -= Managing identities and authorizations - -:context: managing-identities-and-authorizations - -This section describes different aspects of managing identities and authorizations of {prod}. - -* xref:authenticating-users.adoc[] -* xref:authorizing-users.adoc[] -* xref:configuring-authorization.adoc[] -* xref:removing-user-data.adoc[] -* xref:configuring-openshift-oauth.adoc[] - -:context: {parent-context-of-managing-identities-and-authorizations} diff --git a/modules/administration-guide/partials/assembly_monitoring-che.adoc b/modules/administration-guide/partials/assembly_monitoring-che.adoc deleted file mode 100644 index 22b8bf8b5e..0000000000 --- a/modules/administration-guide/partials/assembly_monitoring-che.adoc +++ /dev/null @@ -1,26 +0,0 @@ - - -:parent-context-of-monitoring-che: {context} - -[id="monitoring-{prod-id-short}_{context}"] -= Monitoring {prod-short} - -:context: monitoring-{prod-id-short} - -This chapter describes how to configure {prod-short} to expose metrics and how to build an example monitoring stack with external tools to process data exposed as metrics by {prod-short}. - -include::partial$proc_enabling-and-exposing-che-metrics.adoc[leveloffset=+1] - -include::partial$proc_collecting-che-metrics-with-prometheus.adoc[leveloffset=+1] - -ifeval::["{project-context}" == "che"] - -include::partial$proc_viewing-che-metrics-on-grafana-dashboards.adoc[leveloffset=+1] - -include::partial$ref_grafana-dashboards-for-che.adoc[leveloffset=+1] - -include::partial$proc_developing-grafana-dashboards.adoc[leveloffset=+1] - -endif::[] - -:context: {parent-context-of-monitoring-che} diff --git a/modules/administration-guide/partials/assembly_readiness-init-containers.adoc b/modules/administration-guide/partials/assembly_readiness-init-containers.adoc deleted file mode 100644 index 9f7f08a419..0000000000 --- a/modules/administration-guide/partials/assembly_readiness-init-containers.adoc +++ /dev/null @@ -1,16 +0,0 @@ -:parent-context-of-readiness-init-containers: {context} - -[id="readiness-init-containers_{context}"] -= Readiness init containers - -:context: readiness-init-containers - -{prod-short} Operator installs {prod-short} and starts its containers in the correct order. If a node with {prod-short} is restarted and all {prod-short} containers start simultaneously, some containers may fail because some other component they depend on is not ready. To avoid such failures, the readiness init containers queue the containers for {prod-short} components to start in the correct order. - -The readiness init containers are disabled by default. If you choose to enable them, proceed according to the installation method used to install {prod-short}: - -* xref:enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[] - -* xref:enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[] - -:context: {parent-context-of-readiness-init-containers} \ No newline at end of file diff --git a/modules/administration-guide/partials/assembly_retrieving-che-logs.adoc b/modules/administration-guide/partials/assembly_retrieving-che-logs.adoc deleted file mode 100644 index 9f8bc10205..0000000000 --- a/modules/administration-guide/partials/assembly_retrieving-che-logs.adoc +++ /dev/null @@ -1,20 +0,0 @@ - - -:parent-context-of-retrieving-che-logs: {context} - -[id="retrieving-{prod-id-short}-logs_{context}"] -= Retrieving {prod-short} logs - -:context: retrieving-{prod-id-short}-logs - -For information about obtaining various types of logs in {prod-short}, see the following sections: - -* xref:configuring-server-logging.adoc[] -* xref:viewing-kubernetes-events.adoc[] -* xref:viewing-che-server-logs.adoc[] -* xref:viewing-external-service-logs.adoc[] -* xref:viewing-plug-in-broker-logs.adoc[] -* xref:collecting-logs-using-chectl.adoc[] - - -:context: {parent-context-of-retrieving-che-logs} diff --git a/modules/administration-guide/partials/assembly_running-custom-registries.adoc b/modules/administration-guide/partials/assembly_running-custom-registries.adoc deleted file mode 100644 index d60865f85f..0000000000 --- a/modules/administration-guide/partials/assembly_running-custom-registries.adoc +++ /dev/null @@ -1,31 +0,0 @@ - - -:parent-context-of-running-custom-registries: {context} - -[id="running-custom-registries_{context}"] -= Running custom registries - -:context: running-custom-registries - -.Prerequisites - -The `my-plug-in-registry` and `my-devfile-registry` images used in this section are built using the `docker` command. This section assumes that these images are available on the {platforms-name} cluster where {prod-short} is deployed. - -ifeval::["{project-context}" == "che"] -This is true on Minishift or Minikube, for example, if before running the `docker build` commands, the user executed: - -* The `eval ${minikube docker-env}` command for Minikube. -* The `eval ${minishift docker-env}` command for Minishift. -endif::[] - -These images can be then pushed to: - -* A public container registry such as `quay.io`, or the DockerHub. -* A private registry. - -:context: running-custom-registries-on-openshift -include::partial$proc_deploying-registries-in-openshift.adoc[leveloffset=+1] - -include::partial$proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc[leveloffset=+1] - -:context: {parent-context-of-running-custom-registries} diff --git a/modules/administration-guide/partials/assembly_server-components-with-che-server.adoc b/modules/administration-guide/partials/assembly_server-components-with-che-server.adoc deleted file mode 100644 index 0761752fbf..0000000000 --- a/modules/administration-guide/partials/assembly_server-components-with-che-server.adoc +++ /dev/null @@ -1,26 +0,0 @@ - - -:parent-context-of-understanding-che-workspace-controller: {context} - -[id="understanding-{prod-id-short}-server_{context}"] -= Understanding {prod-short} server - -This chapter describes the {prod-short} controller and the services that are a part of the controller. - -:context: understanding-{prod-id-short}-workspace-controller - -include::partial$con_che-workspace-controller-with-che-server.adoc[leveloffset=+1] - -include::partial$con_che-server.adoc[leveloffset=+1] - -include::partial$con_che-dashboard.adoc[leveloffset=+1] - -include::partial$con_che-devfile-registry.adoc[leveloffset=+1] - -include::partial$con_che-plug-in-registry.adoc[leveloffset=+1] - -include::partial$con_che-postgresql.adoc[leveloffset=+1] - -include::partial$con_che-keycloak.adoc[leveloffset=+1] - -:context: {parent-context-of-understanding-che-workspace-controller} \ No newline at end of file diff --git a/modules/administration-guide/partials/assembly_tracing-che.adoc b/modules/administration-guide/partials/assembly_tracing-che.adoc deleted file mode 100644 index ee0178084e..0000000000 --- a/modules/administration-guide/partials/assembly_tracing-che.adoc +++ /dev/null @@ -1,32 +0,0 @@ - - -:parent-context-of-tracing-che: {context} - -[id="tracing-{prod-id-short}_{context}"] -= Tracing {prod-short} - -:context: tracing-{prod-id-short} - -Tracing helps gather timing data to troubleshoot latency problems in microservice architectures and helps to understand a complete transaction or workflow as it propagates through a distributed system. Every transaction may reflect performance anomalies in an early phase when new services are being introduced by independent teams. - -Tracing the {prod-short} application may help analyze the execution of various operations, such as workspace creations, workspace startup, breaking down the duration of sub-operations executions, helping finding bottlenecks and improve the overall state of the platform. - -Tracers live in applications. They record timing and metadata about operations that take place. They often instrument libraries, so that their use is indiscernible to users. For example, an instrumented web server records when it received a request and when it sent a response. The trace data collected is called a *span*. A span has a context that contains information such as trace and span identifiers and other kinds of data that can be propagated down the line. - -== Tracing API - -{prod-short} utilizes link:https://opentracing.io/[OpenTracing API] - a vendor-neutral framework for instrumentation. This means that if a developer wants to try a different tracing back end, then rather than repeating the whole instrumentation process for the new distributed tracing system, the developer can simply change the configuration of the tracer back end. - -== Tracing back end - -By default, {prod-short} uses Jaeger as the tracing back end. Jaeger was inspired by Dapper and OpenZipkin, and it is a distributed tracing system released as open source by Uber Technologies. Jaeger extends a more complex architecture for a larger scale of requests and performance. - -include::partial$assembly_installing-the-jaeger-tracing-tool.adoc[leveloffset=+1] - -include::partial$proc_enabling-metrics-collection.adoc[leveloffset=+1] - -include::partial$proc_viewing-che-traces-in-jaeger-ui.adoc[leveloffset=+1] - -include::partial$ref_che-tracing-codebase-overview-and-extension-guide.adoc[leveloffset=+1] - -:context: {parent-context-of-tracing-che} diff --git a/modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture-with-che-server.adoc b/modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture-with-che-server.adoc deleted file mode 100644 index d8b19060af..0000000000 --- a/modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture-with-che-server.adoc +++ /dev/null @@ -1,21 +0,0 @@ - - -:parent-context-of-understanding-che-workspaces-architecture: {context} - -[id="understanding-{prod-id-short}-workspaces-architecture_{context}"] -= Understanding {prod-short} workspaces architecture - -:context: understanding-{prod-id-short}-workspaces-architecture - -This chapter describes the architecture and components of {prod-short}. - -include::partial$con_che-workspaces-architecture-with-che-server.adoc[leveloffset=+1] - - -include::partial$assembly_che-workspace-components.adoc[leveloffset=+1] - - -include::partial$con_che-workspace-creation-flow.adoc[leveloffset=+1] - - -:context: {parent-context-of-understanding-che-workspaces-architecture} diff --git a/modules/administration-guide/partials/assembly_viewing-che-server-logs.adoc b/modules/administration-guide/partials/assembly_viewing-che-server-logs.adoc deleted file mode 100644 index 400b95ad46..0000000000 --- a/modules/administration-guide/partials/assembly_viewing-che-server-logs.adoc +++ /dev/null @@ -1,15 +0,0 @@ - -// retrieving-{prod-id-short}-logs - -:parent-context-of-viewing-che-server-logs: {context} - -[id="viewing-{prod-id-short}-server-logs_{context}"] -= Viewing {prod-short} server logs - -:context: viewing-{prod-id-short}-server-logs - -This section describes how to view the {prod-short} server logs using the command line. - -include::partial$proc_viewing-che-server-logs-on-the-cli.adoc[leveloffset=+1] - -:context: {parent-context-of-viewing-che-server-logs} diff --git a/modules/administration-guide/partials/assembly_viewing-external-service-logs.adoc b/modules/administration-guide/partials/assembly_viewing-external-service-logs.adoc deleted file mode 100644 index bb313a205d..0000000000 --- a/modules/administration-guide/partials/assembly_viewing-external-service-logs.adoc +++ /dev/null @@ -1,16 +0,0 @@ - - -:parent-context-of-viewing-external-service-logs: {context} - -[id="viewing-external-service-logs_{context}"] -= Viewing external service logs - -:context: viewing-external-service-logs - -This section describes how the view the logs from external services related to {prod-short} server. - -include::partial$assembly_viewing-keycloak-logs.adoc[leveloffset=+1] - -include::partial$proc_viewing-postgresql-server-logs.adoc[leveloffset=+1] - -:context: {parent-context-of-viewing-external-service-logs} diff --git a/modules/administration-guide/partials/assembly_viewing-keycloak-logs.adoc b/modules/administration-guide/partials/assembly_viewing-keycloak-logs.adoc deleted file mode 100644 index bfe21f238f..0000000000 --- a/modules/administration-guide/partials/assembly_viewing-keycloak-logs.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// viewing-external-service-logs - -:parent-context-of-viewing-keycloak-logs: {context} - -[id="viewing-{identity-provider-id}-logs_{context}"] -= Viewing {identity-provider} logs - -:context: viewing-keycloak-logs - -The {identity-provider} OpenID provider consists of two parts: Server and IDE. It writes its diagnostics or error information to several logs. - -include::partial$proc_viewing-keycloak-server-logs.adoc[leveloffset=+1] - -include::partial$proc_viewing-keycloak-client-logs-on-firefox.adoc[leveloffset=+1] - -include::partial$proc_viewing-keycloak-client-logs-on-google-chrome.adoc[leveloffset=+1] - -:context: {parent-context-of-viewing-keycloak-logs} diff --git a/modules/administration-guide/partials/con_a-workspace-example.adoc b/modules/administration-guide/partials/con_a-workspace-example.adoc index 7acccd1352..794d96f6d3 100644 --- a/modules/administration-guide/partials/con_a-workspace-example.adoc +++ b/modules/administration-guide/partials/con_a-workspace-example.adoc @@ -9,7 +9,6 @@ The following devfile defines the {prod-short} workspace: include::example$snip_a-{project-context}-workspace-example.adoc[] - This table provides the memory requirements for each workspace component: [cols="1,3,1,1", options="header"] @@ -21,41 +20,26 @@ This table provides the memory requirements for each workspace component: |Default memory request |Workspace -|`theia-ide` (default `cheEditor`) -|512 MiB -|512 MiB +|`theia-ide` +|512 Mi +|64 Mi |Workspace -|`machine-exec` (default `chePlugin`) -|128 MiB -|32 MiB +|`machine-exec` +|128 Mi +|32 Mi |Workspace -|`vscode-typescript` (`chePlugin`) -|512 MiB -|512 MiB +|`tools` +|4 Gi +|64 Mi |Workspace -|`nodejs` (`dockerimage`) -|1 GiB -|512 MiB - -|JWT Proxy -|verifier -|128 MiB -|128 MiB +|`che-gateway` +|256 Mi +|64 Mi 2+>s|Total ->s|2.25 GiB ->s|1.38 GiB +>s|4.9 Gi +>s|224 Mi |=== - - -* The `theia-ide` and `machine-exec` components are implicitly added to the workspace, even when not included in the devfile. -* The resources required by `machine-exec` are the default for `chePlugin`. -* The resources for `theia-ide` are specifically set in the `cheEditor` `meta.yaml` to *512 MiB* as `memoryLimit`. -* The Typescript VS Code extension has also overridden the default memory limits. In its `meta.yaml` file, the limits are explicitly specified to *512 MiB*. -* {prod-short} is applying the defaults for the `dockerimage` component type: a memory limit of *1 GiB* and a memory request of *512 MiB*. -* The JWT container requires *128 MiB* of memory. - -Adding all together results in *1.38 GiB* of memory requests with a *2.25 GiB* limit. diff --git a/modules/administration-guide/partials/con_architecture-overview-with-che-server.adoc b/modules/administration-guide/partials/con_architecture-overview-with-che-server.adoc deleted file mode 100644 index f5660cdd1a..0000000000 --- a/modules/administration-guide/partials/con_architecture-overview-with-che-server.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="{prod-id-short}-architecture-overview-with-che-server_{context}"] -= {prod-short} architecture with {prod-short} server - -{prod-short} server is the default workspace engine. - -.High-level {prod-short} architecture with the {prod-short} server engine -image::administration-guide:architecture/{project-context}-architecture-with-che-server-engine.png[] - -{prod} components are: - -{prod-short} server:: - -An always-running service that manages user workspaces with the {orch-name} API. - -User workspaces:: - -Container-based IDEs running on user requests. - -.Additional resources - -* xref:administration-guide:server-components-with-che-server.adoc[] -* xref:administration-guide:che-workspaces-architecture-with-che-server.adoc[] diff --git a/modules/administration-guide/partials/con_architecture-overview-with-devworkspace.adoc b/modules/administration-guide/partials/con_architecture-overview-with-devworkspace.adoc deleted file mode 100644 index f8513420e2..0000000000 --- a/modules/administration-guide/partials/con_architecture-overview-with-devworkspace.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="{prod-id-short}-architecture-overview-with-devworkspace{context}"] -= {prod-short} architecture with {devworkspace} - -include::example$snip_using-devworkspace-warning.adoc[] - -.High-level {prod-short} architecture with the {devworkspace} operator -image::architecture/che-interacting-with-devworkspace.png[] - -When {prod-short} is running with the {devworkspace} operator, it runs on three groups of components: - -{prod-short} server components:: -Manage User {orch-namespace} and workspaces. The main component is the User dashboard, from which users control their workspaces. - -{devworkspace} operator:: -Creates and controls the necessary {orch-name} objects to run User workspaces. Including `Pods`, `Services`, and `PeristentVolumes`. - -User workspaces:: -Container-based development environments, the IDE included. - -The role of these {orch-name} features is central: - -{devworkspace} Custom Resources:: -Valid {orch-name} objects representing the User workspaces and manipulated by {prod-short}. It is the communication channel for the three groups of components. - -{orch-name} role-based access control (RBAC):: -Controls access to all resources. - -.Additional resources - -* xref:server-components.adoc[] -* xref:devworkspace-operator.adoc[] -* xref:user-workspaces.adoc[] -* xref:installation-guide:enabling-dev-workspace-operator.adoc[] -* link:https://github.com/devfile/devworkspace-operator[{devworkspace} Operator repository] -include::example$snip_che-architecture-overview-with-devworkspace-additional-resources.adoc[] - diff --git a/modules/administration-guide/partials/con_architecture-overview.adoc b/modules/administration-guide/partials/con_architecture-overview.adoc deleted file mode 100644 index f85c89366d..0000000000 --- a/modules/administration-guide/partials/con_architecture-overview.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="assembly_architecture-overview_{context}"] -= Architecture overview - - -{prod-short} needs a workspace engine to manage the lifecycle of the workspaces. -Two workspace engines are available. -The choice of a workspace engine defines the architecture. - -xref:administration-guide:architecture-overview-with-che-server.adoc[]:: - -{prod-short} server is the default workspace engine. -+ -.High-level {prod-short} architecture with the {prod-short} server engine -image::administration-guide:architecture/{project-context}-architecture-with-che-server-engine.png[High-level {prod-short} architecture with the {prod-short} server engine] - - -xref:administration-guide:architecture-overview-with-devworkspace.adoc[]:: - -The {devworkspace} Operator is a new workspace engine. -+ -include::example$snip_using-devworkspace-warning.adoc[] -+ -.High-level {prod-short} architecture with the {devworkspace} operator -image::administration-guide:architecture/che-interacting-with-devworkspace.png[High-level {prod-short} architecture with the {devworkspace} operator] - -.Additional resources - -* xref:administration-guide:architecture-overview-with-che-server.adoc[] -* xref:administration-guide:architecture-overview-with-devworkspace.adoc[] -* xref:installation-guide:enabling-dev-workspace-operator.adoc[] -* https://github.com/devfile/devworkspace-operator[{devworkspace} Operator GitHub repository] - diff --git a/modules/administration-guide/partials/con_authorization-and-user-management.adoc b/modules/administration-guide/partials/con_authorization-and-user-management.adoc deleted file mode 100644 index bc171d962c..0000000000 --- a/modules/administration-guide/partials/con_authorization-and-user-management.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// configuring-authorization - -[id="authorization-and-user-management_{context}"] -= Authorization and user management - -{prod} uses {identity-provider-url}[{identity-provider}] to create, import, manage, delete, and authenticate users. {identity-provider} uses built-in authentication mechanisms and user storage. It can use third-party identity management systems to create and authenticate users. {prod} requires a {identity-provider} token when you request access to {prod-short} resources. - -Local users and imported federation users must have an email address in their profile. - -The default {identity-provider} credentials are `admin:admin`. You can use the `admin:admin` credentials when logging into {prod} for the first time. It has system privileges. - -.Identifying the {identity-provider} URL - -ifeval::["{project-context}" == "che"] -{prod-short} running on {kubernetes}:: -Go to `+$CHE_HOST:5050/auth+`. - -{prod-short} is running on OpenShift:: -endif::[] -Go to the OpenShift web console and to the *{identity-provider}* project. diff --git a/modules/administration-guide/partials/con_caching-images-for-faster-workspace-start.adoc b/modules/administration-guide/partials/con_caching-images-for-faster-workspace-start.adoc deleted file mode 100644 index 7ba77951ab..0000000000 --- a/modules/administration-guide/partials/con_caching-images-for-faster-workspace-start.adoc +++ /dev/null @@ -1,83 +0,0 @@ - -[id="caching-images-for-faster-workspace-start_{context}"] -= Caching images for faster workspace start - -To improve the start time performance of {prod-short} workspaces, use the {image-puller-name-short}, a {prod-short}-agnostic component that can be used to pre-pull images for {platforms-name} clusters. The {image-puller-name-short} is an additional {platforms-name} deployment which creates a _DaemonSet_ that can be configured to pre-pull relevant {prod-short} workspace images on each node. These images would already be available when a {prod-short} workspace starts, therefore improving the workspace start time. - -The {image-puller-name-short} provides the following parameters for configuration. -ifeval::["{project-context}" == "che"] -The underlying platform determines the installation method. -endif::[] - -[id="image-puller-configuration_{context}"] -.{image-puller-name-short} parameters -[options="header"] -|=== -|Parameter |Usage |Default - -|`CACHING_INTERVAL_HOURS` - -|DaemonSets health checks interval in hours -|`"1"` - -|`CACHING_MEMORY_REQUEST` -|The memory request for each cached image when the puller is running. See xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. -|`10Mi` - -|`CACHING_MEMORY_LIMIT` -|The memory limit for each cached image when the puller is running. See xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. -|`20Mi` - -|`CACHING_CPU_REQUEST` -|The processor request for each cached image when the puller is running -|`.05` or 50 millicores - -|`CACHING_CPU_LIMIT` -|The processor limit for each cached image when the puller is running -|`.2` or 200 millicores - -|`DAEMONSET_NAME` -|Name of DaemonSet to create -|`{image-puller-deployment-name}` - -|`DEPLOYMENT_NAME` -|Name of the Deployment to create -|`{image-puller-deployment-name}` - -|`NAMESPACE` -|{platforms-namespace} containing DaemonSet to create -|`k8s-image-puller` - -|`IMAGES` -|Semicolon separated list of images to pull, in the format `__<name1>__=__<image1>__;__<name2>__=__<image2>__` See xref:defining-the-list-of-images-to-pull.adoc[]. -| - -|`NODE_SELECTOR` -|Node selector to apply to the Pods created by the DaemonSet -|`'{}'` - -| `AFFINITY` -| Affinity applied to pods created by the DaemonSet -| `'{}'` - -|`IMAGE_PULL_SECRETS` -| List of image pull secrets, in the format `pullsecret1;...` to add to pods created by the DaemonSet. Those secrets need to be in the image puller's namespace and a cluster administrator must create them. -| `""` -|=== - - -.Additional resources - -* xref:defining-the-list-of-images-to-pull.adoc[] -* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. -* xref:installing-image-puller-using-che-operator.adoc[] - -ifeval::["{project-context}" == "che"] -* xref:installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc[] -endif::[] - -* xref:installing-image-puller-on-openshift-using-operatorhub.adoc[] -* xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[] - -* link:https://github.com/che-incubator/{image-puller-repository-name}[{image-puller-name} source code repository] - diff --git a/modules/administration-guide/partials/con_che-dashboard.adoc b/modules/administration-guide/partials/con_che-dashboard.adoc deleted file mode 100644 index 1ca23fe1af..0000000000 --- a/modules/administration-guide/partials/con_che-dashboard.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-with-che-server - -[id="{prod-id-short}-dashboard_{context}"] -= {prod-short} user dashboard - -The user dashboard is the landing page of {prod}. -It is a React application. -{prod-short} users navigate the user dashboard from their browsers to create, start, and manage {prod-short} workspaces. - -.Additional resources - -* xref:end-user-guide:navigating-che.adoc[] - -include::example$snip_{project-context}-dashboard-additional-resources.adoc[] - diff --git a/modules/administration-guide/partials/con_che-devfile-registry.adoc b/modules/administration-guide/partials/con_che-devfile-registry.adoc deleted file mode 100644 index a101c80184..0000000000 --- a/modules/administration-guide/partials/con_che-devfile-registry.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-with-che-server - -[id="{prod-id-short}-devfile-registry_{context}"] -= {prod-short} devfile registry - -The {prod-short} devfile registry is a service that provides a list of {prod-short} samples to create ready-to-use workspaces. This list of samples is used in the *Dashboard* -> *Create Workspace* window. The devfile registry runs in a container and can be deployed wherever the user dashboard can connect. - - -.Additional resources - -* xref:end-user-guide:creating-a-workspace-from-a-code-sample.adoc[] - -include::example$snip_che-devfile-registry-additional-resources.adoc[] diff --git a/modules/administration-guide/partials/con_che-editor-plug-in.adoc b/modules/administration-guide/partials/con_che-editor-plug-in.adoc deleted file mode 100644 index 86d3e2f196..0000000000 --- a/modules/administration-guide/partials/con_che-editor-plug-in.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-components - -[id="{prod-id-short}-editor-plug-in_{context}"] -= `Che Editor` plug-in - -A `Che Editor` plug-in is a {prod-short} workspace plug-in. -It defines the web application that is used as an editor in a workspace. -The default {prod-short} workspace editor is link:https://github.com/eclipse-che/che-theia[Che-Theia]. -It is a web-based source-code editor similar to link:https://code.visualstudio.com/[Visual Studio Code] (VS Code). -It has a plug-in system that supports VS Code extensions. - -[cols=2*] -|=== -| Source code -| link:https://github.com/eclipse-che/che-theia[Che-Theia] - -| Container image -| `eclipse/che-theia` - -| Endpoints -| `theia`, `webviews`, `theia-dev`, `theia-redirect-1`, `theia-redirect-2`, `theia-redirect-3` - -|=== - -.Additional resources - -* link:https://github.com/eclipse-che/che-theia[Che-Theia] -* link:https://github.com/theia-ide/theia[Eclipse Theia open-source project] -* link:https://code.visualstudio.com/[Visual Studio Code] - diff --git a/modules/administration-guide/partials/con_che-keycloak.adoc b/modules/administration-guide/partials/con_che-keycloak.adoc deleted file mode 100644 index 2dee164239..0000000000 --- a/modules/administration-guide/partials/con_che-keycloak.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller - - -[id="{prod-id-short}-keycloak_{context}"] -= {prod-short} and {identity-provider} - -{identity-provider} is a prerequisite to configure {prod-short}. The {prod-short} administrator can choose to connect {prod-short} to an existing {identity-provider} instance or let the {prod-short} deployment start a new dedicated {identity-provider} instance. - -The {prod-short} server uses {identity-provider} as an OpenID Connect (OIDC) provider to authenticate {prod-short} users and secure access to {prod-short} resources. - -.Additional resources - -include::example$snip_che-keycloak-additional-resources.adoc[] - diff --git a/modules/administration-guide/partials/con_che-operator.adoc b/modules/administration-guide/partials/con_che-operator.adoc deleted file mode 100644 index 37cfd94aba..0000000000 --- a/modules/administration-guide/partials/con_che-operator.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="{prod-id-short}-operator_{context}"] -= {prod-short} operator - -// .{prod-short} operator -// image::architecture/{project-context}-operator.png[] - -The {prod-short} operator ensure full lifecycle management of the {prod-short} server components. -It introduces: - -`CheCluster` custom resource definition (CRD):: -Defines the `CheCluster` {orch-name} object. - -{prod-short} controller:: - -Creates and controls the necessary {orch-name} objects to run a {prod-short} instance, such as pods, services, and persistent volumes. - -`CheCluster` custom resource (CR):: -On a cluster with the {prod-short} operator, it is possible to create a `CheCluster` custom resource (CR). The {prod-short} operator ensure full lifecycle management of the {prod-short} server components on this {prod-short} instance. - -.Additional resources - -* xref:installation-guide:configuring-the-che-installation.adoc[] -* xref:installation-guide:installing-che.adoc[] diff --git a/modules/administration-guide/partials/con_che-plug-in-broker.adoc b/modules/administration-guide/partials/con_che-plug-in-broker.adoc deleted file mode 100644 index 2b87e4f9ef..0000000000 --- a/modules/administration-guide/partials/con_che-plug-in-broker.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-components - -[id="{prod-id-short}-plug-in-broker_{context}"] -= {prod-short} plug-ins broker - -Plug-in brokers are special services that, given a plug-in `meta.yaml` file: - -* Gather all the information to provide a plug-in definition that the {prod-short} server knows. - -* Perform preparation actions in the workspace {orch-namespace} (download, unpack files, process configuration). - -The main goal of the plug-in broker is to decouple the {prod-short} plug-ins definitions from the actual plug-ins that {prod-short} can support. With brokers, {prod-short} can support different plug-ins without updating the {prod-short} server. - -The {prod-short} server starts the plug-in broker. The plug-in broker runs in the same {platforms-namespace} as the workspace. It has access to the plug-ins and project persistent volumes. - -A plug-ins broker is defined as a container image (for example, `eclipse/che-plugin-broker`). The plug-in type determines the type of the broker that is started. Two types of plug-ins are supported: `Che Plugin` and `Che Editor`. - -[cols=2*] -|=== -| Source code -| link:https://github.com/eclipse/che-plugin-broker[{prod-short} Plug-in broker] - -| Container image -| `quay.io/eclipse/che-plugin-artifacts-broker` + -`eclipse/che-plugin-metadata-broker` -|=== diff --git a/modules/administration-guide/partials/con_che-plug-in-registry.adoc b/modules/administration-guide/partials/con_che-plug-in-registry.adoc deleted file mode 100644 index 5e08432db3..0000000000 --- a/modules/administration-guide/partials/con_che-plug-in-registry.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-with-che-server - -[id="{prod-id-short}-plug-in-registry_{context}"] -= {prod-short} plug-in registry - -The {prod-short} plug-in registry is a service that provides the list of plug-ins and editors for {prod-short} workspaces. A devfile only references a plug-in that is published in a {prod-short} plug-in registry. It runs in a container and can be deployed wherever {prod-short} server connects. - -.Additional resources - -include::example$snip_che-plugin-registry-additional-resources.adoc[] diff --git a/modules/administration-guide/partials/con_che-plug-ins.adoc b/modules/administration-guide/partials/con_che-plug-ins.adoc deleted file mode 100644 index e333987986..0000000000 --- a/modules/administration-guide/partials/con_che-plug-ins.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-components - -[id="{prod-id-short}-plug-ins_{context}"] -= `Che Plugin` plug-ins - -`Che Plugin` plug-ins are special services that extend {prod-short} workspace capabilities. `Che Plugin` plug-ins are packaged as containers. Packaging plug-ins into a container has the following benefits: - -* It isolates the plug-ins from the main IDE, therefore limiting the resources that a plug-in has access to. - -* It uses the consolidated standard of container registries to publish and distribute plug-ins (as with any container image). - -The containers that plug-ins are packaged into run as sidecars of the {prod-short} workspace editor and augment its capabilities. - -Visual Studio Code extensions packaged in containers are {prod-short} plug-ins for the Che-Theia editor. - -Multiple {prod-short} plug-ins can run in the same container (for better resource use), or a Che Plugin can run in its dedicated container (for better isolation). diff --git a/modules/administration-guide/partials/con_che-postgresql.adoc b/modules/administration-guide/partials/con_che-postgresql.adoc deleted file mode 100644 index 717c354fac..0000000000 --- a/modules/administration-guide/partials/con_che-postgresql.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-with-che-server - -[id="{prod-id-short}-postgresql_{context}"] -= {prod-short} and PostgreSQL - -The PostgreSQL database is a prerequisite for {prod-short} server and {identity-provider}. - -The {prod-short} administrator can choose to: - -* Connect {prod-short} to an existing PostgreSQL instance. -* Let the {prod-short} deployment start a new dedicated PostgreSQL instance. - -Services use the database for the following purposes: - -{prod-short} server:: -Persist user configurations such as workspaces metadata and Git credentials. - -{identity-provider}:: -Persist user information. - -.Additional resources - -* xref:administration-guide:external-database-setup.adoc[] - -include::example$snip_che-postgresql-additional-resources.adoc[] - diff --git a/modules/administration-guide/partials/con_che-server-components.adoc b/modules/administration-guide/partials/con_che-server-components.adoc deleted file mode 100644 index 13bf27be0f..0000000000 --- a/modules/administration-guide/partials/con_che-server-components.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="{prod-id-short}-server-components_{context}"] -= {prod-short} server components - -include::example$snip_using-devworkspace-warning.adoc[] - -The {prod-short} server components ensure multi-tenancy and workspaces management. - -.{prod-short} server components interacting with the {devworkspace} operator -image::architecture/{project-context}-deployments-interacting-with-devworkspace.png[] - -.Additional resources - -* xref:che-operator.adoc[] -* xref:devworkspace-operator.adoc[] -* xref:gateway.adoc[] -* xref:dashboard.adoc[] -* xref:devfile-registries.adoc[] -* xref:che-server.adoc[] -* xref:postgresql.adoc[] -* xref:plug-in-registry.adoc[] diff --git a/modules/administration-guide/partials/con_che-server-with-devworkspace.adoc b/modules/administration-guide/partials/con_che-server-with-devworkspace.adoc deleted file mode 100644 index eb47b3bb80..0000000000 --- a/modules/administration-guide/partials/con_che-server-with-devworkspace.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-with-devworkspace - - -[id="{prod-id-short}-server-with-devworkspace_{context}"] -= {prod-short} server - - -The {prod-short} server main functions are: - -* Creating user namespaces. -* Provisioning user namespaces with required secrets and config maps. -* Integrating with Git services providers, to fetch and validate devfiles and authentication. - -The {prod-short} server is a Java web service exposing an HTTP REST API and needs access to: - -* xref:postgresql.adoc[] -* Git service providers -* {orch-name} API - -.{prod-short} server interactions with other components -image::architecture/{project-context}-server-interactions.png[{prod-short} server interactions with other components] - -.Additional resources - -* xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[] - -include::example$snip_{project-context}-che-server-additional-resources.adoc[] - diff --git a/modules/administration-guide/partials/con_che-server.adoc b/modules/administration-guide/partials/con_che-server.adoc deleted file mode 100644 index 2cbac86402..0000000000 --- a/modules/administration-guide/partials/con_che-server.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-che-server - - -[id="{prod-id-short}-server_{context}"] -= {prod-short} server - -The {prod-short} server is the central service of {prod-short} server-side components. -It is a Java web service exposing an HTTP REST API to manage {prod-short} workspaces and users. -It is the default workspace engine. - -.Additional resources - -* xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[] - -include::example$snip_{project-context}-che-server-additional-resources.adoc[] diff --git a/modules/administration-guide/partials/con_che-system-permissions.adoc b/modules/administration-guide/partials/con_che-system-permissions.adoc deleted file mode 100644 index af3132c400..0000000000 --- a/modules/administration-guide/partials/con_che-system-permissions.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// authorizing-users - -[id="{prod-id-short}-system-permissions_{context}"] -= {prod-short} system permissions - -{prod-short} system permissions control aspects of the whole {prod-short} installation. The following permissions are applicable to the system: - -.{prod-short} system permission -[options="header",cols="2"] -|=== -| Permission -| Description - -| manageSystem -| Allows control of the system and workspaces. -| setPermissions -| Allows updating the permissions for users on the system. -| manageUsers -| Allows creating and managing users. -| monitorSystem -| Allows accessing endpoints used for monitoring the state of the server. -|=== - -All system permissions are granted to the administrative user. To configure the administrative user, use the `CHE_SYSTEM_ADMIN__NAME` property. The default value is `admin`. The system permissions are granted when the {prod-short} server starts. If the record of the user is not in the {prod-short} user database, the permissions are granted after the first login of the user. diff --git a/modules/administration-guide/partials/con_che-user-runtimes.adoc b/modules/administration-guide/partials/con_che-user-runtimes.adoc deleted file mode 100644 index 63f5087f25..0000000000 --- a/modules/administration-guide/partials/con_che-user-runtimes.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-components - -[id="{prod-id-short}-user-runtimes_{context}"] -= {prod-short} user runtimes - -Use any non-terminating user container as a user runtime. An application that can be defined as a container image or as a set of {platforms-name} resources can be included in a {prod-short} workspace. This makes it easy to test applications in the {prod-short} workspace. - -To test an application in the {prod-short} workspace, include the application YAML definition used in stage or production in the workspace specification. It is a 12-factor application development / production parity. - -Examples of user runtimes are Node.js, SpringBoot or MongoDB, and MySQL. diff --git a/modules/administration-guide/partials/con_che-workspace-controller-with-che-server.adoc b/modules/administration-guide/partials/con_che-workspace-controller-with-che-server.adoc deleted file mode 100644 index d9f59b2b2a..0000000000 --- a/modules/administration-guide/partials/con_che-workspace-controller-with-che-server.adoc +++ /dev/null @@ -1,17 +0,0 @@ - -[id="{prod-id-short}-workspace-controller-with-che-server_{context}"] -= {prod-short} server - -The workspaces controller manages the container-based development environments: {prod-short} workspaces. To secure the development environments with authentication, the deployment is always multiuser and multitenant. - - - -The following diagram shows the different services that are a part of the {prod-short} workspaces controller. - - -.{prod-short} workspaces controller -image::architecture/{project-context}-workspaces-controllers.png[] - -.Additional resources - -* xref:authenticating-users.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/partials/con_che-workspace-creation-flow.adoc b/modules/administration-guide/partials/con_che-workspace-creation-flow.adoc deleted file mode 100644 index fd13f2c202..0000000000 --- a/modules/administration-guide/partials/con_che-workspace-creation-flow.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspaces-architecture - -[id="{prod-id-short}-workspace-creation-flow_{context}"] -= {prod-short} workspace creation flow - -image::architecture/che-workspace-creation-flow.png[] - -The following is a {prod-short} workspace creation flow: - -. A user starts a {prod-short} workspace defined by: -+ -* An editor (the default is Che-Theia) -* A list of plug-ins (for example, Java and {platforms-name} tools) -* A list of runtime applications - -. {prod-short} server retrieves the editor and plug-in metadata from the plug-in registry. -. For every plug-in type, {prod-short} server starts a specific plug-in broker. -. The {prod-short} plug-ins broker transforms the plug-in metadata into a Che Plugin definition. It executes the following steps: -+ -.. Downloads a plug-in and extracts its content. -.. Processes the plug-in `meta.yaml` file and sends it back to {prod-short} server in the format of a Che Plugin. - -. {prod-short} server starts the editor and the plug-in sidecars. -. The editor loads the plug-ins from the plug-in persistent volume. diff --git a/modules/administration-guide/partials/con_che-workspace-jwt-proxy.adoc b/modules/administration-guide/partials/con_che-workspace-jwt-proxy.adoc deleted file mode 100644 index bca1f25eb5..0000000000 --- a/modules/administration-guide/partials/con_che-workspace-jwt-proxy.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-components - -[id="{prod-id-short}-workspace-jwt-proxy_{context}"] -= {prod-short} workspace JWT proxy - -The JWT proxy is responsible for securing the communication of the {prod-short} workspace services. - -An HTTP proxy is used to sign outgoing requests from a workspace service to the {prod-short} server and to authenticate incoming requests from the IDE client running on a browser. - -[cols=2*] -|=== -| Source code -| link:https://github.com/eclipse/che-jwtproxy[JWT proxy] - -| Container image -| `eclipse/che-jwtproxy` -|=== diff --git a/modules/administration-guide/partials/con_che-workspace-permissions.adoc b/modules/administration-guide/partials/con_che-workspace-permissions.adoc deleted file mode 100644 index 5b3d7f83d8..0000000000 --- a/modules/administration-guide/partials/con_che-workspace-permissions.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// authorizing-users - -[id="{prod-id-short}-workspace-permissions_{context}"] -= {prod-short} workspace permissions - -The user who creates a workspace is the workspace owner. By default, the workspace owner has the following permissions: `read`, `use`, `run`, `configure`, `setPermissions`, and `delete`. Workspace owners can invite users into the workspace and control workspace permissions for other users. - -The following permissions are associated with workspaces: - -.{prod-short} workspace permissions -[options="header",cols="2"] -|=== -| Permission -| Description - - -| read -| Allows reading the workspace configuration. -| use -| Allows using a workspace and interacting with it. -| run -| Allows starting and stopping a workspace. -| configure -| Allows defining and changing the workspace configuration. -| setPermissions -| Allows updating the workspace permissions for other users. -| delete -| Allows deleting the workspace. -|=== diff --git a/modules/administration-guide/partials/con_che-workspaces-architecture-with-che-server.adoc b/modules/administration-guide/partials/con_che-workspaces-architecture-with-che-server.adoc deleted file mode 100644 index 14b2d8bb1b..0000000000 --- a/modules/administration-guide/partials/con_che-workspaces-architecture-with-che-server.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="{prod-id-short}-workspaces-architecture-with-che-server_{context}"] -= {prod-short} workspaces architecture - -A {prod-short} deployment on the cluster consists of the {prod-short} server component, a database for storing user profile and preferences, and several additional deployments hosting workspaces. The {prod-short} server orchestrates the creation of workspaces, which consist of a deployment containing the workspace containers and enabled plug-ins, plus the related components, such as: - -* ConfigMaps -* services -* endpoints -* ingresses or routes -* secrets -* persistent volumes (PVs) - -The {prod-short} workspace is a web application. It is composed of microservices running in containers that provide all the services of a modern IDE such as an editor, language auto-completion, and debugging tools. The IDE services are deployed with the development tools, packaged in containers and user runtime applications, which are defined as {orch-name} resources. - -The source code of the projects of a {prod-short} workspace is persisted in a {platforms-name} `PersistentVolume`. Microservices run in containers that have read-write access to the source code (IDE services, development tools), and runtime applications have read-write access to this shared directory. - -The following diagram shows the detailed components of a {prod-short} workspace. - -.{prod-short} workspace components -image::architecture/{project-context}-workspaces.png[] - -In the diagram, there are four running workspaces: two belonging to *User A*, one to *User B* and one to *User C*. - -Use the devfile format to specify the tools and runtime applications of a {prod-short} workspace. - diff --git a/modules/administration-guide/partials/con_controller-requirements.adoc b/modules/administration-guide/partials/con_controller-requirements.adoc index 0c0a09c7b4..145394afd8 100644 --- a/modules/administration-guide/partials/con_controller-requirements.adoc +++ b/modules/administration-guide/partials/con_controller-requirements.adoc @@ -1,46 +1,36 @@ // {prod-id-short}-compute-resources-requirements [id="controller-requirements_{context}"] -= Controller requirements += {devworkspace} Operator requirements -The Workspace Controller consists of a set of five services running in five distinct containers. The following table presents the default resource requirements of each of these services. +The {devworkspace} Operator consists of 3 pods. The following table presents the default resource requirements of each of these pods. [cols="2,2,1,1", options="header"] -.ControllerServices +.{devworkspace} Operator Pods |=== |Pod |Container name |Default memory limit |Default memory request -|{prod-short} Server and Dashboard -|che -|1 GiB -|512 MiB - -|PostgreSQL -|`postgres` -|1 GiB -|512 MiB - -|{identity-provider} -|`{identity-provider-id}` -|2 GiB -|512 MiB - -|Devfile registry -|`che-devfile-registry` -|256 MiB -|16 MiB - -|Plug-in registry -|`che-plugin-registry` -|256 MiB -|16 MiB +|{devworkspace} Controller Manager +|`{devworkspace}-controller`, `kube-rbac-proxy` +|1 Gi +|100 Mi + +|{devworkspace} Operator Catalog +|`registry-server` +|N/A +|50 Mi + +|{devworkspace} Webhook Server +|`webhook-server}`, kube-rbac-proxy +|300 Mi +|20 Mi |=== -These default values are sufficient when the {prod-short} Workspace Controller manages a small amount of {prod-short} workspaces. For larger deployments, increase the memory limit. See the xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[] article for instructions on how to override the default requests and limits. For example, the Eclipse Che hosted by Red Hat that runs on link:https://workspaces.openshift.com[] uses 1 GB of memory. +These default values are sufficient when the {devworkspace} Controller manages a relatively big amount of {prod-short} workspaces. For larger deployments, consider increasing the defaults. .Additional resources -* xref:administration-guide:server-components-with-che-server.adoc[]. +* xref:architecture-overview.adoc[]. diff --git a/modules/administration-guide/partials/con_dashboard.adoc b/modules/administration-guide/partials/con_dashboard.adoc deleted file mode 100644 index 58aa524e2d..0000000000 --- a/modules/administration-guide/partials/con_dashboard.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-with-devworkspace - -[id="dashboard_{context}"] -= User dashboard - -The user dashboard is the landing page of {prod}. -{prod-short} end-users browse the user dashboard to access and manage their workspaces. -It is a React application. -The {prod-short} deployment starts it in the `{prod-deployment}-dashboard` Deployment. - -It need access to: - -* xref:devfile-registries.adoc[] -* xref:che-server.adoc[] -* xref:plug-in-registry.adoc[] -* {orch-name} API - -.User dashboard interactions with other components -image::architecture/{project-context}-dashboard-interactions.png[User dashboard interactions with other components] - -When the user requests the user dashboard to start a workspace, the user dashboard executes this sequence of actions: - -. Collects the devfile from the xref:devfile-registries.adoc[], when the user is xref:end-user-guide:creating-a-workspace-from-a-code-sample.adoc[]. -. Sends the repository URL to xref:che-server.adoc[] and expects a devfile in return, when the user is xref:end-user-guide:creating-a-workspace-from-remote-devfile.adoc[]. -. Reads the devfile describing the workspace. -. Collects the additional metadata from the xref:plug-in-registry.adoc[]. -. Converts the information into a {devworkspace} Custom Resource. -. Creates the {devworkspace} Custom Resource in the user {orch-namespace} using the {orch-name} API. -. Watches the {devworkspace} Custom Resource status. -. Redirects the user to the running workspace IDE. - - -.Additional resources - -* xref:end-user-guide:navigating-che.adoc[] - -include::example$snip_{project-context}-dashboard-additional-resources.adoc[] - diff --git a/modules/administration-guide/partials/con_define-backup-server-for-operator.adoc b/modules/administration-guide/partials/con_define-backup-server-for-operator.adoc deleted file mode 100644 index a5fa4110eb..0000000000 --- a/modules/administration-guide/partials/con_define-backup-server-for-operator.adoc +++ /dev/null @@ -1,98 +0,0 @@ -[id="configuring-{prod-id-short}-to-use-a-backup-server"] -= Configuring {prod-short} to use a backup server - - -To configure a backup server for {prod-short}, a user needs to create the `CheBackupServerConfiguration` Custom Resource object in the {prod-namespace} namespace. The object's `spec` property is divided in several sections where each corresponds to a specific xref:setup-backup-server.adoc[backup server type]: - - * xref:configuring-rest-server-cr[REST] - * xref:configuring-aws-s3-or-api-compatible-server-cr[AWS S3 or API compatible] - * xref:configuring-sftp-server-cr[SFTP] -+ -[NOTE] -==== -* The Custom Resource object, stored in the `{prod-namespace}` namespace, must have only one section configured in the `spec` property. - -* It is possible to configure as many backup servers as needed, but each in a separate `Custom Resource`. - -* Referenced secrets for each server type must exist and have required fields specified. See the description of each secret in the corresponding server-type chapters. -==== - -[id="configuring-rest-server-cr"] -== Configuring REST server - -[source,yaml,subs="+attributes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheBackupServerConfiguration -metadata: - name: backup-server-configuration -spec: - rest: - protocol: http <1> - hostname: my-domain.net <2> - port: 1234 <3> - repositoryPath: {prod-short}-backups <4> - repositoryPasswordSecretRef: backup-encryption-password-secret <5> - credentialsSecretRef: rest-server-auth-secret <6> ----- - -<1> Optional property that specifies the protocol to be used. The default value is `https` with `http` as the second allowed option. -<2> Backup server host name. -<3> Optional property that specifies the port on which the backup server is running. The default value is `8000`. -<4> Path on the backup server where the backup snapshots are stored. -<5> Secret name containing a repository password, stored in the `repo-password` field. If the secret contains only one field, its name is arbitrary. The password is used to encrypt and decrypt backup snapshots data. -<6> Optional property that specifies the name of the secret with the REST server user credentials, stored in the `username` and `password` fields. - - -[id="configuring-aws-s3-or-api-compatible-server-cr"] -== Configuring AWS S3 or API compatible server - -[source,yaml,subs="+attributes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheBackupServerConfiguration -metadata: - name: backup-server-configuration -spec: - awss3: - protocol: https <1> - hostname: my-domain.net <2> - port: 1234 <3> - repositoryPath: {prod-short}-backups <4> - repositoryPasswordSecretRef: backup-encryption-password-secret <5> - awsAccessKeySecretRef: aws-user-credentials-secret <6> ----- - -<1> Optional property that specifies the protocol to be used. The default value is `https` with `http` as the second allowed option. -<2> Optional property that specifies the S3 host name. The default value is `s3.amazonaws.com`. -<3> Optional property that specifies the port on which the backup server is running. -<4> The name of the bucket resource where the backup snapshots are stored. The bucket resource must be manually pre-created. -<5> The name of the secret containing a repository password, stored in the `repo-password` field. If the secret contains only one field, this name is arbitrary. The password is used to encrypt and decrypt backup snapshots data. -<6> The name of the secret containing user credentials stored in the `awsAccessKeyId` and `awsSecretAccessKey` fields. - - -[id="configuring-sftp-server-cr"] -== Configuring SFTP server - -[source,yaml,subs="+attributes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheBackupServerConfiguration -metadata: - name: backup-server-configuration -spec: - awss3: - username: user <1> - hostname: my-domain.net <2> - port: 1234 <3> - repositoryPath: {prod-short}-backups <4> - repositoryPasswordSecretRef: backup-encryption-password-secret <5> - sshKeySecretRef: ssh-key-secret <6> ----- - -<1> User name on the remote server to login with using the SSH protocol. -<2> Remote server host name. -<3> Optional property that specifies the port on which an SFTP server is running. The default value is `22`. -<4> Absolute or relative path on the server where backup snapshots are stored. -<5> The name of the secret containing a repository password, stored in the `repo-password` field. If the secret contains only one field, this name is arbitrary. The password is used to encrypt and decrypt backup snapshots data. -<6> The name of the secret containing a private SSH key, stored in the `ssh-privatekey` field. This SSH key can be used to perform a login without a password on an SFTP server. diff --git a/modules/administration-guide/partials/con_devfile-registries.adoc b/modules/administration-guide/partials/con_devfile-registries.adoc deleted file mode 100644 index 0d9a2fd5da..0000000000 --- a/modules/administration-guide/partials/con_devfile-registries.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="devfile-registries_{context}"] -= Devfile registries - -The {prod-short} devfile registries are services providing a list of sample devfiles to create ready-to-use workspaces. -The xref:dashboard.adoc[] displays the samples list on the *Dashboard* -> *Create Workspace* page. -Each sample includes a Devfile v2. -The {prod-short} deployment starts one devfile registry instance in the `devfile-registry` deployment. - -.Devfile registries interactions with other components -image::architecture/{project-context}-devfile-registry-interactions.png[] - -.Additional resources - -* xref:end-user-guide:creating-a-workspace-from-a-code-sample.adoc[] -* link:https://devfile.io/docs/[Devfile v2 documentation] -* xref:building-and-running-a-custom-registry-image.adoc[] -* link:https://eclipse-che.github.io/che-devfile-registry/main/devfiles/[devfile registry latest community version online instance] - -include::example$snip_che-devfile-registry-additional-resources.adoc[] - diff --git a/modules/administration-guide/partials/con_devworkspace-operator.adoc b/modules/administration-guide/partials/con_devworkspace-operator.adoc deleted file mode 100644 index ce8a4b4fcd..0000000000 --- a/modules/administration-guide/partials/con_devworkspace-operator.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="devworkspace-operator_{context}"] -= {devworkspace} operator - -include::example$snip_using-devworkspace-warning.adoc[] - -The {devworkspace} operator extends {orch-name} to provide {devworkspace} support. It introduces: - -{devworkspace} custom resource definition:: - -Defines the {devworkspace} {orch-name} object from the Devfile v2 specification. - -{devworkspace} controller:: - -Creates and controls the necessary {orch-name} objects to run a {devworkspace}, such as pods, services, and persistent volumes. - -{devworkspace} custom resource:: - -On a cluster with the {devworkspace} operator, it is possible to create {devworkspace} custom resources (CR). A {devworkspace} CR is a {orch-name} representation of a Devfile. It defines a User workspaces in a {orch-name} cluster. - - -.Additional resources - -* xref:installation-guide:enabling-dev-workspace-operator.adoc[] -* link:https://github.com/devfile/api[Devfile API repository] -include::example$snip_{project-context}-devworkspace-additional-resources.adoc[] diff --git a/modules/administration-guide/partials/con_external-database-setup.adoc b/modules/administration-guide/partials/con_external-database-setup.adoc deleted file mode 100644 index 68e65140a2..0000000000 --- a/modules/administration-guide/partials/con_external-database-setup.adoc +++ /dev/null @@ -1,46 +0,0 @@ - - -:parent-context-of-external-database-setup: {context} - -[id="external-database-setup_{context}"] -= External database setup - -:context: external-database-setup - -The PostgreSQL database is used by the {prod-short} server for persisting data about the state of {prod-short}. It contains information about user accounts, workspaces, preferences, and other details. - -By default, the {prod-short} Operator creates and manages the database deployment. - -However, the {prod-short} Operator does not support full life-cycle capabilities, such as backups and recovery. - -For a business-critical setup, configure an external database with the following recommended disaster-recovery options: - -* High Availability (HA) -* Point In Time Recovery (PITR) - -Configure an external PostgreSQL instance on-premises or use a cloud service, such as Amazon Relational Database Service (Amazon RDS). With Amazon RDS, it is possible to deploy production databases in a Multi-Availability Zone configuration for a resilient disaster recovery strategy with daily and on-demand snapshots. - -The recommended configuration of the example database is: - -[options="header"] -|=== -|Parameter | Value -|Instance class | db.t2.small -|vCPU | 1 -|RAM | 2 GB -|Multi-az | true, 2 replicas -|Engine version | 9.6.11 -|TLS | enabled -|Automated backups | enabled (30 days) -|=== - -include::partial$proc_configuring-external-PostgreSQL.adoc[leveloffset=+1] - -include::partial$proc_configuring-che-to-work-with-external-PostgreSQL.adoc[leveloffset=+1] - -.Additional resources - -* link:https://www.postgresql.org/[PostgreSQL] -* link:https://aws.amazon.com/rds/[RDS] - -:context: {parent-context-of-external-database-setup} diff --git a/modules/administration-guide/partials/con_gateway.adoc b/modules/administration-guide/partials/con_gateway.adoc deleted file mode 100644 index 622bcaa53c..0000000000 --- a/modules/administration-guide/partials/con_gateway.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="gateway_{context}"] -= Gateway - -The {prod-short} gateway is a Traefik instance applying {orch-name} Role based access control (RBAC) policies to control access to any {prod-short} resource. -The {prod-short} operator manages it as the `che-gateway` Deployment. - -It controls access to: - -* xref:dashboard.adoc[] -* xref:devfile-registries.adoc[] -* xref:che-server.adoc[] -* xref:plug-in-registry.adoc[] -* xref:user-workspaces.adoc[] - -.{prod-short} gateway interactions with other components -image::architecture/{project-context}-gateway-interactions.png[{prod-short} gateway interactions with other components] - -.Additional resources - -* xref:managing-identities-and-authorizations.adoc[] diff --git a/modules/administration-guide/partials/con_machine-token-validation.adoc b/modules/administration-guide/partials/con_machine-token-validation.adoc deleted file mode 100644 index 696248f05d..0000000000 --- a/modules/administration-guide/partials/con_machine-token-validation.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// authenticating-in-a-{prod-id-short}-workspace - -[id="machine-token-validation_{context}"] -= Machine token validation - -The validation of machine tokens (JWT tokens) is performed using a dedicated per-workspace service with `JWTProxy` running on it in a separate Pod. When the workspace starts, this service receives the public part of the SHA key from the {prod-short} server. A separate verification endpoint is created for each secure server. When traffic comes to that endpoint, `JWTProxy` tries to extract the token from the cookies or headers and validates it using the public-key part. - -To query the {prod-short} server, a workspace server can use the machine token provided in the `CHE_MACHINE_TOKEN` environment variable. This token is the user's who starts the workspace. The scope of such requests is restricted to the current workspace only. The list of allowed operations is also strictly limited. diff --git a/modules/administration-guide/partials/con_operator-requirements.adoc b/modules/administration-guide/partials/con_operator-requirements.adoc new file mode 100644 index 0000000000..27aa1a5116 --- /dev/null +++ b/modules/administration-guide/partials/con_operator-requirements.adoc @@ -0,0 +1,51 @@ +// {prod-id-short}-compute-resources-requirements + +[id="operator-requirements_{context}"] += {prod-short} Operator requirements + +The {prod-short} Operator manages six operands running in six distinct pods. The following table presents the default resource requirements of each of these operands. + +[cols="2,2,1,1", options="header"] +.{prod-short} operator operands +|=== +|Pod +|Container names +|Default memory limit +|Default memory request + +|{prod-short} Server +|{prod-short} +|1 Gi +|512 MiB + +|{prod-short} Gateway +|`gateway`, `configbump`, `oauth-proxy`, `kube-rbac-proxy` +| 4 Gi, 256Mi, 512Mi, 512Mi +| 128 Mi, 64Mi, 64Mi, 64Mi + +|{prod-short} Dashboard +|`{prod-short}-dashboard` +|256 Mi +|32 Mi + +|PostgreSQL +|`postgres` +|1 Gi +|512 Mi + +|Devfile registry +|`che-devfile-registry` +|256 Mi +|32 Mi + +|Plug-in registry +|`che-plugin-registry` +|256 Mi +|32 Mi +|=== + +The {prod-short} Operator, which powers all the operands, consists of a single container with the `64Mi` memory request and `256Mi` limit. These default values are sufficient when the {prod-short} Operator manages a relatively big amount of {prod-short} workspaces. For even larger deployments, consider increasing the defaults. + +.Additional resources + +* xref:architecture-overview.adoc[]. diff --git a/modules/administration-guide/partials/con_persistent-volumes-backups.adoc b/modules/administration-guide/partials/con_persistent-volumes-backups.adoc deleted file mode 100644 index 640c8cd1e1..0000000000 --- a/modules/administration-guide/partials/con_persistent-volumes-backups.adoc +++ /dev/null @@ -1,33 +0,0 @@ - - -:parent-context-of-persistent-volumes-backups: {context} - -[id="persistent-volumes-backups_{context}"] -= Persistent Volumes backups - -:context: persistent-volumes-backups - -Persistent Volumes (PVs) store the {prod-short} workspace data similarly to how workspace data is stored for desktop IDEs on the local hard disk drive. - -To prevent data loss, back up PVs periodically. The recommended approach is to use storage-agnostic tools for backing up and restoring {platforms-name} resources, including PVs. - -[id="recommended-backup-tool-velero_{context}"] -== Recommended backup tool: Velero - -Velero is an open-source tool for backing up {orch-name} applications and their PVs. Velero allows you to: - -* Deploy in the cloud or on premises. -* Back up the cluster and restore in case of data loss. -* Migrate cluster resources to other clusters. -* Replicate a production cluster to development and testing clusters. - -NOTE: Alternatively, you can use backup solutions dependent on the underlying storage system. For example, solutions that are Gluster or Ceph-specific. - -.Additional resources - -* link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/[Persistent Volumes documentation] -* link:https://www.gluster.org/[Gluster documentation] -* link:https://docs.ceph.com/docs/master/[Ceph documentation] -* link:https://github.com/vmware-tanzu/velero[Velero on GitHub] - -:context: {parent-context-of-persistent-volumes-backups} diff --git a/modules/administration-guide/partials/con_plug-in-registry.adoc b/modules/administration-guide/partials/con_plug-in-registry.adoc deleted file mode 100644 index 8e41c25470..0000000000 --- a/modules/administration-guide/partials/con_plug-in-registry.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-with-devworkspace - -[id="plug-in-registry_{context}"] -= Plug-in registry - -Each {prod-short} workspace starts with a specific editor and set of associated extensions. -The {prod-short} plug-in registry provides the list of available editors and editor extensions. -A Devfile v2 describes each editor or extension. - -The xref:dashboard.adoc[] is reading the content of the registry. - -.Plug-in registries interactions with other components -image::architecture/{project-context}-plugin-registry-interactions.png[Plug-in registries interactions with other components] - -.Additional resources - -* xref:building-and-running-a-custom-registry-image.adoc[] -* link:https://github.com/eclipse-che/che-plugin-registry/blob/main/che-editors.yaml[Editors definitions in the {prod-short} plug-in registry repository] -* link:https://github.com/eclipse-che/che-plugin-registry/blob/main/che-theia-plugins.yaml[Plug-ins definitions in the {prod-short} plug-in registry repository] -* link:https://eclipse-che.github.io/che-plugin-registry/main/index.json[Plug-in registry latest community version online instance] - diff --git a/modules/administration-guide/partials/con_postgresql.adoc b/modules/administration-guide/partials/con_postgresql.adoc deleted file mode 100644 index 7a0d7ab000..0000000000 --- a/modules/administration-guide/partials/con_postgresql.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller-with-devworkspace - -[id="postgresql_{context}"] -= PostgreSQL - -{prod-short} server uses the PostgreSQL database to persist user configurations such as workspaces metadata. - -The {prod-short} deployment starts a dedicated PostgreSQL instance in the `postgres` Deployment. -You can use an external database instead. - -.PostgreSQL interactions with other components -image::architecture/{project-context}-postgresql-interactions.png[PostgreSQL interactions with other components] - -.Additional resources - -* xref:administration-guide:external-database-setup.adoc[] - -include::example$snip_che-postgresql-additional-resources.adoc[] - diff --git a/modules/administration-guide/partials/con_setup-backup-server.adoc b/modules/administration-guide/partials/con_setup-backup-server.adoc deleted file mode 100644 index b3605b0d16..0000000000 --- a/modules/administration-guide/partials/con_setup-backup-server.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="setting-up-a-backup-server"] -= Setting up a backup server - -The following section describes the supported {prod-short} backup servers and provides information for their setup. - -include::partial$snip_internal-backup-server-warning.adoc[] - -{prod-short} uses the link:https://restic.readthedocs.io/en/latest/[`restic`] tool to: - -* manage backup snapshots - -* push to or to pull backup data from a backup server -+ -[NOTE] -==== -The `restic` backup tool is licensed under the link:https://opensource.org/licenses/BSD-2-Clause[BSD 2-Clause] license. -==== - -.The backup servers currently supported for {prod-short}: - -REST:: The REST server is a solution designed to cooperate with the `restic` tool. See link:https://restic.readthedocs.io/en/latest/[How to set up a REST server] documentation. - -Amazon S3 and API compatible alternatives:: See link:https://docs.aws.amazon.com/s3/index.html[AWS S3 Simple Storage Service Documentation] or the docs of alternative services that have compatible API with AWS. - -SFTP:: See link:https://access.redhat.com/solutions/2399571[How to configure an SFTP server] -ifeval::["{project-context}" == "che"] -or link:https://www.manpagez.com/man/8/sftp-server/[SFTP man page] -endif::[] -. diff --git a/modules/administration-guide/partials/con_super-privileged-mode.adoc b/modules/administration-guide/partials/con_super-privileged-mode.adoc deleted file mode 100644 index 1207c1fea4..0000000000 --- a/modules/administration-guide/partials/con_super-privileged-mode.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// authorizing-users - -[id="super-privileged-mode_{context}"] -= super-privileged mode - -The *manageSystem* permission can be extended to provide a *super-privileged* mode. This allows the user to perform advanced actions on any resources managed by the system. A user can read and stop any workspace with the *manageSystem* permission and assign permissions to other users as needed. - -The *super-privileged* mode is disabled by default. To change to the *super-privileged* mode, set the `+CHE_SYSTEM_SUPER__PRIVILEGED__MODE+` environment variable to `true`. The list of services that are enabled for users with the *manageSystems* permissions and with *super-privileged* mode on: - -[options="header"] -|==== -|Path|HTTP Method|Description -|`/workspace/namespace/{namespace:.*}`|GET|Get all workspaces for the given {orch-namespace}. -|`/workspace/\{id}`|DELETE|Stop a workspace. -|`/workspace/\{key:.*}`|GET|Get a workspace by key. -|==== diff --git a/modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-using-the-operator.adoc b/modules/administration-guide/partials/con_understanding-che-server-advanced-configuration.adoc similarity index 87% rename from modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-using-the-operator.adoc rename to modules/administration-guide/partials/con_understanding-che-server-advanced-configuration.adoc index dbbb679db2..bcd0ddb9fe 100644 --- a/modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-using-the-operator.adoc +++ b/modules/administration-guide/partials/con_understanding-che-server-advanced-configuration.adoc @@ -2,10 +2,10 @@ // // advanced-configuration-options -[id="understanding-{prod-id-short}-server-advanced-configuration-using-the-operator_{context}"] -= Understanding {prod-short} server advanced configuration using the Operator +[id="understanding-{prod-id-short}-server-advanced-configuration_{context}"] += Understanding {prod-short} server advanced configuration -The following section describes the {prod-short} server component advanced configuration method for a deployment using the Operator. +The following section describes the {prod-short} server component advanced configuration method for a deployment. Advanced configuration is necessary to: @@ -41,7 +41,7 @@ Previous versions of the {prod-short} Operator had a ConfigMap named `custom` to .Additional resources -* For the list of all parameters available in the `CheCluster` Custom Resource, see xref:configuring-the-che-installation.adoc[]. +* For the list of all parameters available in the `CheCluster` Custom Resource, see xref:understanding-the-checluster-custom-resource.adoc[]. * For the list of all parameters available to configure `customCheProperties`, see xref:{prod-id-short}-server-component-system-properties-reference_{context}[]. diff --git a/modules/administration-guide/partials/con_user-workspaces.adoc b/modules/administration-guide/partials/con_user-workspaces.adoc deleted file mode 100644 index 378febfe4e..0000000000 --- a/modules/administration-guide/partials/con_user-workspaces.adoc +++ /dev/null @@ -1,41 +0,0 @@ -[id="user-workspaces_{context}"] -= User workspaces - -.User workspaces interactions with other components -image::architecture/{project-context}-user-workspaces-interactions.png[User workspaces interactions with other components] - -User workspaces are web IDEs running in containers. - -A User workspace is a web application. It consists of microservices running in containers providing all the services of a modern IDE running in your browser: - -* Editor -* Language auto-completion -* Language server -* Debugging tools -* Plug-ins -* Application runtimes - -A workspace is one {orch-name} Deployment containing the workspace containers and enabled plug-ins, plus related {orch-name} components: - -* Containers -* ConfigMaps -* Services -* Endpoints -* Ingresses or Routes -* Secrets -* Persistent Volumes (PVs) - -A {prod-short} workspace contains the source code of the projects, persisted in a {platforms-name} Persistent Volume (PV). Microservices have read-write access to this shared directory. - -Use the devfile v2 format to specify the tools and runtime applications of a {prod-short} workspace. - -The following diagram shows one running {prod-short} workspace and its components. - -.{prod-short} workspace components -image::architecture/workspace-components-with-dw.png[] - -In the diagram, there is one running workspaces. - - -.Additional resources - diff --git a/modules/administration-guide/partials/con_workspace-jwt-token.adoc b/modules/administration-guide/partials/con_workspace-jwt-token.adoc deleted file mode 100644 index 5057554fd5..0000000000 --- a/modules/administration-guide/partials/con_workspace-jwt-token.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// authenticating-in-a-{prod-id-short}-workspace - -[id="workspace-jwt-token_{context}"] -= Workspace JWT token - -Workspace tokens are JSON web tokens (link:https://jwt.io/[JWT]) that contain the following information in their claims: - -* `uid`: The ID of the user who owns this token -* `uname`: The name of the user who owns this token -* `wsid`: The ID of a workspace which can be queried with this token - -Every user is provided with a unique personal token for each workspace. The structure of a token and the signature are different than they are in {identity-provider}. The following is an example token view: - -[source,json] ----- -# Header -{ - "alg": "RS512", - "kind": "machine_token" -} -# Payload -{ - "wsid": "workspacekrh99xjenek3h571", - "uid": "b07e3a58-ed50-4a6e-be17-fcf49ff8b242", - "uname": "john", - "jti": "06c73349-2242-45f8-a94c-722e081bb6fd" -} -# Signature -{ - "value": "RSASHA256(base64UrlEncode(header) + . + base64UrlEncode(payload))" -} ----- - -The SHA-256 cipher with the RSA algorithm is used for signing JWT tokens. It is not configurable. Also, there is no public service that distributes the public part of the key pair with which the token is signed. diff --git a/modules/administration-guide/partials/proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc b/modules/administration-guide/partials/proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc deleted file mode 100644 index d91502d427..0000000000 --- a/modules/administration-guide/partials/proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// running-custom-registries - -[id="adding-a-custom-plug-in-registry-in-an-existing-che-workspace_{context}"] -= Adding a custom plug-in registry in an existing {prod-short} workspace - - -The following section describes two methods of adding a custom plug-in registry in an existing {prod-short} workspace: - -* xref:adding-a-custom-plug-in-registry-using-command-palette_{context}[Adding a custom plug-in registry using Command palette] - For adding a new custom plug-in registry quickly, with a use of text inputs from Command palette command. This method does not allow a user to edit already existing information, such as plug-in registry URL or name. - -* xref:adding-a-custom-plug-in-registry-using-the-settings-file_{context}[Adding a custom plug-in registry using the `settings.json` file] - For adding a new custom plug-in registry and editing of the already existing entries. - - -[id="adding-a-custom-plug-in-registry-using-command-palette_{context}"] -== Adding a custom plug-in registry using Command Palette - - -.Prerequisites - -* An instance of {prod-short} - - -.Procedure - -. In the {prod-short} IDE, press kbd:[F1] to open the Command Palette, or navigate to *View -> Find Command* in the top menu. -+ -The *command palette* can be also activated by pressing kbd:[Ctrl+Shift+p] (or kbd:[Cmd+Shift+p] on macOS). - -. Enter the `Add Registry` command into the search box and pres kbd:[Enter] once filled. - -. Enter the registry name and registry URL in next two command prompts. -+ -* After adding a new plug-in registry, the list of plug-ins in the *Plug-ins* view is refreshed, and if the new plug-in registry is not valid, a user is notified by a warning message. - - - -[id="adding-a-custom-plug-in-registry-using-the-settings-file_{context}"] -== Adding a custom plug-in registry using the `settings.json` file - -The following section describes the use of the main {prod-short} Settings menu to edit and add a new plug-in registry using the `settings.json` file. - - -.Prerequisites - -* An instance of {prod-short} - -.Procedure - -. From the main {prod-short} screen, select *Open Preferences* by pressing kbd:[Ctrl+,] -or using the gear wheel icon on the left bar. - -. Select *Che Plug-ins* and continue by *Edit in `setting.json`* link. -+ -The `setting.json` file is displayed. - -. Add a new plug-in registry using the `chePlugins.repositories` attribute as shown below: -+ -[source,yaml,subs="+macros,attributes"] ----- -{ -“application.confirmExit”: “never”, -“chePlugins.repositories”: {“test”: “pass:c,m,a,q[+https+://test.com]”} -} ----- - -. Save the changes to add a custom plug-in registry in an existing {prod-short} workspace. -+ -* A newly added plug-in validation tool checks the correctness of URL values set in the `chePlugins.repositories` field of the `settings.json` file. -+ -* After adding a new plug-in registry, the list of plug-ins in the *Plug-ins* view is refreshed, and if the new plug-in registry is not valid, a user is notified by a warning message. This check is also functional for plug-ins added using the Command palette command `Add plugin registry`. - diff --git a/modules/administration-guide/partials/proc_applying-the-bitbucket-application-link-secret.adoc b/modules/administration-guide/partials/proc_applying-the-bitbucket-application-link-secret.adoc new file mode 100644 index 0000000000..91e0615dbf --- /dev/null +++ b/modules/administration-guide/partials/proc_applying-the-bitbucket-application-link-secret.adoc @@ -0,0 +1,58 @@ +:_content-type: PROCEDURE +:description: Applying the Bitbucket application link Secret +:keywords: bitbucket, bitbucket-application, bitbucket-app, bitbucket-application-link, bitbucket-app-link, bitbucket-secret, secret +:navtitle: Applying the Bitbucket application link Secret +// :page-aliases: + +[id="applying-the-bitbucket-application-link-secret_{context}"] += Applying the Bitbucket application link Secret + +Prepare and apply the Bitbucket application link Secret. + +.Prerequisites +* Setting up the Bitbucket application link is completed. +* The following Base64-encoded files, which were created when setting up the Bitbucket application link, are prepared: +** `privatepkcs8-stripped.pem` +** `bitbucket_consumer_key` +** `bitbucket-shared-secret` +* `{orch-cli}` is installed in the operating system you are using. See {link-installing-orch-cli}. + +.Procedure + +. Prepare the Secret: ++ +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +kind: Secret +apiVersion: v1 +metadata: + name: bitbucket-oauth-config + namespace: {prod-namespace} <1> + labels: + app.kubernetes.io/component: oauth-scm-configuration + app.kubernetes.io/part-of: che.eclipse.org + annotations: + che.eclipse.org/oauth-scm-server: bitbucket + che.eclipse.org/scm-server-endpoint: __<bitbucket_server_url>__ <2> +type: Opaque +data: + private.key: __<Base64_content_of_privatepkcs8-stripped.pem>__ <3> + consumer.key: __<Base64_content_of_bitbucket_server_consumer_key>__ <4> + shared_secret: __<Base64_content_of_bitbucket-shared-secret>__ <5> +---- +<1> The {prod-short} namespace. The default is `{prod-namespace}`. +<2> The Bitbucket server URL. +<3> The Base64-encoded content of the `privatepkcs8-stripped.pem` file. +<4> The Base64-encoded content of the `bitbucket_consumer_key` file. +<5> The Base64-encoded content of the `bitbucket-shared-secret` file. + +. Apply the Secret by entering it with `{orch-cli}` on a command line: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ {orch-cli} apply -f - <<EOF +__<Secret_prepared_in_the_previous_step>__ +EOF +---- + +. Verify in the output that the Secret is created. \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_applying-the-github-oauth-app-secret.adoc b/modules/administration-guide/partials/proc_applying-the-github-oauth-app-secret.adoc new file mode 100644 index 0000000000..5136a8d022 --- /dev/null +++ b/modules/administration-guide/partials/proc_applying-the-github-oauth-app-secret.adoc @@ -0,0 +1,53 @@ +:_content-type: PROCEDURE +:description: Applying the GitHub OAuth App Secret +:keywords: github-oauth-app, apply, secret, github +:navtitle: Applying the GitHub OAuth App Secret +// :page-aliases: + +[id="applying-the-github-oauth-app-secret_{context}"] += Applying the GitHub OAuth App Secret + +Prepare and apply the GitHub OAuth App Secret. + +.Prerequisites +* Setting up the GitHub OAuth App is completed. +* The Base64-encoded values, which were generated when setting up the GitHub OAuth App, are prepared: +** *GitHub OAuth Client ID* +** *GitHub OAuth Client Secret* +* `{orch-cli}` is installed in the operating system you are using. See {link-installing-orch-cli}. + +.Procedure + +. Prepare the Secret: ++ +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +kind: Secret +apiVersion: v1 +metadata: + name: github-oauth-config + namespace: {prod-namespace} <1> + 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 +data: + id: __<Base64_GitHub_OAuth_Client_ID>__ <2> + secret: __<Base64_GitHub_OAuth_Client_Secret>__ <3> +---- +<1> The {prod-short} namespace. The default is `{prod-namespace}`. +<2> The Base64-encoded *GitHub OAuth Client ID*. +<3> The Base64-encoded *GitHub OAuth Client Secret*. + +. Apply the Secret by entering it with `{orch-cli}` on a command line: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ {orch-cli} apply -f - <<EOF +__<Secret_prepared_in_the_previous_step>__ +EOF +---- + +. Verify in the output that the Secret is created. \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_applying-the-gitlab-authorized-application-secret.adoc b/modules/administration-guide/partials/proc_applying-the-gitlab-authorized-application-secret.adoc new file mode 100644 index 0000000000..6268d1254f --- /dev/null +++ b/modules/administration-guide/partials/proc_applying-the-gitlab-authorized-application-secret.adoc @@ -0,0 +1,56 @@ +:_content-type: PROCEDURE +:description: Applying the GitLab-authorized application Secret +:keywords: gitlab, apply, secret, gitlab-application, gitlab-client-secret +:navtitle: Applying the GitLab-authorized application Secret +// :page-aliases: + +[id="applying-the-gitlab-authorized-application-secret_{context}"] += Applying the GitLab-authorized application Secret + +Prepare and apply the GitLab-authorized application Secret. + +.Prerequisites +* Setting up the GitLab authorized application is completed. +* The Base64-encoded values, which were generated when setting up the GitLab authorized application, are prepared: +** *GitLab Application ID* +** *GitLab Client Secret* +* `{orch-cli}` is installed in the operating system you are using. See {link-installing-orch-cli}. + + +.Procedure + +. Prepare the Secret: ++ +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +kind: Secret +apiVersion: v1 +metadata: + name: gitlab-oauth-config + namespace: {prod-namespace} <1> + labels: + app.kubernetes.io/part-of: che.eclipse.org + app.kubernetes.io/component: oauth-scm-configuration + annotations: + che.eclipse.org/oauth-scm-server: gitlab + che.eclipse.org/scm-server-endpoint: __<gitlab_server_url>__ <2> +type: Opaque +data: + id: __<Base64_GitLab_Application_ID>__ <3> + secret: __<Base64_GitLab_Client_Secret>__ <4> +---- +<1> The {prod-short} namespace. The default is `{prod-namespace}`. +<2> The *GitLab server URL*. +<3> The Base64-encoded *GitLab Application ID*. +<4> The Base64-encoded *GitLab Client Secret*. + +. Apply the Secret by entering it with `{orch-cli}` on a command line: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ {orch-cli} apply -f - <<EOF +__<Secret_prepared_in_the_previous_step>__ +EOF +---- + +. Verify in the output that the Secret is created. \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_assigning-che-permissions.adoc b/modules/administration-guide/partials/proc_assigning-che-permissions.adoc deleted file mode 100644 index 5f8f3fb84b..0000000000 --- a/modules/administration-guide/partials/proc_assigning-che-permissions.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// authorizing-users - -[id="assigning-{prod-id-short}-permissions_{context}"] -= Assigning {prod-short} permissions - -To assign permissions to a resource, perform the `POST /permissions` request. The suitable domain values are: - -* system -* organization -* workspace - -The following is a message body that requests permissions for a user with a `userId` to a workspace with a `workspaceID`: - -.Requesting {prod-short} user permissions -[source,json] ----- -{ - "actions": [ - "read", - "use", - "run", - "configure", - "setPermissions" - ], - "userId": "userID", <1> - "domainId": "workspace", - "instanceId": "workspaceID" <2> -} ----- -<1> The *userId* parameter is the ID of the user that has been granted certain permissions. -<2> The *instanceId* parameter is the ID of the resource that retrieves the permission for all users. diff --git a/modules/administration-guide/partials/proc_authenticating-to-the-che-server-using-oauth.adoc b/modules/administration-guide/partials/proc_authenticating-to-the-che-server-using-oauth.adoc deleted file mode 100644 index 83553a0a53..0000000000 --- a/modules/administration-guide/partials/proc_authenticating-to-the-che-server-using-oauth.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// authenticating-to-the-{prod-id-short}-server - -[id="authenticating-to-the-{prod-id-short}-server-using-oauth_{context}"] -= Authenticating to the {prod-short} server using OAuth - -For easy user interaction with third-party services, the {prod-short} server supports OAuth authentication. OAuth tokens are also used for GitHub-related plug-ins. - -OAuth authentication has two main flows: - -delegated:: Default. Delegates OAuth authentication to {identity-provider} server. -embedded:: Uses built-in {prod-short} server mechanism to communicate with OAuth providers. - -To switch between the two implementations, use the `che.oauth.service_mode=__<embedded|delegated>__` configuration property. - -The main REST endpoint in the OAuth API is `/api/oauth`, which contains: - -* An authentication method, `/authenticate`, that the OAuth authentication flow can start with. -* A callback method, `/callback`, to process callbacks from the provider. -* A token GET method, `/token`, to retrieve the current user's OAuth token. -* A token DELETE method, `/token`, to invalidated the current user's OAuth token. -* A GET method, `/`, to get the list of configured identity providers. diff --git a/modules/administration-guide/partials/proc_authenticating-to-the-che-server-using-other-authentication-implementations.adoc b/modules/administration-guide/partials/proc_authenticating-to-the-che-server-using-other-authentication-implementations.adoc deleted file mode 100644 index d93cae4e25..0000000000 --- a/modules/administration-guide/partials/proc_authenticating-to-the-che-server-using-other-authentication-implementations.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// authenticating-to-the-{prod-id-short}-server - -[id="authenticatinng-to-the-{prod-id-short}-server-using-other-authentication-implementations_{context}"] -= Authenticating to the {prod-short} server using other authentication implementations - -This procedure describes how to use an OpenID Connect (OIDC) authentication implementation other than {identity-provider}. - -.Procedure - -. Update the authentication configuration parameters that are stored in the `multiuser.properties` file (such as client ID, authentication URL, realm name). - -. Write a single filter or a chain of filters to validate tokens, create the user in the {prod-short} dashboard, and compose the `subject` object. - -. If the new authorization provider supports the OpenID protocol, use the OIDC JS client library available at the settings endpoint because it is decoupled from specific implementations. - -. If the selected provider stores additional data about the user (first and last name, job title), it is recommended to write a provider-specific *ProfileDao* implementation that provides this information. diff --git a/modules/contributor-guide/partials/proc_building-a-che-theia-container-image-with-custom-branding.adoc b/modules/administration-guide/partials/proc_building-a-che-theia-container-image-with-custom-branding.adoc similarity index 100% rename from modules/contributor-guide/partials/proc_building-a-che-theia-container-image-with-custom-branding.adoc rename to modules/administration-guide/partials/proc_building-a-che-theia-container-image-with-custom-branding.adoc diff --git a/modules/administration-guide/partials/proc_building-a-custom-devfile-registry-image.adoc b/modules/administration-guide/partials/proc_building-a-custom-devfile-registry-image.adoc deleted file mode 100644 index e0fafeef97..0000000000 --- a/modules/administration-guide/partials/proc_building-a-custom-devfile-registry-image.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Used in: -// * administration-guide/building-custom-registry-images/ - -[id="building-a-custom-devfile-registry-image_{context}"] -= Building a custom devfile registry image - -This section describes how to build a custom devfile registry image. -The procedure explains how to add a devfile. -The image contains all sample projects referenced in devfiles. - -.Prerequisites - -* A running installation of link:http://podman.io[podman] or link:http://docker.io[docker]. - -* Valid content for the devfile to add. See: xref:end-user-guide:authoring-devfiles-version-2.adoc[]. - -.Procedure - -. Clone the devfile registry repository and check out the version to deploy: -+ -include::example$snip_{project-context}-clone-the-devfile-registry-repository.adoc[] - -. In the `./{che-devfile-registry-directory}/devfiles/` directory, create a subdirectory `__<devfile-name>__/` and add the `devfile.yaml` and `meta.yaml` files. -+ -.File organization for a devfile -==== -[subs="+attributes,+quotes"] ----- -./{che-devfile-registry-directory}/devfiles/ -└── __<devfile-name>__ - ├── devfile.yaml - └── meta.yaml ----- -==== - -. Add valid content in the `devfile.yaml` file. For a detailed description of the devfile format, see xref:end-user-guide:authoring-devfiles-version-2.adoc[]. - -. Ensure that the `meta.yaml` file conforms to the following structure: -+ -.Parameters for a devfile `meta.yaml` -[%header,format=csv,cols="1m,3"] -|=== -Attribute, Description -description, Description as it appears on the user dashboard. -displayName, Name as it appears on the user dashboard. -icon, Link to an `.svg` file that is displayed on the user dashboard. -tags, List of tags. Tags typically include the tools included in the stack. -globalMemoryLimit, Optional parameter: the sum of the expected memory consumed by all the components launched by the devfile. This number will be visible on the user dashboard. It is informative and is not taken into account by the {prod-short} server. -|=== -+ -.Example devfile `meta.yaml` -==== -include::example$snip_{project-context}-devfile-meta.adoc[] -==== - -. Build a custom devfile registry image: -+ -include::example$snip_{project-context}-build-a-custom-devfile-registry.adoc[] -+ -[NOTE] -==== -To display full options for the `build.sh` script, use the `--help` parameter. -==== - -.Additional resources - -* xref:end-user-guide:authoring-devfiles-version-2.adoc[]. - -* xref:running-custom-registries.adoc[]. diff --git a/modules/administration-guide/partials/proc_building-a-custom-plug-in-registry-image.adoc b/modules/administration-guide/partials/proc_building-a-custom-plug-in-registry-image.adoc deleted file mode 100644 index 31e7044271..0000000000 --- a/modules/administration-guide/partials/proc_building-a-custom-plug-in-registry-image.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Used in: -// * installation-guide/installing-che-in-a-restricted-environment/ -// * installation-guide/upgrading-che-using-the-cli-management-tool-in-restricted-environment/ -// * administration-guide/building-custom-registry-images/ - -[id="building-a-custom-plug-ins-registry-image_{context}"] -= Building a custom plug-ins registry image - -This section describes how to build a custom plug-ins registry image. -The procedure explains how to add a plug-in. -The image contains plug-ins or extensions metadata. - -.Prerequisites - -* Node.js 12.x - -* A running version of yarn. See: link:https://yarnpkg.com/getting-started/install[Installing Yarn]. - -* `./node_modules/.bin` is in the `PATH` environment variable. - -* A running installation of link:http://podman.io[podman] or link:http://docker.io[docker]. - - -.Procedure - -. Clone the plug-ins registry repository and check out the version to deploy: -+ -include::example$snip_{project-context}-clone-the-plug-in-registry-repository.adoc[] - -. In the `./{che-plugin-registry-directory}/` directory, edit the `che-theia-plugins.yaml` file. -+ - -. Add valid content to the `che-theia-plugins.yaml` file, for detailed information see: xref:end-user-guide:adding-a-vs-code-extension-to-the-che-plugin-registry.adoc[]. - -. Build a custom plug-ins registry image: -+ -include::example$snip_{project-context}-build-a-custom-plug-in-registry.adoc[] -+ -[NOTE] -==== -To display full options for the `build.sh` script, use the `--help` parameter. -To include the plug-in binaries in the registry image, add the `--offline` parameter. -==== - -include::example$snip_che-plugin-registry-build-output.adoc[] - -.Additional resources - -* xref:running-custom-registries.adoc[]. diff --git a/modules/installation-guide/partials/proc_building-an-offline-devfile-registry-image.adoc b/modules/administration-guide/partials/proc_building-an-offline-devfile-registry-image.adoc similarity index 77% rename from modules/installation-guide/partials/proc_building-an-offline-devfile-registry-image.adoc rename to modules/administration-guide/partials/proc_building-an-offline-devfile-registry-image.adoc index a63e2a3794..5bf7b668ab 100644 --- a/modules/installation-guide/partials/proc_building-an-offline-devfile-registry-image.adoc +++ b/modules/administration-guide/partials/proc_building-an-offline-devfile-registry-image.adoc @@ -1,6 +1,6 @@ // Used in: -// * installation-guide/installing-che-in-a-restricted-environment/ -// * installation-guide/upgrading-che-using-the-cli-management-tool-in-restricted-environment/ +// * administration-guide/installing-che-in-a-restricted-environment/ +// * administration-guide/upgrading-che-using-the-cli-management-tool-in-restricted-environment/ [id="building-an-offline-devfile-registry-image_{context}"] = Building an offline devfile registry image @@ -28,7 +28,3 @@ include::example$snip_{project-context}-build-an-offline-devfile-registry.adoc[] To display full options for the `build.sh` script, use the `--help` parameter. ==== - -.Additional resources - -* xref:administration-guide:customizing-the-registries.adoc[]. diff --git a/modules/installation-guide/partials/proc_building-an-offline-plug-in-registry-image.adoc b/modules/administration-guide/partials/proc_building-an-offline-plug-in-registry-image.adoc similarity index 80% rename from modules/installation-guide/partials/proc_building-an-offline-plug-in-registry-image.adoc rename to modules/administration-guide/partials/proc_building-an-offline-plug-in-registry-image.adoc index 4e778b077f..df09ebf185 100644 --- a/modules/installation-guide/partials/proc_building-an-offline-plug-in-registry-image.adoc +++ b/modules/administration-guide/partials/proc_building-an-offline-plug-in-registry-image.adoc @@ -1,6 +1,6 @@ // Used in: -// * installation-guide/installing-che-in-a-restricted-environment/ -// * installation-guide/upgrading-che-using-the-cli-management-tool-in-restricted-environment/ +// * administration-guide/installing-che-in-a-restricted-environment/ +// * administration-guide/upgrading-che-using-the-cli-management-tool-in-restricted-environment/ [id="building-an-offline-plug-in-registry-image_{context}"] @@ -35,7 +35,3 @@ include::example$snip_{project-context}-build-an-offline-plug-in-registry.adoc[] To display full options for the `build.sh` script, use the `--help` parameter. ==== - -.Additional resources - -* xref:administration-guide:customizing-the-registries.adoc[]. diff --git a/modules/administration-guide/partials/proc_collecting-che-metrics-with-prometheus.adoc b/modules/administration-guide/partials/proc_collecting-che-metrics-with-prometheus.adoc index baf554372d..e1166ff125 100644 --- a/modules/administration-guide/partials/proc_collecting-che-metrics-with-prometheus.adoc +++ b/modules/administration-guide/partials/proc_collecting-che-metrics-with-prometheus.adoc @@ -3,13 +3,13 @@ [id="collecting-{prod-id-short}-metrics-with-prometheus_{context}"] = Collecting {prod-short} metrics with Prometheus -This section describes how to use the Prometheus monitoring system to collect, store and query metrics about {prod-short}. +This section describes how to use the Prometheus monitoring system to collect, store, and query metrics about {prod-short}. .Prerequisites * {prod-short} is exposing metrics on port `8087`. See xref:enabling-and-exposing-{prod-id-short}-metrics_{context}[Enabling and exposing {prod-short} metrics]. -* Prometheus 2.9.1 or higher is running. The Prometheus console is running on port `9090` with a corresponding *service* and *route*. See link:https://prometheus.io/docs/introduction/first_steps/[First steps with Prometheus]. +* Prometheus 2.9.1 or later is running. The Prometheus console is running on port `9090` with a corresponding *service* and *route*. See link:https://prometheus.io/docs/introduction/first_steps/[First steps with Prometheus]. .Procedure @@ -22,7 +22,7 @@ include::example$prometheus-config.adoc[] + <1> Rate, at which a target is scraped. <2> Rate, at which recording and alerting rules are re-checked (not used in the system at the moment). -<3> Resources Prometheus monitors. In the default configuration, there is a single job called `che`, which scrapes the time series data exposed by the {prod-short} server. +<3> Resources Prometheus monitors. In the default configuration, a single job called `che`, scrapes the time series data exposed by the {prod-short} server. <4> Scrape metrics from the `8087` port. .Verification steps @@ -31,7 +31,7 @@ include::example$prometheus-config.adoc[] + Metrics are available at: `http://_<che-server-url>_:9090/metrics`. + -For more information, see link:https://prometheus.io/docs/introduction/first_steps/#using-the-expression-browser[Using the expression browser] in the Prometheus documentation. +For more information, see link:https://prometheus.io/docs/introduction/first_steps/#using-the-expression-browser[Using the expression browser]. .Additional resources diff --git a/modules/administration-guide/partials/proc_collecting-dev-workspace-operator-metrics-with-prometheus.adoc b/modules/administration-guide/partials/proc_collecting-dev-workspace-operator-metrics-with-prometheus.adoc new file mode 100644 index 0000000000..1f09fb87e0 --- /dev/null +++ b/modules/administration-guide/partials/proc_collecting-dev-workspace-operator-metrics-with-prometheus.adoc @@ -0,0 +1,121 @@ +[id="proc_collecting-dev-workspace-operator-metrics-with-prometheus_{context}"] += Collecting {devworkspace} operator metrics with Prometheus + +[role="_abstract"] +This section describes how to use the Prometheus to collect, store, and query metrics about the {devworkspace} operator. + +.Prerequisites + +* The default configuration is set: +** The `devworkspace-controller-metrics` service is exposing metrics on port `8443`. +** The `devworkspace-webhookserver` service is exposing metrics on `9443`. + +* Prometheus 2.26.0 or later is running. The Prometheus console is running on port `9090` with a corresponding *service* and *route*. See link:https://prometheus.io/docs/introduction/first_steps/[First steps with Prometheus]. + +.Procedure + +. Create a `ClusterRoleBinding` to bind the `ServiceAccount` associated with Prometheus to the link:https://github.com/devfile/devworkspace-operator/blob/main/deploy/deployment/kubernetes/objects/devworkspace-controller-metrics-reader.ClusterRole.yaml[devworkspace-controller-metrics-reader] `ClusterRole`. +Without the `ClusterRoleBinding`, you cannot access {devworkspace} metrics because they are protected with role-based access control (RBAC). ++ +.ClusterRole example +==== +[source,yaml,subs="+attributes"] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: devworkspace-controller-metrics-reader +rules: +- nonResourceURLs: + - /metrics + verbs: + - get +---- + +==== + ++ +.ClusterRoleBinding example +==== +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: devworkspace-controller-metrics-binding +subjects: + - kind: ServiceAccount + name: __<ServiceAccount_name>__ <1> + namespace: __<Prometheus_{orch-namespace}>__ <2> +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: devworkspace-controller-metrics-reader +---- + +<1> Name of the `ServiceAccount` associated with the Prometheus Pod. +<2> The {orch-namespace} in which Prometheus is running. + +==== + +. Configure Prometheus to scrape metrics from the `8443` port exposed by the `devworkspace-controller-metrics` service, and `9443` port exposed by the `devworkspace-webhookserver` service. ++ +.Prometheus configuration example +==== +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: prometheus-config +data: + prometheus.yml: |- + global: + scrape_interval: 5s <1> + evaluation_interval: 5s <2> + scrape_configs: <3> + - job_name: 'DevWorkspace' + scheme: https + authorization: + type: Bearer + credentials_file: '/var/run/secrets/kubernetes.io/serviceaccount/token' + tls_config: + insecure_skip_verify: true + static_configs: + - targets: ['__<devworkspace-controller-metrics_service_host>__:8443'] <4> + - job_name: 'DevWorkspace webhooks' + scheme: https + authorization: + type: Bearer + credentials_file: '/var/run/secrets/kubernetes.io/serviceaccount/token' + tls_config: + insecure_skip_verify: true + static_configs: + - targets: ['__<devworkspace-webhookserver_service_host>__:9443'] <5> +---- + +<1> Rate at which a target is scraped. +<2> Rate at which recording and alerting rules are re-checked. +<3> Resources that Prometheus monitors. In the default configuration, two jobs (`DevWorkspace` and `DevWorkspace webhooks`), scrape the time series data exposed by the `devworkspace-controller-metrics` and `devworkspace-webhookserver` services. +<4> Scrape metrics from the `8443` port. +<5> Scrape metrics from the `9443` port. + +==== + +.Verification steps + +* Use the Prometheus console to view targets and metrics. ++ +For more information, see link:https://prometheus.io/docs/introduction/first_steps/#using-the-expression-browser[Using the expression browser]. + + +[role="_additional-resources"] +.Additional resources + +* link:https://prometheus.io/docs/introduction/first_steps/[First steps with Prometheus]. + +* link:https://prometheus.io/docs/prometheus/latest/configuration/configuration/[Configuring Prometheus]. + +* link:https://prometheus.io/docs/prometheus/latest/querying/basics/[Querying Prometheus]. + +* link:https://prometheus.io/docs/concepts/metric_types/[Prometheus metric types]. diff --git a/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc b/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc deleted file mode 100644 index fc955a3c18..0000000000 --- a/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc +++ /dev/null @@ -1,185 +0,0 @@ -// Module included in the following assemblies: -// -// Configuring Bitbucket server OAuth1 - -[id="proc_configuring-bitbucket-server-oauth1_{context}"] -= Configuring the Bitbucket and {prod-short} integration to use OAuth1 - -The following section describes the configuration of the OAuth 1 authentication that is needed for performing read and write operations with Bitbucket (BB) repositories. To use BB repositories with allowed Git operations, such as `clone` and `push`, register a BB endpoint with {prod-short} first, and configure the OAuth 1 authentication. - -[NOTE] -==== -This procedure requires: - -* generating RSA key pairs -* generating a consumer key-secret pair -* creating an application link on the BB side -* configuring BB on the {prod-short}-server side -==== - -This procedure also describes how to activate OAuth 1 for Bitbucket Server to: - -* Use devfiles hosted on a Bitbucket Server. -* Enable {prod-short} to obtain and renew link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Bitbucket Server Personal access tokens]. - - -.Prerequisites - -* The `{orch-cli}` tool is available. -* Bitbucket Server is available from {prod-short} server. -* An instance of {prod-short}. - -.Procedure - -. Generate an RSA key pair and a stripped-down version of the public key: -+ -[subs="+quotes"] ----- -$ openssl genrsa -out __<private.pem>__ 2048 ----- -+ -[subs="+quotes"] ----- -$ openssl rsa -in __<private.pem>__ -pubout > __<public.pub>__ ----- -+ -[subs="+quotes"] ----- -$ openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in __<private.pem>__ -out __<privatepkcs8.pem>__ ----- -+ -[subs="+quotes"] ----- -$ cat __<public.pub>__ | sed 's/-----BEGIN PUBLIC KEY-----//g' | sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n' > __<public-stripped.pub>__ ----- - -. Generate a consumer key and a shared secret. -+ -[subs="+quotes"] ----- -$ openssl rand -base64 24 > __<bitbucket_server_consumer_key>__ ----- -+ -[subs="+quotes"] ----- -$ openssl rand -base64 24 > __<bitbucket_shared_secret>__ ----- - -. Configure an link:https://confluence.atlassian.com/adminjiraserver/using-applinks-to-link-to-other-applications-938846918.html[Application Link] in Bitbucket to enable the communication from {prod-short} to Bitbucket Server. - -.. In Bitbucket Server, click the cog in the top navigation bar to navigate to *Administration* > *Application Links*. - -.. Enter the application URL: `pass:c,a,q[{prod-url}]` and click the btn:[Create new link] button. - -.. In the warning message stating `No response was received from the URL` click the btn:[Continue] button. - -.. Complete the *Link Applications* form and click the btn:[Continue] button. -+ -==== -Application Name:: `__<{prod-short}>__` - -Application Type:: Generic Application. - -Service Provider Name:: `__<{prod-short}>__` - -Consumer Key:: Paste the content of the `__<bitbucket_server_consumer_key>__` file. - -Shared secret:: Paste the content of the `__<bitbucket_shared_secret>__` file. - -Request Token URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/request-token` - -Access token URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/access-token` - -Authorize URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/access-token` - -Create incoming link:: Enabled. -==== - -.. Complete the *Link Applications* form and click the btn:[Continue] button. -+ -==== -Consumer Key:: Paste the content of the `__<bitbucket_server_consumer_key>__` file. - -Consumer name:: `__<{prod-short}>__` - -Public Key:: Paste the content of the `__<public-stripped.pub>__` file. -==== - - -. Create a {orch-name} Secret in {prod-short} {orch-namespace} containing the consumer and private keys. -+ -[source,yaml,subs="+quotes,+attributes"] ----- -$ {orch-cli} apply -f - <<EOF -kind: Secret -apiVersion: v1 -metadata: - name: bitbucket-oauth-config - namespace: __<{prod-short}-namespace>__ <1> - labels: - app.kubernetes.io/component: oauth-scm-configuration - app.kubernetes.io/part-of: che.eclipse.org - annotations: - che.eclipse.org/oauth-scm-server: bitbucket - che.eclipse.org/scm-server-endpoint: '__<scm-server-endpoint>__' <2> -type: Opaque -data: - private.key: '__<user-private-key>__' <3> - consumer.key: '__<bitbucket_server_consumer_key>__' <4> -EOF ----- -+ -<1> {prod-short} namespace. The default is {prod-namespace} -<2> Bitbucket Server URL -<3> base64 encoded content of the `__<privatepkcs8.pem>__` file without first and last lines. -<4> base64 encoded content of the `__<bitbucket_server_consumer_key>__` file. -+ -.Example -+ -[source,bash,subs="+quotes"] ----- -#!/usr/bin/env bash - -NS=${1:-eclipse-che} -CONSUMER_KEY=$(cat ./certs/bitbucket_server_consumer_key) -PRIVATE_KEY=$(cat ./certs/privatepkcs8.pem | sed 's/-----BEGIN PRIVATE KEY-----//g' | sed 's/-----END PRIVATE KEY-----//g' | tr -d '\n') -BITBUCKET_HOST='__<your-bitbucket-host-here>__' -unameOut="$(uname -s)" - -case "${unameOut}" in - Linux*) BASE64_FUNC='base64 -w 0';; - Darwin*) BASE64_FUNC='base64';; - CYGWIN*) BASE64_FUNC='base64 -w 0';; - MINGW*) BASE64_FUNC='base64 -w 0';; - *) BASE64_FUNC='base64 -w 0' -esac - -cat <<EOF | oc apply -n $NS -f - -kind: Secret -apiVersion: v1 -metadata: - name: bitbucket-oauth-config - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: oauth-scm-configuration - annotations: - che.eclipse.org/oauth-scm-server: bitbucket - che.eclipse.org/scm-server-endpoint: https://$BITBUCKET_HOST -type: Opaque -data: - private.key: $(echo -n $PRIVATE_KEY | $BASE64_FUNC) - consumer.key: $(echo -n $CONSUMER_KEY | $BASE64_FUNC) -EOF ----- -+ -* See the whole script in this link:https://github.com/skabashnyuk/gitsrv/blob/main/bitbucket/4_setupche.sh[GitHub example]. - - -.Additional resources - -* link:https://bitbucket.org/product/enterprise[Bitbucket Server overview] -* link:https://bitbucket.org/product/download[Download Bitbucket Server] -* link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Bitbucket Server Personal access tokens] -* link:https://confluence.atlassian.com/jirakb/how-to-generate-public-key-to-application-link-3rd-party-applications-913214098.html[How to generate public key to application link 3rd party applications] -* link:https://confluence.atlassian.com/adminjiraserver/using-applinks-to-link-to-other-applications-938846918.html[Using AppLinks to link to other applications] -* xref:end-user-guide:authenticating-on-scm-server-with-a-personal-access-token.adoc[]. diff --git a/modules/administration-guide/partials/proc_configuring-bitbucket-servers.adoc b/modules/administration-guide/partials/proc_configuring-bitbucket-servers.adoc deleted file mode 100644 index 34fba0db22..0000000000 --- a/modules/administration-guide/partials/proc_configuring-bitbucket-servers.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// configuring-bitbucket-servers - -[id="configuring_bitbucket_servers_{context}"] -= Configuring a Bitbucket server that uses self-signed TLS certificates - -The following chapter describes how to configure a Bitbucket (BB) server that uses self-signed TLS certificates so that the {prod-short} server and workspace components can establish a trusted connection with BB. - -* Creating ConfigMaps for additional TLS and `gitSelfSign` certificates. This enables: - -** Launching a factory using a devfile URL. -** Importing and cloning a project. - -[NOTE] -==== -* Configure the OAuth 1 authentication on the BB server side. For more information, see xref:configuring-authorization#proc_configuring-bitbucket-server-oauth1_{context}[Configuring Bitbucket Server OAuth 1] -* Creating a ConfigMap for importing additional certificates is necessary only if a BB server is setup with self-signed TLS certificates. These certificates are needed for the proper functionality of {prod-short} server and tools inside of a workspace, which use them for performing Git operations related to a specific repository. -==== - - -.Prerequisites - -* A value of the BB server certification authority (CA) exported in the Base64 ASCII format and stored in a `ca.crt` file. -* An instance of {prod-short}. - -.Procedure - -. Provision the CA of the BB server to the {prod-short} server to enable it to read the devfiles stored in the BB server. To do so, add the following ConfigMap to the `{prod-namespace}` {orch-namespace}: -+ -[subs="+attributes,+quotes"] ----- -$ {orch-cli} create configmap bitbucket-ca-cert-for-factory --from-file=ca.crt -n {prod-namespace} ----- -+ -[subs="+attributes,+quotes"] ----- -$ {orch-cli} label configmap bitbucket-ca-cert-for-factory app.kubernetes.io/part-of=che.eclipse.org app.kubernetes.io/component=ca-bundle -n {prod-namespace} ----- - -. Provision the CA of the BB server to the {prod-short} server to be able to use Git operations. To do so, add a new ConfigMap to the `{prod-namespace}` {orch-namespace}: -+ -[subs="+attributes,+quotes"] ----- -$ {orch-cli} create configmap che-git-self-signed-cert --from-file=ca.crt --from-literal=githost=__<bitbucket_server_url>__ -n {prod-namespace} ----- - -. Edit the CheCluster Custom Resource (CR) to configure the {prod-short} server. -+ -[source,yaml,subs="+quotes"] ----- -spec: - server: - # … - gitSelfSignedCert: __<boolean>__ <1> ----- -<1> Use `true` for a BB server that use a self-signed cert. Default value: `false`. -+ -* For more information, see xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[]. - - -.Reference - -* For adding a Bitbucket CA certificate into {prod-short}, see xref:installation-guide:importing-untrusted-tls-certificates.adoc[]. diff --git a/modules/administration-guide/partials/proc_configuring-che-to-use-external-identity-provider.adoc b/modules/administration-guide/partials/proc_configuring-che-to-use-external-identity-provider.adoc deleted file mode 100644 index 0ad13fc902..0000000000 --- a/modules/administration-guide/partials/proc_configuring-che-to-use-external-identity-provider.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// configuring-authorization - -[id="configuring-che-to-use-external-{identity-provider-id}_{context}"] -= Configuring {prod-short} to use an external {identity-provider} installation - -By default, {prod-short} installation includes the deployment of a dedicated {identity-provider} instance. However, using an external {identity-provider} is also possible. This option is useful when a user has an existing {identity-provider} instance with already-defined users, for example, a company-wide {identity-provider} server used by several applications. - -.Placeholders used in examples -[cols="1,2"] -|=== -| `_<provider-realm-name>_` -| {identity-provider} realm name intended for use by {prod-short} - -| `_<oidc-client-name>_` -| Name of the `oidc` client defined in `_<provider-realm-name>_` - -| `_<auth-base-url>_` -| Base URL of the external {identity-provider} server -|=== - -.Prerequisites - -* In the administration console of the external installation of {identity-provider}, define a link:https://www.keycloak.org/docs/latest/server_admin/#_create-realm[realm] that contains the users to connect to {prod-short}: -+ -image::keycloak/external_keycloak_realm.png[External {identity-provider} realm,link="../_images/keycloak/external_keycloak_realm.png"] - -* In this `realm`, define an link:https://www.keycloak.org/docs/latest/server_admin/#oidc-clients[OIDC client] that {prod-short} will use to authenticate the users. This is an example of such a client with the correct settings: -+ -image::keycloak/external_keycloak_public_client.png[External {identity-provider} public client,link="../_images/keycloak/external_keycloak_public_client.png"] -+ -[NOTE] -==== -* *Client Protocol* must be `openid-connect`. -* *Access Type* must be `public`. {prod-short} only supports the `public` access type. -* *Valid Redirect URIs* must contain at least two URIs related to the {prod-short} server, one using the `http` protocol and the other `https`. These URIs must contain the base URL of the {prod-short} server, followed by `/*` wildcards. -* *Web Origins* must contain at least two URIs related to the {prod-short} server, one using the `http` protocol and the other `https`. These URIs must contain the base URL of the {prod-short} server, without any path after the host. -+ -The number of URIs depends on the number of installed product tools. -==== - -* With {prod-short} -ifeval::["{project-context}" == "che"] -installed on OpenShift -endif::[] -that uses the default OpenShift OAuth support, user authentication relies on the integration of {identity-provider} with OpenShift OAuth. This allows users to log in to {prod-short} with their OpenShift login and have their workspaces created under personal OpenShift projects. -+ -This requires setting up an OpenShift {platforms-identity-provider}. When using an external {identity-provider}, configure the {identity-provider} manually. For instructions, see the appropriate {identity-provider} documentations for either {link-identity-provider-documentation-openshift-3} or {link-identity-provider-documentation-openshift-4}. - -* The configured {identity-provider} has the options *Store Tokens* and *Stored Tokens Readable* enabled. - - -.Procedure - -. Set the following properties in the `CheCluster` Custom Resource (CR): -+ -[source, yaml, subs="+quotes,macros,attributes"] ----- -spec: - auth: - externalIdentityProvider: true - identityProviderURL: <auth-base-url> - identityProviderRealm: <provider-realm-name> - identityProviderClientId: <oidc-client-name> ----- - -. When installing {prod-short} -ifeval::["{project-context}" == "che"] -on OpenShift -endif::[] -with OpenShift OAuth support enabled, set the following properties in the `CheCluster` Custom Resource (CR): -+ -[source, yaml, subs="+quotes,macros,attributes"] ----- -spec: - auth: - openShiftoAuth: true -# Note: only if the OpenShift {platforms-identity-provider} alias is different from 'openshift-v3' or 'openshift-v4' -server: - customCheProperties: - CHE_INFRA_OPENSHIFT_OAUTH__IDENTITY__PROVIDER: <OpenShift {platforms-identity-provider} alias> ----- diff --git a/modules/administration-guide/partials/proc_configuring-che-to-work-with-external-PostgreSQL.adoc b/modules/administration-guide/partials/proc_configuring-che-to-work-with-external-PostgreSQL.adoc deleted file mode 100644 index 89a0f64209..0000000000 --- a/modules/administration-guide/partials/proc_configuring-che-to-work-with-external-PostgreSQL.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// deploying-the-registries - -[id="configuring-{prod-id-short}-to-work-with-external-PostgreSQL_{context}"] -= Configuring {prod-short} to work with an external PostgreSQL - -.Prerequisites - -* The `{orch-cli}` tool is available. - -.Procedure - -. Pre-create a {orch-namespace} for {prod-short}: -+ -[subs="+quotes,attributes"] ----- -$ {orch-cli} create namespace {prod-namespace} ----- - -. Create a secret to store {prod-short} server database credentials: -+ -[subs="+quotes,attributes"] ----- -$ {orch-cli} create secret generic __<server-database-credentials>__ \ <1> ---from-literal=user=__<database-user>__ \ <2> ---from-literal=password=__<database-password>__ \ <3> --n {prod-namespace} ----- -<1> Secret name to store {prod-short} server database credentials -<2> {prod-short} server database username -<3> {prod-short} server database password - -. Add the required labels to the {prod-short} server database credentials secret: -+ -[subs="+quotes,attributes"] ----- -$ {orch-cli} label secret __<server-database-credentials>__ \ <1> - app.kubernetes.io/part-of=che.eclipse.org -n {prod-namespace} ----- -<1> Secret name to store {prod-short} server database credentials - -. Create a secret to store {identity-provider} database credentials: -+ -[subs="+quotes,attributes"] ----- -$ {orch-cli} create secret generic __<identity-database-credentials>__ \ <1> ---from-literal=password=__<identity-database-password>__ \ <2> --n {prod-namespace} ----- -<1> Secret name to store {identity-provider} database credentials -<2> {identity-provider} database password - -. Add the required labels to the {identity-provider} database credentials secret: -+ -[subs="+quotes,attributes"] ----- -$ {orch-cli} label secret __<identity-database-credentials>__ \ <1> -app.kubernetes.io/part-of=che.eclipse.org -n {prod-namespace} ----- -<1> Secret name to store {identity-provider} database credentials - -. Deploy {prod} by executing the `{prod-cli}` command with applying a patch. For example: -+ -[subs="+quotes,+attributes"] ----- -$ {prod-cli} server:deploy --che-operator-cr-patch-yaml=patch.yaml ... ----- - -patch.yaml should contain the following to make the Operator skip deploying a database and pass connection details of an existing database to a {prod-short} server: - -[source,yaml,subs="+quotes"] ----- -spec: - database: - externalDb: true - chePostgresHostName: <hostname> <1> - chePostgresPort: <port> <2> - chePostgresSecret: <server-database-credentials> <3> - chePostgresDb: <database> <4> -spec: - auth: - identityProviderPostgresSecret: <identity-database-credentials> <5> ----- -<1> External database host name -<2> External database port -<3> Secret name with {prod-short} server database credentials -<4> {prod-short} server database name -<5> Secret name with {identity-provider} database credentials - diff --git a/modules/administration-guide/partials/proc_configuring-che-to-work-with-identity-provider.adoc b/modules/administration-guide/partials/proc_configuring-che-to-work-with-identity-provider.adoc deleted file mode 100644 index 92b6361c54..0000000000 --- a/modules/administration-guide/partials/proc_configuring-che-to-work-with-identity-provider.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// configuring-authorization - -[id="configuring-{prod-id-short}-to-work-with-{identity-provider-id}_{context}"] -= Configuring {prod-short} to work with {identity-provider} - -The deployment script configures {identity-provider}. It creates a `{prod-deployment}-public` client with the following fields: - -* *Valid Redirect URIs*: Use this URL to access {prod-short}. -* *Web Origins* - -The following are common errors when configuring {prod-short} to work with {identity-provider}: - -Invalid `redirectURI` error:: Occurs when you access {prod-short} at `myhost`, which is an alias, and your original `+CHE_HOST+` is `1.1.1.1`. If this error occurs, go to the {identity-provider} administration console and ensure that the valid redirect URIs are configured. - -CORS error:: Occurs when you have an invalid web origin. diff --git a/modules/administration-guide/partials/proc_configuring-chectl-to-use-backup-server.adoc b/modules/administration-guide/partials/proc_configuring-chectl-to-use-backup-server.adoc deleted file mode 100644 index 0a1670f2ff..0000000000 --- a/modules/administration-guide/partials/proc_configuring-chectl-to-use-backup-server.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="configuring-{prod-cli}-to-use-a-backup-server"] -= Configuring {prod-cli} to use a backup server - -The following section describes how to define environment variables for a specific backup server using the {prod-cli} tool. - -.Procedure - -. Determine xref:setup-backup-server.adoc[backup server type] and the server URL. Use the link:https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html[restic repository documentation] as the reference. -+ -The URL can be specified with the `-r` parameter or defined using the `BACKUP_REPOSITORY_URL` environment variable. - -. Retrieve or create a password for the backup repository. -+ -The password can be specified with the `-p` parameter or defined using the `BACKUP_REPOSITORY_PASSWORD` environment variable. -+ -[WARNING] -==== -Backup data are encrypted with this password. The loss of the backup repository password will cause losing the data. -==== - -. Set the following environment variables for the chosen xref:setup-backup-server.adoc[backup server type]: - -REST:: When optional authentication is turned on, export `REST_SERVER_USERNAME` and `REST_SERVER_PASSWORD` environment variables. - -AWS S3:: Export the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables with AWS user credentials. - -SFTP:: For login without a password, export the `SSH_KEY_FILE` environment variable that holds the path to a file with a corresponding SSH key, or provide the `--ssh-key-file` parameter. -+ -Alternatively, the `SSH_KEY` environment variable that holds an SSH key itself can be used. - -[NOTE] -==== -It is possible to point directly to the backup server configuration object using `--backup-server-config-name` parameter or `BACKUP_SERVER_CONFIG_NAME` environment variable. -In such a case, all the configuration above is not needed. For more details, see xref:managing-backups-using-custom-resources.adoc[] -==== diff --git a/modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc b/modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc deleted file mode 100644 index 0a1670f2ff..0000000000 --- a/modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="configuring-{prod-cli}-to-use-a-backup-server"] -= Configuring {prod-cli} to use a backup server - -The following section describes how to define environment variables for a specific backup server using the {prod-cli} tool. - -.Procedure - -. Determine xref:setup-backup-server.adoc[backup server type] and the server URL. Use the link:https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html[restic repository documentation] as the reference. -+ -The URL can be specified with the `-r` parameter or defined using the `BACKUP_REPOSITORY_URL` environment variable. - -. Retrieve or create a password for the backup repository. -+ -The password can be specified with the `-p` parameter or defined using the `BACKUP_REPOSITORY_PASSWORD` environment variable. -+ -[WARNING] -==== -Backup data are encrypted with this password. The loss of the backup repository password will cause losing the data. -==== - -. Set the following environment variables for the chosen xref:setup-backup-server.adoc[backup server type]: - -REST:: When optional authentication is turned on, export `REST_SERVER_USERNAME` and `REST_SERVER_PASSWORD` environment variables. - -AWS S3:: Export the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables with AWS user credentials. - -SFTP:: For login without a password, export the `SSH_KEY_FILE` environment variable that holds the path to a file with a corresponding SSH key, or provide the `--ssh-key-file` parameter. -+ -Alternatively, the `SSH_KEY` environment variable that holds an SSH key itself can be used. - -[NOTE] -==== -It is possible to point directly to the backup server configuration object using `--backup-server-config-name` parameter or `BACKUP_SERVER_CONFIG_NAME` environment variable. -In such a case, all the configuration above is not needed. For more details, see xref:managing-backups-using-custom-resources.adoc[] -==== diff --git a/modules/administration-guide/partials/proc_configuring-external-PostgreSQL.adoc b/modules/administration-guide/partials/proc_configuring-external-PostgreSQL.adoc deleted file mode 100644 index 2a30e0210f..0000000000 --- a/modules/administration-guide/partials/proc_configuring-external-PostgreSQL.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// deploying-the-registries - -[id="configuring-external-PostgreSQL_{context}"] -= Configuring external PostgreSQL - -By configuring the external PostgreSQL, you can make the workspace metadata and the user information persistent. - -.Procedure - -. Define the values of the following placeholders: -+ --- -* `<database-user>` is the {prod-short} server database user name -* `<database-password>` is the {prod-short} server database password -* `<database>` is the {prod-short} server database name --- - -. Use the following SQL script to create a user and a database for the {prod-short} server to make workspace metadata persistent: -+ -[subs="+quotes,+attributes"] ----- -CREATE USER <database-user> WITH PASSWORD '<database-password>' -CREATE DATABASE <database> -GRANT ALL PRIVILEGES ON DATABASE <database> TO <database-user> -ALTER USER <database-user> WITH SUPERUSER ----- - -. Define the value of the following placeholder: -+ --- -* `<identity-database-password>` is the {identity-provider} database password --- - -. Use the following SQL script to create a database for the {identity-provider} back end to make the user information persistent: -+ -[subs="+quotes,+attributes"] ----- -CREATE USER keycloak WITH PASSWORD '<identity-database-password>' -CREATE DATABASE keycloak -GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak ----- \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_configuring-github-oauth.adoc b/modules/administration-guide/partials/proc_configuring-github-oauth.adoc deleted file mode 100644 index 94c357aff0..0000000000 --- a/modules/administration-guide/partials/proc_configuring-github-oauth.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// Configuring GitHub OAuth - - -[id="configuring-github-oauth_{context}"] -= Configuring GitHub OAuth - -OAuth for GitHub allows for automatic SSH key upload to GitHub. - -.Prerequisites - -* The `{orch-cli}` tool is available. - -.Procedure - -* Create a link:https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app[OAuth application in GitHub] using {prod-short} URL as the value for the application `Homepage URL` and {identity-provider} GitHub endpoint URL as the value for Authorization callback URL. The default values are `++https://++{prod-deployment}-{prod-namespace}.__<DOMAIN>__/` and `++https://++keycloak-{prod-namespace}.__<DOMAIN>__/auth/realms/{prod-deployment}/broker/github/endpoint` respectively, where `__<DOMAIN>__` is {orch-name} cluster domain. - -. Create a new secret in the {orch-namespace} where {prod-short} is deployed. -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} apply -f - <<EOF -kind: Secret -apiVersion: v1 -metadata: - name: github-oauth-config - namespace: <...> <1> - 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 -data: - id: <...> <2> - secret: <...> <3> -EOF ----- -<1> {prod-short} namespace. The default is {prod-namespace} -<2> base64 encoded GitHub OAuth Client ID -<3> base64 encoded GitHub OAuth Client Secret - -. If {prod-short} was already installed wait until rollout of {identity-provider} component finishes. - diff --git a/modules/administration-guide/partials/proc_configuring-gitlab-oauth2.adoc b/modules/administration-guide/partials/proc_configuring-gitlab-oauth2.adoc deleted file mode 100644 index d1b50d0308..0000000000 --- a/modules/administration-guide/partials/proc_configuring-gitlab-oauth2.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// Configuring GitLab OAuth2 - - -[id="configuring-gitlab-oauth2_{context}"] -= Configuring GitLab OAuth2 - -OAuth2 for GitLab allows accepting factories from private GitLab repositories. - -.Prerequisites - -* GitLab server is running and available from {prod-short} - -.Procedure - -* Create a link:https://docs.gitlab.com/ee/integration/oauth_provider.html#authorized-applications[Authorized OAuth2 application in GitLab] using {prod-short} as the application `Name` and {identity-provider} GitLab endpoint URL as the value for `Redirect URI`. The callback URL default value is `++https://++keycloak-{prod-namespace}.__<DOMAIN>__/auth/realms/{prod-deployment}/broker/gitlab/endpoint`, where `__<DOMAIN>__` is {orch-name} cluster domain. Store the `Application ID` and `Secret` values. - All three types of GitLab OAuth 2 applications are supported: User owned, Group owned and Instance-wide. - -. Create a custom OIDC provider link on {identity-provider} pointing to GitLab server. Fill the following fields: -+ -==== -Client ID:: a value from the `Application ID` field provided by GitLab server in previous step; -Client Secret:: a value from `Secret` field provided by GitLab server in previous step; -Authorization URL:: a URL which have a `https://__<GITLAB_DOMAIN>__/oauth/authorize` format; -Token URL:: a URL which have a `https://__<GITLAB_DOMAIN>__/oauth/token` format; -Scopes:: set of scopes which must contain (but not limited to) the following set: `api write_repository openid`; -Store Tokens:: needs to be enabled; -Store Tokens Readable:: needs to be enabled -==== -+ -[NOTE] -==== -* Substitute `_<GITLAB_DOMAIN>_` with the URL and port of the GitLab installation. -==== - -. Register the GitLab instance URL with the enabled OAuth 2 support in {prod-short} using the `+CHE_INTEGRATION_GITLAB_OAUTH__ENDPOINT+` property. -+ -[WARNING] -==== -* The GitLab instance URL must be present in the list of configured GitLab integration endpoints, set by the `+CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS+` property. -==== - -.Additional resources -In case of having issues {prod-short} accessing GitLab related to TLS keys, consult with the following docs: - -* xref:installation-guide:importing-untrusted-tls-certificates.adoc[]. -* xref:installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]. diff --git a/modules/administration-guide/partials/proc_configuring-gitlab-servers.adoc b/modules/administration-guide/partials/proc_configuring-gitlab-servers.adoc deleted file mode 100644 index 0a79db05aa..0000000000 --- a/modules/administration-guide/partials/proc_configuring-gitlab-servers.adoc +++ /dev/null @@ -1,16 +0,0 @@ - -[id="configuring_gitlab_servers_{context}"] -= Configuring GitLab servers - -To use a GitLab server as a project sources supplier, register the GitLab server URL with {prod-short} using the `CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS` property and specify the host name of the server to register. - -.Example ----- -https://gitlab.apps.cluster-2ab2.2ab2.example.opentlc.com/ ----- - -For additional examples of configuring GitLab servers see xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc#understanding-{prod-id-short}-server-advanced-configuration-using-the-operator_{context}[Understanding {prod-short} server advanced configuration using the Operator] - -.Additional resources - -* xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[] diff --git a/modules/administration-guide/partials/proc_configuring-identity-provider-tokens.adoc b/modules/administration-guide/partials/proc_configuring-identity-provider-tokens.adoc deleted file mode 100644 index dd4c62eca7..0000000000 --- a/modules/administration-guide/partials/proc_configuring-identity-provider-tokens.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// configuring-authorization - -[id="configuring-{identity-provider-id}-tokens_{context}"] -= Configuring {identity-provider} tokens - -A user token expires after 30 minutes by default. - -You can change the following {identity-provider} token settings: - -image::keycloak/keycloak_realm.png[link="../_images/keycloak/keycloak_realm.png"] diff --git a/modules/administration-guide/partials/proc_configuring-openshift-oauth-with-initial-user.adoc b/modules/administration-guide/partials/proc_configuring-openshift-oauth-with-initial-user.adoc deleted file mode 100644 index bc187dad84..0000000000 --- a/modules/administration-guide/partials/proc_configuring-openshift-oauth-with-initial-user.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="configuring-openshift-oauth-with-initial-user_{context}"] -= Configuring OpenShift OAuth with initial user - -.Prerequisites - -* The `oc` tool is available. -* `{prod-cli}` management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. - -.Procedure - -* Configure OpenShift identity providers on the cluster. See the link:https://docs.openshift.com/container-platform/latest/authentication/understanding-identity-provider.html#identity-provider-overview_understanding-identity-provider[Understanding identity provider configuration]. -+ -==== -When a user skips the Configuring step of OpenShift {platforms-identity-provider}, and the OpenShift cluster does not already contain a configured {identity-provider}, {prod-short} creates an initial OpenShift user for the `HTPasswd` identity provider. Credentials of this user are stored in the `openshift-oauth-user-credentials` secret, located in the `openshift-config` namespace. - -Obtain the credentials for logging in to an OpenShift cluster and {prod-short} instance: - -. Obtain OpenShift user name: -+ -[subs="+attributes,+quotes"] ----- -$ oc get secret openshift-oauth-user-credentials -n openshift-config -o json | jq -r '.data.user' | base64 -d ----- -. Obtain OpenShift user password: -+ -[subs="+attributes,+quotes"] ----- -$ oc get secret openshift-oauth-user-credentials -n openshift-config -o json | jq -r '.data.password' | base64 -d ----- -==== -+ -* Deploy {prod-short} using xref:installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc[OperatorHub] or the {prod-cli}, see the -link:{link-cli-github}#user-content-{prod-cli}-serverdeploy[`{prod-cli} server:deploy` specification] chapter. OpenShift OAuth will be enabled by default. - diff --git a/modules/administration-guide/partials/proc_configuring-openshift-oauth-without-initial-user.adoc b/modules/administration-guide/partials/proc_configuring-openshift-oauth-without-initial-user.adoc deleted file mode 100644 index 48c701191a..0000000000 --- a/modules/administration-guide/partials/proc_configuring-openshift-oauth-without-initial-user.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="proc_configuring_openshift-oauth-without-initial-user_{context}"] -= Configuring OpenShift OAuth without provisioning OpenShift initial OAuth user - -The following procedure describes how to configure OpenShift OAuth without provisioning the initial OAuth user. - -.Prerequisites - -* `{prod-cli}` management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. - -.Procedure - -. If you have installed {prod-short} by using the Operator, configure the following values in the {prod-checluster} Custom Resource: -+ -[source,yaml,subs="+quotes"] ----- -spec: - auth: - openShiftoAuth: true - initialOpenShiftOAuthUser: '' ----- -+ -. If you have installed {prod-short} by using the `{prod-cli}` tool, use the `--che-operator-cr-patch-yaml` flag: -+ -[subs="+quotes,+attributes"] ----- -$ {prod-cli} server:deploy --che-operator-cr-patch-yaml=patch.yaml ... ----- -+ -The `patch.yaml` file must contain the following: -+ -[source,yaml,subs="+quotes"] ----- -spec: - auth: - openShiftoAuth: true - initialOpenShiftOAuthUser: '' ----- diff --git a/modules/administration-guide/partials/proc_configuring-openshift-oauth.adoc b/modules/administration-guide/partials/proc_configuring-openshift-oauth.adoc deleted file mode 100644 index 076a9f5b35..0000000000 --- a/modules/administration-guide/partials/proc_configuring-openshift-oauth.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// Configuring OpenShift OAuth - -:parent-context-of-configuring-openshift-oauth: {context} - -[id="configuring-openshift-oauth_{context}"] -= Configuring OpenShift OAuth - -:context: configuring-openshift-oauth - -For users to interact with OpenShift, they must first authenticate to the OpenShift cluster. OpenShift OAuth is a process in which users prove themselves to a cluster through an API with obtained OAuth access tokens. - -Authentication with the xref:extensions:openshift-connector-overview.adoc[] is a possible way for {prod-short} users to authenticate with an OpenShift cluster. - -The following section describes the OpenShift OAuth configuration options and its use with a {prod-short}. - -include::partial$proc_configuring-openshift-oauth-with-initial-user.adoc[leveloffset=+1] - -include::partial$proc_configuring-openshift-oauth-without-initial-user.adoc[leveloffset=+1] - -include::partial$proc_removing-initial-openshift-user.adoc[leveloffset=+1] - -:context: {parent-context-of-configuring-openshift-oauth} \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_configuring-smtp-and-email-notifications.adoc b/modules/administration-guide/partials/proc_configuring-smtp-and-email-notifications.adoc deleted file mode 100644 index a49e325a82..0000000000 --- a/modules/administration-guide/partials/proc_configuring-smtp-and-email-notifications.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// configuring-authorization - -[id="configuring-smtp-and-email-notifications_{context}"] -= Configuring SMTP and email notifications - -{prod} does not provide any pre-configured MTP servers. - -To enable SMTP servers in {identity-provider}: - -. Go to `che realm settings > Email`. - -. Specify the host, port, username, and password. - -{prod} uses the default theme for email templates for registration, email confirmation, password recovery, and failed login. diff --git a/modules/installation-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc b/modules/administration-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc similarity index 68% rename from modules/installation-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc rename to modules/administration-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc index b8ccd8d5c6..929b6ea844 100644 --- a/modules/installation-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc +++ b/modules/administration-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc @@ -5,21 +5,23 @@ [id="creating-an-instance-of-the-{prod-id-short}-operator_{context}"] = Creating an instance of the {prod} Operator -Follow this procedure to install {prod} with the default configuration. To modify the configuration, see xref:configuring-the-che-installation.adoc[]. +Follow this procedure to install {prod} with the default configuration. To modify the configuration, see xref:understanding-the-checluster-custom-resource.adoc[]. .Procedure -. Using the left panel, navigate to the *Operators* -> *Installed Operators* page. +// Steps from this procedure are included in administration-guide:proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc[]. -. In the *Installed Operators* page, click the *{prod}* name. +. In the left panel, click *Operators*, then click *Installed Operators*. -. In the *Operator details* page, in the *Details* tab, click the *Create instance* link in the *Provided APIs* section. +. On the *Installed Operators* page, click the *{prod}* name. + +. On the *Operator details* page, in the *Details* tab, click the *Create instance* link in the *Provided APIs* section. + This navigates you to the *Create CheCluster* page, which contains the configuration needed to create a {prod-short} instance, stored in the `CheCluster` Custom Resource. -. Create the *{prod-checluster}* cluster using the btn:[Create] button at the end of the page using the default values. +. Create the *{prod-checluster}* cluster by using the btn:[Create] button at the end of the page using the default values. -. In the *Operator details* page, in the *{prod} Cluster* tab, click the *{prod-checluster}* link. +. On the *Operator details* page, in the *{prod} Cluster* tab, click the *{prod-checluster}* link. . Navigate to the *{prod-checluster}* instance using the link displayed under the *{prod} URL* output. + diff --git a/modules/administration-guide/partials/proc_creating-secure-servers.adoc b/modules/administration-guide/partials/proc_creating-secure-servers.adoc deleted file mode 100644 index af2f099dc7..0000000000 --- a/modules/administration-guide/partials/proc_creating-secure-servers.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// authenticating-in-a-{prod-id-short}-workspace - -[id="creating-secure-servers_{context}"] -= Creating secure servers - -To create secure servers in {prod-short} workspaces, set the `secure` attribute of the endpoint to `true` in the `dockerimage` type component in the devfile. - -.Devfile snippet for a secure server -[source,yaml] ----- -components: - - type: dockerimage - endpoints: - - attributes: - secure: 'true' ----- diff --git a/modules/contributor-guide/partials/proc_defining-custom-branding-values-for-che-theia.adoc b/modules/administration-guide/partials/proc_defining-custom-branding-values-for-che-theia.adoc similarity index 100% rename from modules/contributor-guide/partials/proc_defining-custom-branding-values-for-che-theia.adoc rename to modules/administration-guide/partials/proc_defining-custom-branding-values-for-che-theia.adoc diff --git a/modules/administration-guide/partials/proc_defining-the-list-of-images-to-pull.adoc b/modules/administration-guide/partials/proc_defining-the-list-of-images-to-pull.adoc deleted file mode 100644 index f5cfdefec9..0000000000 --- a/modules/administration-guide/partials/proc_defining-the-list-of-images-to-pull.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="defining-the-list-of-images-to-pull_{context}"] -= Defining the list of images to pull - -The {image-puller-name-short} can pre-pull most images, including scratch images such as `che-machine-exec`. However, images that mount volumes in the Dockerfile, such as `traefik`, are not supported for pre-pulling on OpenShift 3.11. - -Pre-pulling images involved in workspace startup will reduce workspace start times. For example: - -* Che-Theia -* broker images -* plug-in sidecar images - -.Prerequisites - -* The `curl` tool is available. See link:https://curl.se/[curl homepage]. -* The `jq` tool is available. See link:https://stedolan.github.io/jq/[jq homepage]. -* The `yq` tool is available. See link:https://pypi.org/project/yq/[yq homepage]. - -.Procedure - -. Gather a list of relevant container images for the {platforms-name} platform: -+ -include::example$snip_{project-context}-getting-the-list-of-relevant-images.adoc[] - - -. Determine images from the list for pre-pulling. -+ -For faster workspace startup times, consider pre-pulling the workspace-related images: -+ -include::example$snip_{project-context}-list-of-images-for-faster-workspace-start.adoc[] - -.Additional resources - -pass:[<!-- vale CheDocs.Attributes = NO -->] - -* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. -ifeval::["{project-context}" == "che"] -* xref:installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc[] -endif::[] -* xref:installing-image-puller-on-openshift-using-operatorhub.adoc[] -* xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[] - -pass:[<!-- vale CheDocs.Attributes = YES -->] diff --git a/modules/administration-guide/partials/proc_defining-the-memory-parameters-for-the-image-puller.adoc b/modules/administration-guide/partials/proc_defining-the-memory-parameters-for-the-image-puller.adoc deleted file mode 100644 index 313d4adb7a..0000000000 --- a/modules/administration-guide/partials/proc_defining-the-memory-parameters-for-the-image-puller.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="proc_defining-the-memory-parameters-for-the-image-puller_{context}"] -= Defining the memory parameters for the {image-puller-name-short} - -[role="_abstract"] -Define the memory requests and limits parameters to ensure pulled containers and the platform have enough memory to run. - -.Prerequisites - -* xref:defining-the-list-of-images-to-pull.adoc[] - -.Procedure - -. To define the minimal value for `CACHING_MEMORY_REQUEST` or `CACHING_MEMORY_LIMIT`, consider the necessary amount of memory required to run each of the container images to pull. - -. To define the maximal value for `CACHING_MEMORY_REQUEST` or `CACHING_MEMORY_LIMIT`, consider the total memory allocated to the DaemonSet Pods in the cluster: -+ ----- -(memory limit) * (number of images) * (number of nodes in the cluster) ----- -+ -==== -Pulling 5 images on 20 nodes, with a container memory limit of `20Mi` requires `2000Mi` of memory. -==== - -.Additional resources - -ifeval::["{project-context}" == "che"] -* xref:installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc[] -endif::[] -* xref:installing-image-puller-on-openshift-using-operatorhub.adoc[] -* xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[] diff --git a/modules/administration-guide/partials/proc_deploying-registries-in-openshift.adoc b/modules/administration-guide/partials/proc_deploying-registries-in-openshift.adoc deleted file mode 100644 index a5818d153b..0000000000 --- a/modules/administration-guide/partials/proc_deploying-registries-in-openshift.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// deploying-the-registries - -[id="deploying-registries-in-openshift_{context}"] -= Deploying registries in OpenShift - -.Procedure - -An OpenShift template to deploy the plug-in registry is available in the `deploy/openshift/` directory of the GitHub repository. - -. To deploy the plug-in registry using the OpenShift template, run the following command: -+ -[subs="+quotes"] ----- -NAMESPACE=__<namespace-name>__ <1> -IMAGE_NAME="my-plug-in-registry" -IMAGE_TAG="latest" -oc new-app -f openshift/che-plugin-registry.yml \ - -n "$\{NAMESPACE}" \ - -p IMAGE="$\{IMAGE_NAME}" \ - -p IMAGE_TAG="$\{IMAGE_TAG}" \ - -p PULL_POLICY="Always" ----- -<1> If installed using {prod-cli}, the default {prod-short} {orch-namespace} is `{prod-namespace}`. The OperatorHub installation method deploys {prod-short} to the users current {orch-namespace}. - -. The devfile registry has an OpenShift template in the `deploy/openshift/` directory of the GitHub repository. To deploy it, run the command: -+ -[subs="+quotes"] ----- -NAMESPACE=__<namespace-name>__ <1> -IMAGE_NAME="my-devfile-registry" -IMAGE_TAG="latest" -oc new-app -f openshift/che-devfile-registry.yml \ - -n "$\{NAMESPACE}" \ - -p IMAGE="$\{IMAGE_NAME}" \ - -p IMAGE_TAG="$\{IMAGE_TAG}" \ - -p PULL_POLICY="Always" ----- -<1> If installed using {prod-cli}, the default {prod-short} {orch-namespace} is `{prod-namespace}`. The OperatorHub installation method deploys {prod-short} to the users current {orch-namespace}. - -:platform-routing: route -:platform-routing-host-path: .spec.host - -include::partial$proc_verification-custom-registries.adoc[] diff --git a/modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-olm-installer.adoc b/modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-olm-installer.adoc deleted file mode 100644 index e7ce32bcdf..0000000000 --- a/modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-olm-installer.adoc +++ /dev/null @@ -1,42 +0,0 @@ -:_module-type: PROCEDURE - -[id="disabling-readiness-init-containers-for-the-olm-installer_{context}"] -= Disabling the readiness init containers for the OLM installer - -To disable the previously enabled readiness init containers for the {prod-short} installed by the OLM installer: - -.Prerequisites - -* {prod-short} is installed by the OLM installer. - -.Procedure - -. Find the {prod-short} Operator subscription name: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} get subscriptions -n {prod-namespace} ----- - -. Get the CSV (Cluster Service Version) name from the {prod-short} Operator subscription: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} get subscription <subscription-name> -n {prod-namespace} -o yaml | grep installedCSV ----- - -. Edit the `ClusterServiceVersion` YAML manifest: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} edit csv _<csv-name>_ -n {prod-namespace} ----- -. Remove the following environment variable from the Operator Deployment spec: -+ -[source,yaml,subs="+quotes,+attributes"] ----- - - name: ADD_COMPONENT_READINESS_INIT_CONTAINERS - value: "true" ----- - -. Wait for the {prod-short} Operator restart to finish. The restarted Operator will then continue with restarting some of its components. diff --git a/modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-operator-installer.adoc b/modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-operator-installer.adoc deleted file mode 100644 index 7dd93a5393..0000000000 --- a/modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-operator-installer.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="disabling-readiness-init-containers-for-the-operator-installer_{context}"] -= Disabling the readiness init containers for the Operator installer - -To disable the previously enabled readiness init containers for the {prod-short} installed by the Operator installer: - -.Prerequisites - -* {prod} installed by the Operator installer. - -.Procedure - -. Find the name of the {prod-short} Operator Deployment. Usually it is `{prod-id-short}-operator`: -+ -[source,yaml,subs="+quotes,+attributes"] ----- -$ {orch-cli} get deployments -n {prod-namespace} ----- - -. Edit the Deployment as follows: Under `spec.template.spec.containers[0].env` of the Operator Deployment, remove the following lines: -+ -[source,yaml,subs="+quotes,+attributes"] ----- - - name: ADD_COMPONENT_READINESS_INIT_CONTAINERS <1> - value: "true" ----- -<1> `ADD_COMPONENT_READINESS_INIT_CONTAINERS` is an environment variable. - -. Wait while {prod-short} Operator restarts some components. diff --git a/modules/administration-guide/partials/proc_enabling-and-exposing-che-metrics.adoc b/modules/administration-guide/partials/proc_enabling-and-exposing-che-metrics.adoc index 74bacfb9fb..9901eadf54 100644 --- a/modules/administration-guide/partials/proc_enabling-and-exposing-che-metrics.adoc +++ b/modules/administration-guide/partials/proc_enabling-and-exposing-che-metrics.adoc @@ -7,11 +7,11 @@ This section describes how to enable and expose {prod-short} metrics. .Procedure -. Set the `CHE_METRICS_ENABLED=true` environment variable, which will expose the `8087` port as a service on the che-master host. +. Set the `CHE_METRICS_ENABLED=true` environment variable, which will expose the `8087` port as a service on the `che-master` host. When {prod} is installed from the OperatorHub, the environment variable is set automatically if the default `CheCluster` CR is used: -image::monitoring/monitoring-che-che-cluster-cr.png[link="../_images/monitoring/monitoring-che-che-cluster-cr.png"] +image::monitoring/monitoring-che-che-cluster-cr.png[link="{imagesdir}/monitoring/monitoring-che-che-cluster-cr.png"] [source,yaml] ---- diff --git a/modules/administration-guide/partials/proc_enabling-authentication-with-social-accounts-and-brokering.adoc b/modules/administration-guide/partials/proc_enabling-authentication-with-social-accounts-and-brokering.adoc deleted file mode 100644 index c4f9ab3652..0000000000 --- a/modules/administration-guide/partials/proc_enabling-authentication-with-social-accounts-and-brokering.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// configuring-authorization - -[id="enabling-authentication-with-social-accounts-and-brokering_{context}"] -= Enabling authentication with social accounts and brokering - -{identity-provider} provides built-in support for GitHub, OpenShift, and most common social networks such as Facebook and Twitter. -See {identity-provider} documentation to learn how to link:{link-identity-provider-github}[enable Login with GitHub]. - - -// TODO: To use {prod-short}'s OAuth Authenticator, set `che.oauth.service_mode` to `embedded` and use xref:end-user-guide:version-control.adoc[]. diff --git a/modules/administration-guide/partials/proc_enabling-metrics-collection.adoc b/modules/administration-guide/partials/proc_enabling-metrics-collection.adoc deleted file mode 100644 index d790872b68..0000000000 --- a/modules/administration-guide/partials/proc_enabling-metrics-collection.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// tracing-{prod-id-short} - -[id="enabling-metrics-collection_{context}"] -= Enabling metrics collection - -.Prerequisites - -* Installed Jaeger v1.12.0 or above. See instructions at xref:tracing-che.adoc#installing-the-jaeger-tracing-tool_{context}[] - -.Procedure - -For Jaeger tracing to work, enable the following environment variables in your {prod-short} deployment: - -[source,bash,subs="+quotes,+attributes"] ----- -# Activating {prod-short} tracing modules -CHE_TRACING_ENABLED=true - -# Following variables are the basic Jaeger client library configuration. -JAEGER_ENDPOINT="http://jaeger-collector:14268/api/traces" - -# Service name -JAEGER_SERVICE_NAME="che-server" - -# URL to remote sampler -JAEGER_SAMPLER_MANAGER_HOST_PORT="jaeger:5778" - -# Type and param of sampler (constant sampler for all traces) -JAEGER_SAMPLER_TYPE="const" -JAEGER_SAMPLER_PARAM="1" - -# Maximum queue size of reporter -JAEGER_REPORTER_MAX_QUEUE_SIZE="10000" ----- - -To enable the following environment variables: - -. In the `yaml` source code of the {prod-short} deployment, add the following configuration variables under `spec.server.customCheProperties`. -+ -[source,yaml] ----- -customCheProperties: - CHE_TRACING_ENABLED: 'true' - JAEGER_SAMPLER_TYPE: const - DEFAULT_JAEGER_REPORTER_MAX_QUEUE_SIZE: '10000' - JAEGER_SERVICE_NAME: che-server - JAEGER_ENDPOINT: 'http://jaeger-collector:14268/api/traces' - JAEGER_SAMPLER_MANAGER_HOST_PORT: 'jaeger:5778' - JAEGER_SAMPLER_PARAM: '1' ----- - -. Edit the `JAEGER_ENDPOINT` value to match the name of the Jaeger collector service in your deployment. -+ -From the left menu of the main {ocp} screen, obtain the value of JAEGER_ENDPOINT by navigation to *Networking -> Services*. Alternatively, execute the following `oc` command: -+ ----- -$ oc get services ----- -+ -The requested value is included in the service name that contains the `collector` string. - - - -.Additional resources -* For additional information about custom environment properties and how to define them in CheCluster Custom Resource, see xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[]. -* For custom configuration of Jaeger, see the list of link:https://github.com/jaegertracing/jaeger-client-go#user-content-environment-variables[Jaeger client environment variables]. diff --git a/modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-olm-installer.adoc b/modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-olm-installer.adoc deleted file mode 100644 index 6badd9eee1..0000000000 --- a/modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-olm-installer.adoc +++ /dev/null @@ -1,44 +0,0 @@ -:_module-type: PROCEDURE - -[id="enabling-readiness-init-containers-for-the-olm-installer_{context}"] -= Enabling the readiness init containers for the OLM installer - -The readiness init containers are not enabled by default, so to use them you first have to enable them. To enable the readiness init containers for the {prod-short} installed by the OLM installer: - -.Prerequisites - -* {prod-short} is installed by the OLM installer. - -.Procedure - -. Find the {prod-short} Operator subscription name: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} get subscriptions -n {prod-namespace} ----- - -. Get the CSV (Cluster Service Version) name from the {prod-short} Operator subscription: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} get subscription <subscription-name> -n {prod-namespace} -o yaml | grep installedCSV ----- - -. Edit the `ClusterServiceVersion` YAML manifest: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} edit csv _<csv-name>_ -n {prod-namespace} ----- -. Add the following environment variable to the Operator Deployment spec: -+ -[source,yaml,subs="+quotes,+attributes"] ----- - - name: ADD_COMPONENT_READINESS_INIT_CONTAINERS - value: "true" ----- - -. Wait for the {prod-short} Operator restart to finish. The restarted Operator will then continue with restarting some of its components. - -NOTE: Repeat these steps after each {prod-short} upgrade when a new CSV is created by OLM. diff --git a/modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-operator-installer.adoc b/modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-operator-installer.adoc deleted file mode 100644 index 59ea5c8df6..0000000000 --- a/modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-operator-installer.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="enabling-readiness-init-containers-for-the-operator-installer_{context}"] -= Enabling the readiness init containers for the Operator installer - -The readiness init containers are not enabled by default, so to use them you first have to enable them. To enable the readiness init containers for the {prod-short} installed by the Operator installer: - -.Prerequisites - -* {prod} installed by the Operator installer. - -.Procedure - -. Find the name of the {prod-short} Operator Deployment. Usually it is `{prod-id-short}-operator`: -+ -[source,yaml,subs="+quotes,+attributes"] ----- -$ {orch-cli} get deployments -n {prod-namespace} ----- - -. Edit the Deployment as follows: Under `spec.template.spec.containers[0].env` of the Operator Deployment, insert the following lines: -+ -[source,yaml,subs="+quotes,+attributes"] ----- - - name: ADD_COMPONENT_READINESS_INIT_CONTAINERS <1> - value: "true" ----- -<1> `ADD_COMPONENT_READINESS_INIT_CONTAINERS` is an environment variable. - -. Wait while {prod-short} Operator restarts some components. - -NOTE: Repeat these steps after each {prod-short} upgrade when a new Operator Deployment is created. diff --git a/modules/administration-guide/partials/proc_enabling-self-registration.adoc b/modules/administration-guide/partials/proc_enabling-self-registration.adoc deleted file mode 100644 index 39e913bca3..0000000000 --- a/modules/administration-guide/partials/proc_enabling-self-registration.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// configuring-authorization - -[id="enabling-self-registration_{context}"] -= Enabling self-registration - -Self-registration allows users to register themselves in a {prod-short} instance by accessing the {prod-short} server URL. - -For {prod-short} installed without OpenShift OAuth support, self-registration is disabled by default, therefore the option to register a new user is not available on the login page. - -.Prerequisites - -* You are logged in as an administrator. - -.Procedure - -To enable self-registration of users: - -. Navigate to the *Realm Settings* menu on the left and open the *Login* tab. - -. Set *User registration* option to *On*. diff --git a/modules/installation-guide/partials/proc_installing-che-on-minikube-using-chectl.adoc b/modules/administration-guide/partials/proc_installing-che-on-minikube-using-chectl.adoc similarity index 100% rename from modules/installation-guide/partials/proc_installing-che-on-minikube-using-chectl.adoc rename to modules/administration-guide/partials/proc_installing-che-on-minikube-using-chectl.adoc diff --git a/modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc b/modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc deleted file mode 100644 index 182b5ae645..0000000000 --- a/modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc +++ /dev/null @@ -1,51 +0,0 @@ -ifeval::["{project-context}" == "che"] - -[id="installing-image-puller-on-kubernetes-using-the-operator_{context}"] -= Installing {image-puller-name-short} on {kubernetes} using the {image-puller-operator-name} - -This procedure describes how to install the {image-puller-name-short} on {kubernetes} using the Operator. This is the recommended installation method. - -.Prerequisites - -* xref:defining-the-list-of-images-to-pull.adoc[] -* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. - -.Procedure - -. Create a __<{image-puller-deployment-name}>__ {orch-namespace} to host the {image-puller-name-short}: -+ -[source,shell,subs="+quotes,+attributes"] ----- -kubectl create namespace __<{image-puller-deployment-name}>__ ----- - -. Apply the {image-puller-name-short} manifests on the namespace: -+ -[source,shell,subs="+quotes,+attributes"] ----- -export NAMESPACE=__<{image-puller-deployment-name}>__ -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/{image-puller-operator-repository-name}/master/deploy/crds/che.eclipse.org_kubernetesimagepullers_crd.yaml -n $NAMESPACE -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/{image-puller-operator-repository-name}/master/deploy/role.yaml -n $NAMESPACE -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/{image-puller-operator-repository-name}/master/deploy/role_binding.yaml -n $NAMESPACE -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/{image-puller-operator-repository-name}/master/deploy/service_account.yaml -n $NAMESPACE -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/{image-puller-operator-repository-name}/master/deploy/operator.yaml -n $NAMESPACE ----- - -. Create a `{image-puller-cr-name}` Custom Resource: -+ -[source,yaml,subs="+quotes,+attributes"] ----- -apiVersion: che.eclipse.org/v1alpha1 -kind: {image-puller-cr-name} -metadata: - name: {image-puller-deployment-name} - namespace: {image-puller-deployment-name} -spec: - configMapName: {image-puller-deployment-name} - daemonsetName: {image-puller-deployment-name} - deploymentName: {image-puller-deployment-name} - images: {image-puller-images} ----- - -endif::[] - diff --git a/modules/administration-guide/partials/proc_installing-image-puller-on-openshift-using-operatorhub.adoc b/modules/administration-guide/partials/proc_installing-image-puller-on-openshift-using-operatorhub.adoc deleted file mode 100644 index a2a8daee52..0000000000 --- a/modules/administration-guide/partials/proc_installing-image-puller-on-openshift-using-operatorhub.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="installing-image-puller-on-openshift-4-using-operatorhub_{context}"] -= Installing {image-puller-name-short} on OpenShift 4 using OperatorHub - -This procedure describes how to install the {image-puller-operator-name} on OpenShift 4 using the Operator. - - -.Prerequisites - -* An administrator account on a running instance of OpenShift 4. -* xref:defining-the-list-of-images-to-pull.adoc[] -* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. - -.Procedure - -. To create an OpenShift project __<{image-puller-deployment-name}>__ to host the {image-puller-name-short}, open the OpenShift web console, navigate to the *Home* -> *Projects* section and click btn:[Create Project]. - -. Specify the project details: -+ -* *Name*: __<{image-puller-deployment-name}>__ -* *Display Name*: __<{image-puller-name-short}>__ -* *Description*: __<{image-puller-name}>__ - - -. Navigate to btn:[*Operators*] → btn:[*OperatorHub*]. - -. Use the btn:[*Filter by keyword*] box to search for `{image-puller-operator-name}`. Click the btn:[{image-puller-operator-name}]. - -. Read the description of the Operator. Click btn:[*Continue*] → btn:[*Install*]. - -. Select btn:[*A specific {orch-namespace} on the cluster*] for the btn:[*Installation Mode*]. In the drop-down find the OpenShift project __<{image-puller-deployment-name}>__. Click btn:[*Subscribe*]. - -. Wait for the {image-puller-operator-name} to install. Click the btn:[*{image-puller-cr-name}*] → btn:[*Create instance*]. - -. In a redirected window with a YAML editor, make modifications to the `{image-puller-cr-name}` Custom Resource and click btn:[*Create*]. - -. Navigate to the btn:[*Workloads*] and btn:[*Pods*] menu in the __<{image-puller-deployment-name}>__ OpenShift project. Verify that the {image-puller-name-short} is available. - diff --git a/modules/administration-guide/partials/proc_installing-image-puller-using-che-operator.adoc b/modules/administration-guide/partials/proc_installing-image-puller-using-che-operator.adoc deleted file mode 100644 index 410f4d45ae..0000000000 --- a/modules/administration-guide/partials/proc_installing-image-puller-using-che-operator.adoc +++ /dev/null @@ -1,95 +0,0 @@ -[id="installing-image-puller-using-che-operator_{context}"] -= Installing {image-puller-name-short} using the {prod-short} Operator - -This section describes how to use the {prod-short} Operator to install the {image-puller-name-short}, which is a community-supported feature in the technology preview state. - -.Prerequisites - -* xref:defining-the-list-of-images-to-pull.adoc[] - -* xref:defining-the-memory-parameters-for-the-image-puller.adoc[] - -include::example$snip_{project-context}-installing-image-puller-using-che-operator-prerequisites.adoc[] - -* The {prod-short} Operator is available. See xref:installation-guide:installing-che-on-openshift-4-using-operatorhub.adoc[] - -.Procedure - -. Enable {image-puller-name-short} in the `CheCluster` Custom Resource by setting `.spec.imagePuller.enable` to `true`: -+ -==== -[source,yaml,subs="+attributes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheCluster -metadata: - name: {prod-checluster} -spec: - # ... - imagePuller: - enable: true ----- -==== -+ -. Configure {image-puller-name-short} in the `CheCluster` Custom Resource: -+ -==== -[source,yaml,subs="+quotes,+attributes,+macros"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheCluster -metadata: - name: {prod-checluster} -spec: - ... - imagePuller: - enable: true - spec: - configMapName: __<{image-puller-deployment-name}>__ - daemonsetName: __<{image-puller-deployment-name}>__ - deploymentName: __<{image-puller-deployment-name}>__ - images: {image-puller-images} ----- -==== - -include::example$snip_{project-context}-image-puller-dockerfile.adoc[] - - -.Default images - -* The {prod-short} Operator populates the `.spec.imagePuller.spec.images` field with default images used for workspace startup (Theia images, plugin broker images, sidecar plugin images), provided that no images were added to this field before creating the `CheCluster` Custom Resource. The {prod-short} Operator updates the default images in the `.spec.imagePuller.spec.images` field after every rollout update of {prod-short}. However, if images were added to the `.spec.imagePuller.spec.images` field before creating the `CheCluster` Custom Resource, the {prod-short} Operator will not add default images. - -* If user-provided images are added to the `.spec.imagePuller.spec.images` field **after** creating the `CheCluster` Custom Resource, the {prod-short} Operator -will still update default images on subsequent {prod-short} rollout updates. Non-default images remain unchanged in the `.spec.imagePuller.spec.images` field after rollout updates. - - -.Verification - -* {platforms-name} creates a `{image-puller-operator-id}` Subscription. - -* The `eclipse-che namespace` contains a `{image-puller-operator-name}` `ClusterServiceVersion`: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} get clusterserviceversions ----- - -* The `eclipse-che namespace` contains these deployments: `{image-puller-deployment-name}` and `{image-puller-deployment-id}`. -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} get deployments ----- - -* The {image-puller-operator-name} creates a `{image-puller-cr-name}` Custom Resource: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {orch-cli} get kubernetesimagepullers ----- - -.Uninstalling {image-puller-name-short} using {prod-short} Operator - -. Edit the `CheCluster` Custom Resource and set `.spec.imagePuller.enable` to `false`. - -. Edit the `CheCluster` Custom Resource and set the `.spec.imagePuller.spec` to configure the optional {image-puller-name-short} parameters for the {prod-short} Operator. \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_installing-image-puller-using-openshift-templates.adoc b/modules/administration-guide/partials/proc_installing-image-puller-using-openshift-templates.adoc deleted file mode 100644 index 38494b83aa..0000000000 --- a/modules/administration-guide/partials/proc_installing-image-puller-using-openshift-templates.adoc +++ /dev/null @@ -1,138 +0,0 @@ -// caching-images-for-faster-workspace-start - -[id="installing-image-puller-on-openshift-using-openshift-templates_{context}"] -= Installing {image-puller-name-short} on OpenShift using OpenShift templates - -This procedure describes how to install the {image-puller-name} on OpenShift using OpenShift templates. - -.Prerequisites - -* A running OpenShift cluster. -* The `oc` tool is available. -* xref:defining-the-list-of-images-to-pull.adoc[]. -* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. - -.Procedure - -. Clone the {image-puller-name-short} repository and get in the directory containing the OpenShift templates: -+ -include::example$snip_{project-context}-cloning-image-puller-project.adoc[] - - -. Configure the `app.yaml`, `configmap.yaml` and `serviceaccount.yaml` OpenShift templates using following parameters: -+ -.{image-puller-name-short} OpenShift templates parameters in `app.yaml` -[options="header"] -|=== -|Value |Usage |Default - -|`DEPLOYMENT_NAME` -|The value of `DEPLOYMENT_NAME` in the ConfigMap -|`{image-puller-deployment-name}` - -|`IMAGE` -|Image used for the `{image-puller-deployment-name}` deployment -|`{image-puller-image-name}` - -|`IMAGE_TAG` -|The image tag to pull -|`latest` - -|`SERVICEACCOUNT_NAME` -|The name of the ServiceAccount created and used by the deployment -|`kubernetes-image-puller` - -|=== -+ -.{image-puller-name-short} OpenShift templates parameters in `configmap.yaml` -[options="header"] -|=== -|Value |Usage |Default - -|`CACHING_CPU_LIMIT` -|The value of `CACHING_CPU_LIMIT` in the ConfigMap -|`.2` - -|`CACHING_CPU_REQUEST` -|The value of `CACHING_CPU_REQUEST` in the ConfigMap -|`.05` - -|`CACHING_INTERVAL_HOURS` -|The value of `CACHING_INTERVAL_HOURS` in the ConfigMap -|``"1"`` - -|`CACHING_MEMORY_LIMIT` -|The value of `CACHING_MEMORY_LIMIT` in the ConfigMap -|`"20Mi"` - -|`CACHING_MEMORY_REQUEST` -|The value of `CACHING_MEMORY_REQUEST` in the ConfigMap -|`"10Mi"` - -|`DAEMONSET_NAME` -|The value of `DAEMONSET_NAME` in the ConfigMap -|`{image-puller-deployment-name}` - -|`DEPLOYMENT_NAME` -|The value of `DEPLOYMENT_NAME` in the ConfigMap -|`{image-puller-deployment-name}` - -|`IMAGES` -|The value of `IMAGES` in the ConfigMap -|`{image-puller-images}` - -|`NAMESPACE` -|The value of `NAMESPACE` in the ConfigMap -|`{image-puller-namespace}` - -|`NODE_SELECTOR` -|The value of `NODE_SELECTOR` in the ConfigMap -|`"{}"` -|=== -+ -.{image-puller-name-short} OpenShift templates parameters in `serviceaccount.yaml` -[options="header"] -|=== -|Value |Usage |Default - -|`SERVICEACCOUNT_NAME` -|The name of the ServiceAccount created and used by the deployment -|`kubernetes-image-puller` - -|=== - - - -. Create an OpenShift project to host the {image-puller-name-short}: -+ -[subs="+attributes,+quotes"] ----- -$ oc new-project __<{image-puller-namespace}>__ ----- - -. Process and apply the templates to install the puller: -+ -[subs="+attributes,+quotes"] ----- -$ oc process -f serviceaccount.yaml | oc apply -f - -$ oc process -f configmap.yaml | oc apply -f - -$ oc process -f app.yaml | oc apply -f - ----- - - -.Verification steps - -. Verify the existence of a __<{image-puller-deployment-name}>__ deployment and a __<{image-puller-deployment-name}>__ DaemonSet. The DaemonSet needs to have a Pod for each node in the cluster: -+ -[source%nowrap,dummy,subs="+quotes,+attributes"] ----- -$ oc get deployment,daemonset,pod --namespace __<{image-puller-namespace}>__ ----- - -. Verify the values of the __<{image-puller-deployment-name}>__ `ConfigMap`. -+ -[source%nowrap,dummy,subs="+quotes,+attributes"] ----- -$ oc get configmap __<{image-puller-deployment-name}>__ --output yaml ----- - diff --git a/modules/administration-guide/partials/proc_installing-jaeger-using-cli-on-openshift-4.adoc b/modules/administration-guide/partials/proc_installing-jaeger-using-cli-on-openshift-4.adoc deleted file mode 100644 index c4510ffc8e..0000000000 --- a/modules/administration-guide/partials/proc_installing-jaeger-using-cli-on-openshift-4.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// installing-the-jaeger-tracing-tool - -[id="installing-jaeger-using-cli-on-openshift-4_{context}"] -= Installing Jaeger using CLI on OpenShift 4 - -This section provide information about using Jaeger tracing tool for testing an evaluation purposes. - -To install the Jaeger tracing tool from a {prod-short} project in {ocp}, follow the instructions in this section. - -.Prerequisites - -* The user is logged in to the {ocp} web console. -* A instance of {prod-short} in an {ocp} cluster. - -.Procedure - -. In the {prod-short} installation {orch-namespace} of the {ocp} cluster, use the `oc` client to create a new application for the Jaeger deployment. -+ -[subs="+quotes,attributes"] ----- -$ oc new-app -f / $\{CHE_LOCAL_GIT_REPO}/deploy/openshift/templates/jaeger-all-in-one-template.yml: - ---> Deploying template "__<project_name>__/jaeger-template-all-in-one" for "/home/user/{project-context}-projects/{project-context}/deploy/openshift/templates/jaeger-all-in-one-template.yml" to project __<project_name>__ - - Jaeger (all-in-one) - --------- - Jaeger Distributed Tracing Server (all-in-one) - - * With parameters: - * Jaeger Service Name=jaeger - * Image version=latest - * Jaeger Zipkin Service Name=zipkin - ---> Creating resources ... - deployment.apps "jaeger" created - service "jaeger-query" created - service "jaeger-collector" created - service "jaeger-agent" created - service "zipkin" created - route.route.openshift.io "jaeger-query" created ---> Success - Access your application using the route: 'jaeger-query-__<project_name>__.apps.ci-ln-whx0352-d5d6b.origin-ci-int-aws.dev.rhcloud.com' - Run 'oc status' to view your app. ----- - -. Using the *Workloads -> Deployments* from the left menu of main {ocp} screen, monitor the Jaeger deployment until it finishes successfully. - -. Select *Networking -> Routes* from the left menu of the main {ocp} screen, and click the URL link to access the Jaeger dashboard. - -. Follow the steps in xref:tracing-che.adoc#enabling-metrics-collection_{context}[Enabling metrics collection] to finish the procedure. diff --git a/modules/administration-guide/partials/proc_installing-jaeger-using-operatorhub-on-openshift-4.adoc b/modules/administration-guide/partials/proc_installing-jaeger-using-operatorhub-on-openshift-4.adoc deleted file mode 100644 index d9476ffbc7..0000000000 --- a/modules/administration-guide/partials/proc_installing-jaeger-using-operatorhub-on-openshift-4.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// installing-the-jaeger-tracing-tool - -[id="installing-jaeger-using-operatorhub-on-openshift-4_{context}"] -= Installing Jaeger using OperatorHub on OpenShift 4 - -This section provide information about using Jaeger tracing tool for testing an evaluation purposes in production. - -To install the Jaeger tracing tool from the OperatorHub interface in {ocp}, follow the instructions below. - -.Prerequisites - -* The user is logged in to the {ocp} Web Console. -* A {prod-short} instance is available in a {orch-namespace}. - -.Procedure - -. Open the {ocp} console. -. From the left menu of the main {ocp} screen, navigate to *Operators → OperatorHub*. - -. In the *Search by keyword* search bar, type `Jaeger Operator`. - -. Click the `Jaeger Operator` tile. - -. Click the btn:[Install] button in the `Jaeger Operator` pop-up window. - -. Select the installation method: `A specific {orch-namespace} on the cluster` where the {prod-short} is deployed and leave the rest in its default values. -. Click the *Subscribe* button. -. From the left menu of the main {ocp} screen, navigate to the *Operators → Installed Operators* section. -. {prod} is displayed as an Installed Operator, as indicated by the *InstallSucceeded* status. -. Click the *Jaeger Operator* name in the list of installed Operators. -. Navigate to the *Overview* tab. -. In the Conditions sections at the bottom of the page, wait for this message: `install strategy completed with no errors`. -. `Jaeger Operator` and additional `Elasticsearch Operator` is installed. -. Navigate to the *Operators → Installed Operators* section. -. Click *Jaeger Operator* in the list of installed Operators. -. The *Jaeger Cluster* page is displayed. -. In the lower left corner of the window, click *Create Instance* -. Click *Save*. -. OpenShift creates the Jaeger cluster `jaeger-all-in-one-inmemory`. -. Follow the steps in xref:tracing-che.adoc#enabling-metrics-collection_{context}[Enabling metrics collection] to finish the procedure. diff --git a/modules/installation-guide/partials/proc_installing-the-che-operator.adoc b/modules/administration-guide/partials/proc_installing-the-che-operator.adoc similarity index 95% rename from modules/installation-guide/partials/proc_installing-the-che-operator.adoc rename to modules/administration-guide/partials/proc_installing-the-che-operator.adoc index f0c6ea4856..db9c3792c2 100644 --- a/modules/installation-guide/partials/proc_installing-the-che-operator.adoc +++ b/modules/administration-guide/partials/proc_installing-the-che-operator.adoc @@ -2,7 +2,7 @@ // // assembly_installing-che-on-openshift-4-using-operatorhub -[id="installing-the-che-operator_{context}"] +[id="installing-the-{prod-id-short}-operator_{context}"] = Installing the {prod} Operator {prod} Operator provides all the resources for running {prod-short}, such as PostgreSQL, {identity-provider}, image registries, and the {prod-short} server, and it also configures all these services. diff --git a/modules/administration-guide/partials/proc_listing-che-permissions.adoc b/modules/administration-guide/partials/proc_listing-che-permissions.adoc deleted file mode 100644 index eee99c437d..0000000000 --- a/modules/administration-guide/partials/proc_listing-che-permissions.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// authorizing-users - -[id="listing-{prod-id-short}-permissions_{context}"] -= Listing {prod-short} permissions - -To list {prod-short} permissions that apply to a specific *resource*, perform the `GET /permissions` request. - -To list the permissions that apply to a *user*, perform the `GET /permissions/\{domain}` request. - -To list the permissions that apply to *all users*, perform the `GET /permissions/\{domain}/all` request. The user must have *manageSystem* permissions to see this information. - -The suitable domain values are: - -* system -* organization -* workspace - -NOTE: The domain is optional. If no domain is specified, the API returns all possible permissions for all the domains. diff --git a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc deleted file mode 100644 index 4d3c723830..0000000000 --- a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc +++ /dev/null @@ -1,78 +0,0 @@ -[id="managing-backups-using-{prod-cli}"] -= Managing backups using {prod-cli} - - -The following section describes how to create and use backups of a {prod-short} installation to perform a recovery or a rollback to a previous version using `{prod-cli}`. - -.Prerequisites - -include::partial$snip_internal-backup-server-warning.adoc[] - -* xref:setup-backup-server.adoc[Set up a backup server]. - -* xref:configuring-cli-to-use-backup-server.adoc[Configure {prod-cli} to use the backup server] - -.Procedure - - * xref:cli-creating-a-new-backup[] - * xref:cli-restoring-from-backup[] - -[id="cli-creating-a-new-backup"] -== Creating a new backup - -. To create a backup snapshot and send it to a pre-configured backup server: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {prod-cli} server:backup --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ ----- -+ -* You can create other backups to the same backup server using the `server:backup` command with no arguments. -* Using the `server:backup` command with no arguments for the first time will configure and use an internal backup server. - - - -[id="cli-restoring-from-backup"] -== Restoring from a backup - -A {prod-short} administrator can use an existing snapshot of a particular {prod-short} version to restore a desired state or version. The following instructions describe several variations of the restoration command. Adjust the command arguments according to your use case. - -* To restore the previous functional state of the same version of {prod-short}: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {prod-cli} server:restore --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ --snapshot-id=__<snapshot-id>__ ----- - - -* To roll back to a version different from the current version of {prod-short}: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {prod-cli} server:restore --version=__<version>__ --snapshot-id=__<snapshot-id>__ --repository-url=__<repository-url>__ --repository-password=__<repository-password>__ ----- -+ -This performs a version rollback and restores a snapshot made from a previous version of {prod-short}. The provided snapshot must be created from the version of {prod-short} to which you want to roll back. -+ -NOTE: If you have a dedicated backup repository for each {prod-short} version and want to use the most recent backup for the version, you can provide the `latest` argument as a snapshot ID. By doing so, the `latest` argument will be converted to the latest known ID in the given repository, which will be then used by the {prod-short} Operator to recover. - - -* To restore a state described by an existing backup Custom Resource: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {prod-cli} server:restore --backup-cr-name=__<CheClusterBackupCRName>__ ----- - - -* To roll back a version upgrade of {prod-short}: -+ -[source,shell,subs="+quotes,+attributes"] ----- -$ {prod-cli} server:restore --rollback ----- -+ -This recovers the version that {prod-short} was using before upgrading to a later version. -+ -NOTE: {prod-short} Operator automatically creates a backup before every upgrade. - diff --git a/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc deleted file mode 100644 index f480bfb75f..0000000000 --- a/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc +++ /dev/null @@ -1,141 +0,0 @@ -[id="managing-backups-using-custom-resources_{context}"] -= Managing backups using custom resources - -The following section describes how to create backups of {prod-short} installation and recover directly using Custom Resource objects. - - -include::partial$snip_internal-backup-server-warning.adoc[] - -.Prerequisites - -* xref:setup-backup-server.adoc[Setting up a backup server] - -* xref:define-backup-server-for-operator.adoc[Configuring {prod} to use the backup server] - -.Procedure - - * xref:operator-creating-a-new-backup[] - - * xref:operator-restoring-from-a-backup[] - -[id="operator-creating-a-new-backup"] -== Creating a new backup - -. Create a `CheClusterBackup` object to create a new backup: -+ -[source,yaml,subs="+attributes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheClusterBackup -metadata: - name: {prod-short}-backup -spec: - backupServerConfigRef: backup-server-configuration <1> ----- - -<1> Name of the `CheBackupServerConfiguration` object defining what backup server to use. - -* The creation of a `CheClusterBackup` object starts a new backup. -* Before reusing the same name for a new backup object, delete the old object: -+ -[subs="+attributes,+quotes"] ----- -{orch-cli} delete CheClusterBackup _<name>_ -n {prod-namespace} ----- - -[NOTE] -==== -Editing the `CheClusterBackup` objects has no effect. -==== - -.Alternative - -To use the internal backup server, request automatic configuration from {prod-short} Operator. The preparation described above is not required. - -* Configure the automatic setup and sending of the backup to the internal backup server: -+ -[source,yaml,subs="+attributes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheClusterBackup -metadata: - name: {prod-short}-backup -spec: - useInternalBackupServer: true ----- - -[id="operator-restoring-from-a-backup"] -== Restoring from a backup - -[NOTE] -==== -The approach described in this chapter can not be used to recover to a different version of {prod-short}. To recover {prod-short} to another version, use the `{prod-cli}` tool. See the xref:managing-backups-using-cli.adoc[] chapter for more information. -==== - -. Create a new object of `CheClusterRestore` to recover a {prod-short} installation from a backup: -+ -[source,yaml,subs="+attributes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheClusterRestore -metadata: - name: {prod-short}-restore -spec: - backupServerConfigRef: backup-server-configuration <1> - snapshotId: ba92c7e0 <2> ----- - -<1> Name of the `CheBackupServerConfiguration` object that defines what backup server to use. -<2> Optional parameter defining the Snapshot ID to restore from. The default value is the last snapshot on the backup server. - -. Create a new `CheClusterRestore` object to request a new recovery. - -* Before reusing the same name for a new backup object, delete the old object first: -+ -[subs="+attributes,+quotes"] ----- -{orch-cli} delete CheClusterBackup _<name>_ -n {prod-namespace} ----- - -. Wait until the recovery process finishes. -+ -In a case of errors occurrences in your browser after the recovery, clean up the browser data for the {prod-short} domain. - -[NOTE] -==== -Editing of `CheClusterRestore` objects has no effect. -==== - -.Verification - -. Verify backup process state: - -.. Read the `status` section of the `CheClusterBackup` object to check the backup process: -+ -[source,yaml,subs="+attributes"] ----- -status: - message: 'Backup is in progress. Start time: <timestamp>' <1> - stage: Collecting {prod-short} installation data <2> - state: InProgress <3> - snapshotId: ba92c7e0 <4> ----- -<1> Displays the overall state or error message. -<2> Current phase of the backup process in a human-readable format. -<3> Backup process state. One of `InProgress`, `Succeeded`, or `Failed`. -<4> ID of the created backup snapshot. The field appears only when `state` is `Succeeded`. - -. Verify recovery process state - -.. Read the `status` section of the `CheClusterRestore` object to check the recovery process: -+ -[source,yaml,subs="+attributes"] ----- -status: - message: 'Restore is in progress. Start time: <timestamp>' <1> - stage: Restoring {prod-short} related cluster objects <2> - state: InProgress <3> ----- -<1> Overall state or error message. -<2> Current phase of the recovery process in a human-readable format. -<3> Recovery process state. One of `InProgress`, `Succeeded`, or `Failed`. diff --git a/modules/installation-guide/partials/proc_manually-upgrading-che-in-operatorhub.adoc b/modules/administration-guide/partials/proc_manually-upgrading-che-in-operatorhub.adoc similarity index 95% rename from modules/installation-guide/partials/proc_manually-upgrading-che-in-operatorhub.adoc rename to modules/administration-guide/partials/proc_manually-upgrading-che-in-operatorhub.adoc index e9ff78504f..3d13b05d8c 100644 --- a/modules/installation-guide/partials/proc_manually-upgrading-che-in-operatorhub.adoc +++ b/modules/administration-guide/partials/proc_manually-upgrading-che-in-operatorhub.adoc @@ -2,7 +2,7 @@ // // upgrading-che-using-operatorhub -[id="manually-upgrading-che-in-operatorhub_{context}"] +[id="manually-upgrading-{prod-id-short}-in-operatorhub_{context}"] = Manually upgrading {prod-short} in OperatorHub OperatorHub is an assembly point for sharing Operators. The OperatorHub helps you deploy and update applications. The following section describes the process of upgrading {prod-short} by using OperatorHub and the `Manual` approval strategy approach. Use the `Manual` approval strategy to prevent automatic updates of the Operator with every release. diff --git a/modules/administration-guide/partials/proc_migration_from_postgresql_9_to_postgresql_13.adoc b/modules/administration-guide/partials/proc_migration_from_postgresql_9_to_postgresql_13.adoc deleted file mode 100644 index b1731416ec..0000000000 --- a/modules/administration-guide/partials/proc_migration_from_postgresql_9_to_postgresql_13.adoc +++ /dev/null @@ -1,121 +0,0 @@ - -[id="migration-from-postgresql-9-to-postgresql-13_{context}"] -= Migration from PostgreSQL 9 to PostgreSQL 13 - -By the 11th of November, 2021, the PostgreSQL version 9.6 came out of support, and {prod-short} team recommends that all users undergo migrating to version 13. - -Follow the procedure below to migrate to a newer version of PostgreSQL successfully without any data loss. - -.Prerequisites - -* The `{orch-cli}` tool is available. -* An instance of {prod-short} running in {orch-name}. - -.Procedure - -. Save and push changes back to the Git repositories for all running workspaces of the {prod-short} instance. -+ -. Stop all workspaces in the {prod-short} instance. -+ -. Scale down the {prod-short} and {identity-provider} deployments: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} scale deployment {prod-deployment} --replicas=0 -n {prod-namespace} -{orch-cli} scale deployment keycloak --replicas=0 -n {prod-namespace} ----- - -. Backup available databases: -+ -[subs="+quotes,+attributes"] ----- -POSTGRES_POD=$({orch-cli} get pods -n {prod-namespace} | grep postgres | awk '{print $1}') -CHE_POSTGRES_DB=$({orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o json | jq '.spec.database.chePostgresDb') -{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace} -- bash -c "pg_dump $CHE_POSTGRES_DB > /tmp/che.sql" -{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace} -- bash -c "pg_dump keycloak > /tmp/keycloak.sql" ----- - -. Copy the obtained backups to a local file system: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} cp {prod-namespace}/$POSTGRES_POD:/tmp/che.sql che.sql -{orch-cli} cp {prod-namespace}/$POSTGRES_POD:/tmp/keycloak.sql keycloak.sql ----- - -. Scale down the PostgreSQL deployment: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} scale deployment postgres --replicas=0 -n {prod-namespace} ----- - -. Delete the corresponding PVC unit to clean up old data: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} delete pvc postgres-data -n {prod-namespace} ----- -+ -After deleting the PVC from the step above, a new PVC will automatically appear in a few seconds. - -. Set the version of the new PostgreSQL database to 13.3: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p '[{"op": "replace", "path": "/spec/database/postgresVersion", "value": "13.3"}]' ----- - -. Scale up the PostgreSQL deployments: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} scale deployment postgres --replicas=1 -n {prod-namespace} -{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component=postgres -n {prod-namespace} --timeout=120s ----- - -. Provision a database: -+ -[subs="+quotes,+attributes"] ----- -POSTGRES_POD=$({orch-cli} get pods -n {prod-namespace} | grep postgres | awk '{print $1}') -OPERATOR_POD=$({orch-cli} get pods -n {prod-namespace} | grep {prod-operator} | awk '{print $1}') - -IDENTITY_POSTGRES_SECRET=$({orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o json | jq -r '.spec.auth.identityProviderPostgresSecret') -IDENTITY_POSTGRES_PASSWORD=$(if [ -z "$IDENTITY_POSTGRES_SECRET" ] || [ $IDENTITY_POSTGRES_SECRET = "null" ]; then {orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o json | jq -r '.spec.auth.identityProviderPostgresPassword'; else {orch-cli} get secret $IDENTITY_POSTGRES_SECRET -n {prod-namespace} -o json | jq -r '.data.password' | base64 -d; fi) - -{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace} -- bash -c "psql postgres -tAc \"CREATE USER keycloak WITH PASSWORD '$IDENTITY_POSTGRES_PASSWORD'\"" -{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace} -- bash -c "psql postgres -tAc \"CREATE DATABASE keycloak\"" -{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace} -- bash -c "psql postgres -tAc \"GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak\"" - -POSTGRES_SECRET=$({orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o json | jq -r '.spec.database.chePostgresSecret') -CHE_USER=$(if [ -z "$POSTGRES_SECRET" ] || [ $POSTGRES_SECRET = "null" ]; then {orch-cli} get checluster/{prod-checluster} -n {prod-namespace} -o json | jq -r '.spec.database.chePostgresUser'; else {orch-cli} get secret $POSTGRES_SECRET -n {prod-namespace} -o json | jq -r '.data.user' | base64 -d; fi) - -{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace} -- bash -c "psql postgres -tAc \"ALTER USER $CHE_USER WITH SUPERUSER\"" ----- - -. Copy the backups to the PostgreSQL Pod: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} cp che.sql {prod-namespace}/$POSTGRES_POD:/tmp/che.sql -{orch-cli} cp keycloak.sql {prod-namespace}/$POSTGRES_POD:/tmp/keycloak.sql ----- - -. Restore the database: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace} -- bash -c "psql keycloak < /tmp/keycloak.sql" -{orch-cli} exec -it $POSTGRES_POD -n {prod-namespace} -- bash -c "psql $CHE_POSTGRES_DB < /tmp/che.sql" ----- - -. Scale up the {identity-provider} and {prod-short} deployments: -+ -[subs="+quotes,+attributes"] ----- -{orch-cli} scale deployment keycloak --replicas=1 -n {prod-namespace} -{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component=keycloak -n {prod-namespace} --timeout=120s -{orch-cli} scale deployment {prod-deployment} --replicas=1 -n {prod-namespace} -{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component={prod-deployment} -n {prod-namespace} --timeout=120s ----- diff --git a/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc b/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc similarity index 95% rename from modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc rename to modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc index 89ee286413..f73f934eb7 100644 --- a/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc +++ b/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc @@ -9,7 +9,7 @@ .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* A running instance of {prod}. .Procedure diff --git a/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc b/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc similarity index 96% rename from modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc rename to modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc index f213493a3a..fd19109095 100644 --- a/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc +++ b/modules/administration-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc @@ -9,7 +9,7 @@ .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* A running instance of {prod}. .Procedure diff --git a/modules/administration-guide/partials/proc_removing-initial-openshift-user.adoc b/modules/administration-guide/partials/proc_removing-initial-openshift-user.adoc deleted file mode 100644 index c5de8862dd..0000000000 --- a/modules/administration-guide/partials/proc_removing-initial-openshift-user.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="proc_removing-initial-openshift-user_{context}"] -= Removing OpenShift initial OAuth user - -The following procedure describes how to remove OpenShift initial OAuth user provisioned by {prod}. - -.Prerequisites - -* The `oc` tool installed. -* An instance of {prod} running on OpenShift. -* Logged in to OpenShift cluster using the `oc` tool. - -.Procedure - -. Update {prod-checluster} custom resource: -+ -[subs="+quotes,+attributes"] ----- -$ oc patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/auth/initialOpenShiftOAuthUser", "value": false}]' ----- diff --git a/modules/administration-guide/partials/proc_removing-user-data.adoc b/modules/administration-guide/partials/proc_removing-user-data.adoc deleted file mode 100644 index e2d9e30b1e..0000000000 --- a/modules/administration-guide/partials/proc_removing-user-data.adoc +++ /dev/null @@ -1,153 +0,0 @@ -[id="removing-user-data_{context}"] -= Removing user data - -== Removing user data according to GDPR - -The General Data Protection Regulation (link:https://en.wikipedia.org/wiki/General_Data_Protection_Regulation[GDPR]) law enforces the right for individuals to have personal data erased. - -The following procedure describes how to remove a user’s data from a cluster and the {identity-provider} database. - -[NOTE] -==== -The following commands use the default {platforms-namespace}, `{prod-namespace}`, as a user's example for the `-n` option. -==== - -.Prerequisites - -* A user or an administrator authorization token. To delete any other data except the data bound to a user account, `admin` privileges are required. The `admin` is a special {prod-short} administrator account pre-created and enabled using the `pass:[CHE_SYSTEM_ADMIN__NAME]` and `pass:[CHE_SYSTEM_SUPER__PRIVILEGED__MODE = true]` Custom Resource definitions. -+ -[subs="+quotes,macros"] ----- -spec: - server: - customCheProperties: - pass:[CHE_SYSTEM_SUPER__PRIVILEGED__MODE]: 'true' - pass:[CHE_SYSTEM_ADMIN__NAME]: '__<admin-name>__' ----- -+ -If needed, use commands below for creating the `admin` user: -+ -[subs="+quotes,macros,attributes"] ----- -$ {orch-cli} patch checluster/{prod-checluster} \ - --type merge \ - -p '{ "spec": { "server": {"customCheProperties": {"pass:[CHE_SYSTEM_SUPER__PRIVILEGED__MODE]": "true"} } }}' \ - -n __{prod-namespace}__ ----- -+ -[subs="+quotes,macros,attributes"] ----- -$ {orch-cli} patch checluster/{prod-checluster} \ - --type merge \ - -p '{ "spec": { "server": {"customCheProperties": {"pass:[CHE_SYSTEM_ADMIN__NAME]": "__<admin-name>__"} } }}' \ - -n __{prod-namespace}__ ----- -+ -[NOTE] -==== -All system permissions are granted to the administrative user. To configure the administrative user, use the `CHE_SYSTEM_ADMIN__NAME` property. The default value is `admin`. The system permissions are granted when the {prod-short} server starts. If the user record is not in the {prod-short} user database, the permissions are granted after the first login of the user. - -.Authorization token privileges: - -* `admin` - Can delete all personal data of all users -* `user` - Can delete only the data related to the user -==== - -* A user or an administrator is logged in the OpenShift cluster with deployed {prod-short}. - -* A user ID is obtained. Get the user ID using the commands below: - -** For the current user: -+ -[subs="+quotes,macros,attributes"] ----- -$ curl -X GET \ - --header 'Authorization: Bearer __<user-token>__' \ - 'pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user' ----- - -** To find a user by name: -+ -[subs="+quotes,macros,attributes"] ----- -$ curl -X GET \ - --header 'Authorization: Bearer __<user-token>__' \ - 'pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user/find?name=__<username>__' ----- - -** To find a user by email: -+ -[subs="+quotes,macros,attributes"] ----- -$ curl -X GET \ - --header 'Authorization: Bearer __<user-token>__' \ - 'pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user/find?email=__<email>__' ----- -+ -.Example of obtaining a user ID -+ -This example uses `vparfono` as a local user name. -+ -==== -[subs="+quotes,macros,attributes"] ----- -$ curl -X GET \ - --header 'Authorization: Bearer __<user-token>__' \ - 'https://che-vp-che.apps.che-dev.x6e0.p1.openshiftapps.com/api/user/find?name=vparfono' ----- - -The user ID is at the bottom of the curl command output. - -[source,json] ----- -{ - "name": "vparfono", - "links": [ - { -. -. -. - } - ], - "email": "vparfono@redhat.com", - "id": "921b6f33-2657-407e-93a6-fb14cf2329ce" -} ----- -==== - -.Procedure - -. Update the `{prod-checluster}` `CheCluster Custom` Resource (CR) definition to permit the removal of a user’s data from the {identity-provider} database: -+ -[subs="+quotes,macros,attributes"] ----- -$ {orch-cli} patch checluster/{prod-checluster} \ - --patch "{\"spec\":{\"server\":{\"customCheProperties\": {\"pass:[CHE_KEYCLOAK_CASCADE__USER__REMOVAL__ENABLED]\": \"true\"}}}}" \ - --type=merge -n _{prod-namespace}_ ----- - -. Remove the data using the API: -+ -[subs="+quotes,macros,attributes"] ----- -$ curl -i -X DELETE \ - --header 'Authorization: Bearer __<user-token>__' \ - pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user/__<user-id>__ ----- - - -.Verification - -Running the following command returns code `204` as the API response: - -[subs="+quotes,macros,attributes"] ----- -$ curl -i -X DELETE \ - --header 'Authorization: Bearer __<user-token>__' \ - pass:c,m,a,q[+https:+//__<{prod-host}>__]/api/user/__<user-id>__ ----- - - -.Additional resources - -To remove the data of all users, follow the instructions for xref:installation-guide:uninstalling-che.adoc[]. diff --git a/modules/administration-guide/partials/proc_setting-up-the-bitbucket-application-link.adoc b/modules/administration-guide/partials/proc_setting-up-the-bitbucket-application-link.adoc new file mode 100644 index 0000000000..8ed560bede --- /dev/null +++ b/modules/administration-guide/partials/proc_setting-up-the-bitbucket-application-link.adoc @@ -0,0 +1,65 @@ +:_content-type: PROCEDURE +:description: Setting up the Bitbucket application link +:keywords: bitbucket, bitbucket-application-link, application-link +:navtitle: Setting up the Bitbucket application link +// :page-aliases: + +[id="setting-up-the-bitbucket-application-link_{context}"] += Setting up the Bitbucket application link + +Set up a Bitbucket application link using OAuth 1.0. + +.Prerequisites + +* You are logged in to Bitbucket. +* link:https://www.openssl.org/[`openssl`] is installed in the operating system you are using. +* link:https://www.gnu.org/software/coreutils/base64[`base64`] is installed in the operating system you are using. + +.Procedure + +. On a command line, run the commands to create the necessary files for the next steps and for use when applying the Bitbucket application link Secret: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ openssl genrsa -out private.pem 2048 && \ +openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in private.pem -out privatepkcs8.pem && \ +cat privatepkcs8.pem | sed 's/-----BEGIN PRIVATE KEY-----//g' | sed 's/-----END PRIVATE KEY-----//g' | tr -d '\n' | base64 | tr -d '\n' > privatepkcs8-stripped.pem && \ +openssl rsa -in private.pem -pubout > public.pub && \ +cat public.pub | sed 's/-----BEGIN PUBLIC KEY-----//g' | sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n' > public-stripped.pub && \ +openssl rand -base64 24 > bitbucket-consumer-key && \ +openssl rand -base64 24 > bitbucket-shared-secret +---- + +. Go to menu:Administration[Application Links]. + +. Enter `pass:c,a,q[{prod-url}]/` into the URL field and click *Create new link*. + +. Under *The supplied Application URL has redirected once*, check the *Use this URL* checkbox and click *Continue*. + +. Enter *{prod-short}* as the *Application Name*. + +. Select *Generic Application* as the *Application Type*. + +. Enter *{prod-short}* as the *Service Provider Name*. + +. Paste the content of the `bitbucket-consumer-key` file as the *Consumer key*. + +. Paste the content of the `bitbucket-shared-secret` file as the *Shared secret*. + +. Enter `__<bitbucket_server_url>__/plugins/servlet/oauth/request-token` as the *Request Token URL*. + +. Enter `__<bitbucket_server_url>__/plugins/servlet/oauth/access-token` as the *Access token URL*. + +. Enter `__<bitbucket_server_url>__/plugins/servlet/oauth/authorize` as the *Authorize URL*. + +. Check the *Create incoming link* checkbox and click *Continue*. + +. Paste the content of the `bitbucket_consumer_key` file as the *Consumer Key*. + +. Enter *{prod-short}* as the *Consumer name*. + +. Paste the content of the `public-stripped.pub` file as the *Public Key* and click *Continue*. + +.Additional resources + +* link:https://confluence.atlassian.com/bitbucketserver/link-to-other-applications-1018764620.html[Atlassian Documentation: Link to other applications] \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc new file mode 100644 index 0000000000..763b7f0093 --- /dev/null +++ b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc @@ -0,0 +1,48 @@ +:_content-type: PROCEDURE +:description: Setting up the GitHub OAuth App +:keywords: github, github-oauth-app +:navtitle: Setting up the GitHub OAuth App +// :page-aliases: + +[id="setting-up-the-github-oauth-app_{context}"] += Setting up the GitHub OAuth App + +Set up a GitHub OAuth App using OAuth 2.0. + +.Prerequisites + +* You are logged in to GitHub. +* link:https://www.gnu.org/software/coreutils/base64[`base64`] is installed in the operating system you are using. + +.Procedure + +. Go to link:https://github.com/settings/applications/new[]. +//Long version: Click your GitHub avatar menu:Settings[Developer settings > OAuth Apps > Register a new application]. max-cx + +. Enter the following values: + +.. *Application name*: `{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 *GitHub OAuth Client ID* and encode it to Base64 for use when applying the GitHub OAuth App Secret: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ echo -n '__<github_oauth_client_id>__' | base64 +---- + +. Copy the *GitHub OAuth Client Secret* and encode it to Base64 for use when applying the GitHub OAuth App Secret: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ echo -n '__<github_oauth_client_secret>__' | base64 +---- + +.Additional resources + +* link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub Docs: Creating an OAuth App] \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_setting-up-the-gitlab-authorized-application.adoc b/modules/administration-guide/partials/proc_setting-up-the-gitlab-authorized-application.adoc new file mode 100644 index 0000000000..e8280121e3 --- /dev/null +++ b/modules/administration-guide/partials/proc_setting-up-the-gitlab-authorized-application.adoc @@ -0,0 +1,47 @@ +:_content-type: PROCEDURE +:description: Setting up the GitLab authorized application +:keywords: gitlab, gitlab-application, gitlab-authorized-application, authorized-application +:navtitle: Setting up the GitLab authorized application +// :page-aliases: + +[id="setting-up-the-gitlab-authorized-application_{context}"] += Setting up the GitLab authorized application + +Set up a GitLab authorized application using OAuth 2.0. + +.Prerequisites + +* You are logged in to GitLab. +* link:https://www.gnu.org/software/coreutils/base64[`base64`] is installed in the operating system you are using. + +.Procedure + +. Click your avatar and go to menu:Edit profile[Applications]. + +. Enter *{prod-short}* as the *Name*. + +. Enter `pass:c,a,q[{prod-url}]/api/oauth/callback` as the *Redirect URI*. + +. Check the *Confidential* and *Expire access tokens* checkboxes. + +. Under *Scopes*, check the `api`, `write_repository`, and `openid` checkboxes. + +. Click *Save application*. + +. Copy the *GitLab Application ID* and encode it to Base64 for use when applying the GitLab-authorized application Secret: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ echo -n '__<gitlab_application_id>__' | base64 +---- + +. Copy the *GitLab Client Secret* and encode it to Base64 for use when applying the GitLab-authorized application Secret: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ echo -n '__<gitlab_client_secret>__' | base64 +---- + +.Additional resources + +* link:https://docs.gitlab.com/ee/integration/oauth_provider.html#authorized-applications[GitLab Docs: Authorized applications] \ No newline at end of file diff --git a/modules/installation-guide/partials/proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc b/modules/administration-guide/partials/proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc similarity index 89% rename from modules/installation-guide/partials/proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc rename to modules/administration-guide/partials/proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc index ec6895da1a..acbfda628c 100644 --- a/modules/installation-guide/partials/proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc +++ b/modules/administration-guide/partials/proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc @@ -2,8 +2,7 @@ // // upgrading-che-using-operatorhub -[id="specifying-the-approval-strategy-of-che-in-operatorhub_{context}"] - +[id="specifying-the-approval-strategy-of-{prod-id-short}-in-operatorhub_{context}"] = Specifying the approval strategy of {prod-short} in OperatorHub .Prerequisites diff --git a/modules/contributor-guide/partials/proc_testing-che-theia-with-custom-branding.adoc b/modules/administration-guide/partials/proc_testing-che-theia-with-custom-branding.adoc similarity index 74% rename from modules/contributor-guide/partials/proc_testing-che-theia-with-custom-branding.adoc rename to modules/administration-guide/partials/proc_testing-che-theia-with-custom-branding.adoc index f4bde3c77c..3946b8afa3 100644 --- a/modules/contributor-guide/partials/proc_testing-che-theia-with-custom-branding.adoc +++ b/modules/administration-guide/partials/proc_testing-che-theia-with-custom-branding.adoc @@ -17,7 +17,7 @@ This section describes how to test a customized Che-Theia by opening a new works To test a custom Che-Theia image, create a new `meta.yaml` file describing a custom `cheEditor`, and use it in a devfile for the testing workspace. -. Clone the che-plugin-registry repository and check out the version to deploy. See, +. Clone the `che-plugin-registry` repository and check out the version to deploy. See, + include::administration-guide:example$snip_{project-context}-clone-the-plug-in-registry-repository.adoc[] @@ -35,9 +35,9 @@ include::administration-guide:example$snip_{project-context}-build-a-custom-plug . Create a workspace using the sample https://raw.githubusercontent.com/che-samples/che-theia-branding-example/master/devfile.yaml[che-theia-branding-example devfile] to apply the changes. + -Make sure the `reference` field points to your published `meta.yaml` file: +Verify the `reference` field points to your published `meta.yaml` file: + -image::https://www.eclipse.org/che/contribute.svg[link="https://workspaces.openshift.com/f?url=https://raw.githubusercontent.com/che-samples/che-theia-branding-example/master/devfile.yaml"] +image::contribute.svg[link="https://workspaces.openshift.com/f?url=https://raw.githubusercontent.com/che-samples/che-theia-branding-example/master/devfile.yaml"] + [source,yaml,attrs="nowrap"] ---- @@ -60,15 +60,15 @@ apiVersion: 1.0.0 + * The dark theme of Che-Theia: + -image::branding/welcome-dark.png[link="../_images/branding/welcome-dark.png"] +image::branding/welcome-dark.png[link="{imagesdir}/branding/welcome-dark.png"] + -image::branding/about-dark.png[link="../_images/branding/about-dark.png"] +image::branding/about-dark.png[link="{imagesdir}/branding/about-dark.png"] * The light theme of Che-Theia: + -image::branding/welcome-light.png[link="../_images/branding/welcome-light.png"] +image::branding/welcome-light.png[link="{imagesdir}/branding/welcome-light.png"] + -image::branding/about-light.png[link="../_images/branding/about-light.png"] +image::branding/about-light.png[link="{imagesdir}/branding/about-light.png"] //// diff --git a/modules/installation-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc b/modules/administration-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc similarity index 73% rename from modules/installation-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc rename to modules/administration-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc index 54fda6f94c..40c61f3afc 100644 --- a/modules/installation-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc +++ b/modules/administration-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc @@ -10,7 +10,7 @@ This section describes how to install {prod-short} on CodeReady Containers (CRC) .Prerequisites * The `{prod-cli}` management tool is available. See xref:using-the-chectl-management-tool.adoc[]. -* An installation of CodeReady Containers. See link:https://cloud.redhat.com/openshift/install/crc/installer-provisioned[Installing CodeReady Containers]. +* An installation of CodeReady Containers. See link:https://console.redhat.com/openshift/create/local[Installing CodeReady Containers]. * The path to the user's CRC pull secrete is known. .Procedure @@ -65,13 +65,6 @@ $ {prod-cli} server:deploy --platform crc Login: developer Password: developer ---- -+ -* For the first time {prod-short} installation, a user needs to import the {prod-short} certificate to the browser of their choice. See, xref:end-user-guide:importing-certificates-to-browsers.adoc[]. -+ -[NOTE] -==== -For a {prod-cli} installation, the browser certificate is copied to the `/tmp/cheCA.crt` folder by the `chectl cacert:export` command during the deployment. This is the same certificate that can be extracted from the User Dashboard of a {prod-short} instance, the export of which is described in the link above, and can be used for the direct browser import. -==== . Enter the user's credentials and start using {prod-short}. diff --git a/modules/installation-guide/partials/proc_using-minikube-and-lxc.adoc b/modules/administration-guide/partials/proc_using-minikube-and-lxc.adoc similarity index 100% rename from modules/installation-guide/partials/proc_using-minikube-and-lxc.adoc rename to modules/administration-guide/partials/proc_using-minikube-and-lxc.adoc diff --git a/modules/installation-guide/partials/proc_using-minikube-to-set-up-kubernetes.adoc b/modules/administration-guide/partials/proc_using-minikube-to-set-up-kubernetes.adoc similarity index 100% rename from modules/installation-guide/partials/proc_using-minikube-to-set-up-kubernetes.adoc rename to modules/administration-guide/partials/proc_using-minikube-to-set-up-kubernetes.adoc diff --git a/modules/installation-guide/partials/proc_using-openshift-web-console-to-install-che-on-codeready-containers.adoc b/modules/administration-guide/partials/proc_using-openshift-web-console-to-install-che-on-codeready-containers.adoc similarity index 100% rename from modules/installation-guide/partials/proc_using-openshift-web-console-to-install-che-on-codeready-containers.adoc rename to modules/administration-guide/partials/proc_using-openshift-web-console-to-install-che-on-codeready-containers.adoc diff --git a/modules/administration-guide/partials/proc_using-protocol-based-providers.adoc b/modules/administration-guide/partials/proc_using-protocol-based-providers.adoc deleted file mode 100644 index d66282cc31..0000000000 --- a/modules/administration-guide/partials/proc_using-protocol-based-providers.adoc +++ /dev/null @@ -1,6 +0,0 @@ -// configuring-authorization - -[id="using-protocol-based-providers_{context}"] -= Using protocol-based providers - -{identity-provider} supports link:{link-identity-provider-saml}[SAML v2.0] and link:{link-identity-provider-oidc}[OpenID Connect v1.0] protocols. diff --git a/modules/administration-guide/partials/proc_using-swagger-or-rest-clients-to-execute-queries.adoc b/modules/administration-guide/partials/proc_using-swagger-or-rest-clients-to-execute-queries.adoc deleted file mode 100644 index e7d1c1c18f..0000000000 --- a/modules/administration-guide/partials/proc_using-swagger-or-rest-clients-to-execute-queries.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// authenticating-to-the-{prod-id-short}-server - -[id="using-swagger-or-rest-clients-to-execute-queries_{context}"] -= Using Swagger or REST clients to execute queries - -The user's {identity-provider} token is used to execute queries to the secured API on the user's behalf through REST clients. A valid token must be attached as the *Request* header or the `?token=$token` query parameter. - -Access the {prod-short} Swagger interface at `pass:c,a,q[{prod-url}/swagger]`. The user must be signed in through {identity-provider}, so that the access token is included in the *Request* header. diff --git a/modules/administration-guide/partials/proc_verification-custom-registries.adoc b/modules/administration-guide/partials/proc_verification-custom-registries.adoc deleted file mode 100644 index 07b55364d6..0000000000 --- a/modules/administration-guide/partials/proc_verification-custom-registries.adoc +++ /dev/null @@ -1,92 +0,0 @@ -// deploying-the-registries - -.Verification steps - -. The __<plug-in>__ plug-in is available in the plug-in registry. -+ -.Find __<plug-in>__ requesting the plug-in registry API. -+ -==== -[subs="+quotes,+attributes"] ----- -$ URL=$({orch-cli} get {platform-routing} -l app=che,component=plugin-registry \ - -o 'custom-columns=URL:{platform-routing-host-path}' --no-headers) -$ INDEX_JSON=$(curl -sSL http://$\{URL}/v3/plugins/index.json) -$ echo $\{INDEX_JSON} | jq '.[] | select(.name == "__<plug-in>__")' ----- -==== - -. The __<devfile>__ devfile is available in the devfile registry. -+ -.Find __<devfile>__ requesting the devfile registry API. -==== -[subs="+quotes,+attributes"] ----- -$ URL=$({orch-cli} get {platform-routing} -l app=che,component=devfile-registry \ - -o 'custom-columns=URL:{platform-routing-host-path}' --no-headers) -$ INDEX_JSON=$(curl -sSL http://$\{URL}/v3/plugins/index.json) -$ echo $\{INDEX_JSON} | jq '.[] | select(.name == "__<devfile>__")' ----- -==== - -. {prod-short} server points to the URL of the plug-in registry. -+ -.Compare the value of the `pass:[CHE_WORKSPACE_PLUGIN__REGISTRY__URL]` parameter in the `che` ConfigMap with the URL of the plug-in registry {platform-routing}. -==== -.Get the value of the `pass:[CHE_WORKSPACE_PLUGIN__REGISTRY__URL]` parameter in the `che` ConfigMap. -[subs="+attributes"] ----- -$ {orch-cli} get cm/che \ - -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGIN__REGISTRY__URL']" \ - --no-headers ----- - -.Get the URL of the plug-in registry {platform-routing}. -[subs="+quotes,+attributes"] ----- -$ {orch-cli} get {platform-routing} -l app=che,component=plugin-registry \ - -o 'custom-columns=URL: {platform-routing-host-path}' --no-headers ----- -==== - -. {prod-short} server points to the URL of the devfile registry. -+ -.Compare the value of the `pass:[CHE_WORKSPACE_DEVFILE__REGISTRY__URL]` parameter in the `che` ConfigMap with the URL of the devfile registry {platform-routing}. -==== -.Get the value of the `pass:[CHE_WORKSPACE_DEVFILE__REGISTRY__URL]` parameter in the `che` ConfigMap. -[subs="+attributes"] ----- -$ {orch-cli} get cm/che \ - -o "custom-columns=URL:.data['CHE_WORKSPACE_DEVFILE__REGISTRY__URL']" \ - --no-headers ----- - -.Get the URL of the devfile registry {platform-routing}. -[subs="+quotes,+attributes"] ----- -$ {orch-cli} get {platform-routing} -l app=che,component=devfile-registry \ - -o 'custom-columns=URL: {platform-routing-host-path}' --no-headers ----- -==== - -. If the values do not match, update the ConfigMap and restart the {prod-short} server. -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} edit cm/{prod-deployment} -(...) -$ {orch-cli} scale --replicas=0 deployment/{prod-deployment} -$ {orch-cli} scale --replicas=1 deployment/{prod-deployment} ----- - -pass:[<!-- vale Vale.Terms = NO -->] - -* The plug-ins are available in the: - -** Completion to *chePlugin* components in the *Devfile* tab of a workspace details - -** *Plugin* Che-Theia view of a workspace - -pass:[<!-- vale Vale.Terms = YES -->] - -* The devfiles are available in the *Quick Add* and *Custom Workspace* tab of the *Create Workspace* page on the user dashboard. diff --git a/modules/administration-guide/partials/proc_viewing-che-server-logs-on-the-cli.adoc b/modules/administration-guide/partials/proc_viewing-che-server-logs-on-the-cli.adoc deleted file mode 100644 index 888ae01ac4..0000000000 --- a/modules/administration-guide/partials/proc_viewing-che-server-logs-on-the-cli.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// viewing-{prod-id-short}-server-logs - -[id="viewing-{prod-id-short}-server-logs-on-the-cli_{context}"] -= Viewing the {prod-short} server logs using the OpenShift CLI - -This section describes how to view the {prod-short} server logs using the OpenShift CLI (command line interface). - -.Procedure - -. In the terminal, run the following command to get the Pods: -+ ----- -$ oc get pods ----- -+ -.Example -[subs="+attributes"] ----- -$ oc get pods -NAME READY STATUS RESTARTS AGE -{prod-deployment}-11-j4w2b 1/1 Running 0 3m ----- - -. To get the logs for a deployment, run the following command: -+ -[subs="+quotes"] ----- -$ oc logs _<name-of-pod>_ ----- -+ -.Example -[subs="+attributes"] ----- -$ oc logs {prod-deployment}-11-j4w2b ----- diff --git a/modules/administration-guide/partials/proc_viewing-che-traces-in-jaeger-ui.adoc b/modules/administration-guide/partials/proc_viewing-che-traces-in-jaeger-ui.adoc deleted file mode 100644 index 1e874164db..0000000000 --- a/modules/administration-guide/partials/proc_viewing-che-traces-in-jaeger-ui.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// tracing-{prod-id-short} - -[id="viewing-{prod-id-short}-traces-in-jaeger-ui_{context}"] -= Viewing {prod-short} traces in Jaeger UI - -This section demonstrates how to use the Jaeger UI to overview traces of {prod-short} operations. - -.Procedure - -In this example, the {prod-short} instance has been running for some time and one workspace start has occurred. - -To inspect the trace of the workspace start: - -. In the *Search* panel on the left, filter spans by the operation name (span name), tags, or time and duration. -+ -.Using Jaeger UI to trace {prod-short} -image::tracing/trace-search.png[link="../_images/tracing/trace-search.png"] - -. Select the trace to expand it and show the tree of nested spans and additional information about the highlighted span, such as tags or durations. -+ -.Expanded tracing tree -image::tracing/trace-tree-expanded.png[link="../_images/tracing/trace-tree-expanded.png"] diff --git a/modules/administration-guide/partials/proc_viewing-keycloak-client-logs-on-firefox.adoc b/modules/administration-guide/partials/proc_viewing-keycloak-client-logs-on-firefox.adoc deleted file mode 100644 index cfd41b967f..0000000000 --- a/modules/administration-guide/partials/proc_viewing-keycloak-client-logs-on-firefox.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// viewing-keycloak-logs - -[id="viewing-keycloak-client-logs-on-firefox_{context}"] -= Viewing the {identity-provider} client logs on Firefox - -This section describes how to view the {identity-provider} IDE client diagnostics or error information in the Firefox *WebConsole*. - -.Procedure - -* Click *Menu* > *WebDeveloper* > *WebConsole*. diff --git a/modules/administration-guide/partials/proc_viewing-keycloak-client-logs-on-google-chrome.adoc b/modules/administration-guide/partials/proc_viewing-keycloak-client-logs-on-google-chrome.adoc deleted file mode 100644 index cd28c81f5f..0000000000 --- a/modules/administration-guide/partials/proc_viewing-keycloak-client-logs-on-google-chrome.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// viewing-keycloak-logs - -[id="viewing-keycloak-client-logs-on-google-chrome_{context}"] -= Viewing the {identity-provider} client logs on Google Chrome - -This section describes how to view the {identity-provider} IDE client diagnostics or error information in the Google Chrome *Console* tab. - -.Procedure - -. Click *Menu* > *More Tools* > *Developer Tools*. -. Click the *Console* tab. diff --git a/modules/administration-guide/partials/proc_viewing-keycloak-server-logs.adoc b/modules/administration-guide/partials/proc_viewing-keycloak-server-logs.adoc deleted file mode 100644 index e89abef0ac..0000000000 --- a/modules/administration-guide/partials/proc_viewing-keycloak-server-logs.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// viewing-keycloak-logs - - - -[id="viewing-keycloak-server-logs_{context}"] -= Viewing the {identity-provider} server logs - -This section describes how to view the {identity-provider} OpenID provider server logs. - -.Procedure - -. In the OpenShift Web Console, click *Deployments*. - -. In the *Filter by label* search field, type `keycloak` to see the {identity-provider} logs. - -pass:[<!-- vale Vale.Spelling = NO -->] -. In the *Deployment Configs* section, click the `keycloak` link to open it. - -pass:[<!-- vale Vale.Spelling = YES -->] - -. In the *History* tab, click the *View log* link for the active {identity-provider} deployment. - -. The {identity-provider} logs are displayed. - -.Additional resources - -* See the xref:viewing-che-server-logs.adoc[] for diagnostics and error messages related to the {identity-provider} IDE Server. diff --git a/modules/administration-guide/partials/proc_viewing-kubernetes-events.adoc b/modules/administration-guide/partials/proc_viewing-kubernetes-events.adoc deleted file mode 100644 index 4e2ee7933f..0000000000 --- a/modules/administration-guide/partials/proc_viewing-kubernetes-events.adoc +++ /dev/null @@ -1,35 +0,0 @@ - - -:parent-context-of-viewing-kubernetes-events: {context} -[id="viewing-kubernetes-events_{context}"] -= Accessing {platforms-name} events on OpenShift - -:context: viewing-kubernetes-events - -For high-level monitoring of OpenShift projects, view the {platforms-name} events that the project performs. - -This section describes how to access these events in the OpenShift web console. - -.Prerequisites - -* A running OpenShift web console. - -.Procedure - -. In the left panel of the OpenShift web console, click the *Home -> Events*. - -. To view the list of all events for a particular project, select the project from the list. - -. The details of the events for the current project are displayed. -//// -+ -image::logs/kubernetes-events.png[link="../_images/logs/kubernetes-events.png"] -//// - -.Additional resources - -* For a list of {platforms-name} events, see -https://docs.openshift.com/container-platform/3.6/dev_guide/events.html#events-reference[Comprehensive -List of Events in OpenShift documentation]. - -:context: {parent-context-of-viewing-kubernetes-events} diff --git a/modules/administration-guide/partials/proc_viewing-plug-in-broker-logs.adoc b/modules/administration-guide/partials/proc_viewing-plug-in-broker-logs.adoc deleted file mode 100644 index 0c1bea5500..0000000000 --- a/modules/administration-guide/partials/proc_viewing-plug-in-broker-logs.adoc +++ /dev/null @@ -1,27 +0,0 @@ - - -:parent-context-of-viewing-plug-in-broker-logs: {context} - -[id="viewing-plug-in-broker-logs_{context}"] -= Viewing the plug-in broker logs - -:context: viewing-plug-in-broker-logs - -This section describes how to view the plug-in broker logs. - -The `che-plugin-broker` Pod itself is deleted when its work is complete. Therefore, its event logs are only available while the workspace is starting. - -.Procedure - -To see logged events from temporary Pods: - -. Start a {prod-short} workspace. - -. From the main {ocp} screen, go to *Workload -> Pods*. - -. Use the OpenShift terminal console located in the Pod's *Terminal* tab - -.Verification step -* OpenShift terminal console displays the plug-in broker logs while the workspace is starting - -:context: {parent-context-of-viewing-plug-in-broker-logs} diff --git a/modules/administration-guide/partials/proc_viewing-postgresql-server-logs.adoc b/modules/administration-guide/partials/proc_viewing-postgresql-server-logs.adoc deleted file mode 100644 index 66d879aab2..0000000000 --- a/modules/administration-guide/partials/proc_viewing-postgresql-server-logs.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// viewing-external-service-logs - -pass:[<!-- vale Vale.Spelling = NO -->] - -pass:[<!-- vale Vale.Terms = NO -->] - -[id="viewing-postgresql-server-logs_{context}"] -= Viewing the {prod-short} database logs - -pass:[<!-- vale Vale.Spelling = YES -->] - -pass:[<!-- vale Vale.Terms = YES -->] - -This section describes how to view the database logs in {prod-short}, such as PostgreSQL server logs. - -.Procedure - -. In the OpenShift Web Console, click *Deployments*. - -. In the *Find by label* search field, type: - ** `app=che` and press kbd:[Enter] - ** `component=postgres` and press kbd:[Enter] -+ -The OpenShift Web Console is searching base on those two keys and displays PostgreSQL logs. - -. Click *`postgres`* deployment to open it. - -. Click the *View log* link for the active PostgreSQL deployment. -+ -The OpenShift Web Console displays the database logs. - -.Additional resources - -* Some diagnostics or error messages related to the PostgreSQL server can be found in the active {prod-short} deployment log. For details to access the active {prod-short} deployments logs, see the xref:viewing-che-server-logs.adoc[] section. diff --git a/modules/administration-guide/partials/proc_viewing-the-state-of-the-che-cluster-deployment-using-openshift-4-cli-tools.adoc b/modules/administration-guide/partials/proc_viewing-the-state-of-the-che-cluster-deployment-using-openshift-4-cli-tools.adoc deleted file mode 100644 index 4830682eb3..0000000000 --- a/modules/administration-guide/partials/proc_viewing-the-state-of-the-che-cluster-deployment-using-openshift-4-cli-tools.adoc +++ /dev/null @@ -1,56 +0,0 @@ - -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-openshift-4-from-operatorhub - -[id="viewing-the-state-of-the-{prod-id-short}-cluster-deployment-using-openshift-4-cli-tools_{context}"] -= Viewing the state of the {prod-short} cluster deployment using OpenShift 4 CLI tools - -This section describes how to view the state of the {prod-short} cluster deployment using OpenShift 4 CLI tools. - -.Prerequisites - -* An instance of {prod} running on OpenShift. -* An installation of the OpenShift command-line tool, `oc`. - - -.Procedure - -. Run the following commands to select the `{project-context}` project: -+ -[subs="+quotes"] ----- -$ oc project _<project_name>_ ----- - -. Run the following commands to get the name and status of the Pods running in the selected project: -+ ----- -$ oc get pods ----- - -. Check that the status of all the Pods is `Running`. -+ -.Pods with status `Running` -==== -[subs="+attributes",options="nowrap",role=white-space-pre] ----- -NAME READY STATUS RESTARTS AGE -{prod-deployment}-8495f4946b-jrzdc 0/1 Running 0 86s -{prod-operator}-578765d954-99szc 1/1 Running 0 42m -keycloak-74fbfb9654-g9vp5 1/1 Running 0 4m32s -postgres-5d579c6847-w6wx5 1/1 Running 0 5m14s ----- -==== - -. To see the state of the {prod-short} cluster deployment, run: -+ -[subs="+attributes",options="nowrap",role=white-space-pre] ----- -$ oc logs --tail=10 -f `(oc get pods -o name | grep operator)` ----- -+ -.Logs of the Operator: -==== -include::example$snip_{project-context}-cluster-deployment-openshift-logs.adoc[] -==== diff --git a/modules/administration-guide/partials/proc_workspaces-requirements.adoc b/modules/administration-guide/partials/proc_workspaces-requirements.adoc index 55fbd7c479..226c322018 100644 --- a/modules/administration-guide/partials/proc_workspaces-requirements.adoc +++ b/modules/administration-guide/partials/proc_workspaces-requirements.adoc @@ -3,157 +3,18 @@ [id="workspaces-requirements_{context}"] = Workspaces requirements -This section describes how to calculate the resources required for a workspace. It is the sum of the resources required for each component of this workspace. - -These examples demonstrate the necessity of a proper calculation: - -* A workspace with ten active plug-ins requires more resources than the same workspace with fewer plug-ins. -* A standard Java workspace requires more resources than a standard Node.js workspace because running builds, tests, and application debugging requires more resources. +This section describes how to calculate the resources required for a workspace. That is the sum of the resources required for each container of the workspace. .Procedure -. Identify the workspace components explicitly specified in the `components` section of the xref:end-user-guide:authoring-devfiles-version-2.adoc[]. - -. Identify the implicit workspace components: -+ -.. {prod-short} implicitly loads the default `cheEditor`: `che-theia`, and the `chePlugin` that allows commands execution: `che-machine-exec-plugin`. To change the default editor, add a `cheEditor` component section in the devfile. - -.. The JWT Proxy component is responsible for the authentication and authorization of the external communications of the workspace components. - -. Calculate the requirements for each component: -+ -.. Default values: -+ -The following table displays the default requirements for all workspace components, and the corresponding {prod-short} server properties. Use the {prod-short} server properties to modify the defaults cluster-wide. -+ -[cols="3,2,1,1", options="header"] -.Default requirements of workspace components by type -|=== -|Component types -|{prod-short} server property -|Default memory limit -|Default memory request - -|`chePlugin` -|`che.workspace.sidecar.default_memory_limit_mb` -|128 MiB -|64 MiB - -|`cheEditor` -|`che.workspace.sidecar.default_memory_limit_mb` -|128 MiB -|64 MiB - - -|`kubernetes`, `openshift`, `dockerimage` -|`che.workspace.default_memory_limit_mb`, `che.workspace.default_memory_request_mb` -|1 Gi -|200 MiB - -|`JWT Proxy` -|`che.server.secure_exposer.jwtproxy.memory_limit`, `che.server.secure_exposer.jwtproxy.memory_request` -|128 MiB -|15 MiB -|=== - -.. Custom requirements for `chePlugins` and `cheEditors` components: -+ -... Custom memory limit and request: -+ -Define the `memoryLimit` and `memoryRequest` attributes of the `containers` section of the `meta.yaml` file to configure the memory limit of the `chePlugins` or `cheEditors` components. {prod-short} automatically sets the memory request to match the memory limit if it is not specified explicitly. -+ -.The `chePlugin` `che-incubator/typescript/latest` -==== -.`meta.yaml` spec section: -[source,yaml] ----- -spec: - containers: - - image: docker.io/eclipse/che-remote-plugin-node:next - name: vscode-typescript - memoryLimit: 512Mi - memoryRequest: 256Mi ----- - -This results in a container with the following memory limit and request: +. Identify the workspace components explicitly specified in the `components` section of the devfile. -|=== -|Memory limit | 512 MiB -|Memory request | 256 MiB -|=== -==== -+ -include::example$snip_{project-context}-memory-requirement-note.adoc[] -+ -[NOTE] -==== -.How to find the `meta.yaml` file of `chePlugin` +. Identify the implicit workspace components. -Community plug-ins are available in the link:https://github.com/eclipse-che/che-plugin-registry[{prod-short} plug-ins registry repository] in folder `v3/plugins/$\{organization}/$\{name}/$\{version}/`. +NOTE: {prod-short} implicitly loads the default `theia-ide`, `che-machine-exec`, `che-gateway` containers. -For non-community or customized plug-ins, the `meta.yaml` files are available on the local {platforms-name} cluster at `$\{pluginRegistryEndpoint}/v3/plugins/$\{organization}/$\{name}/$\{version}/meta.yaml`. - -ifeval::["{project-context}" == "che"] -For example, on a local Minikube cluster, the URL for the `che-incubator/typescript/latest meta.yaml` is `+http://plugin-registry-che.192.168.64.78.nip.io/v3/plugins/che-incubator/typescript/latest/meta.yaml+`. -endif::[] -==== - -... Custom CPU limit and request: -+ -{prod-short} does not set CPU limits and requests by default. However, it is possible to configure CPU limits -for the `chePlugin` and `cheEditor` types in the `meta.yaml` file or in the devfile in the same way as it done for memory limits. -+ -.The `chePlugin` `che-incubator/typescript/latest` -==== -.`meta.yaml` spec section: -[source,yaml] ----- -spec: - containers: - - image: docker.io/eclipse/che-remote-plugin-node:next - name: vscode-typescript - cpuLimit: 2000m - cpuRequest: 500m ----- - -It results in a container with the following CPU limit and request: - -|=== -|CPU limit | 2 cores -|CPU request | 0.5 cores -|=== -==== - -To set CPU limits and requests globally, use the following dedicated environment variables: -|=== -| `CPU Limit` | `+CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__LIMIT__CORES+` -| `CPU Request` | `+CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__REQUEST__CORES+` -|=== - -See also xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[]. - -Note that the `LimitRange` object of the {platforms-namespace} may specify defaults for CPU limits and requests set by cluster administrators. To prevent start errors due to resources overrun, limits on application or workspace levels must comply with those settings. - - -.. Custom requirements for `dockerimage` components -+ -Define the `memoryLimit` and `memoryRequest` attributes of the devfile to configure the memory limit of a `dockerimage` container. {prod-short} automatically sets the memory request to match the memory limit if it is not specified explicitly. -+ -[source,yaml] ----- - - alias: maven - type: dockerimage - image: eclipse/maven-jdk8:latest - memoryLimit: 1536M ----- - -.. Custom requirements for `kubernetes` or `openshift` components: -+ -The referenced manifest may define the memory requirements and limits. - -. Add all previously calculated requirements. +. Calculate the requirements for each component. .Additional resources -* xref:administration-guide:che-workspaces-architecture-with-che-server.adoc[]. - +* xref:architecture-overview.adoc[]. diff --git a/modules/installation-guide/partials/ref_che-server-component-system-properties-reference.adoc b/modules/administration-guide/partials/ref_che-server-component-system-properties-reference.adoc similarity index 100% rename from modules/installation-guide/partials/ref_che-server-component-system-properties-reference.adoc rename to modules/administration-guide/partials/ref_che-server-component-system-properties-reference.adoc diff --git a/modules/administration-guide/partials/ref_che-tracing-codebase-overview-and-extension-guide.adoc b/modules/administration-guide/partials/ref_che-tracing-codebase-overview-and-extension-guide.adoc deleted file mode 100644 index 44c7ecc9fd..0000000000 --- a/modules/administration-guide/partials/ref_che-tracing-codebase-overview-and-extension-guide.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// tracing-{prod-id-short} - -[id="{prod-id-short}-tracing-codebase-overview-and-extension-guide_{context}"] -= {prod-short} tracing codebase overview and extension guide - -The core of the tracing implementation for {prod-short} is in the `che-core-tracing-core` and `che-core-tracing-web` modules. - -All HTTP requests to the tracing API have their own trace. This is done by `TracingFilter` from the link:https://github.com/opentracing-contrib/java-web-servlet-filter[OpenTracing library], which is bound for the whole server application. Adding a `@Traced` annotation to methods causes the `TracingInterceptor` to add tracing spans for them. - -== Tagging - -Spans may contain standard tags, such as operation name, span origin, error, and other tags that may help users with querying and filtering spans. Workspace-related operations (such as starting or stopping workspaces) have additional tags, including `userId`, `workspaceID`, and `stackId`. Spans created by `TracingFilter` also have an HTTP status code tag. - -Declaring tags in a traced method is done statically by setting fields from the `TracingTags` class: - -[source,java,subs="+quotes"] ----- -TracingTags.WORKSPACE_ID.set(workspace.getId()); ----- - -`TracingTags` is a class where all commonly used tags are declared, as respective `AnnotationAware` tag implementations. - -.Additional resources - -For more information about how to use Jaeger UI, visit Jaeger documentation: link:https://www.jaegertracing.io/docs/1.12/getting-started/[Jaeger Getting Started Guide]. diff --git a/modules/administration-guide/partials/ref_devworkspace-specific-metrics.adoc b/modules/administration-guide/partials/ref_devworkspace-specific-metrics.adoc new file mode 100644 index 0000000000..0170c24c81 --- /dev/null +++ b/modules/administration-guide/partials/ref_devworkspace-specific-metrics.adoc @@ -0,0 +1,33 @@ +[id="ref_devworkspace-specific-metrics_{context}"] += {devworkspace}-specific metrics + +[role="_abstract"] +This section describes the {devworkspace}-specific metrics exposed by the `devworkspace-controller-metrics` service. + +.Metrics +,=== + Name, Type, Description, Labels + + `devworkspace_started_total`,"Counter","Number of {devworkspace} starting events.", "`source`, `routingclass`" + `devworkspace_started_success_total`,"Counter","Number of {devworkspace}s successfully entering the `Running` phase.", "`source`, `routingclass`" + `devworkspace_fail_total`,"Counter","Number of failed {devworkspace}s.", "`source`, `reason`" + `devworkspace_startup_time`,"Histogram","Total time taken to start a {devworkspace}, in seconds.", "`source`, `routingclass`" +,=== + +.Labels +,=== + Name, Description, Values + + `source`,"The `controller.devfile.io/devworkspace-source` label of the {devworkspace}.",`string` + `routingclass`,"The `spec.routingclass` of the {devworkspace}.",`"basic|cluster|cluster-tls|web-terminal"` + `reason`,"The workspace startup failure reason.",`"BadRequest|InfrastructureFailure|Unknown"` +,=== + +.Startup failure reasons +,=== + Name, Description + + `BadRequest`,"Startup failure due to an invalid devfile used to create a {devworkspace}." + `InfrastructureFailure`,"Startup failure due to the following errors: `CreateContainerError`, `RunContainerError`, `FailedScheduling`, `FailedMount`." + `Unknown`,"Unknown failure reason." +,=== diff --git a/modules/administration-guide/partials/ref_managesystem-permission.adoc b/modules/administration-guide/partials/ref_managesystem-permission.adoc deleted file mode 100644 index efc4cb8ba1..0000000000 --- a/modules/administration-guide/partials/ref_managesystem-permission.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// authorizing-users - -[id="managesystem-permission_{context}"] -= manageSystem permission - -Users with the *manageSystem* permission have access to the following services: - -[options="header"] -|==== -|Path|HTTP Method|Description -|`/resource/free/`|GET|Get free resource limits. -|`/resource/free/\{accountId}`|GET|Get free resource limits for the given account. -|`/resource/free/\{accountId}`|POST|Edit free resource limit for the given account. -|`/resource/free/\{accountId}`|DELETE|Remove free resource limit for the given account. -|`/installer/`|POST|Add installer to the registry. -|`/installer/\{key}`|PUT|Update installer in the registry. -|`/installer/\{key}`|DELETE|Remove installer from the registry. -|`/logger/`|GET|Get logging configurations in the {prod-short} server. -|`/logger/\{name}`|GET|Get configurations of logger by its name in the {prod-short} server. -|`/logger/\{name}`|PUT|Create logger in the {prod-short} server. -|`/logger/\{name}`|POST|Edit logger in the {prod-short} server. -|`/resource/\{accountId}/details`|GET|Get detailed information about resources for the given account. -|`/system/stop`|POST|Shutdown all system services, prepare {prod-short} to stop. -|==== diff --git a/modules/administration-guide/partials/ref_monitorsystem-permission.adoc b/modules/administration-guide/partials/ref_monitorsystem-permission.adoc deleted file mode 100644 index 4f890dd955..0000000000 --- a/modules/administration-guide/partials/ref_monitorsystem-permission.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// authorizing-users - -[id="monitorsystem-permission_{context}"] -= monitorSystem permission - -Users with the *monitorSystem* permission have access to the following services. - -[options="header"] -|==== -|Path|HTTP Method|Description -|/activity|GET|Get workspaces in a certain state for a certain amount of time. -|==== diff --git a/modules/installation-guide/partials/ref_understanding-the-registries.adoc b/modules/administration-guide/partials/ref_understanding-the-registries.adoc similarity index 82% rename from modules/installation-guide/partials/ref_understanding-the-registries.adoc rename to modules/administration-guide/partials/ref_understanding-the-registries.adoc index 3ac4a75841..3497a7726e 100644 --- a/modules/installation-guide/partials/ref_understanding-the-registries.adoc +++ b/modules/administration-guide/partials/ref_understanding-the-registries.adoc @@ -1,12 +1,12 @@ [id="understanding-the-{prod-id-short}-registries_{context}"] = Understanding the {prod-short} registries -{prod-short} uses two registries: the plug-ins registry and the devfile registry. They are static websites publishing the metadata of {prod-short} plug-ins and devfiles. When built in offline mode they also include artifacts. +{prod-short} uses two registries: the plug-ins registry and the devfile registry. They are static websites publishing the metadata of {prod-short} plug-ins and devfiles. When built-in offline mode they also include artifacts. The devfile and plug-in registries run in two separate Pods. Their deployment is part of the {prod-short} installation. .The devfile and plug-in registries -The devfile registry:: The devfile registry holds the definitions of the {prod-short} stacks. Stacks are available on the {prod-short} user dashboard when selecting *Create Workspace*. It contains the list of {prod-short} technological stack samples with example projects. When built in offline mode it also contains all sample projects referenced in devfiles as `zip` files. +The devfile registry:: The devfile registry holds the definitions of the {prod-short} stacks. Stacks are available on the {prod-short} user dashboard when selecting *Create Workspace*. It contains the list of {prod-short} technological stack samples with example projects. When built-in offline mode it also contains all sample projects referenced in devfiles as `zip` files. -The plug-in registry:: The plug-in registry makes it possible to share a plug-in definition across all the users of the same instance of {prod-short}. When built in offline mode it also contains all plug-in or extension artifacts. +The plug-in registry:: The plug-in registry makes it possible to share a plug-in definition across all the users of the same instance of {prod-short}. When built-in offline mode it also contains all plug-in or extension artifacts. diff --git a/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc deleted file mode 100644 index 8f23f8bcd0..0000000000 --- a/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[NOTE] -==== -* {prod} Operator can automatically configure a backup server inside the same cluster; however, it is not recommended for production use. - -* Users who agreed to the limitations coming from the decision to back up their data inside the same {platforms-namespace} as {prod-short} installation may skip this section. -==== diff --git a/modules/installation-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc b/modules/administration-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc similarity index 100% rename from modules/installation-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc rename to modules/administration-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc diff --git a/modules/contributor-guide/attachments/.placeholder b/modules/contributor-guide/attachments/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/contributor-guide/examples/.placeholder b/modules/contributor-guide/examples/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/contributor-guide/images/.placeholder b/modules/contributor-guide/images/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/contributor-guide/images/extensibility/building-plug-in-using-yarn.png b/modules/contributor-guide/images/extensibility/building-plug-in-using-yarn.png deleted file mode 100644 index f8f4bfe62e..0000000000 Binary files a/modules/contributor-guide/images/extensibility/building-plug-in-using-yarn.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/che-theia-hosted-mode.png b/modules/contributor-guide/images/extensibility/che-theia-hosted-mode.png deleted file mode 100644 index 2bd7c727b0..0000000000 Binary files a/modules/contributor-guide/images/extensibility/che-theia-hosted-mode.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/code-completion-example.gif b/modules/contributor-guide/images/extensibility/code-completion-example.gif deleted file mode 100644 index dc5d257649..0000000000 Binary files a/modules/contributor-guide/images/extensibility/code-completion-example.gif and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/controlling-hosted-che-theia.png b/modules/contributor-guide/images/extensibility/controlling-hosted-che-theia.png deleted file mode 100644 index 8e91c6a986..0000000000 Binary files a/modules/contributor-guide/images/extensibility/controlling-hosted-che-theia.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/debugging-plug-ins.gif b/modules/contributor-guide/images/extensibility/debugging-plug-ins.gif deleted file mode 100644 index 1c0a23f5ed..0000000000 Binary files a/modules/contributor-guide/images/extensibility/debugging-plug-ins.gif and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/hosted-instance-output.png b/modules/contributor-guide/images/extensibility/hosted-instance-output.png deleted file mode 100644 index 800665ed51..0000000000 Binary files a/modules/contributor-guide/images/extensibility/hosted-instance-output.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/launching-console-plug-in-generator.png b/modules/contributor-guide/images/extensibility/launching-console-plug-in-generator.png deleted file mode 100644 index e706a5d0d3..0000000000 Binary files a/modules/contributor-guide/images/extensibility/launching-console-plug-in-generator.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/launching-yeoman-wizard.png b/modules/contributor-guide/images/extensibility/launching-yeoman-wizard.png deleted file mode 100644 index 2a238a237e..0000000000 Binary files a/modules/contributor-guide/images/extensibility/launching-yeoman-wizard.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/open-terminal-in-container.png b/modules/contributor-guide/images/extensibility/open-terminal-in-container.png deleted file mode 100644 index 54fb608e94..0000000000 Binary files a/modules/contributor-guide/images/extensibility/open-terminal-in-container.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/running-plug-in-hosted-mode.gif b/modules/contributor-guide/images/extensibility/running-plug-in-hosted-mode.gif deleted file mode 100644 index eee96cedcb..0000000000 Binary files a/modules/contributor-guide/images/extensibility/running-plug-in-hosted-mode.gif and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/watching-hosted-plug-in.png b/modules/contributor-guide/images/extensibility/watching-hosted-plug-in.png deleted file mode 100644 index 37b7ae4d89..0000000000 Binary files a/modules/contributor-guide/images/extensibility/watching-hosted-plug-in.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/yeoman-successful.png b/modules/contributor-guide/images/extensibility/yeoman-successful.png deleted file mode 100644 index 9034f788b5..0000000000 Binary files a/modules/contributor-guide/images/extensibility/yeoman-successful.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-name.png b/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-name.png deleted file mode 100644 index a428bb93c2..0000000000 Binary files a/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-name.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-sample.png b/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-sample.png deleted file mode 100644 index 10c2bab9b4..0000000000 Binary files a/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-sample.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-type.png b/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-type.png deleted file mode 100644 index bd0466eb6d..0000000000 Binary files a/modules/contributor-guide/images/extensibility/yeoman-wizard-choosing-plug-in-type.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/yeoman-wizard-launching.png b/modules/contributor-guide/images/extensibility/yeoman-wizard-launching.png deleted file mode 100644 index 7c692c5226..0000000000 Binary files a/modules/contributor-guide/images/extensibility/yeoman-wizard-launching.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/yeoman-wizard-logs.png b/modules/contributor-guide/images/extensibility/yeoman-wizard-logs.png deleted file mode 100644 index b6045f4c0d..0000000000 Binary files a/modules/contributor-guide/images/extensibility/yeoman-wizard-logs.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/yeoman-wizard-plug-in-generated.png b/modules/contributor-guide/images/extensibility/yeoman-wizard-plug-in-generated.png deleted file mode 100644 index 65bd2e09f6..0000000000 Binary files a/modules/contributor-guide/images/extensibility/yeoman-wizard-plug-in-generated.png and /dev/null differ diff --git a/modules/contributor-guide/images/extensibility/yo-select-plug-in-generator.png b/modules/contributor-guide/images/extensibility/yo-select-plug-in-generator.png deleted file mode 100644 index 4564a763ea..0000000000 Binary files a/modules/contributor-guide/images/extensibility/yo-select-plug-in-generator.png and /dev/null differ diff --git a/modules/contributor-guide/nav.adoc b/modules/contributor-guide/nav.adoc deleted file mode 100644 index 82900b48f7..0000000000 --- a/modules/contributor-guide/nav.adoc +++ /dev/null @@ -1,13 +0,0 @@ -.Contributor Guide - -* xref:branding-che-theia.adoc[] -* xref:developing-che-theia-plug-ins.adoc[] -* xref:testing-che-theia-plug-ins.adoc[] -* xref:publishing-che-theia-plug-ins.adoc[] -* xref:adding-support-for-a-new-language.adoc[] -* xref:adding-support-for-a-new-debugger.adoc[] -* xref:che-extensibility-reference.adoc[] -** xref:che-extension-points.adoc[] -** xref:che-theia-plug-in-api.adoc[] -** xref:debug-adapter-protocol.adoc[] -** xref:language-server-protocol.adoc[] diff --git a/modules/contributor-guide/pages/.placeholder b/modules/contributor-guide/pages/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/contributor-guide/pages/adding-support-for-a-new-debugger.adoc b/modules/contributor-guide/pages/adding-support-for-a-new-debugger.adoc deleted file mode 100644 index e916c3353e..0000000000 --- a/modules/contributor-guide/pages/adding-support-for-a-new-debugger.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="adding-support-for-a-new-debugger"] -// = Adding support for a new debugger -:navtitle: Adding support for a new debugger -:keywords: contributor-guide, adding-support-for-a-new-debugger -:page-aliases: .:adding-support-for-a-new-debugger - -include::partial$proc_adding-support-for-a-new-debugger.adoc[] diff --git a/modules/contributor-guide/pages/adding-support-for-a-new-language.adoc b/modules/contributor-guide/pages/adding-support-for-a-new-language.adoc deleted file mode 100644 index 4020b65c10..0000000000 --- a/modules/contributor-guide/pages/adding-support-for-a-new-language.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="adding-support-for-a-new-language"] -// = Adding support for a new language -:navtitle: Adding support for a new language -:keywords: contributor-guide, adding-support-for-a-new-language -:page-aliases: .:adding-support-for-a-new-language - -include::partial$proc_adding-support-for-a-new-language.adoc[] diff --git a/modules/contributor-guide/pages/branding-che-theia.adoc b/modules/contributor-guide/pages/branding-che-theia.adoc deleted file mode 100644 index 2c99dee4f2..0000000000 --- a/modules/contributor-guide/pages/branding-che-theia.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="branding-che-theia"] -// = Branding Che-Theia -:navtitle: Branding Che-Theia -:keywords: contributor-guide, branding-che-theia -:page-aliases: .:branding-che-theia - -include::partial$assembly_branding-che-theia.adoc[] diff --git a/modules/contributor-guide/pages/che-extensibility-reference.adoc b/modules/contributor-guide/pages/che-extensibility-reference.adoc deleted file mode 100644 index d592a4591b..0000000000 --- a/modules/contributor-guide/pages/che-extensibility-reference.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-extensibility-reference"] -// = Che extensibility reference -:navtitle: Che extensibility reference -:keywords: contributor-guide, che-extensibility-reference -:page-aliases: .:che-extensibility-reference - -include::partial$assembly_che-extensibility-reference.adoc[] diff --git a/modules/contributor-guide/pages/che-extension-points.adoc b/modules/contributor-guide/pages/che-extension-points.adoc deleted file mode 100644 index 31915e7b90..0000000000 --- a/modules/contributor-guide/pages/che-extension-points.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-extension-points"] -// = Che extension points -:navtitle: Che extension points -:keywords: contributor-guide, che-extension-points -:page-aliases: .:che-extension-points - -include::partial$con_che-extension-points.adoc[] diff --git a/modules/contributor-guide/pages/che-theia-plug-in-api.adoc b/modules/contributor-guide/pages/che-theia-plug-in-api.adoc deleted file mode 100644 index d6904bd311..0000000000 --- a/modules/contributor-guide/pages/che-theia-plug-in-api.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-theia-plug-in-api"] -// = Che-Theia plug-in API -:navtitle: Che-Theia plug-in API -:keywords: contributor-guide, che-theia-plug-in-api -:page-aliases: .:che-theia-plug-in-api - -include::partial$ref_che-theia-plug-in-api.adoc[] diff --git a/modules/contributor-guide/pages/debug-adapter-protocol.adoc b/modules/contributor-guide/pages/debug-adapter-protocol.adoc deleted file mode 100644 index e16c3d6f1b..0000000000 --- a/modules/contributor-guide/pages/debug-adapter-protocol.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="debug-adapter-protocol"] -// = Debug Adapter Protocol -:navtitle: Debug Adapter Protocol -:keywords: contributor-guide, debug-adapter-protocol -:page-aliases: .:debug-adapter-protocol - -include::partial$ref_debug-adapter-protocol.adoc[] diff --git a/modules/contributor-guide/pages/developing-che-theia-plug-ins.adoc b/modules/contributor-guide/pages/developing-che-theia-plug-ins.adoc deleted file mode 100644 index 22f182406b..0000000000 --- a/modules/contributor-guide/pages/developing-che-theia-plug-ins.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="developing-che-theia-plug-ins"] -// = Developing Che-Theia plug-ins -:navtitle: Developing Che-Theia plug-ins -:keywords: contributor-guide, developing-che-theia-plug-ins -:page-aliases: .:developing-che-theia-plug-ins - -include::partial$assembly_developing-che-theia-plug-ins.adoc[] diff --git a/modules/contributor-guide/pages/language-server-protocol.adoc b/modules/contributor-guide/pages/language-server-protocol.adoc deleted file mode 100644 index ce8105580d..0000000000 --- a/modules/contributor-guide/pages/language-server-protocol.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="language-server-protocol"] -// = Language Server Protocol -:navtitle: Language Server Protocol -:keywords: contributor-guide, language-server-protocol -:page-aliases: .:language-server-protocol - -include::partial$ref_language-server-protocol.adoc[] diff --git a/modules/contributor-guide/pages/publishing-che-theia-plug-ins.adoc b/modules/contributor-guide/pages/publishing-che-theia-plug-ins.adoc deleted file mode 100644 index 6b71610563..0000000000 --- a/modules/contributor-guide/pages/publishing-che-theia-plug-ins.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="publishing-che-theia-plug-ins"] -// = Publishing Che-Theia plug-ins -:navtitle: Publishing Che-Theia plug-ins -:keywords: contributor-guide, publishing-che-theia-plug-ins -:page-aliases: .:publishing-che-theia-plug-ins - -include::partial$assembly_publishing-che-theia-plug-ins.adoc[] diff --git a/modules/contributor-guide/pages/testing-che-theia-plug-ins.adoc b/modules/contributor-guide/pages/testing-che-theia-plug-ins.adoc deleted file mode 100644 index 2bd65d8b15..0000000000 --- a/modules/contributor-guide/pages/testing-che-theia-plug-ins.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="testing-che-theia-plug-ins"] -// = Testing Che-Theia plug-ins -:navtitle: Testing Che-Theia plug-ins -:keywords: contributor-guide, testing-che-theia-plug-ins -:page-aliases: .:testing-che-theia-plug-ins - -include::partial$assembly_testing-che-theia-plug-ins.adoc[] diff --git a/modules/contributor-guide/partials/.placeholder b/modules/contributor-guide/partials/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/contributor-guide/partials/assembly_che-extensibility-reference.adoc b/modules/contributor-guide/partials/assembly_che-extensibility-reference.adoc deleted file mode 100644 index f8b6d690ab..0000000000 --- a/modules/contributor-guide/partials/assembly_che-extensibility-reference.adoc +++ /dev/null @@ -1,17 +0,0 @@ - - -:parent-context-of-che-extensibility-reference: {context} - -[id="{prod-id-short}-extensibility-reference_{context}"] -= {prod-short} extensibility reference - -:context: {prod-id-short}-extensibility-reference - -This section contains reference material to extend the functions of {prod-short}. - -* xref:che-extension-points.adoc[] -* xref:che-theia-plug-in-api.adoc[] -* xref:debug-adapter-protocol.adoc[] -* xref:language-server-protocol.adoc[] - -:context: {parent-context-of-che-extensibility-reference} \ No newline at end of file diff --git a/modules/contributor-guide/partials/assembly_developing-che-theia-plug-ins.adoc b/modules/contributor-guide/partials/assembly_developing-che-theia-plug-ins.adoc deleted file mode 100644 index 7c5148ddfb..0000000000 --- a/modules/contributor-guide/partials/assembly_developing-che-theia-plug-ins.adoc +++ /dev/null @@ -1,16 +0,0 @@ - - -:parent-context-of-developing-che-theia-plug-ins: {context} - -[id="developing-che-theia-plug-ins_{context}"] -= Developing Che-Theia plug-ins - -:context: developing-che-theia-plug-ins - -// include::partial$con_che-theia-plug-in-development-flow.adoc[leveloffset=+1] - -include::partial$proc_bootstrapping-che-theia-plug-in-development-with-yeoman.adoc[leveloffset=+1] - -include::partial$proc_developing-che-theia-plug-ins-using-che.adoc[leveloffset=+1] - -:context: {parent-context-of-developing-che-theia-plug-ins} diff --git a/modules/contributor-guide/partials/assembly_publishing-che-theia-plug-ins.adoc b/modules/contributor-guide/partials/assembly_publishing-che-theia-plug-ins.adoc deleted file mode 100644 index fff833b83e..0000000000 --- a/modules/contributor-guide/partials/assembly_publishing-che-theia-plug-ins.adoc +++ /dev/null @@ -1,18 +0,0 @@ - - -:parent-context-of-publishing-che-theia-plug-ins: {context} - -[id="publishing-che-theia-plug-ins_{context}"] -= Publishing Che-Theia plug-ins - -:context: publishing-che-theia-plug-ins - -include::partial$con_che-theia-plug-in-registries.adoc[leveloffset=+1] - -include::partial$proc_adding-a-che-theia-plug-in-to-the-che-plug-in-registry.adoc[leveloffset=+1] - -include::partial$proc_adding-a-che-theia-plug-in-into-a-workspace.adoc[leveloffset=+1] - -include::partial$proc_overriding-ram-of-a-che-theia-plug-in.adoc[leveloffset=+1] - -:context: {parent-context-of-publishing-che-theia-plug-ins} diff --git a/modules/contributor-guide/partials/assembly_testing-che-theia-plug-ins.adoc b/modules/contributor-guide/partials/assembly_testing-che-theia-plug-ins.adoc deleted file mode 100644 index 3eb98c4b30..0000000000 --- a/modules/contributor-guide/partials/assembly_testing-che-theia-plug-ins.adoc +++ /dev/null @@ -1,55 +0,0 @@ - - -:parent-context-of-testing-che-theia-plug-ins: {context} - -[id="testing-che-theia-plug-ins_{context}"] -= Testing Che-Theia plug-ins - -:context: testing-che-theia-plug-ins - -Developers can test how plug-ins work while working on them by running Che-Theia in the hosted mode. It is a special mode in which Che-Theia loads your plug-in directly from the `/projects` directory (as opposed to the rest of the plug-ins, which are loaded from the plug-in registry). The Che-Theia hosted mode is similar to the debug mode in VS Code. - -== Starting a hosted Che-Theia instance - -. Press F1 to display the command palette, and run the `Hosted Plugin: Start Instance` command. - -. Specify the path to the plug-in. A new browser tab is opened. - -.Status in the hosted instance - -When running in the hosted mode, Che-Theia displays a *Development Host* message in the status bar. When you hover your mouse over the message, a tip is displayed with the name of the hosted plug-in. - -image::extensibility/che-theia-hosted-mode.png[] - -.Status in the main instance -At the same time, the main instance of Che-Theia displays a *Hosted Plugin* message in the status bar. This element indicates the state of the hosted instance. After starting the hosted instance, main Che-Theia begins to watch the code changes. - -image::extensibility/watching-hosted-plug-in.png[] - -When you change something in your plug-in, you can switch to the hosted Che-Theia instance, refresh the page, and immediately see the results. - -.Plug-in output - -When you run a hosted instance, the main Che-Theia instance opens the *Output* view. This view contains all the output from the `yarn` back-end process. It also contains the output of the back-end plug-in that is being developed. - -image::extensibility/hosted-instance-output.png[link="../_images/extensibility/hosted-instance-output.png"] - -== Controlling a hosted Che-Theia instance - -You can control the state of the hosted instance directly from the main instance. Click *Hosted Plugin* element in the status bar, and a pop-up menu with the available actions is displayed. You can stop and restart the running hosted Che-Theia instance from the pop-up menu. When a hosted instance is stopped, use the pop-up menu to start it again. - -image::extensibility/controlling-hosted-che-theia.png[] - -== Using code completion - -Code completion feature helps you write your plug-in. Code completion covers both the `Che Editor` plug-in API and the `Che Plugin` plug-in API. - -.Code-completion example -[example] -==== -Your plug-in will handle the opening of a document and displaying a notification message when the document is opened. - -image:extensibility/code-completion-example.gif[link="../_images/extensibility/code-completion-example.gif"] -==== - -:context: {parent-context-of-testing-che-theia-plug-ins} diff --git a/modules/contributor-guide/partials/con_che-extension-points.adoc b/modules/contributor-guide/partials/con_che-extension-points.adoc deleted file mode 100644 index 07ba15b1e5..0000000000 --- a/modules/contributor-guide/partials/con_che-extension-points.adoc +++ /dev/null @@ -1,351 +0,0 @@ - - -:parent-context-of-che-extension-points: {context} - -[id="{prod-id-short}-extension-points_{context}"] -= {prod-short} extension points - -:context: {prod-id-short}-extension-points - -In addition to using API methods and events, each plug-in can bring new components into Che-Theia. These components include visual, such as panels, menus, and others. Other types of components are language servers, debuggers, and others. - -The mechanism for adding additional components into Che-Theia is called extension points. An extension point is a section in a Che-Theia plug-in configuration into which the meta-information about a new component is added. This chapter contains the full list of available extension points in Che-Theia. - - -[id="syntax-highlighting-grammars_{context}"] -== Syntax-highlighting grammars - -This section provides syntax highlight rules for specified file types. To add syntax highlighting into Che-Theia using a plug-in, add a record that describes the new grammar into the `contributes.grammars` array of the `package.json` file of the plug-in. - -.Example of a grammar record -[source,json] ----- -"grammars": [ - { - "language": "lang", <1> - "scopeName": "text.ext", <2> - "path": "./path/to/lang.tmLanguage.json" <3> - } -] ----- -<1> Specifies the target language for syntax highlighting. -<2> TextMate scope name and grammar. -<3> Syntax-highlighting rules. - -See link:https://macromates.com/manual/en/language_grammars[TextMate documentation] for more details about syntax-highlighting rules. A full example: link:https://github.com/eclipse/che-theia-samples/tree/master/samples/xml-language-server-plugin[xml-language-server-plugin]. - - -[id="preferences-configuration_{context}"] -== Preferences (configuration) - -A plug-in can introduce new *preferences*. These are defined in the `"configuration"` sub-object of the `"contribution"` object in the `package.json` file. A preference is contributed as a JSON schema that describes what is actually contributed and allows users to get support when editing settings in the *Preferences Editor*. - -.Example of configuration contribution for a plug-in preference that defines a logging level -[source,json] ----- -{ - "contributes": { - "configuration": { - "type": "object", - "title": "A plug-in configuration", - "properties": { - "myPlugin.logLevel": { - "type": "string", - "default": "error", - "description": "Plug-in logging level" - } - } - } - } -} ----- - -Che-Theia has three scopes of preferences: - -* The *default* scope consists of values defined in the `"configuration"` sub-section in the `package.json` file. These are default values of the preferences contributed by the plug-in. - -* The *global* or *application-wide* scope values can be set in *User Preferences*. They override the default ones. - -* The *workspace* scope values, which are applied only when a Che-Theia workspace is opened, override default and global values. They can be set in *Workspace Preferences*. - -A user can obtain preferences using `theia.workspace.getConfiguration(section)`. If a `section` is defined, only that subset of preferences is returned. - -.Example of preferences definition -[source,javascript] ----- -// all preferences contributed by a plug-in -theia.workspace.getConfiguration('myPlugin'); // { "logLevel": "error" } - -// or -theia.workspace.getConfiguration().get('myPlugin'); // { "logLevel": "error" } - -// or, `logLevel` value: -theia.workspace.getConfiguration().get('myPlugin').get('logLevel'); // "error" ----- - -The plug-in API also allows to update preferences: - -[source,javascript] ----- -const pluginPrefs = theia.workspace.getConfiguration('myPlugin'); -pluginPrefs.update('logLevel', 'debug', theia.ConfigurationTarget.User); ----- - -To get all information about a configuration setting, use the `inspect` method. The `inspect` method returns an object that consists of `default`, `global`, and `workspace` (if one exists) values of a preference key: - -[source,javascript] ----- -pluginPrefs.inspect('logLevel'); -// { -// "key": "myPlugin.logLevel", -// "defaultValue": "error", -// "globalValue": "debug" -// } ----- - - -[id="view-containers_{context}"] -== View containers - -A *view container* is a container that holds xref:views_{context}[views]. In Che-Theia, views are typically in the form of panels. All view containers are divided in three sections: *left*, *bottom*, and *right*. The position of a view container depends on the section to which it belongs. This defines the default position of a view container, which can be changed at runtime by dragging and dropping. - -To add a view container into Che-Theia, add the appropriate record into the `viewsContainers` object located under the `contributes` object in the plug-in `package.json` file: - -.Example of a view-container definition -[source,json] ----- -"contributes": { - "viewsContainers": { - "bottom": [ - { - "id": "view-container-id", <1> - "title": "The title" <2> - }, - { - "id": "another-view-container-id", - "title": "Some title" - } - ], - "right": [ - { - "id": "view-container-on-the-right-side-id", - "title": "Panel on the right" - } - ] - } -} ----- -<1> The identifier of the view container. Used to attach to this view container. -<2> Text displayed on the panel tab. - -Note that a view container is only useful with views in it. See a full example at link:https://github.com/eclipse/che-theia-samples/tree/master/samples/tree-view-sample-plugin[tree-view-sample-plugin]. - - -[id="views_{context}"] -== Views -A *view* is a visual component, designed be placed into a xref:view-containers_{context}[view container]. - -To add a view into Che-Theia, add an appropriate record into the `contributes.views` object of a plug-in `package.json` file. Each view is defined by an object with two name:value pairs. Additionally, each view description must be included in an array within the `views` object, with array name matching the `view-container-id` value: - -.Example of a view definition -[source,json] ----- -"viewsContainers": { - "left": [ - { - "id": "view-container-id", <1> - "title": "The title" <2> - } - ], -}, -"views": { - "view-container-id": [ - { - "id": "tree-at-left-side", - "name": "A list" - }, - { - "id": "widget-at-left-side", - "name": "A widget" - } - ] -} ----- -<1> View identifier -<2> Name of the view, which is displayed as the widget title inside the view container - -Currently, only tree view is supported as a view widget. - -For more details, see a full example at https://github.com/eclipse/che-theia-samples/tree/master/samples/tree-view-sample-plugin[tree-view-sample-plugin]. - - -[id="menus_{context}"] -== Menus - -Plug-ins can add new *menu items* into Che-Theia through the `contributes.menus` object in a plug-in `package.json` file. The `menus` object consists of menu names and menu items: - -.Example of a menu definition -[source,json] ----- -"menus": { - "editor/context": [ - { - "command": "my.command.id", <1> - "group": "custom.group", <2> - "when": "view == widget-at-left-side && config.namespace.property" <3> - }, - { - "command": "core.about" - } - ], - "explorer/context": [ - { - "command": "other.command.id", - "group": "some.group" - } - ] -} ----- -<1> The identifier of the Che-Theia command that is executed when the menu item is used. The handler receives the selected resource as the first argument. -<2> (optional) The name of the group in the menu to which the command is added. When omitted, the menu item is added to the common group in the specified menu. -<3> (optional) The condition that defines when this menu item is visible. When omitted, the menu item is always visible. The conditions are the same as in the link:https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[VS Code when clause]. - -Menus that support extending: - -* `explorer/context` -* `editor/context` -* `editor/title` -* `debug/callstack/context` -* `view/item/context` - -A plug-in example that adds menu items: link:https://github.com/eclipse/che-theia-samples/tree/master/samples/menus-contribution-plugin[menus-contribution-plugin]. - - -[id="key-bindings_{context}"] -== Key bindings - -Plug-ins can add new *keyboard shortcuts* or redefine existing ones. To describe a new shortcut, add a definition in the `contributes.keybindings` object of a plug-in `package.json` file. Each key bonding is described by three values: - -.Example of a keyboard-shortcut definition -[source,json] ----- -"keybindings": [ - { - "key": "ctrl+b", <1> - "command": "ts.compile", <2> - "when": "resourceExtname == .ts" <3> - }, - { - "key": "ctrl+f alt+b", - "command": "some.command" - } -] ----- -<1> Defines the key combination for this shortcut. link:https://code.visualstudio.com/docs/getstarted/keybindings#_keyboard-rules[Rules for defining key combinations] are the same as for VS Code. -<2> The identifier of the command invoked when the shortcut is pressed. -<3> (optional) The condition that defines when this shortcut is available. When omitted, the shortcut is always available. The condition format is the same as in the link:https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[VS Code when clause]. - -Note that kbd:[Ctrl+f] kbd:[Alt+b] defines a _chord_: the command is invoked after pressing both kbd:[Ctrl+f] and kbd:[Alt+b] one after the other. - - -[id="debuggers_{context}"] -== Debuggers - -Plug-ins can add new *debuggers* by implementing the link:https://microsoft.github.io/debug-adapter-protocol/[Debugger Adapter Protocol] (DAP) for a specific debugger. The debugger can then register in the `contributes.debuggers` debuggers of a plug-in `package.json` file. - - -See the link:https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/[list of debuggers] from the official DAP site for reference and examples. - - -[id="languages-language-servers_{context}"] -== Languages (language servers) - -NOTE: This is an experimental approach, which may change in the future. - -To add a language server into Che-Theia using a plug-in: - -. Describe the server in the `contributes.languages` array in the plug-in `package.json` file: -+ -.Example of a language-server definition -[source,json] ----- -"languages": [ - { - "id": "lang", <1> - "aliases": [ <2> - "Lang", - "LANG" - ], - "extensions": [ <3> - ".ext" - ], - "firstLine": "^#!/.*interpreter", <4> - "configuration": "./language-configuration.json" <5> - } -] ----- -<1> The ID of the language for which the language server is created. -<2> Other names for the language. -<3> File-name extensions for which this language server is added. -<4> `Hashbang` (first line) for which this language server is added. -<5> Path to a JSON file with the language configuration. See: link:https://code.visualstudio.com/api/language-extensions/language-configuration-guide[Language configurationn guide]. - -. Register the language server using the following API call: -+ -[source,typescript] ----- -theia.languageServer.registerLanguageServerProvider(xLanguageServerInfo); ----- -+ -Where `xLanguageServerInfo` is an object of `theia.LanguageServerInfo` and has to contain the following fields: -+ -|=== -| `id` | Language ID; it has to be the same as the `id` in the configuration JSON file -| `name` | Human-readable name of the language server -| `globPatterns` | File pattern that specifies files for which this language server is added -| `command` | The language server start executable -| `args` | Arguments for the language server start executable -|=== -+ -After the command above is invoked, the language server is started. - -See a full example at https://github.com/eclipse/che-theia-samples/tree/master/samples/xml-language-server-plugin[xml-language-server-plugin]. - - -[id="web-view-api_{context}"] -== Web view API - -A *web view API* is not a contribution point by definition, but it behaves like one and allows to bring many new features to Che-Theia. Web view API plug-ins can add custom UI, graphical data, or anything that can be displayed in a web page. A web view API provides an HTML `iframe` to which a plug-in has access. - -To create an instance of web view: - -. Use the `createWebviewPanel` function: -+ -[source,typescript] ----- -const webViewPanel = theia.window.createWebviewPanel('webViewId', 'Title', theia.ViewColumn.One); ----- - -. Add content: -+ -[source,typescript] ----- -webViewPanel.webview.html ='<html><body><h1>Hello from web view</h1></body></html>'; ----- - -[NOTE] -==== -Web view content is removed when hidden. To restore its state, register a serializer, or set the `retainContextWhenHidden` option for the web view. Even with this option set, hiding a web view pauses all scripts, and the web view will not process messages from the plug-in. - -The current state of a web view can be read from the web view panel object. - -It is possible to load resources and scripts into a web view and communicate with a plug-in by posting messages. See a full sample plug-in at link:https://github.com/eclipse/che-theia-samples/tree/master/samples/webview-sample-plugin[webview-sample-plugin] for more details. -==== - -// .Additional resources -// -// * A bulleted list of links to other material closely related to the contents of the concept module. -// * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. - -:context: {parent-context-of-che-extension-points} diff --git a/modules/contributor-guide/partials/con_che-theia-plug-in-registries.adoc b/modules/contributor-guide/partials/con_che-theia-plug-in-registries.adoc deleted file mode 100644 index 62fdc58731..0000000000 --- a/modules/contributor-guide/partials/con_che-theia-plug-in-registries.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// publishing-che-theia-plug-ins - -[id="che-theia-plug-in-registries_{context}"] -= Che-Theia plug-in registries - -A plug-in registry is a simple service that hosts metadata about the enabled plug-ins. - -To retrieve a full list of plug-ins hosted in a registry, navigate to the `<registry-base-uri>/v3/plugins/index.json` file. - -Each plug-in item in the list is represented by a JSON definition. - -.Sample plug-in definition -[source,json] ----- - { - "description": "This extension provides a live preview, syntax highlighting and snippets for the AsciiDoc format using Asciidoctor flavor.", - "displayName": "AsciiDoc support", - "id": "joaompinto/vscode-asciidoctor/latest", - "links": { - "self": "/v3/plugins/joaompinto/vscode-asciidoctor/latest/" - }, - "name": "vscode-asciidoctor", - "publisher": "joaompinto", - "type": "VS Code extension", - "version": "latest" - } ----- - -This definition contains a `links` section that points to the complete plug-in description (`meta.yaml`). - -.Sample plug-in `meta.yaml` file -[source,yaml] ----- -publisher: joaompinto -apiVersion: v2 -version: latest -type: VS Code extension -name: vscode-asciidoctor -displayName: AsciiDoc support -title: AsciiDoctor Plugin. -description: This extension provides a live preview, syntax highlighting, and snippets - for the AsciiDoc format using Asciidoctor flavor. -icon: https://www.eclipse.org/che/images/logo-eclipseche.svg -category: Language -repository: https://github.com/asciidoctor/asciidoctor-vscode -firstPublicationDate: '2019-09-09' -spec: - extensions: - - https://marketplace.visualstudio.com/_apis/public/gallery/publishers/joaompinto/vsextensions/asciidoctor-vscode/2.7.6/vspackage -latestUpdateDate: "2019-12-09" ----- - -For more details about the `meta.yaml` structure, see xref:end-user-guide:what-is-a-che-theia-plug-in.adoc#che-theia-plug-in-metadata_{context}[Che-Theia plug-in metadata]. - -[id="custom-plug-in-registries_{context}"] -== Custom plug-in registries - -For more information about setting up a custom registry, see the description of the link:https://github.com/eclipse-che/che-plugin-registry[official registry repository]. - -To use plug-ins from a custom registry, follow one of the following methods: - -* Specify a link to the plug-in in the configuration of a workspace. See xref:adding-a-plug-in-by-configuring-a-workspace_{context}[Adding a plug-in into a workspace using the workspace configuration]. - -* Replace the default official registry with a custom one in your {prod-short} instance. To do so, set the `PLUGIN_REGISTRY_IMAGE` environment variable in your {prod-short} configuration. Note that plug-ins from the official registry are not available from the dashboard interface. To include them, add references to your registry from the official registry. - -.Additional resources - -* xref:end-user-guide:what-is-a-che-theia-plug-in.adoc#che-theia-plug-in-metadata_{context}[Che-Theia plug-in metadata] diff --git a/modules/contributor-guide/partials/proc_adding-a-che-theia-plug-in-into-a-workspace.adoc b/modules/contributor-guide/partials/proc_adding-a-che-theia-plug-in-into-a-workspace.adoc deleted file mode 100644 index 977987d526..0000000000 --- a/modules/contributor-guide/partials/proc_adding-a-che-theia-plug-in-into-a-workspace.adoc +++ /dev/null @@ -1,107 +0,0 @@ -// Module included in the following assemblies: -// -// publishing-che-theia-plug-ins - -[id="adding-a-che-theia-plug-in-into-a-workspace_{context}"] -= Adding a Che-Theia plug-in into a workspace - -You can add Che-Theia plug-in into the Che-Theia IDE in three ways: - -* At Theia runtime -* By configuring a workspace devfile -* By preparing shareable devfile - -[id="adding-a-plug-in-at-runtime_{context}"] -== Adding a plug-in at Theia runtime - -This method adds a plug-in to an already running workspace. The plug-in is not added permanently; it is removed when the workspace stops. This is a good method to test a plug-in without affecting the permanent workspace configuration. - -.Procedure -* Run the `Deploy Plugin by Id` command, and specify the ID of the plug-in to add to the workspace. A plug-in ID can be: -+ -A local directory with plug-ins:: {prod-short} loads all the plug-in binaries (`.theia` files) in the specified directory. -+ -.Adding the local directory `/home/theia/plugins/` -==== ----- -local-dir:///home/theia/plugins/ ----- -==== -+ -VS Code extension link:: To obtain the link, go to the VS Code marketplace, find the needed extension, copy its ID, and append the ID to the `vscode:extension/` prefix. -+ -.VS Code extension link for the link:https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml[XML language server] plug-in -==== ----- -vscode:extension/redhat.vscode-xml ----- -==== -+ -Link to plug-in binaries (`.theia` files):: Can be both HTTP and HTTPS. -+ -.Link to plug-in binaries -==== ----- -https://domain.net/path/plugin.theia ----- -==== - -.Verification steps -* Open the *Plugins panel* (*View* > *Plugins* in the main menu) and search for the plug-in in the list. - -[id="adding-a-plug-in-by-configuring-a-workspace_{context}"] -== Adding a plug-in by configuring a workspace devfile - -This method is useful when you need to add plug-ins from a non-default registry. - -.Procedure - -. Navigate to the *Workspaces* tab in the dashboard. -. Select the plug-in destination workspace. -. Switch to the *Devfile* tab, and find the `components` section. -. To add plug-ins, append your plugin component to the `components` section. A record has the following format: -+ -[subs="+quotes,macros,attributes"] ----- -components: - - type: chePlugin - reference: >- - __<registry-base-uri>__/v3/plugins/__<plugin-publisher>__/__<plugin-name>__/__<plugin-version>__ ----- -+ -.`chePlugin` reference URLs pointing to a plug-in `meta.yaml` -==== ----- -https://custom-registry/v3/plugins/custom-plugin-name/0.0.1/ -https://raw.githubusercontent.com/username/che-custom-plugins/master/v3/plugins/custom-plugin-name/0.0.1/meta.yaml ----- -==== - -[id="adding-a-plug-in-by-shareable-devfile_{context}"] -== Adding a plug-in by preparing shareable devfile - -This approach brings an advantage of other users being able to contribute to the development, provided they have write access to the repository with the plug-in. - -.Procedure - -. Create a devfile with the plug-in development environment and share it with reviewers to provide them with the same environment. Reviewers then must build and run the plug-in to test it, using a script or a set of instructions on how to include the build in the plug-in repository. - -. Share with reviewers factory link with a URL to a repository with devfile or a direct URL to content of the devfile. -+ -.Factory URL pointing to a repository containing a devfile -==== -`pass:c,a,q[{prod-url}/#https://github.com/eclipse-che/che-server]` -==== -+ -.Factory URL pointing to a devfile -==== -`pass:c,a,q[{prod-url}/#https://raw.githubusercontent.com/eclipse/che/master/devfile.yaml]` -==== - -. The reviewer starts a workspace by opening a link where they are able to starts a hosted plug-in instance and specify the path to the plug-in project inside the workspace. For instructions on how to start a hosted instance of Che-Theia for plug-in testing, see xref:testing-che-theia-plug-ins.adoc[]. - -// .Additional resources -// -// * A bulleted list of links to other material closely related to the contents of the procedure module. -// * For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. diff --git a/modules/contributor-guide/partials/proc_adding-a-che-theia-plug-in-to-the-che-plug-in-registry.adoc b/modules/contributor-guide/partials/proc_adding-a-che-theia-plug-in-to-the-che-plug-in-registry.adoc deleted file mode 100644 index 1357d824dd..0000000000 --- a/modules/contributor-guide/partials/proc_adding-a-che-theia-plug-in-to-the-che-plug-in-registry.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// publishing-che-theia-plug-ins - -[id="adding-a-che-theia-plug-in-to-the-{prod-id-short}-plug-in-registry_{context}"] -= Adding a Che-Theia plug-in to the {prod-short} plug-in registry - -To have a Che-Theia plug-in available in the default {prod-short} plug-in registry, submit a pull request to the registry GitHub repository. - -.Prerequisites - -* Che-Theia plug-in definition file: `meta.yaml` - -.Procedure - -* Submit a pull request to link:{url-plug-in-registry-repo}[the plug-in registry repository] containing the `meta.yaml` file of the plug-in in the `v3/plugins/__<plugin-publisher>__/__<plugin-name>__/__<plugin-version>__/` directory. -+ -.Location of `meta.yaml` file for the SonarLint Che-Theia plug-in -==== ----- -v3/plugins/sonarsource/sonarlint-vscode/0.0.1/meta.yaml ----- -==== - -// TODO: Add a sample PR adding a plug-in to the registry. - -After the new Che-Theia plug-ins are added and merged into the repository, the list of available plug-ins in the registry is updated. - - -.Additional resources - -* link:https://github.com/eclipse-che/che-plugin-registry/[che-plugin-registry repository] diff --git a/modules/contributor-guide/partials/proc_adding-support-for-a-new-debugger.adoc b/modules/contributor-guide/partials/proc_adding-support-for-a-new-debugger.adoc deleted file mode 100644 index 785266a880..0000000000 --- a/modules/contributor-guide/partials/proc_adding-support-for-a-new-debugger.adoc +++ /dev/null @@ -1,33 +0,0 @@ - - - -[id="adding-support-for-a-new-debugger_{context}"] -= Adding support for a new debugger - -This section describes how to add a new debugger into {prod}. - -.Prerequisites - -* Install the latest Che-Theia plug-in Yeoman generator by running the following command: -+ ----- -$ npm install -g yo @theia/generator-plugin ----- - -.Procedure - -. Generate a sample by running the `yo @theia/plugin` command. When prompted, confirm the choices for *Backend plug-in*, *Samples*, and then *Debugger sample*. This creates a project and a ready-to-use plug-in, which can be deployed. - -. Replace the mock implementation of the debug adapter in the `src/vscode-mockDebug.ts` and `src/vscode-mockRuntime.ts` files with code that interacts with a real debugger or runtime. - -. Build the plug-in by running the `yarn` command in the root of the project. - -. Deploy the Che-Theia plug-in using the plug-in registry. - - -.Additional resources - -* link:https://microsoft.github.io/debug-adapter-protocol/[Debug Adapter Protocol] -* link:https://code.visualstudio.com/api/extension-guides/debugger-extension[VS Code debugger extension documentation] -* link:https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/[Implementations Debug Adapters] -* xref:publishing-che-theia-plug-ins.adoc[] diff --git a/modules/contributor-guide/partials/proc_adding-support-for-a-new-language.adoc b/modules/contributor-guide/partials/proc_adding-support-for-a-new-language.adoc deleted file mode 100644 index f15998d945..0000000000 --- a/modules/contributor-guide/partials/proc_adding-support-for-a-new-language.adoc +++ /dev/null @@ -1,35 +0,0 @@ - - - -[id="adding-support-for-a-new-language_{context}"] -= Adding support for a new language - -This section describes how to add support for a new language into {prod}. - -The described method is to write a Che-Theia plug-in that uses the _languageserver-node_ library to connect a language server to the VS Code extension API. Note that it is also possible to directly connect a Che-Theia plug-in or a VS Code extension to the plug-in API. - -.Prerequisites -* Install the latest Che-Theia plug-in Yeoman generator. Follow the documentation about xref:developing-che-theia-plug-ins.adoc[]. - -.Procedure - -. Generate a sample by running the `yo @theia/plugin` command. When prompted, confirm the choices for *Backend plug-in*, *Samples*, and then *Language sample*. This creates a project and a ready-to-use plug-in, which provides support for XML Language Server and can be deployed. - -. Replace the download URL of the implementation of the language server protocol in the `src/download-xml-ls.js` file. This file will be downloaded during the build process of the plug-in. If the name of `src/download-xml-ls.js` changed, replace it in the `package.json` file in the `scripts` block. - -. Replace the configuration of the language in the `src/language-configuration.json` file. This file contains configuration options for the current language. If the name of `src/language-configuration.json` changed, replace it in the `package.json` file in the `contribution` block. - -. Replace the configuration of the language in the `src/xml.tmLanguage.json` file. This file describes syntax highlighting. If the name of `src/xml.tmLanguage.json` changed, replace it in the `package.json` file in the `contribution.grammars` block. - -. Replace the information about the provided language in the `src/plug-in_name.ts` file. This file contains information about the location of the Language Server Protocol (LSP) implementation and the command with arguments to run it. - -. Build the plug-in by running `yarn` in the root of the project. - - -.Additional resources - -* link:https://github.com/eclipse/che-theia-samples/tree/master/samples/xml-language-server-plugin[Theia plug-in with XML Language Server] -* link:https://microsoft.github.io/language-server-protocol/[Language Server Protocol] -* link:https://code.visualstudio.com/api/language-extensions/overview[VS Code Language Extensions Documentation] -* link:https://code.visualstudio.com/api/language-extensions/language-server-extension-guide[A simple Language Server for plain text files] -* xref:publishing-che-theia-plug-ins.adoc[] diff --git a/modules/contributor-guide/partials/proc_bootstrapping-che-theia-plug-in-development-with-yeoman.adoc b/modules/contributor-guide/partials/proc_bootstrapping-che-theia-plug-in-development-with-yeoman.adoc deleted file mode 100644 index 4042265230..0000000000 --- a/modules/contributor-guide/partials/proc_bootstrapping-che-theia-plug-in-development-with-yeoman.adoc +++ /dev/null @@ -1,132 +0,0 @@ -// Module included in the following assemblies: -// -// developing-che-theia-plug-ins - -[id="bootstrapping-che-theia-plug-in-development-with-yeoman_{context}"] -= Bootstrapping a Che-Theia plug-in development with Yeoman - -Two methods are available to scaffold a new plug-in development environment in Che-Theia: - -* Console plug-in generator (based on the Yeoman generator). -* *Yeoman wizard* (launched from the command palette). - - -[id="list-of-available-plug-in-samples_{context}"] -== List of available plug-in samples - -The Che-Theia plug-in generator provides several predefined samples: - -* *Hello World plug-in*: The plug-in registers a new Che-Theia command. When the user launches this command, Che-Theia displays a notification with the `Hello World` message. The example illustrates how to define and use commands in Che-Theia. - -* *Skeleton plug-in*: The plug-in prints the current Che-Theia window state in the browser log. - -* *Samples plug-in*: The plug-in contains examples of how to use the Che-Theia API: - -** Commands sample: The plug-in shows how to define a Che-Theia command with arguments. Command arguments are useful when another plug-in needs to call a command with parameters. - -** Information message sample: An example of how to define and show a modal information message. - -** Quick-pick sample: An example of how to define a command list with items and a handler for a selected item. - -** Status-bar item sample: An example of how to apply information to the status bar. The status bar is a widget located at the bottom of the Che-Theia window (a footer). - - -[id="generating-plug-ins-overview_{context}"] -== Overview of generating plug-ins - -To simplify plug-in development, there is a plug-in generator (`@theia/generator-plugin`) for creating new plug-ins from scratch. The plug-in generator provides the *Yeoman wizard* for a step-by-step plug-in generation: - -. Choose project name for the future plug-in. -. Select plug-in type. The Che-Theia plug-in API has two plug-in types: -+ --- -** frontend: The plug-in works on the client side -** back end: The plug-in works on the server side --- -+ -During plug-in creation, you need to decide the purpose of the plug-in and, accordingly, select the plug-in type. - -. Select a plug-in sample. - -//*TODO* Apply stack for development: For plug-in development inside Eclipse CHE You could use any stack, but apply theia-dev plug-in. This stack contains installed npm, node, git and preinstalled `@theia/generator-plugin.` - - -[id="installing-the-plug-in-generator_{context}"] -== Installing the plug-in generator - -. Run the following command to install the plug-in generator: -+ ----- -$ yarn global add yo @theia/generator-plugin ----- - -. Check that the `@theia/plugin` generator is available: -+ ----- -$ yo --help ----- -+ -The command returns a list of pre-installed generators. - - -[id="generating-a-new-plug-in-in-the-console_{context}"] -== Generating a new plug-in in the console - -. Create a new terminal inside your workspace using the *Terminal* menu, and run the plug-in generator: -+ ----- -$ yo @theia/plugin ----- -+ -Alternatively, run `yo` without any parameters and select the `@theia/plugin` generator from the list of available generators. -+ -image::extensibility/yo-select-plug-in-generator.png[link="../_images/extensibility/yo-select-plug-in-generator.png"] - -. Enter the information to configure the plug-in. For example: -+ -image::extensibility/launching-console-plug-in-generator.png[link="../_images/extensibility/launching-console-plug-in-generator.png"] - -When the plug-in is generated, it appears in the *Files* panel. The sample is already compiled and contains the plug-in binary file. In this example, the plug-in binary file is named `my_first_plugin.theia`. - - -[id="generating-a-new-plug-in-using-the-yeoman-wizard_{context}"] -== Generating a new plug-in using the Yeoman wizard - -{prod-short}-theia provides the `Yeoman wizard` command for creating new plug-ins from the command palette. - -. To open the command palette, press kbd:[Ctrl+Shift+p] (or kbd:[Cmd+Shift+p] on macOS). - -. Type `Yeom` to filter the commands. Select the `Yeoman Wizard` command. -+ -image::extensibility/yeoman-wizard-launching.png[link="../_images/extensibility/yeoman-wizard-launching.png"] -+ -Note that launching the wizard may take a few seconds. - -. Enter the new project name. -+ -image::extensibility/yeoman-wizard-choosing-plug-in-name.png[link="../_images/extensibility/yeoman-wizard-choosing-plug-in-name.png"] - -. Select the desired plug-in type (client-side or server-side). -+ -image::extensibility/yeoman-wizard-choosing-plug-in-type.png[link="../_images/extensibility/yeoman-wizard-choosing-plug-in-type.png"] - -. Select the plug-in sample to use. -+ -image::extensibility/yeoman-wizard-choosing-plug-in-sample.png[link="../_images/extensibility/yeoman-wizard-choosing-plug-in-sample.png"] - -When the plug-in is generated, the *Yeoman wizard* displays a notification. - -image::extensibility/yeoman-wizard-plug-in-generated.png[link="../_images/extensibility/yeoman-wizard-plug-in-generated.png"] - -The plug-in sample displays in the *Files* panel. Use the *Output* tab in the bottom panel to access logs for plug-in generation. - -image::extensibility/yeoman-wizard-logs.png[link="../_images/extensibility/yeoman-wizard-logs.png"] - -NOTE: The *Yeoman wizard* only works when a workspace is opened in Che-Theia. - - -// .Additional resources -// -// * A bulleted list of links to other material closely related to the contents of the procedure module. -// * For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. diff --git a/modules/contributor-guide/partials/proc_developing-che-theia-plug-ins-using-che.adoc b/modules/contributor-guide/partials/proc_developing-che-theia-plug-ins-using-che.adoc deleted file mode 100644 index 02abc39cf4..0000000000 --- a/modules/contributor-guide/partials/proc_developing-che-theia-plug-ins-using-che.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// developing-che-theia-plug-ins - -[id="developing-che-theia-plug-ins-using-che_{context}"] -= Developing a Che-Theia plug-in using {prod-short} - -This section describes how to configure an environment for developing the Che-Theia plug-ins in {prod}. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* `{prod-cli}` management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. - -. *Create a workspace for development.* {prod-short} has stack for plug-in development. In the *Dashboard*, click the *Workspaces* tab, and click the btn:[Add Workspace] button. - -. Select the *NodeJS React Web Application* sample. - -. *Generate a plug-in scaffold.* The workspace created from this stack provides an easy way to scaffold a new plug-in. When the workspace is started and fully ready, execute the *Yeoman Wizard* from the command palette: -+ -.. Press *F1* or kbd:[Ctrl+Shift+p] to invoke the command palette, and start typing the command name `Yeoman ...`. Note that you can also use the keyboard to navigate through the offered commands. -+ -.Launching the Yeoman Wizard -image::extensibility/launching-yeoman-wizard.png[link="../_images/extensibility/launching-yeoman-wizard.png"] -+ -.. Specify the following fields for the desired plug-in: -+ -* plug-in name: For example, `my-first-plugin`. -* plug-in type: Select `backend plug-in`. -* plug-in template: Select the `Hello World plug-in`. -+ -A message confirming that the plug-in generation has been successful indicates creation of the plug-in. -+ -.Yeoman successfully generated a new plug-in -image::extensibility/yeoman-successful.png[link="../_images/extensibility/yeoman-successful.png"] - -. Open the *Files* panel, to see the sources of the generated plug-in in the `src` directory. - -. *Build the plug-in.* After the plug-in is created, build the plug-in: -+ -.. Open a new terminal in the development container (use kbd:[Ctrl+`], then select ``ws/dev``). -+ -.Opening a new terminal in the development container -image::extensibility/open-terminal-in-container.png[link="../_images/extensibility/open-terminal-in-container.png"] -+ -.. In the terminal, go to the plug-in directory, and run the `yarn` command: -+ ----- -# cd my-first-plugin/ -# yarn ----- -+ -.Building a Che-Theia plug-in using `yarn` -image::extensibility/building-plug-in-using-yarn.png[link="../_images/extensibility/building-plug-in-using-yarn.png"] -+ -NOTE: The plug-in generator automatically builds the plug-in after its generation. - -. *Run the plug-in.* To see your plug-in in action in the IDE, use the *Hosted mode* to start a new IDE instance and to install the plug-in in it. The two IDEs are running: one for developing your plug-in and one for testing it. -+ -.. In the command palette, run: `Hosted Plugin: Start Instance` command (press kbd:[F1], and type the command). -.. Select the path to the root directory of the plug-in in your workspace. -+ -NOTE: If you get a warning that your browser prevented the opening of a new tab, click the btn:[Open] button in the dialog box. A new tab with another Che-Theia instance (with the developed plug-in loaded) is opened. -+ -.Running a Che-Theia plug-in in Hosted mode -image::extensibility/running-plug-in-hosted-mode.gif[link="../_images/extensibility/running-plug-in-hosted-mode.gif"] - -. *Debug the plug-in.* -+ -.. In the source code of your plug-in, set a breakpoint by a click behind a line number (in the editor gutter). -.. Using the command palette, stop your *Hosted Plug-in* instance (if any) by running the `Hosted Plugin: Stop Instance` command. -.. Start the *Hosted Plug-in* instance again in the debugging mode by running the `Hosted Plugin: Debug Instance` command. -.. Switch to the *Hosted Instance* tab and perform the required actions to reach the code with the breakpoint. -.. Go back to the *Main Che-Theia* window, and use the *Debug* panel as you need. -+ -.Debugging a Che-Theia plug-in -image::extensibility/debugging-plug-ins.gif[link="../_images/extensibility/debugging-plug-ins.gif"] -+ -NOTE: When developing a frontend plug-in, debug it using your browser’s Developer Tools option. - - -// .Additional resources -// -// * A bulleted list of links to other material closely related to the contents of the procedure module. -// * For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. diff --git a/modules/contributor-guide/partials/proc_overriding-ram-of-a-che-theia-plug-in.adoc b/modules/contributor-guide/partials/proc_overriding-ram-of-a-che-theia-plug-in.adoc deleted file mode 100644 index d3c7bcc222..0000000000 --- a/modules/contributor-guide/partials/proc_overriding-ram-of-a-che-theia-plug-in.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// publishing-che-theia-plug-ins - -[id="overriding-ram-of-a-che-theia-plug-in_{context}"] -= Overriding RAM of a Che-Theia plug-in - -Sometimes, a plug-in consumes more memory than what has been allocated to it by the plug-in author or {prod-short} defaults. An example of such a case is the use of a language server with a project that has many source files (&8gt; 10 000). RAM consumption in such circumstances needs to be tuned, otherwise the machine that runs the {prod-short} workspaces kills the process with an out-of-memory error (OOM) error. - - -.Procedure - -Users can override the RAM limit and request for a particular plug-in in their workspace configuration. - -* Set the `memoryLimit` and/or `memoryRequest` for devfile component to `1000M` or `10Gi`, or any other value formatted as a number and a unit (`b, k, ki, m, mi, g, gi`). When no unit is specified, the number is in bytes. - -NOTE: Using this notation, units that contain the character `i`, denote a number that is of the power 2, such as 1024 (as opposed to numbers that use a power of 10, such as 1000). - -.Limiting RAM use for a plug-in -[example] -==== -For the YAML language server plug-in, sets the RAM limit to 768 mebibytes (1073741824 bytes) and RAM request to 500 megabytes: - -[source,yaml] ----- -components: - - id: redhat/vscode-yaml/latest - type: chePlugin - memoryLimit: 768mi - memoryRequest: 500M ----- -==== - -.Limiting CPU use for a plug-in -[example] -==== -For the YAML language server plug-in, sets the CPU limit to 1.5 cores and CPU request to 500 millicores: - -[source,yaml] ----- -components: - - id: redhat/vscode-yaml/latest - type: chePlugin - cpuLimit: 1.5 - cpuRequest: 500m ----- -==== - diff --git a/modules/contributor-guide/partials/ref_che-theia-plug-in-api.adoc b/modules/contributor-guide/partials/ref_che-theia-plug-in-api.adoc deleted file mode 100644 index 152b3157fd..0000000000 --- a/modules/contributor-guide/partials/ref_che-theia-plug-in-api.adoc +++ /dev/null @@ -1,107 +0,0 @@ - - -:parent-context-of-che-theia-plug-in-api: {context} - -[id="che-theia-plug-in-api_{context}"] -= Che-Theia plug-in API - -:context: che-theia-plug-in-api - -The Che-Theia plug-in API consists of two {namespace}s: - -[options="header"] -|=== -| Namespace | Description -| `theia` | Provides a Che-Theia IDE-related API that allows to interact with its different components -| `che` | Provides a plug-in API to access parts of the {prod-short} API -|=== - - -[id="theia-{namespace}_{context}"] -== `theia` {namespace} - -The available resources of the `theia` {namespace} are described in the link:https://raw.githubusercontent.com/theia-ide/theia/master/packages/plugin/src/theia.d.ts[`theia.d.ts`] file in the link:https://github.com/theia-ide/theia[Theia repository]. The root of the {namespace} contains types declaration and the following API sections: - -|=== -| `commands` | API for adding new and executing existing Che-Theia commands -| `debug` | API for debugger configuration and debugger events -| `env` | API for accessing environment variables and query parameters of the Che-Theia IDE -| `languages` | API and events related to language support; typically is used by language servers -| `languageServer` (experimental) | API for language-server integration -| `plugins` | API for retrieving information about loaded plug-ins -| `tasks` | API for providing custom task runners -| `window` | API to control visual components of the IDE. It allows to manipulate the editor tabs, terminals, status bar, and so on. The section contains events for changing the state of selected components and the whole IDE. Dialog popups. -| `workspace` | API related to the Che-Theia workspace with information about the current workspace state, documents in it, file-related operations including watching, finding, and so on. The section contains state-change events. -|=== - - -[id="{prod-id-short}-{namespace}_{context}"] -== `che` {namespace} - -NOTE: Many APIs in the {namespace} are experimental and can change in the future. - - -This {namespace} contains APIs and types related to {prod-short}. Some sections are a bridge to {prod-short} API. The following is a list of the sections: - -|=== -| factory | Allows to work with the {prod-short} factory API; provides functionality to retrieve specified factory configuration -| task | Allows to add {prod-short}-aware commands ({prod-short}-specific attributes, such as workspace ID or container name, are accessible from within task implementation) -| variables | Allows to add a variable resolver -| workspace | Allows to work with the {prod-short} workspace API; provides functionality to access workspaces, their lifecycle, and user settings. -|=== - -[id="using-the-{prod-id-short}-in-plug-ins_{context}"] -== Using the `che` {orch-namespace} in plug-ins - -VS Code extensions:: -+ -. Adding the `@eclipse-che/plugin` dependency for backend plug-ins to a `package.json` file is a possibility. -. For quick calls, it is simpler to use VS Code extension mechanism because it does not require relying on a third-party party dependency or trying and catching the error. -+ -. Import and use the {orch-namespace}. For example: -+ -[source,typescript] ----- -const eclipseCheExtPlugin = vscode.extensions.getExtension('@eclipse-che.ext-plugin'); -if (eclipseCheExtPlugin) { - // grab user - const user = await eclipseCheExtPlugin.exports.user.getCurrentUser(); - vscode.window.showInformationMessage(`Eclipse Che user information: id ${user.id} with name ${user.name}`); -} else { - vscode.window.showWarningMessage('Not running inside Eclipse Che, not displaying any user information'); -} ----- - -[id="using-the-{prod-id-short}-namespace-in-plug-ins_{context}"] -== Using the `che` {orch-namespace} in plug-ins - -Backend plug-in:: -+ -. Add the `@eclipse-che/plugin` dependency to a plug-in `package.json` file. -+ -. Import and use the {orch-namespace}. For example: -+ -[source,typescript] ----- -import * as che from '@eclipse-che/plugin'; - -const wsConfig = che.workspace.getById(workspaceID); ----- - -Frontend plug-in:: -+ -. Perform the same steps as for a back-end plug-in. -+ -. Modify the `externals` section in `webpack.config.js` by adding the `@eclipse-che/plugin` key with the following value: `che.<your_plugin_ID>` (copy the `@theia/plugin` value, and substitute `theia.` for `che.`). For example: -+ -[source,javascript] ----- -externals: { - "@theia/plugin": "theia.theia_test_api", - "@eclipse-che/plugin": "che.theia_test_api" - } ----- - -NOTE: It is possible to add a new API {namespace} for plug-ins using a separate extension. - -:context: {parent-context-of-che-theia-plug-in-api} diff --git a/modules/contributor-guide/partials/ref_debug-adapter-protocol.adoc b/modules/contributor-guide/partials/ref_debug-adapter-protocol.adoc deleted file mode 100644 index dd04425ea6..0000000000 --- a/modules/contributor-guide/partials/ref_debug-adapter-protocol.adoc +++ /dev/null @@ -1,9 +0,0 @@ - - - -[id="debug-adapter-protocol_{context}"] -= Debug Adapter Protocol - -The Debug Adapter Protocol (DAP) defines the abstract protocol used between a development tool, such as an Integrated development environment (IDE) or an editor, and a debugger. - -For more details, see link:https://microsoft.github.io/debug-adapter-protocol/[Debug Adapter Protocol] site. diff --git a/modules/contributor-guide/partials/ref_language-server-protocol.adoc b/modules/contributor-guide/partials/ref_language-server-protocol.adoc deleted file mode 100644 index 265de892e8..0000000000 --- a/modules/contributor-guide/partials/ref_language-server-protocol.adoc +++ /dev/null @@ -1,9 +0,0 @@ - - - -[id="language-server-protocol_{context}"] -= Language Server Protocol - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features, including auto complete, go to definition and find all references. - -For more details, see link:https://microsoft.github.io/language-server-protocol/[]. diff --git a/modules/end-user-guide/examples/che-adding-a-git-project-into-a-workspace-using-a-devfile.adoc b/modules/end-user-guide/examples/che-adding-a-git-project-into-a-workspace-using-a-devfile.adoc deleted file mode 100644 index 8d1972e9a7..0000000000 --- a/modules/end-user-guide/examples/che-adding-a-git-project-into-a-workspace-using-a-devfile.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-new-workspace-from-the-dashboard -// adding-projects-to-your-workspace -+ -.Example - Adding a `.git` project into a workspace using a devfile -+ -In the following instance, the project `{project-context}` acts as the example of a user's project. A user specifies this project using the `name` attribute of a devfile. The `location` attribute defines the source repository represented by an URL to a Git repository or zip archive. -+ -To add a project into the workspace, add or edit the following section: -+ -[source,yaml,subs="+quotes,macros,attributes"] ----- -projects: - - name: __<{project-context}>__ - source: - type: git - location: 'https://github.com/__<github-organization>__/__<{project-context}>__.git' ----- -+ -For additional information, see the xref:authoring-devfiles-version-1.adoc[Devfile reference] section. diff --git a/modules/end-user-guide/examples/che-go-configure-goproxy.adoc b/modules/end-user-guide/examples/che-go-configure-goproxy.adoc deleted file mode 100644 index 026a51bf15..0000000000 --- a/modules/end-user-guide/examples/che-go-configure-goproxy.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[source,yaml] ----- -components: -- mountSources: true - type: dockerimage - alias: go-cli - image: 'quay.io/eclipse/che-golang-1.12:7.7.0' - ... - - value: /tmp/.cache - name: GOCACHE - - value: 'http://your.athens.host' - name: GOPROXY ----- \ No newline at end of file diff --git a/modules/end-user-guide/examples/che-go-use-self-signed-cert.adoc b/modules/end-user-guide/examples/che-go-use-self-signed-cert.adoc deleted file mode 100644 index 58e4584a62..0000000000 --- a/modules/end-user-guide/examples/che-go-use-self-signed-cert.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[source,yaml] ----- -components: -- mountSources: true - type: dockerimage - alias: go-cli - image: 'quay.io/eclipse/che-golang-1.12:7.7.0' - ... - - value: /tmp/.cache - name: GOCACHE - - value: 'http://your.athens.host' - name: GOPROXY - - value: 'on' - name: GO111MODULE - - value: '/public-certs/athens-server.cer' - name: SSL_CERT_FILE ----- diff --git a/modules/end-user-guide/examples/che-java-language-support.adoc b/modules/end-user-guide/examples/che-java-language-support.adoc deleted file mode 100644 index dbf2eb0808..0000000000 --- a/modules/end-user-guide/examples/che-java-language-support.adoc +++ /dev/null @@ -1,5 +0,0 @@ -[source,yaml] ----- - - id: redhat/java8/latest - type: chePlugin ----- diff --git a/modules/end-user-guide/examples/che-python-configure-pip.adoc b/modules/end-user-guide/examples/che-python-configure-pip.adoc deleted file mode 100644 index 74dde83927..0000000000 --- a/modules/end-user-guide/examples/che-python-configure-pip.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[source,yaml] ----- - - id: ms-python/python/latest - memoryLimit: 512Mi - type: chePlugin - env: - - name: 'PIP_INDEX_URL' - value: 'https://<username>:<password>@pypi.company.com/simple' - - mountSources: true - memoryLimit: 512Mi - type: dockerimage - alias: python - image: 'quay.io/eclipse/che-python-3.8:nightly' - env: - - name: 'PIP_INDEX_URL' - value: 'https://<username>:<password>@pypi.company.com/simple' ----- diff --git a/modules/end-user-guide/examples/che-python-use-self-signed-cert.adoc b/modules/end-user-guide/examples/che-python-use-self-signed-cert.adoc deleted file mode 100644 index 75b8b9c364..0000000000 --- a/modules/end-user-guide/examples/che-python-use-self-signed-cert.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[source,yaml] ----- - - id: ms-python/python/latest - memoryLimit: 512Mi - type: chePlugin - env: - - name: 'PIP_INDEX_URL' - value: 'https://<username>:<password>@pypi.company.com/simple' - - value: '/public-certs/pip.cer' - name: 'PIP_CERT' - - mountSources: true - memoryLimit: 512Mi - type: dockerimage - alias: python - image: 'quay.io/eclipse/che-python-3.8:nightly' - env: - - name: 'PIP_INDEX_URL' - value: 'https://<username>:<password>@pypi.company.com/simple' - - value: '/public-certs/pip.cer' - name: 'PIP_CERT' ----- diff --git a/modules/end-user-guide/examples/che-ref_git-credential-file-as-kubernetes-secret-into-the-file.adoc b/modules/end-user-guide/examples/che-ref_git-credential-file-as-kubernetes-secret-into-the-file.adoc deleted file mode 100644 index a1362613df..0000000000 --- a/modules/end-user-guide/examples/che-ref_git-credential-file-as-kubernetes-secret-into-the-file.adoc +++ /dev/null @@ -1,23 +0,0 @@ -.Example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: git-credentials-secret - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: workspace-secret - annotations: - che.eclipse.org/automount-workspace-secret: 'true' - che.eclipse.org/mount-path: /home/theia/.git-credentials - che.eclipse.org/mount-as: file - che.eclipse.org/git-credential: 'true' -data: - credentials: aHR0cHM6Ly91c2VyOnBhc3NAZXhhbXBsZS5jb20K ----- -+ -Content of the credential field has to be bas64 encoded to avoid collision with special characters in password. -This results in a file named `credentials` being mounted at the `/home/theia/.git-credentials` path of all workspace containers. -Also, the system configuration of Git would be linked to the mounted file. diff --git a/modules/end-user-guide/examples/che-workspace-from-the-php-stack-java-language-support.adoc b/modules/end-user-guide/examples/che-workspace-from-the-php-stack-java-language-support.adoc deleted file mode 100644 index 7ec6abc67f..0000000000 --- a/modules/end-user-guide/examples/che-workspace-from-the-php-stack-java-language-support.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[source,yaml,subs="+attributes"] ----- -components: - - id: redhat/php/latest - memoryLimit: 1Gi - type: chePlugin - - id: redhat/php-debugger/latest - memoryLimit: 256Mi - type: chePlugin - - mountSources: true - endpoints: - - name: 8080/tcp - port: 8080 - memoryLimit: 512Mi - type: dockerimage - volumes: - - name: composer - containerPath: {prod-home}/.composer - - name: symfony - containerPath: {prod-home}/.symfony - alias: php - image: 'quay.io/eclipse/che-php-7:nightly' - - id: redhat/java8/latest - type: chePlugin ----- diff --git a/modules/end-user-guide/examples/proc_che-including-kubernetes-applications-in-a-workspace-devfile-definition.adoc b/modules/end-user-guide/examples/proc_che-including-kubernetes-applications-in-a-workspace-devfile-definition.adoc deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/end-user-guide/examples/snip_bitbucket-personal-access-token-secret.adoc b/modules/end-user-guide/examples/snip_bitbucket-personal-access-token-secret.adoc deleted file mode 100644 index 999d2627b8..0000000000 --- a/modules/end-user-guide/examples/snip_bitbucket-personal-access-token-secret.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[source,yaml,subs="+quotes,+attributes"] ----- -kind: Secret -apiVersion: v1 -metadata: - labels: - app.kubernetes.io/component: 'scm-personal-access-token' <1> - app.kubernetes.io/part-of: che.eclipse.org - annotations: - che.eclipse.org/che-userid: '__<che-userid>__' <2> - che.eclipse.org/scm-userid: '__<scm-userid>__' <3> - che.eclipse.org/scm-username: '__<scm-username>__' <4> - che.eclipse.org/scm-url: '__<scm-url>__' <5> - che.eclipse.org/expired-after: '-1' <6> - name: bitbucket-personal-access-token-secret - -data: - token: '__<base64-encoded_secret>__' <7> ----- diff --git a/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-a-file.adoc b/modules/end-user-guide/examples/snip_che-a-kubernetes-secret-as-a-file.adoc similarity index 100% rename from modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-a-file.adoc rename to modules/end-user-guide/examples/snip_che-a-kubernetes-secret-as-a-file.adoc diff --git a/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-an-variable.adoc b/modules/end-user-guide/examples/snip_che-a-kubernetes-secret-as-an-variable.adoc similarity index 100% rename from modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-an-variable.adoc rename to modules/end-user-guide/examples/snip_che-a-kubernetes-secret-as-an-variable.adoc diff --git a/modules/end-user-guide/examples/che-ref_annotations-description.adoc b/modules/end-user-guide/examples/snip_che-annotations-description.adoc similarity index 100% rename from modules/end-user-guide/examples/che-ref_annotations-description.adoc rename to modules/end-user-guide/examples/snip_che-annotations-description.adoc diff --git a/modules/end-user-guide/examples/snip_che-configuring-a-workspace-to-use-intellij-idea-community.adoc b/modules/end-user-guide/examples/snip_che-configuring-a-workspace-to-use-intellij-idea-community.adoc deleted file mode 100644 index db2c6b09fc..0000000000 --- a/modules/end-user-guide/examples/snip_che-configuring-a-workspace-to-use-intellij-idea-community.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[source,yaml,subs="+quotes,macros,attributes"] ----- -components: - - type: cheEditor - reference: https://raw.githubusercontent.com/che-incubator/jetbrains-editor-images/meta/che-idea/latest.meta.yaml ----- diff --git a/modules/end-user-guide/examples/snip_che-supported-ides.adoc b/modules/end-user-guide/examples/snip_che-supported-ides.adoc new file mode 100644 index 0000000000..2213e15d83 --- /dev/null +++ b/modules/end-user-guide/examples/snip_che-supported-ides.adoc @@ -0,0 +1,27 @@ + +.The `__<editor_key>__` values for the supported IDEs +|=== +| IDE | `__<editor_key>__` value | Note + + +| link:https://github.com/eclipse-che/che-theia[Che-Theia] +| `eclipse/che-theia/latest` +| This is the default IDE that loads in a new workspace without this URL parameter. + +| link:https://github.com/eclipse-che/che-theia[Che-Theia] +| `eclipse/che-theia/next` +| When using the `next` link:https://github.com/che-incubator/chectl/[chectl] channel, this IDE loads as a default without this URL parameter. + +| link:https://github.com/che-incubator/che-code[Che-Code] +| `che-incubator/che-code/insiders` +| + +| link:https://www.jetbrains.com/help/idea/discover-intellij-idea.html[IntelliJ IDEA Community Edition] +| `che-incubator/intellij-community/latest` +| + +| link:https://www.jetbrains.com/help/pycharm/quick-start-guide.html[PyCharm] +| `che-incubator/pycharm/latest` +| + +|=== \ No newline at end of file diff --git a/modules/end-user-guide/examples/snip_github-personal-access-token-secret.adoc b/modules/end-user-guide/examples/snip_github-personal-access-token-secret.adoc deleted file mode 100644 index 63f0197d46..0000000000 --- a/modules/end-user-guide/examples/snip_github-personal-access-token-secret.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: github-personal-access-token-secret - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: scm-personal-access-token - annotations: - che.eclipse.org/expired-after: '-1' - che.eclipse.org/che-userid: '355d1ce5-990e-401e-9a8c-094bca10b5b3' - che.eclipse.org/scm-userid: '1651062' - che.eclipse.org/scm-username: 'user-foo' - che.eclipse.org/scm-url: 'https://github.com' -data: - token: Yzh5cEt6cURxUWVCa3FKazhtaHg= ----- diff --git a/modules/end-user-guide/examples/snip_gitlab-personal-access-token-secret.adoc b/modules/end-user-guide/examples/snip_gitlab-personal-access-token-secret.adoc deleted file mode 100644 index ae95fd39aa..0000000000 --- a/modules/end-user-guide/examples/snip_gitlab-personal-access-token-secret.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: gitlab-personal-access-token-secret - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: scm-personal-access-token - annotations: - che.eclipse.org/expired-after: '-1' - che.eclipse.org/che-userid: '355d1ce5-990e-401e-9a8c-094bca10b5b3' - che.eclipse.org/scm-userid: '2' - che.eclipse.org/scm-username: 'user-foo' - che.eclipse.org/scm-url: 'https://gitlab.apps.cluster-example.com' -data: - token: Yzh5cEt6cURxUWVCa3FKazhtaHg= ----- diff --git a/modules/end-user-guide/images/contribute.svg b/modules/end-user-guide/images/contribute.svg new file mode 100644 index 0000000000..576ba53f16 --- /dev/null +++ b/modules/end-user-guide/images/contribute.svg @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + Copyright (c) 2012-2020 Red Hat, Inc. + This program and the accompanying materials are made + available under the terms of the Eclipse Public License 2.0 + which is available at https://www.eclipse.org/legal/epl-2.0/ + + SPDX-License-Identifier: EPL-2.0 + + Contributors: + Red Hat, Inc. - initial API and implementation + +--> +<svg width="147px" height="20px" viewBox="0 0 147 20" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"> + <g id="contribute-button"> + <g id="che-contribute"> + <rect fill="#292C2F" fill-rule="nonzero" x="0" y="0" width="117" height="20" rx="4"/> + <g id="Che-logo" transform="translate(8.000000, 2.000000)" fill="#FFFFFF"> + <polygon id="Path-1" points="0.00849162302 8.43339117 0 3.76684272 6.28508764 0 12.5555079 3.76444243 8.68435713 6.08858226 6.29640981 4.69321826"/> + <polygon id="Path-2" points="0 11.8401916 6.29139203 15.5603621 12.6082589 11.7541815 12.6082589 7.13817228 6.29139203 10.8266058 0 7.13817228"/> + </g> + <rect id="Rectangle-path" fill="#525D84" fill-rule="nonzero" x="30" y="0" width="117" height="20" rx="4"/> + <polygon id="Shape" fill="#525D84" fill-rule="nonzero" points="30 0 34 0 34 20 30 20"/> + <path d="M41.788,10.062 C41.788,10.6523363 41.6945009,11.1894976 41.5075,11.6735 C41.3204991,12.1575024 41.0565017,12.5718316 40.7155,12.9165 C40.3744983,13.2611684 39.9656691,13.5279157 39.489,13.71675 C39.0123309,13.9055843 38.4843362,14 37.905,14 L34.957,14 L34.957,6.1185 L37.905,6.1185 C38.4843362,6.1185 39.0123309,6.21291572 39.489,6.40175 C39.9656691,6.59058428 40.3744983,6.85824827 40.7155,7.20475 C41.0565017,7.55125173 41.3204991,7.96649758 41.5075,8.4505 C41.6945009,8.93450242 41.788,9.47166371 41.788,10.062 L41.788,10.062 Z M40.6935,10.062 C40.6935,9.57799758 40.6275007,9.14533524 40.4955,8.764 C40.3634993,8.38266476 40.1765012,8.06000132 39.9345,7.796 C39.6924988,7.53199868 39.3991684,7.33033403 39.0545,7.191 C38.7098316,7.05166597 38.3266688,6.982 37.905,6.982 L36.0295,6.982 L36.0295,13.1365 L37.905,13.1365 C38.3266688,13.1365 38.7098316,13.066834 39.0545,12.9275 C39.3991684,12.788166 39.6924988,12.587418 39.9345,12.32525 C40.1765012,12.063082 40.3634993,11.7413352 40.4955,11.36 C40.6275007,10.9786648 40.6935,10.5460024 40.6935,10.062 L40.6935,10.062 Z M45.2915,8.3405 C45.6251683,8.3405 45.9331653,8.39641611 46.2155,8.50825 C46.4978347,8.62008389 46.7416656,8.78141561 46.947,8.99225 C47.1523344,9.20308439 47.3127494,9.46341512 47.42825,9.77325 C47.5437506,10.0830849 47.6015,10.435998 47.6015,10.832 C47.6015,10.9860008 47.5850002,11.0886664 47.552,11.14 C47.5189998,11.1913336 47.4566671,11.217 47.365,11.217 L43.658,11.217 C43.6653334,11.5690018 43.7129996,11.8751654 43.801,12.1355 C43.8890004,12.3958346 44.0099992,12.6130825 44.164,12.78725 C44.3180008,12.9614175 44.5013323,13.0915829 44.714,13.17775 C44.9266677,13.2639171 45.1649987,13.307 45.429,13.307 C45.6746679,13.307 45.8864158,13.2785836 46.06425,13.22175 C46.2420842,13.1649164 46.395166,13.1035003 46.5235,13.0375 C46.651834,12.9714997 46.7590829,12.9100836 46.84525,12.85325 C46.9314171,12.7964164 47.0056664,12.768 47.068,12.768 C47.1486671,12.768 47.2109998,12.7991664 47.255,12.8615 L47.53,13.219 C47.4089994,13.3656674 47.2641675,13.4930828 47.0955,13.60125 C46.9268325,13.7094172 46.746251,13.798333 46.55375,13.868 C46.361249,13.937667 46.1623344,13.9899165 45.957,14.02475 C45.7516656,14.0595835 45.5481677,14.077 45.3465,14.077 C44.9614981,14.077 44.6067516,14.0119173 44.28225,13.88175 C43.9577484,13.7515827 43.6772512,13.5609179 43.44075,13.30975 C43.2042488,13.0585821 43.0200007,12.7478352 42.888,12.3775 C42.7559993,12.0071648 42.69,11.5818357 42.69,11.1015 C42.69,10.7128314 42.7495827,10.349835 42.86875,10.0125 C42.9879173,9.67516498 43.1593322,9.38275124 43.383,9.13525 C43.6066678,8.88774876 43.8798317,8.69341737 44.2025,8.55225 C44.5251683,8.41108263 44.8881647,8.3405 45.2915,8.3405 L45.2915,8.3405 Z M45.3135,9.061 C44.8404976,9.061 44.4683347,9.19758197 44.197,9.47075 C43.9256653,9.74391803 43.7570003,10.1224976 43.691,10.6065 L46.7215,10.6065 C46.7215,10.3791655 46.6903336,10.1710843 46.628,9.98225 C46.5656664,9.79341572 46.4740006,9.63025069 46.353,9.49275 C46.2319994,9.35524931 46.0844175,9.24891704 45.91025,9.17375 C45.7360825,9.09858296 45.5371678,9.061 45.3135,9.061 L45.3135,9.061 Z M48.003,8.4285 L48.806,8.4285 C48.8830004,8.4285 48.9471664,8.44866646 48.9985,8.489 C49.0498336,8.52933353 49.0864999,8.57699972 49.1085,8.632 L50.522,12.218 C50.5733336,12.3500007 50.6136665,12.4819993 50.643,12.614 C50.6723335,12.7460007 50.6998332,12.876166 50.7255,13.0045 C50.7548335,12.876166 50.7859998,12.7460007 50.819,12.614 C50.8520002,12.4819993 50.8941664,12.3500007 50.9455,12.218 L52.3755,8.632 C52.3975001,8.57333304 52.4332498,8.52475019 52.48275,8.48625 C52.5322502,8.44774981 52.5936663,8.4285 52.667,8.4285 L53.4315,8.4285 L51.16,14 L50.2745,14 L48.003,8.4285 Z M56.4015,8.3405 C56.7351683,8.3405 57.0431653,8.39641611 57.3255,8.50825 C57.6078347,8.62008389 57.8516656,8.78141561 58.057,8.99225 C58.2623344,9.20308439 58.4227494,9.46341512 58.53825,9.77325 C58.6537506,10.0830849 58.7115,10.435998 58.7115,10.832 C58.7115,10.9860008 58.6950002,11.0886664 58.662,11.14 C58.6289998,11.1913336 58.5666671,11.217 58.475,11.217 L54.768,11.217 C54.7753334,11.5690018 54.8229996,11.8751654 54.911,12.1355 C54.9990004,12.3958346 55.1199992,12.6130825 55.274,12.78725 C55.4280008,12.9614175 55.6113323,13.0915829 55.824,13.17775 C56.0366677,13.2639171 56.2749987,13.307 56.539,13.307 C56.7846679,13.307 56.9964158,13.2785836 57.17425,13.22175 C57.3520842,13.1649164 57.505166,13.1035003 57.6335,13.0375 C57.761834,12.9714997 57.8690829,12.9100836 57.95525,12.85325 C58.0414171,12.7964164 58.1156664,12.768 58.178,12.768 C58.2586671,12.768 58.3209998,12.7991664 58.365,12.8615 L58.64,13.219 C58.5189994,13.3656674 58.3741675,13.4930828 58.2055,13.60125 C58.0368325,13.7094172 57.856251,13.798333 57.66375,13.868 C57.471249,13.937667 57.2723344,13.9899165 57.067,14.02475 C56.8616656,14.0595835 56.6581677,14.077 56.4565,14.077 C56.0714981,14.077 55.7167516,14.0119173 55.39225,13.88175 C55.0677484,13.7515827 54.7872512,13.5609179 54.55075,13.30975 C54.3142488,13.0585821 54.1300007,12.7478352 53.998,12.3775 C53.8659993,12.0071648 53.8,11.5818357 53.8,11.1015 C53.8,10.7128314 53.8595827,10.349835 53.97875,10.0125 C54.0979173,9.67516498 54.2693322,9.38275124 54.493,9.13525 C54.7166678,8.88774876 54.9898317,8.69341737 55.3125,8.55225 C55.6351683,8.41108263 55.9981646,8.3405 56.4015,8.3405 L56.4015,8.3405 Z M56.4235,9.061 C55.9504976,9.061 55.5783347,9.19758197 55.307,9.47075 C55.0356653,9.74391803 54.8670003,10.1224976 54.801,10.6065 L57.8315,10.6065 C57.8315,10.3791655 57.8003336,10.1710843 57.738,9.98225 C57.6756664,9.79341572 57.5840006,9.63025069 57.463,9.49275 C57.3419994,9.35524931 57.1944175,9.24891704 57.02025,9.17375 C56.8460825,9.09858296 56.6471678,9.061 56.4235,9.061 L56.4235,9.061 Z M61.049,5.8985 L61.049,14 L60.07,14 L60.07,5.8985 L61.049,5.8985 Z M65.031,8.3405 C65.438002,8.3405 65.8055817,8.40833265 66.13375,8.544 C66.4619183,8.67966734 66.7405822,8.87216542 66.96975,9.1215 C67.1989178,9.37083458 67.3749161,9.6724149 67.49775,10.02625 C67.6205839,10.3800851 67.682,10.7751645 67.682,11.2115 C67.682,11.6515022 67.6205839,12.0474982 67.49775,12.3995 C67.3749161,12.7515018 67.1989178,13.0521654 66.96975,13.3015 C66.7405822,13.5508346 66.4619183,13.742416 66.13375,13.87625 C65.8055817,14.010084 65.438002,14.077 65.031,14.077 C64.623998,14.077 64.2564183,14.010084 63.92825,13.87625 C63.6000817,13.742416 63.3205012,13.5508346 63.0895,13.3015 C62.8584988,13.0521654 62.6806673,12.7515018 62.556,12.3995 C62.4313327,12.0474982 62.369,11.6515022 62.369,11.2115 C62.369,10.7751645 62.4313327,10.3800851 62.556,10.02625 C62.6806673,9.6724149 62.8584988,9.37083458 63.0895,9.1215 C63.3205012,8.87216542 63.6000817,8.67966734 63.92825,8.544 C64.2564183,8.40833265 64.623998,8.3405 65.031,8.3405 L65.031,8.3405 Z M65.031,13.3125 C65.5810027,13.3125 65.9916653,13.1282518 66.263,12.75975 C66.5343347,12.3912482 66.67,11.8770033 66.67,11.217 C66.67,10.55333 66.5343347,10.0363352 66.263,9.666 C65.9916653,9.29566481 65.5810027,9.1105 65.031,9.1105 C64.7523319,9.1105 64.5103344,9.15816619 64.305,9.2535 C64.0996656,9.34883381 63.9282507,9.48633243 63.79075,9.666 C63.6532493,9.84566756 63.5505837,10.066582 63.48275,10.32875 C63.4149163,10.590918 63.381,10.8869984 63.381,11.217 C63.381,11.5470016 63.4149163,11.8421654 63.48275,12.1025 C63.5505837,12.3628346 63.6532493,12.5819158 63.79075,12.75975 C63.9282507,12.9375842 64.0996656,13.0741662 64.305,13.1695 C64.5103344,13.2648338 64.7523319,13.3125 65.031,13.3125 L65.031,13.3125 Z M68.892,15.8865 L68.892,8.4285 L69.475,8.4285 C69.614334,8.4285 69.7023332,8.49633265 69.739,8.632 L69.8215,9.292 C70.0598345,9.00233188 70.3320818,8.76950088 70.63825,8.5935 C70.9444182,8.41749912 71.2973313,8.3295 71.697,8.3295 C72.0160016,8.3295 72.3056654,8.39091605 72.566,8.51375 C72.8263346,8.63658395 73.0481657,8.81808213 73.2315,9.05825 C73.4148342,9.29841787 73.5559995,9.59633155 73.655,9.952 C73.7540005,10.3076684 73.8035,10.7164977 73.8035,11.1785 C73.8035,11.5891687 73.7485006,11.9714149 73.6385,12.32525 C73.5284994,12.6790851 73.3708344,12.9852487 73.1655,13.24375 C72.9601656,13.5022513 72.7080848,13.7057493 72.40925,13.85425 C72.1104152,14.0027507 71.7740019,14.077 71.4,14.077 C71.0553316,14.077 70.7610846,14.0201672 70.51725,13.9065 C70.2734154,13.7928328 70.0580009,13.631501 69.871,13.4225 L69.871,15.8865 L68.892,15.8865 Z M71.3725,9.1215 C71.0534984,9.1215 70.7739179,9.1948326 70.53375,9.3415 C70.2935821,9.4881674 70.0726677,9.69533199 69.871,9.963 L69.871,12.658 C70.0506676,12.9000012 70.2477489,13.0704995 70.46225,13.1695 C70.6767511,13.2685005 70.9159987,13.318 71.18,13.318 C71.6970026,13.318 72.0948319,13.1328352 72.3735,12.7625 C72.6521681,12.3921648 72.7915,11.8641701 72.7915,11.1785 C72.7915,10.8154982 72.759417,10.5038346 72.69525,10.2435 C72.631083,9.98316536 72.5385006,9.76958417 72.4175,9.60275 C72.2964994,9.43591583 72.1480009,9.31400038 71.972,9.237 C71.7959991,9.15999961 71.5961678,9.1215 71.3725,9.1215 L71.3725,9.1215 Z M77.1695,8.3405 C77.5031683,8.3405 77.8111653,8.39641611 78.0935,8.50825 C78.3758347,8.62008389 78.6196656,8.78141561 78.825,8.99225 C79.0303344,9.20308439 79.1907494,9.46341512 79.30625,9.77325 C79.4217506,10.0830849 79.4795,10.435998 79.4795,10.832 C79.4795,10.9860008 79.4630002,11.0886664 79.43,11.14 C79.3969998,11.1913336 79.3346671,11.217 79.243,11.217 L75.536,11.217 C75.5433334,11.5690018 75.5909996,11.8751654 75.679,12.1355 C75.7670004,12.3958346 75.8879992,12.6130825 76.042,12.78725 C76.1960008,12.9614175 76.3793323,13.0915829 76.592,13.17775 C76.8046677,13.2639171 77.0429987,13.307 77.307,13.307 C77.5526679,13.307 77.7644158,13.2785836 77.94225,13.22175 C78.1200842,13.1649164 78.273166,13.1035003 78.4015,13.0375 C78.529834,12.9714997 78.6370829,12.9100836 78.72325,12.85325 C78.8094171,12.7964164 78.8836664,12.768 78.946,12.768 C79.0266671,12.768 79.0889998,12.7991664 79.133,12.8615 L79.408,13.219 C79.2869994,13.3656674 79.1421675,13.4930828 78.9735,13.60125 C78.8048325,13.7094172 78.624251,13.798333 78.43175,13.868 C78.239249,13.937667 78.0403344,13.9899165 77.835,14.02475 C77.6296656,14.0595835 77.4261677,14.077 77.2245,14.077 C76.8394981,14.077 76.4847516,14.0119173 76.16025,13.88175 C75.8357484,13.7515827 75.5552512,13.5609179 75.31875,13.30975 C75.0822488,13.0585821 74.8980007,12.7478352 74.766,12.3775 C74.6339993,12.0071648 74.568,11.5818357 74.568,11.1015 C74.568,10.7128314 74.6275827,10.349835 74.74675,10.0125 C74.8659173,9.67516498 75.0373322,9.38275124 75.261,9.13525 C75.4846678,8.88774876 75.7578317,8.69341737 76.0805,8.55225 C76.4031683,8.41108263 76.7661647,8.3405 77.1695,8.3405 L77.1695,8.3405 Z M77.1915,9.061 C76.7184976,9.061 76.3463347,9.19758197 76.075,9.47075 C75.8036653,9.74391803 75.6350003,10.1224976 75.569,10.6065 L78.5995,10.6065 C78.5995,10.3791655 78.5683336,10.1710843 78.506,9.98225 C78.4436664,9.79341572 78.3520006,9.63025069 78.231,9.49275 C78.1099994,9.35524931 77.9624175,9.24891704 77.78825,9.17375 C77.6140825,9.09858296 77.4151678,9.061 77.1915,9.061 L77.1915,9.061 Z M80.728,14 L80.728,8.4285 L81.289,8.4285 C81.3953339,8.4285 81.4686665,8.44866646 81.509,8.489 C81.5493335,8.52933353 81.5768333,8.5989995 81.5915,8.698 L81.6575,9.567 C81.8481676,9.17833139 82.0837486,8.87491776 82.36425,8.65675 C82.6447514,8.43858224 82.9738314,8.3295 83.3515,8.3295 C83.5055008,8.3295 83.6448327,8.34691649 83.7695,8.38175 C83.8941673,8.41658351 84.0096661,8.46516635 84.116,8.5275 L83.9895,9.259 C83.9638332,9.35066712 83.9070004,9.3965 83.819,9.3965 C83.7676664,9.3965 83.6888339,9.37908351 83.5825,9.34425 C83.4761661,9.30941649 83.3276676,9.292 83.137,9.292 C82.7959983,9.292 82.5109178,9.39099901 82.28175,9.589 C82.0525822,9.78700099 81.8610008,10.0748314 81.707,10.4525 L81.707,14 L80.728,14 Z M86.558,6.1185 L87.4435,6.1185 C87.5388338,6.1185 87.6176664,6.14233309 87.68,6.19 C87.7423336,6.2376669 87.7844999,6.2981663 87.8065,6.3715 L89.4345,11.8495 C89.4638335,11.9485005 89.4904165,12.0548328 89.51425,12.1685 C89.5380835,12.2821672 89.5609999,12.4013327 89.583,12.526 C89.6086668,12.4013327 89.6343332,12.2812506 89.66,12.16575 C89.6856668,12.0502494 89.7149998,11.9448338 89.748,11.8495 L91.6015,6.3715 C91.6235001,6.30916635 91.666583,6.25141693 91.73075,6.19825 C91.794917,6.14508307 91.8728329,6.1185 91.9645,6.1185 L92.2725,6.1185 C92.3678338,6.1185 92.4457497,6.14233309 92.50625,6.19 C92.5667503,6.2376669 92.6098332,6.2981663 92.6355,6.3715 L94.478,11.8495 C94.5440003,12.0401676 94.6026664,12.2583321 94.654,12.504 C94.6760001,12.3829994 94.6961666,12.2675005 94.7145,12.1575 C94.7328334,12.0474994 94.7566665,11.9448338 94.786,11.8495 L96.4195,6.3715 C96.4378334,6.30549967 96.479083,6.24683359 96.54325,6.1955 C96.607417,6.14416641 96.6853329,6.1185 96.777,6.1185 L97.6075,6.1185 L95.149,14 L94.192,14 L92.1955,7.9885 C92.1551665,7.87483276 92.1185002,7.74283408 92.0855,7.5925 C92.0671666,7.6658337 92.0497501,7.73641633 92.03325,7.80425 C92.0167499,7.87208367 91.9993334,7.93349972 91.981,7.9885 L89.9735,14 L89.0165,14 L86.558,6.1185 Z M100.572,8.3405 C100.979002,8.3405 101.346582,8.40833265 101.67475,8.544 C102.002918,8.67966734 102.281582,8.87216542 102.51075,9.1215 C102.739918,9.37083458 102.915916,9.6724149 103.03875,10.02625 C103.161584,10.3800851 103.223,10.7751645 103.223,11.2115 C103.223,11.6515022 103.161584,12.0474982 103.03875,12.3995 C102.915916,12.7515018 102.739918,13.0521654 102.51075,13.3015 C102.281582,13.5508346 102.002918,13.742416 101.67475,13.87625 C101.346582,14.010084 100.979002,14.077 100.572,14.077 C100.164998,14.077 99.7974183,14.010084 99.46925,13.87625 C99.1410817,13.742416 98.8615012,13.5508346 98.6305,13.3015 C98.3994988,13.0521654 98.2216673,12.7515018 98.097,12.3995 C97.9723327,12.0474982 97.91,11.6515022 97.91,11.2115 C97.91,10.7751645 97.9723327,10.3800851 98.097,10.02625 C98.2216673,9.6724149 98.3994988,9.37083458 98.6305,9.1215 C98.8615012,8.87216542 99.1410817,8.67966734 99.46925,8.544 C99.7974183,8.40833265 100.164998,8.3405 100.572,8.3405 L100.572,8.3405 Z M100.572,13.3125 C101.122003,13.3125 101.532665,13.1282518 101.804,12.75975 C102.075335,12.3912482 102.211,11.8770033 102.211,11.217 C102.211,10.55333 102.075335,10.0363352 101.804,9.666 C101.532665,9.29566481 101.122003,9.1105 100.572,9.1105 C100.293332,9.1105 100.051334,9.15816619 99.846,9.2535 C99.6406656,9.34883381 99.4692507,9.48633243 99.33175,9.666 C99.1942493,9.84566756 99.0915837,10.066582 99.02375,10.32875 C98.9559163,10.590918 98.922,10.8869984 98.922,11.217 C98.922,11.5470016 98.9559163,11.8421654 99.02375,12.1025 C99.0915837,12.3628346 99.1942493,12.5819158 99.33175,12.75975 C99.4692507,12.9375842 99.6406656,13.0741662 99.846,13.1695 C100.051334,13.2648338 100.293332,13.3125 100.572,13.3125 L100.572,13.3125 Z M104.433,14 L104.433,8.4285 L104.994,8.4285 C105.100334,8.4285 105.173666,8.44866646 105.214,8.489 C105.254334,8.52933353 105.281833,8.5989995 105.2965,8.698 L105.3625,9.567 C105.553168,9.17833139 105.788749,8.87491776 106.06925,8.65675 C106.349751,8.43858224 106.678831,8.3295 107.0565,8.3295 C107.210501,8.3295 107.349833,8.34691649 107.4745,8.38175 C107.599167,8.41658351 107.714666,8.46516635 107.821,8.5275 L107.6945,9.259 C107.668833,9.35066712 107.612,9.3965 107.524,9.3965 C107.472666,9.3965 107.393834,9.37908351 107.2875,9.34425 C107.181166,9.30941649 107.032668,9.292 106.842,9.292 C106.500998,9.292 106.215918,9.39099901 105.98675,9.589 C105.757582,9.78700099 105.566001,10.0748314 105.412,10.4525 L105.412,14 L104.433,14 Z M109.8835,5.8985 L109.8835,10.667 L110.1365,10.667 C110.209834,10.667 110.270333,10.6569168 110.318,10.63675 C110.365667,10.6165832 110.418833,10.5753336 110.4775,10.513 L112.2375,8.6265 C112.2925,8.56783304 112.3475,8.52016685 112.4025,8.4835 C112.4575,8.44683315 112.530833,8.4285 112.6225,8.4285 L113.5135,8.4285 L111.462,10.612 C111.410666,10.6743336 111.36025,10.7293331 111.31075,10.777 C111.26125,10.8246669 111.205334,10.8668332 111.143,10.9035 C111.209,10.9475002 111.268583,10.9979164 111.32175,11.05475 C111.374917,11.1115836 111.425333,11.1766663 111.473,11.25 L113.651,14 L112.771,14 C112.690333,14 112.621584,13.9844168 112.56475,13.95325 C112.507916,13.9220832 112.453834,13.8735003 112.4025,13.8075 L110.571,11.525 C110.516,11.4479996 110.461,11.3975835 110.406,11.37375 C110.351,11.3499165 110.268501,11.338 110.1585,11.338 L109.8835,11.338 L109.8835,14 L108.899,14 L108.899,5.8985 L109.8835,5.8985 Z M117.82,9.347 C117.776,9.42766707 117.708167,9.468 117.6165,9.468 C117.5615,9.468 117.499167,9.44783353 117.4295,9.4075 C117.359833,9.36716646 117.274584,9.32225025 117.17375,9.27275 C117.072916,9.22324975 116.952834,9.17741688 116.8135,9.13525 C116.674166,9.09308312 116.509168,9.072 116.3185,9.072 C116.153499,9.072 116.005001,9.09308312 115.873,9.13525 C115.740999,9.17741688 115.62825,9.2351663 115.53475,9.3085 C115.44125,9.3818337 115.36975,9.46708285 115.32025,9.56425 C115.27075,9.66141715 115.246,9.76683276 115.246,9.8805 C115.246,10.0235007 115.28725,10.1426662 115.36975,10.238 C115.45225,10.3333338 115.561333,10.415833 115.697,10.4855 C115.832667,10.555167 115.986666,10.6165831 116.159,10.66975 C116.331334,10.7229169 116.508249,10.7797497 116.68975,10.84025 C116.871251,10.9007503 117.048166,10.9676663 117.2205,11.041 C117.392834,11.1143337 117.546833,11.2059994 117.6825,11.316 C117.818167,11.4260005 117.92725,11.5607492 118.00975,11.72025 C118.09225,11.8797508 118.1335,12.0713322 118.1335,12.295 C118.1335,12.5516679 118.087667,12.7890822 117.996,13.00725 C117.904333,13.2254178 117.768668,13.4142492 117.589,13.57375 C117.409332,13.7332508 117.189335,13.8588329 116.929,13.9505 C116.668665,14.0421671 116.368002,14.088 116.027,14.088 C115.638331,14.088 115.286335,14.0247506 114.971,13.89825 C114.655665,13.7717494 114.388001,13.609501 114.168,13.4115 L114.399,13.0375 C114.428333,12.9898331 114.463166,12.9531668 114.5035,12.9275 C114.543834,12.9018332 114.597,12.889 114.663,12.889 C114.729,12.889 114.798666,12.9146664 114.872,12.966 C114.945334,13.0173336 115.034249,13.0741664 115.13875,13.1365 C115.243251,13.1988336 115.369749,13.2556664 115.51825,13.307 C115.666751,13.3583336 115.852832,13.384 116.0765,13.384 C116.267168,13.384 116.433999,13.3592502 116.577,13.30975 C116.720001,13.2602498 116.839166,13.1933338 116.9345,13.109 C117.029834,13.0246662 117.100416,12.9275005 117.14625,12.8175 C117.192084,12.7074994 117.215,12.5901673 117.215,12.4655 C117.215,12.3114992 117.17375,12.1840838 117.09125,12.08325 C117.00875,11.9824162 116.899667,11.8962504 116.764,11.82475 C116.628333,11.7532496 116.473418,11.6909169 116.29925,11.63775 C116.125082,11.5845831 115.947251,11.528667 115.76575,11.47 C115.584249,11.411333 115.406418,11.344417 115.23225,11.26925 C115.058082,11.194083 114.903167,11.0996672 114.7675,10.986 C114.631833,10.8723328 114.52275,10.7320842 114.44025,10.56525 C114.35775,10.3984158 114.3165,10.1958345 114.3165,9.9575 C114.3165,9.74483227 114.3605,9.54041765 114.4485,9.34425 C114.5365,9.14808235 114.664832,8.97575074 114.8335,8.82725 C115.002168,8.67874926 115.209332,8.56050044 115.455,8.4725 C115.700668,8.38449956 115.981165,8.3405 116.2965,8.3405 C116.663168,8.3405 116.992249,8.39824942 117.28375,8.51375 C117.575251,8.62925058 117.827332,8.78783232 118.04,8.9895 L117.82,9.347 Z M119.404,15.8865 L119.404,8.4285 L119.987,8.4285 C120.126334,8.4285 120.214333,8.49633265 120.251,8.632 L120.3335,9.292 C120.571835,9.00233188 120.844082,8.76950088 121.15025,8.5935 C121.456418,8.41749912 121.809331,8.3295 122.209,8.3295 C122.528002,8.3295 122.817665,8.39091605 123.078,8.51375 C123.338335,8.63658395 123.560166,8.81808213 123.7435,9.05825 C123.926834,9.29841787 124.068,9.59633155 124.167,9.952 C124.266,10.3076684 124.3155,10.7164977 124.3155,11.1785 C124.3155,11.5891687 124.260501,11.9714149 124.1505,12.32525 C124.040499,12.6790851 123.882834,12.9852487 123.6775,13.24375 C123.472166,13.5022513 123.220085,13.7057493 122.92125,13.85425 C122.622415,14.0027507 122.286002,14.077 121.912,14.077 C121.567332,14.077 121.273085,14.0201672 121.02925,13.9065 C120.785415,13.7928328 120.570001,13.631501 120.383,13.4225 L120.383,15.8865 L119.404,15.8865 Z M121.8845,9.1215 C121.565498,9.1215 121.285918,9.1948326 121.04575,9.3415 C120.805582,9.4881674 120.584668,9.69533199 120.383,9.963 L120.383,12.658 C120.562668,12.9000012 120.759749,13.0704995 120.97425,13.1695 C121.188751,13.2685005 121.427999,13.318 121.692,13.318 C122.209003,13.318 122.606832,13.1328352 122.8855,12.7625 C123.164168,12.3921648 123.3035,11.8641701 123.3035,11.1785 C123.3035,10.8154982 123.271417,10.5038346 123.20725,10.2435 C123.143083,9.98316536 123.050501,9.76958417 122.9295,9.60275 C122.808499,9.43591583 122.660001,9.31400038 122.484,9.237 C122.307999,9.15999961 122.108168,9.1215 121.8845,9.1215 L121.8845,9.1215 Z M129.568,14 L129.1335,14 C129.038166,14 128.961167,13.9853335 128.9025,13.956 C128.843833,13.9266665 128.805333,13.8643338 128.787,13.769 L128.677,13.252 C128.530333,13.3840007 128.387334,13.5022495 128.248,13.60675 C128.108666,13.7112505 127.962001,13.7992496 127.808,13.87075 C127.653999,13.9422504 127.489918,13.9963331 127.31575,14.033 C127.141582,14.0696668 126.948168,14.088 126.7355,14.088 C126.519166,14.088 126.316584,14.0577503 126.12775,13.99725 C125.938916,13.9367497 125.774834,13.8460006 125.6355,13.725 C125.496166,13.6039994 125.38525,13.4509176 125.30275,13.26575 C125.22025,13.0805824 125.179,12.8615013 125.179,12.6085 C125.179,12.3884989 125.239499,12.176751 125.3605,11.97325 C125.481501,11.769749 125.676749,11.5891675 125.94625,11.4315 C126.215751,11.2738325 126.568664,11.1445838 127.005,11.04375 C127.441336,10.9429162 127.97483,10.8851667 128.6055,10.8705 L128.6055,10.436 C128.6055,10.0033312 128.512918,9.67608444 128.32775,9.45425 C128.142582,9.23241556 127.868502,9.1215 127.5055,9.1215 C127.267165,9.1215 127.066417,9.1517497 126.90325,9.21225 C126.740083,9.2727503 126.598917,9.34058296 126.47975,9.41575 C126.360583,9.49091704 126.257917,9.5587497 126.17175,9.61925 C126.085583,9.6797503 126.000334,9.71 125.916,9.71 C125.85,9.71 125.79225,9.69258351 125.74275,9.65775 C125.69325,9.62291649 125.653833,9.57983359 125.6245,9.5285 L125.4485,9.215 C125.756502,8.91799851 126.088332,8.6961674 126.444,8.5495 C126.799668,8.4028326 127.193831,8.3295 127.6265,8.3295 C127.938168,8.3295 128.214999,8.38083282 128.457,8.4835 C128.699001,8.58616718 128.902499,8.72916575 129.0675,8.9125 C129.232501,9.09583425 129.357166,9.31766536 129.4415,9.578 C129.525834,9.83833463 129.568,10.1243318 129.568,10.436 L129.568,14 Z M127.027,13.4005 C127.199334,13.4005 127.356999,13.3830835 127.5,13.34825 C127.643001,13.3134165 127.777749,13.263917 127.90425,13.19975 C128.030751,13.135583 128.151749,13.0576671 128.26725,12.966 C128.382751,12.8743329 128.495499,12.7698339 128.6055,12.6525 L128.6055,11.492 C128.154498,11.5066667 127.771335,11.5424164 127.456,11.59925 C127.140665,11.6560836 126.884001,11.7303329 126.686,11.822 C126.487999,11.9136671 126.344084,12.0218327 126.25425,12.1465 C126.164416,12.2711673 126.1195,12.4104992 126.1195,12.5645 C126.1195,12.7111674 126.143333,12.8376661 126.191,12.944 C126.238667,13.0503339 126.302833,13.1374163 126.3835,13.20525 C126.464167,13.2730837 126.559499,13.3225832 126.6695,13.35375 C126.779501,13.3849168 126.898666,13.4005 127.027,13.4005 L127.027,13.4005 Z M134.8535,9.4185 C134.824167,9.45883353 134.794833,9.48999989 134.7655,9.512 C134.736167,9.53400011 134.694,9.545 134.639,9.545 C134.584,9.545 134.524417,9.52208356 134.46025,9.47625 C134.396083,9.43041644 134.3145,9.38000027 134.2155,9.325 C134.1165,9.26999972 133.996417,9.21958356 133.85525,9.17375 C133.714083,9.12791644 133.540834,9.105 133.3355,9.105 C133.064165,9.105 132.824001,9.15358285 132.615,9.25075 C132.405999,9.34791715 132.230917,9.48816575 132.08975,9.6715 C131.948583,9.85483425 131.84225,10.0766654 131.77075,10.337 C131.69925,10.5973346 131.6635,10.8888317 131.6635,11.2115 C131.6635,11.548835 131.702,11.848582 131.779,12.11075 C131.856,12.372918 131.964166,12.5929158 132.1035,12.77075 C132.242834,12.9485842 132.412416,13.0842495 132.61225,13.17775 C132.812084,13.2712505 133.036665,13.318 133.286,13.318 C133.524335,13.318 133.720499,13.2895836 133.8745,13.23275 C134.028501,13.1759164 134.156833,13.112667 134.2595,13.043 C134.362167,12.973333 134.4465,12.9100836 134.5125,12.85325 C134.5785,12.7964164 134.6445,12.768 134.7105,12.768 C134.794834,12.768 134.857166,12.7991664 134.8975,12.8615 L135.1725,13.219 C134.930499,13.5160015 134.628002,13.7332493 134.265,13.87075 C133.901998,14.0082507 133.518835,14.077 133.1155,14.077 C132.767165,14.077 132.443585,14.012834 132.14475,13.8845 C131.845915,13.756166 131.586501,13.5700846 131.3665,13.32625 C131.146499,13.0824154 130.973251,12.7826684 130.84675,12.427 C130.720249,12.0713316 130.657,11.6661689 130.657,11.2115 C130.657,10.7971646 130.714749,10.4140018 130.83025,10.062 C130.945751,9.70999824 131.114416,9.40658461 131.33625,9.15175 C131.558084,8.89691539 131.832165,8.69800071 132.1585,8.555 C132.484835,8.41199928 132.858831,8.3405 133.2805,8.3405 C133.669169,8.3405 134.013832,8.40374937 134.3145,8.53025 C134.615168,8.65675063 134.880999,8.83549884 135.112,9.0665 L134.8535,9.4185 Z M138.3955,8.3405 C138.729168,8.3405 139.037165,8.39641611 139.3195,8.50825 C139.601835,8.62008389 139.845666,8.78141561 140.051,8.99225 C140.256334,9.20308439 140.416749,9.46341512 140.53225,9.77325 C140.647751,10.0830849 140.7055,10.435998 140.7055,10.832 C140.7055,10.9860008 140.689,11.0886664 140.656,11.14 C140.623,11.1913336 140.560667,11.217 140.469,11.217 L136.762,11.217 C136.769333,11.5690018 136.817,11.8751654 136.905,12.1355 C136.993,12.3958346 137.113999,12.6130825 137.268,12.78725 C137.422001,12.9614175 137.605332,13.0915829 137.818,13.17775 C138.030668,13.2639171 138.268999,13.307 138.533,13.307 C138.778668,13.307 138.990416,13.2785836 139.16825,13.22175 C139.346084,13.1649164 139.499166,13.1035003 139.6275,13.0375 C139.755834,12.9714997 139.863083,12.9100836 139.94925,12.85325 C140.035417,12.7964164 140.109666,12.768 140.172,12.768 C140.252667,12.768 140.315,12.7991664 140.359,12.8615 L140.634,13.219 C140.512999,13.3656674 140.368168,13.4930828 140.1995,13.60125 C140.030832,13.7094172 139.850251,13.798333 139.65775,13.868 C139.465249,13.937667 139.266334,13.9899165 139.061,14.02475 C138.855666,14.0595835 138.652168,14.077 138.4505,14.077 C138.065498,14.077 137.710752,14.0119173 137.38625,13.88175 C137.061748,13.7515827 136.781251,13.5609179 136.54475,13.30975 C136.308249,13.0585821 136.124001,12.7478352 135.992,12.3775 C135.859999,12.0071648 135.794,11.5818357 135.794,11.1015 C135.794,10.7128314 135.853583,10.349835 135.97275,10.0125 C136.091917,9.67516498 136.263332,9.38275124 136.487,9.13525 C136.710668,8.88774876 136.983832,8.69341737 137.3065,8.55225 C137.629168,8.41108263 137.992165,8.3405 138.3955,8.3405 L138.3955,8.3405 Z M138.4175,9.061 C137.944498,9.061 137.572335,9.19758197 137.301,9.47075 C137.029665,9.74391803 136.861,10.1224976 136.795,10.6065 L139.8255,10.6065 C139.8255,10.3791655 139.794334,10.1710843 139.732,9.98225 C139.669666,9.79341572 139.578001,9.63025069 139.457,9.49275 C139.335999,9.35524931 139.188418,9.24891704 139.01425,9.17375 C138.840082,9.09858296 138.641168,9.061 138.4175,9.061 L138.4175,9.061 Z" id="Developer-Workspace" fill="#FFFFFF" fill-rule="nonzero"/> + </g> + </g> + </g> +</svg> \ No newline at end of file diff --git a/modules/end-user-guide/images/extensibility/che-theia-plug-in-lifecycle.svg b/modules/end-user-guide/images/extensibility/che-theia-plug-in-lifecycle.svg deleted file mode 100644 index 887264678e..0000000000 --- a/modules/end-user-guide/images/extensibility/che-theia-plug-in-lifecycle.svg +++ /dev/null @@ -1 +0,0 @@ -<svg id="a09b9d5e-b60f-4a33-9d6b-722309d3a9b0" data-name="artwork" xmlns="http://www.w3.org/2000/svg" width="760" height="609.123"><defs><style>.af4260a3-0ab4-4592-b0e4-2ae43d2cdbf7{fill:#f3f3f3}.bc806f14-d82d-4a3c-bca5-3de433ba80f8{fill:#dedede}.a4208f3a-203a-436e-a383-27501fc47bb8{fill:#e8e8e8}.f7e0d3cd-2bcb-4a6c-898e-d6f0ebcded07{font-size:12px;font-family:RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif;font-weight:700}.a6823188-ea3a-4166-a8e5-1b1e27a9c647,.f7e0d3cd-2bcb-4a6c-898e-d6f0ebcded07{fill:#151515}.a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b,.b842441e-2f8c-46bc-b5ec-803e13696a68,.f1d727a1-fe40-47a7-a316-a3e5e32da839{fill:none}.a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b{stroke:#06c}.a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b,.b842441e-2f8c-46bc-b5ec-803e13696a68,.f1d727a1-fe40-47a7-a316-a3e5e32da839{stroke-linecap:round;stroke-linejoin:round}.a8433ddf-6d12-4f5e-909e-718d76d8057e{fill:#06c}.a6823188-ea3a-4166-a8e5-1b1e27a9c647{font-size:11px;font-family:RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif;font-weight:500}.b842441e-2f8c-46bc-b5ec-803e13696a68,.f1d727a1-fe40-47a7-a316-a3e5e32da839{stroke:#b9b9b9}.b842441e-2f8c-46bc-b5ec-803e13696a68{stroke-dasharray:1.889 1.889}</style></defs><path class="af4260a3-0ab4-4592-b0e4-2ae43d2cdbf7" d="M0 16h119v553.45H0zM129 16h119v553.45H129zM258 16h119v553.45H258zM387 16h119v553.45H387zM516 16h119v553.45H516zM645 16h115v553.45H645z"/><path class="bc806f14-d82d-4a3c-bca5-3de433ba80f8" d="M10 137.804h109v30H10zM645 137.804h105v30H645z"/><path class="a4208f3a-203a-436e-a383-27501fc47bb8" d="M635 137.804h10v30h-10zM506 137.804h10v30h-10zM377 137.804h10v30h-10zM248 137.804h10v30h-10zM119 137.804h10v30h-10z"/><path class="bc806f14-d82d-4a3c-bca5-3de433ba80f8" d="M129 137.804h119v30H129zM258 137.822h119v30H258zM387 137.822h119v30H387zM516 137.822h119v30H516z"/><text class="f7e0d3cd-2bcb-4a6c-898e-d6f0ebcded07" transform="translate(10 40.788)">User</text><text class="f7e0d3cd-2bcb-4a6c-898e-d6f0ebcded07" transform="translate(139.167 40.788)">Server</text><text class="f7e0d3cd-2bcb-4a6c-898e-d6f0ebcded07" transform="translate(268.334 40.787)">Plug-in registry</text><text class="f7e0d3cd-2bcb-4a6c-898e-d6f0ebcded07" transform="translate(397.5 40.788)">Workspace</text><text class="f7e0d3cd-2bcb-4a6c-898e-d6f0ebcded07" transform="translate(526.5 40.788)">Plug-in</text><text class="f7e0d3cd-2bcb-4a6c-898e-d6f0ebcded07" transform="translate(655.5 40.788)">Broker</text><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M568.324 81.901H10.5"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M566.865 76.914l8.635 4.987-8.635 4.986v-9.973z"/><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(10 74.948)">Create plug-in</text><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M181.324 243.351H10.5"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M179.865 238.365l8.635 4.986-8.635 4.986v-9.972z"/><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(10 236.398)">Start workspace</text><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M310.407 278.351h-170.74"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M308.948 273.365l8.635 4.986-8.635 4.986v-9.972z"/><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(139.167 271.398)">Find plug-in in registry</text><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M237.75 544.463H66.676"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M68.135 539.477l-8.635 4.986 8.635 4.987v-9.973z"/><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(130.254 537.511)">Workspace is started</text><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M439.324 208.485H10.5"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M437.865 203.499l8.635 4.986-8.635 4.986v-9.972z"/><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(10 201.532)">Add plug-in to workspace</text><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(9.5 109.947)">Publish plug-in metadata</text><g><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M10 116.901h300.24"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M308.781 121.887l8.636-4.986-8.636-4.987v9.973z"/></g><path fill="#d9e8f7" d="M139.25 293.351h98.5v45h-98.5z"/><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(149.25 312.613)">Find broker<tspan x="0" y="12">for plug-in</tspan></text><g><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M694.824 368.463H139.917"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M693.365 363.477l8.635 4.986-8.635 4.987v-9.973z"/></g><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(139.417 361.51)">Start broker and pass plug-in metadata</text><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(627.881 396.511)">Parse plug-in metadata</text><g><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M582.676 403.463H748.5"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M584.135 408.45l-8.635-4.987 8.635-4.986v9.973z"/></g><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(622.557 431.511)">Download files if needed<tspan x="-15.125" y="18">Copy plug-in files if needed</tspan><tspan x="-62.083" y="36">Find or generate workspace changes</tspan></text><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(672.936 502.511)">Send response</text><g><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M195.676 509.463H748.5"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M197.135 514.45l-8.635-4.987 8.635-4.986v9.973z"/></g><g><path class="a4f7a91a-3f9f-4d76-aaa0-e4ff85438a9b" d="M453.676 474.463H748.5"/><path class="a8433ddf-6d12-4f5e-909e-718d76d8057e" d="M455.135 479.45l-8.635-4.987 8.635-4.986v9.973z"/></g><g><path class="f1d727a1-fe40-47a7-a316-a3e5e32da839" d="M320.417 116.901h1.5"/><path class="b842441e-2f8c-46bc-b5ec-803e13696a68" d="M323.806 116.901h2.833"/><path class="f1d727a1-fe40-47a7-a316-a3e5e32da839" d="M327.583 116.901h1.5v1.5"/><path stroke-dasharray="2.99 2.99" stroke="#b9b9b9" stroke-linecap="round" stroke-linejoin="round" fill="none" d="M329.083 121.39v153.966"/><path class="f1d727a1-fe40-47a7-a316-a3e5e32da839" d="M329.083 276.851v1.5h-1.5"/><path class="b842441e-2f8c-46bc-b5ec-803e13696a68" d="M325.695 278.351h-2.834"/><path class="f1d727a1-fe40-47a7-a316-a3e5e32da839" d="M321.917 278.351h-1.5"/></g><path class="bc806f14-d82d-4a3c-bca5-3de433ba80f8" d="M272.985 144.068h69.514v17.507h-69.514z"/><text class="a6823188-ea3a-4166-a8e5-1b1e27a9c647" transform="translate(294.939 157.128)">Plug-in creation process finished</text><g><text transform="translate(668.302 592.141)" font-size="10" font-family="RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif" fill="#f3f3f3">124_Codeready_1120</text><path fill="none" d="M0 569.123h760v40H0z"/></g></svg> \ No newline at end of file diff --git a/modules/end-user-guide/images/extensibility/client-server-side-plug-ins.svg b/modules/end-user-guide/images/extensibility/client-server-side-plug-ins.svg deleted file mode 100644 index 02b40ae4f9..0000000000 --- a/modules/end-user-guide/images/extensibility/client-server-side-plug-ins.svg +++ /dev/null @@ -1 +0,0 @@ -<svg id="a8682e74-24d3-4691-84b8-bf73ef96de53" data-name="artwork" xmlns="http://www.w3.org/2000/svg" width="760" height="306.128"><defs><style>.b2bf904d-2ac2-46a4-8251-f5249a6c6571{fill:#e8e8e8}.b30099dd-ff73-47ee-9ac1-50213ddffbea{font-size:16px}.a05e1dc7-dea0-42b4-9512-01b67be3a851,.a3a555f9-78aa-41b6-a243-2e8cc51bb93f,.b30099dd-ff73-47ee-9ac1-50213ddffbea,.b9e59d28-6675-42db-9183-8c439532a3e4,.e3d967a2-cc90-4faf-ba4a-1ac40f5e4042{fill:#151515}.b30099dd-ff73-47ee-9ac1-50213ddffbea,.e3d967a2-cc90-4faf-ba4a-1ac40f5e4042{font-family:RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif;font-weight:700}.e3d2c72e-d252-42b7-884c-2cf3bae36e69,.fc3150d8-4e9c-4e70-8fc8-9e6c2ec3bfe1{fill:none}.fc3150d8-4e9c-4e70-8fc8-9e6c2ec3bfe1{stroke:#151515;stroke-linecap:round;stroke-linejoin:round}.f1813401-186e-4d4d-af92-68d74ece3648{fill:#fff}.a69140f5-535f-4134-becd-e68545a2fa95{fill:#06c}.e3d2c72e-d252-42b7-884c-2cf3bae36e69{stroke:#f3f3f3;stroke-miterlimit:10;stroke-width:1.5px}.a3a555f9-78aa-41b6-a243-2e8cc51bb93f,.e3d967a2-cc90-4faf-ba4a-1ac40f5e4042{font-size:12px}.a3a555f9-78aa-41b6-a243-2e8cc51bb93f,.b9e59d28-6675-42db-9183-8c439532a3e4{font-family:RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif}.a3a555f9-78aa-41b6-a243-2e8cc51bb93f{font-weight:500}.b9e59d28-6675-42db-9183-8c439532a3e4{font-size:11px;font-style:italic}</style></defs><path class="b2bf904d-2ac2-46a4-8251-f5249a6c6571" d="M72.436 16H317.5v250.128H72.436z"/><text class="b30099dd-ff73-47ee-9ac1-50213ddffbea" transform="translate(92.5 49.536)">Browser</text><path class="fc3150d8-4e9c-4e70-8fc8-9e6c2ec3bfe1" d="M327.176 143.064h105.627"/><path class="a05e1dc7-dea0-42b4-9512-01b67be3a851" d="M328.635 148.05L320 143.064l8.635-4.986v9.972zM431.344 148.05l8.635-4.986-8.635-4.986v9.972z"/><path class="f1813401-186e-4d4d-af92-68d74ece3648" d="M93 130.058h204v115.5H93z"/><path class="a69140f5-535f-4134-becd-e68545a2fa95" d="M296.5 130.558v114.5h-203v-114.5h203m1-1h-205v116.5h205v-116.5z"/><path class="e3d2c72e-d252-42b7-884c-2cf3bae36e69" d="M282.5 181.058v50h-165"/><path class="e3d2c72e-d252-42b7-884c-2cf3bae36e69" d="M277.5 176.058v50h-165"/><path class="b2bf904d-2ac2-46a4-8251-f5249a6c6571" d="M107.5 171.058h165v50h-165z"/><text class="e3d967a2-cc90-4faf-ba4a-1ac40f5e4042" transform="translate(107.5 154.662)">Web worker</text><text class="a3a555f9-78aa-41b6-a243-2e8cc51bb93f" transform="translate(166.619 199.383)">Plug-ins</text><path class="f1813401-186e-4d4d-af92-68d74ece3648" d="M92.5 69.628h205v50h-205z"/><text class="a3a555f9-78aa-41b6-a243-2e8cc51bb93f" transform="translate(140.923 97.953)">Extension manager</text><path class="fc3150d8-4e9c-4e70-8fc8-9e6c2ec3bfe1" d="M62.76 93.064H28.75v102.994h54.074"/><path class="a05e1dc7-dea0-42b4-9512-01b67be3a851" d="M61.301 88.078l8.635 4.986-8.635 4.986v-9.972zM81.365 201.044L90 196.058l-8.635-4.986v9.972z"/><path class="f1813401-186e-4d4d-af92-68d74ece3648" d="M15.686 134.955h26.129v19.212H15.686z"/><text class="b9e59d28-6675-42db-9183-8c439532a3e4" transform="translate(1.265 147.685)">Plug-in API</text><text class="b9e59d28-6675-42db-9183-8c439532a3e4" transform="translate(352.765 136.188)">JSON RPC</text><path class="b2bf904d-2ac2-46a4-8251-f5249a6c6571" d="M442.479 16h245.064v250.128H442.479z"/><text class="b30099dd-ff73-47ee-9ac1-50213ddffbea" transform="translate(462.543 49.536)">Server</text><path class="f1813401-186e-4d4d-af92-68d74ece3648" d="M463.043 130.058h204v115.5h-204z"/><path class="a69140f5-535f-4134-becd-e68545a2fa95" d="M666.543 130.558v114.5h-203v-114.5h203m1-1h-205v116.5h205v-116.5z"/><path class="e3d2c72e-d252-42b7-884c-2cf3bae36e69" d="M652.543 181.058v50h-165"/><path class="e3d2c72e-d252-42b7-884c-2cf3bae36e69" d="M647.543 176.058v50h-165"/><path class="b2bf904d-2ac2-46a4-8251-f5249a6c6571" d="M477.543 171.058h165v50h-165z"/><text class="e3d967a2-cc90-4faf-ba4a-1ac40f5e4042" transform="translate(477.543 154.662)">Node.js</text><text class="a3a555f9-78aa-41b6-a243-2e8cc51bb93f" transform="translate(536.662 199.383)">Plug-ins</text><g><path class="fc3150d8-4e9c-4e70-8fc8-9e6c2ec3bfe1" d="M697.283 93.064h34.01v102.994h-54.074"/><path class="a05e1dc7-dea0-42b4-9512-01b67be3a851" d="M698.742 98.05l-8.635-4.986 8.635-4.986v9.972zM678.678 191.072l-8.635 4.986 8.635 4.986v-9.972z"/></g><path class="f1813401-186e-4d4d-af92-68d74ece3648" d="M718.229 134.955h26.129v19.212h-26.129z"/><text class="b9e59d28-6675-42db-9183-8c439532a3e4" transform="translate(704.397 147.685)">Plug-in API</text><g><text transform="translate(668.302 289.145)" font-size="10" fill="#f3f3f3" font-family="RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif">124_Codeready_1120</text><path fill="none" d="M0 266.128h760v40H0z"/></g></svg> \ No newline at end of file diff --git a/modules/end-user-guide/images/extensibility/extending-che.svg b/modules/end-user-guide/images/extensibility/extending-che.svg deleted file mode 100644 index c3d966a930..0000000000 --- a/modules/end-user-guide/images/extensibility/extending-che.svg +++ /dev/null @@ -1 +0,0 @@ -<svg id="e9cc0aff-8d5a-4edb-9176-4ab5c031c17a" data-name="artwork" xmlns="http://www.w3.org/2000/svg" width="760" height="663.095"><defs><style>.ae1a9c51-8cc8-4f92-8560-819c6474005d{fill:#e8e8e8}.ff2fbe5b-ebee-4b4c-a2ff-bb260cbfb415{fill:#06c}.a8ed803d-1b25-4175-9ba8-23261f084349{font-size:14px}.a0f708e6-eacc-4317-b485-eae233fef801,.a8ed803d-1b25-4175-9ba8-23261f084349,.aae8fa3c-4181-4db3-84fa-b687267c0008,.b9258f43-dcdd-4440-bb0a-75bf6383b075,.e481f048-b2bd-46c3-a38b-eec0a7b01bf5{fill:#151515}.a8ed803d-1b25-4175-9ba8-23261f084349,.b9258f43-dcdd-4440-bb0a-75bf6383b075{font-family:RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif;font-weight:700}.a0f708e6-eacc-4317-b485-eae233fef801,.e481f048-b2bd-46c3-a38b-eec0a7b01bf5{font-size:11px}.a0f708e6-eacc-4317-b485-eae233fef801{font-family:RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif;font-weight:500}.e9be48c9-f78f-43b6-886a-e8e981d3726c{fill:#fff}.b9258f43-dcdd-4440-bb0a-75bf6383b075{font-size:12px}.eb2626aa-763e-49fa-9ce9-5dc7bdfb45df{fill:#f3f3f3}.ac6dc3f2-f4a3-4676-9161-f0c5964ddb68,.ae493e8a-2f5c-4d25-938d-244f3617af91,.bb417a5a-3cef-46d9-a25a-8d833e949245,.bd4d2167-a066-4b2c-92b5-8bf131bb3d12,.e2f6f820-405c-433b-9156-d741b7b1f396,.ed94dbba-d063-4926-a3e7-3458631f60ad,.ff41825e-1b9c-467a-9c12-c65b4082b685{fill:none}.bb417a5a-3cef-46d9-a25a-8d833e949245,.ff41825e-1b9c-467a-9c12-c65b4082b685{stroke:#06c}.ac6dc3f2-f4a3-4676-9161-f0c5964ddb68,.ae493e8a-2f5c-4d25-938d-244f3617af91,.bb417a5a-3cef-46d9-a25a-8d833e949245,.bd4d2167-a066-4b2c-92b5-8bf131bb3d12,.e2f6f820-405c-433b-9156-d741b7b1f396,.ed94dbba-d063-4926-a3e7-3458631f60ad,.ff41825e-1b9c-467a-9c12-c65b4082b685{stroke-linecap:round;stroke-linejoin:round}.ff41825e-1b9c-467a-9c12-c65b4082b685{stroke-dasharray:2.991 2.991}.ed94dbba-d063-4926-a3e7-3458631f60ad{stroke:#fff;stroke-width:8px}.e2f6f820-405c-433b-9156-d741b7b1f396{stroke:#151515}.ac6dc3f2-f4a3-4676-9161-f0c5964ddb68,.ae493e8a-2f5c-4d25-938d-244f3617af91,.bd4d2167-a066-4b2c-92b5-8bf131bb3d12{stroke:#e8e8e8}.ae493e8a-2f5c-4d25-938d-244f3617af91{stroke-dasharray:2.96 2.96}.ac6dc3f2-f4a3-4676-9161-f0c5964ddb68{stroke-dasharray:3 3}.e481f048-b2bd-46c3-a38b-eec0a7b01bf5{font-family:RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif;font-style:italic}</style></defs><path class="ae1a9c51-8cc8-4f92-8560-819c6474005d" d="M9.936 196.083h740.128v417.076H9.936z"/><path class="ff2fbe5b-ebee-4b4c-a2ff-bb260cbfb415" d="M758.5 187.647V621.6H1.5V187.647h757m1.5-1.5H0V623.1h760V186.147z"/><path class="ae1a9c51-8cc8-4f92-8560-819c6474005d" d="M759 17v128.364H1V17h758m1-1H0v130.364h760V16z"/><text class="a8ed803d-1b25-4175-9ba8-23261f084349" transform="translate(19.999 46.66)">Workspaces</text><path class="ae1a9c51-8cc8-4f92-8560-819c6474005d" d="M84.936 75.968h160v50.064h-160z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(124.875 104.222)">Project sources</text><path class="ae1a9c51-8cc8-4f92-8560-819c6474005d" d="M514.564 75.968h160v50.064h-160z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(562.577 104.222)">App runtime</text><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" transform="rotate(-180 157.436 445.295)" d="M29.936 297.795h255v295h-255z"/><text class="b9258f43-dcdd-4440-bb0a-75bf6383b075" transform="translate(44.936 322.145)">Built-in IDE</text><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" transform="rotate(-180 104.936 372.795)" d="M54.936 347.795h100v50h-100z"/><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M54.936 347.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(88.942 375.842)">Editor</text><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M54.936 402.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(87.804 430.841)">Panels</text><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M159.936 457.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(183.454 479.842)">Command<tspan x="7.854" y="12">palette</tspan></text><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M54.936 457.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(76.496 485.842)">Debuggers</text><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" d="M729.064 298.8v293h-128v-293h128m1-1h-130v295h130v-295z"/><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M54.936 512.795h205v50h-205z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(108.85 540.842)">Other components</text><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" transform="rotate(-180 665.064 337.199)" d="M615.064 312.199h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(647.277 334.246)">IntelliJ<tspan x="4.823" y="12">IDEA</tspan></text><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" transform="rotate(-180 665.064 391.943)" d="M615.064 366.943h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(649.813 388.99)">Other<tspan x="3.487" y="12">IDEs</tspan></text><path class="bb417a5a-3cef-46d9-a25a-8d833e949245" d="M.5 186.147l1.475-.274"/><path class="ff41825e-1b9c-467a-9c12-c65b4082b685" d="M4.916 185.328l292.638-54.282"/><path class="bb417a5a-3cef-46d9-a25a-8d833e949245" d="M299.025 130.774l1.475-.274M459.5 130.5l1.475.274"/><path class="ff41825e-1b9c-467a-9c12-c65b4082b685" d="M463.916 131.319L756.555 185.6"/><path class="bb417a5a-3cef-46d9-a25a-8d833e949245" d="M758.025 185.873l1.475.274"/><path class="ed94dbba-d063-4926-a3e7-3458631f60ad" d="M394.904 180.268v9.887M365.096 180.268v9.887M380 180.268v9.887"/><path class="e2f6f820-405c-433b-9156-d741b7b1f396" d="M380 131v157.126"/><path class="aae8fa3c-4181-4db3-84fa-b687267c0008" d="M375.013 286.667l4.987 8.635 4.986-8.635h-9.973z"/><path class="e2f6f820-405c-433b-9156-d741b7b1f396" d="M157.436 287.926v-69.843h207.41V131"/><path class="aae8fa3c-4181-4db3-84fa-b687267c0008" d="M162.422 286.467l-4.986 8.635-4.986-8.635h9.972z"/><path class="e2f6f820-405c-433b-9156-d741b7b1f396" d="M665.064 287.926v-69.843h-270.16V131"/><path class="aae8fa3c-4181-4db3-84fa-b687267c0008" d="M670.05 286.467l-4.986 8.635-4.987-8.635h9.973z"/><path class="ff2fbe5b-ebee-4b4c-a2ff-bb260cbfb415" d="M458.5 72.5v57h-157v-57h157M460 71H300v60h160V71z"/><path class="ae1a9c51-8cc8-4f92-8560-819c6474005d" d="M304.968 75.968h150.064v50.064H304.968z"/><text transform="translate(370.452 104.047)" font-size="11" font-family="RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif" font-weight="700" fill="#151515">IDE</text><text class="a8ed803d-1b25-4175-9ba8-23261f084349" transform="translate(29.808 227.055)">IDE<tspan x="24.304" y="0" font-size="16"> </tspan><tspan x="27.744" y="0" font-weight="400" font-family="RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif" font-size="12">(zoom in)</tspan></text><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M159.936 402.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(181.562 430.842)">Languages</text><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M159.936 347.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(192.853 375.842)">Menus</text><text transform="translate(667.802 645.812)" font-size="10" font-family="RedHatText,"Red Hat Text",Overpass,"Helvetica Neue",Arial,sans-serif" fill="#f3f3f3">124_Codeready_1120</text><path fill="none" d="M0 622.795h760v40H0z"/><path class="bd4d2167-a066-4b2c-92b5-8bf131bb3d12" d="M44.936 576.295v1.5h1.5"/><path class="ae493e8a-2f5c-4d25-938d-244f3617af91" d="M49.396 577.795h217.56"/><path class="bd4d2167-a066-4b2c-92b5-8bf131bb3d12" d="M268.436 577.795h1.5v-1.5"/><path class="ac6dc3f2-f4a3-4676-9161-f0c5964ddb68" d="M269.936 573.295v-232.5"/><path class="bd4d2167-a066-4b2c-92b5-8bf131bb3d12" d="M269.936 339.295v-1.5h-1.5"/><path class="ae493e8a-2f5c-4d25-938d-244f3617af91" d="M265.476 337.795H47.916"/><path class="bd4d2167-a066-4b2c-92b5-8bf131bb3d12" d="M46.436 337.795h-1.5v1.5"/><path class="ac6dc3f2-f4a3-4676-9161-f0c5964ddb68" d="M44.936 342.295v232.5"/><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" d="M95.062 570.442H219.81v17.964H95.062z"/><text class="e481f048-b2bd-46c3-a38b-eec0a7b01bf5" transform="translate(100.385 581.426)">Extensible with plug-ins</text><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" transform="rotate(-180 442.25 445.295)" d="M314.75 297.795h255v295h-255z"/><text class="b9258f43-dcdd-4440-bb0a-75bf6383b075" transform="translate(329.75 322.145)">Custom IDE</text><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" transform="rotate(-180 389.75 372.795)" d="M339.75 347.795h100v50h-100z"/><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M339.75 347.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(369.554 369.842)">Custom<tspan x="4.576" y="12">editor</tspan></text><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M339.75 457.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(369.554 479.841)">Custom<tspan x="7.32" y="12">tools</tspan></text><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M339.75 512.795h205v50h-205zM339.75 402.795h100v50h-100zM444.75 457.795h100v50h-100zM444.75 402.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(474.554 424.842)">Custom<tspan x="-2.843" y="12">branding</tspan></text><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(474.554 479.842)">Custom<tspan x="4.064" y="12">layout</tspan></text><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(393.664 540.841)">Other components</text><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(369.554 424.842)">Custom<tspan x="3.438" y="12">panels</tspan></text><path class="eb2626aa-763e-49fa-9ce9-5dc7bdfb45df" d="M444.75 347.795h100v50h-100z"/><text class="a0f708e6-eacc-4317-b485-eae233fef801" transform="translate(474.554 369.842)">Custom<tspan x="3.19" y="12">menus</tspan></text><g><path class="bd4d2167-a066-4b2c-92b5-8bf131bb3d12" d="M330 576.295v1.5h1.5"/><path class="ae493e8a-2f5c-4d25-938d-244f3617af91" d="M334.46 577.795h217.56"/><path class="bd4d2167-a066-4b2c-92b5-8bf131bb3d12" d="M553.5 577.795h1.5v-1.5"/><path class="ac6dc3f2-f4a3-4676-9161-f0c5964ddb68" d="M555 573.295v-232.5"/><path class="bd4d2167-a066-4b2c-92b5-8bf131bb3d12" d="M555 339.295v-1.5h-1.5"/><path class="ae493e8a-2f5c-4d25-938d-244f3617af91" d="M550.54 337.795H332.98"/><path class="bd4d2167-a066-4b2c-92b5-8bf131bb3d12" d="M331.5 337.795H330v1.5"/><path class="ac6dc3f2-f4a3-4676-9161-f0c5964ddb68" d="M330 342.295v232.5"/></g><path class="e9be48c9-f78f-43b6-886a-e8e981d3726c" d="M381.192 570.442h122.617v17.964H381.192z"/><text class="e481f048-b2bd-46c3-a38b-eec0a7b01bf5" transform="translate(385.45 581.426)">Extensible with plug-ins</text><path class="ae1a9c51-8cc8-4f92-8560-819c6474005d" d="M92.162 243.778h479.847v31.602H92.162zM614.223 248.778h101.681v21.602H614.223z"/><text class="e481f048-b2bd-46c3-a38b-eec0a7b01bf5" transform="translate(118.485 257.49)">Use default IDE <tspan x="-20.146" y="12">and extend with plug-ins</tspan></text><text class="e481f048-b2bd-46c3-a38b-eec0a7b01bf5" transform="translate(618.266 262.703)">Use third-party IDE</text><text class="e481f048-b2bd-46c3-a38b-eec0a7b01bf5" transform="translate(292.943 257.491)">Build custom IDE with Eclipse Theia <tspan x="27.665" y="12">and extend with plug-ins</tspan></text></svg> \ No newline at end of file diff --git a/modules/end-user-guide/images/git/git-config-identity.png b/modules/end-user-guide/images/git/git-config-identity.png deleted file mode 100644 index 30e69a803a..0000000000 Binary files a/modules/end-user-guide/images/git/git-config-identity.png and /dev/null differ diff --git a/modules/end-user-guide/images/git/github-sign-in-action.png b/modules/end-user-guide/images/git/github-sign-in-action.png deleted file mode 100644 index 796739068b..0000000000 Binary files a/modules/end-user-guide/images/git/github-sign-in-action.png and /dev/null differ diff --git a/modules/end-user-guide/images/git/terminal-git-command.png b/modules/end-user-guide/images/git/terminal-git-command.png deleted file mode 100644 index 30d6d91487..0000000000 Binary files a/modules/end-user-guide/images/git/terminal-git-command.png and /dev/null differ diff --git a/modules/end-user-guide/images/ide/che-theia-basics-1.png b/modules/end-user-guide/images/ide/che-theia-basics-1.png deleted file mode 100644 index 699360c65f..0000000000 Binary files a/modules/end-user-guide/images/ide/che-theia-basics-1.png and /dev/null differ diff --git a/modules/end-user-guide/images/ide/che-theia-basics-2.png b/modules/end-user-guide/images/ide/che-theia-basics-2.png deleted file mode 100644 index 0061257992..0000000000 Binary files a/modules/end-user-guide/images/ide/che-theia-basics-2.png and /dev/null differ diff --git a/modules/end-user-guide/images/ide/che-theia-basics-3-b.png b/modules/end-user-guide/images/ide/che-theia-basics-3-b.png deleted file mode 100644 index 484850facc..0000000000 Binary files a/modules/end-user-guide/images/ide/che-theia-basics-3-b.png and /dev/null differ diff --git a/modules/end-user-guide/images/ide/che-theia-basics-3-c.png b/modules/end-user-guide/images/ide/che-theia-basics-3-c.png deleted file mode 100644 index 6b6b57c334..0000000000 Binary files a/modules/end-user-guide/images/ide/che-theia-basics-3-c.png and /dev/null differ diff --git a/modules/end-user-guide/images/ide/che-theia-basics-3-d.png b/modules/end-user-guide/images/ide/che-theia-basics-3-d.png deleted file mode 100644 index 8f069dc518..0000000000 Binary files a/modules/end-user-guide/images/ide/che-theia-basics-3-d.png and /dev/null differ diff --git a/modules/end-user-guide/images/ide/che-theia-basics-3.png b/modules/end-user-guide/images/ide/che-theia-basics-3.png deleted file mode 100644 index c16db139d7..0000000000 Binary files a/modules/end-user-guide/images/ide/che-theia-basics-3.png and /dev/null differ diff --git a/modules/end-user-guide/images/ide/che-theia-basics-4.png b/modules/end-user-guide/images/ide/che-theia-basics-4.png deleted file mode 100644 index c669e4d492..0000000000 Binary files a/modules/end-user-guide/images/ide/che-theia-basics-4.png and /dev/null differ diff --git a/modules/end-user-guide/images/ide/che-theia-basics-5.png b/modules/end-user-guide/images/ide/che-theia-basics-5.png deleted file mode 100644 index 44e7fe6320..0000000000 Binary files a/modules/end-user-guide/images/ide/che-theia-basics-5.png and /dev/null differ diff --git a/modules/end-user-guide/images/installation/che-red-hat-application-menu-che-odp.png b/modules/end-user-guide/images/installation/che-red-hat-application-menu-che-odp.png index 9bdd708e60..8f364c255d 100644 Binary files a/modules/end-user-guide/images/installation/che-red-hat-application-menu-che-odp.png and b/modules/end-user-guide/images/installation/che-red-hat-application-menu-che-odp.png differ diff --git a/modules/end-user-guide/images/integration/token-injection.png b/modules/end-user-guide/images/integration/token-injection.png new file mode 100644 index 0000000000..0c8306a047 Binary files /dev/null and b/modules/end-user-guide/images/integration/token-injection.png differ diff --git a/modules/end-user-guide/images/logs/logging-the-client-server-traffic-for-debug-adapters.png b/modules/end-user-guide/images/logs/logging-the-client-server-traffic-for-debug-adapters.png deleted file mode 100644 index 292bb41988..0000000000 Binary files a/modules/end-user-guide/images/logs/logging-the-client-server-traffic-for-debug-adapters.png and /dev/null differ diff --git a/modules/end-user-guide/images/logs/viewing-intelephense-events-in-the-output-panel.png b/modules/end-user-guide/images/logs/viewing-intelephense-events-in-the-output-panel.png deleted file mode 100644 index ec83622b0f..0000000000 Binary files a/modules/end-user-guide/images/logs/viewing-intelephense-events-in-the-output-panel.png and /dev/null differ diff --git a/modules/end-user-guide/images/logs/viewing-logs-for-php-debug.png b/modules/end-user-guide/images/logs/viewing-logs-for-php-debug.png deleted file mode 100644 index 501e8b08fc..0000000000 Binary files a/modules/end-user-guide/images/logs/viewing-logs-for-php-debug.png and /dev/null differ diff --git a/modules/end-user-guide/images/navigation/navigating-openshift-web-console-from-che-dashboard.png b/modules/end-user-guide/images/navigation/navigating-openshift-web-console-from-che-dashboard.png new file mode 100644 index 0000000000..6f3e22e167 Binary files /dev/null and b/modules/end-user-guide/images/navigation/navigating-openshift-web-console-from-che-dashboard.png differ diff --git a/modules/end-user-guide/images/workspace_button/eclipse_che_badges.png b/modules/end-user-guide/images/workspace_button/eclipse_che_badges.png deleted file mode 100644 index 7eecbec1ac..0000000000 Binary files a/modules/end-user-guide/images/workspace_button/eclipse_che_badges.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/che-select-devfile.png b/modules/end-user-guide/images/workspaces/che-select-devfile.png deleted file mode 100644 index cfe3c56d0a..0000000000 Binary files a/modules/end-user-guide/images/workspaces/che-select-devfile.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/che-welcome.png b/modules/end-user-guide/images/workspaces/che-welcome.png deleted file mode 100644 index 237b990f94..0000000000 Binary files a/modules/end-user-guide/images/workspaces/che-welcome.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/configure-command.png b/modules/end-user-guide/images/workspaces/configure-command.png deleted file mode 100644 index 08bc7a2485..0000000000 Binary files a/modules/end-user-guide/images/workspaces/configure-command.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/devfile-projects.png b/modules/end-user-guide/images/workspaces/devfile-projects.png deleted file mode 100644 index 68e9878c6d..0000000000 Binary files a/modules/end-user-guide/images/workspaces/devfile-projects.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/git-clone-command-2.png b/modules/end-user-guide/images/workspaces/git-clone-command-2.png deleted file mode 100644 index f5b33a04f2..0000000000 Binary files a/modules/end-user-guide/images/workspaces/git-clone-command-2.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/git-clone-command.png b/modules/end-user-guide/images/workspaces/git-clone-command.png deleted file mode 100644 index 7990d73c3b..0000000000 Binary files a/modules/end-user-guide/images/workspaces/git-clone-command.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/git-clone-terminal.png b/modules/end-user-guide/images/workspaces/git-clone-terminal.png deleted file mode 100644 index a5e9892b07..0000000000 Binary files a/modules/end-user-guide/images/workspaces/git-clone-terminal.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/run-command.png b/modules/end-user-guide/images/workspaces/run-command.png deleted file mode 100644 index 0f28cea115..0000000000 Binary files a/modules/end-user-guide/images/workspaces/run-command.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/workspace-add-editor.png b/modules/end-user-guide/images/workspaces/workspace-add-editor.png deleted file mode 100644 index 9e2412baec..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace-add-editor.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/workspace-add-plugin.png b/modules/end-user-guide/images/workspaces/workspace-add-plugin.png deleted file mode 100644 index b03a1fba5d..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace-add-plugin.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/workspace-devfile-editor.png b/modules/end-user-guide/images/workspaces/workspace-devfile-editor.png deleted file mode 100644 index deed91ca41..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace-devfile-editor.png and /dev/null differ diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 21c157bc6d..d6cc9891ba 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -1,51 +1,26 @@ -.End-user Guide +.User Guide -* xref:navigating-che.adoc[] -** xref:navigating-che-using-the-dashboard.adoc[] -** xref:importing-certificates-to-browsers.adoc[] -** xref:accessing-che-from-openshift-developer-perspective.adoc[] -* xref:che-theia-ide-basics.adoc[] -** xref:defining-custom-commands-for-che-theia.adoc[] -** xref:version-control.adoc[] -** xref:che-theia-troubleshooting.adoc[] -** xref:differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc[] -* xref:workspaces-overview.adoc[] -** xref:creating-a-workspace-from-a-code-sample.adoc[] -** xref:creating-a-workspace-from-a-template-devfile.adoc[] -** xref:creating-a-workspace-from-remote-devfile.adoc[] -** xref:creating-a-workspace-from-local-devfile-using-chectl.adoc[] -** xref:importing-the-source-code-of-a-project-into-a-workspace.adoc[] -** xref:configuring-a-workspace-with-dashboard.adoc[] -** xref:running-a-workspace-with-dashboard.adoc[] -** xref:importing-kubernetes-applications-into-a-workspace.adoc[] -** xref:remotely-accessing-workspaces.adoc[] -** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container.adoc[] -** xref:authenticating-on-scm-server-with-a-personal-access-token.adoc[] -* xref:authoring-devfiles.adoc[] -** xref:authoring-devfiles-version-1.adoc[] -** xref:authoring-devfiles-version-2.adoc[] -* xref:customizing-developer-environments.adoc[] -** xref:what-is-a-che-theia-plug-in.adoc[] -** xref:adding-a-vs-code-extension-to-a-workspace.adoc[] -** xref:adding-a-vs-code-extension-to-the-che-plugin-registry.adoc[] -** xref:publishing-metadata-for-a-vs-code-extension.adoc[] -** xref:testing-a-visual-studio-code-extension-in-che.adoc[] -** xref:using-alternative-ides-in-che.adoc[] -*** xref:configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc[] -**** xref:building-images-for-ides-based-on-the-intellij-platform.adoc[] -**** xref:provisioning-the-jetbrains-offline-activation-code.adoc[] -*** xref:support-for-theia-based-ides.adoc[] -** xref:adding-tools-to-che-after-creating-a-workspace.adoc[] -** xref:using-private-container-registries.adoc[] -* xref:using-artifact-repositories-in-a-restricted-environment.adoc[] -** xref:using-maven-artifact-repositories.adoc[] -** xref:using-gradle-artifact-repositories.adoc[] -** xref:using-python-artifact-repositories.adoc[] -** xref:using-go-artifact-repositories.adoc[] -** xref:using-nuget-artifact-repositories.adoc[] -** xref:using-npm-artifact-repositories.adoc[] +* xref:user-onboarding.adoc[] +** xref:starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc[] +** xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] +** xref:basic-actions-you-can-perform-on-a-workspace.adoc[] +* xref:using-developer-workspaces.adoc[] +** xref:first-time-contributors.adoc[] +** xref:benefits-of-pull-requests-review-in-che.adoc[] +* xref:selecting-an-ide.adoc[] +* xref:customizing-workspaces-components.adoc[] +* xref:configuring-user-preferences-and-secrets.adoc[] +** xref:configuring-user-secrets.adoc[] +** xref:secret-as-a-file.adoc[] +** xref:secret-as-a-variable.adoc[] +** xref:git-credential-store.adoc[] +* xref:integrating-with-kubernetes.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:investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc[] ** xref:troubleshooting-slow-workspaces.adoc[] ** xref:troubleshooting-network-problems.adoc[] +* xref:adding-a-vscode-extension.adoc[] diff --git a/modules/end-user-guide/pages/.placeholder b/modules/end-user-guide/pages/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/end-user-guide/pages/accessing-che-from-openshift-developer-perspective.adoc b/modules/end-user-guide/pages/accessing-che-from-openshift-developer-perspective.adoc deleted file mode 100644 index 0f4052d1d7..0000000000 --- a/modules/end-user-guide/pages/accessing-che-from-openshift-developer-perspective.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="accessing-che-from-openshift-developer-perspective"] -// = Accessing Che from OpenShift Developer Perspective -:navtitle: Navigating Che from OpenShift Developer Perspective -:keywords: overview, accessing-che-from-openshift-developer-perspective -:page-aliases: .:accessing-che-from-openshift-developer-perspective, overview:accessing-che-from-openshift-developer-perspective - -include::partial$assembly_accessing-che-from-openshift-developer-perspective.adoc[] diff --git a/modules/end-user-guide/pages/adding-a-vs-code-extension-to-a-workspace.adoc b/modules/end-user-guide/pages/adding-a-vs-code-extension-to-a-workspace.adoc deleted file mode 100644 index 95a581eccf..0000000000 --- a/modules/end-user-guide/pages/adding-a-vs-code-extension-to-a-workspace.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="adding-a-vscode-extension-to-a-workspace"] -// = Adding tools to Che after creating a workspace -:navtitle: Adding a VS Code extension to a workspace -:keywords: end-user-guide, adding-a-vscode-extension-to-a-workspace -:page-aliases: .:adding-a-vscode-extension-to-a-workspace, administration-guide:using-a-visual-studio-code-extension-in-che - -include::partial$assembly_adding-a-vs-code-extension-to-a-workspace.adoc[] diff --git a/modules/end-user-guide/pages/adding-a-vs-code-extension-to-the-che-plugin-registry.adoc b/modules/end-user-guide/pages/adding-a-vs-code-extension-to-the-che-plugin-registry.adoc deleted file mode 100644 index b22f083be1..0000000000 --- a/modules/end-user-guide/pages/adding-a-vs-code-extension-to-the-che-plugin-registry.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="adding-a-vs-code-extension-to-the-che-plugin-registry"] -// = Adding a VS Code extension to the Che plug-ins registry -:navtitle: Adding a VS Code extension to the Che plug-ins registry -:keywords: end-user-guide, adding-a-vs-code-extension-to-the-che-plugin-registry -:page-aliases: .:adding-a-vs-code-extension-to-the-che-plugin-registry - -include::partial$proc_adding-a-vs-code-extension-to-the-che-plugin-registry.adoc[] \ No newline at end of file diff --git a/modules/end-user-guide/pages/adding-a-vscode-extension.adoc b/modules/end-user-guide/pages/adding-a-vscode-extension.adoc new file mode 100644 index 0000000000..8250bfb936 --- /dev/null +++ b/modules/end-user-guide/pages/adding-a-vscode-extension.adoc @@ -0,0 +1,160 @@ +:navtitle: Adding a Visual Studio Code extension to a workspace +:keywords: Visual Studio Code extension, user-guide + +[id="adding-visual-studio-code-extension_{context}"] += Adding a Visual Studio Code extension to a workspace + +Previously, with the devfiles v1 format, you used the devfile to specify IDE-specific plug-ins and Visual Studio Code extensions. Now, with devfiles v2, you use a specific meta-folder rather than the devfile to specify the plug-ins and extensions. + +[id="plug-in-registries"] +== {prod-short} plug-in registries overview + +Every {prod-short} instance has a registry of default plug-ins and extensions. The Che-Theia IDE gets information about these plug-ins and extensions from the registry and installs them. + +Check this {prod-short} link:https://github.com/eclipse-che/che-plugin-registry[registry project] for an overview of the default plug-ins, extensions, and source code. An online instance that refreshes after every commit to the main branch, is located link:https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/[here]. You can use a different plug-in or extension registry for Che-Theia if you don't work in air-gapped environment: only the default registry is available there. + +The plug-in and extension overview for Che-Code Visual Studio Code editor is located in the link:https://www.open-vsx.org/[OpenVSX instance]. Air gap is not yet supported for this editor. + +[id="visual-studio-code-extensions-json"] +== Adding an extension to `.vscode/extensions.json` + +The easiest way to add a Visual Studio Code extension to a workspace is to add it to the `.vscode/extensions.json` file. The main advantage of this method is that it works with all supported {prod-short} IDEs. + +If you use the Che-Theia IDE, the extension is installed and configured automatically. If you use a different supported IDE with the Che-Code Visual Studio Code fork, the IDE displays a pop-up with a recommendation to install the extension. + +.Prerequisites +. You have the `.vscode/extensions.json` file in the root of the GitHub repository. + +.Procedure +. Add the extension ID to the `.vscode/extensions.json` file. Use a `.` sign to separate the publisher and extension. The following example uses the IDs of Red Hat Visual Studio Code Java extension: ++ +[source,json,subs="+quotes"] +---- + { + "recommendations": [ + "redhat.java" + ] + } +---- + +NOTE: If the specified set of extension IDs isn't available in the {prod-short} registry, the workspace starts without the extension. + + +[id="che-theia-plug-ins-YAML"] +== Adding plug-in parameters to `.che/che-theia-plugins.yaml` +You can add extra parameters to a plug-in by modifying the `.che/che-theia-plugins.yaml` file. These modifications include: + +* Defining the plug-ins for workspace installation. +* Changing the default memory limit. +* Overriding default preferences. + + +=== Defining the plug-ins for workspace installation +Define the plug-ins to be installed in the workspace. + +.Prerequisites +. You have the `.che/che-theia-plugins.yaml` file in the root of the GitHub repository. + +.Procedure +. Add the ID of the plug-in to the `.che/che-theia-plugins.yaml` file. Use the `/` sign to separate the publisher and plug-in name. The following example uses the IDs of Red Hat Visual Studio Code Java extension: ++ +[source,yaml,subs="+quotes"] +---- +- id: redhat/java +---- + +=== Changing the default memory limit + +Override container settings such as the memory limit. + +.Prerequisites +. You have the `.che/che-theia-plugins.yaml` file in the root of the GitHub repository. + +.Procedure +. Add an `override` section to the `.che/che-theia-plugins.yaml` file under the `id` of the plug-in. +. Specify the memory limit for the extension. In the following example, {prod-short} automatically installs the Red Hat Visual Studio Code Java extension in the {prod-short} workspace and increases the memory of the workspace by two gigabytes: ++ +[source,yaml,subs="+quotes"] +---- + + - id: redhat/java + override: + sidecar: + memoryLimit: 2Gi +---- + +=== Overriding default preferences + +Override the default preferences of the Visual Studio Code extension for the workspace. + +.Prerequisites +. You have the `.che/che-theia-plugins.yaml` file in the root of the GitHub repository. + +.Procedure +. Add an `override` section to the `.che/che-theia-plugins.yaml` file under the `id` of the extension. +. Specify the preferences in the `Preferences` section. In the following example, {prod-short} automatically installs Red Hat Visual Studio Code Java extension in the {prod-short} workspace and sets the `java.server.launchMode` preference to `LightWeight`: ++ +[source,yaml,subs="+quotes"] +---- + - id: redhat/java + override: + preferences: + java.server.launchMode: LightWeight +---- + +[NOTE] +==== +You can also define the preferences in the `.vscode/settings.json` file, either by changing the preferences in the UI of your IDE or by adding them to the `.vscode/settings.json` file: +[source,json,subs="+quotes"] +---- +{ +"my.preferences": "my-value" +} +---- +==== + +[id="visual-studio-code-extensions-in-devfile"] +== Defining Visual Studio Code extension attributes in the devfile + +If it's not possible to add extra files in the GitHub repository, you can define some of the plug-in or extension attributes by inlining them in the devfile. You can use this procedure with both `.vscode/extensions.json` and `.che/che-theia-plugins.yaml` file contents. + +=== Inlining `.vscode/extensions.json` file +Use `.vscode/extensions.json` file contents to inline the extension attributes in the devfile. + +.Procedure +. Add an `attributes` section to your `devfile.yaml` file. +. Add `.vscode/extensions.json` to the `atributes` section. Add a `|` sign after the colon separator. +. Paste the contents of the `.vscode/extensions.json` file after the `|` sign. The following example uses Red Hat Visual Studio Code Java extension attributes: ++ +[source,yaml,subs="+quotes"] +---- +schemaVersion: 2.2.0 +metadata: + name: my-example +attributes: + .vscode/extensions.json: | + { + "recommendations": [ + "redhat.java" + ] + } +---- + +=== Inlining `.che/che-theia-plugins.yaml` file +Use `.che/che-theia-plugins.yaml` file contents to inline the plug-in attributes in the devfile. + +.Procedure +. Add an `attributes` section to your `devfile.yaml` file. +. Add `.vscode/extensions.json` to the `atributes` section. Add a `|` sign after the colon separator. +. Paste the content of the `.che/che-theia-plugins.yaml` file after the `|` sign. The following example uses Red Hat Visual Studio Code Java extension attributes: ++ +[source,yaml,subs="+quotes"] +---- +schemaVersion: 2.2.0 +metadata: + name: my-example +attributes: + .che/che-theia-plugins.yaml: | + - id: redhat/java +---- + diff --git a/modules/end-user-guide/pages/adding-tools-to-che-after-creating-a-workspace.adoc b/modules/end-user-guide/pages/adding-tools-to-che-after-creating-a-workspace.adoc deleted file mode 100644 index 12539c94f3..0000000000 --- a/modules/end-user-guide/pages/adding-tools-to-che-after-creating-a-workspace.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="adding-tools-to-che-after-creating-a-workspace"] -// = Adding tools to Che after creating a workspace -:navtitle: Adding tools to Che after creating a workspace -:keywords: end-user-guide, adding-tools-to-che-after-creating-a-workspace -:page-aliases: .:adding-tools-to-che-after-creating-a-workspace - -include::partial$assembly_adding-tools-to-che-after-creating-a-workspace.adoc[] diff --git a/modules/end-user-guide/pages/authenticating-on-scm-server-with-a-personal-access-token.adoc b/modules/end-user-guide/pages/authenticating-on-scm-server-with-a-personal-access-token.adoc deleted file mode 100644 index a881291895..0000000000 --- a/modules/end-user-guide/pages/authenticating-on-scm-server-with-a-personal-access-token.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authenticating-on-scm-server-with-a-personal-access-token"] -// = Authenticating on scm server with a personal access token -:navtitle: Authenticating on SCM Server with a personal access token -:keywords: end-user-guide, authentication-on-scm-server-with-a-personal-access-token -:page-aliases: .:authenticating-on-scm-server-with-a-personal-access-token - -include::partial$assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc[] diff --git a/modules/end-user-guide/pages/authoring-devfiles-version-1.adoc b/modules/end-user-guide/pages/authoring-devfiles-version-1.adoc deleted file mode 100644 index ab5fb760b1..0000000000 --- a/modules/end-user-guide/pages/authoring-devfiles-version-1.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authoring-devfiles-version-1"] -// -:navtitle: Authoring devfiles version 1 -:keywords: end-user-guide, authoring-devfiles-version-1 -:page-aliases: .:authoring-devfiles-version-1 - -include::partial$assembly_authoring-devfiles-version-1.adoc[] diff --git a/modules/end-user-guide/pages/authoring-devfiles-version-2.adoc b/modules/end-user-guide/pages/authoring-devfiles-version-2.adoc deleted file mode 100644 index 04dea70b12..0000000000 --- a/modules/end-user-guide/pages/authoring-devfiles-version-2.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authoring-devfiles-version-2"] -// -:navtitle: Authoring a devfile 2.0.0 -:keywords: end-user-guide, authoring-devfiles-version-2 -:page-aliases: .:authoring-devfiles-version-2 - -include::partial$assembly_authoring-devfiles-version-2.adoc[] diff --git a/modules/end-user-guide/pages/authoring-devfiles.adoc b/modules/end-user-guide/pages/authoring-devfiles.adoc deleted file mode 100644 index c80078aec4..0000000000 --- a/modules/end-user-guide/pages/authoring-devfiles.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authoring-devfiles"] -// -:navtitle: Authoring devfiles -:keywords: end-user-guide, authoring-devfiles -:page-aliases: .:authoring-devfiles, configuring-a-workspace-using-a-devfile, making-a-workspace-portable-using-a-devfile - -include::partial$assembly_authoring-devfiles.adoc[] diff --git a/modules/end-user-guide/pages/automatic-token-injection.adoc b/modules/end-user-guide/pages/automatic-token-injection.adoc new file mode 100644 index 0000000000..7563ac069b --- /dev/null +++ b/modules/end-user-guide/pages/automatic-token-injection.adoc @@ -0,0 +1,21 @@ +:navtitle: Automatic {orch-name} token injection +:keywords: user-guide, token, injection +:page-aliases: .:automatic-token-injection, overview:automatic-token-injection + +[id="automatic-token-injection_{context}"] += Automatic {orch-name} token injection + +This section describes how to use the {orch-name} user token that is automatically injected into workspace containers which allows running {prod-short} CLI commands against {orch-name} cluster. + +.Procedure + +. Open the {prod-short} dashboard and start a workspace. + +. Once the workspace is started, open a terminal in the container that contains the {prod-short} CLI. + +. Execute {prod-short} CLI commands which allow you to run commands against {orch-name} cluster. CLI can be used for deploying applications, inspecting and managing cluster resources, and viewing logs. {orch-name} user token will be used during the execution of the commands. + ++ +image::integration/token-injection.png[Token Injection in IDE,link="{imagesdir}/integration/token-injection.png"] + +WARNING: The automatic token injection currently works only on the OpenShift infrastructure. diff --git a/modules/end-user-guide/pages/basic-actions-you-can-perform-on-a-workspace.adoc b/modules/end-user-guide/pages/basic-actions-you-can-perform-on-a-workspace.adoc new file mode 100644 index 0000000000..674d319950 --- /dev/null +++ b/modules/end-user-guide/pages/basic-actions-you-can-perform-on-a-workspace.adoc @@ -0,0 +1,33 @@ +:_content-type: REFERENCE +:description: Basic actions you can perform on a workspace +:keywords: workspace, workspaces, reopen, restart, stop, start, delete +:navtitle: Basic actions you can perform on a workspace +// :page-aliases: + +[id="basic-actions-you-can-perform-on-a-workspace_{context}"] += Basic actions you can perform on a workspace + +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. + +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*. + +|=== \ No newline at end of file diff --git a/modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc b/modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc new file mode 100644 index 0000000000..bfd58ab418 --- /dev/null +++ b/modules/end-user-guide/pages/benefits-of-pull-requests-review-in-che.adoc @@ -0,0 +1,33 @@ +:_content-type: PROCEDURE +:navtitle: Reviewing pull and merge requests +:keywords: user-guide, reviewing, pull request, merge request +:description: {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. +:page-aliases: + +[id="title_{context}"] += Benefits of reviewing pull and merge requests in {prod} + +[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. + +.Prerequisites +* You have access to the repository hosted by your Git provider. +* You use a {prod}-supported browser: Google Chrome or Mozilla Firefox. +* You have access to a {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: +** Run a linter. +** 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. + +.Verification + +* (optional) Open a second workspace using the main branch of the repository to reproduce a problem. + +// [role="_additional-resources"] +// .Additional resources diff --git a/modules/end-user-guide/pages/building-images-for-ides-based-on-the-intellij-platform.adoc b/modules/end-user-guide/pages/building-images-for-ides-based-on-the-intellij-platform.adoc deleted file mode 100644 index 88a8b45fec..0000000000 --- a/modules/end-user-guide/pages/building-images-for-ides-based-on-the-intellij-platform.adoc +++ /dev/null @@ -1,5 +0,0 @@ -[id="building-images-for-ides-based-on-the-intellij-platform"] -:navtitle: Building IDE image -:keywords: end-user-guide, jetbrains-projector, intellij, images, build - -include::partial$assembly_building-images-for-ides-based-on-the-intellij-platform.adoc[] diff --git a/modules/end-user-guide/pages/che-theia-ide-basics.adoc b/modules/end-user-guide/pages/che-theia-ide-basics.adoc deleted file mode 100644 index 56873655ab..0000000000 --- a/modules/end-user-guide/pages/che-theia-ide-basics.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-theia-ide-basics"] -// = Che-Theia IDE basics -:navtitle: Che-Theia IDE basics -:keywords: end-user-guide, che-theia-ide-basics -:page-aliases: .:che-theia-ide-basics - -include::partial$assembly_che-theia-ide-basics.adoc[] diff --git a/modules/end-user-guide/pages/che-theia-troubleshooting.adoc b/modules/end-user-guide/pages/che-theia-troubleshooting.adoc deleted file mode 100644 index a821258841..0000000000 --- a/modules/end-user-guide/pages/che-theia-troubleshooting.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-theia-troubleshooting"] -// = Che-Theia Troubleshooting -:navtitle: Che-Theia Troubleshooting -:keywords: end-user-guide, che-theia-troubleshooting -:page-aliases: .:che-theia-troubleshooting - -include::partial$assembly_che-theia-troubleshooting.adoc[] diff --git a/modules/end-user-guide/pages/configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc b/modules/end-user-guide/pages/configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc deleted file mode 100644 index 7b99a8ea4c..0000000000 --- a/modules/end-user-guide/pages/configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform"] -:navtitle: IntelliJ Platform IDEs -:keywords: end-user-guide, jetbrains-ides, jetbrains, intellij, ide, intellij-ides, intellij-ide, idea, pycharm -:page-aliases: support-for-jetbrains-ides, using-jetbrains-intellij-idea-community-edition, using-jetbrains-intellij-idea-ultimate-edition, using-jetbrains-webstorm, configuring-an-existing-workspace-to-use-intellij-idea, using-intellij-based-ides - -include::partial$assembly_configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc[] diff --git a/modules/end-user-guide/pages/configuring-a-workspace-with-dashboard.adoc b/modules/end-user-guide/pages/configuring-a-workspace-with-dashboard.adoc deleted file mode 100644 index d04f8dc8d4..0000000000 --- a/modules/end-user-guide/pages/configuring-a-workspace-with-dashboard.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="configuring-a-workspace-with-dashboard"] -:navtitle: Configuring a workspace -:keywords: end-user-guide, configuring-a-workspace-with-dashboard -:page-aliases: .:configuring-a-workspace-with-dashboard - -include::partial$assembly_configuring-a-workspace-with-dashboard.adoc[] diff --git a/modules/end-user-guide/pages/configuring-user-preferences-and-secrets.adoc b/modules/end-user-guide/pages/configuring-user-preferences-and-secrets.adoc new file mode 100644 index 0000000000..4f1cdb2cca --- /dev/null +++ b/modules/end-user-guide/pages/configuring-user-preferences-and-secrets.adoc @@ -0,0 +1,13 @@ +:navtitle: Configuring user preferences and secrets +:keywords: user-guide, configuring, user, preferences, secrets +:page-aliases: + +[id="configuring-user-preferences-and-secrets_{context}"] += Configuring user preferences and secrets + +User preferences and secrets are not stored in the devfile. + +* IDE Plug-ins +* Git provider secrets +* Application specific secrets + diff --git a/modules/end-user-guide/partials/assembly_mounting-secrets-as-file-or-env-variable-in-workspace-container.adoc b/modules/end-user-guide/pages/configuring-user-secrets.adoc similarity index 60% rename from modules/end-user-guide/partials/assembly_mounting-secrets-as-file-or-env-variable-in-workspace-container.adoc rename to modules/end-user-guide/pages/configuring-user-secrets.adoc index c0ff2b5896..4f9fd43cea 100644 --- a/modules/end-user-guide/partials/assembly_mounting-secrets-as-file-or-env-variable-in-workspace-container.adoc +++ b/modules/end-user-guide/pages/configuring-user-secrets.adoc @@ -1,11 +1,10 @@ +:navtitle: Configuring user secrets +:keywords: user-guide, configuring, user, secrets +:page-aliases: mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container -:parent-context-of-mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container: {context} - -[id="mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container_{context}"] -= Mounting a secret as a file or an environment variable into a workspace container - -:context: mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container +[id="configuring-user-secrets_{context}"] += Configuring user secrets Secrets are {platforms-name} objects that store sensitive data such as user names, passwords, authentication tokens, and configurations in an encrypted form. @@ -30,13 +29,12 @@ NOTE: SSH key pairs can also be mounted as a file, but this format is primarily The mounting process uses the standard {platforms-name} mounting mechanism, but it requires additional annotations and labeling for a proper bound of a secret with the required {prod-short} workspace container. -include::partial$proc_mounting-a-secret-as-a-file-into-a-workspace-container.adoc[leveloffset=+1] - -include::partial$proc_mounting-a-secret-as-an-environment-variable-into-a-workspace-container.adoc[leveloffset=+1] +{orch-name} annotations and labels are tools used by libraries, tools, and other clients, to attach arbitrary non-identifying metadata to {platforms-name} native objects. -include::partial$proc_mounting-a-git-credential-store-into-a-workspace-container.adoc[leveloffset=+1] +Labels select objects and connect them to a collection that satisfies certain conditions, where annotations are used for non-identifying information that is not used by {platforms-name} objects internally. -include::partial$ref_the-use-of-annotations-in-the-process-of-mounting-a-secret-into-a-workspace-container.adoc[leveloffset=+1] +This section describes {platforms-name} annotation values used in the process of {platforms-name} secret mounting in a {prod-short} workspace. -:context: {parent-context-of-mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container} +Annotations must contain items that help identify the proper mounting configuration. These items are: +include::example$snip_{project-context}-annotations-description.adoc[leveloffset=+1] diff --git a/modules/end-user-guide/pages/creating-a-workspace-from-a-code-sample.adoc b/modules/end-user-guide/pages/creating-a-workspace-from-a-code-sample.adoc deleted file mode 100644 index c07e6aad50..0000000000 --- a/modules/end-user-guide/pages/creating-a-workspace-from-a-code-sample.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="creating-a-workspace-from-a-code-sample"] - -:navtitle: Creating a workspace from a code sample -:keywords: end-user-guide, creating-a-workspace-from-a-code-sample -:page-aliases: .:creating-a-workspace-from-a-code-sample, .:creating-a-workspace-from-code-sample, creating-a-workspace-from-code-sample - -include::partial$assembly_creating-a-workspace-from-a-code-sample.adoc[] \ No newline at end of file diff --git a/modules/end-user-guide/pages/creating-a-workspace-from-a-template-devfile.adoc b/modules/end-user-guide/pages/creating-a-workspace-from-a-template-devfile.adoc deleted file mode 100644 index b236f9323d..0000000000 --- a/modules/end-user-guide/pages/creating-a-workspace-from-a-template-devfile.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="creating-a-workspace-from-a-template-devfile"] - -:navtitle: Creating a workspace from a template devfile -:keywords: end-user-guide, creating-a-workspace-from-a-template-devfile -:page-aliases: .:creating-a-workspace-from-a-template-devfile - -include::partial$assembly_creating-a-workspace-from-a-template-devfile.adoc[] \ No newline at end of file diff --git a/modules/end-user-guide/pages/creating-a-workspace-from-local-devfile-using-chectl.adoc b/modules/end-user-guide/pages/creating-a-workspace-from-local-devfile-using-chectl.adoc deleted file mode 100644 index 5c2d73deee..0000000000 --- a/modules/end-user-guide/pages/creating-a-workspace-from-local-devfile-using-chectl.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="creating-a-workspace-from-local-devfile-using-chectl"] -// = Creating a workspace from local devfile using chectl -:navtitle: Creating a workspace from local devfile using {prod-cli} -:keywords: end-user-guide, creating-a-workspace-from-local-devfile-using-chectl -:page-aliases: .:creating-a-workspace-from-local-devfile-using-chectl - -include::partial$proc_creating-a-workspace-using-chectl-and-a-local-devfile.adoc[] diff --git a/modules/end-user-guide/pages/creating-a-workspace-from-remote-devfile.adoc b/modules/end-user-guide/pages/creating-a-workspace-from-remote-devfile.adoc deleted file mode 100644 index d4fce324a0..0000000000 --- a/modules/end-user-guide/pages/creating-a-workspace-from-remote-devfile.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="creating-a-workspace-from-remote-devfile"] -// = Configuring a workspace using a devfile -:navtitle: Creating a workspace from a remote devfile using the dashboard -:keywords: end-user-guide, creating-a-workspace-from-remote-devfile -:page-aliases: .:creating-a-workspace-from-remote-devfile - -include::partial$assembly_creating-a-workspace-from-remote-devfile.adoc[] diff --git a/modules/end-user-guide/pages/customizing-developer-environments.adoc b/modules/end-user-guide/pages/customizing-developer-environments.adoc deleted file mode 100644 index 20a072469d..0000000000 --- a/modules/end-user-guide/pages/customizing-developer-environments.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="customizing-developer-environments"] -// = Customizing developer environments -:navtitle: Customizing developer environments -:keywords: end-user-guide, customizing-developer-environments -:page-aliases: .:customizing-developer-environments - -include::partial$assembly_customizing-developer-environments.adoc[] diff --git a/modules/end-user-guide/pages/customizing-workspaces-components.adoc b/modules/end-user-guide/pages/customizing-workspaces-components.adoc new file mode 100644 index 0000000000..af5a81daf6 --- /dev/null +++ b/modules/end-user-guide/pages/customizing-workspaces-components.adoc @@ -0,0 +1,12 @@ +:navtitle: Customizing workspaces components +:keywords: user-guide, customizing-developer-environments +:page-aliases: configuring-a-workspace-using-a-devfile, making-a-workspace-portable-using-a-devfile, authoring-devfiles-version-1, authoring-devfiles-version-2, authoring-devfiles, defining-custom-commands-for-che-theia, adding-a-vs-code-extension-to-a-workspace, adding-a-vs-code-extension-to-the-che-plugin-registry, adding-tools-to-che-after-creating-a-workspace, using-private-container-registries, using-artifact-repositories-in-a-restricted-environment, using-maven-artifact-repositories, using-gradle-artifact-repositories, using-python-artifact-repositories, using-go-artifact-repositories, using-nuget-artifact-repositories, using-npm-artifact-repositories, customizing-developer-environments, what-is-a-che-theia-plug-in, testing-a-visual-studio-code-extension-in-che, publishing-metadata-for-a-vs-code-extension, contributor-guide:developing-che-theia-plug-ins, contributor-guide:testing-che-theia-plug-ins, contributor-guide:publishing-che-theia-plug-ins, contributor-guide:adding-support-for-a-new-language, contributor-guide:adding-support-for-a-new-debugger, contributor-guide:che-extensibility-reference, contributor-guide:che-extension-points, contributor-guide:che-theia-plug-in-api, contributor-guide:debug-adapter-protocol, contributor-guide:language-server-protocol + +[id="customizing-workspaces_{context}"] += Customizing workspaces + +To configure a workspace: + +* Use a devfile meeting the latest devfile 2 specification. See: link:https://devfile.io/docs/devfile/2.1.0/user-guide/authoring-stacks/[Devfile User Guide]. + +* In addition to the generic devfile specification, you can add {prod-short} specific attributes. diff --git a/modules/end-user-guide/pages/defining-custom-commands-for-che-theia.adoc b/modules/end-user-guide/pages/defining-custom-commands-for-che-theia.adoc deleted file mode 100644 index 07da486cb6..0000000000 --- a/modules/end-user-guide/pages/defining-custom-commands-for-che-theia.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="defining-custom-commands-for-che-theia"] -// = Defining custom commands for Che-Theia -:navtitle: Defining custom commands for Che-Theia -:keywords: end-user-guide, defining-custom-commands-for-che-theia -:page-aliases: .:defining-custom-commands-for-che-theia - -include::partial$assembly_defining-custom-commands-for-che-theia.adoc[] diff --git a/modules/end-user-guide/pages/differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc b/modules/end-user-guide/pages/differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc deleted file mode 100644 index f845ea015d..0000000000 --- a/modules/end-user-guide/pages/differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode"] -// = Differences in Che-Theia Webview in single-host mode and multihost mode -:navtitle: Differences in Che-Theia Webview in single-host mode and multihost mode -:keywords: end-user-guide, differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode -:page-aliases: .:differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode - -include::partial$assembly_differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc[] diff --git a/modules/end-user-guide/pages/first-time-contributors.adoc b/modules/end-user-guide/pages/first-time-contributors.adoc new file mode 100644 index 0000000000..1567444dec --- /dev/null +++ b/modules/end-user-guide/pages/first-time-contributors.adoc @@ -0,0 +1,23 @@ +:navtitle: Badge for first-time contributors +:keywords: user-guide, first-time contributor +:page-aliases: + +[id="using-a-badge-with-a-link-to-enable-a-first-time-contributor-to-start-a-workspace_{context}"] += 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 (`__<your-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://__<your-repository-url>__) +---- + +. 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/git-credential-store.adoc b/modules/end-user-guide/pages/git-credential-store.adoc new file mode 100644 index 0000000000..baee0aa6f7 --- /dev/null +++ b/modules/end-user-guide/pages/git-credential-store.adoc @@ -0,0 +1,87 @@ +:navtitle: Creating a {orch-name} Secret for a Git credentials store +:keywords: user-guide, configuring, user, secrets +:page-aliases: + +[id="mounting-a-git-credential-store-into-workspace-containers_{context}"] += Creating a {orch-name} Secret for a Git credentials store + +As an alternative to the OAuth for GitHub, GitLab, or Bitbucket that is configured by the administrator of your organization's {prod-short} instance, you can apply your Git credentials store as a Secret in your user {orch-namespace}. + +When mounting the Secret, a Git configuration file with the path to the mounted Git credentials store is automatically configured and mounted to the {devworkspace} containers at `/etc/gitconfig`. + +.Prerequisites + +* A running instance of {prod-short}. +* You have CLI or GUI access to the {orch-name} cluster of your organization's {prod-short} instance. +* For CLI users: The `{orch-cli}` and link:https://www.gnu.org/software/coreutils/base64[`base64`] command line tools are installed in the operating system you are using. + +.Procedure +. In your home directory, locate and open your `.git-credentials` file if you already have it. Alternatively, if you do not have this file, save a new `.git-credentials` file, using the link:https://git-scm.com/docs/git-credential-store#_storage_format[Git credentials storage format]. Each credential is stored on its own line in the file: + ++ +[subs="+quotes,+attributes,+macros"] +---- +https://__<username>__:__<token>__@__<git_server_hostname>__ +---- + ++ +.A line in a `.git-credentials` file +==== +`https://trailblazer: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@github.com` +==== + +. Select credentials from your `.git-credentials` file for the Secret. Encode the selected credentials to Base64 for the next step. ++ +[TIP] +==== +CLI users can use the `base64` command as needed: + +* To encode all lines in the file: ++ +`$ cat .git-credentials | base64 | tr -d '\n'` + +* To encode a selected line: ++ +`$ echo -n '__<copied_and_pasted_line_from_.git-credentials>__' | base64` +==== + +. Create a new {orch-name} Secret in your user {orch-namespace}. ++ +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: git-credentials-secret + labels: + controller.devfile.io/git-credential: 'true' <1> + controller.devfile.io/watch-secret: 'true' + annotations: + controller.devfile.io/mount-path: /etc/secret <2> +data: + credentials: __<Base64_content_of_.git-credentials>__ <3> +---- ++ +<1> The `controller.devfile.io/git-credential` label marks the Secret as containing Git credentials. +<2> A custom absolute path in the {devworkspace} containers. The Secret is mounted as the `credentials` file at this path. The default path is `/`. +<3> The selected content from `.git-credentials` that you encoded to Base64 in the previous step. ++ +[TIP] +==== +You can create and apply multiple Git credentials Secrets in your user {orch-namespace}. All of them will be copied into one Secret that will be mounted to the {devworkspace} containers. For example, if you set the mount path to `/etc/secret`, then the one Secret with all of your Git credentials will be mounted at `/etc/secret/credentials`. You must set all Git credentials Secrets in your user {orch-namespace} to the same mount path. You can set the mount path to an arbitrary path because the mount path will be automatically set in the Git configuration file configured at `/etc/gitconfig`. +==== + +. Use the CLI or GUI to apply the Secret to the {orch-name} cluster of your organization's {prod-short} instance. + ++ +[TIP] +==== +CLI users can apply the Secret with `{orch-cli}`: + +[subs="+quotes,+attributes,+macros"] +---- +$ {orch-cli} apply -f - <<EOF +__<Secret_prepared_in_the_previous_step>__ +EOF +---- +==== diff --git a/modules/end-user-guide/pages/importing-certificates-to-browsers.adoc b/modules/end-user-guide/pages/importing-certificates-to-browsers.adoc deleted file mode 100644 index f82e1dc851..0000000000 --- a/modules/end-user-guide/pages/importing-certificates-to-browsers.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="importing-certificates-to-browsers"] -// = Importing certificates to browsers -:navtitle: Importing certificates to browsers -:keywords: overview, importing-certificates-to-browsers, importing-self-signed-certificates-to-browsers -:page-aliases: .:importing-certificates-to-browsers, .:importing-self-signed-certificates-to-browsers, overview:importing-certificates-to-browsers, overview:importing-self-signed-certificates-to-browsers, end-user-guide:importing-self-signed-certificates-to-browsers - -include::partial$proc_importing-certificates-to-browsers.adoc[] diff --git a/modules/end-user-guide/pages/importing-kubernetes-applications-into-a-workspace.adoc b/modules/end-user-guide/pages/importing-kubernetes-applications-into-a-workspace.adoc deleted file mode 100644 index e493b570b0..0000000000 --- a/modules/end-user-guide/pages/importing-kubernetes-applications-into-a-workspace.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="importing-kubernetes-applications-into-a-workspace"] -// = Importing a {orch-name} application into a workspace -:navtitle: Importing {orch-name} applications into a workspace -:keywords: end-user-guide, importing-kubernetes-applications-into-a-workspace -:page-aliases: .:importing-kubernetes-applications-into-a-workspace - -include::partial$assembly_importing-kubernetes-applications-into-a-workspace.adoc[] diff --git a/modules/end-user-guide/pages/importing-the-source-code-of-a-project-into-a-workspace.adoc b/modules/end-user-guide/pages/importing-the-source-code-of-a-project-into-a-workspace.adoc deleted file mode 100644 index d2ce652481..0000000000 --- a/modules/end-user-guide/pages/importing-the-source-code-of-a-project-into-a-workspace.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="importing-the-source-code-of-a-project-into-a-workspace"] -:navtitle: Importing the source code of a project into a workspace -:keywords: end-user-guide, importing-the-source-code-of-a-project-into-a-workspace -:page-aliases: .:importing-the-source-code-of-a-project-into-a-workspace, .:creating-a-workspace-by-importing-the-source-code-of-a-project, creating-a-workspace-by-importing-the-source-code-of-a-project - -include::partial$proc_importing-the-source-code-of-a-project-into-a-workspace.adoc[] diff --git a/modules/end-user-guide/pages/integrating-with-kubernetes.adoc b/modules/end-user-guide/pages/integrating-with-kubernetes.adoc new file mode 100644 index 0000000000..435c925e32 --- /dev/null +++ b/modules/end-user-guide/pages/integrating-with-kubernetes.adoc @@ -0,0 +1,10 @@ +:navtitle: Integrating with {orch-name} +:keywords: overview, integrating with {orch-name} +:page-aliases: + +[id="integrating-with-kubernetes_{context}"] += Integrating with {orch-name} + +* xref:automatic-token-injection.adoc[] +* xref:navigating-che-from-openshift-developer-perspective.adoc[] +* xref:navigating-openshift-web-console-from-che.adoc[] diff --git a/modules/end-user-guide/pages/investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc b/modules/end-user-guide/pages/investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc index 62547ecde0..1a230dc1d2 100644 --- a/modules/end-user-guide/pages/investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc +++ b/modules/end-user-guide/pages/investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc @@ -1,6 +1,47 @@ -[id="investigating-failures-at-a-workspace-start-using-the-verbose-mode"] :navtitle: Troubleshooting workspace start failures -:keywords: end-user-guide, investigating-failures-at-a-workspace-start-using-the-verbose-mode +:keywords: user-guide, investigating-failures-at-a-workspace-start-using-the-verbose-mode :page-aliases: .:investigating-failures-at-a-workspace-start-using-the-verbose-mode, .:starting-a-che-workspace-in-debug-mode, starting-a-che-workspace-in-debug-mode, .:restarting-a-che-workspace-in-debug-mode-after-start-failure, restarting-a-che-workspace-in-debug-mode-after-start-failure -include::partial$proc_investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc[] +[id="investigating-failures-at-a-workspace-start-using-the-verbose-mode_{context}"] += Investigating failures at a workspace start using the Verbose mode + +Verbose mode allows users to reach an enlarged log output, investigating failures at a workspace start. + +In addition to usual log entries, the Verbose mode also lists the container logs of each workspace. + + +[id="restarting-a-{prod-id-short}-workspace-in-verbose-mode-after-start-failure_{context}"] +== Restarting a {prod-short} workspace in Verbose mode after start failure + +This section describes how to restart a {prod-short} workspace in the Verbose mode after a failure during the workspace start. Dashboard proposes the restart of a workspace in the Verbose mode once the workspace fails at its start. + + +.Prerequisites + +* A running instance of {prod-short}. + +* An existing workspace that fails to start. + +.Procedure + +. Using Dashboard, try to start a workspace. +. When it fails to start, click on the displayed *Open in Verbose mode* link. +. Check the *Logs* tab to find a reason for the workspace failure. + + +[id="starting-a-{prod-id-short}-workspace-in-verbose-mode_{context}"] +== Starting a {prod-short} workspace in Verbose mode + +This section describes how to start the {prod} workspace in Verbose mode. + +.Prerequisites + +* A running instance of {prod}. + +* An existing workspace defined on this instance of {prod-short}. + +.Procedure + +. Open the *Workspaces* tab. +. On the left side of a row dedicated to the workspace, access the drop-down menu displayed as three horizontal dots and select the *Open in Verbose mode* option. Alternatively, this option is also available in the workspace details, under the *Actions* drop-down menu. +. Check the *Logs* tab to find a reason for the workspace failure. diff --git a/modules/end-user-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container.adoc b/modules/end-user-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container.adoc deleted file mode 100644 index df5cd2944c..0000000000 --- a/modules/end-user-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container"] -// = Mounting a secret as a file or an environment variable into a workspace container -:navtitle: Mounting a secret as a file or an environment variable into a workspace container -:keywords: end-user-guide, mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container -:page-aliases: .:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container - -include::partial$assembly_mounting-secrets-as-file-or-env-variable-in-workspace-container.adoc[] diff --git a/modules/end-user-guide/partials/assembly_accessing-che-from-openshift-developer-perspective.adoc b/modules/end-user-guide/pages/navigating-che-from-openshift-developer-perspective.adoc similarity index 66% rename from modules/end-user-guide/partials/assembly_accessing-che-from-openshift-developer-perspective.adoc rename to modules/end-user-guide/pages/navigating-che-from-openshift-developer-perspective.adoc index a49baa5469..c39e39d9db 100644 --- a/modules/end-user-guide/partials/assembly_accessing-che-from-openshift-developer-perspective.adoc +++ b/modules/end-user-guide/pages/navigating-che-from-openshift-developer-perspective.adoc @@ -1,18 +1,19 @@ - +:navtitle: Navigating {prod-short} from OpenShift Developer Perspective +:keywords: overview, accessing-che-from-openshift-developer-perspective +:page-aliases: .:accessing-che-from-openshift-developer-perspective, overview:accessing-che-from-openshift-developer-perspective, accessing-che-from-openshift-developer-perspective :parent-context-of-accessing-che-from-openshift-developer-perspective: {context} -[id="accessing-{prod-id-short}-from-openshift-developer-perspective_{context}"] -= Accessing {prod-short} from OpenShift Developer Perspective +[id="navigating-{prod-id-short}-from-openshift-developer-perspective_{context}"] += Navigating {prod-short} from OpenShift Developer Perspective :context: accessing-{prod-id-short}-from-openshift-developer-perspective - The OpenShift Container Platform web console provides two perspectives; the *Administrator* perspective and the *Developer* perspective. The Developer perspective provides workflows specific to developer use cases, such as the ability to: -* Create and deploy applications on OpenShift Container Platform by importing existing codebases, images, and Dockerfiles. +* Create and deploy applications on the OpenShift Container Platform by importing existing codebases, images, and Dockerfiles. * Visually interact with applications, components, and services associated with them within a project and monitor their deployment and build status. diff --git a/modules/end-user-guide/pages/navigating-che-using-the-dashboard.adoc b/modules/end-user-guide/pages/navigating-che-using-the-dashboard.adoc deleted file mode 100644 index 1f08d869e1..0000000000 --- a/modules/end-user-guide/pages/navigating-che-using-the-dashboard.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="navigating-che-using-the-dashboard"] -// = Navigating Che: dashboard -:navtitle: Navigating Che: dashboard -:keywords: end-user-guide, navigating-che-using-the-dashboard -:page-aliases: .:navigating-che-using-the-dashboard - -include::partial$assembly_navigating-che-using-the-dashboard.adoc[] diff --git a/modules/end-user-guide/pages/navigating-che.adoc b/modules/end-user-guide/pages/navigating-che.adoc deleted file mode 100644 index 328b38ad26..0000000000 --- a/modules/end-user-guide/pages/navigating-che.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="navigating-che"] -// = Navigating Che -:navtitle: Navigating Che -:keywords: end-user-guide, navigating-che -:page-aliases: .:navigating-che - -include::partial$assembly_navigating-che.adoc[] diff --git a/modules/end-user-guide/pages/navigating-openshift-web-console-from-che.adoc b/modules/end-user-guide/pages/navigating-openshift-web-console-from-che.adoc new file mode 100644 index 0000000000..ee751117b0 --- /dev/null +++ b/modules/end-user-guide/pages/navigating-openshift-web-console-from-che.adoc @@ -0,0 +1,24 @@ +:navtitle: Navigating OpenShift web console from {prod-short} +:keywords: overview, OpenShift, web console +:page-aliases: .:accessing-openshift-web-console-from-che, overview:accessing-openshift-web-console-from-che, accessing-openshift-web-console-from-che + +:parent-context-of-accessing-che-from-openshift-developer-perspective: {context} + +[id="navigating-openshift-web-console-from-{prod-id-short}_{context}"] += Navigating OpenShift web console from {prod-short} + +This section describes how to access OpenShift web console from {prod-short}. + +.Prerequisites + +* The {prod-short} Operator is available in OpenShift 4. + +.Procedure + +. Open the {prod-short} dashboard and click the three-by-three matrix icon in the upper right corner of the main screen. ++ +The drop-down menu displays the available applications. ++ +image::navigation/navigating-openshift-web-console-from-che-dashboard.png[OpenShift web console in the drop-down menu,link="{imagesdir}/navigation/navigating-openshift-web-console-from-che-dashboard.png"] + +. Click the *OpenShift console* link to open the OpenShift web console. diff --git a/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc b/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc new file mode 100644 index 0000000000..148965acf8 --- /dev/null +++ b/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc @@ -0,0 +1,93 @@ +:_content-type: CONCEPT +:description: Optional parameters for the URLs for starting a new workspace +:keywords: url, urls, parameter, parameters, starting, start, workspace, workspaces, url-parameter, url-parameters, multiple-url-parameters, combine-url-parameters, several-url-parameters, add-url-parameters, concatenate, concatenate-multiple-URL-parameters, concatenate-URL-parameters, concatenating, concatenating-multiple-URL-parameters, concatenating-URL-parameters, concatenation, start-duplicate-workspaces, start-duplicated-workspaces, duplicate-workspace, duplicate-workspaces, duplicated-workspace, duplicated-workspaces, how-to-start-a-duplicate, how-to-start-duplicate, devfile, override-devfile-file-name, override-file-name, file-name, devfile-name, different-devfile-name, file-path, devfile-path, devfile-file-path, devfile-path-parameter, devfile-file-path-parameterdevfile, file-path, devfile-path, devfile-file-path, devfile-path-parameter, devfile-file-path-parameter +:navtitle: Optional parameters for the URLs for starting a new workspace +// :page-aliases: + +[id="parameters-for-the-urls-for-starting-a-new-workspace_{context}"] += Optional parameters for the URLs for starting a new workspace + +When you start a new workspace, {prod-short} configures the workspace according to the instructions in the devfile. When you use a URL to start a new workspace, you can append optional parameters to the URL that further configure the workspace. You can use these parameters to specify a workspace IDE, start duplicate workspaces, and specify a devfile file name or path. + +== URL parameter concatenation + +The URL for starting a new workspace supports concatenation of multiple optional URL parameters by using `&` with the following URL syntax: + +`pass:c,a,q[{prod-url}]#__<git_repository_url>__?__<url_parameter_1>__&__<url_parameter_2>__&__<url_parameter_3>__` + +.A URL for starting a new workspace with the URL of a Git repository and optional URL parameters +==== +The complete URL for the browser: + +`pass:c,a,q[{prod-url}#https://github.com/che-samples/cpp-hello-world?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml]` + +Explanation of the parts of the URL: + +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}] <1> +#https://github.com/che-samples/cpp-hello-world <2> +?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml <3> +---- +<1> {prod-short} URL. +<2> The URL of the Git repository to be cloned into the new workspace. +<3> The concatenated optional URL parameters. +==== + +== URL parameter for the workspace IDE + +Che-Theia is the default integrated development environment (IDE) that a workspace loads with if no IDE is specified as a URL parameter as part of the URL for starting a new workspace. + +The URL parameter for specifying another supported IDE is `che-editor=__<editor_key>__`: + +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#__<git_repository_url>__?che-editor=__<editor_key>__ +---- + +include::example$snip_{project-context}-supported-ides.adoc[] + +== URL parameter for starting duplicate workspaces + +Visiting a URL for starting a new workspace results in a new workspace according to the devfile and with a clone of the linked Git repository. + +In some situations, you may need to have multiple workspaces that are duplicates in terms of the devfile and the linked Git repository. You can do this by visiting the same URL for starting a new workspace with a URL parameter. + +The URL parameter for starting a duplicate workspace is `new`: + +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#__<git_repository_url>__?new +---- + +NOTE: If you currently have a workspace that you started using a URL, then visiting the URL again without the `new` URL parameter results in an error message. + +== URL parameter for the devfile file name + +When you visit a URL for starting a new workspace, {prod-short} searches the linked Git repository for a devfile with the file name `.devfile.yaml` or `devfile.yaml`. The devfile in the linked Git repository must follow this file-naming convention. + +In some situations, you may need to specify a different, unconventional file name for the devfile. + +The URL parameter for specifying an unconventional file name of the devfile is `df=__<filename>__.yaml`: + +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#__<git_repository_url>__?df=__<filename>__.yaml <1> +---- +<1> `__<filename>__.yaml` is an unconventional file name of the devfile in the linked Git repository. + +TIP: The `df=__<filename>__.yaml` parameter also has a long version: `devfilePath=__<filename>__.yaml`. + +== URL parameter for the devfile file path + +When you visit a URL for starting a new workspace, {prod-short} searches the root directory of the linked Git repository for a devfile (with the file name `.devfile.yaml` or `devfile.yaml`). The file path of the devfile in the linked Git repository must follow this path convention. + +In some situations, you may need to specify a different, unconventional file path for the devfile in the linked Git repository. + +The URL parameter for specifying an unconventional file path of the devfile is `devfilePath=__<relative_file_path>__`: + +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#__<git_repository_url>__?devfilePath=__<relative_file_path>__ <1> +---- +<1> `__<relative_file_path>__` is an unconventional file path of the devfile in the linked Git repository. \ No newline at end of file diff --git a/modules/end-user-guide/pages/provisioning-the-jetbrains-offline-activation-code.adoc b/modules/end-user-guide/pages/provisioning-the-jetbrains-offline-activation-code.adoc deleted file mode 100644 index 04cecdaabd..0000000000 --- a/modules/end-user-guide/pages/provisioning-the-jetbrains-offline-activation-code.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="provisioning-the-jetbrains-offline-activation-code"] -:navtitle: JetBrains offline activation code -:keywords: end-user-guide, jetbrains-activation-code-for-offline-use -:page-aliases: provisioning-jetbrains-activation-code-for-offline-use - -include::partial$proc_provisioning-the-jetbrains-offline-activation-code.adoc[] diff --git a/modules/end-user-guide/pages/publishing-metadata-for-a-vs-code-extension.adoc b/modules/end-user-guide/pages/publishing-metadata-for-a-vs-code-extension.adoc deleted file mode 100644 index bd622ff5ef..0000000000 --- a/modules/end-user-guide/pages/publishing-metadata-for-a-vs-code-extension.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="publishing-metadata-for-a-vs-code-extension"] -// = Publishing a VS Code extension -:navtitle: Publishing a VS Code extension -:keywords: end-user-guide, publishing-metadata-for-a-vs-code-extension -:page-aliases: .:publishing-metadata-for-a-vs-code-extension - -include::partial$proc_publishing-metadata-for-a-vs-code-extension.adoc[] diff --git a/modules/end-user-guide/pages/remotely-accessing-workspaces.adoc b/modules/end-user-guide/pages/remotely-accessing-workspaces.adoc deleted file mode 100644 index 61c10b6888..0000000000 --- a/modules/end-user-guide/pages/remotely-accessing-workspaces.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="remotely-accessing-workspaces"] -// = Remotely accessing workspaces -:navtitle: Remotely accessing workspaces -:keywords: end-user-guide, remotely-accessing-workspaces -:page-aliases: .:remotely-accessing-workspaces - -include::partial$assembly_remotely-accessing-workspaces.adoc[] diff --git a/modules/end-user-guide/pages/running-a-workspace-with-dashboard.adoc b/modules/end-user-guide/pages/running-a-workspace-with-dashboard.adoc deleted file mode 100644 index abc64dfca5..0000000000 --- a/modules/end-user-guide/pages/running-a-workspace-with-dashboard.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="configuring-a-workspace-with-dashboard"] -:navtitle: Running a workspace -:keywords: end-user-guide, starting-a-workspace-with-dashboard -:page-aliases: .:starting-a-workspace-with-dashboard - -include::partial$assembly_running-an-existing-workspace-from-the-user-dashboard.adoc[] diff --git a/modules/end-user-guide/partials/proc_mounting-a-secret-as-a-file-into-a-workspace-container.adoc b/modules/end-user-guide/pages/secret-as-a-file.adoc similarity index 58% rename from modules/end-user-guide/partials/proc_mounting-a-secret-as-a-file-into-a-workspace-container.adoc rename to modules/end-user-guide/pages/secret-as-a-file.adoc index 5d409b8d30..e6b8f1f3a6 100644 --- a/modules/end-user-guide/partials/proc_mounting-a-secret-as-a-file-into-a-workspace-container.adoc +++ b/modules/end-user-guide/pages/secret-as-a-file.adoc @@ -1,21 +1,15 @@ -// Module included in the following assemblies: -// -// mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container +:navtitle: Secret as a file +:keywords: user-guide, configuring, user, secrets +:page-aliases: [id="mounting-a-secret-as-a-file-into-a-workspace-container_{context}"] = Mounting a secret as a file into a workspace container -WARNING: On -ifeval::["{project-context}" == "che"] -{platforms-name} older than v1.13 and -endif::[] -OpenShift {ocp3-ver}, secrets mounted as file overrides volume mounts defined in the devfile. - This section describes how to mount a secret from the user's {orch-namespace} as a file in single-workspace or multiple-workspace containers of {prod-short}. .Prerequisites -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. +* A running instance of {prod-short}. .Procedure @@ -26,4 +20,4 @@ This section describes how to mount a secret from the user's {orch-namespace} as * `app.kubernetes.io/part-of: che.eclipse.org` * `app.kubernetes.io/component: workspace-secret`: + -include::example${project-context}-ref_a-kubernetes-secret-as-a-file.adoc[levelofset=+1] +include::example$snip_{project-context}-a-kubernetes-secret-as-a-file.adoc[levelofset=+1] diff --git a/modules/end-user-guide/partials/proc_mounting-a-secret-as-an-environment-variable-into-a-workspace-container.adoc b/modules/end-user-guide/pages/secret-as-a-variable.adoc similarity index 71% rename from modules/end-user-guide/partials/proc_mounting-a-secret-as-an-environment-variable-into-a-workspace-container.adoc rename to modules/end-user-guide/pages/secret-as-a-variable.adoc index da00e8b385..fc4356ad4a 100644 --- a/modules/end-user-guide/partials/proc_mounting-a-secret-as-an-environment-variable-into-a-workspace-container.adoc +++ b/modules/end-user-guide/pages/secret-as-a-variable.adoc @@ -1,6 +1,6 @@ -// Module included in the following assemblies: -// -// mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container +:navtitle: Secret as environment variable +:keywords: user-guide, configuring, user, secrets +:page-aliases: [id="mounting-a-secret-as-an-environment-variable-into-a-workspace-container_{context}"] = Mounting a secret as an environment variable into a workspace container @@ -9,7 +9,7 @@ The following section describes how to mount a {platforms-name} secret from the .Prerequisites -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. +* A running instance of {prod-short}. .Procedure @@ -20,4 +20,4 @@ The following section describes how to mount a {platforms-name} secret from the * `app.kubernetes.io/part-of: che.eclipse.org` * `app.kubernetes.io/component: workspace-secret`: + -include::example${project-context}-ref_a-kubernetes-secret-as-an-variable.adoc[levelofset=+1] +include::example$snip_{project-context}-a-kubernetes-secret-as-an-variable.adoc[levelofset=+1] diff --git a/modules/end-user-guide/pages/selecting-an-ide.adoc b/modules/end-user-guide/pages/selecting-an-ide.adoc new file mode 100644 index 0000000000..281db2bfc6 --- /dev/null +++ b/modules/end-user-guide/pages/selecting-an-ide.adoc @@ -0,0 +1,17 @@ +:navtitle: Selecting an IDE +:keywords: user-guide, selecting, IDE +:page-aliases: che-theia-ide-basics, version-control, using-alternative-ides-in-che, configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform, building-images-for-ides-based-on-the-intellij-platform, provisioning-the-jetbrains-offline-activation-code, support-for-theia-based-ides, che-theia-troubleshooting, differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode + +[id="selecting-an-ide_{context}"] += Selecting an IDE + +You can select your IDE at when starting a workspace: + +* link:https://theia-ide.org/docs/[Eclipse Theia] (default IDE) +* JetBrains IDE such as IntelliJ or PyCharm +* Visual Studio Code + +.Additional resources + +See: link:https://theia-ide.org/docs/[] + diff --git a/modules/end-user-guide/pages/starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc b/modules/end-user-guide/pages/starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc new file mode 100644 index 0000000000..45626c2439 --- /dev/null +++ b/modules/end-user-guide/pages/starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc @@ -0,0 +1,90 @@ +:_content-type: PROCEDURE +:description: Starting a new workspace with a clone of a Git repository +: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: Starting a new workspace with a clone of a Git repository +// :page-aliases: + +[id="starting-a-new-workspace-with-a-clone-of-a-git-repository_{context}"] += Starting a new workspace with a clone of a Git repository + +Working with {prod-short} in your browser involves multiple URLs: + +* The URL of your organization's {prod-short} instance, used as part of all the following URLs +* The URL of the *Workspaces* page of your {prod-short} dashboard with the workspace control panel +* [.underline]#The URLs for starting a new workspace# +* The URLs of your workspaces in use + +With {prod-short}, you can visit 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, a GitLab instance, or a Bitbucket server. + +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 Git repository to start a new workspace. + +.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}]`. +* 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[].) ++ +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 the Che-Theia IDE and the Universal Developer Image. +//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}]#__<git_repository_url>__ +---- ++ +[TIP] +==== +You can extend this URL with optional parameters: +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#__<git_repository_url>__?__<optional_parameters>__ <1> +---- +<1> See xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]. +==== ++ +.A URL for starting a new workspace +==== + +`pass:c,a,q[{prod-url}#https://github.com/che-samples/cpp-hello-world]` + +==== ++ +.The URL syntax for starting a new workspace with a clone of a GitHub-hosted repository +==== + +With GitHub and GitLab, you can even use the URL of a specific branch of the repository to be cloned: + +* `pass:c,a,q[{prod-url}#https://github.com/__<user_or_org>__/__<repository>__]` starts a new workspace with a clone of the default branch. +* `pass:c,a,q[{prod-url}#https://github.com/__<user_or_org>__/__<repository>__/tree/__<branch_name>__]` starts a new workspace with a clone of the specified branch. +* `pass:c,a,q[{prod-url}#https://github.com/__<user_or_org>__/__<repository>__/pull/__<pull_request_id>__]` starts a new workspace with a clone of the branch of the pull request. +==== ++ +After you enter the URL to start a new workspace in a browser tab, it renders the workspace-starting page. ++ +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}]#workspace__<unique_url>__`. + +[TIP] +==== +Although this is not possible in the address bar, you can add a URL for starting a new workspace as a bookmark by using the browser bookmark manager: + +* In Mozilla Firefox, go to *☰* *>* *Bookmarks* *>* *Manage bookmarks Ctrl+Shift+O* *>* *Bookmarks Toolbar* *>* *Organize* *>* *Add bookmark*. + +* In Google Chrome, go to *⋮* *>* *Bookmarks* *>* *Bookmark manager* *>* *Bookmarks bar* *>* *⋮* *>* *Add new bookmark*. +==== + +.Additional resources + +* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] +* xref:basic-actions-you-can-perform-on-a-workspace.adoc[] \ No newline at end of file diff --git a/modules/end-user-guide/pages/support-for-theia-based-ides.adoc b/modules/end-user-guide/pages/support-for-theia-based-ides.adoc deleted file mode 100644 index 6c99ed38d2..0000000000 --- a/modules/end-user-guide/pages/support-for-theia-based-ides.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="support-for-theia-based-ides"] -// = Theia-based IDEs -:navtitle: Theia-based IDEs -:keywords: end-user-guide, theia-based-ides -// :page-aliases: .:theia-based-ides - -include::partial$con_support-for-theia-based-ides.adoc[] diff --git a/modules/end-user-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc b/modules/end-user-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc deleted file mode 100644 index 9c73da7fc4..0000000000 --- a/modules/end-user-guide/pages/testing-a-visual-studio-code-extension-in-che.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="testing-a-visual-studio-code-extension-in-che"] -// = Testing a VS Code extension in Che -:navtitle: Testing a VS Code extension in Che -:keywords: contributor-guide, testing-a-visual-studio-code-extension-in-che -:page-aliases: .:testing-a-visual-studio-code-extension-in-che, administration-guide:testing-a-visual-studio-code-extension-in-che - -include::partial$assembly_testing-a-visual-studio-code-extension-in-che.adoc[] diff --git a/modules/end-user-guide/pages/troubleshooting-che.adoc b/modules/end-user-guide/pages/troubleshooting-che.adoc index b4c507d455..db2c0b58fa 100644 --- a/modules/end-user-guide/pages/troubleshooting-che.adoc +++ b/modules/end-user-guide/pages/troubleshooting-che.adoc @@ -1,7 +1,15 @@ -[id="troubleshooting-che"] -// = Troubleshooting Che :navtitle: Troubleshooting Che -:keywords: end-user-guide, troubleshooting-che +:keywords: user-guide, troubleshooting-che :page-aliases: .:troubleshooting-che -include::partial$assembly_troubleshooting-che.adoc[] +[id="troubleshooting-{prod-id-short}_{context}"] += Troubleshooting {prod-short} + +This section provides troubleshooting procedures for the most frequent issues a user can come in conflict with. + +.Additional resources + +* xref:viewing-che-workspaces-logs.adoc[] +* xref:investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc[] +* xref:troubleshooting-slow-workspaces.adoc[] +* xref:troubleshooting-network-problems.adoc[] diff --git a/modules/end-user-guide/pages/troubleshooting-network-problems.adoc b/modules/end-user-guide/pages/troubleshooting-network-problems.adoc index af14bad6e8..b7271ee074 100644 --- a/modules/end-user-guide/pages/troubleshooting-network-problems.adoc +++ b/modules/end-user-guide/pages/troubleshooting-network-problems.adoc @@ -1,7 +1,25 @@ -[id="troubleshooting-network-problems"] -// = Troubleshooting network problems :navtitle: Troubleshooting network problems -:keywords: end-user-guide, troubleshooting-network-problems +:keywords: user-guide, troubleshooting-network-problems :page-aliases: .:troubleshooting-network-problems -include::partial$proc_troubleshooting-network-problems.adoc[] +[id="troubleshooting-network-problems_{context}"] += Troubleshooting network problems + +This section describes how to prevent or resolve issues related to network policies. +{prod-short} requires the availability of the WebSocket Secure (WSS) connections. +Secure WebSocket connections improve confidentiality and also reliability because they reduce the risk of interference by bad proxies. + +.Prerequisites + +* The WebSocket Secure (WSS) connections on port 443 must be available on the network. Firewall and proxy may need additional configuration. +* Use a supported web browser: +** Google Chrome +** Mozilla Firefox + +.Procedure + +. Verify the browser supports the WebSocket protocol. See: link:https://www.google.com/search?q=websocket+test[Searching a websocket test]. + +. Verify firewalls settings: WebSocket Secure (WSS) connections on port 443 must be available. + +. Verify proxy servers settings: The proxy transmits and intercepts WebSocket Secure (WSS) connections on port 443. diff --git a/modules/end-user-guide/pages/troubleshooting-slow-workspaces.adoc b/modules/end-user-guide/pages/troubleshooting-slow-workspaces.adoc index 725c545274..eb6508c1e7 100644 --- a/modules/end-user-guide/pages/troubleshooting-slow-workspaces.adoc +++ b/modules/end-user-guide/pages/troubleshooting-slow-workspaces.adoc @@ -1,7 +1,121 @@ -[id="troubleshooting-slow-workspaces"] -// = Troubleshooting slow workspaces :navtitle: Troubleshooting slow workspaces -:keywords: end-user-guide, troubleshooting-slow-workspaces +:keywords: user-guide, troubleshooting-slow-workspaces :page-aliases: .:troubleshooting-slow-workspaces -include::partial$proc_troubleshooting-slow-workspaces.adoc[] +[id="troubleshooting-slow-workspaces_{context}"] += Troubleshooting slow workspaces + +Sometimes, workspaces can take a long time to start. Tuning can reduce this start time. Depending on the options, administrators or users can do the tuning. + +This section includes several tuning options for starting workspaces faster or improving workspace runtime performance. + +[id="improving-workspace-start-time_{context}"] +== Improving workspace start time + +Caching images with {image-puller-name-short}:: ++ +_Role: Administrator_ ++ +When starting a workspace, {orch-name} pulls the images from the registry. A workspace can include many containers meaning that {orch-name} pulls Pod's images (one per container). Depending on the size of the image and the bandwidth, it can take a long time. ++ +{image-puller-name-short} is a tool that can cache images on each of {orch-name} nodes. As such, pre-pulling images can improve start times. See xref:administration-guide:caching-images-for-faster-workspace-start.adoc[]. + +Choosing better storage type:: ++ +_Role: Administrator and user_ ++ +Every workspace has a shared volume attached. This volume stores the project files, so that when restarting a workspace, changes are still available. Depending on the storage, attach time can take up to a few minutes, and I/O can be slow. + +Installing offline:: ++ +_Role: Administrator_ ++ +Components of {prod-short} are OCI images. Set up {prod} in offline mode (air-gap scenario) to reduce any extra download at runtime because everything needs to be available from the beginning. See xref:administration-guide:installing-che-in-a-restricted-environment.adoc[]. + +Optimizing workspace plug-ins:: ++ +_Role: User_ ++ +When selecting various plug-ins, each plug-in can bring its own sidecar container, which is an OCI image. {orch-name} pulls the images of these sidecar containers. ++ +Reduce the number of plug-ins, or disable them to see if start time is faster. See also xref:administration-guide:caching-images-for-faster-workspace-start.adoc[]. + +Reducing the number of public endpoints:: ++ +_Role: Administrator_ ++ +For each endpoint, {orch-name} is creating {platforms-ingress} objects. Depending on the underlying configuration, this creation can be slow. ++ +To avoid this problem, reduce the exposure. For example, to automatically detect a new port listening inside containers and redirect traffic for the processes using a local IP address (`127.0.0.1`), the Che-Theia IDE plug-in has three optional routes. ++ +By reducing the number of endpoints and checking endpoints of all plug-ins, workspace start can be faster. + +CDN configuration:: ++ +The IDE editor uses a CDN (Content Delivery Network) to serve content. Check that the content uses a CDN to the client (or a local route for offline setup). ++ +To check that, open Developer Tools in the browser and check for `vendors` in the *Network* tab. `vendors.<random-id>.js` or `editor.main.*` should come from CDN URLs. + + +[id="improving-workspace-runtime-performance_{context}"] +== Improving workspace runtime performance + +Providing enough CPU resources:: ++ +Plug-ins consume CPU resources. For example, when a plug-in provides IntelliSense features, adding more CPU resources may lead to better performance. ++ +Ensure the CPU settings in the devfile definition, `devfile.yaml`, are correct: ++ +[source,yaml] +---- +apiVersion: 1.0.0 + +components: + - + type: chePlugin + id: id/of/plug-in + cpuLimit: 1360Mi <1> + cpuRequest: 100m <2> +---- +<1> Specifies the CPU limit for the plug-in. +<2> Specifies the CPU request for the plug-in. + +Providing enough memory:: ++ +Plug-ins consume CPU and memory resources. For example, when a plug-in provides IntelliSense features, collecting data can consume all the memory allocated to the container. ++ +Providing more memory to the plug-in can increase performance. Ensure about the correctness of memory settings: ++ +* in the plug-in definition - `meta.yaml` file +* in the devfile definition - `devfile.yaml` file ++ +[source,yaml] +---- +apiVersion: v2 + +spec: + containers: + - image: "quay.io/my-image" + name: "vscode-plugin" + memoryLimit: "512Mi" <1> + extensions: + - https://link.to/vsix +---- +<1> Specifies the memory limit for the plug-in. ++ +In the devfile definition (`devfile.yaml`): ++ +[source,yaml] +---- +apiVersion: 1.0.0 + +components: + - + type: chePlugin + id: id/of/plug-in + memoryLimit: 1048M <1> + memoryRequest: 256M +---- +<1> Specifies the memory limit for this plug-in. + + diff --git a/modules/end-user-guide/pages/user-onboarding.adoc b/modules/end-user-guide/pages/user-onboarding.adoc new file mode 100644 index 0000000000..c1f282fc4d --- /dev/null +++ b/modules/end-user-guide/pages/user-onboarding.adoc @@ -0,0 +1,14 @@ +:_content-type: CONCEPT +:description: User onboarding +:keywords: getting-started, user-onboarding, new-user, new-users +:navtitle: User onboarding +// :page-aliases: + +[id="user-onboarding_{context}"] += User onboarding + +If your organization is already running a {prod-short} instance, you can get started as a new user of {prod-short} by first learning how to start a new workspace and how to manage your workspaces: + +. xref:starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc[] +. xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[] +. xref:basic-actions-you-can-perform-on-a-workspace.adoc[] diff --git a/modules/end-user-guide/pages/using-alternative-ides-in-che.adoc b/modules/end-user-guide/pages/using-alternative-ides-in-che.adoc deleted file mode 100644 index 2f6e4cbf4c..0000000000 --- a/modules/end-user-guide/pages/using-alternative-ides-in-che.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-alternative-ides-in-che"] -// = Using alternative IDEs in Che -:navtitle: Using alternative IDEs in Che -:keywords: end-user-guide, using-alternative-ides-in-che -:page-aliases: .:using-alternative-ides-in-che - -include::partial$assembly_using-alternative-ides-in-che.adoc[] diff --git a/modules/end-user-guide/pages/using-artifact-repositories-in-a-restricted-environment.adoc b/modules/end-user-guide/pages/using-artifact-repositories-in-a-restricted-environment.adoc deleted file mode 100644 index d4848dd731..0000000000 --- a/modules/end-user-guide/pages/using-artifact-repositories-in-a-restricted-environment.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-artifact-repositories-in-a-restricted-environment"] -// = Using artifact repositories in a restricted environment -:navtitle: Using artifact repositories in a restricted environment -:keywords: end-user-guide, using-artifact-repositories-in-a-restricted-environment -:page-aliases: .:using-artifact-repositories-in-a-restricted-environment - -include::partial$assembly_using-artifact-repositories-in-a-restricted-environment.adoc[] diff --git a/modules/end-user-guide/pages/using-developer-workspaces.adoc b/modules/end-user-guide/pages/using-developer-workspaces.adoc new file mode 100644 index 0000000000..e8f7b7b760 --- /dev/null +++ b/modules/end-user-guide/pages/using-developer-workspaces.adoc @@ -0,0 +1,22 @@ +:navtitle: Using developer workspaces +:keywords: user-guide, workspaces-overview +:page-aliases: .:workspaces-overview, .:what-are-workspaces.html, .:creating-and-configuring-a-new-workspace, creating-and-configuring-a-new-workspace, authenticating-on-scm-server-with-a-personal-access-token, navigating-che, navigating-che-using-the-dashboard, importing-certificates-to-browsers, creating-a-workspace-from-local-devfile-using-chectl, importing-kubernetes-applications-into-a-workspace, workspaces-overview, configuring-a-workspace-with-dashboard, creating-a-workspace-from-a-code-sample, creating-a-workspace-from-a-template-devfile, creating-a-workspace-from-remote-devfile, running-a-workspace-with-dashboard, remotely-accessing-workspaces, importing-the-source-code-of-a-project-into-a-workspace + +[id="developer-workspaces_{context}"] += Developer workspaces + +{prod} provides developer workspaces with everything you need to code, build, test, run, and debug applications: + +* Project source code +* Web-based integrated development environment (IDE) +* Tool dependencies needed by developers to work on a project +* Application runtime: a replica of the environment where the application runs in production + +Pods manage each component of a {prod-short} workspace. Therefore, everything running in a {prod-short} workspace is running inside containers. This makes a {prod-short} workspace highly portable. + +The embedded browser-based IDE is the point of access for everything running in a {prod-short} workspace. This makes a {prod-short} workspace easy to share. + +Typical use cases: + +* xref:first-time-contributors.adoc[] +* xref:benefits-of-pull-requests-review-in-che.adoc[] diff --git a/modules/end-user-guide/pages/using-go-artifact-repositories.adoc b/modules/end-user-guide/pages/using-go-artifact-repositories.adoc deleted file mode 100644 index d5cf31a7ca..0000000000 --- a/modules/end-user-guide/pages/using-go-artifact-repositories.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-go-artifact-repositories"] -// = Using Go artifact repositories -:navtitle: Using Go artifact repositories -:keywords: end-user-guide, using-go-artifact-repositories -:page-aliases: .:using-go-artifact-repositories - -include::partial$assembly_using-go-artifact-repositories.adoc[] diff --git a/modules/end-user-guide/pages/using-gradle-artifact-repositories.adoc b/modules/end-user-guide/pages/using-gradle-artifact-repositories.adoc deleted file mode 100644 index bd157d8b72..0000000000 --- a/modules/end-user-guide/pages/using-gradle-artifact-repositories.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-gradle-artifact-repositories"] -// = Using Gradle artifact repositories -:navtitle: Using Gradle artifact repositories -:keywords: end-user-guide, using-gradle-artifact-repositories -:page-aliases: .:using-gradle-artifact-repositories - -include::partial$assembly_using-gradle-artifact-repositories.adoc[] diff --git a/modules/end-user-guide/pages/using-maven-artifact-repositories.adoc b/modules/end-user-guide/pages/using-maven-artifact-repositories.adoc deleted file mode 100644 index 5b2694ca82..0000000000 --- a/modules/end-user-guide/pages/using-maven-artifact-repositories.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-maven-artifact-repositories"] -// = Using Maven artifact repositories -:navtitle: Using Maven artifact repositories -:keywords: end-user-guide, using-maven-artifact-repositories -:page-aliases: .:using-maven-artifact-repositories - -include::partial$assembly_using-maven-artifact-repositories.adoc[] diff --git a/modules/end-user-guide/pages/using-npm-artifact-repositories.adoc b/modules/end-user-guide/pages/using-npm-artifact-repositories.adoc deleted file mode 100644 index 46fb270ee1..0000000000 --- a/modules/end-user-guide/pages/using-npm-artifact-repositories.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-npm-artifact-repositories"] -// = Using npm artifact repositories -:navtitle: Using npm artifact repositories -:keywords: end-user-guide, using-npm-artifact-repositories -:page-aliases: .:using-npm-artifact-repositories - -include::partial$proc_using-npm-artifact-repositories.adoc[] diff --git a/modules/end-user-guide/pages/using-nuget-artifact-repositories.adoc b/modules/end-user-guide/pages/using-nuget-artifact-repositories.adoc deleted file mode 100644 index 637fee27ec..0000000000 --- a/modules/end-user-guide/pages/using-nuget-artifact-repositories.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-nuget-artifact-repositories"] -// = Using NuGet artifact repositories -:navtitle: Using NuGet artifact repositories -:keywords: end-user-guide, using-nuget-artifact-repositories -:page-aliases: .:using-nuget-artifact-repositories - -include::partial$assembly_using-nuget-artifact-repositories.adoc[] diff --git a/modules/end-user-guide/pages/using-private-container-registries.adoc b/modules/end-user-guide/pages/using-private-container-registries.adoc deleted file mode 100644 index 34c5afc8c0..0000000000 --- a/modules/end-user-guide/pages/using-private-container-registries.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-private-container-registries"] -// = Using private container registries -:navtitle: Using private container registries -:keywords: end-user-guide, using-private-container-registries -:page-aliases: .:using-private-container-registries - -include::partial$proc_using-private-container-registries.adoc[] \ No newline at end of file diff --git a/modules/end-user-guide/pages/using-python-artifact-repositories.adoc b/modules/end-user-guide/pages/using-python-artifact-repositories.adoc deleted file mode 100644 index 43b1c57ca4..0000000000 --- a/modules/end-user-guide/pages/using-python-artifact-repositories.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-python-artifact-repositories"] -// = Using Python artifact repositories -:navtitle: Using Python artifact repositories -:keywords: end-user-guide, using-python-artifact-repositories -:page-aliases: .:using-python-artifact-repositories - -include::partial$assembly_using-python-artifact-repositories.adoc[] diff --git a/modules/end-user-guide/pages/version-control.adoc b/modules/end-user-guide/pages/version-control.adoc deleted file mode 100644 index 09ce83ac23..0000000000 --- a/modules/end-user-guide/pages/version-control.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="version-control"] -// = Version Control -:navtitle: Version Control -:keywords: end-user-guide, version-control -:page-aliases: .:version-control - -include::partial$assembly_version-control.adoc[] diff --git a/modules/end-user-guide/pages/viewing-che-workspaces-logs.adoc b/modules/end-user-guide/pages/viewing-che-workspaces-logs.adoc index 10ddeb7ba2..3d709c9b4c 100644 --- a/modules/end-user-guide/pages/viewing-che-workspaces-logs.adoc +++ b/modules/end-user-guide/pages/viewing-che-workspaces-logs.adoc @@ -1,7 +1,20 @@ -[id="viewing-che-workspaces-logs"] -// = Viewing Che workspaces logs -:navtitle: Viewing Che workspaces logs +:navtitle: Viewing {prod-short} workspaces logs :keywords: administration-guide, viewing-che-workspaces-logs :page-aliases: .:viewing-che-workspaces-logs, administration-guide:viewing-che-workspaces-logs -include::partial$assembly_viewing-che-workspaces-logs.adoc[] +:parent-context-of-viewing-che-workspaces-logs: {context} + +[id="viewing-{prod-id-short}-workspaces-logs_{context}"] += Viewing {prod-short} workspaces logs + +:context: viewing-{prod-id-short}-workspaces-logs + +This section describes how to view {prod-short} workspaces logs. + +include::partial$assembly_viewing-logs-from-language-servers-and-debug-adapters.adoc[leveloffset=+1] + + +include::partial$assembly_viewing-che-theia-ide-logs.adoc[leveloffset=+1] + + +:context: {parent-context-of-viewing-che-workspaces-logs} diff --git a/modules/end-user-guide/pages/what-is-a-che-theia-plug-in.adoc b/modules/end-user-guide/pages/what-is-a-che-theia-plug-in.adoc deleted file mode 100644 index ca2fdcf11b..0000000000 --- a/modules/end-user-guide/pages/what-is-a-che-theia-plug-in.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="what-is-a-che-theia-plug-in"] -// = What is a Che-Theia plug-in -:navtitle: What is a Che-Theia plug-in -:keywords: end-user-guide, what-is-a-che-theia-plug-in -:page-aliases: .:what-is-a-che-theia-plug-in - -include::partial$assembly_what-is-a-che-theia-plug-in.adoc[] diff --git a/modules/end-user-guide/pages/workspaces-overview.adoc b/modules/end-user-guide/pages/workspaces-overview.adoc deleted file mode 100644 index 3c7177faef..0000000000 --- a/modules/end-user-guide/pages/workspaces-overview.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="workspaces-overview"] -// = Using developer workspaces -:navtitle: Using developer workspaces -:keywords: end-user-guide, workspaces-overview -:page-aliases: .:workspaces-overview, .:what-are-workspaces.html, .:creating-and-configuring-a-new-workspace, creating-and-configuring-a-new-workspace - -include::partial$assembly_workspaces-overview.adoc[] diff --git a/modules/end-user-guide/partials/assembly_adding-a-vs-code-extension-to-a-workspace.adoc b/modules/end-user-guide/partials/assembly_adding-a-vs-code-extension-to-a-workspace.adoc deleted file mode 100644 index 7d9e0d72d4..0000000000 --- a/modules/end-user-guide/partials/assembly_adding-a-vs-code-extension-to-a-workspace.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// using-a-visual-studio-code-extension-in-{prod-id-short} - -:parent-context-of-adding-che-plug-in-registry-vs-code-extension-to-a-workspace: {context} - -[id="adding-a-vs-code-extension-to-a-workspace_{context}"] -= Adding a VS Code extension to a workspace - -:context: adding-{prod-id-short}-plug-in-registry-vs-code-extension-to-a-workspace - -This section describes how to add a VS Code extension to a workspace using the workspace configuration. - -.Prerequisites - -* The VS Code extension is available in the {prod-short} plug-in registry, or metadata for the VS Code extension are available. See xref:publishing-metadata-for-a-vs-code-extension.adoc[]. - -include::partial$proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc[leveloffset=+1] - -include::partial$proc_adding-the-vs-code-extension-using-recommendations.adoc[leveloffset=+1] - -:context: {parent-context-of-adding-che-plug-in-registry-vs-code-extension-to-a-workspace} diff --git a/modules/end-user-guide/partials/assembly_adding-tools-to-che-after-creating-a-workspace.adoc b/modules/end-user-guide/partials/assembly_adding-tools-to-che-after-creating-a-workspace.adoc deleted file mode 100644 index 35368f111a..0000000000 --- a/modules/end-user-guide/partials/assembly_adding-tools-to-che-after-creating-a-workspace.adoc +++ /dev/null @@ -1,25 +0,0 @@ -:parent-context-of-adding-tools-to-che-after-creating-a-workspace: {context} - -[id="adding-tools-to-{prod-id-short}-after-creating-a-workspace_{context}"] -= Adding tools to {prod-short} after creating a workspace - -:context: adding-tools-to-{prod-id-short}-after-creating-a-workspace - -When installed in a workspace, {prod-short} plug-ins bring new capabilities to {prod-short}. Plug-ins consist of a Che-Theia plug-in, metadata, and a hosting container. These plug-ins may provide the following capabilities: - -* Integrating with other systems, including {platforms-name}. -* Automating some developer tasks, such as formatting, refactoring, and running automated tests. -* Communicating with multiple databases directly from the IDE. -* Enhanced code navigation, auto-completion, and error highlighting. - -This chapter provides basic information about installing, enabling, and using {prod-short} plug-ins in workspaces. - -* xref:additional-tools-in-the-{prod-id-short}-workspace_{context}[] -* xref:adding-language-support-plug-in-to-the-{prod-id-short}-workspace_{context}[] - -include::partial$con_additional-tools-in-the-che-workspace.adoc[leveloffset=+1] - -include::partial$proc_adding-language-support-plug-in-to-the-che-workspace.adoc[leveloffset=+1] - - -:context: {parent-context-of-adding-tools-to-che-after-creating-a-workspace} diff --git a/modules/end-user-guide/partials/assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc b/modules/end-user-guide/partials/assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc deleted file mode 100644 index 31ac9e0864..0000000000 --- a/modules/end-user-guide/partials/assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc +++ /dev/null @@ -1,26 +0,0 @@ - - -:parent-context-of-authenticating-on-scm-server-with-a-personal-access-token: {context} - -[id="authenticating-on-scm-server-with-a-personal-access-token_{context}"] -= Authenticating users on private repositories of SCM servers - - -The following section describes how to configure user authentications for SCM servers. - -* xref:configuring_bitbucket_authentication_{context}[] - -* xref:configuring_gitlab_authentication_{context}[] - -* xref:configuring_github_authentication_{context}[] - - - -include::partial$proc_configuring_bitbucket_authentication.adoc[leveloffset=+1] - -include::partial$proc_configuring_gitlab_authentication.adoc[leveloffset=+1] - -include::partial$proc_configuring_github_authentication.adoc[leveloffset=+1] - - -:context: {parent-context-of-authenticating-on-scm-server-with-a-personal-access-token} \ No newline at end of file diff --git a/modules/end-user-guide/partials/assembly_authoring-devfiles-version-1.adoc b/modules/end-user-guide/partials/assembly_authoring-devfiles-version-1.adoc deleted file mode 100644 index cddafd49b9..0000000000 --- a/modules/end-user-guide/partials/assembly_authoring-devfiles-version-1.adoc +++ /dev/null @@ -1,22 +0,0 @@ -:parent-context-of-authoring-devfiles-version-1: {context} - -[id="authoring-devfiles-version-1_{context}"] -= Authoring devfiles version 1 - -:context: authoring-devfiles-version-1 - -This section explains the concept of a devfile and how to configure a {prod-short} workspace by using a devfile of the 1.0 specification. - -include::partial$con_what-is-a-devfile.adoc[leveloffset=+1] - -include::partial$con_a-minimal-devfile.adoc[leveloffset=+1] - -include::partial$proc_generating-workspace-names.adoc[leveloffset=+1] - -include::partial$proc_writing-a-devfile-for-your-project.adoc[leveloffset=+1] - -include::partial$ref_devfile-reference.adoc[leveloffset=+1] - -include::partial$ref_objects-supported-in-che.adoc[leveloffset=+1] - -:context: {parent-context-of-authoring-devfiles-version-1} diff --git a/modules/end-user-guide/partials/assembly_authoring-devfiles-version-2.adoc b/modules/end-user-guide/partials/assembly_authoring-devfiles-version-2.adoc deleted file mode 100644 index d6280d20b9..0000000000 --- a/modules/end-user-guide/partials/assembly_authoring-devfiles-version-2.adoc +++ /dev/null @@ -1,22 +0,0 @@ -:parent-context-of-authoring-devfiles-version-2: {context} - -[id="authoring-devfiles-version-2_{context}"] -= Authoring a devfile 2 -//a new attribute to be considered for supported devfile version specification for when all three assemblies on the topic of authoring a devfile are rewritten. max-cx - -:context: authoring-devfiles-version-2 - -When you author or edit a devfile for configuring a workspace, the devfile must meet the latest devfile 2 specification. - -.Prerequisites -* An instance of {prod-short} with the xref:installation-guide:enabling-dev-workspace-operator.adoc[{devworkspace} Operator] enabled. See xref:installation-guide:installing-che.adoc[Installing {prod-short}]. - -.Procedure - -* Follow the instructions in the link:https://devfile.io/docs/devfile/2.0.0/user-guide/authoring-stacks.html[Devfile User Guide]. - -.Additional resources - -* For more information about devfile object schema and object properties, see the link:https://redhat-developer.github.io/devfile/devfile[Introduction to Devfiles]. - -:context: {parent-context-of-authoring-devfiles-version-2} diff --git a/modules/end-user-guide/partials/assembly_authoring-devfiles.adoc b/modules/end-user-guide/partials/assembly_authoring-devfiles.adoc deleted file mode 100644 index 7a8efd2b10..0000000000 --- a/modules/end-user-guide/partials/assembly_authoring-devfiles.adoc +++ /dev/null @@ -1,12 +0,0 @@ -:parent-context-of-authoring-devfiles: {context} - -[id="authoring-devfiles_{context}"] -= Authoring devfiles - -:context: authoring-devfiles - -* xref:authoring-devfiles-version-1.adoc[] - -* xref:authoring-devfiles-version-2.adoc[] - -:context: {parent-context-of-authoring-devfiles} diff --git a/modules/end-user-guide/partials/assembly_building-images-for-ides-based-on-the-intellij-platform.adoc b/modules/end-user-guide/partials/assembly_building-images-for-ides-based-on-the-intellij-platform.adoc deleted file mode 100644 index ea2ad76d82..0000000000 --- a/modules/end-user-guide/partials/assembly_building-images-for-ides-based-on-the-intellij-platform.adoc +++ /dev/null @@ -1,18 +0,0 @@ -:parent-context-of-building-images-for-ides-based-on-the-intellij-platform: {context} - -[id="building-images-for-ides-based-on-the-intellij-platform_{context}"] -= Building images for IDEs based on the IntelliJ Platform - -:context: building-images-for-ides-based-on-the-intellij-platform - -This section describes how to build images for link:https://plugins.jetbrains.com/docs/intellij/intellij-platform.html#ides-based-on-the-intellij-platform[IDEs based on the IntelliJ Platform] link:https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#intellij-platform-based-products-of-recent-ide-versions[version 2020.3]. - - -include::partial$proc_building-an-image-for-intellij-idea-community-or-pycharm-community.adoc[leveloffset=+1] - - -include::partial$proc_building-an-image-for-an-ide-based-on-the-intellij-platform.adoc[leveloffset=+1] - - -:context: {parent-context-of-building-images-for-ides-based-on-the-intellij-platform} - diff --git a/modules/end-user-guide/partials/assembly_che-theia-ide-basics.adoc b/modules/end-user-guide/partials/assembly_che-theia-ide-basics.adoc deleted file mode 100644 index e4bf515282..0000000000 --- a/modules/end-user-guide/partials/assembly_che-theia-ide-basics.adoc +++ /dev/null @@ -1,20 +0,0 @@ - - -:parent-context-of-che-theia-ide-basics: {context} - -[id="che-theia-ide-basics_{context}"] -= Che-Theia IDE basics - -:context: che-theia-ide-basics - -This section describes basics workflows and commands for Che-Theia: the native integrated development environment for {prod}. - -* xref:defining-custom-commands-for-che-theia.adoc[] - -* xref:version-control.adoc[] - -* xref:che-theia-troubleshooting.adoc[] - -* xref:differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc[] - -:context: {parent-context-of-che-theia-ide-basics} diff --git a/modules/end-user-guide/partials/assembly_che-theia-remote-plugin-image.adoc b/modules/end-user-guide/partials/assembly_che-theia-remote-plugin-image.adoc deleted file mode 100644 index a517d1542c..0000000000 --- a/modules/end-user-guide/partials/assembly_che-theia-remote-plugin-image.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// This assembly is included in the following assemblies: -// -// what-is-a-che-theia-plug-in - -:parent-context-of-remote-plug-in-endpoint: {context} - -[id="remote-plug-in-endpoint_{context}"] -= Remote plug-in endpoint - -:context: remote-plug-in-endpoint - -{prod} has a remote plug-in endpoint service to start VS Code Extensions and Che-Theia plug-ins in separate containers. {prod} injects the remote plug-in endpoint binaries into each remote plug-in container. This service starts remote extensions and plug-ins defined in the plug-in `meta.yaml` file and connects them to the Che-Theia editor container. - -The remote plug-in endpoint creates a plug-in API proxy between the remote plug-in container and the Che-Theia editor container. The remote plug-in endpoint is also an interceptor for some plug-in API parts, which it launches inside a remote sidecar container rather than an editor container. Examples: terminal API, debug API. - -The remote plug-in endpoint executable command is stored in the environment variable of the remote plug-in container: `+PLUGIN_REMOTE_ENDPOINT_EXECUTABLE+`. - -{prod} provides two ways to start the remote plug-in endpoint with a sidecar image: - -* Defining a `launch` remote plug-in endpoint using a Dockerfile. To use this method, patch an original image and rebuild it. -* Defining a `launch` remote plug-in endpoint in the plug-in `meta.yaml` file. Use this method to avoid patching an original image. - -include::partial$proc_defining-a-launch-remote-plug-in-endpoint-using-dockerfile.adoc[leveloffset=+1] -include::partial$proc_defining-a-launch-remote-plug-in-endpoint-in-a-meta-yaml-file.adoc[leveloffset=+1] - -:context: {parent-context-of-remote-plug-in-endpoint} diff --git a/modules/end-user-guide/partials/assembly_che-theia-troubleshooting.adoc b/modules/end-user-guide/partials/assembly_che-theia-troubleshooting.adoc deleted file mode 100644 index 193745d00f..0000000000 --- a/modules/end-user-guide/partials/assembly_che-theia-troubleshooting.adoc +++ /dev/null @@ -1,31 +0,0 @@ - - -:parent-context-of-che-theia-troubleshooting: {context} - -[id="che-theia-troubleshooting_{context}"] -= Che-Theia Troubleshooting - -:context: che-theia-troubleshooting - -This section describes the most frequent issues with the Che-Theia IDE. - -Che-Theia shows a notification with the following message: `Plugin runtime crashed unexpectedly, all plugins are not working, please reload the page. Probably there is not enough memory for the plugins.`:: - - This means that one of the Che-Theia plug-ins that are running in the Che-Theia IDE container requires more memory than the container has. To fix this problem, increase the amount of memory for the Che-Theia IDE container: - - . Navigate to the {prod-short} Dashboard. - . Select the workspace in which the problem happened. - . Switch to the *Devfile* tab. - . In the `components` section of the devfile, find a component of the `cheEditor` type. - . Add a new property, `memoryLimit: 1024M` (or increase the value if it already exists). - . Save changes and restart the workspace. - -ifeval::["{project-context}" == "che"] - -.Additional resources - -* Asking the community for help: link:https://mattermost.eclipse.org/eclipse/channels/eclipse-che[Mattermost channel] dedicated to {prod}. -* Reporting a bug: link:https://github.com/eclipse/che[{prod} repository issues]. -endif::[] - -:context: {parent-context-of-che-theia-troubleshooting} diff --git a/modules/end-user-guide/partials/assembly_configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc b/modules/end-user-guide/partials/assembly_configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc deleted file mode 100644 index 2c3def6605..0000000000 --- a/modules/end-user-guide/partials/assembly_configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc +++ /dev/null @@ -1,31 +0,0 @@ -:parent-context-of-assembly_configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform: {context} - -[id="configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform_{context}"] -= Configuring a workspace to use an IDE based on the IntelliJ Platform - -:context: assembly_configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform - -This section describes how to configure a workspace to use an link:https://plugins.jetbrains.com/docs/intellij/intellij-platform.html#ides-based-on-the-intellij-platform[IDE based on the IntelliJ Platform]. - - -[NOTE] -.No initial repository checkout when running the {prod-short} Server workspaces engine -==== -When the {prod-short} instance is running the {prod-short} Server workspaces engine, the workspace starts without an initial checkout of the code repositories referenced in the devfile. - -.Workarounds - -* In the IDE, click btn:[Get from VCS] to checkout a repository. -* To enable the automatic initial checkout of the code repositories in the devfile, use the {devworkspace} operator. -==== - -include::partial$proc_configuring-a-workspace-to-use-intellij-idea-community.adoc[leveloffset=+1] - - -include::partial$proc_configuring-a-workspace-to-use-pycharm-community.adoc[leveloffset=+1] - - -include::partial$proc_configuring-a-workspace-to-use-a-custom-image-with-an-ide-based-on-the-intellij-platform.adoc[leveloffset=+1] - - -:context: {parent-context-of-assembly_configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform} diff --git a/modules/end-user-guide/partials/assembly_configuring-a-workspace-with-dashboard.adoc b/modules/end-user-guide/partials/assembly_configuring-a-workspace-with-dashboard.adoc deleted file mode 100644 index 69b3c30d9d..0000000000 --- a/modules/end-user-guide/partials/assembly_configuring-a-workspace-with-dashboard.adoc +++ /dev/null @@ -1,21 +0,0 @@ - -// using-developer-environments-workspaces - -:parent-context-of-configuring-a-workspace-with-dashboard: {context} - -[id="configuring-a-workspace-with-dashboard_{context}"] -= Configuring a {prod-short} {prod-ver} workspace - -:context: configuring-a-workspace-with-dashboard - -include::partial$proc_changing-the-configuration-of-an-existing-workspace.adoc[leveloffset=+1] - -include::partial$proc_adding-projects-to-your-workspace.adoc[leveloffset=+1] - -include::partial$proc_configuring-the-workspace-and-adding-tooling.adoc[leveloffset=+1] - -.Additional resources - -* xref:end-user-guide:authoring-devfiles-version-2.adoc[] - -:context: {parent-context-of-configuring-a-workspace-with-dashboard} diff --git a/modules/end-user-guide/partials/assembly_creating-a-workspace-from-a-code-sample.adoc b/modules/end-user-guide/partials/assembly_creating-a-workspace-from-a-code-sample.adoc deleted file mode 100644 index ada5f13036..0000000000 --- a/modules/end-user-guide/partials/assembly_creating-a-workspace-from-a-code-sample.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="creating-a-workspace-from-a-code-sample_{context}"] -= Creating a workspace from a code sample - -You can create a new workspace by using one of the code samples included in {prod-short}. - -.Prerequisites - -* A running instance of {prod-short}. See xref:installation-guide:installing-che.adoc[]. - -.Procedure - -. Go to the xref:navigating-che-using-the-dashboard.adoc[Dashboard] of {prod-short}. - -. In the left navigation panel, click btn:[Create Workspace] to go to the *Quick Add* tab that contains code samples. - -. Select a sample to start a new workspace. - -. Wait for the initialized workspace to start and for the IDE to open. - -[NOTE] -==== -{prod-short} generates a unique name for a new workspace from the devfile's `metadata.generateName` property followed by four random characters. You can edit the name of the workspace when it is created. -==== diff --git a/modules/end-user-guide/partials/assembly_creating-a-workspace-from-a-template-devfile.adoc b/modules/end-user-guide/partials/assembly_creating-a-workspace-from-a-template-devfile.adoc deleted file mode 100644 index e65980666f..0000000000 --- a/modules/end-user-guide/partials/assembly_creating-a-workspace-from-a-template-devfile.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: - -[id="creating-a-workspace-from-a-template-devfile_{context}"] -= Creating a workspace from a template devfile - -You can create a new workspace by using one of the devfile templates included in {prod-short}. - -For information about devfiles, see xref:authoring-devfiles-version-2.adoc[]. - -.Prerequisites - -* A running instance of {prod-short}. See xref:installation-guide:installing-che.adoc[]. - -.Procedure - -. Go to the xref:navigating-che-using-the-dashboard.adoc[Dashboard] of {prod-short}. - -. In the left navigation panel, click btn:[Create Workspace]. - -. Go to the *Custom Workspace* tab. - -. Enter a workspace name. -+ -[NOTE] -==== -If you do not enter a *Workspace Name* for your workspace, {prod-short} generates a unique name for a new workspace from the devfile's `metadata.generateName` property followed by four random characters. -==== - -. Select a devfile template from the drop-down list. - -. Click btn:[Create & Open]. - -. Wait for the initialized workspace to start and for the IDE to open. diff --git a/modules/end-user-guide/partials/assembly_creating-a-workspace-from-remote-devfile.adoc b/modules/end-user-guide/partials/assembly_creating-a-workspace-from-remote-devfile.adoc deleted file mode 100644 index 9c63b032ca..0000000000 --- a/modules/end-user-guide/partials/assembly_creating-a-workspace-from-remote-devfile.adoc +++ /dev/null @@ -1,28 +0,0 @@ - - -:parent-context-of-creating-a-workspace-from-remote-devfile: {context} - -[id="creating-a-workspace-from-a-remote-devfile_{context}"] -= Creating a workspace from remote devfile - -:context: configuring-a-workspace-using-a-devfile-url - -For quick and easy {prod-short} workspace creation, use a factory link. - -include::partial$proc_creating-a-workspace-from-the-default-branch-of-a-git-repository.adoc[leveloffset=+1] - -include::partial$proc_creating-a-workspace-from-a-feature-branch-of-a-git-repository.adoc[leveloffset=+1] - -include::partial$proc_creating-a-workspace-from-with-a-publicly-accessible-standalone-devfile-using-http.adoc[leveloffset=+1] - -include::partial$proc_overriding-devfile-values-using-factory-parameters.adoc[leveloffset=+1] - -include::partial$proc_allowing-users-to-define-workspace-deployment-labels-and-annotations.adoc[leveloffset=+1] - -include::partial$proc_allowing-users-to-define-workspace-creation-strategy.adoc[leveloffset=+1] - -.Additional resources - -* xref:authoring-devfiles-version-2.adoc[] - -:context: {parent-context-of-creating-a-workspace-from-remote-devfile} diff --git a/modules/end-user-guide/partials/assembly_customizing-developer-environments.adoc b/modules/end-user-guide/partials/assembly_customizing-developer-environments.adoc deleted file mode 100644 index a6d96f3295..0000000000 --- a/modules/end-user-guide/partials/assembly_customizing-developer-environments.adoc +++ /dev/null @@ -1,38 +0,0 @@ - - -:parent-context-of-customizing-developer-environments: {context} - -[id="customizing-developer-environments_{context}"] -= Customizing developer environments - -:context: customizing-developer-environments - -{prod} is an extensible and customizable developer-workspaces platform. - -You can extend {prod} in three different ways: - -* *Alternative IDEs* provide specialized tools for {prod}. For example, a Jupyter notebook for data analysis. Alternate IDEs can be based on Eclipse Theia or any other IDE (web or desktop based). The default IDE in {prod} is Che-Theia. - -* *Che-Theia plug-ins* add capabilities to the Che-Theia IDE. They rely on plug-in APIs that are compatible with Visual Studio Code. The plug-ins are isolated from the IDE itself. They can be packaged as files or as containers to provide their own dependencies. - -pass:[<!-- vale Vale.Spelling = NO -->] - -pass:[<!-- vale Vale.Terms = NO -->] - -* *Stacks* are pre-configured {prod-short} workspaces with a dedicated set of tools, which cover different developer personas. For example, it is possible to pre-configure a workbench for a tester with only the tools needed for their purposes. - -.{prod-short} extensibility -image::extensibility/extending-che.svg[link="../_images/extensibility/extending-che.svg"] - -A user can extend {prod-short} by using `self-hosted` mode, which {prod-short} provides by default. - -* xref:what-is-a-che-theia-plug-in.adoc[] -* xref:using-alternative-ides-in-che.adoc[] -* xref:adding-a-vs-code-extension-to-a-workspace.adoc[] -* xref:using-private-container-registries.adoc[] - -pass:[<!-- vale Vale.Spelling = YES -->] - -pass:[<!-- vale Vale.Terms = YES -->] - -:context: {parent-context-of-customizing-developer-environments} diff --git a/modules/end-user-guide/partials/assembly_defining-custom-commands-for-che-theia.adoc b/modules/end-user-guide/partials/assembly_defining-custom-commands-for-che-theia.adoc deleted file mode 100644 index a685fcf07b..0000000000 --- a/modules/end-user-guide/partials/assembly_defining-custom-commands-for-che-theia.adoc +++ /dev/null @@ -1,28 +0,0 @@ - - -:parent-context-of-defining-custom-commands-for-che-theia: {context} - -// che-theia-ide-basics - -[id="defining-custom-commands-for-che-theia_{context}"] -= Defining custom commands for Che-Theia - -:context: defining-custom-commands-for-che-theia - -The Che-Theia IDE allows users to define custom commands in a devfile that are then available when working in a workspace. - -This is useful, for example, for: - -* Simplifying building, running, and debugging projects. -* Allowing lead developers to customize workspaces based on team requirements. -* Reducing time needed to onboard new team members. - -See also xref:authoring-devfiles-version-2.adoc[]. - -include::partial$con_che-theia-task-types.adoc[leveloffset=+1] - -include::partial$proc_running-and-debugging.adoc[leveloffset=+1] - -include::partial$proc_editing-a-task-and-a-launch-configuration.adoc[leveloffset=+1] - -:context: {parent-context-of-defining-custom-commands-for-che-theia} diff --git a/modules/end-user-guide/partials/assembly_differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc b/modules/end-user-guide/partials/assembly_differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc deleted file mode 100644 index 54f43b68c3..0000000000 --- a/modules/end-user-guide/partials/assembly_differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode.adoc +++ /dev/null @@ -1,27 +0,0 @@ - - -:parent-context-of-differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode: {context} - -[id="differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode_{context}"] -= Differences in Che-Theia Webview in single-host mode and multihost mode - -:context: differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode - -Depending on which Che deployment strategy is used, single-host or multihost, there are differences in how Che-Theia Webview API works. - -== What’s a Webview - -Webview Plug-in API allows creating a view within Che-Theia to show an arbitrary HTML content. Internally, it’s implemented with an link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe[iframe] and link:https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API[service worker]. - -== Webview in multihost mode - -When {prod} is deployed in multihost mode, Webview content is served on a separate link:https://developer.mozilla.org/en-US/docs/Glossary/Origin[origin]. That means it’s isolated from the main Che-Theia context. So, a contributed view has no access: - -* to the top-level DOM -* to the Che-Theia state, like local storage, cookies, and so on. - -== Webview in single-host mode - -When {prod} is deployed in single-host mode, Webview content is loaded through the same origin as the main Che-Theia context. It means that nothing prevents external content from accessing the main Che-Theia in a browser. So, pay extra attention to what content may be loaded by different Plugins that contribute the Webviews. - -:context: {parent-context-of-differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode} diff --git a/modules/end-user-guide/partials/assembly_importing-kubernetes-applications-into-a-workspace.adoc b/modules/end-user-guide/partials/assembly_importing-kubernetes-applications-into-a-workspace.adoc deleted file mode 100644 index e60022db45..0000000000 --- a/modules/end-user-guide/partials/assembly_importing-kubernetes-applications-into-a-workspace.adoc +++ /dev/null @@ -1,21 +0,0 @@ - - -:parent-context-of-importing-kubernetes-applications-into-a-workspace: {context} - -[id="importing-kubernetes-applications-into-a-workspace_{context}"] -= Importing {orch-name} applications into a workspace - -:context: importing-kubernetes-applications-into-a-workspace - -To deploy a new instance of an application in a {prod-short} workspace, use one of the following scenarios: - -* Modifying an existing workspace: xref:importing-kubernetes-applications-into-a-workspace.adoc#adding-a-kubernetes-application-to-an-existing-workspace-using-the-dashboard_{context}[Using the Dashboard user interface] -* From a running application: xref:importing-kubernetes-applications-into-a-workspace.adoc#generating-a-devfile-from-an-existing-kubernetes-application_{context}[Generating a devfile with `{prod-cli}`] - -include::example$proc_{project-context}-including-kubernetes-applications-in-a-workspace-devfile-definition.adoc[leveloffset=+1] - -include::partial$proc_adding-a-kubernetes-application-to-an-existing-workspace-using-the-dashboard.adoc[leveloffset=+1] - -include::partial$proc_generating-a-devfile-from-an-existing-kubernetes-application.adoc[leveloffset=+1] - -:context: {parent-context-of-importing-kubernetes-applications-into-a-workspace} diff --git a/modules/end-user-guide/partials/assembly_navigating-che-using-the-dashboard.adoc b/modules/end-user-guide/partials/assembly_navigating-che-using-the-dashboard.adoc deleted file mode 100644 index 155b939d92..0000000000 --- a/modules/end-user-guide/partials/assembly_navigating-che-using-the-dashboard.adoc +++ /dev/null @@ -1,29 +0,0 @@ - - -:parent-context-of-navigating-che-using-the-dashboard: {context} - -[id="navigating-{prod-id-short}-using-the-dashboard_{context}"] -= Navigating {prod-short} using the Dashboard - -:context: navigating-{prod-id-short}-using-the-dashboard - -The *Dashboard* is accessible on your cluster from a URL such as `pass:c,a,q[{prod-url}/dashboard]`. -This section describes how to access this URL on -ifeval::["{project-context}" == "che"] -Minishift and -endif::[] -OpenShift. - -ifeval::["{project-context}" == "che"] -include::partial$proc_navigating-che-using-the-dashboard-on-minishift.adoc[leveloffset=+1] -endif::[] - -include::partial$proc_logging-in-to-che-on-openshift-for-the-first-time-using-oauth.adoc[leveloffset=+1] - -include::partial$proc_logging-in-to-che-on-openshift-for-the-first-time-registering-as-a-new-user.adoc[leveloffset=+1] - -include::partial$proc_logging-in-to-che-server-using-cli.adoc[leveloffset=+1] - -include::partial$proc_finding-che-cluster-url-using-openshift-4-cli-tools.adoc[leveloffset=+1] - -:context: {parent-context-of-navigating-che-using-the-dashboard} diff --git a/modules/end-user-guide/partials/assembly_navigating-che.adoc b/modules/end-user-guide/partials/assembly_navigating-che.adoc deleted file mode 100644 index 1ffc358ee2..0000000000 --- a/modules/end-user-guide/partials/assembly_navigating-che.adoc +++ /dev/null @@ -1,18 +0,0 @@ - - -:parent-context-of-navigating-che: {context} - -[id="navigating-{prod-id-short}_{context}"] -= Navigating {prod-short} - -:context: navigating-{prod-id-short} - -This chapter describes available methods to navigate {prod}. - -* xref:navigating-che-using-the-dashboard.adoc[] - -* xref:importing-certificates-to-browsers.adoc[] - -* xref:accessing-che-from-openshift-developer-perspective.adoc[] - -:context: {parent-context-of-navigating-che} diff --git a/modules/end-user-guide/partials/assembly_remotely-accessing-workspaces.adoc b/modules/end-user-guide/partials/assembly_remotely-accessing-workspaces.adoc deleted file mode 100644 index b0c32ed9ac..0000000000 --- a/modules/end-user-guide/partials/assembly_remotely-accessing-workspaces.adoc +++ /dev/null @@ -1,21 +0,0 @@ - - -:parent-context-of-remotely-accessing-workspaces: {context} - -[id="remotely-accessing-workspaces_{context}"] -= Remotely accessing workspaces - -:context: remotely-accessing-workspaces - -This section describes how to remotely access {prod-short} workspaces outside of the browser. - -{prod-short} workspaces exist as containers and are, by default, modified from a browser window. In addition to this, there are the following methods of interacting with a {prod-short} workspace: - -* Opening a command line in the workspace container using the {orch-name} command-line tool, `{orch-cli}`. -* Uploading and downloading files using the `{orch-cli}` tool. - -include::partial$proc_accessing-workspaces-remotely-using-kubectl.adoc[leveloffset=+1] - -include::partial$proc_downloading-and-uploading-a-file-to-a-workspace-using-the-command-line-interface.adoc[leveloffset=+1] - -:context: {parent-context-of-remotely-accessing-workspaces} diff --git a/modules/end-user-guide/partials/assembly_running-an-existing-workspace-from-the-user-dashboard.adoc b/modules/end-user-guide/partials/assembly_running-an-existing-workspace-from-the-user-dashboard.adoc deleted file mode 100644 index d8b7ee7ae2..0000000000 --- a/modules/end-user-guide/partials/assembly_running-an-existing-workspace-from-the-user-dashboard.adoc +++ /dev/null @@ -1,16 +0,0 @@ -:parent-context-of-running-an-existing-workspace-from-the-user-dashboard: {context} - -[id="running-an-existing-workspace-from-the-user-dashboard_{context}"] -= Running an existing workspace from the user dashboard - -:context: running-an-existing-workspace-from-the-user-dashboard - -This section describes how to run an existing workspace from the user dashboard. - -include::partial$proc_running-an-existing-workspace-from-the-user-dashboard-using-the-run-button.adoc[leveloffset=+1] - -include::partial$proc_running-an-existing-workspace-from-the-user-dashboard-using-the-open-button.adoc[leveloffset=+1] - -include::partial$proc_running-an-existing-workspace-from-the-user-dashboard-using-the-recent-workspaces.adoc[leveloffset=+1] - -:context: {parent-context-of-running-an-existing-workspace-from-the-user-dashboard} diff --git a/modules/end-user-guide/partials/assembly_testing-a-visual-studio-code-extension-in-che.adoc b/modules/end-user-guide/partials/assembly_testing-a-visual-studio-code-extension-in-che.adoc deleted file mode 100644 index fa44fb309f..0000000000 --- a/modules/end-user-guide/partials/assembly_testing-a-visual-studio-code-extension-in-che.adoc +++ /dev/null @@ -1,25 +0,0 @@ - - -:parent-context-of-testing-a-visual-studio-code-extension-in-che: {context} - -[id="testing-a-visual-studio-code-extension-in-{prod-id-short}_{context}"] -= Testing a Visual Studio Code extension in {prod-short} - -:context: testing-a-visual-studio-code-extension-in-{prod-id-short} - -Visual Studio Code (VS Code) extensions work in a workspace. VS Code extensions can run in the Che-Theia editor container, or in their own isolated and preconfigured containers with their prerequisites. - -This section describes how to test a VS Code extension in {prod-short} with workspaces and how to review the compatibility of VS Code extensions to check whether a specific API is available. - -NOTE: The extension-hosting sidecar container and the use of the extension in a devfile are optional. - - -include::partial$proc_testing-the-vs-code-extension-using-gist.adoc[leveloffset=+1] - -//// -include::partial$proc_choosing-the-sidecar-image.adoc[leveloffset=+1] -//// - -include::partial$proc_verifying-the-vs-code-extension-api-compatibility-level.adoc[leveloffset=+1] - -:context: {parent-context-of-testing-a-visual-studio-code-extension-in-che} diff --git a/modules/end-user-guide/partials/assembly_troubleshooting-che.adoc b/modules/end-user-guide/partials/assembly_troubleshooting-che.adoc deleted file mode 100644 index 1f97738165..0000000000 --- a/modules/end-user-guide/partials/assembly_troubleshooting-che.adoc +++ /dev/null @@ -1,19 +0,0 @@ - - -:parent-context-of-troubleshooting-che: {context} - -[id="troubleshooting-{prod-id-short}_{context}"] -= Troubleshooting {prod-short} - -:context: troubleshooting-che - -This section provides troubleshooting procedures for the most frequent issues a user can come in conflict with. - -.Additional resources - -* xref:viewing-che-workspaces-logs.adoc[] -* xref:investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc[] -* xref:troubleshooting-slow-workspaces.adoc[] -* xref:troubleshooting-network-problems.adoc[] - -:context: {parent-context-of-troubleshooting-che} diff --git a/modules/end-user-guide/partials/assembly_using-a-visual-studio-code-extension-in-che.adoc b/modules/end-user-guide/partials/assembly_using-a-visual-studio-code-extension-in-che.adoc deleted file mode 100644 index c12afb222f..0000000000 --- a/modules/end-user-guide/partials/assembly_using-a-visual-studio-code-extension-in-che.adoc +++ /dev/null @@ -1,25 +0,0 @@ - - -:parent-context-of-using-a-visual-studio-code-extension-in-che: {context} - -[id="using-a-visual-studio-code-extension-in-{prod-id-short}_{context}"] -= Using a Visual Studio Code extension in {prod-short} - -:context: using-a-visual-studio-code-extension-in-{prod-id-short} - -In {prod}, Visual Studio Code (VS Code) extensions can be installed to extend the functionality of a {prod-short} workspace. VS Code extensions can run in the Che-Theia editor container, or they can be packaged in their own isolated and pre-configured containers with their prerequisites. - -This document describes: - -* Use of a VS Code extension in {prod-short} with workspaces. -* {prod-short} Plug-ins panel. -* How to publish a VS Code extension in the {prod-short} plug-in registry (to share the extension with other {prod-short} users). -+ -** The extension-hosting sidecar container and the use of the extension in a devfile are optional for this. -** How to review the compatibility of the VS Code extensions to be informed whether a specific API is supported or has not been implemented yet. - -include::partial$assembly_publishing-a-vs-code-extension-into-the-che-plug-in-registry.adoc[leveloffset=+1] - -include::partial$assembly_adding-che-plug-in-registry-vs-code-extension-to-a-workspace.adoc[leveloffset=+1] - -:context: {parent-context-of-using-a-visual-studio-code-extension-in-che} diff --git a/modules/end-user-guide/partials/assembly_using-alternative-ides-in-che.adoc b/modules/end-user-guide/partials/assembly_using-alternative-ides-in-che.adoc deleted file mode 100644 index e493af2d33..0000000000 --- a/modules/end-user-guide/partials/assembly_using-alternative-ides-in-che.adoc +++ /dev/null @@ -1,16 +0,0 @@ - - -:parent-context-of-using-alternative-ides-in-che: {context} - -[id="using-alternative-ides-in-{prod-id-short}_{context}"] -= Using alternative IDEs in {prod-short} - -:context: using-alternative-ides-in-che - -{prod} provides a default web IDE to use in the developer workspaces. To use another editor, see: - -* xref:configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc[] - -* xref:support-for-theia-based-ides.adoc[] - -:context: {parent-context-of-using-alternative-ides-in-che} diff --git a/modules/end-user-guide/partials/assembly_using-artifact-repositories-in-a-restricted-environment.adoc b/modules/end-user-guide/partials/assembly_using-artifact-repositories-in-a-restricted-environment.adoc deleted file mode 100644 index 6398f7de01..0000000000 --- a/modules/end-user-guide/partials/assembly_using-artifact-repositories-in-a-restricted-environment.adoc +++ /dev/null @@ -1,19 +0,0 @@ - - -:parent-context-of-using-artifact-repositories-in-a-restricted-environment: {context} - -[id="using-artifact-repositories-in-a-restricted-environment_{context}"] -= Using artifact repositories in a restricted environment - -:context: using-artifact-repositories-in-a-restricted-environment - -By configuring technology stacks, you can work with artifacts from in-house repositories using self-signed certificates. - -* xref:using-maven-artifact-repositories.adoc[] -* xref:using-gradle-artifact-repositories.adoc[] -* xref:using-python-artifact-repositories.adoc[] -* xref:using-go-artifact-repositories.adoc[] -* xref:using-nuget-artifact-repositories.adoc[] -* xref:using-npm-artifact-repositories.adoc[] - -:context: {parent-context-of-using-artifact-repositories-in-a-restricted-environment} diff --git a/modules/end-user-guide/partials/assembly_using-go-artifact-repositories.adoc b/modules/end-user-guide/partials/assembly_using-go-artifact-repositories.adoc deleted file mode 100644 index b1ec944c3c..0000000000 --- a/modules/end-user-guide/partials/assembly_using-go-artifact-repositories.adoc +++ /dev/null @@ -1,22 +0,0 @@ - - - -:parent-context-of-using-go-artifact-repositories: {context} - -[id="using-go-artifact-repositories_{context}"] -= Using Go artifact repositories - -:context: using-go-artifact-repositories - -To configure Go in a restricted environment, use the `GOPROXY` environment variable and the link:https://github.com/gomods/athens[Athens] module data store and proxy. - -include::partial$proc_configuring-go-to-use-a-non-standard-registry.adoc[leveloffset=+1] - -include::partial$proc_using-self-signed-certificates-in-go-projects.adoc[leveloffset=+1] - -.Additional resources - -* link:https://github.com/gomods/athens[The Athens project repository] -* link:https://docs.gomods.io/[The Athens project documentation] - -:context: {parent-context-of-using-go-artifact-repositories} diff --git a/modules/end-user-guide/partials/assembly_using-gradle-artifact-repositories.adoc b/modules/end-user-guide/partials/assembly_using-gradle-artifact-repositories.adoc deleted file mode 100644 index 461eb66704..0000000000 --- a/modules/end-user-guide/partials/assembly_using-gradle-artifact-repositories.adoc +++ /dev/null @@ -1,23 +0,0 @@ - - - -:parent-context-of-using-gradle-artifact-repositories: {context} - -[id="using-gradle-artifact-repositories_{context}"] -= Using Gradle artifact repositories - -:context: using-gradle-artifact-repositories - -This section describes how to download and configure Gradle. - -include::partial$proc_downloading-different-versions-of-gradle.adoc[leveloffset=+1] - -include::partial$proc_configuring-global-gradle-repositories.adoc[leveloffset=+1] - -include::partial$proc_using-self-signed-certificates-in-gradle-projects.adoc[leveloffset=+1] - -.Additional resources - * link:https://docs.gradle.org/current/userguide/init_scripts.html[Gradle documentation about initialization scripts] - * link:https://docs.gradle.org/current/userguide/gradle_wrapper.html[The Gradle Wrapper documentation] - -:context: {parent-context-of-using-gradle-artifact-repositories} diff --git a/modules/end-user-guide/partials/assembly_using-maven-artifact-repositories.adoc b/modules/end-user-guide/partials/assembly_using-maven-artifact-repositories.adoc deleted file mode 100644 index 7526f06f8f..0000000000 --- a/modules/end-user-guide/partials/assembly_using-maven-artifact-repositories.adoc +++ /dev/null @@ -1,22 +0,0 @@ - - - -:parent-context-of-using-maven-artifact-repositories: {context} - -[id="using-maven-artifact-repositories_{context}"] -= Using Maven artifact repositories - -:context: using-maven-artifact-repositories - -Maven downloads artifacts that are defined in two locations: - -* Artifact repositories defined in a `pom.xml` file of the project. Configuring repositories in `pom.xml` is not specific to {prod}. For more information, see link:https://maven.apache.org/guides/introduction/introduction-to-the-pom.html[the Maven documentation about the POM]. -* Artifact repositories defined in a `settings.xml` file. By default, `settings.xml` is located at ``~/.m2/settings.xml`. - -include::partial$proc_defining-maven-repositories-in-the-settings-xml-file.adoc[leveloffset=+1] - -include::partial$proc_defining-maven-settings-xml-file-across-workspaces.adoc[leveloffset=+1] - -include::partial$proc_using-self-signed-certificates-in-maven-projects.adoc[leveloffset=+1] - -:context: {parent-context-of-using-maven-artifact-repositories} diff --git a/modules/end-user-guide/partials/assembly_using-nuget-artifact-repositories.adoc b/modules/end-user-guide/partials/assembly_using-nuget-artifact-repositories.adoc deleted file mode 100644 index 821658b937..0000000000 --- a/modules/end-user-guide/partials/assembly_using-nuget-artifact-repositories.adoc +++ /dev/null @@ -1,17 +0,0 @@ - - - -:parent-context-of-using-nuget-artifact-repositories: {context} - -[id="using-nuget-artifact-repositories_{context}"] -= Using NuGet artifact repositories - -:context: using-nuget-artifact-repositories - -To configure NuGet in a restricted environment, modify the `nuget.config` file and use the `SSL_CERT_FILE` environment variable in the devfile to add self-signed certificates. - -include::partial$proc_configuring-nuget-to-use-a-non-standard-registry.adoc[leveloffset=+1] - -include::partial$proc_using-self-signed-certificates-in-nuget-projects.adoc[leveloffset=+1] - -:context: {parent-context-of-using-nuget-artifact-repositories} diff --git a/modules/end-user-guide/partials/assembly_using-python-artifact-repositories.adoc b/modules/end-user-guide/partials/assembly_using-python-artifact-repositories.adoc deleted file mode 100644 index 49db037174..0000000000 --- a/modules/end-user-guide/partials/assembly_using-python-artifact-repositories.adoc +++ /dev/null @@ -1,15 +0,0 @@ - - - -:parent-context-of-using-python-artifact-repositories: {context} - -[id="using-python-artifact-repositories_{context}"] -= Using Python artifact repositories - -:context: using-python-artifact-repositories - -include::partial$proc_configuring-python-to-use-a-non-standard-registry.adoc[leveloffset=+1] - -include::partial$proc_using-self-signed-certificates-in-python-projects.adoc[leveloffset=+1] - -:context: {parent-context-of-using-python-artifact-repositories} diff --git a/modules/end-user-guide/partials/assembly_version-control.adoc b/modules/end-user-guide/partials/assembly_version-control.adoc deleted file mode 100644 index 03e38d5a22..0000000000 --- a/modules/end-user-guide/partials/assembly_version-control.adoc +++ /dev/null @@ -1,22 +0,0 @@ - - -:parent-context-of-version-control: {context} - -// che-theia-ide-basics - -[id="version-control_{context}"] -= Version Control - -:context: version-control - -{prod} natively supports the link:https://code.visualstudio.com/docs/editor/versioncontrol#_scm-providers[VS Code SCM model]. By default, {prod} includes the native link:https://code.visualstudio.com/docs/editor/versioncontrol#_git-support[VS Code Git extension] as a Source Code Management (SCM) provider. - -include::partial$proc_managing-git-configuration-identity.adoc[leveloffset=+1] - -include::partial$proc_accessing-a-git-repository-via-https.adoc[leveloffset=+1] - -include::partial$proc_accessing-a-git-repository-via-ssh.adoc[leveloffset=+1] - -include::partial$proc_managing-pull-requests-using-the-github-pr-plug-in.adoc[leveloffset=+1] - -:context: {parent-context-of-version-control} diff --git a/modules/end-user-guide/partials/assembly_viewing-che-workspaces-logs.adoc b/modules/end-user-guide/partials/assembly_viewing-che-workspaces-logs.adoc deleted file mode 100644 index e3b1227cf5..0000000000 --- a/modules/end-user-guide/partials/assembly_viewing-che-workspaces-logs.adoc +++ /dev/null @@ -1,18 +0,0 @@ - - -:parent-context-of-viewing-che-workspaces-logs: {context} - -[id="viewing-{prod-id-short}-workspaces-logs_{context}"] -= Viewing {prod-short} workspaces logs - -:context: viewing-{prod-id-short}-workspaces-logs - -This section describes how to view {prod-short} workspaces logs. - -include::partial$assembly_viewing-logs-from-language-servers-and-debug-adapters.adoc[leveloffset=+1] - - -include::partial$assembly_viewing-che-theia-ide-logs.adoc[leveloffset=+1] - - -:context: {parent-context-of-viewing-che-workspaces-logs} diff --git a/modules/end-user-guide/partials/assembly_what-is-a-che-theia-plug-in.adoc b/modules/end-user-guide/partials/assembly_what-is-a-che-theia-plug-in.adoc deleted file mode 100644 index 12bb5ff58c..0000000000 --- a/modules/end-user-guide/partials/assembly_what-is-a-che-theia-plug-in.adoc +++ /dev/null @@ -1,45 +0,0 @@ - - -:parent-context-of-what-is-a-che-theia-plug-in: {context} - -[id="what-is-a-che-theia-plug-in_{context}"] -= What is a Che-Theia plug-in - -:context: what-is-a-che-theia-plug-in - -A Che-Theia plug-in is an extension of the development environment isolated from the IDE. Plug-ins can be packaged as files or containers to provide their own dependencies. - -Extending Che-Theia using plug-ins can enable the following capabilities: - -* *Language support:* Extend the supported languages by relying on the https://microsoft.github.io/language-server-protocol/[Language Server Protocol]. -* *Debuggers:* Extend debugging capabilities with the https://microsoft.github.io/debug-adapter-protocol/[Debug Adapter Protocol]. -* *Development Tools:* Integrate your favorite linters, and as testing and performance tools. -* *Menus, panels, and commands:* Add your own items to the IDE components. -* *Themes:* Build custom themes, extend the UI, or customize icon themes. -* *Snippets, code formatting, and syntax highlighting:* Enhance comfort of use with supported programming languages. -* *Keybindings:* Add new keyboard mapping and popular keybindings to make the environment feel natural. - -== Features and benefits of Che-Theia plug-ins - -[options="header"] -|=== -| *Features* | *Description* | *Benefits* -| *Fast Loading* | Plug-ins are loaded at runtime and are already compiled. IDE is loading the plug-in code. | Avoid any compilation time. Avoid post-installation steps. -| *Secure Loading* | Plug-ins are loaded separately from the IDE. The IDE stays always in a usable state. | Plug-ins do not break the whole IDE if it has bugs. Handle network issue. -| *Tools Dependencies*| Dependencies for the plug-in are packaged with the plug-in in its own container. | No-installation for tools. Dependencies running into container. -| *Code Isolation* | Guarantee that plug-ins cannot block the main functions of the IDE like opening a file or typing | Plug-ins are running into separate threads. Avoid dependencies mismatch. -| *VS Code Extension Compatibility* | Extend the capabilities of the IDE with existing VS Code Extensions. | Target multiple platform. Allow easy discovery of Visual Studio Code Extension with required installation. -|=== - - -include::partial$con_che-theia-plug-in-concept-in-detail.adoc[leveloffset=+1] - -include::partial$ref_che-theia-plug-in-metadata.adoc[leveloffset=+1] - -include::partial$con_che-theia-plug-in-lifecycle.adoc[leveloffset=+1] - -include::partial$con_embedded-and-remote-che-theia-plug-ins.adoc[leveloffset=+1] - -include::partial$assembly_che-theia-remote-plugin-image.adoc[leveloffset=+1] - -:context: {parent-context-of-what-is-a-che-theia-plug-in} diff --git a/modules/end-user-guide/partials/assembly_workspaces-overview.adoc b/modules/end-user-guide/partials/assembly_workspaces-overview.adoc deleted file mode 100644 index b1812711be..0000000000 --- a/modules/end-user-guide/partials/assembly_workspaces-overview.adoc +++ /dev/null @@ -1,87 +0,0 @@ - - -:parent-context-of-developer-workspaces: {context} - -[id="developer-workspaces_{context}"] -= Developer workspaces - -:context: developer-workspaces - -{prod} provides developer workspaces with everything you need to code, build, test, run, and debug applications: - -* Project source code -* Web-based integrated development environment (IDE) -* Tool dependencies needed by developers to work on a project -* Application runtime: a replica of the environment where the application runs in production - -Pods manage each component of a {prod-short} workspace. Therefore, everything running in a {prod-short} workspace is running inside containers. This makes a {prod-short} workspace highly portable. - -The embedded browser-based IDE is the point of access for everything running in a {prod-short} workspace. This makes a {prod-short} workspace easy to share. - -[IMPORTANT] -==== -By default, it is possible to run only one workspace at a time. To increase the number of concurrent workspaces a user can run, update the CheCluster: - -[subs="+quotes,+attributes"] ----- -$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=merge \ --p '{ "spec": { "server": { "customCheProperties": { "CHE_LIMITS_USER_WORKSPACES_RUN_COUNT": "-1" } } } }' ----- - -For additional information, see: xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc#users-workspace-limits[]. -==== - - -.Features and benefits -[options="header",cols="h,,"] -|=== -| Features -| Traditional IDE workspaces -| {prod} workspaces - -| Configuration and installation required -| Yes. -| No. - -| Embedded tools -| Partial. IDE plug-ins need configuration. Dependencies need installation and configuration. Example: JDK, Maven, Node. -| Yes. Plug-ins provide their dependencies. - -| Application runtime provided -| No. Developers have to manage that separately. -| Yes. Application runtime is replicated in the workspace. - -| Shareable -| No. Or not easily -| Yes. Developer workspaces are shareable with a URL. - -| Capable of being versioned -| No -| Yes. Devfiles exist with project source code. - -| Accessible from anywhere -| No. Installation is needed. -| Yes. Only requires a browser. -|=== - -Start a {prod-short} workspace: - -* xref:configuring-a-workspace-with-dashboard.adoc[] - -Use the Dashboard to discover {prod-short} {prod-ver}: - -* xref:creating-a-workspace-from-a-code-sample.adoc[] -* xref:importing-the-source-code-of-a-project-into-a-workspace.adoc[] - -Use a devfile as the preferred way to start a {prod-short} {prod-ver} workspace: - -* xref:authoring-devfiles.adoc[] -* xref:importing-kubernetes-applications-into-a-workspace.adoc[] - -Use the browser-based IDE as the preferred way to interact with a {prod-short} {prod-ver} workspace. For an alternative way to interact with a {prod-short} {prod-ver} workspace, see: xref:remotely-accessing-workspaces.adoc[]. - -ifeval::["{project-context}" == "che"] -include::partial$proc_using-a-badge-to-link-to-workspaces.adoc[leveloffset=+1] -endif::[] - -:context: {parent-context-of-developer-workspaces} diff --git a/modules/end-user-guide/partials/con_a-minimal-devfile.adoc b/modules/end-user-guide/partials/con_a-minimal-devfile.adoc deleted file mode 100644 index d76b4f7d99..0000000000 --- a/modules/end-user-guide/partials/con_a-minimal-devfile.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-using-a-devfile - -[id="a-minimal-devfile_{context}"] -= A minimal devfile - -The following is the minimum content required in a devfile: - -* link:https://redhat-developer.github.io/devfile/devfile#apiversion[apiVersion] -* link:https://redhat-developer.github.io/devfile/devfile#metadata[metadata name] - -[source,yaml,subs="+attributes"] ----- -apiVersion: 1.0.0 -metadata: - name: {project-context}-in-{project-context}-out ----- - -For a complete devfile example, see link:https://raw.githubusercontent.com/eclipse-che/che-server/main/devfile.yaml[{prod} in {prod-short} devfile.yaml]. - -[NOTE] -==== -A choice of use of the parameter `generateName` or `name` is optional, but only one of these parameters has to be chosen by a user and defined. -When both attributes are specified, `generateName` is ignored. -See xref:#generating-workspace-names_{context}[]. - -[source,yaml] ----- -metadata: - generatedName: ----- - -or - -[source,yaml] ----- -metadata: - name: ----- -==== - diff --git a/modules/end-user-guide/partials/con_additional-tools-in-the-che-workspace.adoc b/modules/end-user-guide/partials/con_additional-tools-in-the-che-workspace.adoc deleted file mode 100644 index 42741f9035..0000000000 --- a/modules/end-user-guide/partials/con_additional-tools-in-the-che-workspace.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// adding-tools-to-{prod-id-short}-after-creating-a-workspace - -[id="additional-tools-in-the-{prod-id-short}-workspace_{context}"] -= Additional tools in the {prod-short} workspace - -{prod-short} plug-ins are extensions to the Che-Theia IDE that come bundled with container images. These images contain the native prerequisites of their respective extensions. For example, the OpenShift command-line tool is bundled with a command to install it, which ensures the proper functionality of the OpenShift Connector plug-in, all available in the dedicated image. - -Plug-ins can also include metadata to define a description, categorization tags, and an icon. {prod-short} provides a registry of plug-ins available for installation into the user's workspace. - -The Che-Theia IDE is generally compatible with the VS Code extensions API and VS Code extensions are automatically compatible with Che-Theia. These extensions are possible to package as {prod-short} plug-ins by combining them with their dependencies. By default, {prod-short} includes a plug-in registry containing common plug-ins. - -.Adding a plug-in - -* Using the Dashboard: -** Add a plug-in directly into a devfile using the *Devfile* tab. -+ -The devfile can also further the plug-in configuration, such as defining memory or CPU consumption. - -* Using the Che-Theia IDE: -** By pressing kbd:[Ctrl+Shift+J] or by navigating to *View -> Plugins*. - -.Additional resources - -* xref:authoring-devfiles-version-1.adoc[Adding components to a devfile] diff --git a/modules/end-user-guide/partials/con_che-theia-plug-in-concept-in-detail.adoc b/modules/end-user-guide/partials/con_che-theia-plug-in-concept-in-detail.adoc deleted file mode 100644 index 663b84fdf1..0000000000 --- a/modules/end-user-guide/partials/con_che-theia-plug-in-concept-in-detail.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// This assembly is included in the following assemblies: -// -// what-is-a-che-theia-plug-in - -[id="che-theia-plug-in-concept-in-detail_{context}"] -= Che-Theia plug-in concept in detail - -{prod} provides a default web IDE for workspaces: Che-Theia. It is based on Eclipse Theia. It is a slightly different version than the plain Eclipse Theia one because there are functionalities that have been added based on the nature of the {prod} workspaces. This version of Eclipse Theia for {prod-short} is called *Che-Theia*. - -You can extend the IDE provided with {prod} by building a *Che-Theia plug-in*. Che-Theia plug-ins are compatible with any other Eclipse Theia-based IDE. - - -[id="client-side-and-server-side-che-theia-plug-ins_{context}"] -== Client-side and server-side Che-Theia plug-ins - -The Che-Theia editor plug-ins let you add languages, debuggers, and tools to your installation to support your development workflow. Plug-ins run when the editor completes loading. If a Che-Theia plug-in fails, the main Che-Theia editor continues to work. - -Che-Theia plug-ins run either on the client side or on the server side. This is a scheme of the client and server-side plug-in concept: - -.Client and server-side Che-Theia plug-ins -image::extensibility/client-server-side-plug-ins.svg[] - -The same Che-Theia plug-in API is exposed to plug-ins running on the client side (Web Worker) or the server side (Node.js). - - -[id="che-theia-plug-in-apis_{context}"] -== Che-Theia plug-in APIs - -To provide tool isolation and easy extensibility in {prod}, the Che-Theia IDE has a set of plug-in APIs. The APIs are compatible with Visual Studio Code extension APIs. Usually, Che-Theia can run VS Code extensions as its own plug-ins. - -When developing a plug-in that depends on or interacts with components of {prod-short} workspaces (containers, preferences, factories), use the {prod-short} APIs embedded in Che-Theia. - - -[id="che-theia-plug-in-capabilities_{context}"] -== Che-Theia plug-in capabilities - -Che-Theia plug-ins have the following capabilities: - -[options="header",cols="3"] -|=== -| *Plug-in* -| *Description* -| *Repository* - -| *{prod-short} Extended Tasks* -| Handles the {prod-short} commands and provides the ability to start those into a specific container of the workspace. -|link:https://github.com/eclipse-che/che-theia/tree/master/plugins/task-plugin[Task plug-in] - -| *{prod-short} Extended Terminal* -| Allows to provide terminal for any of the containers of the workspace. -|link:https://github.com/eclipse-che/che-theia/tree/master/extensions/eclipse-che-theia-terminal[Extended Terminal extension] - -| *{prod-short} Factory* -| Handles the {prod} Factories -|link:https://github.com/eclipse-che/che-theia/tree/master/plugins/workspace-plugin[Workspace plug-in] - -| *{prod-short} Container* -| Provides a container view that shows all the containers that are running in the workspace and allows to interact with them. -| link:https://github.com/eclipse-che/che-theia/tree/master/plugins/containers-plugin[Containers plug-in] - -| *Dashboard* -| Integrates the IDE with the *Dashboard* and facilitate the navigation. -|link:https://github.com/eclipse-che/che-theia/tree/master/extensions/eclipse-che-theia-dashboard[Che-Theia Dashbord extension] - -| *{prod-short} APIs* -| Extends the IDE APIs to allow interacting with {prod-short}-specific components (workspaces, preferences). -|link:https://github.com/eclipse-che/che-theia/tree/master/extensions/eclipse-che-theia-plugin-ext[Che-Theia API extension] -|=== - - - -[id="vs-code-extensions-and-eclipse-theia-plug-ins_{context}"] -== VS Code extensions and Eclipse Theia plug-ins - -A Che-Theia plug-in can be based on a VS Code extension or an Eclipse Theia plug-in. - -A Visual Studio Code extension:: To repackage a VS Code extension as a Che-Theia plug-in with its own set of dependencies, package the dependencies into a container. This ensures that {prod} users do not need to install the dependencies when using the extension. See xref:adding-a-vs-code-extension-to-a-workspace.adoc[]. - -An Eclipse Theia plug-in:: You can build a Che-Theia plug-in by implementing an Eclipse Theia plug-in and packaging it to {prod}. - - -.Additional resources - -* xref:embedded-and-remote-che-theia-plug-ins_{context}[] diff --git a/modules/end-user-guide/partials/con_che-theia-plug-in-lifecycle.adoc b/modules/end-user-guide/partials/con_che-theia-plug-in-lifecycle.adoc deleted file mode 100644 index afd8f10950..0000000000 --- a/modules/end-user-guide/partials/con_che-theia-plug-in-lifecycle.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// This assembly is included in the following assemblies: -// -// `what-is-a-che-theia-plug-in` - -[id="che-theia-plug-in-lifecycle_{context}"] -= Che-Theia plug-in lifecycle - -Every time a user starts a Che workspace, a Che-Theia plug-in life cycle process starts. The steps of this process are as follows: - -. {prod-short} server checks for plug-ins to start from the workspace definition. -. {prod-short} server retrieves plug-in metadata, recognizes each plug-in type, and stores them in memory. -. {prod-short} server selects a broker according to the plug-in type. -. The broker processes the installation and deployment of the plug-in. The installation process of the plug-in differs for each specific broker. - -NOTE: Plug-ins exist in various types. A broker ensures the success of a plug-in deployment by meeting all installation requirements. - - - -.Che-Theia plug-in lifecycle -image::extensibility/che-theia-plug-in-lifecycle.svg[link="../_images/extensibility/che-theia-plug-in-lifecycle.svg"] - -Before a {prod-short} workspace is launched, {prod-short} server starts the workspace containers: - -. The Che-Theia plug-in broker extracts the information about sidecar containers that a particular plug-in needs from the `.theia` file. -. The broker sends the appropriate container information to {prod-short} server. -. The broker copies the Che-Theia plug-in to a volume to have it available for the Che-Theia editor container. -. {prod-short} server then starts all the containers of the workspace. -. Che-Theia starts in its container and checks the correct folder to load the plug-ins. - -.A user experience with Che-Theia plug-in lifecycle -. When a user opens a browser tab with Che-Theia, Che-Theia starts a new plug-in session with: -+ -* Web Worker for frontend -* Node.js for backend - -. Che-Theia notifies all Che-Theia plug-ins with the start of the new session by calling the `start()` function for each triggered plug-in. - -. A Che-Theia plug-in session runs and interacts with the Che-Theia backend and frontend. - -. When the user closes the Che-Theia browser tab, or the session ended on a timeout limit, Che-Theia notifies all plug-ins with the `stop()` function for each triggered plug-in. - - -// .Additional resources -// -// * A bulleted list of links to other material closely related to the contents of the concept module. -// * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. diff --git a/modules/end-user-guide/partials/con_che-theia-task-types.adoc b/modules/end-user-guide/partials/con_che-theia-task-types.adoc deleted file mode 100644 index 513a073233..0000000000 --- a/modules/end-user-guide/partials/con_che-theia-task-types.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// defining-custom-commands-for-che-theia - -[id="che-theia-task-types_{context}"] -= Che-Theia task types - -The following is an example of the `commands` section of a devfile. - -[source,yaml] ----- -commands: - - - name: Package Native App - actions: - - type: exec - component: centos-quarkus-maven - command: "mvn package -Dnative -Dmaven.test.skip" - workdir: ${CHE_PROJECTS_ROOT}/quarkus-quickstarts/getting-started - - - name: Start Native App - actions: - - type: exec - component: ubi-minimal - command: ./getting-started-1.0-SNAPSHOT-runner - workdir: ${CHE_PROJECTS_ROOT}/quarkus-quickstarts/getting-started/target - - - name: Attach remote debugger - actions: - - type: vscode-launch - referenceContent: | - { - "version": "0.2.0", - "configurations": [ - { - "type": "java", - "request": "attach", - "name": "Attach to Remote Quarkus App", - "hostName": "localhost", - "port": 5005 - } - ] - } ----- - -{prod-short} commands:: `Package Native App` and `Start Native App` -+ -The {prod-short} commands are to be used to define tasks that will be executed in the workspace container. -+ -* The `exec` type implies that the {prod-short} runner is used for command execution. The user can specify the component in whose container the command is executed. -* The `command` field contains the command line for execution. -* The `workdir` is the working directory in which the command is executed. -* The `component` field refers to the container where the command will be executed. The field contains the component `alias` where the container is defined. - -VS Code `launch` configurations:: `Attach remote debugger` -+ -VS Code `launch` configurations are commonly used to define debugging configuration. To trigger these configurations, press btn:[F5] or choose *Start Debugging* from the *Debug* menu. The configurations provide information to the debugger, such as the port to connect to for debugging or the type of the application to debug (Node.js, Java, and others.). -+ -* The type is `vscode-launch`. -* It contains the `launch` configurations in the VS Code format. -* For more information about VS Code `launch` configurations, see the Debugging section on the link:https://code.visualstudio.com/docs/editor/debugging#_launch-configurations[Visual Studio documentation page]. - -Tasks of type `che`, also known as `exec` commands, can be executed from the *Terminal->Run Task* menu or by selecting them in the *My Workspace* panel. Other tasks are only available from *Terminal->Run Task*. Configurations to start with are available in the Che-Theia debugger. - -.Additional resources - -* link:https://raw.githubusercontent.com/eclipse/che-devfile-registry/master/devfiles/quarkus-command-mode/devfile.yaml[Quarkus command mode devfile, including a `theia` task and a `vscode-launch` task] diff --git a/modules/end-user-guide/partials/con_embedded-and-remote-che-theia-plug-ins.adoc b/modules/end-user-guide/partials/con_embedded-and-remote-che-theia-plug-ins.adoc deleted file mode 100644 index 7065b43b32..0000000000 --- a/modules/end-user-guide/partials/con_embedded-and-remote-che-theia-plug-ins.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// This assembly is included in the following assemblies: -// -// what-is-a-che-theia-plug-in - -[id="embedded-and-remote-che-theia-plug-ins_{context}"] -= Embedded and remote Che-Theia plug-ins - -Developer workspaces in {prod} provide all dependencies needed to work on a project. The application includes the dependencies needed by all the tools and plug-ins used. - -Based on the required dependencies, Che-Theia plug-in can run as: - -* Embedded, also know as local -* Remote - - -[id="embedded-or-local-plug-ins_{context}"] -== Embedded (local) plug-ins - -The Embedded plug-ins are plug-ins without specific dependencies that are injected into the Che-Theia IDE. These plug-ins use the Node.js runtime, which runs in the IDE container. - -Examples: - -* Code linting -* New set of commands -* New UI components - -To include a Che-Theia plug-in or VS Code extension, define a URL to the plug-in `.theia` archive binary in the `meta.yaml` file. See -xref:adding-a-vs-code-extension-to-a-workspace.adoc[] - -When starting a workspace, {prod-short} downloads and unpacks the plug-in binaries and includes them in the Che-Theia editor container. The Che-Theia editor initializes the plug-ins when it starts. - - -[id="remote-plug-ins_{context}"] -== Remote plug-ins - -The plug-in relies on dependencies or it has a back end. It runs in its own sidecar container, and all dependencies are packaged in the container. - -A remote Che-Theia plug-in consist of two parts: - -* Che-Theia plug-in or VS Code extension binaries. The definition in the `meta.yaml` file is the same as for embedded plug-ins. - -* Container image definition, for example, `eclipse/che-theia-dev:nightly`. From this image, {prod-short} creates a separate container inside a workspace. - -Examples: - -* Java Language Server -* Python Language Server - -When starting a workspace, {prod-short} creates a container from the plug-in image, downloads and unpacks the plug-in binaries, and includes them in the created container. The Che-Theia editor connects to the remote plug-ins when it starts. - - -== Comparison matrix - -* Embedded plug-ins are those Che-Theia plug-ins or VS Code extensions that do not require extra dependencies inside its container. - -* Remote plug-ins are containers that contain a plug-in with all required dependencies. - -.Che-Theia plug-in comparison matrix: embedded vs remote -[options="header",cols="h,,,"] -|=== -| -| Configure RAM per plug-in -| Environment dependencies -| Create separated container - -| Remote -| TRUE -| Plug-in uses dependencies defined in the remote container. -| TRUE - -| Embedded -| FALSE (users can configure RAM for the whole editor container, but not per plug-in) -| Plug-in uses dependencies from the editor container; if container does not include these dependencies, the plug-in fails or does not function as expected. -| FALSE -|=== - -Depending on your use case and the capabilities provided by your plug-in, select one of the described running modes. - - -// .Additional resources -// -// * A bulleted list of links to other material closely related to the contents of the concept module. -// * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. diff --git a/modules/end-user-guide/partials/con_jetbrains-product-name-mapping.adoc b/modules/end-user-guide/partials/con_jetbrains-product-name-mapping.adoc deleted file mode 100644 index a7c7a67976..0000000000 --- a/modules/end-user-guide/partials/con_jetbrains-product-name-mapping.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following procedures: -// -// provisioning-jetbrains-activation-code-for-offline-use - -[id="jetbrains-product-name-mapping"] -= JetBrains product-name mapping - -This section provides mapping used internally between JetBrains products and the product name during image build. - -[cols="<,",options="header"] -|=== -|JetBrains Product |`PRODUCT_NAME` -|IntelliJ Idea Community Edition |`ideaIC` -|IntelliJ Idea Ultimate Edition |`ideaIU` -|WebStorm |`WebStorm` -|=== diff --git a/modules/end-user-guide/partials/con_support-for-theia-based-ides.adoc b/modules/end-user-guide/partials/con_support-for-theia-based-ides.adoc deleted file mode 100644 index 1b757ef8c6..0000000000 --- a/modules/end-user-guide/partials/con_support-for-theia-based-ides.adoc +++ /dev/null @@ -1,61 +0,0 @@ -[id="con_support-for-theia-based-ides_{context}"] -= Theia-based IDEs - -This section describes how to provide a custom IDE, based on Eclipse Theia framework. - -To use a Theia-based IDE in {prod} as an editor, you need to prepare two main components: - -* a Docker image containing your IDE -* the Che editor descriptor file - `meta.yaml` - -.Procedure - -. Describe the IDE with an editor descriptor - `meta.yaml` file: -+ -[source,yaml] ----- -version: 1.0.0 -editors: - - id: eclipse/che-theia/next - title: Eclipse Theia development version. - displayName: theia-ide - description: Eclipse Theia, get the latest release each day. - icon: https://raw.githubusercontent.com/theia-ide/theia/master/logo/theia-logo-no-text-black.svg?sanitize=true - repository: https://github.com/eclipse-che/che-theia - firstPublicationDate: "2021-01-01" - endpoints: - - name: "theia" - public: true - targetPort: 3100 - attributes: - protocol: http - type: ide - secure: true - cookiesAuthEnabled: true - discoverable: false - containers: - - name: theia-ide - image: "<your-ide-image>" - mountSources: true - ports: - - exposedPort: 3100 - memoryLimit: "512M" ----- -+ -`targetPort` and `exposedPort` must be the same as the Theia-based IDE running inside the container. -Replace `<your-ide-image>` with the name of the IDE image. -The `meta.yaml` file should be publicly accessible through an HTTP(S) link. - -. Add your editor to a Devfile: -+ -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: che-theia-based-ide -components: - - type: cheEditor - reference: '<meta.yaml URL>' ----- -+ -`<meta.yaml URL>` should point to the publicly hosted `meta.yaml` file described in the previous step. diff --git a/modules/end-user-guide/partials/con_what-is-a-devfile.adoc b/modules/end-user-guide/partials/con_what-is-a-devfile.adoc deleted file mode 100644 index 3845dd6d1c..0000000000 --- a/modules/end-user-guide/partials/con_what-is-a-devfile.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-using-a-devfile -// configuring-a-workspace-using-a-devfile - - -[id="what-is-a-devfile_{context}"] -= What is a devfile - -A devfile is a file that describes and define a development environment: - -* The source code. -* The development components, such as browser IDE tools and application runtimes. -* A list of pre-defined commands. -* Projects to clone. - -A devfiles is a YAML file that {prod-short} consumes and transforms into a cloud workspace composed of multiple containers. It is possible to store a devfile remotely or locally, in any number of ways, such as: - -* In a Git repository, in the root folder, or on a feature branch. -* On a publicly accessible web server, accessible through HTTP. -* Locally as a file, and deployed using `{prod-cli}`. -* In a collection of devfiles, known as a xref:administration-guide:customizing-the-registries.adoc#understanding-the-che-registries_{context}[devfile registry]. - -When creating a workspace, {prod-short} uses that definition to initiate everything and run all the containers for the required tools and application runtimes. {prod-short} also mounts file-system volumes to make source code available to the workspace. - -Devfiles can be versioned with the project source code. When there is a need for a workspace to fix an old maintenance branch, the project devfile provides a definition of the workspace with the tools and the exact dependencies to start working on the old branch. Use it to instantiate workspaces on demand. - -{prod-short} maintains the devfile up-to-date with the tools used in the workspace: - -* Elements of the project, such as the path, Git location, or branch. -* Commands to perform daily tasks such as build, run, test, and debug. -* The runtime environment with its container images needed for the application to run. -* Che-Theia plug-ins with tools, IDE features, and helpers that a developer would use in the workspace, for example, Git, Java support, SonarLint, and Pull Request. diff --git a/modules/end-user-guide/partials/proc_accessing-a-git-repository-via-https.adoc b/modules/end-user-guide/partials/proc_accessing-a-git-repository-via-https.adoc deleted file mode 100644 index a2d484414a..0000000000 --- a/modules/end-user-guide/partials/proc_accessing-a-git-repository-via-https.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// version-control - -[id="accessing-a-git-repository-via-https_{context}"] -= Accessing a Git repository using HTTPS - -.Procedure - -To clone a repository using HTTPS: - -. Use the link:https://code.visualstudio.com/docs/editor/versioncontrol#_cloning-a-repository[clone] command provided by the Visual Studio Code *Git* extension. - -Alternatively, use the native Git commands in the terminal to clone a project. - -. Navigate to destination folder using the `cd` command. -. Use `git clone` to clone a repository: -+ -[subs=+quotes] ----- -$ git clone _<link>_ ----- -+ -{prod} supports Git self-signed TLS certificates. -See xref:installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] to learn more. diff --git a/modules/end-user-guide/partials/proc_accessing-a-git-repository-via-ssh.adoc b/modules/end-user-guide/partials/proc_accessing-a-git-repository-via-ssh.adoc deleted file mode 100644 index d5e337e67f..0000000000 --- a/modules/end-user-guide/partials/proc_accessing-a-git-repository-via-ssh.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// version-control - -[id="accessing-a-git-repository-via-ssh_{context}"] -= Accessing a Git repository using a generated SSH key pair - -== Generating an SSH key using the {prod-short} command palette - -You can generate an SSH key by using the {prod-short} command palette. You have to create a unique SSH key for each Git provider in use because each SSH key restricts permissions for one specific Git provider. - -A common SSH key pair that works with all the Git providers is available by default. To start using it, add the public key to the Git provider. - -.Prerequisites -* A running instance of {prod-short}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. - -* An existing workspace defined on this instance of {prod-short} xref:configuring-a-workspace-with-dashboard.adoc[]. - -* Personal link:https://help.github.com/en/articles/types-of-github-accounts[GitHub account] or other Git provider account created. - -.Procedure - -. Generate an SSH key pair that only works with a particular Git provider: - -** In the {prod-short} IDE, press kbd:[F1] to open the Command Palette, or navigate to *View -> Find Command* in the top menu. -+ -The *command palette* can be also activated by pressing kbd:[Ctrl+Shift+p] (or kbd:[Cmd+Shift+p] on macOS). - -** Search for *SSH: generate key pair for particular host* by entering `generate` into the search box and pressing kbd:[Enter] once filled. - -** Provide the host name for the SSH key pair such as, for example, `github.com`. -+ -The SSH key pair is generated. - -. Click the btn:[View] button in the lower-right corner and copy the public key from the editor and add it to the Git provider. -+ -It is possible to use another command from the command palette: *Clone git repository* by providing an SSH secured URL. - -== Adding the associated public key to a repository or account on GitHub - -To add the associated public key to a repository or account on GitHub: - -. Navigate to link:https://github.com[github.com]. -. Click the drop-down arrow next to the user icon in the upper right corner of the window. -. Click *Settings* -> *SSH and GPG keys* and then click the btn:[New SSH key] button. -. In the *Title* field, type a title for the key, and in the *Key* field, paste the public key copied from {prod-short}. -. Click the btn:[Add SSH key] button. - -== Adding the associated public key to a Git repository or account on GitLab - -To add the associated public key to a Git repository or account on GitLab: - -. Navigate to link:https://gitlab.com[gitlab.com]. -. Click the user icon in the upper right corner of the window. -. Click *Settings* -> *SSH Keys*. -. In the *Title* field, type a title for the key and in the *Key* field, paste the public key copied from {prod-short}. -. Click the btn:[Add key] button. diff --git a/modules/end-user-guide/partials/proc_accessing-che-from-red-hat-applications-menu.adoc b/modules/end-user-guide/partials/proc_accessing-che-from-red-hat-applications-menu.adoc index 1745d9a7da..52949656dc 100644 --- a/modules/end-user-guide/partials/proc_accessing-che-from-red-hat-applications-menu.adoc +++ b/modules/end-user-guide/partials/proc_accessing-che-from-red-hat-applications-menu.adoc @@ -5,7 +5,7 @@ [id="accessing-{prod-id-short}-from-red-hat-applications-menu_{context}"] = Accessing {prod-short} from Red Hat Applications menu -This section describes how to access {prod-short} workspaces from the *Red Hat Applications* menu on OpenShift Container Platform. +This section describes how to access {prod-short} workspaces from the *Red Hat Applications* menu on the OpenShift Container Platform. .Prerequisites @@ -17,7 +17,7 @@ This section describes how to access {prod-short} workspaces from the *Red Hat A + The drop-down menu displays the available applications. + -image::installation/{project-context}-red-hat-application-menu-che-odp.png[Applications in the drop-down menu,link="../_images/installation/{project-context}-red-hat-application-menu-che-odp.png"] +image::installation/{project-context}-red-hat-application-menu-che-odp.png[Applications in the drop-down menu,link="{imagesdir}/installation/{project-context}-red-hat-application-menu-che-odp.png"] . Click the *{prod-short}* link to open the {prod2} Dashboard. diff --git a/modules/end-user-guide/partials/proc_accessing-workspaces-remotely-using-kubectl.adoc b/modules/end-user-guide/partials/proc_accessing-workspaces-remotely-using-kubectl.adoc deleted file mode 100644 index 148d6d600f..0000000000 --- a/modules/end-user-guide/partials/proc_accessing-workspaces-remotely-using-kubectl.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// remotely-accessing-workspaces - -[id="accessing-workspaces-remotely-using-{orch-cli}_{context}"] -= Remotely accessing workspaces using `{orch-cli}` - -To access {prod-short} workspaces remotely using {orch-name} command-line tool (`{orch-cli}`), follow the instructions in this section. - -ifeval::["{project-context}" == "che"] -NOTE: The `{orch-cli}` tool is used in this section to open a shell and manage files in a {prod-short} workspace. Alternatively, it is possible to use the `oc` OpenShift command-line tool. -endif::[] - -.Prerequisites - -* The `{orch-cli}`, version 1.5.0 or higher, is available. For information about installed version, use: -+ -[subs="+quotes,+attributes",options="+nowrap"] ----- -$ {orch-cli} version -Client Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0" - -... - ----- - - -.Procedure - -In the example below: - -* `workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4` is the name of the Pod. -* `{project-context}` is the {orch-namespace}. - -. To find the name of the {platforms-name} {orch-namespace} and the Pod that runs the {prod-short} workspace: -+ -[subs="+attributes,+quotes",options="+nowrap"] ----- -$ {orch-cli} get pod -l che.workspace_id --all-namespaces -NAMESPACE NAME READY STATUS RESTARTS AGE -{project-context} workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4 4/4 Running 0 6m4s ----- - - -. To find the name of the container: -+ -[subs="+attributes,+quotes",options="+nowrap"] ----- -$ NAMESPACE={project-context} -$ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4 -$ {orch-cli} get pod $\{POD} -o custom-columns=CONTAINERS:.spec.containers[*].name -CONTAINERS -maven,che-machine-execpau,theia-ide6dj,vscode-javaw92 ----- - -. When you have the {orch-namespace}, Pod name, and the name of the container, use the `{orch-cli} ` command to open a remote shell: -+ -[literal,subs="+attributes,+quotes",options="nowrap"] --- -$ NAMESPACE={project-context} -$ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4 -$ CONTAINER=maven -$ {orch-cli} exec -ti -n $\{NAMESPACE} $\{POD} -c $\{CONTAINER} bash -user@workspace7b2wemdf3hx7s3ln $ --- - -. From the container, execute the `build` and `run` commands (as if from the {prod-short} workspace terminal): -+ -[subs="+quotes",options="+nowrap"] ----- -user@workspace7b2wemdf3hx7s3ln $ mvn clean install -[INFO] Scanning for projects... -(...) ----- - -.Additional resources - -* For more about `{orch-cli}`, see the {orch-cli-link}. diff --git a/modules/end-user-guide/partials/proc_adding-a-kubernetes-application-to-an-existing-workspace-using-the-dashboard.adoc b/modules/end-user-guide/partials/proc_adding-a-kubernetes-application-to-an-existing-workspace-using-the-dashboard.adoc deleted file mode 100644 index a05be8a896..0000000000 --- a/modules/end-user-guide/partials/proc_adding-a-kubernetes-application-to-an-existing-workspace-using-the-dashboard.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// importing-kubernetes-applications-into-a-workspace - -[id="adding-a-kubernetes-application-to-an-existing-workspace-using-the-dashboard_{context}"] -= Adding a {platforms-name} application to an existing workspace using the dashboard - -This procedure demonstrates how to modify an existing workspace and import the {platforms-name} application using the newly created devfile. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -. After the creation of a workspace, use the *Workspace* menu and then click on the desired workspace. -. Modify the workspace devfile, use the *Devfile* tab. -. Add a {platforms-name} component. -. For the changes to take effect, save the devfile and restart the {prod-short} workspace. diff --git a/modules/end-user-guide/partials/proc_adding-a-vs-code-extension-to-the-che-plugin-registry.adoc b/modules/end-user-guide/partials/proc_adding-a-vs-code-extension-to-the-che-plugin-registry.adoc deleted file mode 100644 index d927b11c0d..0000000000 --- a/modules/end-user-guide/partials/proc_adding-a-vs-code-extension-to-the-che-plugin-registry.adoc +++ /dev/null @@ -1,107 +0,0 @@ -[id="proc_adding-a-vs-code-extension-to-the-che-plugin-registry_{context}"] -= Adding a VS Code extension to the Che plug-ins registry - -To use a VS Code extension in a {prod-short} workspace, {prod-short} need to consume metadata describing the extension. The {prod-short} plug-ins registry is a static website publishing metadata for common VS Code extensions. VS Code extension metadata for the {prod-short} plug-ins registry is generated from a central file named `che-theia-plugins.yaml`. - -To add or modify an extension in the {prod-short} plug-ins registry, edit the `che-theia-plugins.yaml` file and add relevant metadata. - -[NOTE] -==== -This article describes the steps needed to build the plug-ins registry with a custom plug-in definition. If you are looking to create a custom `meta.yaml` file that can be directly referenced in a devfile, see xref:end-user-guide:publishing-metadata-for-a-vs-code-extension.adoc[]. -==== - - -.Prerequisite -* A working knowledge of customizing the registries, see xref:administration-guide:customizing-the-registries.adoc[] -* A link to a sidecar container image, should the VS Code extension require one. - - -.Procedure - -. Edit the `che-theia-plugins.yaml` file and create a new entry. - -+ -[source,yaml] ----- -- id: publisher/my-vscode-ext <1> - repository: <2> - url: https://github.com/publisher/my-vscode-ext <3> - revision: 1.7.2 <4> - aliases: <5> - - publisher/my-vscode-ext-revised - preferences: <6> - asciidoc.use_asciidoctorpdf: true - shellcheck.executablePath: /bin/shellcheck - solargraph.bundlerPath: /usr/local/bin/bundle - solargraph.commandPath: /usr/local/bundle/bin/solargraph - sidecar: <7> - image: quay.io/repository/eclipse/che-plugin-sidecar:sonarlint-2fcf341 <8> - name: my-vscode-ext-sidecar <9> - memoryLimit: "1500Mi" <10> - memoryRequest: "1000Mi" <11> - cpuLimit: "500m" <12> - cpuRequest: "125m" <13> - command: <14> - - /bin/sh - args: <15> - - "-c" - - "./entrypoint.sh" - volumeMounts: <16> - - name: vscode-ext-volume <17> - path: "/home/theia/my-vscode-ext" <18> - endpoints: <19> - - name: "configuration-endpoint" <20> - public: true <21> - targetPort: 61436 <22> - attributes: <23> - protocol: http - extension: https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix <24> - skipDependencies: <25> - - id-of/extension1 - - id-of/extension2 - extraDependencies: <26> - - id-of/extension1 - - id-of/extension2 - metaYaml: - skipIndex: <true|false> <27> - skipDependencies: <28> - - id-of/extension1 - - id-of/extension2 - extraDependencies: <29> - - id-of/extension1 - - id-of/extension2 ----- - -<1> (OPTIONAL) The ID of the plug-in, useful if a plug-in has multiple entries for one repository. For example, Java 8 and Java 11. -<2> Repository information about the plug-in. If ID is specified, then this field is not a list element. -<3> The URL to the Git repository of the extension. -<4> Tag or SHA1 ID of the upstream repository that hosts the extension, corresponding to a version, snapshot, or release. -<5> (OPTIONAL) An alias for this plug-in. For anything listed here, a `meta.yaml` file is generated. -<6> (OPTIONAL) Plug-in preferences in freeform format. -<7> (OPTIONAL) If the plug-in runs in a sidecar container, then the sidecar information is specified here. -<8> A location of a container image to be used as the plug-in sidecar. This line cannot be specified concurrently with `directory`. See above. -<9> (OPTIONAL) The name of the sidecar container. -<10> (OPTIONAL) The memory limit of the sidecar container. -<11> (OPTIONAL) The memory request of the sidecar container. -<12> (OPTIONAL) The CPU limit of the sidecar container. -<13> (OPTIONAL) The CPU request of the sidecar container. -<14> (OPTIONAL) Definitions of root process commands inside the container. -<15> (OPTIONAL) Arguments for root process commands inside the container. -<16> (OPTIONAL) Any volume mounting information for the sidecar container. -<17> The name of the mount. -<18> The path to the mount. -<19> (OPTIONAL) Any endpoint information for the sidecar container. -<20> Endpoint name. -<21> A Boolean value determining whether the endpoint is exposed publicly. -<22> The port number. -<23> Attributes relating to the endpoint. -<24> Direct link or links to the `vsix` files included with the plug-in. The `vsix` built by the repository specified, such as the main extension, must be listed first. -<25> # TODO # -<26> (OPTIONAL) Extra dependencies in addition to the one listed in extensionDependencies field of package.json. -<27> (OPTIONAL) Do not include this plug-in in index.json if true. Useful in case of dependencies that you do not want to expose as standalone plug-ins. -<28> (OPTIONAL) Do not look at specified dependencies from extensionDependencies field of package.json (only for meta.yaml generation). -<29> (OPTIONAL) Extra dependencies in addition to the one listed in extensionDependencies field of package.json (only for meta.yaml generation). - - -. Run the `build.sh` script with the options of your choosing. The build process will generate `meta.yaml` files automatically, based on the entries in the `che-theia-plugins.yaml` file. -. Use the resulting plug-ins registry image in {prod-short}, or copy the `meta.yaml` file out of the registry container and reference it directly as an HTTP resource. diff --git a/modules/end-user-guide/partials/proc_adding-language-support-plug-in-to-the-che-workspace.adoc b/modules/end-user-guide/partials/proc_adding-language-support-plug-in-to-the-che-workspace.adoc deleted file mode 100644 index 89c422057a..0000000000 --- a/modules/end-user-guide/partials/proc_adding-language-support-plug-in-to-the-che-workspace.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// adding-tools-to-{prod-id-short}-after-creating-a-workspace - -[id="adding-language-support-plug-in-to-the-{prod-id-short}-workspace_{context}"] -= Adding a language support plug-in to a {prod-short} workspace - -This procedure describes adding a tool to a created workspace by enabling a dedicated plug-in from the Dashboard. - -//To add tools that are available as plug-ins into a {prod-short} workspace, use one of the following methods: -//The sentence on the prev line seems to be out of place at the time of writing this comment, hence commenting it out. max-cx - -* xref:installing-the-plug-in-by-adding-content-to-the-devfile_{context}[Edit the workspace devfile from the Dashboard *Devfile* tab.] - -.Prerequisites - -* A running instance of {prod-short}. -+ -See {link-installing-an-instance}. - -* A created workspace that is defined in this instance of {prod}. -+ -See xref:configuring-a-workspace-with-dashboard.adoc[] and xref:creating-a-workspace-from-a-code-sample.adoc[]. - -* The workspace must be in a **stopped** state. -+ -The steps to stop a workspace: -+ -.. Navigate to the {prod-short} Dashboard, as explained in xref:navigating-che-using-the-dashboard.adoc[]. -.. In the *Dashboard*, click the *Workspaces* menu to open the workspaces list and locate the workspace. -.. On the same row with the displayed workspace, on the right side of the screen, click btn:[Stop] to stop the workspace. -.. Wait a few seconds for the workspace to stop, and then configure the workspace by selecting it. - -//Is there a different section that describes the procedure on the previous lines? max-cx - -.Procedure - -To add a plug-in from the plug-in registry to a created {prod-short} workspace, install the plug-in as follows by adding content to the devfile: -//To add a plug-in from the Plug-in registry to a created {prod-short} workspace, use one of the following methods: -//This list contains only one entry at the time of writing this comment, hence commenting out the sentence on the previous line. max-cx - -[id="installing-the-plug-in-by-adding-content-to-the-devfile_{context}"] - -//<<installing-the-plug-in-by-adding-content-to-the-devfile_{context}>> - -//** Installing the plug-in by adding content to the devfile. commented out by max-cx -. Navigate to the *Devfile* tab, where the devfile YAML is displayed. -. In the `components` devfile section, add the following lines: `id` and `type`. -+ -.Example: Adding the Java 8 language plugin -include::example${project-context}-java-language-support.adoc[] -+ -.Example: The end result -+ -include::example${project-context}-workspace-from-the-php-stack-java-language-support.adoc[] -. Click btn:[Save] to save the changes. -. Restart the workspace. -. Verify that the workspace includes the new plug-in. - -.Additional resources - -* link:https://redhat-developer.github.io/devfile/devfile[Devfile specifications] diff --git a/modules/end-user-guide/partials/proc_adding-projects-to-your-workspace.adoc b/modules/end-user-guide/partials/proc_adding-projects-to-your-workspace.adoc deleted file mode 100644 index 470e586377..0000000000 --- a/modules/end-user-guide/partials/proc_adding-projects-to-your-workspace.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-with-dashboard - -[id="adding-projects-to-your-workspace_{context}"] -= Adding projects to your workspace - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -To add a project to your workspace: - -. Navigate to the *Workspaces* page and click the workspace, which is about to be updated. - -. Open the *Devfile* tab. - -. In the *Devfile editor*, add a `projects` section with desired project. -+ -image::workspaces/workspace-devfile-editor.png[Edit Devfile Content, link="../_images/workspaces/workspace-devfile-editor.png"] -+ -. Once the project is added, click the btn:[Save] button to save this workspace configuration. -+ -For demonstration example, see below: -+ -include::example${project-context}-adding-a-git-project-into-a-workspace-using-a-devfile.adoc[leveloffset=+1] diff --git a/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-recommendations.adoc b/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-recommendations.adoc deleted file mode 100644 index e877b58aa3..0000000000 --- a/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-recommendations.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// adding-{prod-id-short}-plug-in-registry-vs-code-extension-to-a-workspace - -[id="adding-the-vs-code-extension-using-recommendations-{prod-id-short}_{context}"] -= Adding a VS Code extension using recommendations - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. -* Featured VS Code extensions are available in the {prod-short} plug-in registry. - -.Procedure - -Open a workspace without any existing devfile using the *{prod-short} dashboard*: - -The recommendations plug-in will scan files, discover languages and install VS Code extensions matching these languages. -Disable this feature by setting `extensions.ignoreRecommendations` to true in the devfile attributes. - -The recommendations plug-in can suggest VS Code extensions to install when opening files. It suggests extensions based on the workspace content, allowing the user to work with the given files. -Enable this feature by setting `extensions.openFileRecommendations` to true in the devfile attributes. diff --git a/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc b/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc deleted file mode 100644 index e7d748cba5..0000000000 --- a/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// adding-{prod-id-short}-plug-in-registry-vs-code-extension-to-a-workspace - -[id="adding-the-vs-code-extension-using-the-{prod-id-short}-plugins-panel_{context}"] -= Adding a VS Code extension using the *{prod-short} Plugins* panel - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. -* The VS Code extension is available in the {prod-short} plug-in registry, or metadata for the VS Code extension are available. See xref:publishing-metadata-for-a-vs-code-extension.adoc[]. - -.Procedure - -To add a VS Code extension using the *{prod-short} Plugins* panel: - -. Open the *{prod-short} Plugins* panel by pressing `CTRL+SHIFT+J` or navigate to *View -> Plugins*. - -. Change the current registry to the registry in which the VS Code extension was added. - -. In the search bar, click the *Menu* button and then click *Change Registry* to choose the registry from the list. If the required registry is not in the list, add it using the *Add Registry* menu option. The registry link points to the `plugins` segment of the registry, for example: `+https://my-registry.com/v3/plugins/index.json+`. - -. To update the list of plug-ins after adding a new registry link, use `Refresh` command from the search bar menu. - -. Search for the required plug-in using the filter, and then click the btn:[Install] button. -. Restart the workspace for the changes to take effect. diff --git a/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc b/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc deleted file mode 100644 index 2709d54c7e..0000000000 --- a/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// adding-{prod-id-short}-plug-in-registry-vs-code-extension-to-a-workspace - -[id="adding-the-vs-code-extension-using-the-workspace-configuration_{context}"] -= Adding a VS Code extension using the workspace configuration - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod-short}. - -* The VS Code extension is available in the {prod-short} plug-in registry, or metadata for the VS Code extension are available. See xref:publishing-metadata-for-a-vs-code-extension.adoc[]. - -.Procedure - -To add a VS Code extension using the workspace configuration: - -. Click the *Workspaces* tab on the *Dashboard* and select the plug-in destination workspace. -+ -The *Workspace __<workspace-name>__* window is opened showing the details of the workspace. - -. Click the *devfile* tab. - -. Locate the *components* section, and add a new entry with the following structure: -+ -[source,yaml,subs="+quotes"] ----- - - type: chePlugin - id: <1> ----- -<1> ID format: `_<publisher>/<plug-inName>/<plug-inVersion>_` -+ -{prod-short} automatically adds the other fields to the new component. -+ -Alternatively, you can link to a `meta.yaml` file hosted on GitHub, using the dedicated reference field. -+ -[source,yaml,subs="+quotes"] ----- - - type: chePlugin - reference: <1> ----- -<1> `pass:c,a,q[https://raw.githubusercontent.com/__<username>__/__<registryRepository>__/v3/plugins/__<publisher>__/__<plug-inName>__/__<plug-inVersion>__/meta.yaml]` -+ - -. Restart the workspace for the changes to take effect. diff --git a/modules/end-user-guide/partials/proc_allowing-users-to-define-workspace-creation-strategy.adoc b/modules/end-user-guide/partials/proc_allowing-users-to-define-workspace-creation-strategy.adoc deleted file mode 100644 index 4517e50953..0000000000 --- a/modules/end-user-guide/partials/proc_allowing-users-to-define-workspace-creation-strategy.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-a-remote-devfile - -[id="allowing-users-to-define-workspace-creation-strategy_{context}"] -= Allowing users to define workspace creation strategy - - -As a developer, you can configure {prod-short} to create a new workspace each time it accepts a factory URL, or to reuse the existing workspace if a user already has one. - -{prod-short} supports the following options: - -* `perclick`: The default strategy, which creates a new workspace each time a given factory URL is accepted. - -* `peruser`: Initially, a workspace is created using a factory URL. Other user's calls then re-use the particular workspace created by the factory URL (1 factory = 1 workspace). - -.Prerequisites - -* A running instance of {prod-short}. See xref:installation-guide:installing-che.adoc[]. -* The Git repository __<GIT_REPOSITORY_URL>__ is available over HTTPS. - - -.Procedure - -pass:[<!-- vale CheDocs.TechnicalTerms = NO -->] - -* Run the workspace by opening the factory URL and specify the additional strategy parameter: -+ -`pass:c,a,q[{prod-url}/f?url=__<GIT_REPOSITORY_URL>&policies.create=<value>__]` -+ - -pass:[<!-- vale CheDocs.TechnicalTerms = YES -->] diff --git a/modules/end-user-guide/partials/proc_allowing-users-to-define-workspace-deployment-labels-and-annotations.adoc b/modules/end-user-guide/partials/proc_allowing-users-to-define-workspace-deployment-labels-and-annotations.adoc deleted file mode 100644 index adbe23e594..0000000000 --- a/modules/end-user-guide/partials/proc_allowing-users-to-define-workspace-deployment-labels-and-annotations.adoc +++ /dev/null @@ -1,155 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-a-remote-devfile - -[id="allowing-users-to-define-workspace-deployment-labels-and-annotations_{context}"] -= Allowing users to define workspace deployment labels and annotations - -This section describes how to customize workspace deployment labels and annotation using factory parameters. - - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. -* A publicly accessible standalone `devfile.yaml` file. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles. - -.Procedure - -. Open the workspace by navigating to the following URL: `pass:c,a,q[{prod-url}/f?url=https://__<hostURL>__/devfile.yaml&workspaceDeploymentLabels=__<url_encoded_comma_separated_key_values>__&workspaceDeploymentAnnotations=__<url_encoded_comma_separated_key_values override>__]` - -.Example of overriding the `deployment labels` - -==== -Consider the following labels to add: - -[subs="+quotes"] ----- -ike.target=preference-v1 -ike.session=test ----- - - -To add or override labels, use the following factory URL: - -[subs="+quotes"] ----- -https://workspaces.openshift.com/f?url=__<repository-url>__&workspaceDeploymentLabels=ike.target%3Dpreference-v1%2Cike.session%3Dtest ----- - -The resulting workspace has the following deployment labels: - -[subs="+quotes"] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - annotations: - deployment.kubernetes.io/revision: "1" - creationTimestamp: "2020-10-27T14:03:26Z" - generation: 1 - labels: - che.component.name: che-docs-dev - che.original_name: che-docs-dev - che.workspace_id: workspacegln2g1shejjufpkd - ike.session: test - ike.target: preference-v1 - name: workspacegln2g1shejjufpkd.che-docs-dev - namespace: opentlc-mgr-che - resourceVersion: "107516" -spec: -... ----- -==== - -.Example of overriding the `deployment annotations` - -==== -Consider the following annotations to add: - -[subs="+quotes"] ----- -ike.A1=preference-v1 -ike.A=test ----- - - -To add or override annotations, use the following factory URL: - -[subs="+quotes"] ----- -https://workspaces.openshift.com/f?url=__<repository-url>__&workspaceDeploymentAnnotations=ike.A1%3Dpreference-v1%2Cike.A%3Dtest - ----- - -The resulting workspace has the following deployment annotations: - -[subs="+quotes"] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - annotations: - deployment.kubernetes.io/revision: "1" - ike.A: test - ike.A1: preference-v1 - creationTimestamp: "2020-10-28T09:58:52Z" - generation: 1 - labels: - che.component.name: che-docs-dev - che.original_name: che-docs-dev - che.workspace_id: workspacexrtf710v64rl5ouz - name: workspacexrtf710v64rl5ouz.che-docs-dev - namespace: opentlc-mgr-che - resourceVersion: "213191" -... ----- -==== - -.Verification steps - -To display the deployment labels and annotations: - -. Get the name of the user's namespace: - -pass:[<!-- vale Vale.Terms = NO -->] - -.. Using {prod-short} Dashboard, move to the *Workspaces* tab and read the name of the *{orch-name} {namespace}* field. - -pass:[<!-- vale Vale.Terms = YES -->] - -. Log in to the cluster: - -.. Retrieve the {prod-short} cluster URL from the `checluster` CR (Custom Resource), run: -+ -[options="nowrap",role=white-space-pre] ----- -$ oc get checluster --output jsonpath='{.items[0].status.cheURL}' ----- - -.. Log in: -+ -[subs="+attributes,+quotes"] ----- -$ oc login -u _<username>_ -p _<password>_ _<cluster_URL>_ ----- - -pass:[<!-- vale Vale.Terms = NO -->] - -. Display the deployment labels and annotations for all deployments in the {orch-namespace} using the *{orch-name} {namespace}* name from the first step: -+ -[subs="+attributes,+quotes"] ----- -$ oc get deployment -n __<NAMESPACE>__ -o=custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,LABELS:.metadata.labels,ANNOTATIONS:.metadata.annotations" ----- - - -//// -. To display the deployment labels and annotations for a specific deploymen: -+ -[subs="+attributes,+quotes"] ----- -$ oc get deployment/__<deployment-name>__ -n __<NAMESPACE>__ -o=custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,LABELS:.metadata.labels,ANNOTATIONS:.metadata.annotations" ----- -//// - -pass:[<!-- vale Vale.Terms = YES -->] \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_building-an-image-for-an-ide-based-on-the-intellij-platform.adoc b/modules/end-user-guide/partials/proc_building-an-image-for-an-ide-based-on-the-intellij-platform.adoc deleted file mode 100644 index 07423473d6..0000000000 --- a/modules/end-user-guide/partials/proc_building-an-image-for-an-ide-based-on-the-intellij-platform.adoc +++ /dev/null @@ -1,177 +0,0 @@ -[id="building-an-image-for-an-ide-based-on-the-intellij-platform_{context}"] -= Building an image for an IDE based on the IntelliJ Platform - -This procedure describes how to build an image for an link:https://plugins.jetbrains.com/docs/intellij/intellij-platform.html#ides-based-on-the-intellij-platform[IDE based on the IntelliJ Platform] link:https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#intellij-platform-based-products-of-recent-ide-versions[version 2020.3]. -For JetBrains IDEs, the IDE version number corresponds to the version of the IntelliJ Platform. -See the link:https://github.com/che-incubator/jetbrains-editor-images/blob/main/doc/Compatible-IDE.md[list of compatible IDEs]. - -.Prerequisites - -* The build host has at least 2 GB of available RAM. - -* The following tools are installed on the build host: - -** link:https://www.docker.com/[Docker] version 18.09 or greater, supporting link:https://docs.docker.com/develop/develop-images/build_enhancements/[BuildKit] - -** link:https://git-scm.com[Git] - -** link:https://www.gnu.org/software/libc/manual/html_node/Getopt.html[GNU getopt] - -** link:https://www.gnu.org/software/wget/[GNU wget] - -** link:https://openjdk.java.net/projects/jdk/11/[Java Development Kit (JDK) version 11] - -** link:https://stedolan.github.io/jq/[jq] - - -.Procedure - -. Get a local copy of the link:https://github.com/che-incubator/jetbrains-editor-images[JetBrains Projector Editor Images repository]. -+ ----- -$ git clone https://github.com/che-incubator/jetbrains-editor-images -$ cd jetbrains-editor-images ----- - -. Run the build script with parameters: -+ -[subs="+quotes,macros,attributes"] ----- -$ ./projector build --tag __<tag>__ --url __<URL>__ ----- -+ -`--tag __<tag>__`:: -The name and tag to apply to the image after build in `name:tag` format. -+ -`--url __<url>__`:: -The URL pointing to an archive of the IDE based on the link:https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#intellij-platform-based-products-of-recent-ide-versions[IntelliJ Platform version 2020.3]. The archive must target the Linux platform, be in `+tar.gz+` format, and include JetBrains Runtime (JBR). -+ -.Building the image with IntelliJ IDEA Community 2020.3.3 -==== ----- -./projector.sh build --tag che-idea:2020.3.3 \ - --url https://download-cdn.jetbrains.com/idea/ideaIC-2020.3.3.tar.gz ----- -==== -+ -.Building the image with PyCharm Community 2020.3.5 -==== ----- -$ ./projector.sh build --tag che-pycharm:2020.3.5 \ - --url https://download.jetbrains.com/python/pycharm-community-2020.3.5.tar.gz ----- -==== -+ -.Building the image with WebStorm 2020.3.3 -==== ----- -$ ./projector.sh build --tag che-webstorm:2020.3.3 \ - --url https://download.jetbrains.com/webstorm/WebStorm-2020.3.3.tar.gz ----- -==== -+ -.Building the image with IntelliJ IDEA Ultimate 2020.2.2 -==== ----- -$ ./projector.sh build --tag che-idea-ultimate:2020.2.2 \ - --url https://download.jetbrains.com/idea/ideaIU-2020.2.2.tar.gz ----- -==== -+ -.Building the image with Android Studio 4.2.0.22 -==== ----- -$ ./projector.sh build --tag che-android-studio:4.2.0.22 \ - --url https://redirector.gvt1.com/edgedl/android/studio/ide-zips/4.2.0.22/android-studio-ide-202.7188722-linux.tar.gz ----- -==== - -. To test the image, run it locally and go to `++http://localhost:8887++` to access the IDE. -+ -[subs="+quotes,macros,attributes"] ----- -$ ./projector.sh run __<tag>__ ----- -+ -.Testing the image with IntelliJ IDEA Community 2020.3.3 -==== ----- -$ ./projector.sh run che-idea:2020.3.3 ----- -==== -+ -.Testing the image with PyCharm 2020.3.5 -==== ----- -$ ./projector.sh run che-pycharm:2020.3.5 ----- -==== -+ -.Testing the image with WebStorm 2020.3.3 -==== ----- -$ ./projector.sh run che-webstorm:2020.3.3 ----- -==== -+ -.Testing the image with IntelliJ IDEA Ultimate 2020.2.2 -==== ----- -$ ./projector.sh run che-idea-ultimate:2020.2.2 ----- -==== -+ -.Testing the image with Android Studio 4.2.0.22 -==== ----- -$ ./projector.sh run che-android-studio:4.2.0.22 ----- -==== - -. Publish the image to a registry accessible by {prod-short}, and remember the location: __<registry>/<image>:<tag>__. - -. Create a `+meta.yaml+` file containing the IDE metadata for {prod-short}: -+ -[source,yaml,subs="+quotes,macros,attributes"] ----- -apiVersion: v2 -publisher: __<publisher>__ <1> -name: intellij-ide -version: latest -type: Che Editor -displayName: IntelliJ Platform IDE -title: IDE based on the IntelliJ Platform -description: IDE based on the IntelliJ Platform running using Projector -icon: https://www.jetbrains.com/apple-touch-icon.png -category: Editor -repository: https://github.com/che-incubator/jetbrains-editor-images -firstPublicationDate: "2021-04-10" -spec: - endpoints: - - name: intellij - public: true - targetPort: 8887 - attributes: - protocol: http - type: ide - path: /projector-client/index.html?backgroundColor=434343&wss - containers: - - name: intellij-ide - image: __<registry>/<image>:<tag>__ <2> - mountSources: true - volumes: - - mountPath: "/home/projector-user" - name: projector-user - ports: - - exposedPort: 8887 - memoryLimit: "4096M" ----- -<1> `__<publisher>__`: Your publisher name. -<2> `__<registry>/<image>:<tag>__`: Location of the IDE image in a registry accessible by {prod-short}. - -. Publish the `meta.yaml` file to an HTTPS resource accessible by {prod-short} and copy the resulting URL for use as `__<URL_to_meta.yaml>__` when configuring a workspace to use this IDE. - -.Next steps - -* xref:configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc[] - diff --git a/modules/end-user-guide/partials/proc_building-an-image-for-intellij-idea-community-or-pycharm-community.adoc b/modules/end-user-guide/partials/proc_building-an-image-for-intellij-idea-community-or-pycharm-community.adoc deleted file mode 100644 index feb6042bb5..0000000000 --- a/modules/end-user-guide/partials/proc_building-an-image-for-intellij-idea-community-or-pycharm-community.adoc +++ /dev/null @@ -1,99 +0,0 @@ -[id="building-an-image-for-intellij-idea-community-or-pycharm-community_{context}"] -= Building an image for IntelliJ IDEA Community or PyCharm Community - -This procedure describes how to build an image for IntelliJ IDEA Community or PyCharm Community. - -.Prerequisites - -* The build host has at least 2 GB of available RAM. - -* The following tools are installed on the build host: - -** link:https://www.docker.com/[Docker] version 18.09 or greater, supporting link:https://docs.docker.com/develop/develop-images/build_enhancements/[BuildKit] - -** link:https://git-scm.com[Git] - -** link:https://www.gnu.org/software/libc/manual/html_node/Getopt.html[GNU getopt] - -** link:https://www.gnu.org/software/wget/[GNU wget] - -** link:https://openjdk.java.net/projects/jdk/11/[Java Development Kit (JDK) version 11] - -** link:https://stedolan.github.io/jq/[jq] - - -.Procedure - -. Get a local copy of the link:https://github.com/che-incubator/jetbrains-editor-images[JetBrains Projector Editor Images repository]. -+ ----- -$ git clone https://github.com/che-incubator/jetbrains-editor-images -$ cd jetbrains-editor-images ----- - -. Run the build script and select the IDE package and package version: -+ ----- -$ ./projector.sh build -[info] Select the IDE package to build (default is 'IntelliJ IDEA Community'): - 1) IntelliJ IDEA Community - 2) PyCharm Community -[info] Select the IDE package version to build (default is '2020.3.3'): - 1) 2020.3.3 - 2) 2020.3.2 - 3) 2020.3.1 ----- - -. To test the image, run it locally and go to `++http://localhost:8887++` to access the IDE. -+ ----- -$ ./projector.sh run ----- - -. Publish the image to a registry accessible by {prod-short}, and remember the location: `__<registry>/<image>:<tag>__`. - -. Create a `+meta.yaml+` file with the following content: -+ -[source,yaml,subs="+quotes,macros,attributes"] ----- -apiVersion: v2 -publisher: __<publisher>__ <1> -name: intellij-ide -version: latest -type: Che Editor -displayName: IntelliJ Platform IDE -title: IDE based on the IntelliJ Platform -description: IDE based on the IntelliJ Platform running using Projector -icon: https://www.jetbrains.com/apple-touch-icon.png -category: Editor -repository: https://github.com/che-incubator/jetbrains-editor-images -firstPublicationDate: "2021-04-10" -spec: - endpoints: - - name: intellij - public: true - targetPort: 8887 - attributes: - protocol: http - type: ide - path: /projector-client/index.html?backgroundColor=434343&wss - containers: - - name: intellij-ide - image: __<registry>/<image>:<tag>__ <2> - mountSources: true - volumes: - - mountPath: "/home/projector-user" - name: projector-user - ports: - - exposedPort: 8887 - memoryLimit: "4096M" ----- -<1> `__<publisher>__`: Your publisher name. -<2> `__<registry>/<image>:<tag>__`: Location of the IDE image in a registry accessible by {prod-short}. - -. Publish the `meta.yaml` file to an HTTPS resource accessible by {prod-short} and copy the resulting URL for use as `__<URL_to_meta.yaml>__` when configuring a workspace to use this IDE. - -.Next steps - -* xref:configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc[] - diff --git a/modules/end-user-guide/partials/proc_changing-the-configuration-of-an-existing-workspace.adoc b/modules/end-user-guide/partials/proc_changing-the-configuration-of-an-existing-workspace.adoc deleted file mode 100644 index 525ea79de2..0000000000 --- a/modules/end-user-guide/partials/proc_changing-the-configuration-of-an-existing-workspace.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-code-sample (I didn't find it there, max-cx) - -[id="changing-the-configuration-of-an-existing-workspace_{context}"] -= Changing the configuration of an existing workspace - -This section describes how to change the configuration of an existing workspace from the user Dashboard. - -.Prerequisites - -* A running instance of {prod-short}. See {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -. Navigate to the {prod-short} Dashboard. See xref:navigating-che-using-the-dashboard.adoc[]. - -. In the left navigation panel, go to *Workspaces*. - -. Click the name of a workspace to navigate to the configuration overview page. - -. Click the *Overview* tab and execute following actions: - -** Change the *Workspace name*. - -** Select *Storage Type*. - -** Review *{orch-namespace}*. - -. From the *Devfile* tab, edit YAML configuration of the workspace. See xref:authoring-devfiles-version-2.adoc[]. \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_che-including-kubernetes-applications-in-a-workspace-devfile-definition.adoc b/modules/end-user-guide/partials/proc_che-including-kubernetes-applications-in-a-workspace-devfile-definition.adoc deleted file mode 100644 index c2a4409974..0000000000 --- a/modules/end-user-guide/partials/proc_che-including-kubernetes-applications-in-a-workspace-devfile-definition.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// importing-kubernetes-applications-into-a-workspace - -[id="including-kubernetes-applications-in-a-workspace-devfile-definition_{context}"] -= Including a {platforms-name} application in a workspace devfile definition - -This procedure describes how to define a {prod-short} workspace devfile to include a {orch-name} application. - -The devfile format is used to define a {prod-short} workspace, and its format is described in the xref:authoring-devfiles-version-2.adoc[] section. - -.Prerequisites - -* You are logged in to the cluster with a running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. - -* `{prod-cli}` management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. - - -.Procedure -// TO DO Supply URL for that file location - -. Create the simplest devfile: -+ -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: minimal-workspace <1> ----- -+ -<1> Only the name `minimal-workspace` is specified. After the {prod-short} server processes this devfile, the devfile is converted to a minimal {prod-short} workspace that only has the default editor (Che-Theia) and the default editor plug-ins, including, for example, the terminal. - -. To add {orch-name} applications to a workspace, modify the devfile and add the `{kubernetes}` component type. -+ -For example, to embed the NodeJS-Mongo application in the `minimal-workspace`: -+ -include::example$snip_including-kubernetes-applications-in-a-workspace-devfile-definition-nodejs-minimal.adoc[leveloffset=+1] -+ -<1> The `sleep infinity` command is added as the entrypoint of the Node.js application. The command prevents the application from starting at the workspace start phase. This configuration allows the user to start the application when needed for testing or debugging purposes. - -. Add the commands in the devfile to make it easier for a developer to test the application: -+ -include::example$snip_including-kubernetes-applications-in-a-workspace-devfile-definition-nodejs-minimal-added-commands.adoc[leveloffset=+1] -+ -<1> The `run` command added to the devfile is available as a task in Che-Theia from the command palette. When executed, the command starts the Node.js application. - -. Use the devfile to create and start a workspace: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} workspace:start --devfile __<devfile-path>__ ----- diff --git a/modules/end-user-guide/partials/proc_checking-yaml-language-server-feature-flags.adoc b/modules/end-user-guide/partials/proc_checking-yaml-language-server-feature-flags.adoc index 019e4cc286..e2564fd284 100644 --- a/modules/end-user-guide/partials/proc_checking-yaml-language-server-feature-flags.adoc +++ b/modules/end-user-guide/partials/proc_checking-yaml-language-server-feature-flags.adoc @@ -18,4 +18,4 @@ To check the feature flags: . Verify if there are any document symbols. If yes, the language server is connected to the editor. -. If any feature is not working, make sure that the settings listed above are set to `true` (they are set to `true` by default). If a feature is not working, file an issue against the link:https://github.com/redhat-developer/yaml-language-server[Language Server]. +. If any feature is not working, verify that the settings listed above are set to `true` (they are set to `true` by default). If a feature is not working, file an issue against the link:https://github.com/redhat-developer/yaml-language-server[Language Server]. diff --git a/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-a-custom-image-with-an-ide-based-on-the-intellij-platform.adoc b/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-a-custom-image-with-an-ide-based-on-the-intellij-platform.adoc deleted file mode 100644 index 3f5ff834dc..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-a-custom-image-with-an-ide-based-on-the-intellij-platform.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="configuring-a-workspace-to-use-a-custom-image-with-an-ide-based-on-the-intellij-platform_{context}"] -= Configuring a workspace to use a custom image with an IDE based on the IntelliJ Platform - -This section describes how to configure a workspace to use an IDE based on the IntelliJ Platform. - -.Prerequisites - -* {prod-short} has access to metadata and image with the desired IDE based on the IntelliJ Platform. See xref:building-images-for-ides-based-on-the-intellij-platform.adoc[]. - -.Procedure - -. Add the following component to the workspace devfile: -+ -[source,yaml,subs="+quotes,macros,attributes"] ----- -components: - - type: cheEditor - reference: "__<URL_to_meta.yaml>__" <1> ----- -+ -<1> `__<URL_to_meta.yaml>__`: HTTPS resource defining the IDE metadata, see xref:building-images-for-ides-based-on-the-intellij-platform.adoc[]. - -. Remove the plugins or commands defined for the Theia IDE from the workspace devfile. - -. Restart the workspace. - diff --git a/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-intellij-idea-community.adoc b/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-intellij-idea-community.adoc deleted file mode 100644 index 19af7e1342..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-intellij-idea-community.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="configuring-a-workspace-to-use-intellij-idea-community_{context}"] -= Configuring a workspace to use IntelliJ IDEA Community - -This section describes how to configure a workspace devfile to use IntelliJ IDEA Community. - -.Procedure - -. Add the following component to the workspace devfile: -+ -include::example$snip_{project-context}-configuring-a-workspace-to-use-intellij-idea-community.adoc[] - -. Remove the plugins or commands defined for the Theia IDE from the workspace devfile. - -. Restart the workspace. - diff --git a/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-pycharm-community.adoc b/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-pycharm-community.adoc deleted file mode 100644 index ca8cf6191d..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-pycharm-community.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="configuring-a-workspace-to-use-pycharm-community_{context}"] -= Configuring a workspace to use PyCharm Community - -This section describes how to configure a workspace devfile to use PyCharm Community. - -.Procedure - -. Add the following component to the workspace devfile: -+ -[source,yaml,subs="+quotes,macros,attributes"] ----- -components: - - type: cheEditor - reference: https://raw.githubusercontent.com/che-incubator/jetbrains-editor-images/meta/che-pycharm/latest.meta.yaml ----- - -. Remove the plugins or commands defined for the Theia IDE from the workspace devfile. - -. Restart the workspace. - diff --git a/modules/end-user-guide/partials/proc_configuring-global-gradle-repositories.adoc b/modules/end-user-guide/partials/proc_configuring-global-gradle-repositories.adoc deleted file mode 100644 index dd6f2a1670..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-global-gradle-repositories.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// using-gradle-artifact-repositories - -[id="configuring-global-gradle-repositories_{context}"] -= Configuring global Gradle repositories - -Use an initialization script to configure global repositories for the workspace. -Gradle performs extra configuration before projects are evaluated, and this configuration is used in each Gradle project from the workspace. - -.Procedure - -To set global repositories for Gradle that could be used in each Gradle project in the workspace, create an `init.gradle` script in the `~/.gradle/` directory: - -[source,groovy] ----- -allprojects { - repositories { - mavenLocal () - maven { - url "http://repo.mycompany.com/maven" - credentials { - username "admin" - password "my_password" - } - } - } -} ----- - -This file configures Gradle to use a local Maven repository with the given credentials. - -[NOTE] -==== -The `~/.gradle` directory does not persist in the current Java plug-in versions, so you must create the `init.gradle` script at each workspace start in the Java plug-in sidecar container. -==== diff --git a/modules/end-user-guide/partials/proc_configuring-go-to-use-a-non-standard-registry.adoc b/modules/end-user-guide/partials/proc_configuring-go-to-use-a-non-standard-registry.adoc deleted file mode 100644 index 517a4e40d7..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-go-to-use-a-non-standard-registry.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// using-go-artifact-repositories - -[id="configuring-go-to-use-a-non-standard-registry_{context}"] -= Configuring Go to use a non-standard-registry - -Athens is a Go module data store and proxy with many configuration options. It can be configured to act only as a module data store and not as a proxy. An administrator can upload their Go modules to the Athens data store and have them available across their Go projects. If a project tries to access a Go module that is not in the Athens data store, the Go build fails. - -* To work with Athens, configure the `GOPROXY` environment variable in the devfile of your CLI container: -+ -include::example${project-context}-go-configure-goproxy.adoc[] diff --git a/modules/end-user-guide/partials/proc_configuring-nuget-to-use-a-non-standard-registry.adoc b/modules/end-user-guide/partials/proc_configuring-nuget-to-use-a-non-standard-registry.adoc deleted file mode 100644 index 2bceb88903..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-nuget-to-use-a-non-standard-registry.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// using-nuget-artifact-repositories - -[id="configuring-nuget-to-use-a-non-standard-registry_{context}"] -= Configuring NuGet to use a non-standard artifact repository - -NuGet searches for configuration files anywhere between the solution directory and the driver root directory. If you put the `nuget.config` file in the `/projects` directory, the `nuget.config` file defines NuGet behavior for all projects in `/projects`. - -.Procedure - -* Create and place the `nuget.config` file in the `/projects` directory. -+ -.Example `nuget.config` with a Nexus repository hosted at `nexus.example.org`: -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<configuration> - <packageSources> - <add key="nexus2" value="https://nexus.example.org/repository/nuget-hosted/"/> - </packageSources> - <packageSourceCredentials> - <nexus2> - <add key="Username" value="user" /> - <add key="Password" value="..." /> - </nexus2> - </packageSourceCredentials> -</configuration> ----- diff --git a/modules/end-user-guide/partials/proc_configuring-python-to-use-a-non-standard-registry.adoc b/modules/end-user-guide/partials/proc_configuring-python-to-use-a-non-standard-registry.adoc deleted file mode 100644 index be3920a906..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-python-to-use-a-non-standard-registry.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// using-python-artifact-repositories - -[id="configuring-python-to-use-a-non-standard-registry_{context}"] -= Configuring Python to use a non-standard registry - -To specify a non-standard repository for use by the Python pip tool, set the `PIP_INDEX_URL` environment variable. - -.Procedure - -* In your devfile, configure the `PIP_INDEX_URL` environment variable for the language support and for the development container components: -+ -include::example${project-context}-python-configure-pip.adoc[] diff --git a/modules/end-user-guide/partials/proc_configuring-the-workspace-and-adding-tooling.adoc b/modules/end-user-guide/partials/proc_configuring-the-workspace-and-adding-tooling.adoc deleted file mode 100644 index 27c2ffba96..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-the-workspace-and-adding-tooling.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-with-dashboard - -[id="configuring-the-workspace-and-adding-tooling_{context}"] -= Configuring the workspace tools - -[id="adding-plug-ins_{context}"] -== Adding plug-ins - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -To add plug-ins to your workspace: - -. Click the *Devfile* tab. -. Add the desired `chePlugin` component and click the btn:[Save] button. -+ -NOTE: To see a list of available plugins, activate the completion feature by pressing kbd:[Ctrl+Space]. -+ -image::workspaces/workspace-add-plugin.png[] - -[id="defining-the-workspace-editor_{context}"] -== Defining the workspace editor - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -To define the editor to use with the workspace: - -. Click the *Devfile* tab. -. Add the desired `cheEditor` component and click the btn:[Save] button. -+ -NOTE: To see a list of available plugins, activate the completion feature by pressing kbd:[Ctrl+Space]. The recommended editor for {prod-short} {prod-ver} is Che-Theia. -+ -image::workspaces/workspace-add-editor.png[] - diff --git a/modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc b/modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc deleted file mode 100644 index d5c441bd93..0000000000 --- a/modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// authenticating-on-scm-server-with-a-personal-access-token - -[id="configuring_bitbucket_authentication_{context}"] - -= Authenticating on Bitbucket servers - -The following section describes the configuration needed to enables {prod-short} to use Bitbucket (BB) repositories with Git cloning operations. - -BB authentication is based on using personal access tokens. Each BB user is able to request several personal access tokens with different attributes, such as names, permissions, or expiration times. Those tokens can also be used to sign BB REST API calls and perform Git repository operations. - -* {prod-short} users may use public or private repositories on the BB Source Code Management (SCM) system as a source of their projects. - -NOTE: Before configuring the OAuth 1 authentication that is required for reading from private repositories and writing to both private and public repositories, configure the BB server with {prod-short} first. To do so, see the Prerequisites section below. - - -.Additional resources - -For a remote Git repository that uses a self-signed certificate, add an additional server configuration. See xref:installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]. - - -.Prerequisites - -* A BB endpoint has been registered with {prod-short}. Follow the xref:administration-guide:configuring-authorization#configuring_bitbucket_servers_{context}[Configuring Bitbucket servers] procedure and register a BB server using the `CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS` YAML secret property. - -.Procedure - -. Configure the OAuth 1 authentication by following the xref:administration-guide:configuring-authorization#proc_configuring-bitbucket-server-oauth1_{context}[Configuring Bitbucket Server OAuth 1] procedure. diff --git a/modules/end-user-guide/partials/proc_configuring_github_authentication.adoc b/modules/end-user-guide/partials/proc_configuring_github_authentication.adoc deleted file mode 100644 index 2c41cdb77d..0000000000 --- a/modules/end-user-guide/partials/proc_configuring_github_authentication.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// authenticating-on-scm-server-with-a-personal-access-token - -[id="configuring_github_authentication_{context}"] -= Authenticating on GitHub servers - -Configuring authentication on the GitHub system is similar to GitLab. - -GitHub authentication can be based on using personal access tokens. Each GitHub user is able to request several personal access tokens with different names, permissions, expiration times, and so on. Those tokens can be used to sign GitHub REST API calls and perform Git repository operations. - -To allow GitHub authentication on {prod-short} side, personal tokens must be stored in the user's {orch-namespace} in the form of -a secret. The secret must look as follows: - -.GitHub personal access token secret -==== -include::example$snip_github-personal-access-token-secret.adoc[] -==== - -The main parts of the secret are: - -[cols=3*] -|=== -| Label -| `app.kubernetes.io/component` -| Indicates it is an SCM personal token secret. - -| Annotation -| `che.eclipse.org/che-userid` -| {prod} id of the user token belongs to - -| Annotation -| `che.eclipse.org/scm-userid` -| GitHub user id to which token belongs - -| Annotation -| `che.eclipse.org/scm-username` -| GitHub username to which token belongs - -| Annotation -| `che.eclipse.org/scm-url` -| GitHub server URL to which this token belongs. Typically, it is `https://github.com` - -| Annotation -| `che.eclipse.org/expired-after` -| Personal access token expiration time - -| Data entry -| `token` -| Base-64 encoded value of the personal access token - -|=== - -NOTE: Encoding a string into the base64 format using the `base64` tool on Linux machines leads to adding the newline character to the end of the source string and causing a value to be unusable as the authentication header value after decoding. Avoid this by using `base64 -w0`, which removes newly added lines, or strip newlines explicitly using`tr -d \\n`. - -. To obtain a user ID from a secret, make a call to a REST API URL: -+ -[subs="+quotes,macros"] ----- -++https++://api.github.com/user ----- - -* For {prod-short} -+ -[subs="+macros,attributes"] ----- -{prod-url}/api/user ----- - -* With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories. - -* When a remote Git repository uses a self-signed certificate, add an additional server configuration. See: -xref:installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]. diff --git a/modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc b/modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc deleted file mode 100644 index 16f27c89df..0000000000 --- a/modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// authenticating-on-scm-server-with-a-personal-access-token - -[id="configuring_gitlab_authentication_{context}"] -= Authenticating on GitLab servers - -Configuring authentication on the GitLab system is similar to Bitbucket. - -GitLab authentication is based on using personal access tokens. Each GitLab user is able to request several personal access tokens with different names, permissions, expiration times, and so on. Those tokens can be used to sign GitLab REST API calls and perform Git repository operations. - -See the link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens[GitLab documentation] for more details about personal access tokens. - -To allow GitLab authentication on {prod-short} side, personal tokens must be stored in the user's {orch-namespace} in the form of -a secret. The secret must look as follows: - -.GitLab personal access token secret -==== -include::example$snip_gitlab-personal-access-token-secret.adoc[] -==== - -The main parts of the secret are: - -[cols=3*] -|=== -| Label -| `app.kubernetes.io/component` -| Indicates it is a SCM personal token secret. - -| Annotation -| `che.eclipse.org/che-userid` -| {prod} id of the user token belongs to - -| Annotation -| `che.eclipse.org/scm-userid` -| GitLab user id to which token belongs - -| Annotation -| `che.eclipse.org/scm-username` -| GitlLab user name to which token belongs - -| Annotation -| `che.eclipse.org/scm-url` -| GitLab server URL to which this token belong - -| Annotation -| `che.eclipse.org/expired-after` -| Personal access token expiration time - -| Data entry -| `token` -| Base-64 encoded value of the personal access token - -|=== - -NOTE: Encoding a string into the base64 format using the `base64` tool on Linux machines leads to adding the newline character to the end of the source string and causing a value to be unusable as the authentication header value after decoding. Avoid this by using `base64 -w0`, which removes newly added lines, or strip newlines explicitly using`tr -d \\n`. - -. To obtain a user ID from a secret, take a look into user profile page on GitLab web UI or make a call to a REST API URL: -* For GitLab: -+ -[subs="+quotes,macros"] ----- -++https++://__<gitlab-hostname>__/api/v4/users?username=__<username>__ ----- - -* For {prod-short} -+ -[subs="+macros,attributes"] ----- -{prod-url}/api/user ----- - -* With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories. - -* When a remote Git repository uses a self-signed certificate, add an additional server configuration. See: -xref:installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]. \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_creating-a-workspace-from-a-feature-branch-of-a-git-repository.adoc b/modules/end-user-guide/partials/proc_creating-a-workspace-from-a-feature-branch-of-a-git-repository.adoc deleted file mode 100644 index 7717650adc..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-workspace-from-a-feature-branch-of-a-git-repository.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-a-remote-devfile - -[id="creating-a-workspace-from-a-feature-branch-of-a-git-repository_{context}"] -= Creating a workspace from a feature branch of a Git repository - -A {prod-short} workspace can be created by pointing to devfile that is stored in a Git source repository on a feature branch of the user’s choice. The {prod-short} instance then uses the discovered devfile to build a workspace. - -.Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. -* The `devfile.yaml` or `.devfile.yaml` file is located in the root folder of a Git repository, on a specific branch of the user's choice that is accessible over HTTPS. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles. - -.Procedure -Execute the workspace by opening the following URL: `pass:c,a,q[{prod-url}/#__<GitHubBranch>__]` - -.Example -Use following URL format to open an experimental link:https://github.com/quarkusio/quarkus-quickstarts[quarkus-quickstarts] branch hosted on link:https://workspaces.openshift.com[workspaces.openshift.com]. - -[subs="+quotes"] ----- -https://workspaces.openshift.com/f?url=https://github.com/maxandersen/quarkus-quickstarts/tree/che ----- diff --git a/modules/end-user-guide/partials/proc_creating-a-workspace-from-the-default-branch-of-a-git-repository.adoc b/modules/end-user-guide/partials/proc_creating-a-workspace-from-the-default-branch-of-a-git-repository.adoc deleted file mode 100644 index c98fd16555..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-workspace-from-the-default-branch-of-a-git-repository.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-a-remote-devfile - -[id="creating-a-workspace-from-the-default-branch-of-a-git-repository_{context}"] -= Creating a workspace from the default branch of a Git repository - -This section describes how to start a {prod-short} workspace using a factory URL. The factory URL is a link pointing {prod-short} to a Git source repository containing a devfile. - -The factory URL exist in two forms: - -* the short form `/#$URL` -* long `/f?url=$URL` form that supports additional configuration parameters used in previous versions of {prod-short} - -.Prerequisites - -* A running instance of {prod}. See xref:installation-guide:installing-che.adoc[]. -* The Git repository __<GIT_REPOSITORY_URL>__ is available over HTTPS and contains a `devfile.yaml` or `.devfile.yaml` in the root folder. See xref:authoring-devfiles-version-2.adoc[]. - - -.Procedure - -pass:[<!-- vale CheDocs.TechnicalTerms = NO -->] - -* Run the workspace by opening the factory URL. Two formats are available: -+ -`pass:c,a,q[{prod-url}/#__<GIT_REPOSITORY_URL>__]`:: This is the short format. -`pass:c,a,q[{prod-url}/f?url=__<GIT_REPOSITORY_URL>__]`:: This long format supports additional configuration parameters. -+ -.Create a workspace on Eclipse Che hosted by Red Hat from the default branch of the `https://github.com/eclipse-che/che-server` repository using the short factory URL format. -[subs="+quotes"] -==== -link:https://workspaces.openshift.com/#https://github.com/eclipse-che/che-server[] -==== -+ -.Create a workspace on Eclipse Che hosted by Red Hat from the default branch of the `https://github.com/eclipse-che/che-server` repository using the long factory URL format. -[subs="+quotes"] -==== -link:https://workspaces.openshift.com/f?url=https://github.com/eclipse-che/che-server[] -==== - -pass:[<!-- vale CheDocs.TechnicalTerms = YES -->] \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard-quick-add.adoc b/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard-quick-add.adoc deleted file mode 100644 index e4e068f25b..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard-quick-add.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-code-sample - -[id="creating-a-workspace-from-quick-add-view-of-user-dashboard_{context}"] -= Creating a workspace from Quick Add of user dashboard - -This section describes how to create a workspace using the user dashboard and a code sample. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see xref:installation-guide:installing-che.adoc[]. - -.Procedure - -. Navigate to the {prod-short} dashboard. See xref:navigating-che-using-the-dashboard.adoc[]. - -. In the left navigation panel, go to *Create Workspace*. - -. Click the btn:[Quick Add] tab. -+ -The gallery lists sample projects to build and run. - -. To start a workspace, select a sample project from the set of pre-created devfiles. - - -[NOTE] -.A new workspace name -==== -Unless overridden, workspace names will be generated from the `metadata.generateName` property in the devfile, plus four random characters to ensure uniqueness. -==== diff --git a/modules/end-user-guide/partials/proc_creating-a-workspace-from-with-a-publicly-accessible-standalone-devfile-using-http.adoc b/modules/end-user-guide/partials/proc_creating-a-workspace-from-with-a-publicly-accessible-standalone-devfile-using-http.adoc deleted file mode 100644 index 4266f73bb1..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-workspace-from-with-a-publicly-accessible-standalone-devfile-using-http.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-a-remote-devfile - -[id="creating-a-workspace-from-a-publicly-accessible-standalone-devfile-using-http_{context}"] -= Creating a workspace from a publicly accessible standalone devfile using HTTP - -A workspace can be created using a devfile, the URL of which is pointing to the raw content of the devfile. The {prod-short} instance then uses the discovered devfile to build a workspace. - -.Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. -* The publicly-accessible standalone `devfile.yaml` file. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles. - -.Procedure -. Execute the workspace by opening the following URL: `pass:c,a,q[{prod-url}/#https://__<yourhosturl>__/devfile.yaml]` - -ifeval::["{project-context}" == "che"] -.Example -[subs="+quotes"] ----- -https://workspaces.openshift.com/f?url=https://github.com/eclipse/che-docs ----- -endif::[] diff --git a/modules/end-user-guide/partials/proc_creating-a-workspace-using-chectl-and-a-local-devfile.adoc b/modules/end-user-guide/partials/proc_creating-a-workspace-using-chectl-and-a-local-devfile.adoc deleted file mode 100644 index becd5b3472..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-workspace-using-chectl-and-a-local-devfile.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-using-a-devfile - -[id="creating-a-workspace-using-{prod-cli}-and-a-local-devfile_{context}"] -= Creating a workspace using {prod-cli} and a local devfile - -A {prod-short} workspace can be created by pointing the `{prod-cli}` tool to a locally stored devfile. The {prod-short} instance then uses the discovered devfile to build a workspace. - -.Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. -* The {prod-short} CLI management tool. See xref:overview:using-the-chectl-management-tool.adoc[]. -* The devfile is available on the local filesystem in the current working directory. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles. -* You are logged in to {prod}. See xref:end-user-guide:navigating-{prod-id-short}-using-the-dashboard.adoc#logging-in-to-{prod-id-short}-using-{prod-cli}_{context}[How to login into {prod-short} using {prod-cli}] - - -ifeval::["{project-context}" == "che"] -.Example -Download the `devfile.yaml` file from the link:https://raw.githubusercontent.com/eclipse-che/che-server/main/devfile.yaml[GitHub repository] to the current working directory. -endif::[] - - -.Procedure -. Run a workspace from a devfile using the `workspace:create` parameter with the `{prod-cli}` tool as follows: - -[subs="+attributes,+quotes"] ----- -$ {prod-cli} workspace:create --name=__<WORKSPACE_NAME>__ \ <1> ---devfile=devfile.yaml --start \ --n {prod-namespace} ----- -<1> The workspace name to create. - -NOTE: If `--devfile` flag is omitted, the {prod-cli} looks for `devfile.yaml` or `devfile.yml` files in the current directory to create a workspace from. - diff --git a/modules/end-user-guide/partials/proc_defining-a-launch-remote-plug-in-endpoint-in-a-meta-yaml-file.adoc b/modules/end-user-guide/partials/proc_defining-a-launch-remote-plug-in-endpoint-in-a-meta-yaml-file.adoc deleted file mode 100644 index 3349a377e7..0000000000 --- a/modules/end-user-guide/partials/proc_defining-a-launch-remote-plug-in-endpoint-in-a-meta-yaml-file.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// This module is included in -// -// remote-plug-in-endpoint - -[id="defining-a-launch-remote-plug-in-endpoint-in-a-meta-yaml-file_{context}"] -= Defining a `launch` remote plug-in endpoint in a `meta.yaml` file - -Use this method to re-use images for starting a remote plug-in endpoint without any modifications. - -.Procedure - -Modify the plug-in `meta.yaml` file properties `command` and `args`: - -* `command` - {prod2} uses the `command` properties to override the `Dockerfile#ENTRYPOINT` value. -* `args` - {prod2} uses uses the `args` properties to override the `Dockerfile#CMD` value. - - -* Example of a YAML file with the `command` and `args` properties modified: -+ -[source,yaml] ----- -apiVersion: v2 -category: Language -description: "Typescript language features" -displayName: Typescript -firstPublicationDate: "2019-10-28" -icon: "https://www.eclipse.org/che/images/logo-eclipseche.svg" -name: typescript -publisher: che-incubator -repository: "https://github.com/Microsoft/vscode" -title: "Typescript language features" -type: "VS Code extension" -version: remote-bin-with-override-entrypoint -spec: - containers: - - image: "example/fedora-for-ts-remote-plugin-without-endpoint:latest" - memoryLimit: 512Mi - name: vscode-typescript - command: - - sh - - -c - args: - - ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE} - extensions: - - "https://github.com/che-incubator/ms-code.typescript/releases/download/v1.35.1/che-typescript-language-1.35.1.vsix" ----- - -* Modify `args` instead of `command` to use an image with a wrapper script pattern and to keep a call of the `entrypoint.sh` script: -+ -[source,yaml] ----- -apiVersion: v2 -category: Language -description: "Typescript language features" -displayName: Typescript -firstPublicationDate: "2019-10-28" -icon: "https://www.eclipse.org/che/images/logo-eclipseche.svg" -name: typescript -publisher: che-incubator -repository: "https://github.com/Microsoft/vscode" -title: "Typescript language features" -type: "VS Code extension" -version: remote-bin-with-override-entrypoint -spec: - containers: - - image: "example/fedora-for-ts-remote-plugin-without-endpoint:latest" - memoryLimit: 512Mi - name: vscode-typescript - args: - - sh - - -c - - ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE} - extensions: - - "https://github.com/che-incubator/ms-code.typescript/releases/download/v1.35.1/che-typescript-language-1.35.1.vsix" ----- -+ -{prod} calls the `entrypoint.sh` wrapper script defined in the `ENTRYPOINT` command of the Dockerfile. The script executes `+[ ‘sh’, ‘-c”, ‘ ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}’ ]+` using the `exec “$@”` command. - -[NOTE] -==== -.By modifying the `command` and `args` properties of the `meta.yaml` file, a user can: - -* Execute a service at a container start - -* Start a remote plug-in endpoint - -.To make these actions run at the same time: - -. Start the service. - -. Detach the process. - -. Start the remote plug-in endpoint. -==== - diff --git a/modules/end-user-guide/partials/proc_defining-a-launch-remote-plug-in-endpoint-using-dockerfile.adoc b/modules/end-user-guide/partials/proc_defining-a-launch-remote-plug-in-endpoint-using-dockerfile.adoc deleted file mode 100644 index 570c62d909..0000000000 --- a/modules/end-user-guide/partials/proc_defining-a-launch-remote-plug-in-endpoint-using-dockerfile.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// This module is included in -// -// remote-plug-in-endpoint - -[id="defining-a-launch-remote-plug-in-endpoint-using-dockerfile_{context}"] -= Defining a `launch` remote plug-in endpoint using Dockerfile - -To start a remote plug-in endpoint, set the `+PLUGIN_REMOTE_ENDPOINT_EXECUTABLE+` environment variable in the Dockerfile. - -.Procedure - -* Start a remote plug-in endpoint using the `CMD` command in the Dockerfile: -+ -.Dockerfile example -[source,subs="+attributes"] ----- -FROM fedora:30 - -RUN dnf update -y && dnf install -y nodejs htop && node -v - -RUN mkdir {prod-home} - -ENV HOME={prod-home} - -RUN mkdir /projects \ - && chmod -R g+rwX /projects \ - && chmod -R g+rwX "$\{HOME}" - -CMD $\{PLUGIN_REMOTE_ENDPOINT_EXECUTABLE} ----- - -* Start a remote plug-in endpoint using the `ENTRYPOINT` command in the Dockerfile: -+ -.Dockerfile example -[source,subs="+attributes"] ----- -FROM fedora:30 - -RUN dnf update -y && dnf install -y nodejs htop && node -v - -RUN mkdir {prod-home} - -ENV HOME={prod-home} - -RUN mkdir /projects \ - && chmod -R g+rwX /projects \ - && chmod -R g+rwX "$\{HOME}" - -ENTRYPOINT $\{PLUGIN_REMOTE_ENDPOINT_EXECUTABLE} ----- - -== Using a wrapper script - -Some images use a wrapper script to configure permissions inside the container. The Dockertfile `ENTRYPOINT` command defines this script, which executes the main process defined in the `CMD` command of the Dockerfile. - -{prod2} uses images with a wrapper script to provide permission configurations to different infrastructures protected by advanced security. {OCP} is an example of such an infrastructure. - -* Example of a wrapper script: -+ -[source,bash] ----- -#!/bin/sh - -set -e - -export USER_ID=$(id -u) -export GROUP_ID=$(id -g) - -if ! whoami >/dev/null 2>&1; then - echo "${USER_NAME:-user}:x:${USER_ID}:0:${USER_NAME:-user} user:${HOME}:/bin/sh" >> /etc/passwd -fi - -# Grant access to projects volume in case of non root user with sudo rights -if [ "${USER_ID}" -ne 0 ] && command -v sudo >/dev/null 2>&1 && sudo -n true > /dev/null 2>&1; then - sudo chown "${USER_ID}:${GROUP_ID}" /projects -fi - -exec "$@" ----- - -* Example of a Dockerfile with a wrapper script: -+ -.Dockerfile example -[source] ----- -FROM alpine:3.10.2 - -ENV HOME=/home/theia - -RUN mkdir /projects ${HOME} && \ - # Change permissions to let any arbitrary user - for f in "${HOME}" "/etc/passwd" "/projects"; do \ - echo "Changing permissions on ${f}" && chgrp -R 0 ${f} && \ - chmod -R g+rwX ${f}; \ - done - -ADD entrypoint.sh /entrypoint.sh - -ENTRYPOINT [ "/entrypoint.sh" ] -CMD ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE} ----- -+ -==== -.Explanation: - -* The container launches the `/entrypoint.sh` script defined in the `ENTRYPOINT` command of the Dockerfile. - -* The script configures the permissions and executes the command using `exec $@`. - -* `CMD` is the argument for `ENTRYPOINT`, and the `exec $@` command calls `+${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}+`. - -* The remote plug-in endpoint then starts in the container after permission configuration. -==== \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_defining-maven-repositories-in-the-settings-xml-file.adoc b/modules/end-user-guide/partials/proc_defining-maven-repositories-in-the-settings-xml-file.adoc deleted file mode 100644 index 41705577c2..0000000000 --- a/modules/end-user-guide/partials/proc_defining-maven-repositories-in-the-settings-xml-file.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// using-maven-artifact-repositories - -[id="defining-repositories-in-settings-xml_{context}"] -= Defining repositories in `settings.xml` - -To specify your own artifact repositories at `example.server.org`, use the `settings.xml` file. -Ensure that `settings.xml` is in all the containers that use Maven tools. In particular, ensure that it is in the Maven container and the Java plug-in container. - -By default, `settings.xml` is located at the `__<home dir>__/.m2` directory which is already on persistent volume in Maven and Java plug-in containers and you don't need to re-create the file each time you restart the workspace if it isn't in ephemeral mode. - -In case you have another container that uses Maven tools and you are about to share `<home dir>/.m2` folder with this container, you have to specify the custom volume for this specific component in the devfile: - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -components: - - type: chePlugin - alias: maven-tool - id: plugin/id - volumes: - - name: m2 - containerPath: <home dir>/.m2 ----- - -.Procedure - -. Configure your `settings.xml` file to use artifact repositories at `example.server.org`: -+ -[source,xml] ----- -<settings> - <profiles> - <profile> - <id>my-nexus</id> - <pluginRepositories> - <pluginRepository> - <id>my-nexus-snapshots</id> - <releases> - <enabled>false</enabled> - </releases> - <snapshots> - <enabled>true</enabled> - </snapshots> - <url>http://example.server.org/repository/maven-snapshots/</url> - </pluginRepository> - <pluginRepository> - <id>my-nexus-releases</id> - <releases> - <enabled>true</enabled> - </releases> - <snapshots> - <enabled>false</enabled> - </snapshots> - <url>http://example.server.org/repository/maven-releases/</url> - </pluginRepository> - </pluginRepositories> - <repositories> - <repository> - <id>my-nexus-snapshots</id> - <releases> - <enabled>false</enabled> - </releases> - <snapshots> - <enabled>true</enabled> - </snapshots> - <url>http://example.server.org/repository/maven-snapshots/</url> - </repository> - <repository> - <id>my-nexus-releases</id> - <releases> - <enabled>true</enabled> - </releases> - <snapshots> - <enabled>false</enabled> - </snapshots> - <url>http://example.server.org/repository/maven-releases/</url> - </repository> - </repositories> - </profile> - </profiles> - <activeProfiles> - <activeProfile>my-nexus</activeProfile> - </activeProfiles> -</settings> ----- diff --git a/modules/end-user-guide/partials/proc_defining-maven-settings-xml-file-across-workspaces.adoc b/modules/end-user-guide/partials/proc_defining-maven-settings-xml-file-across-workspaces.adoc deleted file mode 100644 index ab83fa1aed..0000000000 --- a/modules/end-user-guide/partials/proc_defining-maven-settings-xml-file-across-workspaces.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// using-maven-artifact-repositories - -[id="proc_defining-maven-settings-xml-file-across-workspaces_{context}"] -= Defining Maven `settings.xml` file across workspaces - -To use your own `settings.xml` file across all your workspaces, create a Secret object (with a name of your choice) in the same {orch-namespace} as the workspace. Put the contents of the required `settings.xml` in the data section of the Secret (possibly along with other files that should reside in the same directory). Labelling and annotating this Secret according to xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container.adoc#mounting-a-secret-as-a-file-into-a-workspace-container_{context}[] ensures that the contents of the Secret is mounted into the workspace Pod. Note that you need to restart any previously running workspaces for them to use this Secret. - -.Prerequisites - -This is required to set your private credentials to a Maven repository. See the Maven documentation link:https://maven.apache.org/settings.html#servers[Settings.xml#Servers] for additional information. - -To mount this `settings.xml`: - -[source,xml] -<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 - https://maven.apache.org/xsd/settings-1.0.0.xsd"> - <servers> - <server> - <id>repository-id</id> - <username>username</username> - <password>password123</password> - </server> - </servers> -</settings> - -.Procedure - -. Convert `settings.xml` to base64: -+ ----- -$ cat settings.xml | base64 ----- - -. Copy the output to a new file, `secret.yaml`, which also defines needed annotations and labels: -+ - -[source,yaml,subs="+attributes"] ----- -apiVersion: v1 -kind: Secret -metadata: - name: maven-settings-secret - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: workspace-secret - annotations: - che.eclipse.org/automount-workspace-secret: "true" - che.eclipse.org/mount-path: {prod-home}/.m2 - che.eclipse.org/mount-as: file -type: Opaque -data: - settings.xml: PHNldHRpbmdzIHhtbG5zPSJodHRwOi8vbWF2ZW4uYXBhY2hlLm9yZy9TRVRUSU5HUy8xLjAuMCIKICAgICAgICAgIHhtbG5zOnhzaT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEtaW5zdGFuY2UiCiAgICAgICAgICB4c2k6c2NoZW1hTG9jYXRpb249Imh0dHA6Ly9tYXZlbi5hcGFjaGUub3JnL1NFVFRJTkdTLzEuMC4wCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGh0dHBzOi8vbWF2ZW4uYXBhY2hlLm9yZy94c2Qvc2V0dGluZ3MtMS4wLjAueHNkIj4KICA8c2VydmVycz4KICAgIDxzZXJ2ZXI+CiAgICAgIDxpZD5yZXBvc2l0b3J5LWlkPC9pZD4KICAgICAgPHVzZXJuYW1lPnVzZXJuYW1lPC91c2VybmFtZT4KICAgICAgPHBhc3N3b3JkPnBhc3N3b3JkMTIzPC9wYXNzd29yZD4KICAgIDwvc2VydmVyPgogIDwvc2VydmVycz4KPC9zZXR0aW5ncz4K ----- - -. Create this secret in the cluster: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} apply -f secret.yaml ----- - -. Start a new workspace. The `maven` container contains a file `{prod-home}/.m2/settings.xml` with your original content. - -== OpenShift 3.11 and {platforms-name} <1.13 - -On OpenShift 3.11 -ifeval::["{project-context}" == "che"] -and {kubernetes} versions older than 1.13 -endif::[] -, it's impossible to have multiple VolumeMounts at same path so having devfile with volume `{prod-home}/.m2` and secret at `{prod-home}/.m2/settings.xml` would resolve into the conflict. On these clusters use `{prod-home}/.m2/repository` as a volume for maven repository in the devfile: - -[source,yaml,subs="+attributes"] ----- -apiVersion: 1.0.0 -metadata: - ... -components: - - type: dockerimage - alias: maven - image: maven:3.11 - volumes: - - name: m2 - containerPath: {prod-home}/.m2/repository - ... ----- diff --git a/modules/end-user-guide/partials/proc_downloading-and-uploading-a-file-to-a-workspace-using-the-command-line-interface.adoc b/modules/end-user-guide/partials/proc_downloading-and-uploading-a-file-to-a-workspace-using-the-command-line-interface.adoc deleted file mode 100644 index 700f0d8ca4..0000000000 --- a/modules/end-user-guide/partials/proc_downloading-and-uploading-a-file-to-a-workspace-using-the-command-line-interface.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// remotely-accessing-workspaces - -[id="downloading-and-uploading-a-file-to-a-workspace-using-the-command-line-interface_{context}"] -= Downloading and uploading a file to a workspace using the command-line interface - -This procedure describes how to use the `{orch-cli}` tool to download or upload files remotely from or to an {prod-short} workspace. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. -* Remote access to the {prod-short} workspace you intend to modify. See xref:remotely-accessing-workspaces.adoc#accessing-workspaces-remotely-using-{orch-cli}_{context}[Remotely accessing workspaces]. - -* The `{orch-cli}`, version 1.5.0 or higher, is available. For information about installed version, use: -+ -[subs="+quotes,+attributes",options="+nowrap"] ----- -$ {orch-cli} version -Client Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0" - -... - ----- - -.Procedure - -The following procedure uses `{project-context}` as an example of a user {orch-namespace}. - -* To download a local file named `downloadme.txt` from a workspace container to the current home directory of the user, use the following in the {prod-short} remote shell. -+ -[subs="+quotes,+attributes",options="+nowrap"] ----- -$ REMOTE_FILE_PATH=/projects/downloadme.txt -$ NAMESPACE={project-context} -$ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4 -$ CONTAINER=maven -$ {orch-cli} cp $\{NAMESPACE}/$\{POD}:$\{REMOTE_FILE_PATH} ~/downloadme.txt -c $\{CONTAINER} ----- - -* To upload a local file named `uploadme.txt` to a workspace container in the `/projects` directory: - -[subs="+quotes,+attributes",options="+nowrap"] ----- -$ LOCAL_FILE_PATH=./uploadme.txt -$ NAMESPACE={project-context} -$ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4 -$ CONTAINER=maven -$ {orch-cli} cp $\{LOCAL_FILE_PATH} $\{NAMESPACE}/$\{POD}:/projects -c $\{CONTAINER} ----- - -Using the preceding steps, the user can also download and upload directories. - -// PUT AN EXAMPLE HERE? - -.Additional resources - -* For more about `{orch-cli}`, see the {orch-cli-link}. diff --git a/modules/end-user-guide/partials/proc_downloading-different-versions-of-gradle.adoc b/modules/end-user-guide/partials/proc_downloading-different-versions-of-gradle.adoc deleted file mode 100644 index ece6595efb..0000000000 --- a/modules/end-user-guide/partials/proc_downloading-different-versions-of-gradle.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="downloading-different-versions-of-gradle_{context}"] -= Downloading different versions of Gradle - -The recommended way to download any version of Gradle is by using the Gradle Wrapper script. If your project does not have a `gradle/wrapper` directory, run `$ gradle wrapper` to configure the Wrapper. - -.Prerequisites - -* The Gradle Wrapper is available in your project. - -.Procedure - -To download a Gradle version from a non-standard location, change your Wrapper settings in `/projects/<your_project>/gradle/wrapper/gradle-wrapper.properties`: - - * Change the `distributionUrl` property to point to a URL of the Gradle distribution `ZIP` file: -+ ----- -properties -distributionUrl=http://<url_to_gradle>/gradle-6.1-bin.zip ----- - -Alternatively, you may place a Gradle distribution zip file locally in `/project/gradle` in your workspace. - -* Change the `distributionUrl` property to point to a local address of the Gradle distribution zip file: -+ ----- -properties -distributionUrl=file\:/projects/gradle/gradle-6.1-bin.zip ----- diff --git a/modules/end-user-guide/partials/proc_editing-a-task-and-a-launch-configuration.adoc b/modules/end-user-guide/partials/proc_editing-a-task-and-a-launch-configuration.adoc deleted file mode 100644 index 1f552fb1d9..0000000000 --- a/modules/end-user-guide/partials/proc_editing-a-task-and-a-launch-configuration.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// defining-custom-commands-for-che-theia - -[id="editing-task-and-launch-configuration_{context}"] -= Editing a task and `launch` configuration - -.Procedure - -To customize the configuration file: - -. Edit the `tasks.json` or `launch.json` configuration files. -. Add new definitions to the configuration file or modify the existing ones. -+ -NOTE: The changes are stored in the configuration file. - -. To customize the task configuration provided by plug-ins, select the *Terminal* -> *Configure Tasks* menu option, and choose the task to configure. The configuration is then copied to the `tasks.json` file and is available for editing. diff --git a/modules/end-user-guide/partials/proc_editing-the-code-of-applications-running-in-openshift-container-platform-using-che.adoc b/modules/end-user-guide/partials/proc_editing-the-code-of-applications-running-in-openshift-container-platform-using-che.adoc index bae7faff93..f9fa34c4a8 100644 --- a/modules/end-user-guide/partials/proc_editing-the-code-of-applications-running-in-openshift-container-platform-using-che.adoc +++ b/modules/end-user-guide/partials/proc_editing-the-code-of-applications-running-in-openshift-container-platform-using-che.adoc @@ -22,6 +22,6 @@ This section describes how to start editing the source code of applications runn + The deployments are displayed as graphical circles surrounded by circular buttons. One of these buttons is *Edit Source Code*. + -image::installation/edit-source-code-button-che-odp.png[link="../_images/installation/edit-source-code-button-che-odp.png"] +image::installation/edit-source-code-button-che-odp.png[link="{imagesdir}/installation/edit-source-code-button-che-odp.png"] . To edit the code of an application using {prod-short}, click the *Edit Source Code* button. This redirects to a workspace with the cloned source code of the application component. diff --git a/modules/end-user-guide/partials/proc_enabling-xml-language-server-protocol-lsp-tracing.adoc b/modules/end-user-guide/partials/proc_enabling-xml-language-server-protocol-lsp-tracing.adoc index f2be6270c5..073584b2aa 100644 --- a/modules/end-user-guide/partials/proc_enabling-xml-language-server-protocol-lsp-tracing.adoc +++ b/modules/end-user-guide/partials/proc_enabling-xml-language-server-protocol-lsp-tracing.adoc @@ -5,4 +5,4 @@ .Procedure -To log LSP messages to the VS Code *Output* view, enable tracing by setting the `xml.trace.server` attribute to `verbose`. +To log LSP messages to the Visual Studio Code *Output* view, enable tracing by setting the `xml.trace.server` attribute to `verbose`. diff --git a/modules/end-user-guide/partials/proc_enabling-yaml-language-server-protocol-lsp-tracing.adoc b/modules/end-user-guide/partials/proc_enabling-yaml-language-server-protocol-lsp-tracing.adoc index cb8adb5be9..56a2cf771e 100644 --- a/modules/end-user-guide/partials/proc_enabling-yaml-language-server-protocol-lsp-tracing.adoc +++ b/modules/end-user-guide/partials/proc_enabling-yaml-language-server-protocol-lsp-tracing.adoc @@ -5,4 +5,4 @@ .Procedure -To log LSP messages to the VS Code *Output* view, enable tracing by setting the `yaml.trace.server` attribute to `verbose`. +To log LSP messages to the Visual Studio Code *Output* view, enable tracing by setting the `yaml.trace.server` attribute to `verbose`. diff --git a/modules/end-user-guide/partials/proc_finding-che-cluster-url-using-openshift-4-cli-tools.adoc b/modules/end-user-guide/partials/proc_finding-che-cluster-url-using-openshift-4-cli-tools.adoc deleted file mode 100644 index eeac5818d6..0000000000 --- a/modules/end-user-guide/partials/proc_finding-che-cluster-url-using-openshift-4-cli-tools.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-openshift-4-from-operatorhub - -[id="finding-{prod-id-short}-cluster-url-using-openshift-4-cli-tools_{context}"] -= Finding {prod-short} cluster URL using the OpenShift 4 CLI - -This section describes how to obtain the {prod-short} cluster URL using the OpenShift 4 command line interface (CLI). The URL can be retrieved from the OpenShift logs or from the `checluster` Custom Resource. - -.Prerequisites - -* An instance of {prod} running on OpenShift. -* User is located in a {prod-short} installation {orch-namespace}. - -.Procedure - -. To retrieve the {prod-short} cluster URL from the `checluster` CR (Custom Resource), run: -+ -[options="nowrap",role=white-space-pre] ----- -$ oc get checluster --output jsonpath='{.items[0].status.cheURL}' ----- - -. Alternatively, to retrieve the {prod-short} cluster URL from the OpenShift logs, run: -+ -[options="nowrap",role=white-space-pre] ----- -$ oc logs --tail=10 `(oc get pods -o name | grep operator)` | \ - grep "available at" | \ - awk -F'available at: ' '{print $2}' | sed 's/"//' ----- diff --git a/modules/end-user-guide/partials/proc_generating-a-devfile-from-an-existing-kubernetes-application.adoc b/modules/end-user-guide/partials/proc_generating-a-devfile-from-an-existing-kubernetes-application.adoc deleted file mode 100644 index 18f4c3ebb0..0000000000 --- a/modules/end-user-guide/partials/proc_generating-a-devfile-from-an-existing-kubernetes-application.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// importing-kubernetes-applications-into-a-workspace - - - -[id="generating-a-devfile-from-an-existing-kubernetes-application_{context}"] -= Generating a devfile from an existing {platforms-name} application - -This procedure demonstrates how to generate a devfile from an existing {platforms-name} application using the `{prod-cli}` tool. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* The `{prod-cli}` management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. - -* You are logged in to {prod-short}. See xref:end-user-guide:navigating-{prod-id-short}-using-the-dashboard.adoc#logging-in-to-{prod-id-short}-using-{prod-cli}_{context}[How to login into {prod-short} using {prod-cli}] - -.Procedure - -. To generate a devfile, use: -+ -[subs="+attributes"] ----- -$ {prod-cli} devfile:generate ----- - -* It is also possible to generate a devfile from, for example, the `NodeJS-MongoDB` application that includes the `NodeJS` component, using the `{prod-cli} devfile:generate` command: -+ -.Example: -+ -[subs="+attributes"] ----- -$ {prod-cli} devfile:generate --selector="app=nodejs" -apiVersion: 1.0.0 -metadata: - name: {prod-cli}-generated -components: - - type: kubernetes - alias: app=nodejs - referenceContent: | - kind: List - apiVersion: v1 - metadata: - name: app=nodejs - items: - - apiVersion: apps/v1 - kind: Deployment - metadata: - labels: - app: nodejs - name: web -(...) ----- -+ -The Node.js application YAML definition is available in the devfile, inline, using the `referenceContent` attribute. - -* To include support for a language, use the `--language` parameter: -+ -[subs="+attributes"] ----- -$ {prod-cli} devfile:generate --selector="app=nodejs" --language="typescript" -apiVersion: 1.0.0 -metadata: - name: {prod-cli}-generated -components: - - type: kubernetes - alias: app=nodejs - referenceContent: | - kind: List - apiVersion: v1 -(...) - - type: chePlugin - alias: typescript-ls - id: che-incubator/typescript/latest ----- - -. Use the generated devfile to start a {prod-short} workspace with `{prod-cli}`. -+ -[subs="+attributes"] ----- -$ {prod-cli} workspace:start --devfile=devfile​.yaml ----- diff --git a/modules/end-user-guide/partials/proc_generating-workspace-names.adoc b/modules/end-user-guide/partials/proc_generating-workspace-names.adoc deleted file mode 100644 index a822c60a59..0000000000 --- a/modules/end-user-guide/partials/proc_generating-workspace-names.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-using-a-devfile - -[id="generating-workspace-names_{context}"] -= Generating workspace names - -To specify a prefix for automatically generated workspace names, set the `generateName` parameter in the devfile: - -[source,yaml,subs="+attributes"] ----- -apiVersion: 1.0.0 -metadata: - generateName: {project-context}- ----- - -The workspace name will be in the `<generateName>YYYYY` format (for example, `che-2y7kp`). `Y` is random `[a-z0-9]` character. - -The following naming rules apply when creating workspaces: - -* When `name` is defined, it is used as the workspace name: `<name>` -* When only `generateName` is defined, it is used as the base of the generated name: `<generateName>YYYYY` - -[NOTE] -==== -For workspaces created using a factory, defining `name` or `generateName` has the same effect. The defined value is used as the name prefix: `<name>YYYYY` or `<generateName>YYYYY`. When both `generateName` and `name` are defined, `generateName` takes precedence. -==== diff --git a/modules/end-user-guide/partials/proc_importing-certificates-to-browsers.adoc b/modules/end-user-guide/partials/proc_importing-certificates-to-browsers.adoc deleted file mode 100644 index d03d6329c3..0000000000 --- a/modules/end-user-guide/partials/proc_importing-certificates-to-browsers.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-codeready-containers -// installing-{prod-id-short}-on-kind -// installing-{prod-id-short}-on-minikube -// installing-{prod-id-short}-on-minishift -// installing-{prod-id-short}-on-docker-desktop - -[id="importing-certificates-to-browsers_{context}"] -= Importing certificates to browsers - -This section describes how to import a root certificate authority into a web browser to use {prod-short} with self-signed TLS certificates. - -When a TLS certificate is not trusted, the error message *"Your {prod2} server may be using a self-signed certificate. To resolve the issue, import the server CA certificate in the browser."* blocks the login process. To prevent this, add the public part of the self-signed CA certificate into the browser after installing {prod-short}. - -== Adding certificates to Google Chrome on Linux or Windows - -.Procedure - -. Navigate to URL where {prod-short} is deployed. -. Save the certificate: -.. Click the warning or open lock icon on the left of the address bar. -.. Click *Certificates* and navigate to the *Details* tab. -.. Select the top-level certificate, which is the needed Root certificate authority (do not export the unfolded certificate from the lower level), and export it: -+ -* On Linux, click the btn:[Export] button. -* On Windows, click the btn:[Save to file] button. - -. Go to link:chrome://settings/certificates[Google Chrome Certificates settings] in the *Privacy and security* section and navigate to the *Authorities* tab. -. Click the btn:[Import] button and open the saved certificate file. -. Select *Trust this certificate for identifying websites* and click the btn:[OK] button. -. After adding the {prod-short} certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection. - - -== Adding certificates to Google Chrome on macOS - -.Procedure - -. Navigate to URL where {prod-short} is deployed. -. Save the certificate: -.. Click the lock icon on the left of the address bar. -.. Click *Certificates*. -.. Select the certificate to use and drag its displayed large icon to the desktop. -. Open the *Keychain Access* application. -. Select the *System* keychain and drag the saved certificate file to it. -. Double-click the imported CA, then go to *Trust* and select *When using this certificate*: *Always Trust*. -. Restart the browser for the added certificated to take effect. - - -== Adding certificates to Firefox - -.Procedure - -. Navigate to URL where {prod-short} is deployed. -. Save the certificate: -.. Click the lock icon on the left of the address bar. -.. Click the btn:[>] button next to the *Connection not secure* warning. -.. Click the btn:[More information] button. -.. Click the btn:[View Certificate] button on the *Security* tab. -.. Select the second certificate tab. The certificate Common Name should start with `ingress-operator` -.. Click the *PEM (cert)* link and save the certificate. -. Navigate to link:about:preferences[about:preferences], search for `certificates`, and click *View Certificates*. -. Go to the *Authorities* tab, click the btn:[Import] button, and open the saved certificate file. -. Check *Trust this CA to identify websites* and click btn:[OK]. -. Restart Firefox for the added certificated to take effect. -. After adding the {prod-short} certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection. diff --git a/modules/end-user-guide/partials/proc_importing-the-source-code-of-a-project-into-a-workspace.adoc b/modules/end-user-guide/partials/proc_importing-the-source-code-of-a-project-into-a-workspace.adoc deleted file mode 100644 index 0f302c280e..0000000000 --- a/modules/end-user-guide/partials/proc_importing-the-source-code-of-a-project-into-a-workspace.adoc +++ /dev/null @@ -1,187 +0,0 @@ - - -:parent-context-of-importing-the-source-code-of-a-project-into-a-workspace: {context} - -[id="importing-the-source-code-of-a-project-into-a-workspace_{context}"] -= Importing the source code of a project into a workspace - -:context: importing-the-source-code-of-a-project-into-a-workspace - -With {prod-short}, you can import and work on a project's current codebase in a workspace. - -You can import a project's codebase into a workspace by using any of the following options: - -* xref:creating-a-custom-workspace-from-the-dashboard_{context}[] -* xref:importing-from-the-dashboard-into-an-existing-workspace_{context}[] -* xref:importing-to-a-running-workspace-using-the-git-clone-command_{context}[] -* xref:importing-to-a-running-workspace-with-git-clone-in-a-terminal_{context}[] - -.Prerequisites - -* A running instance of {prod-short}. See xref:installation-guide:installing-che.adoc[]. - -* A configured workspace with plug-ins related to your development environment defined on this instance of {prod}. See xref:configuring-a-workspace-with-dashboard.adoc[]. -//Not sure how relevant this prerequisite is to any or all of the following cases. max-cx - -[id="creating-a-custom-workspace-from-the-dashboard_{context}"] -== Importing a project when creating a workspace - -You can import a project's codebase while creating a new workspace: by using a devfile template and the project's URL. - -.Procedure - -. Go to the xref:navigating-che-using-the-dashboard.adoc[Dashboard] of {prod-short}. - -. In the left navigation panel, click btn:[Create Workspace]. - -. Go to the *Custom Workspace* tab. - -. Enter a workspace name. -+ -[NOTE] -==== -If you do not enter a *Workspace Name* for your workspace, {prod-short} generates a unique name for a new workspace from the devfile's `metadata.generateName` property followed by four random characters. -==== - -. Select a devfile template from the drop-down list. -+ -image::workspaces/{project-context}-select-devfile.png[Select a devfile from the list] - -. Edit the `projects` section of the template devfile displayed in the devfile editor on the page. -+ -image::workspaces/devfile-projects.png[Edit the projects section of the devfile] -+ -.Editing the `projects` section of a devfile -==== -[source,yaml] ----- -projects: - - name: che - source: - type: git - location: 'https://github.com/eclipse-che/che-server.git' ----- -For more information about devfiles, see xref:authoring-devfiles-version-2.adoc[]. -==== - -. Click btn:[Create & Open]. - -. Wait for the initialized workspace to start and for the IDE to open. - -[id="importing-from-the-dashboard-into-an-existing-workspace_{context}"] -== Importing a project into a created workspace - -You can import a project's codebase into a created workspace by editing its devfile. - -.Prerequisites -* A running workspace - -.Procedure - -. Go to the xref:navigating-che-using-the-dashboard.adoc[Dashboard] of {prod-short}. - -. Under *RECENT WORKSPACES*, hover over the name of the workspace to which you will import the project. - -. Click the three dots. - -. Select *Edit Workspace*. - -. In the *Devfile* tab, edit the `projects` section of the devfile in the editor on the page. -+ -.Editing the `projects` section of a devfile -==== -[source,yaml] ----- -projects: - - name: che - source: - type: git - location: 'https://github.com/eclipse-che/che-server.git' ----- -For more information about devfiles, see xref:authoring-devfiles-version-2.adoc[]. -==== - -. Click btn:[Save]. - -[id="editing-the-commands-after-importing-a-project_{context}"] -=== Adding commands to an imported project -//Is this section only relevant as a subsection here or does it also apply to the other sections in this file? If the latter, consider promoting it to the next heading level. In any case, not checked by me, max-cx - -You can add commands to a project that will enable running, debugging, or starting an application in a browser. - -.Prerequisites - -* A workspace with a project in it - -.Procedure - -. Go to the xref:navigating-che-using-the-dashboard.adoc[Dashboard] of {prod-short}. - -. Under *RECENT WORKSPACES*, hover over the name of the workspace to which you will import the project. - -. Click the three dots next to the workspace name. - -. Select *Edit Workspace*. - -. In the *Devfile* tab, edit the `commands` section of the devfile in the editor on the page. - -. Click btn:[Save]. - -. Open the workspace. - -. To run a command, select *Terminal* > *Run Task* from the main menu. -+ -image::workspaces/run-command.png[Run task] - -. To configure commands, select *Terminal* > *Configure Tasks* from the main menu. -+ -image::workspaces/configure-command.png[Configure tasks] - - -[id="importing-to-a-running-workspace-using-the-git-clone-command_{context}"] -== Importing a project with *Git: Clone* in the GUI - -You can import a project's codebase into a running workspace with the *Git: Clone* command in the graphic user interface of {prod-short}. - -.Prerequisites -* A started workspace - -.Procedure - -. Select the *Git: Clone* command on the *Welcome* screen or from the command palette: -* On the *Welcome* screen, click the *Git: Clone* link. -+ -image::workspaces/{project-context}-welcome.png[Welcome screen] - -* To open the command palette, press F1 or kbd:[Ctrl+Shift+P] (kbd:[Cmd+Shift+P] on macOS). -+ -image::workspaces/git-clone-command.png[Invoke git clone command] - -. Enter the path to the project that you want to clone. -+ -image::workspaces/git-clone-command-2.png[Configure git clone command] - -[id="importing-to-a-running-workspace-with-git-clone-in-a-terminal_{context}"] -== Importing a project with `git clone` in a terminal - -You can use the command line to import a project's codebase into a running workspace. - -.Prerequisites -* A running workspace - -.Procedure - -. Open a terminal inside the running workspace. - -. Type the `git clone` command to pull code. -+ -image::workspaces/git-clone-terminal.png[Run git clone in a terminal] - -[NOTE] -==== -Importing or deleting workspace projects in the terminal does not update the workspace configuration, and the IDE does not reflect the changes in the *Devfile* tab in the dashboard. - -Similarly, when you add a project in the *Dashboard* and then delete the project with the `rm -fr myproject` command, the project may still appear in the *Devfile* tab. -==== - -:context: {parent-context-of-importing-the-source-code-of-a-project-into-a-workspace} diff --git a/modules/end-user-guide/partials/proc_investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc b/modules/end-user-guide/partials/proc_investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc deleted file mode 100644 index b502129f71..0000000000 --- a/modules/end-user-guide/partials/proc_investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// troubleshooting-che - -[id="investigating-failures-at-a-workspace-start-using-the-verbose-mode_{context}"] -= Investigating failures at a workspace start using the Verbose mode - -Verbose mode allows users to reach an enlarged log output, investigating failures at a workspace start. - -In addition to usual log entries, the Verbose mode also lists the container logs of each workspace. - - -[id="restarting-a-{prod-id-short}-workspace-in-verbose-mode-after-start-failure_{context}"] -== Restarting a {prod-short} workspace in Verbose mode after start failure - -This section describes how to restart a {prod-short} workspace in the Verbose mode after a failure during the workspace start. Dashboard proposes the restart of a workspace in the Verbose mode once the workspace fails at its start. - - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* An existing workspace that fails to start. - -.Procedure - -. Using Dashboard, try to start a workspace. -. When it fails to start, click on the displayed *Open in Verbose mode* link. -. Check the *Logs* tab to find a reason for the workspace failure. - - -[id="starting-a-{prod-id-short}-workspace-in-verbose-mode_{context}"] -== Starting a {prod-short} workspace in Verbose mode - -This section describes how to start the {prod} workspace in Verbose mode. - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. - -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -. Open the *Workspaces* tab. -. On the left side of a row dedicated to the workspace, access the drop-down menu displayed as three horizontal dots and select the *Open in Verbose mode* option. Alternatively, this option is also available in the workspace details, under the *Actions* drop-down menu. -. Check the *Logs* tab to find a reason for the workspace failure. diff --git a/modules/end-user-guide/partials/proc_logging-in-to-che-on-openshift-for-the-first-time-registering-as-a-new-user.adoc b/modules/end-user-guide/partials/proc_logging-in-to-che-on-openshift-for-the-first-time-registering-as-a-new-user.adoc deleted file mode 100644 index 5aaa73fa01..0000000000 --- a/modules/end-user-guide/partials/proc_logging-in-to-che-on-openshift-for-the-first-time-registering-as-a-new-user.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-openshift-4-from-operatorhub - -[id="logging-in-to-{prod-id-short}-on-openshift-for-the-first-time-registering-as-a-new-user_{context}"] -= Logging in to {prod-short} on OpenShift for the first time registering as a new user - -This section describes how to log in to {prod-short} on OpenShift for the first time registering as a new user. - -.Prerequisites - -* Contact the administrator of the OpenShift instance to obtain the *{prod} URL*. - -* Self-registration is enabled. See xref:administration-guide:configuring-authorization.adoc#enabling-self-registration_{context}[]. - -.Procedure - -. Navigate to the *{prod} URL* to display the {prod} login page. - -. Choose the *Register as a new user* option. - -. Update the account information: specify the `Username`, `Email`, `First name` and `Last name` field and click the btn:[Submit] button. - -.Validation steps - -* The browser displays the {prod} *Dashboard*. diff --git a/modules/end-user-guide/partials/proc_logging-in-to-che-on-openshift-for-the-first-time-using-oauth.adoc b/modules/end-user-guide/partials/proc_logging-in-to-che-on-openshift-for-the-first-time-using-oauth.adoc deleted file mode 100644 index a877aa9c70..0000000000 --- a/modules/end-user-guide/partials/proc_logging-in-to-che-on-openshift-for-the-first-time-using-oauth.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-openshift-4-from-operatorhub - -[id="logging-in-to-{prod-id-short}-on-openshift-for-the-first-time-using-oauth_{context}"] -= Logging in to {prod-short} on OpenShift for the first time using OAuth - -This section describes how to log in to {prod-short} on OpenShift for the first time using OAuth. - -.Prerequisites - -* Contact the administrator of the OpenShift instance to obtain the *{prod} URL*. - - -.Procedure - -. Navigate to the *{prod} URL* to display the {prod} login page. - -. Choose the *OpenShift OAuth* option. - -. The *Authorize Access* page is displayed. - -. Click on the btn:[Allow selected permissions] button. - -. Update the account information: specify the `Username`, `Email`, `First name` and `Last name` fields and click the btn:[Submit] button. - -.Validation steps - -* The browser displays the {prod} *Dashboard*. diff --git a/modules/end-user-guide/partials/proc_logging-in-to-che-server-using-cli.adoc b/modules/end-user-guide/partials/proc_logging-in-to-che-server-using-cli.adoc deleted file mode 100644 index ddedabcfe2..0000000000 --- a/modules/end-user-guide/partials/proc_logging-in-to-che-server-using-cli.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="logging-in-to-{prod-id-short}-using-{prod-cli}_{context}"] -= Logging in to {prod-short} using {prod-cli} - -This section describes how to log in to {prod-short} using the {prod-cli} tool by copying login command from {prod-short} Dashboard. - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. -* The {prod-short} CLI management tool. See xref:overview:using-the-chectl-management-tool.adoc[]. -* {prod} Dashboard is opened in a browser. - -.Procedure - -. Using the upper-right corner of Dashboard, open the user's pop-up menu. - -. Select the *Copy {prod-cli} login command* option. - -. Wait for the notification message `The login command copied to clipboard` to display. - -. Paste the login command into a terminal and observe a successful login: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} auth:login ... -Successfully logged into __<server>__ as __<user>__ ----- diff --git a/modules/end-user-guide/partials/proc_logging-the-client-server-traffic-for-debug-adapters.adoc b/modules/end-user-guide/partials/proc_logging-the-client-server-traffic-for-debug-adapters.adoc index b232229a8a..5130e7a0d8 100644 --- a/modules/end-user-guide/partials/proc_logging-the-client-server-traffic-for-debug-adapters.adoc +++ b/modules/end-user-guide/partials/proc_logging-the-client-server-traffic-for-debug-adapters.adoc @@ -20,7 +20,3 @@ This section describes how to log the exchange between Che-Theia and a debug ada All the communication events are logged. . To watch these events, click *View -> Output* and select *Debug adapters* from the drop-down list at the upper right corner of the *Output* view. -ifeval::["{project-context}" == "che"] -+ -image::logs/logging-the-client-server-traffic-for-debug-adapters.png[] -endif::[] \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_logging-the-java-language-server-protocol-lsp-messages.adoc b/modules/end-user-guide/partials/proc_logging-the-java-language-server-protocol-lsp-messages.adoc index 845cda4b91..a6692b6e98 100644 --- a/modules/end-user-guide/partials/proc_logging-the-java-language-server-protocol-lsp-messages.adoc +++ b/modules/end-user-guide/partials/proc_logging-the-java-language-server-protocol-lsp-messages.adoc @@ -5,8 +5,8 @@ .Procedure -To log the LSP messages to the VS Code *Output* view, enable tracing by setting the `java.trace.server` attribute to `verbose`. +To log the LSP messages to the Visual Studio Code *Output* view, enable tracing by setting the `java.trace.server` attribute to `verbose`. .Additional resources -For troubleshooting instructions, see the link:https://github.com/redhat-developer/vscode-java[VS Code Java GitHub repository]. +For troubleshooting instructions, see the link:https://github.com/redhat-developer/vscode-java[Visual Studio Code Java GitHub repository]. diff --git a/modules/end-user-guide/partials/proc_managing-git-configuration-identity.adoc b/modules/end-user-guide/partials/proc_managing-git-configuration-identity.adoc deleted file mode 100644 index ac6fa2e643..0000000000 --- a/modules/end-user-guide/partials/proc_managing-git-configuration-identity.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// version-control - -[id="managing-git-configuration-identity_{context}"] -= Managing Git configuration: identity - -The first thing to do before starting to use Git is to set a user name and email address. This is important because every Git commit uses this information. - -.Procedure - -* To configure Git identity using the {prod-short} user interface: -+ -. Open *File > Settings > Open Preferences* or press kbd:[Ctrl+,]. -+ -image::git/git-config-identity.png[Configuring Git identity,link="../_images/git/git-config-identity.png"] -+ -. In the opened window, navigate to the *Git -> User* sub-section and enter the User mail and User name values. - - -* To configure Git identity using the command line, open the terminal of the Che-Theia container. -+ -. Navigate to the *My Workspace* view, and open *Plugins > theia-ide > New terminal*: -+ -image::git/terminal-git-command.png[] -+ -. Execute the following commands: -+ ----- -$ git config --global user.name "John Doe" -$ git config --global user.email johndoe@example.com ----- - -Che-Theia permanently stores this information in the current container and restores it for other containers on future workspace starts. diff --git a/modules/end-user-guide/partials/proc_managing-pull-requests-using-the-github-pr-plug-in.adoc b/modules/end-user-guide/partials/proc_managing-pull-requests-using-the-github-pr-plug-in.adoc deleted file mode 100644 index a1583f25d1..0000000000 --- a/modules/end-user-guide/partials/proc_managing-pull-requests-using-the-github-pr-plug-in.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// version-control - -[id="managing-pull-requests-using-the-github-pr-plug-in_{context}"] -= Managing pull requests using the GitHub PR plug-in - -To manage GitHub pull requests, the VS Code GitHub Pull Request plug-in is available in the list of plug-ins of the workspace. - - -== Using the GitHub Pull Requests plug-in - -.Prerequisites - -* GitHub OAuth is configured. See xref:administration-guide:configuring-authorization#configuring-github-oauth_{context}[Configuring GitHub OAuth]. - -.Procedure - -* Sign in to GitHub, using the *Accounts* menu or the *Sign in* button in the plugin's view: -+ -image::git/github-sign-in-action.png[] - -To sign out from GitHub use the *Accounts* menu in the left bottom side, or *GitHub Pull Requests: Sign out of GitHub* command. - -.Additional resources - -* link:https://code.visualstudio.com/docs/editor/github#_pull-requests[vscode GitHub Pull Requests plugin documentation] diff --git a/modules/end-user-guide/partials/proc_mounting-a-git-credential-store-into-a-workspace-container.adoc b/modules/end-user-guide/partials/proc_mounting-a-git-credential-store-into-a-workspace-container.adoc deleted file mode 100644 index dd07c5010c..0000000000 --- a/modules/end-user-guide/partials/proc_mounting-a-git-credential-store-into-a-workspace-container.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// mounting-a-git-credential-store-into-a-workspace-container - -[id="mounting-a-git-credential-store-into-a-workspace-container_{context}"] -= Mounting a git credentials store into a workspace container - -This section describes how to mount git credentials store as secret from the user's {orch-namespace} into the file in single-workspace or multiple-workspace containers of {prod-short}. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -.Procedure -. Prepare git credential file in the link:https://git-scm.com/docs/git-credential-store#_storage_format[Storage format]. -. Encode content of the file to the base64 format. -. Create a new {platforms-name} secret in the {platforms-name} {orch-namespace} where a {prod-short} workspace will be created. - -* The labels of the secret that is about to be created must match the set of labels configured in `che.workspace.provision.secret.labels` property of {prod-short}. The default labels are: - -* `app.kubernetes.io/part-of: che.eclipse.org` -* `app.kubernetes.io/component: workspace-secret`: -+ -include::example${project-context}-ref_git-credential-file-as-kubernetes-secret-into-the-file.adoc[levelofset=+1] diff --git a/modules/end-user-guide/partials/proc_navigating-che-using-the-dashboard-on-minishift.adoc b/modules/end-user-guide/partials/proc_navigating-che-using-the-dashboard-on-minishift.adoc deleted file mode 100644 index ae9e9a16b3..0000000000 --- a/modules/end-user-guide/partials/proc_navigating-che-using-the-dashboard-on-minishift.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// navigating-{prod-id-short}-using-the-dashboard - -[id="navigating-{prod-id-short}-using-the-dashboard-on-minishift_{context}"] -= Navigating {prod-short} using the Dashboard on Minishift - -This section describes how to access the {prod} Dashboard on Minishift. - -.Prerequisites - -* {prod-short} deployed on a running Minishift instance. See xref:overview:running-che-locally.adoc[]. - -* Take note of the IP address of the Minishift console as displayed during Minishift startup. - -* Use the latest version of Google Chrome. Google Chrome is the officially supported browser for {prod} {prod-ver} - -.Procedure - -. Log into the Minishift console at `https://__<IP-address>__:8443/console/`. - -. Navigate to the *mini-che* project: `https://__<IP-address>__:8443/console/project/mini-che/overview`. - -. Click on to the mini-che route link: `++http://che-che.++__<IP-address>.__nip.io/`. - -.Validation steps - -* The browser displays the {prod} *Dashboard*. \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_overriding-devfile-values-using-factory-parameters.adoc b/modules/end-user-guide/partials/proc_overriding-devfile-values-using-factory-parameters.adoc deleted file mode 100644 index b50189acea..0000000000 --- a/modules/end-user-guide/partials/proc_overriding-devfile-values-using-factory-parameters.adoc +++ /dev/null @@ -1,163 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-a-remote-devfile - -[id="overriding-devfile-values-using-factory-parameters_{context}"] -= Overriding devfile values using factory parameters - -You can override values in the following sections of a remote devfile: - -* `apiVersion` -* `metadata` -* `projects` -* `attributes` - -You can override the values by using additional factory parameters. - -.Prerequisites - -* A running instance of {prod}. See xref:installation-guide:installing-che.adoc[]. -* A publicly accessible stand-alone `devfile.yaml` file. See xref:authoring-devfiles-version-2.adoc[] for information about creating and using devfiles. - -.Procedure - -. Open the workspace by navigating to the following URL: `pass:c,a,q[{prod-url}/f?url=https://__<hostURL>__/devfile.yaml&override.__<parameter.path>__=__<value>__]` - -.Example of overriding the `generateName` property - -==== -Consider the following initial devfile: - -[subs="+quotes"] ----- -apiVersion: 1.0.0 -metadata: - generateName: golang- -projects: -... ----- - -To add or override `generateName` value, use the following factory URL: - -[subs="+quotes"] ----- -https://workspaces.openshift.com/f?url=__<repository-url>__&override.metadata.generateName=myprefix ----- - -The resulting workspace has the following devfile model: - -[subs="+quotes"] ----- -apiVersion: 1.0.0 -metadata: - generateName: myprefix -projects: -... ----- -==== - -.Example of overriding project source branch property - -==== -Consider the following initial devfile: - -[subs="+quotes"] ----- -apiVersion: 1.0.0 -metadata: - generateName: java-mysql- -projects: - - name: web-java-spring-petclinic - source: - type: git - location: "https://github.com/spring-projects/spring-petclinic.git" -... ----- - -To add or override the source `branch` value, use the following factory URL: - -[subs="+quotes"] ----- -https://workspaces.openshift.com/f?url=__<repository-url>__&override.projects.web-java-spring-petclinic.source.branch=1.0.x ----- - -The resulting workspace has the following devfile model: - -[subs="+quotes"] ----- -apiVersion: 1.0.0 -metadata: - generateName: java-mysql- -projects: - - name: web-java-spring-petclinic - source: - type: git - location: "https://github.com/spring-projects/spring-petclinic.git" - branch: 1.0.x -... ----- -==== - - -.Example of overriding or creating an attribute value - -==== -Consider the following initial devfile: - -[subs="+quotes"] ----- -apiVersion: 1.0.0 -metadata: - generateName: golang- -attributes: - persistVolumes: false -projects: -... ----- - -To add or override the `persistVolumes` attribute value, use the following factory URL: - -[subs="+quotes"] ----- -https://workspaces.openshift.com/f?url=__<repository-url>__&override.attributes.persistVolumes=true ----- - - -The resulting workspace has the following devfile model: - -[subs="+quotes"] ----- ---- -apiVersion: 1.0.0 -metadata: - generateName: golang- -attributes: - persistVolumes: true -projects: -... ----- - -When overriding attributes, everything that follows the `attributes` keyword is interpreted as an attribute name. You can use dot-separated names: - -[subs="+quotes"] ----- -https://workspaces.openshift.com/f?url=__<repository-url>__&override.attributes.dot.name.format.attribute=true ----- - -The resulting workspace has the following devfile model: - -[subs="+quotes"] ----- -apiVersion: 1.0.0 -metadata: - generateName: golang- -attributes: - dot.name.format.attribute: true -projects: -... ----- -==== - -.Verification steps - -. In {prod-short} Dashboard, navigate to the *Devfile* tab of the newly created workspace and inspect the content. diff --git a/modules/end-user-guide/partials/proc_provisioning-the-jetbrains-offline-activation-code.adoc b/modules/end-user-guide/partials/proc_provisioning-the-jetbrains-offline-activation-code.adoc deleted file mode 100644 index d9bdfea363..0000000000 --- a/modules/end-user-guide/partials/proc_provisioning-the-jetbrains-offline-activation-code.adoc +++ /dev/null @@ -1,68 +0,0 @@ -[id="provisioning-the-jetbrains-offline-activation-code_{context}"] -= Provisioning the JetBrains offline activation code - -Some editions of JetBrains IDEs require a paid subscription beyond the evaluation period, which means buying a license from JetBrains. To register a license, you need to provision to {prod-short} the JetBrains activation code for offline usage. When you renew your subscription, you will need to generate and provision a new offline activation code. - -.Prerequisites - -* An active link:https://www.jetbrains.com/store/comparison.html[JetBrains subscription] associated to an active link:https://account.jetbrains.com/login[JetBrains account]. -* The link:https://www.openssl.org/[OpenSSL] and `{orch-cli}` tools are installed. -* An image containing the IDE. See xref:building-images-for-ides-based-on-the-intellij-platform.adoc[]. -* A workspace running with the IDE. See xref:configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc[]. - -.Procedure - -. Log in to your link:https://account.jetbrains.com/login[JetBrains account], choose the desired subscription, and click on the *Download activation code for offline usage* link. - -. Extract from the downloaded zip archive the file named `__<License{nbsp}ID>__{nbsp}-{nbsp}for{nbsp}2018.1{nbsp}or{nbsp}later.txt`. - -. Convert the activation code to a base64 encoded single line for use in the next step as `__<base64_encoded_activation_code>__`. -+ -[subs="+quotes,+attributes,+macros"] ----- -$ openssl base64 -e -A -in '__<License{nbsp}ID>__{nbsp}-{nbsp}for{nbsp}2018.1{nbsp}or{nbsp}later.txt' ----- - -. Create a `secret.yaml` file defining the {orch-name} Secret to provision the activation code to {prod-short}. -+ -[source,yaml,subs="+quotes,+attributes,+macros"] ----- -apiVersion: v1 -kind: Secret -metadata: - name: jetbrains-offline-activation-code - labels: - app.kubernetes.io/component: workspace-secret - app.kubernetes.io/part-of: che.eclipse.org - annotations: - che.eclipse.org/automount-workspace-secret: 'false' <1> - che.eclipse.org/mount-path: /tmp/ - che.eclipse.org/mount-as: file -data: - idea.key: __<base64_encoded_activation_code>__ - pycharm.key: __<base64_encoded_activation_code>__ - webstorm.key: __<base64_encoded_activation_code>__ - phpstorm.key: __<base64_encoded_activation_code>__ - goland.key: __<base64_encoded_activation_code>__ ----- -+ -<1> `+che.eclipse.org/automount-workspace-secret: 'false'+`: disables the mounting process until a workspace component explicitly requests it with the `+automountWorkspaceSecrets: true+` property. - -. Apply the {orch-name} Secret to the {orch-name} {orch-namespace} running the workspace. -+ -[subs="+quotes,+attributes,+macros"] ----- -$ {orch-cli} apply -f secret.yaml ----- - -. To mount the activation codes into a workspace, update the workspace devfile configuration to set `+automountWorkspaceSecrets: true+`. -+ -[source,yaml,subs="+quotes,+attributes,+macros"] ----- -components: - - type: cheEditor - automountWorkspaceSecrets: true - reference: "__<URL_to_meta.yaml>__" ----- - -. Restart the workspace. diff --git a/modules/end-user-guide/partials/proc_publishing-metadata-for-a-vs-code-extension.adoc b/modules/end-user-guide/partials/proc_publishing-metadata-for-a-vs-code-extension.adoc deleted file mode 100644 index f3a069b323..0000000000 --- a/modules/end-user-guide/partials/proc_publishing-metadata-for-a-vs-code-extension.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// publishing-a-vs-code-extension-into-the-{prod-id-short}-plug-in-registry - -[id="proc_publishing-metadata-for-a-vs-code-extension_{context}"] -= Publishing metadata for a VS Code extension - -To use a VS Code extension in a {prod-short} workspace, {prod-short} needs to consume metadata describing the extension. The {prod-short} plug-ins registry is a static website publishing metadata for common VS Code extensions. - -This article describes how to publish metadata for an additional extension, not available in the {prod-short} plug-ins registry, by using the extension configuration `meta.yaml` file. - -For details on adding a plugin to an existing plug-in registry, see xref:adding-a-vs-code-extension-to-the-che-plugin-registry.adoc[] - -.Prerequisite - -* If the VS Code extension requires it, the required associated container image is available. - -.Procedure - -. Create a `meta.yaml` file. - -. Edit the `meta.yaml` file and provide the necessary information. The file must have the following structure: -+ -[source,yaml] ----- -apiVersion: v2 <1> -publisher: myorg <2> -name: my-vscode-ext <3> -version: 1.7.2 <4> -type: value <5> -displayName: <6> -title: <7> -description: <8> -icon: https://www.eclipse.org/che/images/logo-eclipseche.svg <9> -repository: <10> -category: <11> -spec: - containers: <12> - - image: <13> - memoryLimit: <14> - memoryRequest: <15> - cpuLimit: <16> - cpuRequest: <17> - extensions: <18> - - https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix - - https://github.com/SonarSource/sonarlint-vscode/releases/download/1.16.0/sonarlint-vscode-1.16.0.vsix ----- -<1> Version of the file structure. -<2> Name of the plug-in publisher. Must be the same as the publisher in the path. -<3> Name of the plug-in. Must be the same as in path. -<4> Version of the plug-in. Must be the same as in path. -<5> Type of the plug-in. Possible values: `Che Plugin`, `Che Editor`, `Theia plugin`, `VS Code extension`. -<6> A short name of the plug-in. -<7> Title of the plug-in. -<8> A brief explanation of the plug-in and what it does. -<9> The link to the plug-in logo. -<10> Optional. The link to the source-code repository of the plug-in. -<11> Defines the category that this plug-in belongs to. Should be one of the following: `Editor`, `Debugger`, `Formatter`, `Language`, `Linter`, `Snippet`, `Theme`, or `Other`. -<12> If this section is omitted, the VS Code extension is added into the Che-Theia IDE container. -<13> The Docker image from which the sidecar container will be started. Example: `{theia-endpoint-image}`. -<14> The maximum RAM which is available for the sidecar container. Example: "512Mi". This value might be overridden by the user in the component configuration. -<15> The RAM which is given for the sidecar container by default. Example: "256Mi". This value might be overridden by the user in the component configuration. -<16> The maximum CPU amount in cores or millicores (suffixed with "m") which is available for the sidecar container. Examples: "500m", "2". This value might be overridden by the user in the component configuration. -<17> The CPU amount in cores or millicores (suffixed with "m") which is given for the sidecar container by default. Example: "125m". This value might be overridden by the user in the component configuration. -<18> A list of VS Code extensions run in this sidecar container. - -. Publish the `meta.yaml` file as an HTTP resource by creating a gist on GitHub or GitLab with a file content published there. \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-open-button.adoc b/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-open-button.adoc deleted file mode 100644 index 962f41cdf6..0000000000 --- a/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-open-button.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// running-an-existing-workspace-from-the-user-dashboard - -[id="running-an-existing-workspace-from-the-user-dashboard-with-the-open-button_{context}"] -= Running an existing workspace from the user dashboard using the Open button - -This section describes how to run an existing workspace from the user dashboard using the *Open* button. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -. Navigate to the {prod-short} Dashboard. See xref:navigating-che-using-the-dashboard.adoc[]. - -. In the left navigation panel, navigate to *Workspaces*. - -. Click on the name of a non-running workspace to navigate to the overview page. - -. Click on the btn:[Open] button in the top right corner of the page. -+ -The workspace is started, and a browser navigates to the workspace. diff --git a/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-recent-workspaces.adoc b/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-recent-workspaces.adoc deleted file mode 100644 index 338deb4a30..0000000000 --- a/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-recent-workspaces.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// running-an-existing-workspace-from-the-user-dashboard - -[id="running-an-existing-workspace-from-the-user-dashboard-usinng-the-recent-workspaces_{context}"] -= Running an existing workspace from the user dashboard using the Recent Workspaces - -This section describes how to run an existing workspace from the user dashboard using the Recent Workspaces. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -. Navigate to the {prod-short} Dashboard. See xref:navigating-che-using-the-dashboard.adoc[]. - -. In the left navigation panel, in the *Recent Workspaces* section, right-click the name of a non-running workspace and click *Run* in the contextual menu to start it. diff --git a/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-run-button.adoc b/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-run-button.adoc deleted file mode 100644 index 2638a82f11..0000000000 --- a/modules/end-user-guide/partials/proc_running-an-existing-workspace-from-the-user-dashboard-using-the-run-button.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// running-an-existing-workspace-from-the-user-dashboard - -[id="running-an-existing-workspace-from-the-user-dashboard-with-the-run-button_{context}"] -= Running an existing workspace from the user dashboard with the Run button - -This section describes how to run an existing workspace from the user dashboard using the *Run* button. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. -* An existing workspace defined on this instance of {prod-short}. - -.Procedure - -. Navigate to the {prod-short} Dashboard. See xref:navigating-che-using-the-dashboard.adoc[]. - -. In the left navigation panel, navigate to *Workspaces*. - -. Click on the name of a non-running workspace to navigate to the overview page. - -. Click on the btn:[Run] button in the top right corner of the page. -+ -The workspace is started, and a browser *does not* navigates to the workspace. diff --git a/modules/end-user-guide/partials/proc_running-and-debugging.adoc b/modules/end-user-guide/partials/proc_running-and-debugging.adoc deleted file mode 100644 index dc18df9a25..0000000000 --- a/modules/end-user-guide/partials/proc_running-and-debugging.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// defining-custom-commands-for-che-theia - -[id="running-and-debugging_{context}"] -= Running and debugging - -Che-Theia supports the link:https://microsoft.github.io/debug-adapter-protocol/[Debug Adapter Protocol]. This protocol defines a generic way for how a development tool can communicate with a debugger. It means Che-Theia works with all link:https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/[implementations]. - -.Prerequisites -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -pass:[<!-- vale Vale.Spelling = NO -->] - -pass:[<!-- vale Vale.Terms = NO -->] - -.Procedure -To debug an application: - -. Click *Debug* -> *Add Configuration* for debugging or adding of a `launch` configuration to the project. -+ -image::ide/che-theia-basics-1.png[] - -. From the pop-up menu, select the appropriate configuration for the application that you are about to debug. -+ -image::ide/che-theia-basics-2.png[] - -. Update the configuration by modifying or adding attributes. -+ -image::ide/che-theia-basics-3.png[] - -. Breakpoints can be toggled by selecting the editor margin. -+ -image::ide/che-theia-basics-3-b.png[] - -. After opening the breakpoint menu, use the *Edit Breakpoint* command to add conditions. -+ -image::ide/che-theia-basics-3-c.png[] -+ -The IDE then displays the `Expresion` input field. -+ -image::ide/che-theia-basics-3-d.png[] - -. To start debugging, click *View->Debug*. -+ -image::ide/che-theia-basics-4.png[] - -. In the *Debug* view, select the configuration and press *F5* to debug the application. Or, start the application without debugging by pressing btn:[Ctrl+F5]. -+ -image::ide/che-theia-basics-5.png[] - -pass:[<!-- vale Vale.Spelling = YES -->] - -pass:[<!-- vale Vale.Terms = YES -->] \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc b/modules/end-user-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc deleted file mode 100644 index 83d975bece..0000000000 --- a/modules/end-user-guide/partials/proc_testing-the-vs-code-extension-using-gist.adoc +++ /dev/null @@ -1,234 +0,0 @@ -// Module included in the following assemblies: -// -// assembly_testing-a-visual-studio-code-extension-in-che - -[id="testing-the-vs-code-extension-using-gist_{context}"] -= Testing a VS Code extension using GitHub gist - -Each workspace can have its own set of plug-ins. The list of plug-ins and the list of projects to clone are defined in the `devfile.yaml` file. - -For example, to enable an AsciiDoc plug-in from the {prod} dashboard, add the following snippet to the devfile: - -[source,yaml,subs="+quotes"] ----- -components: - - id: joaopinto/vscode-asciidoctor/latest - type: chePlugin ----- - -To add a plug-in that is not in the default plug-in registry, build a custom plug-in registry. See xref:administration-guide:customizing-the-registries.adoc[], or, alternatively, use GitHub and the gist service. - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - -* A GitHub account. - -.Procedure - -. Go to the link:https://gist.github.com/[gist] webpage and create a `README.md` file with the following description: `Try Bracket Pair Colorizer extension in {prod}` and content: `Example VS Code extension`. (link:https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer[Bracket Pair Colorizer] is a popular VS Code extension.) - -. Click the btn:[Create secret gist] button. - -. Clone the gist repository by using the URL from the navigation bar of the browser: -+ -[subs="+quotes"] ----- -$ git clone https://gist.github.com/__<your-github-username>__/__<gist-id>__ ----- -+ -.Example of the output of the `git clone` command -[subs="+quotes"] ----- -git clone https://gist.github.com/benoitf/85c60c8c439177ac50141d527729b9d9 <1> -Cloning into '85c60c8c439177ac50141d527729b9d9'... -remote: Enumerating objects: 3, done. -remote: Counting objects: 100% (3/3), done. -remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 -Unpacking objects: 100% (3/3), done. ----- -<1> Each gist has a unique ID. - -. Change the directory: -+ -[subs="+quotes"] ----- -$ cd _<gist-directory-name>_ <1> ----- -<1> Directory name matching the gist ID. - -. Download the plug-in from the link:https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer[VS Code marketplace] or from its link:https://github.com/CoenraadS/BracketPair/releases[GitHub page], and store the plug-in file in the cloned directory. - -. Create a `plugin.yaml` file in the cloned directory to add the definition of this plug-in. -+ -.Example of the `plugin.yaml` file referencing the `.vsix` binary file extension -+ -[source,yaml] ----- -apiVersion: v2 -publisher: CoenraadS -name: bracket-pair-colorizer -version: 1.0.61 -type: VS Code extension -displayName: Bracket Pair Colorizer -title: Bracket Pair Colorizer -description: Bracket Pair Colorizer -icon: https://raw.githubusercontent.com/redhat-developer/codeready-workspaces/crw-2-rhel-8/dependencies/che-plugin-registry/resources/images/default.svg?sanitize=true -repository: https://github.com/CoenraadS/BracketPair -category: Language -firstPublicationDate: '2020-07-30' -spec: <1> - extensions: - - "{{REPOSITORY}}/CoenraadS.bracket-pair-colorizer-1.0.61.vsix" <2> -latestUpdateDate: "2020-07-30" ----- -<1> This extension requires a basic Node.js runtime, so it is not necessary to add a custom runtime image in `plugin.yaml`. -<2> `{\{REPOSITORY}}` is a macro for a pre-commit hook. - -. Define a memory limit and volumes: -+ -[source,yaml,subs="+quotes"] ----- -spec: - containers: - - image: "quay.io/eclipse/che-sidecar-java:8-0cfbacb" - name: vscode-java - memoryLimit: "1500Mi" - volumes: - - mountPath: "/home/theia/.m2" - name: m2 ----- - -. Create a `devfile.yaml` that references the `plugin.yaml` file: -+ -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - generateName: java-maven- -projects: - - - name: console-java-simple - source: - type: git - location: "https://github.com/che-samples/console-java-simple.git" - branch: java1.11 -components: - - - type: chePlugin - id: redhat/java11/latest - - - type: chePlugin <1> - reference: "{{REPOSITORY}}/plugin.yaml" - - - type: dockerimage - alias: maven - image: quay.io/eclipse/che-java11-maven:nightly - memoryLimit: 512Mi - mountSources: true - volumes: - - name: m2 - containerPath: /home/user/.m2 -commands: - - - name: maven build - actions: - - - type: exec - component: maven - command: "mvn clean install" - workdir: ${CHE_PROJECTS_ROOT}/console-java-simple - - - name: maven build and run - actions: - - - type: exec - component: maven - command: "mvn clean install && java -jar ./target/*.jar" - workdir: ${CHE_PROJECTS_ROOT}/console-java-simple ----- -<1> Any other devfile definition is also accepted. The important information in this devfile are the lines defining this external component. It means that an external reference defines the plug-in and not an ID, which pointing to a definition in the default plug-in registry. - -. Verify there are 4 files in the current Git directory: -+ -[subs="+quotes"] ----- -$ ls -la -.git -CoenraadS.bracket-pair-colorizer-1.0.61.vsix -README.md -devfile.yaml -plugin.yaml ----- - -. Before committing the files, add a pre-commit hook to update the `{\{REPOSITORY}}` variable to the public external raw gist link: - -.. Create a `.git/hooks/pre-commit` file with this content: -+ -[source,sh] ----- -#!/bin/sh - -# get modified files -FILES=$(git diff --cached --name-only --diff-filter=ACMR "*.yaml" | sed 's| |\\ |g') - -# exit fast if no files found -[ -z "$FILES" ] && exit 0 - -# grab remote origin -origin=$(git config --get remote.origin.url) -url="${origin}/raw" - -# iterate on files and add the good prefix pattern -for FILE in ${FILES}; do - sed -e "s#{{REPOSITORY}}#${url}#g" "${FILE}" > "${FILE}.back" - mv "${FILE}.back" "${FILE}" -done - -# Add back to staging -echo "$FILES" | xargs git add - -exit 0 ----- -+ -The hook replaces the `{\{REPOSITORY}}` macro and adds the external raw link to the gist. - -.. Make the script executable: -+ -[subs="+quotes"] ----- -$ chmod u+x .git/hooks/pre-commit ----- - -. Commit and push the files: -+ -[subs="+quotes"] ----- -# Add files -$ git add * - -# Commit -$ git commit -m "Initial Commit for the test of our extension" -[main 98dd370] Initial Commit for the test of our extension - 3 files changed, 61 insertions(+) - create mode 100644 CoenraadS.bracket-pair-colorizer-1.0.61.vsix - create mode 100644 devfile.yaml - create mode 100644 plugin.yaml - -# and push the files to the main branch -$ git push origin ----- - -. Visit the gist website and verify that all links have the correct public URL and do not contain any `{\{REPOSITORY}}` variables. To reach the devfile: -+ -[subs="+quotes"] ----- -$ echo "$(git config --get remote.origin.url)/raw/devfile.yaml" ----- -+ -or: -+ -[subs="+quotes"] ----- -$ echo "https://__<che-server>__/#$(git config --get remote.origin.url)/raw/devfile.yaml" ----- diff --git a/modules/end-user-guide/partials/proc_troubleshooting-network-problems.adoc b/modules/end-user-guide/partials/proc_troubleshooting-network-problems.adoc deleted file mode 100644 index 3bf48ee49f..0000000000 --- a/modules/end-user-guide/partials/proc_troubleshooting-network-problems.adoc +++ /dev/null @@ -1,26 +0,0 @@ - -// Module included in the following assemblies: -// -// troubleshooting-che - -[id="troubleshooting-network-problems_{context}"] -= Troubleshooting network problems - -This section describes how to prevent or resolve issues related to network policies. -{prod-short} requires the availability of the WebSocket Secure (WSS) connections. -Secure WebSocket connections improve confidentiality and also reliability because they reduce the risk of interference by bad proxies. - -.Prerequisites - -* The WebSocket Secure (WSS) connections on port 443 must be available on the network. Firewall and proxy may need additional configuration. -* Use a supported web browser: -** Chrome -** Firefox - -.Procedure - -. Verify the browser supports the WebSocket protocol. See: link:https://www.google.com/search?q=websocket+test[Searching a websocket test]. - -. Verify firewalls settings: WebSocket Secure (WSS) connections on port 443 must be available. - -. Verify proxy servers settings: The proxy transmits and intercepts WebSocket Secure (WSS) connections on port 443. diff --git a/modules/end-user-guide/partials/proc_troubleshooting-slow-workspaces.adoc b/modules/end-user-guide/partials/proc_troubleshooting-slow-workspaces.adoc deleted file mode 100644 index 7139d8c92f..0000000000 --- a/modules/end-user-guide/partials/proc_troubleshooting-slow-workspaces.adoc +++ /dev/null @@ -1,126 +0,0 @@ - -// Module included in the following assemblies: -// -// troubleshooting-che - -[id="troubleshooting-slow-workspaces_{context}"] -= Troubleshooting slow workspaces - -Sometimes, workspaces can take a long time to start. Tuning can reduce this start time. Depending on the options, administrators or users can do the tuning. - -This section includes several tuning options for starting workspaces faster or improving workspace runtime performance. - -[id="improving-workspace-start-time_{context}"] -== Improving workspace start time - -Caching images with {image-puller-name-short}:: -+ -_Role: Administrator_ -+ -When starting a workspace, {orch-name} pulls the images from the registry. A workspace can include many containers meaning that {orch-name} pulls Pod's images (one per container). Depending on the size of the image and the bandwidth, it can take a long time. -+ -{image-puller-name-short} is a tool that can cache images on each of {orch-name} nodes. As such, pre-pulling images can improve start times. See xref:administration-guide:caching-images-for-faster-workspace-start.adoc[]. - -Choosing better storage type:: -+ -_Role: Administrator and user_ -+ -Every workspace has a shared volume attached. This volume stores the project files, so that when restarting a workspace, changes are still available. Depending on the storage, attach time can take up to a few minutes, and I/O can be slow. -+ -To avoid this problem, use ephemeral or asynchronous storage. See xref:installation-guide:configuring-storage-types.adoc[]. - -Installing offline:: -+ -_Role: Administrator_ -+ -Components of {prod-short} are OCI images. Set up {prod} in offline mode (air-gap scenario) to reduce any extra download at runtime because everything needs to be available from the beginning. See xref:installation-guide:installing-che-in-a-restricted-environment.adoc[]. - -Optimizing workspace plug-ins:: -+ -_Role: User_ -+ -When selecting various plug-ins, each plug-in can bring its own sidecar container, which is an OCI image. {orch-name} pulls the images of these sidecar containers. -+ -Reduce the number of plug-ins, or disable them to see if start time is faster. See also xref:administration-guide:caching-images-for-faster-workspace-start.adoc[]. - -Reducing the number of public endpoints:: -+ -_Role: Administrator_ -+ -For each endpoint, {orch-name} is creating {platforms-ingress} objects. Depending on the underlying configuration, this creation can be slow. -+ -To avoid this problem, reduce the exposure. For example, to automatically detect a new port listening inside containers and redirect traffic for the processes using a local IP address (`127.0.0.1`), the Che-Theia IDE plug-in has three optional routes. -+ -By reducing the number of endpoints and checking endpoints of all plug-ins, workspace start can be faster. - -CDN configuration:: -+ -The IDE editor uses a CDN (Content Delivery Network) to serve content. Check that the content uses a CDN to the client (or a local route for offline setup). -+ -To check that, open Developer Tools in the browser and check for `vendors` in the *Network* tab. `vendors.<random-id>.js` or `editor.main.*` should come from CDN URLs. - - -[id="improving-workspace-runtime-performance_{context}"] -== Improving workspace runtime performance - -Providing enough CPU resources:: -+ -Plug-ins consume CPU resources. For example, when a plug-in provides IntelliSense features, adding more CPU resources may lead to better performance. -+ -Ensure the CPU settings in the devfile definition, `devfile.yaml`, are correct: -+ -[source,yaml] ----- -apiVersion: 1.0.0 - -components: - - - type: chePlugin - id: id/of/plug-in - cpuLimit: 1360Mi <1> - cpuRequest: 100m <2> ----- -<1> Specifies the CPU limit for the plug-in. -<2> Specifies the CPU request for the plug-in. - -Providing enough memory:: -+ -Plug-ins consume CPU and memory resources. For example, when a plug-in provides IntelliSense features, collecting data can consume all the memory allocated to the container. -+ -Providing more memory to the plug-in can increase performance. Ensure about the correctness of memory settings: -+ -* in the plug-in definition - `meta.yaml` file -* in the devfile definition - `devfile.yaml` file -+ -[source,yaml] ----- -apiVersion: v2 - -spec: - containers: - - image: "quay.io/my-image" - name: "vscode-plugin" - memoryLimit: "512Mi" <1> - extensions: - - https://link.to/vsix ----- -<1> Specifies the memory limit for the plug-in. -+ -In the devfile definition (`devfile.yaml`): -+ -[source,yaml] ----- -apiVersion: 1.0.0 - -components: - - - type: chePlugin - id: id/of/plug-in - memoryLimit: 1048M <1> - memoryRequest: 256M ----- -<1> Specifies the memory limit for this plug-in. - -Choosing better storage type:: -+ -Use ephemeral or asynchronous storage for faster I/O. See xref:installation-guide:configuring-storage-types.adoc[]. diff --git a/modules/end-user-guide/partials/proc_using-a-badge-to-link-to-workspaces.adoc b/modules/end-user-guide/partials/proc_using-a-badge-to-link-to-workspaces.adoc deleted file mode 100644 index 262c95769b..0000000000 --- a/modules/end-user-guide/partials/proc_using-a-badge-to-link-to-workspaces.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="using-a-badge-to-link-to-workspaces_{context}"] -= Using a badge to link to workspaces - -It is common for code repositories to display badges in their `README` files that describe various aspects of the project, such as its test coverage, latest build status, link to documentation, and other things. For example, the {prod-short} GitHub `README` has the following badges: - -image::workspace_button/eclipse_che_badges.png[link="../_images/workspace_button/eclipse_che_badges.png"] - -To make the process of using {prod-short} easier, the following badge is available: image:https://www.eclipse.org/che/contribute.svg[Factory Badge] - -Use this badge and link it to a {prod-short} instance to quickly open a developer workspace. - - -== Including the developer workspace badge in a README - -.Procedure - -. To open a workspace in your {prod-short} installation, substitute your URL and repository: -+ ----- -[![Contribute](https://www.eclipse.org/che/contribute.svg)](https://your-che-host.com/f?url=https://your-repository-url) ----- - -. Add the link to your repository in the project `README` file. - -.Example: Using link:https://workspaces.openshift.com[workspaces.openshift.com] as the {prod-short} host and a GitHub repository - -The following snippet creates a badge that opens a developer workspace of the repository at `+https://github.com/org/repository+` in link:https://workspaces.openshift.com/[workspaces.openshift.com]: ----- -[![Contribute](https://www.eclipse.org/che/contribute.svg)](https://workspaces.openshift.com/f?url=https://github.com/org/repository) ----- - diff --git a/modules/end-user-guide/partials/proc_using-npm-artifact-repositories.adoc b/modules/end-user-guide/partials/proc_using-npm-artifact-repositories.adoc deleted file mode 100644 index 9cc249da0d..0000000000 --- a/modules/end-user-guide/partials/proc_using-npm-artifact-repositories.adoc +++ /dev/null @@ -1,44 +0,0 @@ - - -:parent-context-of-using-npm-artifact-repositories: {context} - -[id="using-npm-artifact-repositories_{context}"] -= Using npm artifact repositories - -:context: using-npm-artifact-repositories - -The npm (Node Package Manager) package manager for the JavaScript programming language is configured using the `npm config` command, by writing values to the `.npmrc` files. However, configuration values can also be set using the environment variables beginning with `NPM_CONFIG_`. - -The Typescript plug-in used in {prod} does not download any artifacts. It is enough to configure npm in the dev-machine component. - -Use the following environment variables for configuration: - -* The URL for the artifact repository: `NPM_CONFIG_REGISTRY` -* For using a certificate from a file: `NODE_EXTRA_CA_CERTS` - -Obtain a server certificate file from the repository server. It is customary for administrators to provide certificates of internal artifact servers as {orch-name} secrets (see xref:installation-guide:importing-untrusted-tls-certificates.adoc[]). The relevant server certificates will be mounted in `/public-certs` in every container in the workspace. - -. An example configuration for the use of an internal repository with a self-signed certificate: -+ -[source,yaml] ----- - - mountSources: true - endpoints: - - name: nodejs - port: 3000 - memoryLimit: '512Mi' - type: 'dockerimage' - alias: 'nodejs' - image: 'quay.io/eclipse/che-nodejs10-ubi:nightly' - env: - -name: NODE_EXTRA_CA_CERTS - value: '/public-certs/nexus.cer - - name: NPM_CONFIG_REGISTRY - value: 'https://snexus-airgap.apps.acme.com/repository/npm-proxy/' ----- - -// .Additional resources -// * link: -// * link: - -:context: {parent-context-of-using-npm-artifact-repositories} diff --git a/modules/end-user-guide/partials/proc_using-private-container-registries.adoc b/modules/end-user-guide/partials/proc_using-private-container-registries.adoc deleted file mode 100644 index 02fbabeae3..0000000000 --- a/modules/end-user-guide/partials/proc_using-private-container-registries.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="proc_using-private-container-registries_{context}"] -= Using private container registries - -[role="_abstract"] -This section describes the necessary steps to use container images from private container registries. - - -.Prerequisites - -* A running instance of {prod-short}. See xref:installation-guide:installing-che.adoc[]. - - -.Procedure - -. Navigate to the {prod-short} Dashboard. See xref:navigating-che-using-the-dashboard.adoc[]. - -. Navigate to *User Preferences*. - -.. Click on your username in the top right corner. - -.. Click the btn:[User Preferences] tab. - -. Click the btn:[Add Container Registry] button in btn:[Container Registries] tab and execute following actions: - -** Enter the container registry domain name in the *Registry* field. - -** Optionally, enter the username of your account at this registry in the *Username* field. - -** Enter the password in the *Password* field to authenticate in the container registry. - -. Click the btn:[Add] button. - - -.Verification - -. See that there is a new entry in the btn:[Container Registries] tab. - -. Create a workspace that uses a container image from the specified container registry. See xref:authoring-devfiles-version-2.adoc[]. - -.Additional resources - -* link:https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/[Kubernetes documentation: Pull an Image from a Private Registry] diff --git a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-go-projects.adoc b/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-go-projects.adoc deleted file mode 100644 index c3cd2fad51..0000000000 --- a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-go-projects.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// using-go-artifact-repositories - -[id="using-self-signed-certificates-in-go-projects_{context}"] -= Using self-signed certificates in Go projects - -Internal artifact repositories often do not have a self-signed TLS certificate signed by an authority that is trusted by default. They are typically signed by an internal company authority or are self-signed. Configure your tools to accept these certificates. - -Go uses certificates from a file defined in the `SSL_CERT_FILE` environment variable. - -.Procedure - -. Obtain the certificate used by the Athens server in the Privacy-Enhanced Mail (PEM) format. It is customary for administrators to provide certificates of internal artifact servers as {orch-name} secrets (see xref:installation-guide:importing-untrusted-tls-certificates.adoc[]). The relevant server certificates will be mounted in `/public-certs` in every container in the workspace. - -. Add the appropriate environment variables to your devfile: -+ -include::example${project-context}-go-use-self-signed-cert.adoc[] diff --git a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-gradle-projects.adoc b/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-gradle-projects.adoc deleted file mode 100644 index e465be502f..0000000000 --- a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-gradle-projects.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// using-gradle-artifact-repositories - -[id="using-self-signed-certificates-in-gradle-projects_{context}"] -= Using self-signed certificates in Gradle projects - -Internal artifact repositories often do not have a certificate signed by an authority that is trusted by default in Java. They are mainly signed by an internal company authority or are self-signed. Configure your tools to accept these certificates by adding them to the Java truststore. - -.Procedure - -. Obtain a server certificate file from the repository server. It is customary for administrators to provide certificates of internal artifact servers as {orch-name} secrets (see xref:installation-guide:importing-untrusted-tls-certificates.adoc[]). The relevant server certificates will be mounted in `/public-certs` in every container in the workspace. - -.. Copy the original Java truststore file: -+ ----- -$ mkdir /projects/maven -$ cp $JAVA_HOME/lib/security/cacerts /projects/maven/truststore.jks -$ chmod +w /projects/maven/truststore.jks ----- -+ -.. Import the certificate into the Java truststore file -+ ----- -$ keytool -import -noprompt -file /public-certs/nexus.cer -alias nexus -keystore /projects/maven/truststore.jks -storepass changeit -Certificate was added to keystore - ----- - -.. Upload the truststore file to `/projects/gradle/truststore.jks` to make it available for all containers. - -. Add the truststore file in the Gradle container. -+ -.. Add the `javax.net.ssl` system property to the `JAVA_OPTS` environment variable: -+ -[source,yaml] ----- - - mountSources: true - alias: maven - type: dockerimage - ... - env: - -name: JAVA_OPTS - value: >- - -Duser.home=/projects/gradle - -Djavax.net.ssl.trustStore=/projects/maven/truststore.jks - -Djavax.net.ssl.trustStorePassword=changeit ----- diff --git a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-maven-projects.adoc b/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-maven-projects.adoc deleted file mode 100644 index 95f08e9f88..0000000000 --- a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-maven-projects.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// using-maven-artifact-repositories - -[id="using-self-signed-certificates-in-maven-projects_{context}"] -= Using self-signed certificates in Maven projects - -Internal artifact repositories often do not have a certificate signed by an authority that is trusted by default in Java. They are mainly signed by an internal company authority or are self-signed. Configure your tools to accept these certificates by adding them to the Java truststore. - -.Procedure - -. Obtain a server certificate file from the repository server. It is customary for administrators to provide certificates of internal artifact servers as {orch-name} secrets (see xref:installation-guide:importing-untrusted-tls-certificates.adoc[]). The relevant server certificates will be mounted in `/public-certs` in every container in the workspace. - -.. Copy the original Java truststore file: -+ ----- -$ mkdir /projects/maven -$ cp $JAVA_HOME/lib/security/cacerts /projects/maven/truststore.jks -$ chmod +w /projects/maven/truststore.jks ----- -+ -.. Import the certificate into the Java truststore file -+ ----- -$ keytool -import -noprompt -file /public-certs/nexus.cer -alias nexus -keystore /projects/maven/truststore.jks -storepass changeit -Certificate was added to keystore - ----- -+ -. Add the truststore file. -+ -* In the Maven container: -+ -.. Add the `javax.net.ssl` system property to the `MAVEN_OPTS` environment variable: -+ -[source,yaml] ----- - - mountSources: true - alias: maven - type: dockerimage - ... - env: - -name: MAVEN_OPTS - value: >- - -Duser.home=/projects/maven -Djavax.net.ssl.trustStore=/projects/maven/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit ----- -+ -.. Restart the workspace. -+ -* In the Java plug-in container: -+ -In the devfile, add the `javax.net.ssl` system property for the Java language server: -+ -[source,yaml] ----- -components: - - id: redhat/java11/latest - type: chePlugin - preferences: - java.jdt.ls.vmargs: >- - -noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication - -Duser.home=/projects/maven - -Djavax.net.ssl.trustStore=/projects/maven/truststore.jks - -Djavax.net.ssl.trustStorePassword=changeit -... ----- diff --git a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-nuget-projects.adoc b/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-nuget-projects.adoc deleted file mode 100644 index 7205dc88d0..0000000000 --- a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-nuget-projects.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// using-nuget-artifact-repositories - -[id="using-self-signed-certificates-in-nuget-projects_{context}"] -= Using self-signed certificates in NuGet projects - -Internal artifact repositories often do not have a self-signed TLS certificate signed by an authority that is trusted by default. They are mainly signed by an internal company authority or are self-signed. Configure your tools to accept these certificates. - -.Procedure - -. Obtain the certificate used by the .NET server in the Privacy-Enhanced Mail (PEM) format. It is customary for administrators to provide certificates of internal artifact servers as {orch-name} secrets (see xref:installation-guide:importing-untrusted-tls-certificates.adoc[]). The relevant server certificates will be mounted in `/public-certs` in every container in the workspace. - -. Specify the location of the certificate file in the `SSL_CERT_FILE` environment variable in your devfile for the OmniSharp plug-in and for the .NET container. -+ -.Example of the devfile: -[source,yaml,subs="+attributes"] ----- -components: - - id: redhat-developer/che-omnisharp-plugin/latest - memoryLimit: 1024Mi - type: chePlugin - alias: omnisharp - env: - - value: /public-certs/nuget.cer - name: SSL_CERT_FILE - - mountSources: true - endpoints: - - name: 5000/tcp - port: 5000 - memoryLimit: 512Mi - type: dockerimage - volumes: - - name: dotnet - containerPath: {prod-home} - alias: dotnet - image: 'quay.io/eclipse/che-dotnet-2.2:7.7.1' - env: - - value: /projects/tls/rootCA.crt - name: SSL_CERT_FILE ----- diff --git a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-python-projects.adoc b/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-python-projects.adoc deleted file mode 100644 index c5fbb1fe3c..0000000000 --- a/modules/end-user-guide/partials/proc_using-self-signed-certificates-in-python-projects.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// using-python-artifact-repositories - -[id="using-self-signed-certificates-in-python-projects_{context}"] -= Using self-signed certificates in Python projects - -Internal artifact repositories often do not have a self-signed TLS certificate signed by an authority that is trusted by default. They are mainly signed by an internal company authority or are self-signed. Configure your tools to accept these certificates. - -Python uses certificates from a file defined in the `PIP_CERT` environment variable. - -.Procedure - -. Obtain the certificate used by the pip server in the Privacy-Enhanced Mail (PEM) format. It is customary for administrators to provide certificates of internal artifact servers as {orch-name} secrets (see xref:installation-guide:importing-untrusted-tls-certificates.adoc[]). The relevant server certificates will be mounted in `/public-certs` in every container in the workspace. -+ -[NOTE] -==== -pip accepts certificates in the Privacy-Enhanced Mail (PEM) format only. Convert the certificate to the PEM format using OpenSSL if necessary. -==== -+ -. Configure the devfile: -+ -include::example${project-context}-python-use-self-signed-cert.adoc[] diff --git a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-camel-language-server.adoc b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-camel-language-server.adoc index 0e72b681f3..1bf2871004 100644 --- a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-camel-language-server.adoc +++ b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-camel-language-server.adoc @@ -16,4 +16,4 @@ To verify the state of the language server: java -jar /tmp/vscode-unpacked/camel-tooling.vscode-apache-camel.latest.euqhbmepxd.camel-tooling.vscode-apache-camel-0.0.14.vsix/extension/jars/language-server.jar ---- -. If you cannot find it, see xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs]. +. If you cannot find it, see xref:viewing-che-workspaces-logs.adoc[]. diff --git a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-eclipse-jdt-language-server.adoc b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-eclipse-jdt-language-server.adoc index f578dfb4f8..784784ecc4 100644 --- a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-eclipse-jdt-language-server.adoc +++ b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-eclipse-jdt-language-server.adoc @@ -15,6 +15,6 @@ Check if the container that is running the Eclipse JDT Language Server plug-in i usr/lib/jvm/default-jvm/bin/java --add-modules=ALL-SYSTEM --add-opens java.base/java.util ---- + -This message also shows the VSCode Java extension used. If it is not running, the language server has not been started inside the container. +This message also shows the Visual Studio Code Java extension used. If it is not running, the language server has not been started inside the container. -. Check all logs described in xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs] +. Check all logs described in xref:viewing-che-workspaces-logs.adoc[]. diff --git a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-netcoredebugoutput-plug-in.adoc b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-netcoredebugoutput-plug-in.adoc index 635c1292fa..214e94f39d 100644 --- a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-netcoredebugoutput-plug-in.adoc +++ b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-netcoredebugoutput-plug-in.adoc @@ -23,5 +23,5 @@ ---- ==== -. Test the autocompletion feature within the braces of the `configuration` section of the `launch.json` file. If you can find `netcoredbg`, the Che-Theia plug-in is correctly initialized. If not, see xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs]. +. Test the autocompletion feature within the braces of the `configuration` section of the `launch.json` file. If you can find `netcoredbg`, the Che-Theia plug-in is correctly initialized. If not, see xref:viewing-che-workspaces-logs.adoc[]. diff --git a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-omnisharp-theia-plug-in-language-server.adoc b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-omnisharp-theia-plug-in-language-server.adoc index b322637d51..6259316157 100644 --- a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-omnisharp-theia-plug-in-language-server.adoc +++ b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-omnisharp-theia-plug-in-language-server.adoc @@ -12,4 +12,4 @@ To check if the container running the OmniSharp-Theia plug-in is running OmniSha /tmp/theia-unpacked/redhat-developer.che-omnisharp-plugin.0.0.1.zcpaqpczwb.omnisharp_theia_plugin.theia/server/omnisharp/OmniSharp.exe ---- -If the output is different, the language server has not started inside the container. Check the logs described in xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs]. +If the output is different, the language server has not started inside the container. Check the logs described in xref:viewing-che-workspaces-logs.adoc[]. diff --git a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-xml-language-server.adoc b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-xml-language-server.adoc index ba2132b2fc..2b1e8d1429 100644 --- a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-xml-language-server.adoc +++ b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-xml-language-server.adoc @@ -13,6 +13,6 @@ java ***/org.eclipse.ls4xml-uber.jar` ---- + -If is not, see the xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs] chapter. +If is not, see the xref:viewing-che-workspaces-logs.adoc[] chapter. // TODO: image::logs/verifying-the-state-of-the-xml-language-server.png[] diff --git a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-yaml-language-server.adoc b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-yaml-language-server.adoc index 2cb3e5f23c..e803e87f8d 100644 --- a/modules/end-user-guide/partials/proc_verifying-the-state-of-the-yaml-language-server.adoc +++ b/modules/end-user-guide/partials/proc_verifying-the-state-of-the-yaml-language-server.adoc @@ -15,4 +15,4 @@ Check if the container running the YAML plug-in is running the YAML language ser + image::logs/verifying-the-state-of-the-yaml-language-server.png[Verifying the state of the YAML language server] -The `node ********/server.js` running in the container indicates that the language server is running. If it is not running, the language server has not started inside the container. In this case, see xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs]. +The `node ********/server.js` running in the container indicates that the language server is running. If it is not running, the language server has not started inside the container. In this case, see xref:viewing-che-workspaces-logs.adoc[]. diff --git a/modules/end-user-guide/partials/proc_verifying-the-vs-code-extension-api-compatibility-level.adoc b/modules/end-user-guide/partials/proc_verifying-the-vs-code-extension-api-compatibility-level.adoc deleted file mode 100644 index df9f74edd3..0000000000 --- a/modules/end-user-guide/partials/proc_verifying-the-vs-code-extension-api-compatibility-level.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// using-a-visual-studio-code-extension-in-{prod-id-short} - -[id="verifying-the-vs-code-extension-api-compatibility-level_{context}"] -= Verifying the VS Code extension API compatibility level - -Che-Theia does not fully support the VS Code extensions API. The link:https://github.com/che-incubator/vscode-theia-comparator/[vscode-theia-comparator] is used to analyze the compatibility between the Che-Theia plug-in API and the VS Code extension API. This tool runs nightly, and the results are published on the link:https://che-incubator.github.io/vscode-theia-comparator/status.html[vscode-theia-comparator] GitHub page. - -.Prerequisites - -* Personal GitHub access token. See link:https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line[Creating a personal access token for the command line]. A GitHub access token is required to increase the GitHub download limit for your IP address. - -.Procedure - -To run the *vscode-theia comparator* manually: - -. Clone the link:https://github.com/che-incubator/vscode-theia-comparator/[vscode-theia-comparator] repository, and build it using the `yarn` command. - -. Set the `GITHUB_TOKEN` environment variable to your token. - -. Execute the `yarn run generate` command to generate a report. - -. Open the `out/status.html` file to view the report. diff --git a/modules/end-user-guide/partials/proc_viewing-camel-logs-in-the-output-panel.adoc b/modules/end-user-guide/partials/proc_viewing-camel-logs-in-the-output-panel.adoc index 25429c2032..ba0ed843b6 100644 --- a/modules/end-user-guide/partials/proc_viewing-camel-logs-in-the-output-panel.adoc +++ b/modules/end-user-guide/partials/proc_viewing-camel-logs-in-the-output-panel.adoc @@ -12,4 +12,4 @@ The Camel language server logs are printed in the *Output* channel named *Langua NOTE: The output channel is created only at the first created log entry on the client side. It may be absent when everything is going well. -image::logs/viewing-camel-logs-in-the-output-panel.png[link="../_images/logs/viewing-camel-logs-in-the-output-panel.png"] +image::logs/viewing-camel-logs-in-the-output-panel.png[link="{imagesdir}/logs/viewing-camel-logs-in-the-output-panel.png"] diff --git a/modules/end-user-guide/partials/proc_viewing-intelephense-events-in-the-output-panel.adoc b/modules/end-user-guide/partials/proc_viewing-intelephense-events-in-the-output-panel.adoc index 84648c381d..702ff453c8 100644 --- a/modules/end-user-guide/partials/proc_viewing-intelephense-events-in-the-output-panel.adoc +++ b/modules/end-user-guide/partials/proc_viewing-intelephense-events-in-the-output-panel.adoc @@ -10,7 +10,3 @@ This procedure describes how to view Intelephense events in the *Output* panel. . Click *View -> Output* . Select *Intelephense* in the drop-down list for the *Output* view. -ifeval::["{project-context}" == "che"] -+ -image::logs/viewing-intelephense-events-in-the-output-panel.png[] -endif::[] \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_viewing-logs-for-php-debug.adoc b/modules/end-user-guide/partials/proc_viewing-logs-for-php-debug.adoc index 654188c441..724e43992f 100644 --- a/modules/end-user-guide/partials/proc_viewing-logs-for-php-debug.adoc +++ b/modules/end-user-guide/partials/proc_viewing-logs-for-php-debug.adoc @@ -12,7 +12,3 @@ This procedure describes how to configure the PHP Debug plug-in to log the PHP D . Start the debug session. . The diagnostic messages are printed into the *Debug Console* view along with the application output. -ifeval::["{project-context}" == "che"] -+ -image::logs/viewing-logs-for-php-debug.png[] -endif::[] \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_writing-a-devfile-for-your-project.adoc b/modules/end-user-guide/partials/proc_writing-a-devfile-for-your-project.adoc deleted file mode 100644 index 3fc6b49e48..0000000000 --- a/modules/end-user-guide/partials/proc_writing-a-devfile-for-your-project.adoc +++ /dev/null @@ -1,102 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-using-a-devfile - -[id="writing-a-devfile-for-your-project_{context}"] -= Writing a devfile for a project - -This section describes how to create a minimal devfile for your project and how to include more than one projects in a devfile. - -[id="preparing-a-minimal-devfile_{context}"] -== Preparing a minimal devfile - -A minimal devfile sufficient to run a workspace consists of the following parts: - -* Specification version -* Name - -.Example of a minimal devfile with no project -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: minimal-workspace ----- - -Without any further configuration, a workspace with the default editor is launched along with its default plug-ins, which are configured on the {prod-short} Server. Che-Theia is configured as the default editor along with the *{prod-short} Machine Exec* plug-in. When launching a workspace within a Git repository using a factory, the project from the given repository and branch is be created by default. The project name then matches the repository name. - -Add the following parts for a more functional workspace: - -* List of components: Development components and user runtimes -* List of projects: Source code repositories -* List of commands: Actions to manage the workspace components, such as running the development tools, starting the runtime environments, and others - -.Example of a minimal devfile with a project -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: petclinic-dev-environment -projects: - - name: petclinic - source: - type: git - location: 'https://github.com/spring-projects/spring-petclinic.git' -components: - - type: chePlugin - id: redhat/java/latest ----- - - -[id="specifying-multiple-projects-in-a-devfile_{context}"] -== Specifying multiple projects in a devfile - -A single devfile can define multiple projects, which are cloned to the desired destination. These projects are created inside a user’s workspace after the workspace is started. - -For each project, specify the following: - -* The type of the source repository - this can be .git or .zip. For additional information, see the xref:devfile-reference_{context}[Devfile reference] section. - -* The location of the source repository - an URL to a Git repository or zip archive. - -* Optionally, the directory to which the project is cloned. If none is specified, the default directory is used, which is a directory that matches the project name or project Git repository. - - - -.Example of a devfile with two projects - -In the following example, the projects `frontend` and `backend` act as examples of a user's projects. Each project is located in a separate repository. - -* The `backend` project has a specific requirement to be cloned into the `src/github.com/__<github-organization>__/__<backend>__/` directory under the source root, implicitly defined by the {prod-short} runtime. - -* The `frontend` project will be cloned into the `__<frontend/>__` directory under the source root. - -[source,yaml,subs="+quotes"] ----- -apiVersion: 1.0.0 -metadata: - name: example-devfile -projects: -- name: __<frontend>__ - source: - type: git - location: https://github.com/__<github-organization>__/__<frontend>__.git -- name: __<backend>__ - clonePath: src/github.com/__<github-organization>__/__<backend>__ - source: - type: git - location: https://github.com/__<github-organization>__/__<backend>__.git ----- - - -.Additional resources - -For a detailed explanation of all devfile component assignments and possible values, see: - -* link:https://github.com/redhat-developer/devfile[Specification repository] -* link:https://redhat-developer.github.io/devfile/devfile[Detailed json-schema documentation] - -These sample devfiles are a good source of inspiration: - -* link:https://github.com/eclipse-che/che-devfile-registry/tree/master/devfiles[Sample devfiles for {prod} workspaces used by default in the user interface]. -* link:https://github.com/redhat-developer/devfile/tree/main/samples[Sample devfiles for {prod} workspaces from Red Hat Developer program]. diff --git a/modules/end-user-guide/partials/ref_che-theia-plug-in-metadata.adoc b/modules/end-user-guide/partials/ref_che-theia-plug-in-metadata.adoc deleted file mode 100644 index f4be37edbf..0000000000 --- a/modules/end-user-guide/partials/ref_che-theia-plug-in-metadata.adoc +++ /dev/null @@ -1,199 +0,0 @@ -pass:[<!-- vale Vale.Spelling = NO -->] - -pass:[<!-- vale Vale.Terms = NO -->] - -pass:[<!-- vale IBM.Usage = NO -->] - -pass:[<!-- vale IBM.PassiveVoice = NO -->] - -pass:[<!-- vale IBM.Slash = NO -->] - -// This assembly is included in the following assemblies: -// -// what-is-a-che-theia-plug-in - -[id="che-theia-plug-in-metadata_{context}"] -= Che-Theia plug-in metadata - -Che-Theia plug-in metadata is information about individual plug-ins for the plug-in registry. - -The Che-Theia plug-in metadata, for each specific plug-in, is defined in a `meta.yaml` file. These files can be referenced in a devfile to include Che-Theia plug-ins in a workspace. - -Here is an overview of all fields that can be available in plug-in meta YAML files. This document represents the link:https://github.com/eclipse-che/che-plugin-registry#user-content-plugin-meta-yaml-structure[plugin meta YAML structure (version 3)]. - -ifeval::["{project-context}" == "che"] -In the link:https://github.com/eclipse-che/che-plugin-registry[{prod-short} plug-ins registry repository], the `che-theia-plugins.yaml` file contains a list of all Che-Theia plug-ins in the registry. Build the registry container image to generate the `meta.yaml` file. -endif::[] - -.`meta.yml` -|=== -|`apiVersion`| Version 2 and higher where version is 1 supported for backwards compatibility -|`category`| Available: Category must be set to one of the followings: `Editor`, `Debugger`, `Formatter`, `Language`, `Linter`, `Snippet`, `Theme`, `Other` -|`description`| Short description of the plug-in purpose -|`displayName`| Name shown in user dashboard -|`deprecate` | Optional; section for deprecating plug-ins in favor of others - - * autoMigrate - boolean - - * migrateTo - new `org/plugin-id/version`, for example `redhat/vscode-apache-camel/latest` -|`firstPublicationDate`| Not required to be in YAML; if it is not included, the plug-in registry `dockerimage` build generates it -|`latestUpdateDate`| Not required to be in YAML; if it is not included, the plug-in registry `dockerimage` build generates it -|`icon`| URL of an SVG or PNG icon -|`name`| Name (no spaces allowed), must match [-a-z0-9] -|`publisher`| Name of the publisher, must match [-a-z0-9] -|`repository`| URL for plug-in repository, for example, GitHub -|`title`| Plug-in title (long) -|`type`| `Che Plugin`, `VS Code extension` -|`version`| Version information, for example: 7.5.1, [-.a-z0-9] -|`spec`| Specifications (see below) -|=== - -.`spec` attributes -|=== -|`endpoints` | Optional; plug-in endpoint -|`containers`| Optional; sidecar containers for the plug-in. Che Plug-in and VS Code extension supports only one container -|`initContainers`| Optional; sidecar init containers for the plug-in -|`workspaceEnv`| Optional; environment variables for the workspace -|`extensions`| Optional; Attribute that is required for VS Code and Che-Theia plug-ins in a form list of URLs to plug-in artefacts, such as .vsix or .theia files -|=== - -.`spec.containers`. Notice: `spec.initContainers` has absolutely the same container definition. -|=== -|`name` | Sidecar container name -|`image` | Absolute or relative container image URL -|`memoryLimit` | OpenShift memory limit string, for example `512Mi` -|`memoryRequest` | OpenShift memory request string, for example `512Mi` -|`cpuLimit` | OpenShift CPU limit string, for example `2500m` -|`cpuRequest` | OpenShift CPU request string, for example `125m` -|`env` | List of environment variables to set in the sidecar -|`command` | String array definition of the root process command in the container -|`args` | String array arguments for the root process command in the container -|`volumes` | Volumes required by the plug-in -|`ports` | Ports exposed by the plug-in (on the container) -|`commands` | Development commands available to the plug-in container -|`mountSources` | Boolean flag to bound volume with source code `/projects` to the plug-in container -|`initContainers` | Optional; init containers for sidecar plug-in -|`Lifecycle` | Container lifecycle hooks. See link:https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/[`lifecycle` description] -|=== - -.`spec.containers.env` and `spec.initContainers.env` attributes. Notice: `workspaceEnv` has absolutely the same attributes -|=== -|`name`| Environment variable name -|`value`| Environment variable value -|=== - -.`spec.containers.volumes` and `spec.initContainers.volumes` attributes -:=== -`mountPath`: Path to the volume in the container -`name`: Volume name -`ephemeral`: If true, the volume is ephemeral, otherwise the volume is persisted -:=== - -.`spec.containers.ports` and `spec.initContainers.ports` attributes -:=== -`exposedPort`: Exposed port -:=== - -.`spec.containers.commands` and `spec.initContainers.commands` attributes -:=== -`name`: Command name -`workingDir`: Command working directory -`command`: String array that defines the development command -:=== - -.`spec.endpoints` attributes -:=== -`name`: Name (no spaces allowed), must match [-a-z0-9] -`public`: `true`, `false` -`targetPort`: Target port -`attributes`: Endpoint attributes -:=== - -.`spec.endpoints.attributes` attributes -:=== -`protocol`: Protocol, example\: `ws` -`type`: `ide`, `ide-dev` -`discoverable`: `true`, `false` -`secure`: `true`, `false`. If `true`, then the endpoint is assumed to listen solely on `127.0.0.1` and is exposed using a JWT proxy -`cookiesAuthEnabled`: `true`, `false` -`requireSubdomain`: `true`, `false`. If `true`, the endpoint is exposed on subdomain in single-host mode. -:=== - -.`spec.containers.lifecycle` and `spec.initContainers.lifecycle` attributes -|=== -|`postStart` | The `postStart` event that runs immediately after a Container is started. See link:https://kubernetes.io/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/[postStart and preStop handlers] - -* `exec`: Executes a specific command, resources consumed by the command are counted against the Container - -* `command`: ["/bin/sh", "-c", "/bin/post-start.sh"] -|`preStop` | The `preStop` event that runs before a Container is terminated. See link:https://kubernetes.io/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/[postStart and preStop handlers] - -* `exec`: Executes a specific command, resources consumed by the command are counted against the Container - -* `command`: ["/bin/sh", "-c", "/bin/post-start.sh"] -|=== - -.Example `meta.yaml` for a Che-Theia plug-in: the {prod-short} machine-exec Service -[source,yaml,subs="+quotes,+attributes"] ----- - apiVersion: v2 - publisher: eclipse - name: che-machine-exec-plugin - version: 7.9.2 - type: Che Plugin - displayName: {prod-short} machine-exec Service - title: Che machine-exec Service Plugin - description: {prod-short} Plug-in with che-machine-exec service to provide creation terminal - or tasks for Eclipse CHE workspace containers. - icon: https://www.eclipse.org/che/images/logo-eclipseche.svg - repository: https://github.com/eclipse-che/che-machine-exec/ - firstPublicationDate: "2020-03-18" - category: Other - spec: - endpoints: - - name: "che-machine-exec" - public: true - targetPort: 4444 - attributes: - protocol: ws - type: terminal - discoverable: false - secure: true - cookiesAuthEnabled: true - containers: - - name: che-machine-exec - image: "quay.io/eclipse/che-machine-exec:7.9.2" - ports: - - exposedPort: 4444 - command: ['/go/bin/che-machine-exec', '--static', '/cloud-shell', '--url', '127.0.0.1:4444'] ----- - -.Example `meta.yaml` for a VisualStudio Code extension: the AsciiDoc support extension -[source,yaml] ----- -apiVersion: v2 -category: Language -description: This extension provides a live preview, syntax highlighting and snippets for the AsciiDoc format using Asciidoctor flavor -displayName: AsciiDoc support -firstPublicationDate: "2019-12-02" -icon: https://www.eclipse.org/che/images/logo-eclipseche.svg -name: vscode-asciidoctor -publisher: joaompinto -repository: https://github.com/asciidoctor/asciidoctor-vscode -title: AsciiDoctor Plug-in -type: VS Code extension -version: 2.7.7 -spec: - extensions: - - https://github.com/asciidoctor/asciidoctor-vscode/releases/download/v2.7.7/asciidoctor-vscode-2.7.7.vsix ----- - -pass:[<!-- vale Vale.Spelling = YES -->] - -pass:[<!-- vale Vale.Terms = YES -->] - -pass:[<!-- vale IBM.Usage = YES -->] - -pass:[<!-- vale IBM.PassiveVoice = YES -->] - -pass:[<!-- vale IBM.Slash = YES -->] diff --git a/modules/end-user-guide/partials/ref_devfile-reference.adoc b/modules/end-user-guide/partials/ref_devfile-reference.adoc deleted file mode 100644 index 4941ab99d4..0000000000 --- a/modules/end-user-guide/partials/ref_devfile-reference.adoc +++ /dev/null @@ -1,1126 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-using-a-devfile - -[id="devfile-reference_{context}"] -= Devfile reference - -This section contains devfile reference and instructions on how to use the various elements that devfiles consist of. - -[id="adding-schema-version-to-a-devfile_{context}"] -== Adding schema version to a devfile - -.Procedure - -* Define the `schemaVersion` attribute in the devfile: - -.Adding schema version to a devfile -==== -[source,yaml] ----- -schemaVersion: 1.0.0 ----- -==== - -[id="adding-a-name-to-a-devfile_{context}"] -== Adding a name to a devfile - -Adding a name to a devfile is mandatory. Both `name` and `generateName` are optional attributes, but at least one of them must be defined. - -.Procedure - -. To specify a static name for the workspace, define the `name` attribute. -+ -.Adding a static name to a devfile - -[source,yaml] ----- -schemaVersion: 1.0.0 -metadata: - name: devfile-sample ----- - -. To specify a prefix for automatically generated workspace names, define the `generateName` attribute and don't define the `name` attribute. The workspace name will be in the `<generateName>YYYYY` format, for example, `devfile-sample-2y7kp`, where `Y` is a random `[a-z0-9]` character. -+ -.Adding a generated name to a devfile - -[source,yaml] ----- -schemaVersion: 1.0.0 -metadata: - generateName: devfile-sample- ----- - -[NOTE] -==== -For workspaces created using a factory, defining `name` or `generateName` has the same effect. The defined value is used as the name prefix: `<name>YYYYY` or `<generateName>YYYYY`. When both `generateName` and `name` are defined, `generateName` takes precedence. -==== - -[id="adding-projects-to-a-devfile_{context}"] -== Adding projects to a devfile - -A devfile is designed to contain one or more projects. A workspace is created to develop those projects. Projects are added in the `projects` section of devfiles. - -Each project in a single devfile must have: - -* Unique name -* Source specified - -Project source consists of two mandatory values: `type` and `location`. - -`type`:: The kind of project-source provider. -`location`:: The URL of project source. - -{prod-short} supports the following project types: - -`git`:: Projects with sources in Git. The location points to a clone link. - -`github`:: Same as `git` but for projects hosted on link:https://github.com/[GitHub] only. Use `git` for projects that do not use GitHub-specific features. - -`zip`:: Projects with sources in a `.zip` archive. Location points to a `.zip` file. - - -=== Project-source type: git - -[source,yaml] ----- -source: - type: git - location: https://github.com/eclipse-che/che-server.git - startPoint: main <1> - tag: 7.34.0 - commitId: 36fe587 - branch: 7.34.x - sparseCheckoutDir: core <2> ----- - -<1> `startPoint`: The general value for `tag`, `commitId`, and `branch`. The `startPoint`, `tag`, `commitId`, and `branch` parameters are mutually exclusive. When more than one is supplied, the following order is used: `startPoint`, `tag`, `commitId`, `branch`. - -<2> `sparseCheckoutDir`: The template for the sparse checkout Git feature. This is useful when only a part of a project, typically a single directory, is needed. - -.`sparseCheckoutDir` parameter settings -==== -* Set to `/my-module/` to create only the root `my-module` directory (and its content). - -* Omit the leading slash (`my-module/`) to create all `my-module` directories that exist in the project. Including, for example, `/addons/my-module/`. -+ -The trailing slash indicates that only directories with the given name (including their content) are created. - -* Use wildcards to specify more than one directory name. For example, setting `module-*` checks out all directories of the given project that start with `module-`. -==== - -For more information, see link:https://git-scm.com/docs/git-read-tree#_sparse_checkout[Sparse checkout in Git documentation]. - - -=== Project-source type: zip - -[source,yaml] ----- -source: - type: zip - location: http://host.net/path/project-src.zip ----- - - -=== Project clone-path parameter: clonePath - -The `clonePath` parameter specifies the path into which the project is to be cloned. The path must be relative to the `/projects/` directory, and it cannot leave the `/projects/` directory. The default value is the project name. - -.Example devfile with projects -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: my-project-dev -projects: - - name: my-project-resourse - clonePath: resources/my-project - source: - type: zip - location: http://host.net/path/project-res.zip - - name: my-project - source: - type: git - location: https://github.com/my-org/project.git - branch: develop ----- - -[id="adding-components-to-a-devfile_{context}"] -== Adding components to a devfile - -Each component in a single devfile must have a unique name. - -=== Component type: cheEditor - -Describes the editor used in the workspace by defining its `id`. A devfile can only contain one component of the `cheEditor` type. - -[source,yaml] ----- -components: - - alias: theia-editor - type: cheEditor - id: eclipse/che-theia/next ----- - -When `cheEditor` is missing, a default editor is provided along with its default plug-ins. The default plug-ins are also provided for an explicitly defined editor with the same `id` as the default one (even if it is a different version). Che-Theia is configured as default editor along with the *{prod-short} Machine Exec* plug-in. - -To specify that a workspace requires no editor, use the xref:attribute-editorfree_{context}[`editorFree:true` attribute] in the devfile attributes. - -=== Component type: chePlugin - -Describes plug-ins in a workspace by defining their `id`. A devfile is allowed to have multiple `chePlugin` components. - -[source,yaml] ----- - components: - - alias: exec-plugin - type: chePlugin - id: eclipse/che-machine-exec-plugin/latest ----- - -Both types above use an ID, which is slash-separated publisher, name and version of plug-in from the {prod-short} Plug-in registry. Note that the {prod-short} Plug-in registry uses the `latest` version by default for all plug-ins. - -To reference a custom plug-in by ID, build and deploy a custom plug-in registry. See xref:administration-guide:building-custom-registry-images.adoc[]. - -=== Specifying an alternative component registry - -To specify an alternative registry for the `cheEditor` and `chePlugin` component types, use the `registryUrl` parameter: - -[source,yaml] ----- - components: - - alias: exec-plugin - type: chePlugin - registryUrl: https://my-customregistry.com - id: eclipse/che-machine-exec-plugin/latest ----- - -=== Specifying a component by linking to its descriptor - - -Rather than using the editor or plug-in `id` to specify `cheEditor` or `chePlugin`, provide a direct link to the component descriptor, typically named as `meta.yaml`, using the `reference` field: - -[source,yaml] ----- - components: - - alias: exec-plugin - type: chePlugin - reference: https://raw.githubusercontent.com.../plugin/1.0.1/meta.yaml ----- - -The URL in the `reference` field must be publicly accessible and should directly point to a fetchable `meta.yaml` file. URLs that redirect or do not directly point to a `meta.yaml` file will cause the workspace startup to fail. To learn more about publishing `meta.yaml` files, see xref:publishing-metadata-for-a-vs-code-extension.adoc[]. - -NOTE: It is impossible to mix the `id` and `reference` fields in a single component definition; they are mutually exclusive. - -=== Tuning chePlugin component configuration - -A chePlugin component may need to be precisely tuned, and in such case, component preferences can be used. The example shows how to configure JVM using plug-in preferences. - -[source,yaml] ----- - id: redhat/java/latest - type: chePlugin - preferences: - java.jdt.ls.vmargs: '-noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication' ----- - -Preferences may also be specified as an array: - -[source,yaml] ----- - id: redhat/java/latest - type: chePlugin - preferences: - go.lintFlags: ["--enable-all", "--new"] ----- - -=== Component type: `kubernetes` - -A complex component type that allows to apply configuration from a list of {orch-name} components. - -The content can be provided through the `reference` attribute, which points to the file with the component content. - -[source,yaml] ----- - components: - - alias: mysql - type: kubernetes - reference: petclinic.yaml - selector: - app.kubernetes.io/name: mysql - app.kubernetes.io/component: database - app.kubernetes.io/part-of: petclinic ----- - -Alternatively, to post a devfile with such components to REST API, the contents of the {orch-name} `List` object can be embedded into the devfile using the `referenceContent` field: - -[source,yaml] ----- - components: - - alias: mysql - type: kubernetes - reference: petclinic.yaml - referenceContent: | - kind: List - items: - - - apiVersion: v1 - kind: Pod - metadata: - name: ws - spec: - containers: - ... etc ----- - -=== Overriding container entrypoints - -As with the xref:component-type-dockerimage_{context}[understood] by {platforms-name}). - -There can be more containers in the list (contained in Pods or Pod templates of deployments). To select which containers to apply the entrypoint changes to. - -The entrypoints can be defined as follows: - -[source,yaml] ----- - components: - - alias: appDeployment - type: kubernetes - reference: app-deployment.yaml - entrypoints: - - parentName: mysqlServer - command: ['sleep'] - args: ['infinity'] - - parentSelector: - app: prometheus - args: ['-f', '/opt/app/prometheus-config.yaml'] ----- - -The `entrypoints` list contains constraints for picking the containers along with the `command` and `args` parameters to apply to them. In the example above, the constraint is `parentName: mysqlServer`, which will cause the command to be applied to all containers defined in any parent object called `mysqlServer`. The parent object is assumed to be a top level object in the list defined in the referenced file, which is `app-deployment.yaml` in the example above. - -Other types of constraints (and their combinations) are possible: - -`containerName`:: the name of the container -`parentName`:: the name of the parent object that (indirectly) contains the containers to override -`parentSelector`:: the set of labels the parent object needs to have - -A combination of these constraints can be used to precisely locate the containers inside the referenced {orch-name} `List`. - -=== Overriding container environment variables - -To provision or override entrypoints in a {platforms-name} component, configure it in the following way: - -[source,yaml] ----- - components: - - alias: appDeployment - type: kubernetes - reference: app-deployment.yaml - env: - - name: ENV_VAR - value: value ----- - -This is useful for temporary content or without access to editing the referenced content. The specified environment variables are provisioned into each init container and containers inside all Pods and Deployments. - -=== Specifying mount-source option - -To specify a project sources directory mount into container(s), use the `mountSources` parameter: - -[source,yaml] ----- - components: - - alias: appDeployment - type: kubernetes - reference: app-deployment.yaml - mountSources: true ----- - -If enabled, project sources mounts will be applied to every container of the given component. -This parameter is also applicable for `chePlugin` type components. - -[id="component-type-dockerimage_{context}"] -=== Component type: `dockerimage` - -A component type that allows to define a container image-based configuration of a container in a workspace. The `dockerimage` type of component brings in custom tools into the workspace. The component is identified by its image. - -[source,yaml] ----- - components: - - alias: maven - type: dockerimage - image: quay.io/eclipse/che-java11-maven:nightly - volumes: - - name: mavenrepo - containerPath: /root/.m2 - env: - - name: ENV_VAR - value: value - endpoints: - - name: maven-server - port: 3101 - attributes: - protocol: http - secure: 'true' - public: 'true' - discoverable: 'false' - memoryLimit: 1536M - memoryRequest: 256M - command: ['tail'] - args: ['-f', '/dev/null'] ----- - -*Example of a minimal `dockerimage` component* - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -components: - - type: dockerimage - image: golang - memoryLimit: 512Mi - command: ['sleep', 'infinity'] ----- - -It specifies the type of the component, `dockerimage` and the `image` attribute names the image to be used for the component using the usual Docker naming conventions, that is, the above `type` attribute is equal to `docker.io/library/golang:latest`. - -A `dockerimage` component has many features that enable augmenting the image with additional resources and information needed for meaningful integration of the *tool* provided by the image with {prod}. - -=== Mounting project sources - -For the `dockerimage` component to have access to the project sources, you must set the `mountSources` attribute to `true`. - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -components: - - type: dockerimage - image: golang - memoryLimit: 512Mi - command: ['sleep', 'infinity'] ----- - -The sources is mounted on a location stored in the `CHE_PROJECTS_ROOT` environment variable that is made available in the running container of the image. This location defaults to `/projects`. - -=== Container entrypoint - -The `command` attribute of the `dockerimage` along with other arguments, is used to modify the `entrypoint` command of the container created from the image. In {prod} the container is needed to run indefinitely so that you can connect to it and execute arbitrary commands in it at any time. Because the availability of the `sleep` command and the support for the `infinity` argument for it is different and depends on the base image used in the particular images, {prod-short} cannot insert this behavior automatically on its own. However, you can take advantage of this feature to, for example, start necessary servers with modified configurations, and so on. - -=== Persistent Storage - -Components of any type can specify the custom volumes to be mounted on specific locations within the image. Note that the volume names are shared across all components and therefore this mechanism can also be used to share file systems between components. - -Example specifying volumes for `dockerimage` type: - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -components: - - type: dockerimage - image: golang - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - volumes: - - name: cache - containerPath: /.cache ----- - -Example specifying volumes for `cheEditor`/`chePlugin` type: - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -components: - - type: cheEditor - alias: theia-editor - id: eclipse/che-theia/next - env: - - name: HOME - value: $(CHE_PROJECTS_ROOT) - volumes: - - name: cache - containerPath: /.cache ----- - -Example specifying volumes for `kubernetes`/`openshift` type: - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -components: - - type: openshift - alias: mongo - reference: mongo-db.yaml - volumes: - - name: mongo-persistent-storage - containerPath: /data/db ----- - -=== Specifying container memory limit for components - -To specify a container(s) memory limit for `dockerimage`, `chePlugin` or `cheEditor`, use the `memoryLimit` parameter: - -[source,yaml] ----- - components: - - alias: exec-plugin - type: chePlugin - id: eclipse/che-machine-exec-plugin/latest - memoryLimit: 1Gi - - alias: maven - type: dockerimage - image: quay.io/eclipse/che-java11-maven:nightly - memoryLimit: 512M ----- - -This limit will be applied to every container of the given component. - -For the `cheEditor` and `chePlugin` component types, RAM limits can be described in the plug-in descriptor file, typically named `meta.yaml`. - -If none of them are specified, system-wide defaults will be applied (see description of `pass:[CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__LIMIT__MB]` system property). - - -=== Specifying container memory request for components - -To specify a container(s) memory request for `dockerimage`, `chePlugin` or `cheEditor`, use the `memoryRequest` parameter: - -[source,yaml] ----- - components: - - alias: exec-plugin - type: chePlugin - id: eclipse/che-machine-exec-plugin/latest - memoryLimit: 1Gi - memoryRequest: 512M - - alias: maven - type: dockerimage - image: quay.io/eclipse/che-java11-maven:nightly - memoryLimit: 512M - memoryRequest: 256M ----- - -This limit will be applied to every container of the given component. - -For the `cheEditor` and `chePlugin` component types, RAM requests can be described in the plug-in descriptor file, typically named `meta.yaml`. - -If none of them are specified, system-wide defaults are applied (see description of `pass:[CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__REQUEST__MB]` system property). - - -=== Specifying container CPU limit for components - -To specify a container(s) CPU limit for `chePlugin`, `cheEditor` or `dockerimage` use the `cpuLimit` parameter: - -[source,yaml] ----- - components: - - alias: exec-plugin - type: chePlugin - id: eclipse/che-machine-exec-plugin/latest - cpuLimit: 1.5 - - alias: maven - type: dockerimage - image: quay.io/eclipse/che-java11-maven:nightly - cpuLimit: 750m ----- - -This limit will be applied to every container of the given component. - -For the `cheEditor` and `chePlugin` component types, CPU limits can be described in the plug-in descriptor file, typically named `meta.yaml`. - -If none of them are specified, system-wide defaults are applied (see description of `pass:[CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__LIMIT__CORES]` system property). - - -=== Specifying container CPU request for components - -To specify a container(s) CPU request for `chePlugin`, `cheEditor` or `dockerimage` use the `cpuRequest` parameter: - -[source,yaml] ----- - components: - - alias: exec-plugin - type: chePlugin - id: eclipse/che-machine-exec-plugin/latest - cpuLimit: 1.5 - cpuRequest: 0.225 - - alias: maven - type: dockerimage - image: quay.io/eclipse/che-java11-maven:nightly - cpuLimit: 750m - cpuRequest: 450m ----- - -This limit will be applied to every container of the given component. - -For the `cheEditor` and `chePlugin` component types, CPU requests can be described in the plug-in descriptor file, typically named `meta.yaml`. - -If none of them are specified, system-wide defaults are applied (see description of `pass:[CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__REQUEST__CORES]` system property). - -=== Environment variables - -{prod} allows you to configure Docker containers by modifying the environment variables available in component's configuration. -Environment variables are supported by the following component types: `dockerimage`, `chePlugin`, `cheEditor`, `kubernetes`, `openshift`. -In case component has multiple containers, environment variables will be provisioned to each container. - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -components: - - type: dockerimage - image: golang - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - env: - - name: GOPATH - value: $(CHE_PROJECTS_ROOT)/go - - type: cheEditor - alias: theia-editor - id: eclipse/che-theia/next - memoryLimit: 2Gi - env: - - name: HOME - value: $(CHE_PROJECTS_ROOT) ----- - -[NOTE] -==== -* The variable expansion works between the environment variables, and it uses the {kubernetes} convention for the variable references. - -* The predefined variables are available for use in custom definitions. -==== - -The following environment variables are pre-set by the {prod-short} server: - -* `CHE_PROJECTS_ROOT`: The location of the projects directory (note that if the component does not mount the sources, the projects will not be accessible). - -* `CHE_WORKSPACE_LOGS_ROOT__DIR`: The location of the logs common to all the components. If the component chooses to put logs into this directory, the log files are accessible from all other components. - -* `CHE_API_INTERNAL`: The URL to the {prod-short} server API endpoint used for communication with the {prod-short} server. - -* `CHE_WORKSPACE_ID`: The ID of the current workspace. - -* `CHE_WORKSPACE_NAME`: The name of the current workspace. - -* `CHE_WORKSPACE_NAMESPACE`: The {prod-short} {orch-namespace} of the current workspace. This environment variable is the name of the user or organization that the workspace belongs to. Note that this is different from -the {platforms-namespace} to which the workspace is deployed. - -* `CHE_MACHINE_TOKEN`: The token used to authenticate the request against the {prod-short} server. - -[subs="+quotes,macros"] -* `pass:[CHE_MACHINE_AUTH_SIGNATURE__PUBLIC__KEY]`: The public key used to secure the communication with the {prod-short} server. - -* `CHE_MACHINE_AUTH_SIGNATURE__ALGORITHM`: The encryption algorithm used in the secured communication with the {prod-short} server. - - -A devfile might need the `CHE_PROJECTS_ROOT` environment variable to locate the cloned projects in the component's container. More advanced devfiles might use the `CHE_WORKSPACE_LOGS_ROOT__DIR` environment variable to read the logs. The environment variables for securely accessing the {prod-short} server are out of scope for devfiles. These variables are available only to {prod-short} plug-ins, which use them for advanced use cases. - -[id="endpoints_{context}"] -=== Endpoints - -Components of any type can specify the endpoints that the Docker image exposes. These endpoints can be made accessible to the users if the {prod-short} cluster is running using a {kubernetes} ingress or an OpenShift route and to the other components within the workspace. You can create an endpoint for your application or database, if your application or database server is listening on a port and you need to be able to directly interact with it yourself or you allow other components to interact with it. - -Endpoints have several properties as shown in the following example: - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - source: - type: git - location: https://github.com/acme/my-go-project.git -components: - - type: dockerimage - image: golang - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - env: - - name: GOPATH - value: $(CHE_PROJECTS_ROOT)/go - - name: GOCACHE - value: /tmp/go-cache - endpoints: - - name: web - port: 8080 - attributes: - discoverable: false - public: true - protocol: http - - type: dockerimage - image: postgres - memoryLimit: 512Mi - env: - - name: POSTGRES_USER - value: user - - name: POSTGRES_PASSWORD - value: password - - name: POSTGRES_DB - value: database - endpoints: - - name: postgres - port: 5432 - attributes: - discoverable: true - public: false ----- - -Here, there are two Docker images, each defining a single endpoint. Endpoint is an accessible port that can be made accessible inside the workspace or also publicly (example, from the UI). Each endpoint has a name and port, which is the port on which certain server running inside the container is listening. The following are a few attributes that you can set on the endpoint: - -* `discoverable`: If an endpoint is discoverable, it means that it can be accessed using its name as the host name within the workspace containers (in the {platforms-name} terminology, a service is created for it with the provided name). -55 -* `public`: The endpoint will be accessible outside of the workspace, too (such endpoint can be accessed from the {prod-short} user interface). Such endpoints are publicized always on port `80` or `443` (depending on whether `tls` is enabled in {prod-short}). - -* `protocol`: For public endpoints the protocol is a hint to the UI on how to construct the URL for the endpoint access. Typical values are `http`, `https`, `ws`, `wss`. - -* `secure`: A boolean value (defaulting to `false`) specifying whether the endpoint is put behind a JWT proxy requiring a JWT workspace token to grant access. The JWT proxy is deployed in the same Pod as the server and assumes the server listens solely on the local loop-back interface, such as `127.0.0.1`. -+ -WARNING: Listening on any other interface than the local loop-back poses a security risk because such server is accessible without the JWT authentication within the cluster network on the corresponding IP addresses. - -* `path`: The path portion of the URL to the endpoint. This defaults to `/`, meaning that the endpoint is assumed to be accessible at the web root of the server defined by the component. - -* `unsecuredPaths`: A comma-separated list of endpoint paths that are to stay unsecured even if the `secure` attribute is set to `true`. - -* `cookiesAuthEnabled`: When set to `true` (the default is `false`), the JWT workspace token is automatically fetched and included in a workspace-specific cookie to allow requests to pass through the JWT proxy. -+ -WARNING: This setting potentially allows a link:https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF] attack when used in conjunction with a server using POST requests. - - -When starting a new server within a component, {prod-short} automatically detects this, and the UI offers to expose this port as a `public` port automatically. This behavior is useful for debugging a web application. It is impossible to do this for servers, such as a database server, which automatically starts at the container start. For such components, specify the endpoints explicitly. - -Example specifying endpoints for `kubernetes`/`openshift` and `chePlugin`/`cheEditor` types: - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -components: - - type: cheEditor - alias: theia-editor - id: eclipse/che-theia/next - endpoints: - - name: 'theia-extra-endpoint' - port: 8880 - attributes: - discoverable: true - public: true - - - type: chePlugin - id: redhat/php/latest - memoryLimit: 1Gi - endpoints: - - name: 'php-endpoint' - port: 7777 - - - type: chePlugin - alias: theia-editor - id: eclipse/che-theia/next - endpoints: - - name: 'theia-extra-endpoint' - port: 8880 - attributes: - discoverable: true - public: true - - - type: openshift - alias: webapp - reference: webapp.yaml - endpoints: - - name: 'web' - port: 8080 - attributes: - discoverable: false - public: true - protocol: http - - - type: openshift - alias: mongo - reference: mongo-db.yaml - endpoints: - - name: 'mongo-db' - port: 27017 - attributes: - discoverable: true - public: false ----- - -=== {platforms-name} resources - -To describe complex deployments, include references to {platforms-name} resource lists in the devfile. The {platforms-name} resource lists become a part of the workspace. - -[IMPORTANT] -==== -* {prod-short} merges all resources from the {platforms-name} resource lists into a single deployment. - -* Be careful when designing such lists to avoid name conflicts and other problems. - -==== - -.Supported {platforms-name} resources -[%header] -|=== -| Platform | Supported resources -ifeval::["{project-context}" == "che"] -| {kubernetes} | `deployments`, `pods`, `services`, `persistent volume claims`, `secrets`, `ConfigMaps` -endif::[] -| OpenShift | `deployments`, `pods`, `services`, `persistent volume claims`, `secrets`, `ConfigMaps`, `Routes` -|=== - - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - source: - type: git - location: https://github.com/acme/my-go-project.git -components: - - type: kubernetes - reference: ../relative/path/postgres.yaml ----- - -The preceding component references a file that is relative to the location of the devfile itself. Meaning, this devfile is only loadable by a {prod-short} factory to which you supply the location of the devfile and therefore it is able to figure out the location of the referenced {platforms-name} resource list. - -The following is an example of the `postgres.yaml` file. - -[source,yaml] ----- -apiVersion: v1 -kind: List -items: -- - apiVersion: v1 - kind: Deployment - metadata: - name: postgres - labels: - app: postgres - spec: - template: - metadata: - name: postgres - app: - name: postgres - spec: - containers: - - image: postgres - name: postgres - ports: - - name: postgres - containerPort: 5432 - volumeMounts: - - name: pg-storage - mountPath: /var/lib/postgresql/data - volumes: - - name: pg-storage - persistentVolumeClaim: - claimName: pg-storage -- - apiVersion: v1 - kind: Service - metadata: - name: postgres - labels: - app: postgres - name: postgres - spec: - ports: - - port: 5432 - targetPort: 5432 - selector: - app: postgres -- - apiVersion: v1 - kind: PersistentVolumeClaim - metadata: - name: pg-storage - labels: - app: postgres - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi ----- - -For a basic example of a devfile with an associated {platforms-name} list, see link:https://github.com/redhat-developer/devfile/tree/main/samples/web-nodejs-with-db-sample[web-nodejs-with-db-sample] on redhat-developer GitHub. - -If you use generic or large resource lists from which you will only need a subset of resources, you can select particular resources from the list using a selector (which, as the usual {platforms-name} selectors, works on the labels of the resources in the list). - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - source: - type: git - location: https://github.com/acme/my-go-project.git -components: - - type: kubernetes - reference: ../relative/path/postgres.yaml - selector: - app: postgres ----- - -Additionally, you can modify the entrypoints (command and arguments) of the containers in the resource list. - -//For details of the advanced use case, see xref:configuring-a-workspace-with-dashboard.adoc#defining-specific-container-images_configuring-a-workspace-with-dashboard[Defining specific container images]. - -[id="adding-commands-to-a-devfile_{context}"] -== Adding commands to a devfile - -A devfile allows to specify commands to be available for execution in a workspace. Every command can contain a subset of actions, which are related to a specific component in whose container it will be executed. - -[source,yaml] ----- - commands: - - name: build - actions: - - type: exec - component: mysql - command: mvn clean - workdir: /projects/spring-petclinic ----- - -You can use commands to automate the workspace. You can define commands for building and testing your code, or cleaning the database. - -The following are two kinds of commands: - -* {prod-short} specific commands: You have full control over what component executes the command. - -* Editor specific commands: You can use the editor-specific command definitions (example: `tasks.json` and `launch.json` in Che-Theia, which is equivalent to how these files work in VS Code). - -=== {prod-short}-specific commands - -Each {prod-short}-specific command features: - - * An `actions` attribute that specifies a command to execute. - * A `component` attribute that specifies the container in which to execute the command. - -The commands are run using the default shell in the container. - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - source: - type: git - location: https://github.com/acme/my-go-project.git -components: - - type: dockerimage - image: golang - alias: go-cli - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - env: - - name: GOPATH - value: $(CHE_PROJECTS_ROOT)/go - - name: GOCACHE - value: /tmp/go-cache -commands: - - name: compile and run - actions: - - type: exec - component: go-cli - command: “go get -d && go run main.go” - workdir: “${CHE_PROJECTS_ROOT}/src/github.com/acme/my-go-project” ----- - -[NOTE] -==== -* If a component to be used in a command must have an alias. This alias is used to reference the component in the command definition. Example: `alias: go-cli` in the component definition and `component: go-cli` in the command definition. This ensures that {prod} can find the correct container to run the command in. - -* A command can have only one action. -==== - -=== Editor-specific commands - -If the editor in the workspace supports it, the devfile can specify additional configuration in the editor-specific format. This is dependent on the integration code in the workspace editor itself and so is not a generic mechanism. However, the default Che-Theia editor within {prod} is equipped to understand the `tasks.json` and `launch.json` files provided in the devfile. - -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: MyDevfile -projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - source: - type: git - location: https://github.com/acme/my-go-project.git -commands: - - name: tasks - actions: - - type: vscode-task - referenceContent: > - { - "version": "2.0.0", - "tasks": [ - { - "label": "create test file", - "type": "shell", - "command": "touch ${workspaceFolder}/test.file" - } - ] - } ----- - -This example shows association of a `tasks.json` file with a devfile. Notice the `vscode-task` type that instructs the Che-Theia editor to interpret this command as a tasks definition and `referenceContent` attribute that contains the contents of the file itself. You can also save this file separately from the devfile and use `reference` attribute to specify a relative or absolute URL to it. - -In addition to the `vscode-task` commands, the Che-Theia editor understands `vscode-launch` type using which you can specify the start configurations. - -=== Command preview URL - -It is possible to specify a preview URL for commands that expose web UI. This URL is offered for opening when the command is executed. - -[source,yaml] ----- -commands: - - name: tasks - previewUrl: - port: 8080 <1> - path: /myweb <2> - actions: - - type: exec - component: go-cli - command: "go run webserver.go" - workdir: ${CHE_PROJECTS_ROOT}/webserver ----- -<1> TCP port where the application listens. Mandatory parameter. -<2> The path part of the URL to the UI. Optional parameter. The default is root (`/`). - -The example above opens `++http://__<server-domain>__/myweb++`, where `_<server-domain>_` is the URL to the dynamically created {platforms-ingress}. - -==== Setting the default way of opening preview URLs - -By default, a notification that asks the user about the URL opening preference is displayed. - -To specify the preferred way of previewing a service URL: - -. Open {prod-short} preferences in *File -> Settings -> Open Preferences* and find `che.task.preview.notifications` in the *{prod-short}* section. - -. Choose from the list of possible values: -+ -* `on` -- enables a notification for asking the user about the URL opening preferences -* `alwaysPreview` -- the preview URL opens automatically in the *Preview* panel as soon as a task is running -* `alwaysGoTo` -- the preview URL opens automatically in a separate browser tab as soon as a task is running -* `off` -- disables opening the preview URL (automatically and with a notification) - - -== Adding attributes to a devfile - -Devfile attributes can be used to configure various features. - -[id="attribute-editorfree_{context}"] -=== Attribute: editorFree - -When an editor is not specified in a devfile, a default is provided. When no editor is needed, use the `editorFree` attribute. The default value of `false` means that the devfile requests the provisioning of the default editor. - -.Example of a devfile without an editor -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: petclinic-dev-environment -components: - - alias: myApp - type: kubernetes - reference: my-app.yaml -attributes: - editorFree: true ----- - -=== Attribute: persistVolumes (ephemeral mode) - -By default, volumes and PVCs specified in a devfile are bound to a host folder to persist data even after a container restart. To disable data persistence to make the workspace faster, such as when the volume back end is slow, modify the `persistVolumes` attribute in the devfile. The default value is `true`. Set to `false` to use `emptyDir` for configured volumes and PVC. - -.Example of a devfile with ephemeral mode enabled -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: petclinic-dev-environment -projects: - - name: petclinic - source: - type: git - location: 'https://github.com/che-samples/web-java-spring-petclinic.git' -attributes: - persistVolumes: false ----- - -=== Attribute: asyncPersist (asynchronous storage) - -When `persistVolumes` is set to `false` (see above), the additional attribute `asyncPersist` can be set to `true` to enable asynchronous storage. See xref:installation-guide:configuring-storage-types.adoc[] for more details. - -.Example of a devfile with asynchronous storage enabled -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: petclinic-dev-environment -projects: - - name: petclinic - source: - type: git - location: 'https://github.com/che-samples/web-java-spring-petclinic.git' -attributes: - persistVolumes: false - asyncPersist: true ----- - -=== Attribute: mergePlugins - -This property can be set to manually control how plugins are included in the workspace. When the property `mergePlugins` is set to `true`, Che will attempt to avoid running multiple instances of the same container by combining plugins. The default value when this property is not included in a devfile is governed by the Che configuration property `che.workspace.plugin_broker.default_merge_plugins`; adding the `mergePlugins: false` attribute to a devfile will disable plugin merging for that workspace. - -.Example of a devfile with plugin merging disabled -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: petclinic-dev-environment -projects: - - name: petclinic - source: - type: git - location: 'https://github.com/che-samples/web-java-spring-petclinic.git' -attributes: - mergePlugins: false ----- - -pass:[<!-- vale IBM.Slash = YES -->] - -pass:[<!-- vale IBM.Terms = YES -->] - -pass:[<!-- vale Vale.Avoid = YES -->] - diff --git a/modules/end-user-guide/partials/ref_netcoredebugoutput-plug-in.adoc b/modules/end-user-guide/partials/ref_netcoredebugoutput-plug-in.adoc index d520371571..09f3a991d1 100644 --- a/modules/end-user-guide/partials/ref_netcoredebugoutput-plug-in.adoc +++ b/modules/end-user-guide/partials/ref_netcoredebugoutput-plug-in.adoc @@ -4,6 +4,6 @@ = NetcoredebugOutput plug-in The NetcoredebugOutput plug-in provides the link:https://github.com/Samsung/netcoredbg[`netcoredbg`] tool. -This tool implements the VS Code Debug Adapter protocol and allows users to debug .NET applications under the .NET Core runtime. +This tool implements the Visual Studio Code Debug Adapter protocol and allows users to debug .NET applications under the .NET Core runtime. The container where the NetcoredebugOutput plug-in is running contains .NET SDK v.2.2.105. diff --git a/modules/end-user-guide/partials/ref_objects-supported-in-che.adoc b/modules/end-user-guide/partials/ref_objects-supported-in-che.adoc deleted file mode 100644 index e021a77245..0000000000 --- a/modules/end-user-guide/partials/ref_objects-supported-in-che.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-a-workspace-using-a-devfile - -[id="objects-supported-in-{prod-id-short}_{context}"] -= Objects supported in {prod} {prod-ver} - -The following table lists the objects that are partially supported in {prod} {prod-ver}: - -[cols="1,1,1,1,5", options="header"] -|=== -|Object -|API -|{kubernetes} Infra -|OpenShift Infra -|Notes - -|Pod -|{kubernetes} -|Yes -|Yes -|- - -|Deployment -|{kubernetes} -|Yes -|Yes -|- - -|ConfigMap -|{kubernetes} -|Yes -|Yes -|- - -|PVC -|{kubernetes} -|Yes -|Yes -|- - -|Secret -|{kubernetes} -|Yes -|Yes -|- - -|Service -|{kubernetes} -|Yes -|Yes -|- - -|Ingress -|{kubernetes} -|Yes -|No -|Minishift allows you to create Ingress and it works when the host is specified (OpenShift creates a route for it). But, the `loadBalancer` IP is not provisioned. To add Ingress support for the OpenShift infrastructure node, generate routes based on the provided Ingress. - -|Route -|OpenShift -|No -|Yes -|The OpenShift recipe must be made compatible with the {kubernetes} Infrastructure: OpenShift routes replaced on Ingresses. - -|Template -|OpenShift -|Yes -|Yes -|The {kubernetes} API does not support templates. A workspace with a template in the recipe starts successfully and the default parameters are resolved. -|=== diff --git a/modules/end-user-guide/partials/ref_the-use-of-annotations-in-the-process-of-mounting-a-secret-into-a-workspace-container.adoc b/modules/end-user-guide/partials/ref_the-use-of-annotations-in-the-process-of-mounting-a-secret-into-a-workspace-container.adoc deleted file mode 100644 index 50b07c8a75..0000000000 --- a/modules/end-user-guide/partials/ref_the-use-of-annotations-in-the-process-of-mounting-a-secret-into-a-workspace-container.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container - -[id="the-use-of-annotations-in-the-process-of-mounting-a-secret-into-a-workspace-container_{context}"] -= The use of annotations in the process of mounting a secret into a workspace container - -{kubernetes} annotations and labels are tools used by libraries, tools, and other clients, to attach arbitrary non-identifying metadata to {platforms-name} native objects. - -Labels select objects and connect them to a collection that satisfies certain conditions, where annotations are used for non-identifying information that is not used by {platforms-name} objects internally. - -This section describes {platforms-name} annotation values used in the process of {platforms-name} secret mounting in a {prod-short} workspace. - -Annotations must contain items that help identify the proper mounting configuration. These items are: - -include::example${project-context}-ref_annotations-description.adoc[levelofset=+1] diff --git a/modules/extensions/examples/snip_che-authenticating-with-openshift-connector-from-a-local-instance.adoc b/modules/extensions/examples/snip_che-authenticating-with-openshift-connector-from-a-local-instance.adoc new file mode 100644 index 0000000000..b60cb8736a --- /dev/null +++ b/modules/extensions/examples/snip_che-authenticating-with-openshift-connector-from-a-local-instance.adoc @@ -0,0 +1 @@ +When using a local instance of OpenShift such as CodeReady Containers, {prod-short} stores the user’s credentials in a `~/.kube/config` file in the workspace. Use this file for automatic authentication in subsequent logins. In the context of {prod-short}, the `~/.kube/config` is stored as a part of the plug-in sidecar container. diff --git a/modules/extensions/examples/telemetry/AnalyticsManagerSkeleton.java b/modules/extensions/examples/telemetry/AnalyticsManagerSkeleton.java deleted file mode 100644 index 1fafaeaae2..0000000000 --- a/modules/extensions/examples/telemetry/AnalyticsManagerSkeleton.java +++ /dev/null @@ -1,42 +0,0 @@ -package org.my.group; - -import java.util.Map; - -import org.eclipse.che.api.core.rest.HttpJsonRequestFactory; -import org.eclipse.che.incubator.workspace.telemetry.base.AbstractAnalyticsManager; -import org.eclipse.che.incubator.workspace.telemetry.base.AnalyticsEvent; - -public class AnalyticsManager extends AbstractAnalyticsManager { - - public AnalyticsManager(String apiEndpoint, String workspaceId, String machineToken, - HttpJsonRequestFactory requestFactory) { - super(apiEndpoint, workspaceId, machineToken, requestFactory); - } - - @Override - public boolean isEnabled() { - // TODO Auto-generated method stub - return true; - } - - @Override - public void destroy() { - // TODO Auto-generated method stub - } - - @Override - public void onEvent(AnalyticsEvent event, String ownerId, String ip, String userAgent, String resolution, - Map<String, Object> properties) { - // TODO Auto-generated method stub - } - - @Override - public void increaseDuration(AnalyticsEvent event, Map<String, Object> properties) { - // TODO Auto-generated method stub - } - - @Override - public void onActivity() { - // TODO Auto-generated method stub - } -} diff --git a/modules/extensions/examples/telemetry/MainConfiguration.java b/modules/extensions/examples/telemetry/MainConfiguration.java deleted file mode 100644 index 325cb82696..0000000000 --- a/modules/extensions/examples/telemetry/MainConfiguration.java +++ /dev/null @@ -1,16 +0,0 @@ -package org.my.group; - -import javax.enterprise.context.Dependent; -import javax.enterprise.inject.Produces; - -import org.eclipse.che.incubator.workspace.telemetry.base.AbstractAnalyticsManager; -import org.eclipse.che.incubator.workspace.telemetry.base.BaseConfiguration; - -@Dependent -public class MainConfiguration extends BaseConfiguration { - @Produces - public AbstractAnalyticsManager analyticsManager() { - return new AnalyticsManager(apiEndpoint, workspaceId, machineToken, requestFactory()); - - } -} diff --git a/modules/extensions/examples/telemetry/che_cluster_with_custom_plugin.yaml b/modules/extensions/examples/telemetry/che_cluster_with_custom_plugin.yaml deleted file mode 100644 index d86cea43b0..0000000000 --- a/modules/extensions/examples/telemetry/che_cluster_with_custom_plugin.yaml +++ /dev/null @@ -1,60 +0,0 @@ -apiVersion: org.eclipse.che/v1 -kind: CheCluster -metadata: - creationTimestamp: '2020-05-14T13:21:51Z' - finalizers: - - oauthclients.finalizers.che.eclipse.org - generation: 18 - name: {prod-checluster} - namespace: __<{prod-namespace}>__ - resourceVersion: '5108404' - selfLink: /apis/org.eclipse.che/v1/namespaces/che/checlusters/eclipse-che - uid: bae08db2-104d-4e44-a001-c9affc07528d -spec: - auth: - identityProviderURL: 'https://keycloak-che.apps-crc.testing' - identityProviderRealm: che - updateAdminPassword: false - oAuthSecret: ZMmNPRbgOJJQ - oAuthClientName: eclipse-che-openshift-identity-provider-yrlcxs - identityProviderClientId: che-public - identityProviderPostgresSecret: che-identity-postgres-secret - externalIdentityProvider: false - identityProviderSecret: che-identity-secret - openShiftoAuth: true - database: - chePostgresDb: dbche - chePostgresHostName: postgres - chePostgresPort: '5432' - chePostgresSecret: che-postgres-secret - externalDb: false - k8s: {} - metrics: - enable: false - server: - cheLogLevel: INFO - customCheProperties: - CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR_PLUGINS: 'http://apache-che.apps-crc.testing/meta.yaml' - externalDevfileRegistry: false - cheHost: che-che.apps-crc.testing - selfSignedCert: true - cheDebug: 'false' - tlsSupport: true - allowUserDefinedWorkspaceNamespaces: false - externalPluginRegistry: false - gitSelfSignedCert: false - cheFlavor: che - storage: - preCreateSubPaths: true - pvcClaimSize: 1Gi - pvcStrategy: per-workspace -status: - devfileRegistryURL: 'https://devfile-registry-che.apps-crc.testing' - keycloakProvisioned: true - cheClusterRunning: Available - cheURL: 'https://che-che.apps-crc.testing' - openShiftoAuthProvisioned: true - dbProvisioned: true - cheVersion: 7.13.1 - keycloakURL: 'https://keycloak-che.apps-crc.testing' - pluginRegistryURL: 'https://plugin-registry-che.apps-crc.testing/v3' diff --git a/modules/extensions/examples/telemetry/onEvent.java b/modules/extensions/examples/telemetry/onEvent.java deleted file mode 100644 index abfdd48732..0000000000 --- a/modules/extensions/examples/telemetry/onEvent.java +++ /dev/null @@ -1,15 +0,0 @@ -@Override -public void onEvent(AnalyticsEvent event, String ownerId, String ip, String userAgent, String resolution, Map<String, Object> properties) { - HttpClient httpClient = HttpClients.createDefault(); - HttpPost httpPost = new HttpPost("http://little-telemetry-backend-che.apps-crc.testing/event"); - HashMap<String, Object> eventPayload = new HashMap<String, Object>(properties); - eventPayload.put("event", event); - StringEntity requestEntity = new StringEntity(new JsonObject(eventPayload).toString(), - ContentType.APPLICATION_JSON); - httpPost.setEntity(requestEntity); - try { - HttpResponse response = httpClient.execute(httpPost); - } catch (IOException e) { - e.printStackTrace(); - } -} diff --git a/modules/extensions/examples/telemetry/pom_snippet.xml b/modules/extensions/examples/telemetry/pom_snippet.xml deleted file mode 100644 index 9058915307..0000000000 --- a/modules/extensions/examples/telemetry/pom_snippet.xml +++ /dev/null @@ -1,10 +0,0 @@ -<dependency> - <groupId>org.eclipse.che.incubator.workspace-telemetry</groupId> - <artifactId>backend-base</artifactId> - <version>0.0.11</version> -</dependency> -<dependency> - <groupId>org.apache.httpcomponents</groupId> - <artifactId>httpclient</artifactId> - <version>4.5.12</version> -</dependency> diff --git a/modules/extensions/examples/telemetry/sample_meta.yaml b/modules/extensions/examples/telemetry/sample_meta.yaml deleted file mode 100644 index d98bd45da1..0000000000 --- a/modules/extensions/examples/telemetry/sample_meta.yaml +++ /dev/null @@ -1,19 +0,0 @@ -apiVersion: v2 -publisher: demo-publisher -name: little-telemetry-backend -version: 0.0.1 -type: Che Plugin -displayName: Little Telemetry Backend -description: A Demo telemetry backend -title: Little Telemetry Backend -category: Other -spec: - workspaceEnv: - - name: CHE_WORKSPACE_TELEMETRY_BACKEND_PORT - value: '4167' - containers: - - name: YOUR BACKEND NAME - image: YOUR IMAGE NAME - env: - - name: CHE_API - value: $(CHE_API_INTERNAL) diff --git a/modules/extensions/images/lombok/lombok.png b/modules/extensions/images/lombok/lombok.png deleted file mode 100644 index a2243f23f7..0000000000 Binary files a/modules/extensions/images/lombok/lombok.png and /dev/null differ diff --git a/modules/extensions/images/telemetry/custom_telemetry_plugin.png b/modules/extensions/images/telemetry/custom_telemetry_plugin.png deleted file mode 100644 index 9417768dd8..0000000000 Binary files a/modules/extensions/images/telemetry/custom_telemetry_plugin.png and /dev/null differ diff --git a/modules/extensions/images/telemetry/telemetry_diagram.png b/modules/extensions/images/telemetry/telemetry_diagram.png deleted file mode 100644 index 065a420373..0000000000 Binary files a/modules/extensions/images/telemetry/telemetry_diagram.png and /dev/null differ diff --git a/modules/extensions/nav.adoc b/modules/extensions/nav.adoc index a1fce4af11..99861aef79 100644 --- a/modules/extensions/nav.adoc +++ b/modules/extensions/nav.adoc @@ -1,13 +1,8 @@ -.Extensions +* xref:extensions.adoc[] -* xref:eclipse-che4z.adoc[] -* xref:openshift-connector-overview.adoc[] -** xref:features-of-openshift-connector.adoc[] -** xref:installing-openshift-connector-in-che.adoc[] -** xref:authenticating-with-openshift-connector-from-che.adoc[] -** xref:creating-components-with-openshift-connector-in-che.adoc[] -** xref:connecting-source-code-from-github-to-a-openshift-component-using-openshift-connector.adoc[] -* xref:telemetry.adoc[] -** xref:creating-a-telemetry-plugin.adoc[] -** xref:the-woopra-telemetry-plugin.adoc[] -* xref:java-lombok.adoc[] +** xref:openshift-connector-overview.adoc[] +*** xref:features-of-openshift-connector.adoc[] +*** xref:installing-openshift-connector-in-che.adoc[] +*** xref:authenticating-with-openshift-connector-from-che.adoc[] +*** xref:creating-components-with-openshift-connector-in-che.adoc[] +*** xref:connecting-source-code-from-github-to-a-openshift-component-using-openshift-connector.adoc[] diff --git a/modules/extensions/pages/creating-a-telemetry-plugin.adoc b/modules/extensions/pages/creating-a-telemetry-plugin.adoc deleted file mode 100644 index 275792cbb1..0000000000 --- a/modules/extensions/pages/creating-a-telemetry-plugin.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="creating-a-telemetry-plugin"] -// = Creating a telemetry plugin -:navtitle: Creating A Telemetry Plugin -:keywords: extensions, telemetry -:page-aliases: .:creating-a-telemetry-plugin - -include::partial$proc_creating-a-telemetry-plugin.adoc[] diff --git a/modules/extensions/pages/eclipse-che4z.adoc b/modules/extensions/pages/eclipse-che4z.adoc deleted file mode 100644 index 905da07251..0000000000 --- a/modules/extensions/pages/eclipse-che4z.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="eclipse-che4z"] -// = Eclipse Che4z -:navtitle: Eclipse Che4z -:keywords: extensions, eclipse-che4z -:page-aliases: .:eclipse-che4z - -include::partial$assembly_eclipse-che4z.adoc[] diff --git a/modules/extensions/pages/extensions.adoc b/modules/extensions/pages/extensions.adoc new file mode 100644 index 0000000000..6ec9ad98cd --- /dev/null +++ b/modules/extensions/pages/extensions.adoc @@ -0,0 +1,8 @@ +:navtitle: Extensions +:keywords: extensions +:page-aliases: eclipse-che4z, java-lombok + += Extensions + +include::../nav.adoc[lines=2..-1] + diff --git a/modules/extensions/pages/java-lombok.adoc b/modules/extensions/pages/java-lombok.adoc deleted file mode 100644 index 8523084a79..0000000000 --- a/modules/extensions/pages/java-lombok.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="java-lombok"] -// = Java Lombok -:navtitle: Java Lombok -:keywords: extensions, lombok, java -:page-aliases: .:java-lombok - -include::partial$proc_java-lombok.adoc[] diff --git a/modules/extensions/pages/telemetry.adoc b/modules/extensions/pages/telemetry.adoc deleted file mode 100644 index fd63224202..0000000000 --- a/modules/extensions/pages/telemetry.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="telemetry"] -// = Telemetry -:navtitle: Telemetry -:keywords: extensions, telemetry -:page-aliases: .:telemetry - -include::partial$assembly_telemetry-overview.adoc[] diff --git a/modules/extensions/pages/the-woopra-telemetry-plugin.adoc b/modules/extensions/pages/the-woopra-telemetry-plugin.adoc deleted file mode 100644 index 9c1153492e..0000000000 --- a/modules/extensions/pages/the-woopra-telemetry-plugin.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="the-woopra-telemetry-plugin"] -// = The Woopra Telemtry Plugin -:navtitle: The Woopra Telemetry Plugin -:keywords: extensions, telemetry -:page-aliases: .:the-woopra-telemetry-plugin - -include::partial$ref_the-woopra-telemetry-plugin.adoc[] diff --git a/modules/extensions/partials/assembly_eclipse-che4z.adoc b/modules/extensions/partials/assembly_eclipse-che4z.adoc deleted file mode 100644 index 85013526e1..0000000000 --- a/modules/extensions/partials/assembly_eclipse-che4z.adoc +++ /dev/null @@ -1,168 +0,0 @@ -:parent-context-of-eclipse-che4z: {context} - -[id="eclipse-che4z_{context}"] -= Eclipse Che4z - -pass:[<!-- vale Vale.Terms = NO -->] -pass:[<!-- vale IBM.Terms = NO -->] - -Eclipse Che4z is an all-in-one mainframe extension stack for {prod}, which provides a modern experience for mainframe software developers working with z/OS applications. - -Powered by the open-source projects link:https://www.zowe.org/[Zowe] and link:https://www.eclipse.org/che/[Eclipse Che], Che4z offers an easy and streamlined on-boarding process to get new developers using the tools they need. Using container technology and stacks, {prod} brings the necessary technology to the task at hand. - -Developers can find the code they need to work on in Explorer for Endevor, Git and Zowe Explorer, edit code assisted by COBOL or HLASM Language Support, and test the resulting code with the Debugger, all in one Mainframe development package. - -Eclipse Che4z is an open source project. Many of the components of the Che4z stack are also available on the VS Code marketplace as part of the https://marketplace.visualstudio.com/items?itemName=broadcomMFD.code4z-extension-pack[Code4z] package. - -== Use cases - -The Eclipse Che4z extension allows: - -* Viewing and editing CA Endevor SCM data in the {prod} environment. -* Editing COBOL and High Level Assembler language files with syntax awareness and autocomplete features. -* Browsing mainframe data sets in the {prod} environment. -* Debugging CICS and Batch programs written in COBOL. -* Performing tasks on mainframe applications using a command-line interface. - -== Getting Started - -For instructions on how to install the Eclipse Che4z stack, see the https://github.com/eclipse/che-che4z[Che4z Git repository] - -== Components - -The Eclipse Che4z extension includes the following components: - -=== COBOL Language Support - -COBOL Language Support enhances the COBOL programming experience on your IDE. The extension leverages the language server protocol to provide autocomplete, syntax coloring, highlighting and diagnostic features for COBOL code and copybooks. The COBOL Language Support extension can also connect to a mainframe using a Zowe CLI z/OSMF profile to automatically retrieve copybooks used in your programs and store them in your workspace. - -==== Features: - -* Edit COBOL code with assistance including: -** Syntax highlighting and coloring -** Real time syntax validation -** Content assist -* Automatic copybook retrieval - -link:https://github.com/eclipse/che-che4z-lsp-for-cobol/issues[image:https://img.shields.io/github/issues-raw/eclipse/che-che4z-lsp-for-cobol?style=flat-square[GitHub issues]] -link:https://join.slack.com/t/che4z/shared_invite/enQtNzk0MzA4NDMzOTIwLWIzMjEwMjJlOGMxNmMyNzQ1NWZlMzkxNmQ3M2VkYWNjMmE0MGQ0MjIyZmY3MTdhZThkZDg3NGNhY2FmZTEwNzQ[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[slack]] - -* For documentation and release information, see the https://github.com/eclipse/che-che4z-lsp-for-cobol[COBOL Language Support Git repository]. -* For the feedback related to the topic of improving COBOL Language Support, see https://github.com/eclipse/che-che4z-lsp-for-cobol/issues[Let us know]. - - -==== Blogs: -* https://medium.com/modern-mainframe/beginners-guide-cobol-made-easy-introduction-ecf2f611ac76[Beginner’s Guide: COBOL Made Easy] - -=== Zowe Explorer - -Zowe Explorer is an extension powered by Zowe CLI that streamlines interaction with mainframe data sets, USS files, and jobs. The extension is designed to function along with other extensions and plug-ins to deliver a richer experience. - -You can learn more about the Zowe Explorer by watching the https://www.youtube.com/embed/G_WCsFZIWt4[Getting Started] and https://www.youtube.com/embed/X4oSHrI4oN4[Work with Data Sets] tutorial videos. - -==== Features: -* Access z/OS Datasets and z/OS Unix file systems, and submit JCLs. -* Create, edit, and work with z/OSMF compatible profiles. -* Store your credentials securely with Secure Credentials Store plug-in. -* View and download job output. -* Issue TSO commands. -* Install additional extensions. - -link:https://github.com/zowe/vscode-extension-for-zowe/issues[image:https://img.shields.io/github/issues-raw/zowe/vscode-extension-for-zowe?style=flat-square[GitHub issues]] -link:https://openmainframeproject.slack.com/[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[slack]] - -* For documentation, see link:https://docs.zowe.org/stable/user-guide/ze-install/[Zowe Docs] -* For the feedback related to the topic of improving Zowe Explorer, see link:https://github.com/zowe/vscode-extension-for-zowe/issues[Let us know on our Git repository] - - -==== Blogs: -* link:https://medium.com/zowe/beginners-guide-how-to-access-mainframe-via-zowe-in-10-easy-steps-fbec14ed6ed2[Beginner’s Guide: How to access mainframe using Zowe in 10 easy steps] * -* link:https://medium.com/zowe[Zowe blog] - -=== HLASM Language Support - -HLASM Language Support is an extension that supports the High Level Assembler language. It provides code completion, highlighting and navigation features, shows mistakes in the source, and lets you trace how the conditional assembly is evaluated with a modern debugging experience. - -==== Features - -* Highlights statements with different colors for labels, instructions, operands, remarks and variables. -* Autocomplete is enabled for the instruction field. While typing, a list of instructions starting with the typed characters displays. -* The extension adds the 'go to definition' and 'find all references' functionalities. -* The macro tracer functionality allows you to track the process of assembling HLASM code. - -* link:https://github.com/eclipse/che-che4z-lsp-for-hlasm/issues[image:https://img.shields.io/github/issues-raw/zowe/vscode-extension-for-zowe?style=flat-square[GitHub issues]] -* link:https://openmainframeproject.slack.com/[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[Slack]] - -* For documentation and release information, see the https://github.com/eclipse/che-che4z-lsp-for-hlasm[HLASM Language Support Git repository]. -* For the feedback related to the topic of improving HLASM Language Support, see https://github.com/eclipse/che-che4z-lsp-for-hlasm/issues[Let us know]. - - -=== Explorer for Endevor - -Explorer for Endevor gives you the ability to Browse and Retrieve link:https://www.broadcom.com/products/mainframe/application-development[CA Endevor® SCM] elements using a user-friendly, intuitive interface. - -This extension offers best developer experience in synergy with https://youtu.be/sjnZuQpUVM4[Bridge for Git], a solution which enables you to concurrently work in Git and mainframe. - -==== Features -* Retrieve, browse and search CA Endevor® elements. - -https://github.com/eclipse/che-che4z-explorer-for-endevor/issues[image:https://img.shields.io/github/issues-raw/eclipse/che-che4z-explorer-for-endevor?style=flat-square[GitHub issues]] -https://join.slack.com/t/che4z/shared_invite/enQtNzk0MzA4NDMzOTIwLWIzMjEwMjJlOGMxNmMyNzQ1NWZlMzkxNmQ3M2VkYWNjMmE0MGQ0MjIyZmY3MTdhZThkZDg3NGNhY2FmZTEwNzQ[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[slack]] - -* For documentation and release information, see the https://github.com/eclipse/che-che4z-explorer-for-endevor/[Explorer for Endevor Git repository]. -* For the feedback related to the topic of improving Explorer for Endevor, see https://github.com/eclipse/che-che4z-explorer-for-endevor/issues[Let us know]. - -=== Debugger for Mainframe - -Debugger for Mainframe provides the debugging interface to https://www.broadcom.com/products/mainframe/devops-app-development/testing-quality/intertest-cics[CA InterTest™ for CICS] and https://www.broadcom.com/products/mainframe/testing-and-quality/intertest-batch[CA InterTest™ Batch]. This extension provides a modern debug experience for CICS and Batch applications written in COBOL. - -==== Features: -* Debug COBOL code for applications running in a CICS region. -* Debug COBOL code for Batch programs. - -https://github.com/BroadcomMFD/debugger-for-mainframe/issues[image:https://img.shields.io/github/issues-raw/broadcomMFD/debugger-for-mainframe?style=flat-square[GitHub issues]] -https://join.slack.com/t/che4z/shared_invite/enQtNzk0MzA4NDMzOTIwLWIzMjEwMjJlOGMxNmMyNzQ1NWZlMzkxNmQ3M2VkYWNjMmE0MGQ0MjIyZmY3MTdhZThkZDg3NGNhY2FmZTEwNzQ[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[slack]] - -* For documentation and release information, see the link:https://github.com/BroadcomMFD/debugger-for-mainframe[Debugger for Mainframe Git repository]. -* For the feedback related to the topic of improving Debugger for Mainframe, see link:https://github.com/BroadcomMFD/debugger-for-mainframe/issues[Let us know]. - - -=== Zowe CLI plug-ins - -Zowe Command Line-Interface (Zowe CLI) is a command-line interface that lets application developers interact with the mainframe in a familiar format. -// The following Zowe CLI plug-ins are included in the Che4z basic stack: -* link:https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-brightside/3-0/zowe-cli/available-cli-plug-ins/ca-endevor-scm-plug-in-for-zowe-cli.html[CA Endevor SCM plug-in for Zowe CLI] -* link:https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-brightside/3-0/zowe-cli/available-cli-plug-ins/ca-file-master-plus-plug-in-for-zowe-cli.html[CA File Master Plus plug-in for Zowe CLI] -* link:https://docs.zowe.org/stable/user-guide/cli-db2plugin.html[IBM Db2 plug-in for Zowe CLI] -* link:https://docs.zowe.org/stable/user-guide/cli-cicsplugin.html[IBM CICS plug-in for Zowe CLI] - -== Sample Workflows - -=== COBOL Language Support using CA Endevor Bridge for Git and Explorer for Endevor - -* Use VS Code’s built-in Git interface to clone source code from CA Endevor using Endevor’s Bridge for Git. -* Edit COBOL code using COBOL Language Support, taking advantage of all the coding assistance provided by the extension. -* Locate all copybooks in the Git folder structure, and if needed, download other copybooks used in the source code from the mainframe. -* Use VS Code’s built-in Git interface to push, pull and merge changes. -* Search and browse additional code elements in the entire map of Endevor using the Explorer for Endevor extension. The COBOL Language Support extension provides syntax awareness for COBOL elements. -* Download code elements, including their dependencies, into the current workspace using the Explorer for Endevor extension, and synchronize them with the Git project if code modifications are needed. - -=== Debugger for Mainframe - -* Provide InterTest server location, CICS region, credentials and program or transaction name (either by file or input form). -* Obtain the listing and set breakpoints. -* Trigger the CICS transaction and start a debug session. -* Display and change variable values. -* Stop at designated breakpoints, continue from a designated breakpoint and step through the listing. -* Close the debug session. - -=== Zowe Explorer and Zowe CLI - -* Access mainframe files and execute jobs, either from an interactive graphical interface or in the terminal with CLI. Whether you need to view a PDS, allocate a dataset, change a JCL, submit a mainframe compile, or download and upload files, Zowe Explorer and Zowe CLI interfaces provide these capabilities. - -:context: {parent-context-of-eclipse-che4z} - - -pass:[<!-- vale Vale.Terms = YES -->] - -pass:[<!-- vale IBM.Terms = YES -->] \ No newline at end of file diff --git a/modules/extensions/partials/assembly_telemetry-overview.adoc b/modules/extensions/partials/assembly_telemetry-overview.adoc deleted file mode 100644 index 679dddcef1..0000000000 --- a/modules/extensions/partials/assembly_telemetry-overview.adoc +++ /dev/null @@ -1,32 +0,0 @@ -:parent-context-of-telemetry-overview: {context} - -[id="telemetry-overview_{context}"] -= Telemetry overview - -:context: telemetry-overview - -Telemetry is the explicit and ethical collection of operation data. By default, telemetry is not available in {prod}, but there is an abstract API that allows enabling telemetry using the plug-in mechanism. This approach is used in the xref:overview:hosted-che.adoc[] service where telemetry is enabled for every workspace. - -This documentation includes a guide describing how to make your own telemetry client for {prod}, followed by an overview of the link:https://github.com/che-incubator/che-workspace-telemetry-woopra-plugin[{prod} Woopra Telemetry Plugin]. - -== Use cases -[id="use-cases_{context}"] - -{prod} telemetry API allows tracking: - -* Duration of a workspace utilization -* User-driven actions such as file editing, committing, and pushing to remote repositories. -* The list of plug-ins enabled in a workspace -* Programming languages and devfiles used in workspaces. See xref:end-user-guide:authoring-devfiles-version-2.adoc[] - -== How it works -[id="how-it-works_{context}"] - -When a {prod-short} workspace starts, the `che-theia` container starts the telemetry plug-in, which is responsible for sending telemetry events to a back-end. If the `$CHE_WORKSPACE_TELEMETRY_BACKEND_PORT` environment variable was set in the workspace Pod, the telemetry plug-in will send events to a back-end listening at that port. - -If the {prod-short} workspace has a telemetry back-end container running, and it is listening on `$CHE_WORKSPACE_TELEMETRY_BACKEND_PORT`, it takes the events sent from the telemetry plug-in, turns them into the back-end-specific representation of events, and sends them to the configured analytics back-end (for example, Segment or Woopra). - -image::telemetry/telemetry_diagram.png[] - - -:context: {parent-context-of-telemetry-overview} diff --git a/modules/extensions/partials/proc_authenticating-with-openshift-connector-from-che.adoc b/modules/extensions/partials/proc_authenticating-with-openshift-connector-from-che.adoc index 401f41a42a..cedb406197 100644 --- a/modules/extensions/partials/proc_authenticating-with-openshift-connector-from-che.adoc +++ b/modules/extensions/partials/proc_authenticating-with-openshift-connector-from-che.adoc @@ -33,20 +33,18 @@ To work around this issue: . Log in to OpenShift cluster using the OpenShift user's credentials. ==== -ifeval::["{project-context}" == "che"] -When using a local instance of OpenShift such as CodeReady Containers or Minishift, {prod-short} stores the user’s credentials in a `~/.kube/config` file in the workspace. Use this file for automatic authentication in subsequent logins. In the context of {prod-short}, the `~/.kube/config` is stored as a part of the plug-in sidecar container. -endif::[] +include::example$snip_{project-context}-authenticating-with-openshift-connector-from-a-local-instance.adoc[] + .Prerequisites -* A running instance of {prod-short}. See xref:installation-guide:installing-che.adoc[]. +* A running instance of {prod-short}. -* A {prod-short} workspace is available. See xref:end-user-guide:workspaces-overview.adoc[]. +* A {prod-short} workspace is available. * The OpenShift Connector plug-in is available. See xref:installing-openshift-connector-in-che.adoc[]. -* The OpenShift OAuth provider is available only for the auto-login to the OpenShift instance containing {prod-short}. See xref:administration-guide:configuring-openshift-oauth.adoc[]. - +* The OpenShift OAuth provider is available only for the auto-login to the OpenShift instance containing {prod-short}. .Procedure diff --git a/modules/extensions/partials/proc_connecting-source-code-from-github-to-a-openshift-component-using-openshift-connector.adoc b/modules/extensions/partials/proc_connecting-source-code-from-github-to-a-openshift-component-using-openshift-connector.adoc index 70d992b498..0f2b09a729 100644 --- a/modules/extensions/partials/proc_connecting-source-code-from-github-to-a-openshift-component-using-openshift-connector.adoc +++ b/modules/extensions/partials/proc_connecting-source-code-from-github-to-a-openshift-component-using-openshift-connector.adoc @@ -22,4 +22,3 @@ To make changes to your GitHub component, clone the repository into {prod-short} . Provide the GitHub URL and select the destination for the deployment. . Add source-code files to your Project using the btn:[Add to workspace] button. -For additional information about cloning Git repository, see: {link-accessing-a-git-repository-via-https}. diff --git a/modules/extensions/partials/proc_creating-a-telemetry-plugin.adoc b/modules/extensions/partials/proc_creating-a-telemetry-plugin.adoc deleted file mode 100644 index bc03b7861b..0000000000 --- a/modules/extensions/partials/proc_creating-a-telemetry-plugin.adoc +++ /dev/null @@ -1,275 +0,0 @@ -[id="creating-a-telemetry-plugin_{context}"] -= Creating A Telemetry Plug-in - -This section shows how to create an `AnalyticsManager` class that extends link:https://github.com/che-incubator/che-workspace-telemetry-client/blob/master/backend-base/src/main/java/org/eclipse/che/incubator/workspace/telemetry/base/AbstractAnalyticsManager.java[`AbstractAnalyticsManager`] and implements the following methods: - -* `isEnabled()` - determines whether the telemetry back-end is functioning correctly. This could mean always returning `true`, or have more complex checks, for example, returning `false` when a connection property is missing. -* `destroy()` - cleanup method that is run before shutting down the telemetry back-end. This method sends the `WORKSPACE_STOPPED` event. -* `onActivity()` - notifies that some activity is still happening for a given user. This is mainly used to send `WORKSPACE_INACTIVE` events. -* `onEvent()` - submits telemetry events to the telemetry server, such as `WORKSPACE_USED` or `WORKSPACE_STARTED`. -* `increaseDuration()` - increases the duration of a current event rather than sending multiple events in a small frame of time. - -The following sections cover: - -* Creation of a telemetry server to echo events to standard output. -* Extending the {prod-short} telemetry client and implementing a user's custom back-end. -* Creating a `meta.yaml` file representing a {prod-short} workspace plug-in for a user's custom back-end. -* Specifying of a location of a custom plug-in to {prod-short} by setting the `CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR_PLUGINS` environment variable. - -== Getting Started - -This document describes the steps required to extend the {prod-short} telemetry system to connect to a custom back-end: - -. Creating a server process that receives events -. Extending {prod-short} libraries to create a back-end that send events to the server -. Packaging the telemetry back-end in a container and deploying it to an image registry -. Adding a plug-in for your back-end and instructing {prod-short} to load the plug-in in your workspaces - -[discrete] -== Optional: creating a server that receives events - -This example shows how to create a server that receives events from {prod-short} and writes them to standard output. - -For production use cases, consider integrating with a third-party telemetry system (for example, Segment, Woopra) rather than creating your own telemetry server. In this case, use your provider's APIs to send events from your custom back-end to their system. - -The following Go code starts a server on port 8080 and writes events to standard output: - -.`main.go` -==== -[source,go] ----- -include::example$telemetry/main.go[] ----- -==== - -Create a container image based on this code and expose it as a deployment in OpenShift in the {prod-namespace} {orch-namespace}. The code for the example telemetry server is available at link:https://github.com/che-incubator/che-workspace-telemetry-example[che-workspace-telemetry-example]. To deploy the telemetry server, clone the repository and build the container: - ----- -$ git clone https://github.com/che-incubator/che-workspace-telemetry-example -$ cd che-workspace-telemetry-example -$ docker build -t registry/organization/che-workspace-telemetry-example:latest . -$ docker push registry/organization/che-workspace-telemetry-example:latest ----- - -In `manifest.yaml`, replace the `image` and `host` fields to match the image you pushed, and the public host name of your {platforms-name} cluster. Then run: - -[subs="+quotes"] ----- -$ kubectl apply -f manifest.yaml -n {prod-namespace} ----- - -== Creating a new Maven project - -NOTE: For fast feedback when developing, it is recommended to do development inside a {prod-short} workspace. This way, you can run the application in a cluster and connect to the workspaces front-end telemetry plug-in to send events to your custom back-end. - -. Create a new Maven Quarkus project scaffolding: -+ ----- -$ mvn io.quarkus:quarkus-maven-plugin:1.2.1.Final:create \ - -DprojectGroupId=mygroup -DprojectArtifactId=telemetryback-end \ - -DprojectVersion=my-version -DclassName="org.my.group.MyResource" ----- - -. Add a dependency to `org.eclipse.che.incubator.workspace-telemetry.back-end-base` in your `pom.xml`: -+ -.`pom.xml` -==== -[source,xml] ----- -include::example$telemetry/pom_snippet.xml[] ----- -==== - -. Add the Apache HTTP components library to send HTTP requests. - -. Consult the link:https://github.com/che-incubator/che-workspace-telemetry-client/packages[GitHub packages] for the latest version and Maven coordinates of `back-end-base`. link:https://help.github.com/en/packages/publishing-and-managing-packages/about-github-packages[GitHub packages] require a personal access token with `read:packages` permissions to download the {prod-short} telemetry libraries. Create a personal access token and copy the token value. - -. Create a `settings.xml` file in the repository root and add the coordinates and token to the `che-incubator` packages: -+ -.`settings.xml` -==== -[source,xml] ----- -include::example$telemetry/settings.xml[] ----- -==== -+ -This file is used when packaging the application in a container. When running locally, add the information to your personal `settings.xml` file. - -[id="running-the-application_{context}"] -== Running the application - -Run and test the application is in a {prod-short} workspace: - ----- -$ mvn quarkus:dev -Dquarkus.http.port=${CHE_WORKSPACE_TELEMETRY_BACKEND_PORT} ----- - -If {prod-short} is secured using a self-signed certificate, add the certificate to a trust store and mount it into the workspace. Also add the Java system property, `-Djavax.net.ssl.trustStore=/path/to/trustStore`, to the `mvn` command. For example, assuming the trust store is located in `$JAVA_HOME/jre/lib/security/cacerts`: - -[subs="+quotes"] ----- -$ keytool -import -alias self-signed-certificate \ - -file _<path/to/self-signed-certificate>_ -keystore $JAVA_HOME/jre/lib/security/cacerts ----- - -Followed by: - ----- -$ mvn quarkus:dev -Dquarkus.http.port=${CHE_WORKSPACE_TELEMETRY_BACKEND_PORT} \ - -Djavax.net.ssl.trustStore=$JAVA_HOME/jre/lib/security/cacerts ----- - -== Creating a concrete implementation of AnalyticsManager and adding specialized logic - -Create two new files in your project: - -* `AnalyticsManager.java` - contains the logic specific to the telemetry system. -* `MainConfiguration.java` - is the main entrypoint that creates an instance of `AnalyticsManager` and starts listening for events. - -.`AnalyticsManager.java` -==== -[source,java] ----- -include::example$telemetry/AnalyticsManagerSkeleton.java[] ----- -==== - -.`MainConfiguration.java` -==== -[source,java] ----- -include::example$telemetry/MainConfiguration.java[] ----- -==== - -== Implementing `isEnabled()` - -For the purposes of the example, this method just returns `true` whenever it is called. Whenever the server is running, it is enabled and operational. - -.`AnalyticsManager.java` -==== -[source,java] ----- -include::example$telemetry/isEnabled.java[] ----- -==== - -It is possible to put more a complex login in `isEnabled()`. For example, the service should not be considered operational in certain cases. The link:https://github.com/redhat-developer/che-workspace-telemetry-woopra-backend/blob/master/src/main/java/com/redhat/che/workspace/services/telemetry/woopra/AnalyticsManager.java[hosted {prod-short} woopra back-end] checks that a configuration property exists before determining if the back-end is enabled. - -== Implementing `onEvent()` - -`onEvent()` sends the event passed to the back-end to the telemetry system. For the example application, it sends an HTTP POST payload to the telemetry server. The example telemetry server application is deployed to OpenShift at the following URL: `++http://little-telemetry-back-end-che.apps-crc.testing++`. - -.`AnalyticsManager.java` -==== -[source,java] ----- -include::example$telemetry/onEvent.java[] ----- -==== - -This sends an HTTP request to the telemetry server and automatically delays identical events for a small period of time. The default duration is 1500 milliseconds. You can modify the duration by setting subclasses. - -== Implementing `increaseDuration()` - -Many telemetry systems recognize event duration. The `AbstractAnalyticsManager` merges similar events that happen in the same frame of time into one event. This implementation of `increaseDuration()` is a no-op. This method uses the APIs of the user's telemetry provider to alter the event or event properties to reflect the increased duration of an event. - -.`AnalyticsManager.java` -==== -[source,java] ----- -include::example$telemetry/increaseDuration.java[] ----- -==== - -== Implementing `onActivity()` - -Set an inactive timeout limit, and use `onActivity()` to send a `WORKSPACE_INACTIVE` event if the last event time is longer than the inactivity timeout. - -.`AnalyticsManager.java` -==== -[source,java] ----- -include::example$telemetry/onActivity.java[] ----- -==== - -== Implementing `destroy()` - -When `destroy()` is called, send a `WORKSPACE_STOPPED` event and shutdown any resources, such as connection pools. - -.`AnalyticsManager.java` -==== -[source,java] ----- -include::example$telemetry/destroy.java[] ----- -==== - -Running `mvn quarkus:dev` as described in xref:running-the-application_{context}[] displays the `WORKSPACE_STOPPED` event, sent to the server when the Quarkus application is terminated. - -== Packaging the Quarkus application - -See link:https://quarkus.io/guides/building-native-image#using-a-multi-stage-docker-build[the quarkus documentation] for the best instructions to package the application in a container. Build and push the container to a container registry of your choice. - -== Creating a `meta.yaml` for your plug-in - -Create a `meta.yaml` definition representing a {prod-short} plug-in that runs your custom back-end in a workspace Pod. For more information about `meta.yaml`, see xref:end-user-guide:what-is-a-che-theia-plug-in.adoc[]. - -.meta.yaml -==== -[source,yaml] ----- -include::example$telemetry/sample_meta.yaml[] ----- -==== - -Typically, the user deploys this file to a corporate web server. This guide demonstrates how to create an Apache web server on OpenShift and host the plug-in there. - -Create a ConfigMap referencing the new `meta.yaml` file. - -[subs="+attributes"] ----- -$ oc create configmap --from-file=meta.yaml -n {prod-namespace} telemetry-plugin-meta ----- - -Create a deployment, a service, and a route to expose the web server. The deployment references this ConfigMap and places it in the `/var/www/html` directory. - -.`manifests.yaml` -==== -[source,yaml,subs="+quotes,+attributes"] ----- -include::example$telemetry/webserver.yaml[] ----- -==== - ----- -$ oc apply -f manifests.yaml ----- - -Wait a few minutes for the image to pull and the deployment to start, and then confirm that `meta.yaml` is available in the web server: - ----- -$ curl apache-che.apps-crc.testing/meta.yaml ----- - -This command should return the `meta.yaml` file. - -== Updating {prod-short} to reference your telemetry plug-in - -Update the `CheCluster` Custom Resource, and add the `CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR_PLUGINS` environment variable to `spec.server.customCheProperties`. The value of the environment variable must be the URL of the location of the `meta.yaml` file on your web server. This can be accomplished by running `oc edit checluster -n {prod-namespace}` and typing in the change at the terminal, or by editing the CR in the OpenShift console (*Installed Operators -> {prod} -> {prod} Cluster -> {prod-checluster} -> YAML*). - -.Example of a YAML file -==== -[source,yaml,subs="+quotes,+attributes"] ----- -include::example$telemetry/che_cluster_with_custom_plugin.yaml[] ----- -==== - -Wait for the {prod-short} server to restart, and create a new workspace. See a new message stating that the plug-in is being installed into the workspace. - -image::telemetry/custom_telemetry_plugin.png[] - -Perform any operations in the started workspace and observe their events in the example telemetry server logs. diff --git a/modules/extensions/partials/proc_creating-components-with-openshift-connector-in-che.adoc b/modules/extensions/partials/proc_creating-components-with-openshift-connector-in-che.adoc index 7dab2d8b5f..b200e0e3e5 100644 --- a/modules/extensions/partials/proc_creating-components-with-openshift-connector-in-che.adoc +++ b/modules/extensions/partials/proc_creating-components-with-openshift-connector-in-che.adoc @@ -11,7 +11,7 @@ This chapter describes how to create OpenShift Components in the {prod-short} us .Prerequisites -* A running instance of {prod-short}. To install an instance of {prod-short}, see xref:installation-guide:installing-che.adoc[]. +* A running instance of {prod-short}. * The user is logged in to an OpenShift cluster using the OpenShift Connector plug-in. .Procedure diff --git a/modules/extensions/partials/proc_installing-openshift-connector-in-che.adoc b/modules/extensions/partials/proc_installing-openshift-connector-in-che.adoc index bfde4928b7..00b9ced2ba 100644 --- a/modules/extensions/partials/proc_installing-openshift-connector-in-che.adoc +++ b/modules/extensions/partials/proc_installing-openshift-connector-in-che.adoc @@ -12,10 +12,14 @@ To install and enable OpenShift Connector in a {prod-short} instance, use instru .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. +* A running instance of {prod}. .Procedure +// "Plugins" in the UI. +pass:[<!-- vale RedHat.TermsErrors = NO -->] + + Install OpenShift Connector in {prod-short} by adding it as an extension in the {prod-short} *Plugins* panel. . Open the *{prod-short} Plugins* panel by pressing kbd:[Ctrl+Shift+J] or by navigating to *View -> Plugins*. diff --git a/modules/extensions/partials/proc_java-lombok.adoc b/modules/extensions/partials/proc_java-lombok.adoc deleted file mode 100644 index 019c9a784e..0000000000 --- a/modules/extensions/partials/proc_java-lombok.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="proc_java-lombok_{context}"] -= Java Lombok - -This section shows how to enable Lombok support in your Java projects. By default, the `lombok.jar` file is available in all Java plug-ins provided by {prod-short}. - -To enable Lombok in a {prod-short} workspace, see the instructions below. - - -.Prerequisites - -* A workspace or a devfile with: - -** One of the Java-based plug-ins enabled (`redhat/java`, `redhat/java11`, `redhat/java8`, `redhat/quarkus-java8` or `redhat/quarkus-java11`) -** A valid Lombok project to import - -.Procedure - -. Open the workspace devfile. -. Edit the existing Java plug-in section, adding the preference: -+ -[source,yaml,attrs="nowrap"] ----- - - id: redhat/java/latest - preferences: - java.jdt.ls.vmargs: '-javaagent:/lombok.jar' ----- - - -.Verification - -. Start or restart the workspace. - -. Open a file containing Lombok annotations. - -. Verify that the Class outline contains the Lombok generated methods. -+ -image::lombok/lombok.png[Lombok] - - -.Additional resources - -* For more details, see the link:https://projectlombok.org/[Project Lombok] website. diff --git a/modules/extensions/partials/ref_the-woopra-telemetry-plugin.adoc b/modules/extensions/partials/ref_the-woopra-telemetry-plugin.adoc deleted file mode 100644 index 1b1ece8dc3..0000000000 --- a/modules/extensions/partials/ref_the-woopra-telemetry-plugin.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="the-woopra-telemetry-plugin"] - -= The Woopra Telemetry Plugin - -The link:https://github.com/che-incubator/che-workspace-telemetry-woopra-plugin[Woopra Telemetry Plugin] is a plugin built to send telemetry from a {prod} installation to Segment and Woopra. This plugin is used by link:https://workspaces.openshift.com[Eclipse Che hosted by Red Hat], but any {prod} deployment can take advantage of this plugin. There are no dependencies other than a valid Woopra domain and Segment Write key. The link:https://raw.githubusercontent.com/che-incubator/che-workspace-telemetry-woopra-plugin/master/meta.yaml[plugin's meta.yaml] file has 5 environment variables that can be passed to the plugin: - -- `WOOPRA_DOMAIN` - The Woopra domain to send events to. -- `SEGMENT_WRITE_KEY` - The write key to send events to Segment and Woopra. -- `WOOPRA_DOMAIN_ENDPOINT` - If you prefer not to pass in the Woopra domain directly, the plugin will get it from a supplied HTTP endpoint that returns the Woopra Domain. -- `SEGMENT_WRITE_KEY_ENDPOINT` - If you prefer not to pass in the Segment write key directly, the plugin will get it from a supplied HTTP endpoint that returns the Segment write key. - -To enable the Woopra plugin on the {prod} installation, deploy the `meta.yaml` file to an HTTP server with the environment variables set correctly. Then, edit the `CheCluster` Custom Resource, and set the `spec.server.customCheProperties.CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR_PLUGINS` field: - -[source,yaml] ----- -spec: - server: - customCheProperties: - CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR_PLUGINS: 'eclipse/che-machine-exec-plugin/7.20.0,https://your-web-server/meta.yaml' ----- \ No newline at end of file diff --git a/modules/glossary/partials/con_glossary.adoc b/modules/glossary/partials/con_glossary.adoc index 22da45180b..7b59085852 100644 --- a/modules/glossary/partials/con_glossary.adoc +++ b/modules/glossary/partials/con_glossary.adoc @@ -12,21 +12,21 @@ This section provides an overview of the main terms and expressions used through == Naming {prod}:: A developer platform for the cloud that provides an in-browser IDE. {prod-short} tools can be extended by adding development services, such as language servers, debug adapters, or editors (IDEs) packaged as containers. -Che-Theia:: The default editor component of a {prod-short} workspace. It is a {prod-short}-specific customization of the Eclipse Theia editor. Che-Theia can be extended using Che-Theia plugins, which are packaged as containers for ease of deployment and use. Che-Theia plugins are usually compatible with Visual Studio extensions. +Che-Theia:: The default editor component of a {prod-short} workspace. It is a {prod-short}-specific customization of the Eclipse Theia editor. Che-Theia can be extended using Che-Theia plug-ins, which are packaged as containers for ease of deployment and use. Che-Theia plug-ins are usually compatible with Visual Studio extensions. {prod-short} Workspace:: A container-based development environment managed by {prod}. Every {prod-short} workspace is defined by a devfile. A {prod-short} workspace is composed of an editor, runtime and build containers and other development tools running inside containers. == Terminology -Editor:: A web application that is used as an editor in a workspace. +`Editor`:: A web application that is used as an editor in a workspace. -Plugin:: Plugins are services that extend {prod-short} workspace capabilities. {prod-short} plugins are packaged as containers. Plugins are extensions of an editor or a service running in the container. For example, the Che-Theia editor is compatible with Visual Studio Code extensions. +`Plugin`:: Plug-ins are services that extend {prod-short} workspace capabilities. {prod-short} plug-ins are packaged as containers. plug-ins are extensions of an editor or a service running in the container. For example, the Che-Theia editor is compatible with Visual Studio Code extensions. //TODO See for a diagram of {prod-short} extensibility architecture. -Both {prod-short} plugins and editors are distributed through the {prod-short} plug-ins registry. +Both {prod-short} plug-ins and editors are distributed through the {prod-short} plug-ins registry. -Workspace:: A container based development environment managed by {prod}. Every {prod-short} workspace is defined by a devfile. A {prod-short} workspace can be composed by an editor, some plugins and runtime containers. Workspace runtime containers can be defined as simple container images or as {platforms-name} resources. A {prod-short} Workspace can be associated with source code projects hosted on a remote CVS server. A {prod-short} Workspace can contain the definition of one or more commands such as `run`, `build`, or `debug`. +Workspace:: A container-based development environment managed by {prod}. Every {prod-short} workspace is defined by a devfile. A {prod-short} workspace can be composed by an editor, some plug-ins and runtime containers. Workspace runtime containers can be defined as simple container images or as {platforms-name} resources. A {prod-short} Workspace can be associated with source code projects hosted on a remote CVS server. A {prod-short} Workspace can contain the definition of one or more commands such as `run`, `build`, or `debug`. -Devfile:: A workspace configuration template. Devfiles are used to create workspaces in the Dashboard. A devfile includes metadata such as scope, tags, components, description, name, and identification. VS Code API is one of the plugin APIs that can be used in Theia. +Devfile:: A workspace configuration template. Devfiles are used to create workspaces in the Dashboard. A devfile includes metadata such as scope, tags, components, description, name, and identification. Visual Studio Code API is one of the plug-in APIs that can be used in Theia. Factory:: A template that contains the configuration to automate the generation of a new workspace using a factory identifier or a devfile added to the URL of the IDE. Use factories to create replicas of existing workspaces or to automate the provisioning of statically or dynamically defined workspaces. diff --git a/modules/hosted-che/images/hosted-che/getting-started-devfile.png b/modules/hosted-che/images/hosted-che/getting-started-devfile.png index e4f25040e4..255005fdeb 100644 Binary files a/modules/hosted-che/images/hosted-che/getting-started-devfile.png and b/modules/hosted-che/images/hosted-che/getting-started-devfile.png differ diff --git a/modules/hosted-che/images/hosted-che/unblock_third_party_cookies.png b/modules/hosted-che/images/hosted-che/unblock_third_party_cookies.png index ed9e9d59b5..2b21620895 100644 Binary files a/modules/hosted-che/images/hosted-che/unblock_third_party_cookies.png and b/modules/hosted-che/images/hosted-che/unblock_third_party_cookies.png differ diff --git a/modules/hosted-che/partials/assembly_hosted-che.adoc b/modules/hosted-che/partials/assembly_hosted-che.adoc index 5cca51c629..d81c36b02f 100644 --- a/modules/hosted-che/partials/assembly_hosted-che.adoc +++ b/modules/hosted-che/partials/assembly_hosted-che.adoc @@ -23,6 +23,6 @@ include::partial$ref_hosted-che-faq-and-troubleshooting.adoc[leveloffset=+1] .Additional resources -* For general end-user guidance, see xref:end-user-guide:workspaces-overview.adoc[]. +* For general end-user guidance, see xref:end-user-guide:using-developer-workspaces.adoc[]. :context: {parent-context-of-hosted-che} diff --git a/modules/hosted-che/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc b/modules/hosted-che/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc index 641fe4227f..1a45cf65e8 100644 --- a/modules/hosted-che/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc +++ b/modules/hosted-che/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc @@ -10,7 +10,7 @@ This section describes how to integrate the Try in Web IDE GitHub action to a Gi .Prerequisites * A GitHub repository -* A xref:end-user-guide:authoring-devfiles-version-1.adoc[devfile] in the root of the GitHub repository (see xref:providing-a-devfile_{context}[Providing a devfile]) +* A devfile in the root of the GitHub repository. .Procedure @@ -20,7 +20,7 @@ This section describes how to integrate the Try in Web IDE GitHub action to a Gi + include::example$snip_github-action-yaml-example.adoc[] This code snippet creates a workflow named `Try in Web IDE example`, with a job that runs the `v1` version of the `redhat-actions/try-in-web-ide` community action. -The workflow is triggered on the link:https://docs.github.com/en/actions/reference/events-that-trigger-workflows[`pull_request_target` event], +The workflow is triggered on the link:https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows[`pull_request_target` event], on the `opened` activity type. . Optionally configure the activity types from the `on.pull_request_target.types` field to customize when workflow trigger. Activity types such as `reopened` and `synchronize` can be useful. diff --git a/modules/hosted-che/partials/proc_contributing-to-github-projects-in-hosted-che.adoc b/modules/hosted-che/partials/proc_contributing-to-github-projects-in-hosted-che.adoc index b886a02035..6619f4576d 100644 --- a/modules/hosted-che/partials/proc_contributing-to-github-projects-in-hosted-che.adoc +++ b/modules/hosted-che/partials/proc_contributing-to-github-projects-in-hosted-che.adoc @@ -17,4 +17,4 @@ This section describes how to contribute to GitHub projects from Eclipse Che hos . Generate an SSH key pair with the link:https://github.com/eclipse-che/che-theia/tree/master/plugins/ssh-plugin[SSH Plug-in]. -. Upload the public key to the GitHub account. For details, see the link:https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account[Adding a new SSH key to your GitHub account] procedure. +. Upload the public key to the GitHub account. For details, see the link:https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account[Adding a new SSH key to your GitHub account] procedure. diff --git a/modules/hosted-che/partials/proc_creating-a-workspace-from-template-in-hosted-che.adoc b/modules/hosted-che/partials/proc_creating-a-workspace-from-template-in-hosted-che.adoc index 51c8beb5b4..537d577013 100644 --- a/modules/hosted-che/partials/proc_creating-a-workspace-from-template-in-hosted-che.adoc +++ b/modules/hosted-che/partials/proc_creating-a-workspace-from-template-in-hosted-che.adoc @@ -17,13 +17,7 @@ Various programming languages and frameworks are supported. . Navigate to the link:https://www.eclipse.org/che/getting-started/cloud/[templates registry]. -. Choose the required type of a workspace. - -pass:[<!-- vale IBM.Terms = NO -->] - -. Click the btn:[Launch Workspace] button. - -pass:[<!-- vale IBM.Terms = YES -->] +. Choose the required type of a workspace and click on the dedicated template icon. The workspace is created and displayed in the Eclipse Che hosted by Red hat. diff --git a/modules/hosted-che/partials/proc_creating-a-workspace-from-the-user-dashboard.adoc b/modules/hosted-che/partials/proc_creating-a-workspace-from-the-user-dashboard.adoc index cadd6ce643..55bb5d4a0a 100644 --- a/modules/hosted-che/partials/proc_creating-a-workspace-from-the-user-dashboard.adoc +++ b/modules/hosted-che/partials/proc_creating-a-workspace-from-the-user-dashboard.adoc @@ -16,10 +16,7 @@ This section describes how to create a workspace from the user dashboard in Ecli . Navigate to link:https://workspaces.openshift.com[`workspaces.openshift.com`]. -. Once login, the redirect to the user dashboard will happen. +. After logging in, you will be redirected to the user dashboard. -. Click the btn:[Add Workspace] button and create a "Custom Workspace" using Devfile, or choose the "Get Started" tab, and pick one of the existing samples. +. Click the btn:[Create Workspace] menu item and create a "Custom Workspace" using a devfile, or use the default "Quick Add" tab, and select one of the existing samples. -.Additional resources - -* For more details, see xref:end-user-guide:workspaces-overview.adoc[]. diff --git a/modules/hosted-che/partials/proc_providing-a-devfile.adoc b/modules/hosted-che/partials/proc_providing-a-devfile.adoc index 8deb508090..a46a24780b 100644 --- a/modules/hosted-che/partials/proc_providing-a-devfile.adoc +++ b/modules/hosted-che/partials/proc_providing-a-devfile.adoc @@ -5,7 +5,7 @@ [id="providing-a-devfile_{context}"] = Providing a devfile -Providing a xref:end-user-guide:authoring-devfiles-version-1.adoc[devfile] in the root of the repository is recommended to define the development environment of the workspace created by the factory URL. -This ensures that the workspace contains everything users need to effectively review the pull request, such as plug-ins, development commands, and other environment setup. +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 plug-ins, development commands, and other environment setup. -The link:https://github.com/eclipse/che-docs/blob/master/devfile.yaml[Che documentation repository devfile] is an example of a well-defined and effective devfile to start workspaces from. +The link:https://github.com/eclipse/che-docs/blob/master/devfile.yaml[Che documentation repository devfile] is an example of a well-defined and effective devfile. diff --git a/modules/hosted-che/partials/ref_about-hosted-che.adoc b/modules/hosted-che/partials/ref_about-hosted-che.adoc index 80d8b06824..99f72510eb 100644 --- a/modules/hosted-che/partials/ref_about-hosted-che.adoc +++ b/modules/hosted-che/partials/ref_about-hosted-che.adoc @@ -6,12 +6,12 @@ [id="about-hosted-che_{context}"] = About Eclipse Che hosted by Red Hat -Eclipse Che hosted by Red Hat is an open-source product based on link:https://www.eclipse.org/che/[Eclipse {prod-short}] that is running on link:https://www.openshift.com/products/dedicated/[OpenShift Dedicated]. +Eclipse Che hosted by Red Hat is an open source product based on link:https://www.eclipse.org/che/[Eclipse {prod-short}] that is running on link:https://www.openshift.com/products/dedicated/[OpenShift Dedicated]. The new service is part of the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox for Red Hat OpenShift] offering, and is using link:https://developers.redhat.com/products/codeready-workspaces/overview[CodeReady Workspaces], which is built upon Eclipse Che and is optimized for Red Hat OpenShift and Red Hat Linux. == Differences between Eclipse Che and CodeReady Workspaces -Red Hat CodeReady Workspaces is the product that is built from the Eclipse Che project. The product is normally two versions behind the project. Red Hat also provides licensing, packaging, and support, so CodeReady Workspaces is considered a more stable product than the upstream Eclipse Che project. More details about the difference between Eclipse Che and Red Hat CodeReady Workspaces can be found on the official link:https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.8/html/release_notes_and_known_issues/installing_and_deploying_codeready_workspaces#difference-between-che-and-codready-workspaces[documentation]. +Red Hat CodeReady Workspaces is the product that is built from the Eclipse Che project. The product is normally two versions behind the project. Red Hat also provides licensing, packaging, and support, so CodeReady Workspaces is considered a more stable product than the upstream Eclipse Che project. See link:https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.14/html/release_notes_and_known_issues/about-codeready-workspaces_crw[About Red Hat CodeReady Workspaces]. NOTE: link:https://workspaces.openshift.com/[Eclipse Che hosted by Red Hat] provides both CodeReady Workspaces product-specific, as well as, Eclipse Che community devfiles on the "Get Started" tab of the User Dashboard. @@ -19,7 +19,7 @@ image::hosted-che/get-started-product-and-community-devfiles.png[] [IMPORTANT] ==== -Eclipse Che and Red Hat CodeReady Workspaces share all the features - all the product's functionality is available in the project and vice versa. However, not all the upstream plugins are available in the CodeReady Workspaces. To use an unsupported plugin inside the CodeReady Workspaces, one must explicitly point to the raw `meta.yaml` of the plugin from the devfile. The procedure is described in the xref:end-user-guide:adding-a-vs-code-extension-to-a-workspace.adoc#adding-the-vs-code-extension-using-the-workspace-configuration_che[Adding a VS Code extension using the workspace configuration] section. +Eclipse Che and Red Hat CodeReady Workspaces share all the features - all the product's functionality is available in the project and vice versa. However, not all the upstream plug-ins are available in the CodeReady Workspaces. To use an unsupported plug-in inside the CodeReady Workspaces, one must explicitly point to the raw `meta.yaml` of the plug-in from the devfile. ==== [id="terms-of-service_{context}"] diff --git a/modules/hosted-che/partials/ref_about-try-in-web-ide-github-action.adoc b/modules/hosted-che/partials/ref_about-try-in-web-ide-github-action.adoc index 900342a774..4dbc520d57 100644 --- a/modules/hosted-che/partials/ref_about-try-in-web-ide-github-action.adoc +++ b/modules/hosted-che/partials/ref_about-try-in-web-ide-github-action.adoc @@ -6,8 +6,8 @@ [id="about-try-on-web-ide-github-action_{context}"] 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 link:https://www.eclipse.org/che/docs/che-7/end-user-guide/creating-a-workspace-from-remote-devfile/#creating-a-workspace-from-the-default-branch-of-a-git-repository_che[factory URL] by creating a comment, a status check, or both. -This factory URL creates a new workspace (link:https://www.eclipse.org/che/docs/che-7/end-user-guide/creating-a-workspace-from-remote-devfile/#creating-a-workspace-from-a-feature-branch-of-a-git-repository_che[from the pull request branch]) 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. diff --git a/modules/hosted-che/partials/ref_hosted-che-faq-and-troubleshooting.adoc b/modules/hosted-che/partials/ref_hosted-che-faq-and-troubleshooting.adoc index aca719e2fb..acfa6b6dff 100644 --- a/modules/hosted-che/partials/ref_hosted-che-faq-and-troubleshooting.adoc +++ b/modules/hosted-che/partials/ref_hosted-che-faq-and-troubleshooting.adoc @@ -3,12 +3,12 @@ // hosted-che -[id="hosted-che-faq-and-troubleshooting_{context}"] +[id="hosted-{prod-id-short}-faq-and-troubleshooting_{context}"] = Frequently Asked Questions (FAQs) and Troubleshooting == FAQs -Eclipse Che hosted by Red Hat is part of the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox for Red Hat OpenShift] offering. +IMPORTANT: Eclipse Che hosted by Red Hat is part of the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox for Red Hat OpenShift] offering. The common FAQs are available on the link:https://developers.redhat.com/developer-sandbox#assembly-field-sections-57861[Developer Sandbox for Red Hat OpenShift] website. == Troubleshooting diff --git a/modules/installation-guide/attachments/.placeholder b/modules/installation-guide/attachments/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/installation-guide/examples/.placeholder b/modules/installation-guide/examples/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/installation-guide/examples/ref_che-supported-platforms-and-installation-methods.adoc b/modules/installation-guide/examples/ref_che-supported-platforms-and-installation-methods.adoc deleted file mode 100644 index 60dd8de4f7..0000000000 --- a/modules/installation-guide/examples/ref_che-supported-platforms-and-installation-methods.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// supported_platforms - -The following section provides information about the availability of {prod-short} {prod-ver} on {platforms-name} infrastructures, and about their supported installation methods. - -{prod} can be installed on: - -* {kubernetes} infrastructures starting at version {kube-ver-min} -* {ocp} versions 3.11, 4.3, and 4.4 - -The following options are available: - -.Local installation on {kubernetes} -[options="header",cols="2*.^"] -|=== -|{kubernetes} -|Installation method - -a|* `minikube` -* `microk8s` -* `docker-desktop` -* `kind` -|`{prod-cli}` using the Operator -|=== - -.Local installation on OpenShift -[options="header",cols="2,2"] -|=== -|{ocp} -|Installation method - -|CodeReady Containers -|OperatorHub -|=== - -.Public cloud installation on {platforms-name} -[options="header",cols="25,25,25,25"] -|=== -| -|{kubernetes} + -{kube-ver-min} or higher -|{ocp} + -3.11 -|{ocp} + -4.3 and 4.4 - -a|* Microsoft Azure -* Amazon Web Services -* Google Cloud -* IBM Cloud -.^|`{prod-cli}` using the Operator -.^|`{prod-cli}` using the Operator -.^|OperatorHub -|=== - -It is possible to use the `{prod-cli}` utility for deploying {prod-short} on {ocp} version 4.3 and 4.4. This method is considered unofficial and serves as a backup installation method for situations where installation using OperatorHub is not available. - -//// -Starting with the {prod-short} version 7.14, the `{prod-cli}` acts as secondary supported and official installation method that serves also as an backup installation method for situations where the installation method using OperatorHub is not available. -//// - -.Additional resources - -* xref:installing-che.adoc[] diff --git a/modules/installation-guide/images/.placeholder b/modules/installation-guide/images/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/installation-guide/images/installation/adding-a-record-set.png b/modules/installation-guide/images/installation/adding-a-record-set.png deleted file mode 100644 index ee3138d895..0000000000 Binary files a/modules/installation-guide/images/installation/adding-a-record-set.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/aws-create-policy.png b/modules/installation-guide/images/installation/aws-create-policy.png deleted file mode 100644 index 89abca14da..0000000000 Binary files a/modules/installation-guide/images/installation/aws-create-policy.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/aws-hosted-zones-dns.png b/modules/installation-guide/images/installation/aws-hosted-zones-dns.png deleted file mode 100644 index 2d30c512a3..0000000000 Binary files a/modules/installation-guide/images/installation/aws-hosted-zones-dns.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/aws-lauch-instance.png b/modules/installation-guide/images/installation/aws-lauch-instance.png deleted file mode 100644 index 99cfafe53d..0000000000 Binary files a/modules/installation-guide/images/installation/aws-lauch-instance.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/aws-summary-iam-role.png b/modules/installation-guide/images/installation/aws-summary-iam-role.png deleted file mode 100644 index 357ab33791..0000000000 Binary files a/modules/installation-guide/images/installation/aws-summary-iam-role.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/cloud-dns-zone-on-gcp.png b/modules/installation-guide/images/installation/cloud-dns-zone-on-gcp.png deleted file mode 100644 index af6bd982c3..0000000000 Binary files a/modules/installation-guide/images/installation/cloud-dns-zone-on-gcp.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/completing-the-creation-of-the-zone.png b/modules/installation-guide/images/installation/completing-the-creation-of-the-zone.png deleted file mode 100644 index c45629b90d..0000000000 Binary files a/modules/installation-guide/images/installation/completing-the-creation-of-the-zone.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/create-policy-review-policy.png b/modules/installation-guide/images/installation/create-policy-review-policy.png deleted file mode 100644 index da03f60881..0000000000 Binary files a/modules/installation-guide/images/installation/create-policy-review-policy.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/create-policy-review.png b/modules/installation-guide/images/installation/create-policy-review.png deleted file mode 100644 index e82be0675d..0000000000 Binary files a/modules/installation-guide/images/installation/create-policy-review.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/create-record-set-all-values.png b/modules/installation-guide/images/installation/create-record-set-all-values.png deleted file mode 100644 index 49146e53ec..0000000000 Binary files a/modules/installation-guide/images/installation/create-record-set-all-values.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/create-record-set.png b/modules/installation-guide/images/installation/create-record-set.png deleted file mode 100644 index d679f6745d..0000000000 Binary files a/modules/installation-guide/images/installation/create-record-set.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/creating-dns-zone-on-gcp.png b/modules/installation-guide/images/installation/creating-dns-zone-on-gcp.png deleted file mode 100644 index 8a95b49fb7..0000000000 Binary files a/modules/installation-guide/images/installation/creating-dns-zone-on-gcp.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/describtion-tab-iam-role.png b/modules/installation-guide/images/installation/describtion-tab-iam-role.png deleted file mode 100644 index f496e933ad..0000000000 Binary files a/modules/installation-guide/images/installation/describtion-tab-iam-role.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/dns-challenge-gcp.png b/modules/installation-guide/images/installation/dns-challenge-gcp.png deleted file mode 100644 index 75b5edda45..0000000000 Binary files a/modules/installation-guide/images/installation/dns-challenge-gcp.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/dns-nameservers.png b/modules/installation-guide/images/installation/dns-nameservers.png deleted file mode 100644 index 9123ead314..0000000000 Binary files a/modules/installation-guide/images/installation/dns-nameservers.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/dns-settings-gcp.png b/modules/installation-guide/images/installation/dns-settings-gcp.png deleted file mode 100644 index 0f523efc89..0000000000 Binary files a/modules/installation-guide/images/installation/dns-settings-gcp.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/dns-zone-in-microsoft-azure.png b/modules/installation-guide/images/installation/dns-zone-in-microsoft-azure.png deleted file mode 100644 index 881894b97b..0000000000 Binary files a/modules/installation-guide/images/installation/dns-zone-in-microsoft-azure.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/entering-the-name-fo-the-domain.png b/modules/installation-guide/images/installation/entering-the-name-fo-the-domain.png deleted file mode 100644 index 31c33bb1fa..0000000000 Binary files a/modules/installation-guide/images/installation/entering-the-name-fo-the-domain.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/example-of-an-added-dns-zone.png b/modules/installation-guide/images/installation/example-of-an-added-dns-zone.png deleted file mode 100644 index 603c2d4653..0000000000 Binary files a/modules/installation-guide/images/installation/example-of-an-added-dns-zone.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/gcp-new-nodepool-select-machine-type-standard.png b/modules/installation-guide/images/installation/gcp-new-nodepool-select-machine-type-standard.png deleted file mode 100644 index 6d1bfbf0d4..0000000000 Binary files a/modules/installation-guide/images/installation/gcp-new-nodepool-select-machine-type-standard.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/gcp-new-nodepool.png b/modules/installation-guide/images/installation/gcp-new-nodepool.png deleted file mode 100644 index 34e58c09b7..0000000000 Binary files a/modules/installation-guide/images/installation/gcp-new-nodepool.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/json-review-policy.png b/modules/installation-guide/images/installation/json-review-policy.png deleted file mode 100644 index 2163ad5ddb..0000000000 Binary files a/modules/installation-guide/images/installation/json-review-policy.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/list-of-created-zones-and-NS.png b/modules/installation-guide/images/installation/list-of-created-zones-and-NS.png deleted file mode 100644 index d71c81bdd7..0000000000 Binary files a/modules/installation-guide/images/installation/list-of-created-zones-and-NS.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/new-dns-challenge-added.png b/modules/installation-guide/images/installation/new-dns-challenge-added.png deleted file mode 100644 index b8c8d05a1a..0000000000 Binary files a/modules/installation-guide/images/installation/new-dns-challenge-added.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/record-set-button.png b/modules/installation-guide/images/installation/record-set-button.png deleted file mode 100644 index 9cd5b83746..0000000000 Binary files a/modules/installation-guide/images/installation/record-set-button.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/registrar-setup-gcp.png b/modules/installation-guide/images/installation/registrar-setup-gcp.png deleted file mode 100644 index bd43ea7661..0000000000 Binary files a/modules/installation-guide/images/installation/registrar-setup-gcp.png and /dev/null differ diff --git a/modules/installation-guide/images/installation/selecting-the-resource-group.png b/modules/installation-guide/images/installation/selecting-the-resource-group.png deleted file mode 100644 index f28f1f1e6f..0000000000 Binary files a/modules/installation-guide/images/installation/selecting-the-resource-group.png and /dev/null differ diff --git a/modules/installation-guide/images/keycloak/che-keycloak-username-readonly-theme.png b/modules/installation-guide/images/keycloak/che-keycloak-username-readonly-theme.png deleted file mode 100644 index 92fa5179f3..0000000000 Binary files a/modules/installation-guide/images/keycloak/che-keycloak-username-readonly-theme.png and /dev/null differ diff --git a/modules/installation-guide/images/troubleshooting/status-bar-file-sync.png b/modules/installation-guide/images/troubleshooting/status-bar-file-sync.png deleted file mode 100644 index ccbadc474d..0000000000 Binary files a/modules/installation-guide/images/troubleshooting/status-bar-file-sync.png and /dev/null differ diff --git a/modules/installation-guide/nav.adoc b/modules/installation-guide/nav.adoc deleted file mode 100644 index 99814d8ad4..0000000000 --- a/modules/installation-guide/nav.adoc +++ /dev/null @@ -1,64 +0,0 @@ -.Installation Guide - -* xref:supported-platforms.adoc[] - -* xref:configuring-the-che-installation.adoc[] - -* xref:installing-che.adoc[] - - -** xref:installing-che-in-cloud.adoc[] - -*** xref:installing-che-on-openshift-4-using-operatorhub.adoc[] -*** xref:installing-che-on-openshift-4-using-cli.adoc[] -*** xref:installing-che-on-openshift-3-using-the-operator.adoc[] -*** xref:installing-che-on-kubespray.adoc[] -*** xref:installing-che-on-aws.adoc[] -*** xref:installing-che-on-google-cloud-platform.adoc[] -*** xref:installing-che-on-microsoft-azure.adoc[] - -** xref:running-che-locally.adoc[] - -*** xref:installing-che-on-codeready-containers.adoc[] -*** xref:installing-che-on-docker-desktop.adoc[] -*** xref:installing-che-on-minikube.adoc[] -*** xref:installing-che-on-minishift.adoc[] -*** xref:installing-che-on-kind.adoc[] - -** xref:using-the-chectl-management-tool.adoc[] - -** xref:installing-che-in-a-restricted-environment.adoc[] - -* xref:advanced-configuration.adoc[] - -** xref:advanced-configuration-options-for-the-che-server-component.adoc[] -** xref:configuring-namespace-strategies.adoc[] -** xref:configuring-storage-strategies.adoc[] -** xref:configuring-storage-types.adoc[] -** xref:configuring-the-number-of-workspaces-that-a-user-can-run.adoc[] -** xref:configuring-the-number-of-workspaces-that-a-user-can-create.adoc[] -** xref:configuring-workspace-exposure-strategies.adoc[] -** xref:configuring-workspaces-nodeselector.adoc[] -** xref:configuring-che-hostname.adoc[] -** xref:configuring-ingresses.adoc[] -** xref:configuring-routes.adoc[] -** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] -** xref:installing-che-using-storage-classes.adoc[] -** xref:importing-untrusted-tls-certificates.adoc[] -** xref:configuring-communication-between-che-components.adoc[] -** xref:setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc[] -** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[] -** xref:enabling-dev-workspace-operator.adoc[] - -* xref:upgrading-che.adoc[] - -** xref:upgrading-che-using-operatorhub.adoc[] -** xref:upgrading-che-using-the-cli-management-tool.adoc[] -** xref:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc[] -** xref:upgrading-che-namespace-strategies-other-than-per-user.adoc[] - - -* xref:uninstalling-che.adoc[] -** xref:uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc[] -** xref:uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc[] -** xref:uninstalling-che-after-chectl-installation.adoc[] diff --git a/modules/installation-guide/pages/.placeholder b/modules/installation-guide/pages/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/installation-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc b/modules/installation-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc deleted file mode 100644 index c355662d10..0000000000 --- a/modules/installation-guide/pages/advanced-configuration-options-for-the-che-server-component.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="advanced-configuration-options-for-the-che-server-component"] -// = Advanced configuration options for Che server -:navtitle: Advanced configuration options for Che server -:keywords: installation-guide, advanced-configuration-options-for-the-che-server-component -:page-aliases: .:advanced-configuration-options-for-the-che-server-component, .:configuring-system-variables - -include::partial$assembly_advanced-configuration-options-for-the-che-server-component.adoc[] diff --git a/modules/installation-guide/pages/advanced-configuration.adoc b/modules/installation-guide/pages/advanced-configuration.adoc deleted file mode 100644 index 2a78704a3d..0000000000 --- a/modules/installation-guide/pages/advanced-configuration.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="advanced-configuration"] -// = Advanced configuration -:navtitle: Advanced configuration -:keywords: installation-guide, advanced-configuration, advanced-configuration-options -:page-aliases: .:advanced-configuration, .:advanced-configuration-options, advanced-configuration-options - -include::partial$assembly_advanced-configuration.adoc[] diff --git a/modules/installation-guide/pages/configuring-che-hostname.adoc b/modules/installation-guide/pages/configuring-che-hostname.adoc deleted file mode 100644 index fbf5b8be2f..0000000000 --- a/modules/installation-guide/pages/configuring-che-hostname.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-che-hostname"] -// = Configuring Che hostname -:navtitle: Configuring Che hostname -:keywords: installation-guide, configuring-che-hostname -:page-aliases: .:configuring-che-hostname - -include::partial$proc_configuring-che-hostname.adoc[] diff --git a/modules/installation-guide/pages/configuring-communication-between-che-components.adoc b/modules/installation-guide/pages/configuring-communication-between-che-components.adoc deleted file mode 100644 index 35df91d02b..0000000000 --- a/modules/installation-guide/pages/configuring-communication-between-che-components.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="configuring-communication-between-che-components"] -:navtitle: Configuring communication between Che components -:keywords: installation-guide -:page-aliases: .:configuring-communication-between-che-components, .:switching-between-external-and-internal-communication, switching-between-external-and-internal-communication - -include::partial$proc_configuring-communication-between-che-components.adoc[] diff --git a/modules/installation-guide/pages/configuring-ingresses.adoc b/modules/installation-guide/pages/configuring-ingresses.adoc deleted file mode 100644 index 9bff9bdf3d..0000000000 --- a/modules/installation-guide/pages/configuring-ingresses.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="configuring-ingresses"] -:navtitle: Configuring {orch-ingress} -:keywords: installation-guide, configuring-ingresses -:page-aliases: .:configuring-ingresses - -include::partial$proc_configuring-ingresses.adoc[] diff --git a/modules/installation-guide/pages/configuring-namespace-strategies.adoc b/modules/installation-guide/pages/configuring-namespace-strategies.adoc deleted file mode 100644 index cbdf184062..0000000000 --- a/modules/installation-guide/pages/configuring-namespace-strategies.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-namespace-strategies"] -// = Configuring namespace strategies -:navtitle: Configuring workspace target {orch-namespace} -:keywords: installation-guide, configuring-namespace -:page-aliases: .:Configuring workspace target {orch-namespace} - -include::partial$proc_configuring-namespace-strategies.adoc[] diff --git a/modules/installation-guide/pages/configuring-routes.adoc b/modules/installation-guide/pages/configuring-routes.adoc deleted file mode 100644 index 09effcbd31..0000000000 --- a/modules/installation-guide/pages/configuring-routes.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-routes"] -// = Configuring Labels -:navtitle: Configuring OpenShift Route -:keywords: installation-guide, configuring-routes -:page-aliases: .:configuring-routes - -include::partial$proc_configuring-routes.adoc[] diff --git a/modules/installation-guide/pages/configuring-storage-strategies.adoc b/modules/installation-guide/pages/configuring-storage-strategies.adoc deleted file mode 100644 index 74783d9028..0000000000 --- a/modules/installation-guide/pages/configuring-storage-strategies.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-storage-strategies"] -// = Configuring storage strategies -:navtitle: Configuring storage strategies -:keywords: installation-guide, configuring-storage-strategies -:page-aliases: .:configuring-storage-strategies - -include::partial$assembly_configuring-storage-strategies.adoc[] diff --git a/modules/installation-guide/pages/configuring-storage-types.adoc b/modules/installation-guide/pages/configuring-storage-types.adoc deleted file mode 100644 index fcb9959a62..0000000000 --- a/modules/installation-guide/pages/configuring-storage-types.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-storage-types"] -// = Configuring storage types -:navtitle: Configuring storage types -:keywords: installation-guide, configuring-storage-types -:page-aliases: .:configuring-storage-types - -include::partial$proc_configuring-storage-types.adoc[] diff --git a/modules/installation-guide/pages/configuring-the-che-installation.adoc b/modules/installation-guide/pages/configuring-the-che-installation.adoc deleted file mode 100644 index 49c522ba3d..0000000000 --- a/modules/installation-guide/pages/configuring-the-che-installation.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-the-che-installation"] -// = Configuring the Che installation -:navtitle: Configuring the Che installation -:keywords: installation-guide, configuring-the-che-installation, configuring-che -:page-aliases: .:configuring-the-che-installation, .:configuring-che, configuring-che - -include::partial$assembly_configuring-the-che-installation.adoc[] diff --git a/modules/installation-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-create.adoc b/modules/installation-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-create.adoc deleted file mode 100644 index ba26c89b8e..0000000000 --- a/modules/installation-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-create.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-the-number-of-workspaces-that-a-user-can-create"] -// = Configuring the number of workspaces that a user can create -:navtitle: Configuring the number of workspaces that a user can create -:keywords: installation-guide -:page-aliases: .:configuring-the-number-of-workspaces-that-a-user-can-create - -include::partial$proc_configuring-the-number-of-workspaces-that-a-user-can-create.adoc[] diff --git a/modules/installation-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-run.adoc b/modules/installation-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-run.adoc deleted file mode 100644 index 78540fb7c8..0000000000 --- a/modules/installation-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-run.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-the-number-of-workspaces-that-a-user-can-run"] -// = Configuring the number of workspaces that a user can run -:navtitle: Configuring the number of workspaces that a user can run -:keywords: installation-guide, running-workspaces -:page-aliases: .:configuring-the-number-of-workspaces-that-a-user-can-run, .:running-more-than-one-workspace-at-a-time, running-more-than-one-workspace-at-a-time - -include::partial$proc_configuring-the-number-of-workspaces-that-a-user-can-run.adoc[] diff --git a/modules/installation-guide/pages/configuring-workspace-exposure-strategies.adoc b/modules/installation-guide/pages/configuring-workspace-exposure-strategies.adoc deleted file mode 100644 index e122f75550..0000000000 --- a/modules/installation-guide/pages/configuring-workspace-exposure-strategies.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-workspace-exposure-strategies"] -// = Configuring workspace exposure strategies -:navtitle: Configuring workspace exposure strategies -:keywords: installation-guide, configuring-workspace-exposure-strategies -:page-aliases: .:configuring-workspace-exposure-strategies, end-user-guide:configuring-workspace-exposure-strategies - -include::partial$assembly_configuring-workspace-exposure-strategies.adoc[] diff --git a/modules/installation-guide/pages/configuring-workspaces-nodeselector.adoc b/modules/installation-guide/pages/configuring-workspaces-nodeselector.adoc deleted file mode 100644 index 5b89ff9612..0000000000 --- a/modules/installation-guide/pages/configuring-workspaces-nodeselector.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-workspaces-nodeselector"] -// = Configuring workspaces nodeSelector -:navtitle: Configuring workspaces nodeSelector -:keywords: installation-guide, configuring-workspaces-nodeselector -:page-aliases: .:configuring-workspaces-nodeselector - -include::partial$proc_configuring-workspaces-nodeselector.adoc[] diff --git a/modules/installation-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc b/modules/installation-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc deleted file mode 100644 index 3747122638..0000000000 --- a/modules/installation-guide/pages/deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="deploying-che-with-support-for-git-repositories-with-self-signed-certificates"] -// = Deploying Che with support for Git repositories with self-signed certificates -:navtitle: Deploying Che with support for Git repositories with self-signed certificates -:keywords: installation-guide, deploying-che-with-support-for-git-repositories-with-self-signed-certificates -:page-aliases: .:deploying-che-with-support-for-git-repositories-with-self-signed-certificates - -include::partial$proc_deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] diff --git a/modules/installation-guide/pages/enabling-dev-workspace-operator.adoc b/modules/installation-guide/pages/enabling-dev-workspace-operator.adoc deleted file mode 100644 index 7c510eb5d6..0000000000 --- a/modules/installation-guide/pages/enabling-dev-workspace-operator.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="enabling-dev-workspace-operator"] -// = Configuring Labels -:navtitle: Enabling {devworkspace} operator -:keywords: installation-guide, {devworkspace} -:page-aliases: .:enabling-dev-workspace-operator - -include::partial$proc_enabling-dev-workspace-operator.adoc[] diff --git a/modules/installation-guide/pages/importing-untrusted-tls-certificates-old.adoc b/modules/installation-guide/pages/importing-untrusted-tls-certificates-old.adoc deleted file mode 100644 index 5bb138e751..0000000000 --- a/modules/installation-guide/pages/importing-untrusted-tls-certificates-old.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="importing-untrusted-tls-certificates-old"] -// = Importing untrusted TLS certificates -:navtitle: Importing untrusted TLS certificates to {prod-short} -:keywords: installation-guide, tls, certificate -:page-aliases: .:importing-untrusted-tls-certificates-old - -include::partial$proc_importing-untrusted-tls-certificates-old.adoc[] diff --git a/modules/installation-guide/pages/importing-untrusted-tls-certificates.adoc b/modules/installation-guide/pages/importing-untrusted-tls-certificates.adoc deleted file mode 100644 index 28ee867bad..0000000000 --- a/modules/installation-guide/pages/importing-untrusted-tls-certificates.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="importing-untrusted-tls-certificates"] -// = Importing untrusted TLS certificates -:navtitle: Importing untrusted TLS certificates to {prod-short} -:keywords: installation-guide, tls, certificate -:page-aliases: .:importing-untrusted-tls-certificates - -include::partial$proc_importing-untrusted-tls-certificates.adoc[] diff --git a/modules/installation-guide/pages/installing-che-in-a-restricted-environment.adoc b/modules/installation-guide/pages/installing-che-in-a-restricted-environment.adoc deleted file mode 100644 index d719144dc7..0000000000 --- a/modules/installation-guide/pages/installing-che-in-a-restricted-environment.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-in-a-restricted-environment"] -// = Installing Che in a restricted environment -:navtitle: Installing Che in restricted environment -:keywords: installation-guide, installing-che-in-a-restricted-environment, installing-che-in-restricted-environment -:page-aliases: .:installing-che-in-restricted-environment, .:installing-che-in-a-restricted-environment, installing-che-in-restricted-environment - -include::example$assembly_{project-context}-installing-che-in-a-restricted-environment.adoc[] diff --git a/modules/installation-guide/pages/installing-che-in-cloud.adoc b/modules/installation-guide/pages/installing-che-in-cloud.adoc deleted file mode 100644 index 99c2625d4e..0000000000 --- a/modules/installation-guide/pages/installing-che-in-cloud.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-in-cloud"] -// = Installing Che in cloud -:navtitle: Installing Che in cloud -:keywords: installation-guide, installing-che-in-cloud -:page-aliases: .:installing-che-in-cloud - -include::partial$assembly_installing-che-in-cloud.adoc[] diff --git a/modules/installation-guide/pages/installing-che-locally.adoc b/modules/installation-guide/pages/installing-che-locally.adoc deleted file mode 100644 index 80bc7afefd..0000000000 --- a/modules/installation-guide/pages/installing-che-locally.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-locally"] -// = Install Che locally -:navtitle: Installing Che locally -:keywords: overview, running-che-locally, installing-che-locally -:page-aliases: .:running-che-locally, .:installing-che-in-tls-mode-with-self-signed-certificates, overview:running-che-locally, running-che-locally - -include::partial$assembly_installing-che-locally.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-aws.adoc b/modules/installation-guide/pages/installing-che-on-aws.adoc deleted file mode 100644 index 7b7550fd74..0000000000 --- a/modules/installation-guide/pages/installing-che-on-aws.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-aws"] -// = Installing Che on AWS -:navtitle: Installing Che on AWS -:keywords: overview, installing-che-on-aws -:page-aliases: .:installing-che-on-aws, overview:installing-che-on-aws - -include::partial$assembly_installing-che-on-aws.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-codeready-containers.adoc b/modules/installation-guide/pages/installing-che-on-codeready-containers.adoc deleted file mode 100644 index 8aeb03960d..0000000000 --- a/modules/installation-guide/pages/installing-che-on-codeready-containers.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-codeready-containers"] -// = Installing Che on CodeReady Containers -:navtitle: Installing Che on CodeReady Containers -:keywords: overview, installing-che-on-codeready-containers -:page-aliases: .:installing-che-on-codeready-containers, overview:installing-che-on-codeready-containers - -include::partial$assembly_installing-che-on-codeready-containers.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-docker-desktop.adoc b/modules/installation-guide/pages/installing-che-on-docker-desktop.adoc deleted file mode 100644 index 339bcf3705..0000000000 --- a/modules/installation-guide/pages/installing-che-on-docker-desktop.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-docker-desktop"] -// = Installing Che on Docker Desktop -:navtitle: Installing Che on Docker Desktop -:keywords: overview, installing-che-on-docker-desktop -:page-aliases: .:installing-che-on-docker-desktop, overview:installing-che-on-docker-desktop - -include::partial$assembly_installing-che-on-docker-desktop.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-google-cloud-platform.adoc b/modules/installation-guide/pages/installing-che-on-google-cloud-platform.adoc deleted file mode 100644 index 64a8a84ac8..0000000000 --- a/modules/installation-guide/pages/installing-che-on-google-cloud-platform.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-google-cloud-platform"] -// = Installing Che on Google Cloud -:navtitle: Installing Che on Google Cloud -:keywords: overview, installing-che-on-google-cloud-platform -:page-aliases: .:installing-che-on-google-cloud-platform, overview:installing-che-on-google-cloud-platform - -include::partial$assembly_installing-che-on-google-cloud-platform.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-kind.adoc b/modules/installation-guide/pages/installing-che-on-kind.adoc deleted file mode 100644 index 2a22271c81..0000000000 --- a/modules/installation-guide/pages/installing-che-on-kind.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-kind"] -// = Installing Che on Kind -:navtitle: Installing Che on Kind -:keywords: overview, installing-che-on-kind -:page-aliases: .:installing-che-on-kind, overview:installing-che-on-kind - -include::partial$assembly_installing-che-on-kind.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-kubespray.adoc b/modules/installation-guide/pages/installing-che-on-kubespray.adoc deleted file mode 100644 index 6ffe27cd1f..0000000000 --- a/modules/installation-guide/pages/installing-che-on-kubespray.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-kubespray"] -// = Installing Che on Kubespray -:navtitle: Installing Che on Kubespray -:keywords: overview, installing-che-on-kubespray -:page-aliases: .:installing-che-on-kubespray, overview:installing-che-on-kubespray - -include::partial$assembly_installing-che-on-kubespray.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-microsoft-azure.adoc b/modules/installation-guide/pages/installing-che-on-microsoft-azure.adoc deleted file mode 100644 index 6d1994d906..0000000000 --- a/modules/installation-guide/pages/installing-che-on-microsoft-azure.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-microsoft-azure"] -// = Installing Che on Microsoft Azure -:navtitle: Installing Che on Microsoft Azure -:keywords: overview, installing-che-on-microsoft-azure -:page-aliases: .:installing-che-on-microsoft-azure, overview:installing-che-on-microsoft-azure - -include::partial$assembly_installing-che-on-microsoft-azure.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-minikube.adoc b/modules/installation-guide/pages/installing-che-on-minikube.adoc deleted file mode 100644 index 04f4398aa1..0000000000 --- a/modules/installation-guide/pages/installing-che-on-minikube.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-minikube"] -// = Installing Che on Minikube -:navtitle: Installing Che on Minikube -:keywords: overview, installing-che-on-minikube -:page-aliases: .:installing-che-on-minikube, overview:installing-che-on-minikube - -include::partial$assembly_installing-che-on-minikube.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-minishift.adoc b/modules/installation-guide/pages/installing-che-on-minishift.adoc deleted file mode 100644 index 220f2638a3..0000000000 --- a/modules/installation-guide/pages/installing-che-on-minishift.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-minishift"] -// = Installing Che on Minishift -:navtitle: Installing Che on Minishift -:keywords: overview, installing-che-on-minishift -:page-aliases: .:installing-che-on-minishift, overview:installing-che-on-minishift - -include::partial$assembly_installing-che-on-minishift.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-openshift-3-using-the-operator.adoc b/modules/installation-guide/pages/installing-che-on-openshift-3-using-the-operator.adoc deleted file mode 100644 index c308143fe1..0000000000 --- a/modules/installation-guide/pages/installing-che-on-openshift-3-using-the-operator.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-openshift-3-using-the-operator"] -// = Installing Che on OpenShift 3 -:navtitle: Installing Che on OpenShift 3 -:keywords: overview, installing-che-on-openshift-3-using-the-operator -:page-aliases: .:installing-che-on-openshift-3-using-the-operator, overview:installing-che-on-openshift-3-using-the-operator - -include::partial$proc_installing-che-on-openshift-3-using-the-operator.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-openshift-4-using-cli.adoc b/modules/installation-guide/pages/installing-che-on-openshift-4-using-cli.adoc deleted file mode 100644 index 063ef91b41..0000000000 --- a/modules/installation-guide/pages/installing-che-on-openshift-4-using-cli.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-openshift-4-using-cli"] -// = Installing Che on OpenShift 4 using CLI -:navtitle: Installing Che on OpenShift 4 using CLI -:keywords: overview, installing-che-on-openshift-4-using-cli -:page-aliases: .:installing-che-on-openshift-4-using-cli, overview:installing-che-on-openshift-4-using-cli - -include::partial$proc_installing-che-on-openshift-4-using-the-cli.adoc[] diff --git a/modules/installation-guide/pages/installing-che-on-openshift-4-using-operatorhub.adoc b/modules/installation-guide/pages/installing-che-on-openshift-4-using-operatorhub.adoc deleted file mode 100644 index b29449b5a3..0000000000 --- a/modules/installation-guide/pages/installing-che-on-openshift-4-using-operatorhub.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-on-openshift-4-using-operatorhub"] -// = Installing Che on OpenShift 4 -:navtitle: Installing Che on OpenShift 4 using OperatorHub -:keywords: overview, installing-che-on-openshift-4-using-operatorhub -:page-aliases: .:installing-che-on-openshift-4-using-operatorhub, overview:installing-che-on-openshift-4-using-operatorhub - -include::partial$assembly_installing-che-on-openshift-4-using-operatorhub.adoc[] diff --git a/modules/installation-guide/pages/installing-che-using-storage-classes.adoc b/modules/installation-guide/pages/installing-che-using-storage-classes.adoc deleted file mode 100644 index bf4d1d670d..0000000000 --- a/modules/installation-guide/pages/installing-che-using-storage-classes.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che-using-storage-classes"] -// = Installing Che using storage classes -:navtitle: Installing Che using storage classes -:keywords: installation-guide, installing-che-using-storage-classes -:page-aliases: .:installing-che-using-storage-classes - -include::partial$proc_installing-che-using-storage-classes.adoc[] diff --git a/modules/installation-guide/pages/installing-che.adoc b/modules/installation-guide/pages/installing-che.adoc deleted file mode 100644 index 7adb9148a0..0000000000 --- a/modules/installation-guide/pages/installing-che.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="installing-che"] -// = Installing Che -:navtitle: Installing Che -:keywords: installation-guide, installing-che -:page-aliases: .:installing-che, .:3-minutes-to-che, overview:3-minutes-to-che, .:quick-starts, .:che-quick-starts, .:quick-start.html, overview:che-quick-start - -include::partial$assembly_installing-che.adoc[] diff --git a/modules/installation-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc b/modules/installation-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc deleted file mode 100644 index 325988d557..0000000000 --- a/modules/installation-guide/pages/mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container"] -:navtitle: Mounting a Secret or a ConfigMap as a file or an environment variable into a {prod} container -:keywords: installation-guide, mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container -:page-aliases: .:mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container - -include::partial$assembly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc[] diff --git a/modules/installation-guide/pages/setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc b/modules/installation-guide/pages/setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc deleted file mode 100644 index 961a62ce0f..0000000000 --- a/modules/installation-guide/pages/setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page"] -// = Setting up the Keycloak che-username-readonly theme for the Eclipse Che login page -:navtitle: Setting up the Keycloak che-username-readonly theme for the Eclipse Che login page -:keywords: installation-guide, setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page, keycloak -:page-aliases: .:setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page - -include::partial$proc_setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc[] diff --git a/modules/installation-guide/pages/supported-platforms.adoc b/modules/installation-guide/pages/supported-platforms.adoc deleted file mode 100644 index ed6947bcea..0000000000 --- a/modules/installation-guide/pages/supported-platforms.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="supported-platforms"] -// = Supported platforms -:navtitle: Supported platforms -:keywords: installation-guide, supported-platforms -:page-aliases: .:supported-platforms - -include::partial$con_supported-platforms.adoc[] diff --git a/modules/installation-guide/pages/uninstalling-che-after-chectl-installation.adoc b/modules/installation-guide/pages/uninstalling-che-after-chectl-installation.adoc deleted file mode 100644 index a1871f4686..0000000000 --- a/modules/installation-guide/pages/uninstalling-che-after-chectl-installation.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="uninstalling-che-after-chectl-installation"] -// = Uninstalling Che after chectl installation -:navtitle: Using chectl -:keywords: installation-guide, uninstalling-che, uninstalling-che-after-chectl-installation -:page-aliases: .:uninstalling-che-after-chectl-installation - -include::example$proc_{project-context}-uninstalling-che-after-chectl-installation.adoc[] diff --git a/modules/installation-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc b/modules/installation-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc deleted file mode 100644 index 31d51fb776..0000000000 --- a/modules/installation-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="uninstalling-che-after-operatorhub-installation-using-openshift-cli"] -// = Uninstalling Che after OperatorHub installation using OpenShift CLI -:navtitle: Using OpenShift CLI -:keywords: installation-guide, uninstalling-che, uninstalling-che-after-operatorhub-installation-using-openshift-cli -:page-aliases: .:uninstalling-che-after-operatorhub-installation-using-openshift-cli - -include::partial$proc_uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc[] diff --git a/modules/installation-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc b/modules/installation-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc deleted file mode 100644 index 6ff71d1f61..0000000000 --- a/modules/installation-guide/pages/uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="uninstalling-che-after-operatorhub-installation-using-openshift-web-console"] -// = Uninstalling Che after OperatorHub installation using the OpenShift web console -:navtitle: Using the OpenShift web console -:keywords: installation-guide, uninstalling-che, uninstalling-che-after-operatorhub-installation-using-openshift-web-console -:page-aliases: .:uninstalling-che-after-operatorhub-installation-using-openshift-web-console - -include::partial$proc_uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc[] diff --git a/modules/installation-guide/pages/uninstalling-che.adoc b/modules/installation-guide/pages/uninstalling-che.adoc deleted file mode 100644 index 0b55b7554d..0000000000 --- a/modules/installation-guide/pages/uninstalling-che.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="uninstalling-che"] -// = Uninstalling Che -:navtitle: Uninstalling Che -:keywords: installation-guide, uninstalling-che -:page-aliases: .:uninstalling-che - -include::partial$assembly_uninstalling-che.adoc[] diff --git a/modules/installation-guide/pages/upgrading-che-namespace-strategies-other-than-per-user.adoc b/modules/installation-guide/pages/upgrading-che-namespace-strategies-other-than-per-user.adoc deleted file mode 100644 index 6ad4b3f317..0000000000 --- a/modules/installation-guide/pages/upgrading-che-namespace-strategies-other-than-per-user.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="upgrading-che-namespace-strategies-other-than-per-user"] -// = Updating Che namespace strategies other than 'per user' -:navtitle: Updating Che namespace strategies other than 'per user' -:keywords: installation-guide, upgrading-che-namespace-strategies-other-than-per-user. -:page-aliases: .:upgrading-che-namespace-strategies-other-than-per-user. - -include::partial$assembly_upgrading-che-namespace-strategies-other-than-per-user.adoc[] diff --git a/modules/installation-guide/pages/upgrading-che-using-operatorhub.adoc b/modules/installation-guide/pages/upgrading-che-using-operatorhub.adoc deleted file mode 100644 index 4e3bc6ecf8..0000000000 --- a/modules/installation-guide/pages/upgrading-che-using-operatorhub.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="upgrading-che-using-operatorhub"] -// = Upgrading Che using OperatorHub -:navtitle: Upgrading Che using OperatorHub -:keywords: installation-guide, upgrading-che-using-operatorhub -:page-aliases: .:upgrading-che-using-operatorhub - -include::partial$assembly_upgrading-che-using-operatorhub.adoc[] diff --git a/modules/installation-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc b/modules/installation-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc deleted file mode 100644 index 50d2e3611f..0000000000 --- a/modules/installation-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="upgrading-che-using-the-cli-management-tool-in-restricted-environment"] -// = Upgrading Che using the CLI management tool in restricted environment -:navtitle: Upgrading Che in restricted environment -:keywords: installation-guide, upgrading-che-using-the-cli-management-tool-in-restricted-environment, upgrading-che-in-restricted-environment - -include::partial$assembly_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc[] diff --git a/modules/installation-guide/pages/upgrading-che-using-the-cli-management-tool.adoc b/modules/installation-guide/pages/upgrading-che-using-the-cli-management-tool.adoc deleted file mode 100644 index 8686713dec..0000000000 --- a/modules/installation-guide/pages/upgrading-che-using-the-cli-management-tool.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="upgrading-che-using-the-cli-management-tool"] -// = Upgrading Che using the CLI management tool -:navtitle: Upgrading Che using the CLI management tool -:keywords: installation-guide, upgrading-che-using-the-cli-management-tool -:page-aliases: .:upgrading-che-using-the-cli-management-tool - -include::partial$proc_upgrading-che-using-the-cli-management-tool.adoc[] diff --git a/modules/installation-guide/pages/upgrading-che.adoc b/modules/installation-guide/pages/upgrading-che.adoc deleted file mode 100644 index 9b01878305..0000000000 --- a/modules/installation-guide/pages/upgrading-che.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="upgrading-che"] -// = Upgrading Che -:navtitle: Upgrading Che -:keywords: installation-guide, upgrading-che -:page-aliases: .:upgrading-che, installation-guide:upgrading-che-known-issues - -include::partial$assembly_upgrading-che.adoc[] diff --git a/modules/installation-guide/pages/using-the-chectl-management-tool.adoc b/modules/installation-guide/pages/using-the-chectl-management-tool.adoc deleted file mode 100644 index c93568d6f8..0000000000 --- a/modules/installation-guide/pages/using-the-chectl-management-tool.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="using-the-chectl-management-tool"] -// = Using the chectl management tool -:navtitle: Using the chectl management tool -:keywords: overview, using-the-chectl-management-tool -:page-aliases: .:using-the-chectl-management-tool, overview:using-the-chectl-management-tool - -include::partial$assembly_using-the-chectl-management-tool.adoc[] diff --git a/modules/installation-guide/partials/.placeholder b/modules/installation-guide/partials/.placeholder deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/modules/installation-guide/partials/assembly_advanced-configuration.adoc b/modules/installation-guide/partials/assembly_advanced-configuration.adoc deleted file mode 100644 index 844f7febcc..0000000000 --- a/modules/installation-guide/partials/assembly_advanced-configuration.adoc +++ /dev/null @@ -1,47 +0,0 @@ - - -:parent-context-of-configuring-che: {context} - - -[id="configuring-che_{context}"] -= Configuring {prod-short} - -:context: configuring-che - -The following chapter describes configuration methods and options for {prod}, with some user stories as example. - -* xref:advanced-configuration-options-for-the-che-server-component.adoc[] describes advanced configuration methods to use when the previous method is not applicable. - -The next sections describe some specific user stories. - -* xref:configuring-namespace-strategies.adoc[] - -* xref:configuring-the-number-of-workspaces-that-a-user-can-create.adoc[] - -* xref:configuring-the-number-of-workspaces-that-a-user-can-run.adoc[] - -* xref:configuring-workspaces-nodeselector.adoc[] - -* xref:configuring-che-hostname.adoc[] - -* xref:configuring-ingresses.adoc[] - -* xref:configuring-routes.adoc[] - -* xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] - -* xref:installing-che-using-storage-classes.adoc[] - -* xref:configuring-storage-types.adoc[] - -* xref:importing-untrusted-tls-certificates.adoc[] - -* xref:configuring-communication-between-che-components.adoc[] - -* xref:setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc[] - -* xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[] - -* xref:enabling-dev-workspace-operator.adoc[] - -:context: {parent-context-of-configuring-che} diff --git a/modules/installation-guide/partials/assembly_configuring-che-on-google-cloud-platform.adoc b/modules/installation-guide/partials/assembly_configuring-che-on-google-cloud-platform.adoc deleted file mode 100644 index e878b4a650..0000000000 --- a/modules/installation-guide/partials/assembly_configuring-che-on-google-cloud-platform.adoc +++ /dev/null @@ -1,16 +0,0 @@ - -:parent-context-of-configuring-che-on-google-cloud-platform: {context} - -[id="configuring-che-on-google-cloud-platform_{context}"] -= Configuring Che on Google Cloud Platform - -:context: configuring-che-on-google-cloud-platform - -The following section describes configuration guidelines after a {prod} installation on Google Cloud Platform. - -include::partial$proc_configuring-the-che-operator-checluster-resource-with-kubectl.adoc[leveloffset=+1] - -include::partial$proc_sizing-google-cloud-node-pools-for-your-eclipse-che-workspaces.adoc[leveloffset=+1] - -:context: {parent-context-of-configuring-che-on-google-cloud-platform} - diff --git a/modules/installation-guide/partials/assembly_configuring-storage-strategies.adoc b/modules/installation-guide/partials/assembly_configuring-storage-strategies.adoc deleted file mode 100644 index 5290658d6c..0000000000 --- a/modules/installation-guide/partials/assembly_configuring-storage-strategies.adoc +++ /dev/null @@ -1,14 +0,0 @@ -:parent-context-of-configuring-storage-strategies: {context} - -[id="configuring-storage-strategies_{context}"] -= Configuring storage strategies - -:context: configuring-storage-strategies - -This section describes how to configure storage strategies for {prod-short} workspaces. - -include::partial$con_persistent-volume-configuration.adoc[leveloffset=+1] - -include::partial$proc_configuring-a-che-workspace-with-a-persistent-volume-strategy.adoc[leveloffset=+1] - -:context: {parent-context-of-configuring-storage-strategies} diff --git a/modules/installation-guide/partials/assembly_configuring-the-che-installation.adoc b/modules/installation-guide/partials/assembly_configuring-the-che-installation.adoc deleted file mode 100644 index 8790021a04..0000000000 --- a/modules/installation-guide/partials/assembly_configuring-the-che-installation.adoc +++ /dev/null @@ -1,26 +0,0 @@ - -:parent-context-of-configuring-the-che-installation: {context} - - -[id="configuring-the-{prod-id-short}-installation_{context}"] -= Configuring the {prod-short} installation - -:context: configuring-the-che-installation - -The following section describes configuration options to install {prod} using the Operator. - - -ifeval::["{project-context}" == "che"] - -.Prerequisites - -* Choose an installation procedure using the Operator. - -endif::[] - -include::partial$con_understanding-the-checluster-custom-resource.adoc[leveloffset=+1] - -include::partial$ref_checluster-custom-resource-fields-reference.adoc[leveloffset=+1] - -:context: {parent-context-of-configuring-the-che-installation} - diff --git a/modules/installation-guide/partials/assembly_configuring-workspace-exposure-strategies.adoc b/modules/installation-guide/partials/assembly_configuring-workspace-exposure-strategies.adoc deleted file mode 100644 index 994cfb5968..0000000000 --- a/modules/installation-guide/partials/assembly_configuring-workspace-exposure-strategies.adoc +++ /dev/null @@ -1,18 +0,0 @@ - - -:parent-context-of-configuring-workspace-exposure-strategies: {context} - -[id="configuring-workspace-exposure-strategies_{context}"] -= Configuring workspace exposure strategies - -:context: configuring-workspace-exposure-strategies - -The following section describes how to configure workspace exposure strategies of a {prod-short} server and ensure that applications running inside are not vulnerable to outside attacks. - -include::partial$proc_configuring-workspace-exposure-strategies-using-an-operator.adoc[leveloffset=+1] - -include::partial$con_workspace-exposure-strategies.adoc[leveloffset=+1] - -include::partial$con_security-considerations.adoc[leveloffset=+1] - -:context: {parent-context-of-configuring-workspace-exposure-strategies} diff --git a/modules/installation-guide/partials/assembly_installing-che-in-cloud.adoc b/modules/installation-guide/partials/assembly_installing-che-in-cloud.adoc deleted file mode 100644 index c353495bdd..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che-in-cloud.adoc +++ /dev/null @@ -1,14 +0,0 @@ -ifeval::["{project-context}" == "che"] - -[id="installing-{prod-id-short}-in-cloud_{context}"] -= Installing {prod-short} in cloud - -* xref:installing-che-on-openshift-4-using-operatorhub.adoc[] -* xref:installing-che-on-openshift-4-using-cli.adoc[] -* xref:installing-che-on-openshift-3-using-the-operator.adoc[] -* xref:installing-che-on-kubespray.adoc[] -* xref:installing-che-on-aws.adoc[] -* xref:installing-che-on-google-cloud-platform.adoc[] -* xref:installing-che-on-microsoft-azure.adoc[] - -endif::[] diff --git a/modules/installation-guide/partials/assembly_installing-che-on-aws.adoc b/modules/installation-guide/partials/assembly_installing-che-on-aws.adoc deleted file mode 100644 index ed5705e4b9..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che-on-aws.adoc +++ /dev/null @@ -1,21 +0,0 @@ - -// che-quick-starts - -:parent-context-of-installing-che-on-aws: {context} - -[id="installing-{prod-id-short}-on-aws_{context}"] -= Installing {prod-short} on AWS - -:context: installing-{prod-id-short}-on-aws - -This article describes how to deploy {prod} on the Amazon Web Services (AWS) cloud. - -include::partial$proc_preparing-the-aws-system-for-installing-che.adoc[leveloffset=+1] - -:k8s-platform: AWS -:domain: aws.my-ide.cloud - -include::partial$proc_installing-che-on-kubernetes_using_chectl.adoc[leveloffset=+1] - - -:context: {parent-context-of-installing-che-on-aws} diff --git a/modules/installation-guide/partials/assembly_installing-che-on-docker-desktop.adoc b/modules/installation-guide/partials/assembly_installing-che-on-docker-desktop.adoc deleted file mode 100644 index e63d50b908..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che-on-docker-desktop.adoc +++ /dev/null @@ -1,18 +0,0 @@ - - -:parent-context-of-installing-che-on-docker-desktop: {context} - -[id="installing-{prod-id-short}-on-docker-desktop_{context}"] -= Installing {prod-short} on Docker Desktop - -:context: installing-{prod-id-short}-on-docker-desktop - -This article explains how to deploy {prod-short} on Docker Desktop. - -WARNING: Remember that Docker Desktop is suited only for testing or development. Do *NOT* use such clusters to run {prod-short} for organizations or developer teams. - -include::partial$proc_installing-che-on-docker-desktop-using-chectl.adoc[leveloffset=+1] - -include::end-user-guide:partial$proc_importing-certificates-to-browsers.adoc[leveloffset=+1] - -:context: {parent-context-of-installing-che-on-docker-desktop} diff --git a/modules/installation-guide/partials/assembly_installing-che-on-google-cloud-platform.adoc b/modules/installation-guide/partials/assembly_installing-che-on-google-cloud-platform.adoc deleted file mode 100644 index 5a91ccb197..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che-on-google-cloud-platform.adoc +++ /dev/null @@ -1,19 +0,0 @@ - - -:parent-context-of-installing-che-on-google-cloud-platform: {context} - -[id="installing-{prod-id-short}-on-google-cloud-platform_{context}"] -= Installing {prod-short} on Google Cloud Platform - -:context: installing-{prod-id-short}-on-google-cloud-platform - -include::partial$assembly_preparing-google-cloud-platform-for-installing-che.adoc[leveloffset=+1] - -:k8s-platform: Google Cloud Platform -:domain: gcp.my-ide.cloud - -include::partial$proc_installing-che-on-kubernetes_using_chectl.adoc[leveloffset=+1] - -include::partial$assembly_configuring-che-on-google-cloud-platform.adoc[leveloffset=+1] - -:context: {parent-context-of-installing-che-on-google-cloud-platform} diff --git a/modules/installation-guide/partials/assembly_installing-che-on-kind.adoc b/modules/installation-guide/partials/assembly_installing-che-on-kind.adoc deleted file mode 100644 index a81ef63671..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che-on-kind.adoc +++ /dev/null @@ -1,16 +0,0 @@ - - -:parent-context-of-installing-che-on-kind: {context} - -[id="installing-{prod-id-short}-on-kind_{context}"] -= Installing {prod-short} on Kind - -:context: installing-{prod-id-short}-on-kind - -This article explains how to deploy {prod-short} on a local kind {kubernetes} cluster. - -include::partial$proc_installing-che-on-kind-using-chectl.adoc[leveloffset=+1] - -include::end-user-guide:partial$proc_importing-certificates-to-browsers.adoc[leveloffset=+1] - -:context: {parent-context-of-installing-che-on-kind} diff --git a/modules/installation-guide/partials/assembly_installing-che-on-kubespray.adoc b/modules/installation-guide/partials/assembly_installing-che-on-kubespray.adoc deleted file mode 100644 index 78aaadd165..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che-on-kubespray.adoc +++ /dev/null @@ -1,20 +0,0 @@ - - -:parent-context-of-installing-che-on-kubespray: {context} - -[id="installing-{prod-id-short}-on-kubespray_{context}"] -= Installing {prod-short} on Kubespray - -:context: installing-{prod-id-short}-on-kubespray - -This article explains how to deploy {prod-short} on {kubernetes} provisioned by Kubespray. - -include::partial$proc_using-kubespray-to-set-up-kubernetes.adoc[leveloffset=+1] - -include::partial$proc_configuring-the-metallb-load-balancer-on-kubernetes.adoc[leveloffset=+1] - -include::partial$proc_installing-storage-for-kubernetes.adoc[leveloffset=+1] - -include::partial$proc_installing-che-on-kubespray-using-chectl.adoc[leveloffset=+1] - -:context: {parent-context-of-installing-che-on-kubespray} diff --git a/modules/installation-guide/partials/assembly_installing-che-on-microsoft-azure.adoc b/modules/installation-guide/partials/assembly_installing-che-on-microsoft-azure.adoc deleted file mode 100644 index 1c02f0d147..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che-on-microsoft-azure.adoc +++ /dev/null @@ -1,31 +0,0 @@ - - -:parent-context-of-installing-che-on-microsoft-azure: {context} - -[id="installing-{prod-id-short}-on-microsoft-azure_{context}"] -= Installing {prod-short} on Microsoft Azure - -:context: installing-{prod-id-short}-on-microsoft-azure - -Microsoft Azure is a cloud computing service created by Microsoft for building, testing, deploying, and managing applications and services through Microsoft-managed data centers. - -This section provides information about installing, enabling, and basic use of {prod-short} on Microsoft Azure. - -include::partial$proc_preparing-azure-for-installing-che.adoc[leveloffset=+1] - -include::partial$proc_installing-ingress-on-kubernetes.adoc[leveloffset=+1] - -include::partial$proc_configuring-dns-on-azure.adoc[leveloffset=+1] - -include::partial$proc_enabling-the-tls-dns-challenge-on-azure.adoc[leveloffset=+2] - -include::partial$proc_creating-a-service-account-secret-on-azure.adoc[leveloffset=+2] - -include::partial$proc_installing-cert-manager.adoc[leveloffset=+1] - -:k8s-platform: Microsoft Azure -:domain: azr.my-ide.cloud - -include::partial$proc_installing-che-on-kubernetes_using_chectl.adoc[leveloffset=+1] - -:context: {parent-context-of-installing-che-on-microsoft-azure} diff --git a/modules/installation-guide/partials/assembly_installing-che-on-minishift.adoc b/modules/installation-guide/partials/assembly_installing-che-on-minishift.adoc deleted file mode 100644 index 9232d5dba1..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che-on-minishift.adoc +++ /dev/null @@ -1,26 +0,0 @@ - - -:parent-context-of-installing-che-on-minishift: {context} - -[id="installing-{prod-id-short}-on-minishift_{context}"] -= Installing {prod-short} on Minishift - -:context: installing-{prod-id-short}-on-minishift - -This article explains how to create a single-node OpenShift 3 cluster with Minishift to deploy {prod-short}. - -WARNING: Remember that single-node OpenShift clusters are suited only for testing or development. Do *NOT* use such clusters to run {prod-short} for organizations or developer teams. - -include::partial$proc_using-minishift-to-set-up-openshift-3.adoc[leveloffset=+1] - -When deploying {prod-short} on Minishift, it is necessary to manually generate TLS certificates for use by the {prod-short} server. - -include::partial$proc_generating-self-signed-certificates.adoc[leveloffset=+1] - -include::partial$proc_adding-self-signed-certs-to-minishift.adoc[leveloffset=+1] - -include::partial$proc_installing-che-on-minishift-using-chectl.adoc[leveloffset=+1] - -include::end-user-guide:partial$proc_importing-certificates-to-browsers.adoc[leveloffset=+1] - -:context: {parent-context-of-installing-che-on-minishift} diff --git a/modules/installation-guide/partials/assembly_installing-che.adoc b/modules/installation-guide/partials/assembly_installing-che.adoc deleted file mode 100644 index a241441671..0000000000 --- a/modules/installation-guide/partials/assembly_installing-che.adoc +++ /dev/null @@ -1,50 +0,0 @@ - - -:parent-context-of-installing-che: {context} - -[id="installing-{prod-id-short}_{context}"] -= Installing {prod-short} - -:context: installing-{prod-id-short} - -This section contains instructions to install {prod}. The installation method depends on the target platform and the environment restrictions. - -ifeval::["{project-context}" == "che"] - - - -.Prerequisites - -* A {platforms-name} cluster to deploy {prod-short} on. - -[NOTE] -==== -To use {prod-short} as a service, see: xref:hosted-che:hosted-che.adoc[]. -==== - -[NOTE] -==== -You can deploy only one instance of {prod-short} per cluster. -==== - -== Installing {prod-short} on a local single-node cluster - -WARNING: Single-node clusters are suited only for testing or development. Do *not* use such clusters to run {prod-short} for organizations or developer teams. - -* xref:installing-che-on-codeready-containers.adoc[] -* xref:installing-che-on-docker-desktop.adoc[] -* xref:installing-che-on-minikube.adoc[] -* xref:installing-che-on-minishift.adoc[] -* xref:installing-che-on-kind.adoc[] - - -include::partial$assembly_installing-che-in-cloud.adoc[leveloffset=+1] - - -== Installing {prod-short} in a restricted environment - -* xref:installing-che-in-a-restricted-environment.adoc[] - -endif::[] - -:context: {parent-context-of-installing-che} diff --git a/modules/installation-guide/partials/assembly_preparing-google-cloud-platform-for-installing-che.adoc b/modules/installation-guide/partials/assembly_preparing-google-cloud-platform-for-installing-che.adoc deleted file mode 100644 index b803c4ee4c..0000000000 --- a/modules/installation-guide/partials/assembly_preparing-google-cloud-platform-for-installing-che.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-google-cloud-platform - -:parent-context-of-preparing-google-cloud-platform-for-installing-che: {context} - -[id="preparing-google-cloud-platform-for-installing-che_{context}"] -= Preparing Google Cloud Platform for installing {prod-short} - -Google Cloud Platform (GCP) is a suite of cloud computing services that provides infrastructure as a service, platform as a service, and serverless computing environments. - -This section provides information about how to configure the GCP environment for installing {prod}. - -:context: preparing-google-cloud-platform-for-installing-che - -include::partial$proc_creating-a-google-kubernetes-engine-instance.adoc[leveloffset=+1] - -include::partial$proc_installing-ingress-on-kubernetes.adoc[leveloffset=+1] - -include::partial$proc_installing-dns-on-google-cloud-platform.adoc[leveloffset=+1] - -include::partial$proc_enabling-the-tls-dns-challenge-on-google-cloud-platform.adoc[leveloffset=+1] - -include::partial$proc_creating-a-service-account-secret-on-google-cloud-platform.adoc[leveloffset=+1] - -include::partial$proc_installing-cert-manager-on-kubernetes.adoc[leveloffset=+1] - -:context: {parent-context-of-preparing-google-cloud-platform-for-installing-che} diff --git a/modules/installation-guide/partials/assembly_upgrading-che-namespace-strategies-other-than-per-user.adoc b/modules/installation-guide/partials/assembly_upgrading-che-namespace-strategies-other-than-per-user.adoc deleted file mode 100644 index aa10a58a12..0000000000 --- a/modules/installation-guide/partials/assembly_upgrading-che-namespace-strategies-other-than-per-user.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// upgrading-{prod-id-short} - -[id="upgrading-{prod-id-short}-namespace-strategies-other-than-per-user"] -= Upgrading {prod-short} that uses {orch-namespace} strategies other than 'per user' - -This section describes how to upgrade {prod-short} that uses {orch-namespace} strategies other than 'per user'. - -{prod-short} intends to use {kubernetes} secrets as a storage for all sensitive user data. One {orch-namespace} -per user simplifies the design of the workspaces. This is the reason why {orch-namespace} strategies other than `per user` become -deprecated. The deprecation process happens in two steps. In the `First Step` {orch-namespace} strategies other than `per user` are allowed but not recommended. In the `Second Step` support for {orch-namespace} strategies other than `per user` is going to be removed. - -NOTE: No automated upgrade support exists between `First Step` and `Second Step` for the installations where {orch-namespace} -strategies other than `per user` are used without losing data. - -.Prerequisites - * {prod-short} configured with the {orch-namespace} strategies other than `per user`. - * Intention to use {prod-short} configured with the `per user` namespace strategies `per user`. - -include::partial$proc_upgrading-che-and-backing-up-user-data.adoc[leveloffset=+1] -include::partial$proc_upgrading-che-and-losing-user-data.adoc[leveloffset=+1] - -.Additional resources - -* xref:configuring-namespace-strategies.adoc[] -* xref:installation-guide:installing-che.adoc[] -* xref:end-user-guide:workspaces-overview.adoc[] -* xref:end-user-guide:importing-the-source-code-of-a-project-into-a-workspace.adoc[] diff --git a/modules/installation-guide/partials/assembly_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc b/modules/installation-guide/partials/assembly_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc deleted file mode 100644 index 3bdbab799d..0000000000 --- a/modules/installation-guide/partials/assembly_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc +++ /dev/null @@ -1,31 +0,0 @@ -:parent-context-of-upgrading-prod-short-using-the-cli-management-tool-in-restricted-environment: {context} - -[id="upgrading-{prod-id-short}-using-the-cli-management-tool-in-restricted-environment_{context}"] -= Upgrading {prod-short} using the CLI management tool in restricted environment - -:context: upgrading-prod-short-using-the-cli-management-tool-in-restricted-environment - -This section describes how to upgrade {prod} using the CLI management tool in restricted environment. The upgrade path supports minor version update, from {prod-short} version {prod-prev-ver} to version {prod-ver}. - -.Prerequisites - -* An administrative account on an instance of {platforms-name}. - -* A running instance version {prod-prev-ver} of {prod}, installed using the CLI management tool on the same instance of {platforms-name}, with the {prod-cli} `--installer operator` method, in the `_<{prod-namespace}>_` project. See xref:installing-che-in-a-restricted-environment.adoc[]. - -* The `{prod-cli}` {prod-ver} management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. - -include::example$con_{project-context}-understanding-network-connectivity-in-restricted-environments.adoc[leveloffset=+1] - - -include::partial$assembly_building-offline-registry-images.adoc[leveloffset=+1] - - -include::example$proc_{project-context}-preparing-a-private-registry.adoc[leveloffset=+1] - - -include::partial$proc_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc[leveloffset=+1] - - -:context: {parent-context-of-upgrading-prod-short-using-the-cli-management-tool-in-restricted-environment} - diff --git a/modules/installation-guide/partials/assembly_using-the-chectl-management-tool.adoc b/modules/installation-guide/partials/assembly_using-the-chectl-management-tool.adoc deleted file mode 100644 index 58d6bdaf0f..0000000000 --- a/modules/installation-guide/partials/assembly_using-the-chectl-management-tool.adoc +++ /dev/null @@ -1,25 +0,0 @@ - - -:parent-context-of-using-the-chectl-management-tool: {context} - -[id="using-the-{prod-cli}-management-tool_{context}"] -= Using the {prod-cli} management tool - -:context: using-the-{prod-cli}-management-tool - -`{prod-cli}` is the {prod} command-line management tool. It is used for operations on the {prod-short} server (start, stop, update, delete) and on workspaces (list, start, stop, inject) and to generate devfiles. - -include::partial$proc_installing-the-chectl-management-tool-on-windows.adoc[leveloffset=+1] - -include::partial$proc_installing-the-chectl-management-tool-on-linux-or-macos.adoc[leveloffset=+1] - -include::partial$proc_upgrading-the-chectl-management-tool.adoc[leveloffset=+1] - - -ifeval::["{project-context}" == "che"] -.Additional resources - -* See: link:https://github.com/che-incubator/{prod-cli}/[`{prod-cli}` reference documentation]. -endif::[] - -:context: {parent-context-of-using-the-chectl-management-tool} diff --git a/modules/installation-guide/partials/con_persistent-volume-configuration.adoc b/modules/installation-guide/partials/con_persistent-volume-configuration.adoc deleted file mode 100644 index 1b647dd315..0000000000 --- a/modules/installation-guide/partials/con_persistent-volume-configuration.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-configuration - -[id="storage-strategies-for-{prod-id-short}-workspaces_{context}"] -= Storage strategies for {prod-id-short} workspaces - -Storage strategy:: -A configurable method defining how {prod-short} workspaces use persistent volume claims (PVCs) and persistent volumes (PVs). -This method defines the storage for workspace data, for example, projects, workspace logs, or additional volumes defined by a user. - -.Storage strategies comparison -[width="100%",cols="1,1,1,1",options="header"] -|=== -| Storage strategy name -| `common` -| `per-workspace` -| `unique` - -| PV count -| One per user -| One per workspace -| Multiple PVs per workspace - -| Default -| yes -| no -| no - - -| Limitations -| Maximum one running workspace per user when the PV is in the `ReadWriteOnce` access mode -| PV count depends on the number of workspaces -| Unpredictable PV count - -|=== - -Persistent volumes (PVs) access mode:: -The nature of the PV determines the available access mode: `ReadWriteMany` or `ReadWriteOnce`. -See link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes[Kubernetes documentation - access mode]. -For example, link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html[Amazon EBS] supports only the `ReadWriteOnce` access mode. - - -[id="the-common-storage-strategy_{context}"] -== The `common` storage strategy - -This is the default storage strategy. -For each user, all workspaces use the same PV for the default data storage. - -When the user starts a first non-ephemeral workspace, the workspace engine creates a common PV. - -When the user starts another non-ephemeral workspace, the workspace engine uses the same common PV. -The workspace only binds simultaneously to one node in the {orch-name} cluster. -The workspace engine ignores user-defined volumes. -The workspace engine replaces volumes related to user-defined volumes with a subPath in the common volume. -SubPaths have a `_<workspace-ID>_` or `__<original-volume-name>__` prefix. -See xref:how-subpaths-are-used-in-persistent-volumes_{context}[]. -The {prod-short} volume name is identical to the name of the user-defined PV. -Therefore, if a workspace container uses a {prod-short} volume with the same name as the user-defined PV, they will use the same shared folder in the common PV. - -When the user deletes a workspace, the workspace engine deletes the corresponding subdirectory (`$\{ws-id}`) in the PV directory. - -When the user deletes the last workspace, the workspace engine removes the common PV. - -Restrictions on the `common` storage strategy with the `ReadWriteOnce` access mode:: -The `ReadWriteOnce` access mode limits each user to run only one concurrent workspace. -See xref:installation-guide:configuring-the-number-of-workspaces-that-a-user-can-run.adoc[]. - -Scalability:: -The `common` storage strategy is not suitable for multi-node clusters with the 'ReadWriteOnce' access mode for PVs if the number of concurrently running workspaces per user is more than 1. - -Persistent volumes (PV) provisioning:: -Create a large enough PV to accommodate all projects to prevent a situation in which one project depletes the resources of others. - -[id="the-per-workspace-storage-strategy_{context}"] -== The `per-workspace` storage strategy - -Each workspace uses one dedicated PV. -All {prod-short} volumes defined within a single workspace use the same PV. - - -Persistent volumes (PV) provisioning:: -Users can run multiple workspaces simultaneously. This action results in more PVs. - -[id="the-unique-storage-strategy_{context}"] -== The `unique` storage strategy - -Each {prod-short} volume defined in a workspace has its own PV. - -When the user starts a workspace, the workspace engine creates the workspace PVs. - -The workspace engine generates a unique name for each PV to prevent name conflicts with other PVs in the same {orch-namespace}. - -To ensure that different storage strategies use the same PV data structure, subPaths of the mounted PVs that reference user-defined PVs are prefixed with `_<workspace-ID>_` or `__<persistent-volume-name>__`. -See xref:how-subpaths-are-used-in-persistent-volumes_{context}[]. - -When the user deletes a workspace, the workspace engine deletes all workspace PVs. - -PV provisioning:: -This is the strategy, which creates the highest volume counts. - - -[id="how-subpaths-are-used-in-persistent-volumes_{context}"] -== How subPaths are used in persistent volumes (PVs) - -SubPaths illustrate the folder hierarchy in the PV. - -[subs="+quotes,+attributes"] ----- -/__<pv0001>__ - /__<workspaceID1>__ - /__<workspaceID2>__ - /__<workspaceIDn>__ - /che-logs - /projects - /__<volume1>__ - /__<volume2>__ - /__<user-defined-volume-name-1>__ - /__<user-defined-volume-name-2>__ - /__<user-defined-volume-name-3|volume3>__ - ... ----- - -When a user defines volumes for components in the devfile, all components that define the volume of the same name will be backed by the same directory in the PV as `__<persistent-volume-name>__`, `__<workspace-ID>__`, or `__<original-volume-name>__`. -Each component can have this location mounted on a different path in its containers. diff --git a/modules/installation-guide/partials/con_security-considerations.adoc b/modules/installation-guide/partials/con_security-considerations.adoc deleted file mode 100644 index d67a9e293a..0000000000 --- a/modules/installation-guide/partials/con_security-considerations.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-workspace-exposure-strategies - -[id="security-considerations_{context}"] -= Security considerations - -This section explains the security impact of using different {prod-short} workspace exposure strategies. - - -[id="json-web-token-jwt-proxy_{context}"] -== JSON web token (JWT) proxy - -All {prod-short} plug-ins, editors, and components can require authentication of the user accessing them. This authentication is performed using a JSON web token (JWT) proxy that functions as a reverse proxy of the corresponding component, based on its configuration, and performs the authentication on behalf of the component. - -The authentication uses a redirect to a special page on the {prod-short} server that propagates the workspace and user-specific authentication token (workspace access token) back to the originally requested page. - -The JWT proxy accepts the workspace access token from the following places in the incoming requests, in the following order: - -. The token query parameter -. The Authorization header in the bearer-token format -. The `access_token` cookie - -== Secured plug-ins and editors - -{prod-short} users do not need to secure workspace plug-ins and workspace editors (such as Che-Theia). This is because the JWT proxy authentication is indiscernible to the user and is governed by the plug-in or editor definition in their `meta.yaml` descriptors. - -== Secured container-image components - -Container-image components can define custom endpoints for which the devfile author can require {prod-short}-provided authentication, if needed. This authentication is configured using two optional attributes of the endpoint: - -* `secure` - A boolean attribute that instructs the {prod-short} server to put the JWT proxy in front of the endpoint. Such endpoints have to be provided with the workspace access token in one of the several ways explained in xref:#json-web-token-jwt-proxy_{context}[]. The default value of the attribute is `false`. - -* `cookiesAuthEnabled` - A boolean attribute that instructs the {prod-short} server to automatically redirect the unauthenticated requests for current user authentication as described in xref:#json-web-token-jwt-proxy_{context}[]. Setting this attribute to `true` has security consequences because it makes Cross-site request forgery (CSRF) attacks possible. The default value of the attribute is `false`. - -== Cross-site request forgery attacks - -Cookie-based authentication can make an application secured by a JWT proxy prone to Cross-site request forgery (CSRF) attacks. See the link:https://en.wikipedia.org/wiki/Cross-site_request_forgery[Cross-site request forgery] Wikipedia page and other resources to ensure your application is not vulnerable. - -== Phishing attacks - -An attacker who is able to create an Ingress or route inside the cluster with the workspace that shares the host with some services behind a JWT proxy, the attacker may be able to create a service and a specially forged Ingress object. When such a service or Ingress is accessed by a legitimate user that was previously authenticated with a workspace, it can lead to the attacker stealing the workspace access token from the cookies sent by the legitimate user’s browser to the forged URL. -To eliminate this attack vector, configure OpenShift to disallow setting the host of an Ingress. diff --git a/modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-not-using-the-operator.adoc b/modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-not-using-the-operator.adoc deleted file mode 100644 index e61b839014..0000000000 --- a/modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-not-using-the-operator.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// advanced-configuration-options-for-the-che-server-component - -[id="understanding-{prod-id-short}-server-advanced-configuration-not-using-the-operator_{context}"] -= Understanding {prod-short} server advanced configuration not using the Operator - -The following section describes {prod-short} server component advanced configuration method when the installation method is not using the Operator. - -The user configures {prod-short} manually by modifying the `configMap` object. - -.Procedure - -. Proceed to the installation to generate the `che` `configMap` object. -. Edit the `che` `configMap` template. -. Apply manual changes to the `custom` `configMap` without downtime using the following `{orch-cli} ` command: -+ ----- -$ kubectl rollout restart deployment/che ----- - -.Additional resources - -* link:https://docs.openshift.com/container-platform/latest/cicd/builds/setting-up-trusted-ca.html[Understanding `configMaps`] diff --git a/modules/installation-guide/partials/con_understanding-the-checluster-custom-resource.adoc b/modules/installation-guide/partials/con_understanding-the-checluster-custom-resource.adoc deleted file mode 100644 index 923548b7f9..0000000000 --- a/modules/installation-guide/partials/con_understanding-the-checluster-custom-resource.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="understanding-the-checluster-custom-resource_{context}"] -= Understanding the `CheCluster` Custom Resource - -A default deployment of {prod-short} consist in the application of a parametrized `CheCluster` Custom Resource by the {prod} Operator. - -`CheCluster` Custom Resource:: - -* A YAML document describing the configuration of the overall {prod-short} installation. -* Contains sections to configure each component: `auth`, `database`, `server`, `storage`. - - -Role of the {prod} Operator:: - -* To translate the `CheCluster` Custom Resource into configuration (ConfigMap) usable by each component of the {prod-short} installation. - -Role of the {orch-name} platform:: - -* To apply the configuration (ConfigMap) for each component. -* To create the necessary Pods. -* When {orch-name} detects a change in the configuration of a component, it restarts the Pods accordingly. - -.Configuring the main properties of the {prod-short} server component -==== -. The user applies a `CheCluster` Custom Resource containing some configuration related to the `server`. -. The Operator generates a necessary ConfigMap, called `che`. -. {orch-name} detects change in the ConfigMap and triggers a restart of the {prod-short} Pod. -==== - -.Additional resources - -* link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Understanding Operators]. - -* link:https://docs.openshift.com/container-platform/latest/operators/understanding/crds/crd-managing-resources-from-crds.html[Understanding Custom Resources]. - -* To learn how to modify the `CheCluster` Custom Resource, see the chosen installation procedure. diff --git a/modules/installation-guide/partials/con_workspace-exposure-strategies.adoc b/modules/installation-guide/partials/con_workspace-exposure-strategies.adoc deleted file mode 100644 index 1fa3dd4366..0000000000 --- a/modules/installation-guide/partials/con_workspace-exposure-strategies.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-workspace-exposure-strategies - -[id="workspace-exposure-strategies_{context}"] -= Workspace exposure strategies - -Specific components of workspaces need to be made accessible outside of the {platforms-name} cluster. This is typically the user interface of the workspace's IDE, but it can also be the web UI of the application being developed. This enables developers to interact with the application during the development process. - -The supported way of making workspace components available to the users is referred to as a _strategy_. This strategy defines whether new subdomains are created for the workspace components and what hosts these components are available on. - -{prod-short} supports: - -* `multi-host` strategy -* `single-host` strategy -** with the `gateway` subtype -ifeval::["{project-context}" == "che"] -** with the `native` subtype -* `default-host` strategy -endif::[] - -[id="multi-host-workspace-exposure-strategy_{context}"] -== Multihost strategy - -With multihost strategy, each workspace component is assigned a new subdomain of the main domain configured for the {prod-short} server. This is the default strategy. - -This strategy is the easiest to understand from the perspective of component deployment because any paths to the component in the URL are received as they are by the component. - -On a {prod-short} server secured using the Transport Layer Security (TLS) protocol, creating new subdomains for each component of each workspace requires a wildcard certificate to be available for all such subdomains for the {prod-short} deployment to be practical. - -[id="single-host-workspace-exposure-strategy_{context}"] -== Single-host strategy - -With single-host strategy, all workspaces are deployed to sub-paths of the main {prod-short} server domain. - -This is convenient for TLS-secured {prod-short} servers because it is sufficient to have a single certificate for the {prod-short} server, which will cover all the workspace component deployments as well. - -Single-host strategy have two subtypes with different implementation methods. First subtype is named `native`. This strategy is available and default on {kubernetes}, but not on OpenShift, since it uses Ingresses for servers exposing. The second subtype named `gateway`, works both on {platforms-name}, and uses a special Pod with reverse-proxy running inside to route requests. - -[WARNING] -==== -With `gateway` single-host strategy, cluster network policies has to be configured so that workspace's services are reachable from reverse-proxy Pod (typically in {prod-short} {orch-namespace}). These typically lives in different {orch-namespace}. -==== - -To define how to expose the endpoints specified in the devfile, define the `++CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE++` environment variable in the {prod-short} instance. This environment variable is only effective with the single-host server strategy and is applicable to all workspaces of all users. - -=== devfile endpoints: `single-host` - -`++CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE: 'single-host'++` - -This single-host configuration exposes the endpoints on subpaths, for example: `++https://<che-host>/serverihzmuqqc/go-cli-server-8080++`. This limits the exposed components and user applications. Any absolute URL generated on the server side that points back to the server does not work. This is because the server is hidden behind a path-rewriting reverse proxy that hides the unique URL path prefix from the component or user application. - -For example, when the user accesses the hypothetical `pass:c,a,q[{prod-url}/component-prefix-djh3d/app/index.php]` URL, the application sees the request coming to `++https://internal-host/app/index.php++`. If the application used the host in the URL that it generates in its UI, it would not work because the internal host is different from the externally visible host. However, if the application used an absolute path as the URL (for the example above, this would be `/app/index.php`), such URL would still not work. This is because on the outside, such URL does not point to the application, because it is missing the component-specific prefix. - -Therefore, only applications that use relative URLs in their UI work with the single-host workspace exposure strategy. - -=== devfile endpoints: `multi-host` - -`++CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE: 'multi-host'++` - -This single-host configuration exposes the endpoints on subdomains, for example: `++http://serverihzmuqqc-go-cli-server-8080.<che-host>++`. These endpoints are exposed on an unsecured HTTP port. A dedicated Ingress or Route is used for such endpoints, even with `gateway` single-host setup. - -This configuration limits the usability of previews shown directly in the editor page when {prod-short} is configured with TLS. Since `https` pages allow communication only with secured endpoints, users must open their application previews in another browser tab. - -ifeval::["{project-context}" == "che"] - -[id="default-host-workspace-exposure-strategy_{context}"] -== Default-host strategy - -This strategy exposes the components to the outside world on the sub-paths of the default host of the cluster. It is similar to the single-host strategy. All the limitations and advantages of the single-host strategy applying to this strategy as well. -endif::[] diff --git a/modules/installation-guide/partials/proc_adding-self-signed-certs-to-minishift.adoc b/modules/installation-guide/partials/proc_adding-self-signed-certs-to-minishift.adoc deleted file mode 100644 index bb27fa7b5f..0000000000 --- a/modules/installation-guide/partials/proc_adding-self-signed-certs-to-minishift.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-minishift - -[id="adding-self-signed-certificates-to-minishift"] -= Adding self-signed certificates to Minishift - -This section describes how to add user-generated certificates to a Minishift cluster. - -NOTE: This method involves reconfiguration of the OpenShift router to use user-provided TLS certificates. - -.Prerequisites - -* A running OpenShift 3 instance, version 3.11 or higher. -* All required keys and certificates. See xref:generating-self-signed-certificates_{context}[]. - -.Procedure - -. Log in to the default OpenShift project: -+ ----- -$ oc login -u system:admin --insecure-skip-tls-verify=true -$ oc project default ----- - -. Reconfigure the router with the generated certificate: -+ -[subs="+quotes,+attributes"] ----- -$ oc delete secret router-certs -$ cat domain.crt domain.key > openshift.crt -$ oc create secret tls router-certs --key=domain.key --cert=openshift.crt -$ oc rollout latest router ----- - -. Create a {orch-namespace} for {prod-short}: -+ -[subs="+quotes,+attributes"] ----- -$ oc create namespace {prod-namespace} ----- - -. Create a secret from the CA certificate: -+ -[subs="+quotes,+attributes"] ----- -$ oc create secret generic self-signed-certificate --from-file=ca.crt -n={prod-namespace} ----- - -.Additional resources - -* xref:end-user-guide:importing-certificates-to-browsers.adoc[] diff --git a/modules/installation-guide/partials/proc_configuring-a-che-workspace-with-a-persistent-volume-strategy.adoc b/modules/installation-guide/partials/proc_configuring-a-che-workspace-with-a-persistent-volume-strategy.adoc deleted file mode 100644 index 56e1e9cd24..0000000000 --- a/modules/installation-guide/partials/proc_configuring-a-che-workspace-with-a-persistent-volume-strategy.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-configuration - -[id="configuring-a-{prod-id-short}-workspace-with-a-persistent-volume-strategy_{context}"] -= Configuring a {prod-short} workspace with a persistent volume strategy - -A persistent volume (PV) acts as a virtual storage instance that adds a volume to a cluster. - -A persistent volume claim (PVC) is a request to provision persistent storage of a specific type and configuration, available in the following {prod-short} storage configuration strategies: - -* Common -* Per-workspace -* Unique - -The mounted PVC is displayed as a folder in a container file system. - -[id="configuring-a-pvc-strategy-using-the-operator_{context}"] -== Configuring a PVC strategy using the Operator - -The following section describes how to configure workspace persistent volume claim (PVC) strategies of a {prod-short} server using the Operator. - -WARNING: It is not recommended to reconfigure PVC strategies on an existing {prod-short} cluster with existing workspaces. Doing so causes data loss. - -link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Operators] are software extensions to {platforms-name} that use link:https://docs.openshift.com/container-platform/latest/operators/understanding/crds/crd-managing-resources-from-crds.html[Custom Resources] to manage applications and their components. - -When deploying {prod-short} using the Operator, configure the intended strategy by modifying the `spec.storage.pvcStrategy` property of the CheCluster Custom Resource object YAML file. - -.Prerequisites - -* The `{orch-cli}` tool is available. - -.Procedure - -The following procedure steps are available for {platforms-name} command-line tool, {platforms-cli}. - -To do changes to the CheCluster YAML file, choose one of the following: - -* Create a new cluster by executing the `{orch-cli} apply` command. For example: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} apply -f _<my-cluster.yaml>_ ----- - -* Update the YAML file properties of an already running cluster by executing the `{orch-cli} patch` command. For example: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} patch checluster/{prod-checluster} --type=json \ - -p '[{"op": "replace", "path": "/spec/storage/pvcStrategy", "value": "per-workspace"}]' ----- - -Depending on the strategy used, replace the `per-workspace` option in the above example with `unique` or `common`. - -//// -.Additional resources - -* TBD -//// diff --git a/modules/installation-guide/partials/proc_configuring-communication-between-che-components.adoc b/modules/installation-guide/partials/proc_configuring-communication-between-che-components.adoc deleted file mode 100644 index ea16affd5d..0000000000 --- a/modules/installation-guide/partials/proc_configuring-communication-between-che-components.adoc +++ /dev/null @@ -1,65 +0,0 @@ -[id="configuring-communication-between-{prod-id-short}-components_{context}"] -= Configuring communication between {prod-short} components - -You can select whether {prod-short} components communicate by using the internal network or external {platforms-ingress}. - -By default, {prod-short} components communicate by using the internal network. {prod-short} components use their internal services names, which are exposed in the internal {platforms-name} network. - -As the administrator, disable the use of the internal services names to force the {prod-short} components to use external {platforms-ingress} in the following situations: - -* To deploy {prod-short} on a cluster where NetworkPolicies restricts communications between namespaces. -* To deploy {prod-short} with the multitenant network plugin. - -[IMPORTANT] -==== -Using the external {platforms-ingress} might slow the traffic and lead to issues because it uses proxies, certificates, and firewalls. -==== - -.Prerequisites - -* An instance of {prod-short} running on {platforms-name}. - -.Procedure - -* In the CheCluster Custom Resource server settings, for the `disableInternalClusterSVCNames` property, set `__<property-value>__` to: -[horizontal] -`true`:: To use external {platforms-ingress}. -`false`:: To use internal {orch-name} DNS names. - -+ -==== -[source,yaml,subs="+quotes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheCluster -# ... -spec: - server: - # ... - disableInternalClusterSVCNames: __<property-value>__ ----- -==== - -.Verification steps -. Specify {prod-short} as the default project: -+ -[subs="+quotes,attributes"] ----- -$ {orch-cli} project {prod-namespace} ----- -. Inspect the ConfigMap properties to determine which communication method {prod-short} uses: -+ -[subs="+quotes,attributes,macros"] ----- -$ {orch-cli} get configmap che -o \ -jsonpath='{.data.pass:[CHE_KEYCLOAK_AUTH__INTERNAL__SERVER__URL]}' -$ {orch-cli} get configmap che -o \ -jsonpath='{.data.pass:[CHE_WORKSPACE_PLUGIN__REGISTRY__INTERNAL__URL]}' ----- -* If {prod-short} components communicate internally, the output is following: -+ ----- -http://keycloak.eclipse-che.svc:8080/auth -http://plugin-registry.eclipse-che.svc:8080/v3 ----- -* Otherwise, if the components communicate externally, the output is empty. diff --git a/modules/installation-guide/partials/proc_configuring-dns-on-azure.adoc b/modules/installation-guide/partials/proc_configuring-dns-on-azure.adoc deleted file mode 100644 index 9674f8a075..0000000000 --- a/modules/installation-guide/partials/proc_configuring-dns-on-azure.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[id="configuring-DNS-on-azure_{context}"] -= Configuring DNS on Azure - -.Procedure - -To configure DNS on Azure: - -. In the Azure web console, navigate to *Home* -> *DNS zones*. -+ -image::installation/dns-zone-in-microsoft-azure.png[DNS zone in Microsoft Azure,link="../_images/installation/dns-zone-in-microsoft-azure.png"] - -. Create a new zone. -+ -.. In the *Resource group* drop-down list, click *eclipseCheResourceGroup*. -+ -image::installation/selecting-the-resource-group.png[Selecting the resource group,link="../_images/installation/selecting-the-resource-group.png"] - -.. In the *Instance details* section, in the *Name* field, type the name of the domain (`azr.my-ide.cloud`, in this case. You will need to get a domain name from a registrar like Namecheap or GoDaddy). - -.. Click the btn:[Review + create] button. -+ -image::installation/entering-the-name-fo-the-domain.png[Entering the name for the domain,link="../_images/installation/entering-the-name-fo-the-domain.png"] - -. Click the btn:[Create] button. -+ -image::installation/completing-the-creation-of-the-zone.png[Completing the creation of the zone,link="../_images/installation/completing-the-creation-of-the-zone.png"] -+ -The created zone and the list of name servers (NS) are displayed in the *DNS Zones* section. -+ -image::installation/list-of-created-zones-and-NS.png[List of created zones and name servers,link="../_images/installation/list-of-created-zones-and-NS.png"] -+ -These servers must be configured with the registrar of the domain. - -. Navigate to the Azure DNS zone, and click the btn:[+ Record set] button (image:installation/record-set-button.png[width=25px]). - -. To add a record set: -+ -.. In the *Name* field, type _*_. - -.. In the *IP Address* field, select the external IP of Ingress-nginx controller that the user had obtained in the xref:installing-ingress-on-kubernetes_{context}[] section (*40.89.129.194*, in this case). -+ -image::installation/adding-a-record-set.png[Adding a record set,link="../_images/installation/adding-a-record-set.png"] -+ -The following is an example of an added DNS zone: -+ -image::installation/example-of-an-added-dns-zone.png[Example of an added DNS zone,link="../_images/installation/example-of-an-added-dns-zone.png"] diff --git a/modules/installation-guide/partials/proc_configuring-storage-types.adoc b/modules/installation-guide/partials/proc_configuring-storage-types.adoc deleted file mode 100644 index f240ee3ea5..0000000000 --- a/modules/installation-guide/partials/proc_configuring-storage-types.adoc +++ /dev/null @@ -1,126 +0,0 @@ - - - - -[id="configuring-storage-types_{context}"] -= Configuring storage types - -{prod} supports three types of storage with different capabilities: - -* Persistent -* Ephemeral -* Asynchronous - - -== Persistent storage - -Persistent storage allows storing user changes directly in the mounted Persistent Volume. User changes are kept safe by the {platforms-name} infrastructure (storage backend) at the cost of slow I/O, especially with many small files. For example, Node.js projects tend to have many dependencies and the `node_modules/` directory is filled with thousands of small files. - -NOTE: I/O speeds vary depending on the link:https://kubernetes.io/docs/concepts/storage/storage-classes/[Storage Classes] configured in the environment. - -Persistent storage is the default mode for new workspaces. To make this setting visible in workspace configuration, add the following to the devfile: - -[source,yaml] ----- -attributes: - persistVolumes: 'true' ----- - - -== Ephemeral storage - -Ephemeral storage saves files to the link:https://kubernetes.io/docs/concepts/storage/volumes/#emptydir[`emptyDir`] volume. This volume is initially empty. When a Pod is removed from a node, the data in the `emptyDir` volume is deleted forever. This means that all changes are lost on workspace stop or restart. - -IMPORTANT: To save the changes, commit and push to the remote before stopping an ephemeral workspace. - -Ephemeral mode provides faster I/O than persistent storage. To enable this storage type, add the following to workspace configuration: - -[source,yaml] ----- -attributes: - persistVolumes: 'false' ----- - - -.Comparison between I/O of ephemeral (`emptyDir`) and persistent modes on link:https://kubernetes.io/docs/concepts/storage/storage-classes/#aws-ebs[AWS EBS] -[cols="3", options="header"] -|=== -|Command -|Ephemeral -|Persistent - -|Clone {prod} -|0 m 19 s -|1 m 26 s - -|Generate 1000 random files -|1 m 12 s -|44 m 53 s -|=== - - -== Asynchronous storage - -NOTE: Asynchronous storage is an experimental feature. - -Asynchronous storage is a combination of persistent and ephemeral modes. The initial workspace container mounts the `emptyDir` volume. Then a backup is performed on workspace stop, and changes are restored on workspace start. Asynchronous storage provides fast I/O (similar to ephemeral mode), and workspace project changes are persisted. - -Synchronization is performed by the link:https://rsync.samba.org/[rsync] tool using the link:https://www.openssh.com/[SSH] protocol. When a workspace is configured with asynchronous storage, the link:https://github.com/che-incubator/workspace-data-sync/[workspace-data-sync] plug-in is automatically added to the workspace configuration. The plug-in runs the `rsync` command on workspace start to restore changes. When a workspace is stopped, it sends changes to the permanent storage. - -For relatively small projects, the restore procedure is fast, and project source files are immediately available after Che-Theia is initialized. In case `rsync` takes longer, the synchronization process is shown in the Che-Theia status-bar area. (link:https://github.com/eclipse-che/che-theia/tree/master/extensions/eclipse-che-theia-file-sync-tracker[Extension in Che-Theia repository]). - -image::troubleshooting/status-bar-file-sync.png[link="../_images/troubleshooting/status-bar-file-sync.png",Files synchronization progress] - -[NOTE] -==== -Asynchronous mode has the following limitations: - -* Supports only the _common_ PVC strategy -* Supports only the _per-user_ {orch-namespace} strategy -* Only one workspace can be running at a time -==== - -To configure asynchronous storage for a workspace, add the following to workspace configuration: - -[source,yaml] ----- -attributes: - asyncPersist: 'true' - persistVolumes: 'false' ----- - -== Configuring storage type defaults for {prod-short} dashboard - -Use the following two `che.properties` to configure the default client values in {prod-short} dashboard: - -`che.workspace.storage.available_types`:: Defines available values for storage types that clients like the dashboard propose for users during workspace creation or update. Available values: `persistent`, `ephemeral`, and `async`. Separate multiple values by commas. For example: -+ ----- -che.workspace.storage.available_types=persistent,ephemeral,async ----- - -`che.workspace.storage.preferred_type`:: Defines the default value for storage type that clients like the dashboard propose for users during workspace creation. The `async` value is not recommended as the default type because it is experimental. For example: -+ ----- -che.workspace.storage.preferred_type=persistent ----- - -Then users are able to configure Storage Type on the *Create Custom Workspace* tab on {prod-short} dashboard during workspace creation. -Storage type for existing workspace can be configured in on *Overview* tab of the workspace details. - -== Idling asynchronous storage Pods - -{prod-short} can shut down the Asynchronous Storage Pod when not used for a configured period of time. - -Use these configuration properties to adjust the behavior: - -`che.infra.kubernetes.async.storage.shutdown_timeout_min`:: Defines the idle time after which the asynchronous storage Pod is stopped following the stopping of the last active workspace. The default value is 120 minutes. - -`che.infra.kubernetes.async.storage.shutdown_check_period_min`:: Defines the frequency with which the asynchronous storage Pod is checked for idleness. The default value is 30 minutes. - -To increase the timeout of a {prod-short} workspace, use the following example, which sets the workspace timeout for 1800000 milliseconds that correspond to the interval of 30 minutes. -+ -[subs="+attributes",options="nowrap",role=white-space-pre] ----- - $ {orch-cli} patch checluster/{prod-checluster} --patch "{\"spec\":{\"server\":{\"customCheProperties\": {\"CHE_LIMITS_WORKSPACE_IDLE_TIMEOUT\": \"1800000\"}}}}" --type=merge -n {prod-namespace} ----- \ No newline at end of file diff --git a/modules/installation-guide/partials/proc_configuring-the-che-operator-checluster-resource-with-kubectl.adoc b/modules/installation-guide/partials/proc_configuring-the-che-operator-checluster-resource-with-kubectl.adoc deleted file mode 100644 index 11c62061cc..0000000000 --- a/modules/installation-guide/partials/proc_configuring-the-che-operator-checluster-resource-with-kubectl.adoc +++ /dev/null @@ -1,13 +0,0 @@ - - -[id="configuring-the-che-operator-checluster-resource-with-kubectl_{context}"] - -= Configuring CheCluster Custom Resource with {orch-cli} -Edit the CheCluster custom resource configuration with {orch-cli}: - -[subs="+attributes"] ----- -{orch-cli} edit CheCluster/eclipse-che -n {prod-namespace} ----- - -For more details on configuring CheCluster custom resource, see xref:installation-guide:configuring-the-che-installation.adoc[] diff --git a/modules/installation-guide/partials/proc_configuring-the-metallb-load-balancer-on-kubernetes.adoc b/modules/installation-guide/partials/proc_configuring-the-metallb-load-balancer-on-kubernetes.adoc deleted file mode 100644 index 7ecf8a65ac..0000000000 --- a/modules/installation-guide/partials/proc_configuring-the-metallb-load-balancer-on-kubernetes.adoc +++ /dev/null @@ -1,60 +0,0 @@ -[id="configuring-the-metallb-load-balancer-on-kubernetes_{context}"] -= Configuring the MetalLB load balancer on {kubernetes} - -This section describes how to use MetalLB to install a load balancer for {kubernetes} on bare metal. - -.Prerequisites - -* MetalLB installed. See the link:https://metallb.universe.tf/installation/[installation guide]. - -.Procedure - -. Configure {kubernetes} proxy: -+ ----- -$ kubectl edit configmap -n kube-system kube-proxy ----- -+ -and set: -+ -[source,yaml] ----- -apiVersion: kubeproxy.config.k8s.io/v1alpha1 -kind: KubeProxyConfiguration -mode: "ipvs" -ipvs: - strictARP: true ----- - -. Apply the MetalLB manifests: -+ ----- -$ kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.3/manifests/namespace.yaml -$ kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.3/manifests/metallb.yaml - -# On first install only: -$ kubectl create secret generic -n metallb-system memberlist \ - --from-literal=secretkey="$(openssl rand -base64 128)" ----- - -. Configure MetalLB. To allow the load balancer to distribute external IPs, specify in its configuration the IP range allocated for it: -+ -[subs="+quotes"] ----- -$ cat << EOF | kubectl apply -f - -apiVersion: v1 -kind: ConfigMap -metadata: - namespace: metallb-system - name: config -data: - config: | - address-pools: - - name: default - protocol: layer2 - addresses: - - _<your-ip-range>_ -EOF ----- -+ -NOTE: Set `_<your-ip-range>_` to the IP range you intend to use. diff --git a/modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-run.adoc b/modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-run.adoc deleted file mode 100644 index 7e1876ad84..0000000000 --- a/modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-run.adoc +++ /dev/null @@ -1,57 +0,0 @@ - -[id="configuring-the-number-of-workspaces-that-a-user-can-run_{context}"] -= Configuring the number of workspaces that a user can run - -This procedure describes how to configure {prod-short} to run more than one workspace simultaneously. By running multiple workspaces, users can use different work environments simultaneously. - -.Prerequisites -* You have installed an instance of {prod-short} by using the Operator. -* The combination of storage strategy and access mode matches one of the following cases: -+ -.Multiple workspaces compatibility list -[width="100%",cols="2,1,1,1",options="header"] -|=== -| Storage strategy -| `common` (default) -| `per-workspace` -| `unique` - - -|`ReadWriteMany` access mode -| yes -| yes -| yes - -| `ReadWriteOnce` access mode -| no -| yes -| yes -|=== - -** To determine the access modes supported by your storage, see link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes[Kubernetes documentation - Access Modes]. For example, link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html[Amazon EBS] only supports the `ReadWriteOnce` access mode. -** See xref:configuring-storage-strategies.adoc[]. - -* You have determined the value of the `_<number-of-workspaces>_` placeholder. -+ -[NOTE] -==== -If the value is `-1`, an unlimited number of workspaces can run per user. If the value is a positive integer, users can run as many workspaces as the value of the integer. The default value is `1`. -==== - -.Procedure - -* In the `CheCluster` Custom Resource `server` settings, configure the number of workspaces that a user can run by adding the `+CHE_LIMITS_USER_WORKSPACES_RUN_COUNT+` property to `customCheProperties`: -+ -==== -[source,yaml,subs="+quotes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheCluster -# ... -spec: - server: - # ... - customCheProperties: - CHE_LIMITS_USER_WORKSPACES_RUN_COUNT: "__<number-of-workspaces>__" ----- -==== diff --git a/modules/installation-guide/partials/proc_configuring-workspace-exposure-strategies-using-an-operator.adoc b/modules/installation-guide/partials/proc_configuring-workspace-exposure-strategies-using-an-operator.adoc deleted file mode 100644 index 27dd0e6854..0000000000 --- a/modules/installation-guide/partials/proc_configuring-workspace-exposure-strategies-using-an-operator.adoc +++ /dev/null @@ -1,90 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-workspace-exposure-strategies - -[id="configuring-workspace-exposure-strategies-using-an-operator_{context}"] -= Configuring workspace exposure strategies using an Operator - -link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Operators] are software extensions to {platforms-name} that use link:https://docs.openshift.com/container-platform/latest/operators/understanding/crds/crd-managing-resources-from-crds.html[Custom Resources] to manage applications and their components. - -.Prerequisites - -* The `{orch-cli}` tool is available. - -.Procedure - -When deploying {prod-short} using the Operator, configure the intended strategy by modifying the `spec.server.serverExposureStrategy` property of the CheCluster Custom Resource object YAML file. - -The supported values for `spec.server.serverExposureStrategy` are: - -* xref:multi-host-workspace-exposure-strategy_{context}[`multi-host`] -* xref:single-host-workspace-exposure-strategy_{context}[`single-host`] -ifeval::["{project-context}" == "che"] -* xref:default-host-workspace-exposure-strategy_{context}[`default-host`] -endif::[] - -See xref:workspace-exposure-strategies_{context}[] for more detail about individual strategies. - -To activate changes done to CheCluster YAML file, do one of the following: - -* Create a new cluster by executing the `{prod-cli}` command with applying a patch. For example: -+ -[subs="+quotes,+attributes"] ----- -$ {prod-cli} server:deploy --installer=operator --platform=__<platform>__ \ - --che-operator-cr-patch-yaml=patch.yaml ----- -+ -[NOTE] -==== -For a list of available {platforms-name} deployment platforms, use `{prod-cli} server:deploy --platform --help`. -==== -+ - -** Use the following `patch.yaml` file: -+ -[source,yaml,subs="+quotes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheCluster -metadata: - name: eclipse-che -spec: - server: - serverExposureStrategy: '__<exposure-strategy>__' <1> ----- -<1> - used workspace exposure strategy - - -* Update the YAML file properties of an already running cluster by executing the `{orch-cli} patch` command. For example: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} patch checluster/{prod-checluster} --type=json \ - -p '[{"op": "replace", - "path": "/spec/server/serverExposureStrategy", - "value": "__<exposure-strategy>__"}]' \ <1> - -n {prod-namespace} ----- -<1> - used workspace exposure strategy - -ifeval::["{project-context}" == "che"] - -.Gateway single-host on {orch-name} -Single-host on {orch-name} has two implementations, `native`(default) and `gateway`. To deploy with `gateway` set the `k8s.singleHostExposureType` of CheCluster Custom Resource to `gateway`, or use this patch: - -[source,yaml,subs="+quotes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheCluster -metadata: - name: eclipse-che -spec: - server: - serverExposureStrategy: 'single-host' - k8s: - singleHostExposureType: 'gateway' - ----- - -endif::[] diff --git a/modules/installation-guide/partials/proc_creating-a-google-kubernetes-engine-instance.adoc b/modules/installation-guide/partials/proc_creating-a-google-kubernetes-engine-instance.adoc deleted file mode 100644 index 0c412d8e08..0000000000 --- a/modules/installation-guide/partials/proc_creating-a-google-kubernetes-engine-instance.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-google-cloud-platform -// preparing-google-cloud-platform-for-installing-che - -[id="creating-a-google-kubernetes-engine-instance_using_the_SDK_{context}"] -= Creating a Google {kubernetes} Engine instance - -This section describes how to create a Google {kubernetes} Engine instance. - - -.Prerequisites - -* The Google Cloud SDK is available. See link:https://cloud.google.com/sdk/install[Installing Google Cloud SDK]. -+ -[NOTE] -==== -To install the SDK on macOS, use the `$ brew cask install google-cloud-sdk` command. -==== - -.Procedure - -. Ensure the `gcloud` tool is configured: -+ ----- -$ gcloud init ----- - -. Create a new project with the `eclipse-che-1` ID: -+ ----- -$ gcloud projects create eclipse-che-1 ----- - -. Check from GCP Web Console that the {kubernetes} engine is available on this project. - -. Configure the different default options (such as using the `europe-west1-b` zone) in the shell: -+ ----- -$ gcloud config set project eclipse-che-1 -$ gcloud config set compute/zone europe-west1-b -$ gcloud config set compute/region europe-west1 ----- - -. Check all the components are up-to-date: -+ ----- -$ gcloud components update -All components are up to date. ----- - -. Create a cluster with the name `eclipse-che`: -+ ----- -$ gcloud container clusters create eclipse-che --zone europe-west1-b ----- - -. Wait for the cluster to be ready. - -. This commands updates the {kubernetes} context. To verify it: -+ ----- -$ kubectl config current-context -gke_eclipse-che-1_europe-west1-b_eclipse-che ----- - diff --git a/modules/installation-guide/partials/proc_creating-a-service-account-secret-on-azure.adoc b/modules/installation-guide/partials/proc_creating-a-service-account-secret-on-azure.adoc deleted file mode 100644 index ff467123b7..0000000000 --- a/modules/installation-guide/partials/proc_creating-a-service-account-secret-on-azure.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-microsoft-azure - -[id="creating-a-service-account-secret-on-azure_{context}"] -= Creating a Service Account Secret on Azure - -The secret must be in the *cert-manager* {orch-namespace}. Otherwise the secret cannot be found, and cert-manager reports errors. - -.Procedure - -To create the secret, run the following command: - ----- -$ kubectl create secret generic azuredns-config \ - --from-literal=CLIENT_SECRET=$AZURE_CERT_MANAGER_SP_PASSWORD -n cert-manager ----- diff --git a/modules/installation-guide/partials/proc_creating-a-service-account-secret-on-google-cloud-platform.adoc b/modules/installation-guide/partials/proc_creating-a-service-account-secret-on-google-cloud-platform.adoc deleted file mode 100644 index c2ef72bfc5..0000000000 --- a/modules/installation-guide/partials/proc_creating-a-service-account-secret-on-google-cloud-platform.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// preparing-google-cloud-platform-for-installing-che - -[id="creating-a-service-account-secret-on-google-cloud-platform_{context}"] -= Creating a Service Account Secret on Google Cloud Platform - - -.Procedure - -To access the service account, cert-manager uses a key stored in a {kubernetes} Secret. - -. Create a key for the service account and download it as a JSON file: -+ ----- -$ gcloud iam service-accounts keys create key.json \ - --iam-account dns01-solver@eclipse-che-1.iam.gserviceaccount.com ----- -The following is the output of the preceding command: -+ ----- -created key [05e94ca2e7754b94a63049605ee8d2813d16ff37] of type [json] as [key.json] for [dns01-solver@eclipse-che-1.iam.gserviceaccount.com] ----- -+ -The key file is generated: -+ ----- -$ ls -la key.json --rw------- 1 joe staff 2318 Jul 29 12:13 key.json ----- -+ -IMPORTANT: Keep the key file safe, and do not share it with anyone because it can be used to gain access to your cloud resources. The key file can be deleted after it has been used to generate the Secret. - -. Create cert-manager namespace -+ ----- -$ kubectl create ns cert-manager ----- - -. Create a Secret from this file. -+ ----- -$ kubectl create secret generic clouddns-dns01-solver-svc-acct --from-file=key.json --namespace=cert-manager ----- diff --git a/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc b/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc deleted file mode 100644 index 8468f91652..0000000000 --- a/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc +++ /dev/null @@ -1,67 +0,0 @@ - -[id="enabling-dev-workspace-operator_{context}"] -= Enabling {devworkspace} operator - -This procedure describes how to enable the {devworkspace} operator to support the Devfile 2.0.0 file format and mentions how to do so on existing instances or those about to be installed. - -.Prerequisites - -* The `{orch-cli}` and `{prod-cli}` tools are available. - - -.Procedure - -* For a new OperatorHub installation: -+ -. Enter the {prod} Cluster using {ocp} and create CheCluster Custom Resource (CR). See, xref:installing-che-on-openshift-4-using-operatorhub#creating-an-instance-of-the-{prod-id-short}-operator_{context}[Creating an instance of the {prod} Operator] - -+ -. Set the following values in {prod-checluster} Custom Resource (CR): -+ -[source,yaml,subs="+quotes"] ----- -spec: - devWorkspace: - enable: true ----- - - -* For a new `{prod-cli}` installation: -+ -. Configure the the `{prod-cli}` installation using: -+ -[subs="+quotes,+attributes"] ----- -$ {prod-cli} server:deploy --che-operator-cr-patch-yaml=patch.yaml ... ----- -+ -`patch.yaml` must contain the following: -+ -[source,yaml,subs="+quotes"] ----- -spec: - devWorkspace: - enable: true ----- - -* For already existing {prod-short} installation: -+ -. Update `{prod-checluster}` CR using the `{orch-cli}` tool: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/devWorkspace/enable", "value": true}]' ----- - -ifeval::["{project-context}" == "che"] -[WARNING] -==== -* Before enabling {devworkspace} operator on existed Kubernetes-based {prod-short} installation, install cert-manager. -==== -endif::[] - -.Additional resources - -For information about installation methods mentioned in this chapter, see xref:installing-che.adoc[]. - diff --git a/modules/installation-guide/partials/proc_enabling-the-tls-dns-challenge-on-azure.adoc b/modules/installation-guide/partials/proc_enabling-the-tls-dns-challenge-on-azure.adoc deleted file mode 100644 index 56b8ac4783..0000000000 --- a/modules/installation-guide/partials/proc_enabling-the-tls-dns-challenge-on-azure.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-microsoft-azure - -[id="enabling-the-TLS-DNS-challenge-on-azure_{context}"] -= Enabling the TLS and DNS challenge on Azure - -To use Azure DNS and TLS, permissions must be granted to have cert-manager managing the DNS challenge for the _Let’s Encrypt_ service. - -.Procedure - -. Set the variable for the domain: -+ ----- -AZURE_CERT_MANAGER_DNS_NAME=azr.my-ide.cloud ----- - -. Generate the secrets: -+ ----- -AZURE_CERT_MANAGER_SP_APP_ID=$(az ad sp create-for-rbac --name cert-manager-eclipse-che --query "appId" --output tsv) -AZURE_CERT_MANAGER_SP_PASSWORD=$(az ad sp create-for-rbac --name cert-manager-eclipse-che --query "password" --output tsv) ----- - -. Lower the permissions of the service principal (SP): -+ ----- -$ az role assignment delete --assignee $AZURE_CERT_MANAGER_SP_APP_ID --role Contributor ----- - -. Give access to the DNS zone: -+ ----- -DNS_ID=$(az network dns zone show --name $AZURE_CERT_MANAGER_DNS_NAME --resource-group eclipseCheResourceGroup --query "id" --output tsv) - -$ az role assignment create --assignee $AZURE_CERT_MANAGER_SP_APP_ID \ - --role "DNS Zone Contributor" --scope $DNS_ID ----- - -. Check the permissions: -+ ----- -$ az role assignment list --assignee $AZURE_CERT_MANAGER_SP_APP_ID ----- - -. Get the Service Principal App ID and password for the configuration: -+ ----- -$ echo ID=$AZURE_CERT_MANAGER_SP_APP_ID -$ echo PASSWORD=$AZURE_CERT_MANAGER_SP_PASSWORD ----- diff --git a/modules/installation-guide/partials/proc_enabling-the-tls-dns-challenge-on-google-cloud-platform.adoc b/modules/installation-guide/partials/proc_enabling-the-tls-dns-challenge-on-google-cloud-platform.adoc deleted file mode 100644 index 42856598fa..0000000000 --- a/modules/installation-guide/partials/proc_enabling-the-tls-dns-challenge-on-google-cloud-platform.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// preparing-google-cloud-platform-for-installing-che - -[id="enabling-the-tls-dns-challenge-on-google-cloud-platform_{context}"] -= Enabling the TLS and DNS challenge on Google Cloud Platform - - -.Procedure - -To use the Cloud DNS and TLS, service accounts must be enabled, and cert-manager must manage the DNS challenge for the _Let’s Encrypt_ service. - -. Create a service account with the given name: -+ ----- -$ gcloud iam service-accounts create dns01-solver --display-name "dns01-solver" ----- - -. Add the policy binding to the IAM policy of the *eclipse-che-1* project (replace the *eclipse-che-1* project name with the name of your project): -+ ----- -$ gcloud projects add-iam-policy-binding eclipse-che-1 \ - --member serviceAccount:dns01-solver@eclipse-che-1.iam.gserviceaccount.com \ - --role roles/dns.admin ----- -+ -The following is the output of this command: -+ ----- -Updated IAM policy for project [eclipse-che-1]. - -bindings: -- members: - - serviceAccount:service-779451692063@compute-system.iam.gserviceaccount.com - role: roles/compute.serviceAgent -- members: - - serviceAccount:service-779451692063@container-engine-robot.iam.gserviceaccount.com - role: roles/container.serviceAgent -- members: - - serviceAccount:dns01-solver@eclipse-che-1.iam.gserviceaccount.com - role: roles/dns.admin -- members: - - serviceAccount:779451692063-compute@developer.gserviceaccount.com - - serviceAccount:779451692063@cloudservices.gserviceaccount.com - - serviceAccount:service-779451692063@containerregistry.iam.gserviceaccount.com - role: roles/editor -- members: - - user:<email-address> - role: roles/owner -etag: <some-tag> -version: 1 ----- diff --git a/modules/installation-guide/partials/proc_generating-self-signed-certificates.adoc b/modules/installation-guide/partials/proc_generating-self-signed-certificates.adoc deleted file mode 100644 index 8308486b97..0000000000 --- a/modules/installation-guide/partials/proc_generating-self-signed-certificates.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates - -[id="generating-self-signed-certificates_{context}"] -= Generating self-signed TLS certificates - -This section describes how to prepare self-signed TLS certificates to use with {prod-short} on Minishift. - - -.Prerequisites - -* The expected domain name where the {prod-short} deployment is planned. Typically, for Minishift, this is `$(minishift ip).nip.io` - -* The location of the `openssl.cnf` file on the target machine. -+ -.Usual OpenSSL configuration file locations -[options="header"] -|=== -| Linux distribution | File location -| Fedora, Red Hat Enterprise Linux, CentOS | `/etc/pki/tls/openssl.cnf` -| Debian, Ubuntu, Mint, Arch Linux | `/etc/ssl/openssl.cnf` -|=== - -.Procedure - -. Set the necessary environment variables: -+ -[subs="+attributes,quotes"] ----- -$ CA_CN="Local {prod} Signer" -$ DOMAIN=*.__<expected.domain.com>__ -$ OPENSSL_CNF=__<path_to_openssl.cnf>__ ----- -ifeval::["{project-context}" == "che"] -+ -.Example (Fedora) -[subs="+attributes,quotes"] ----- -$ CA_CN="Local {prod} Signer" -$ DOMAIN=\*.$( minishift ip ).nip.io -$ OPENSSL_CNF=/etc/pki/tls/openssl.cnf ----- -+ -.Example (macOS) -[subs="+attributes,quotes"] ----- -$ export CA_CN="Local {prod} Signer" -$ export DOMAIN=\*.$( minishift ip ).nip.io -$ export OPENSSL_CNF=/System/Library/OpenSSL/openssl.cnf ----- -endif::[] - -. Generate the root Certificate Authority (CA) key. Add the `-des3` parameter to use a passphrase: -+ -[subs="+quotes"] ----- -$ openssl genrsa -out ca.key 4096 ----- - -. Generate the root CA certificate: -+ -[subs="+quotes"] ----- -$ openssl req -x509 \ - -new -nodes \ - -key ca.key \ - -sha256 \ - -days 1024 \ - -out ca.crt \ - -subj /CN="${CA_CN}" \ - -reqexts SAN \ - -extensions SAN \ - -config <(cat ${OPENSSL_CNF} \ - <(printf '[SAN]\nbasicConstraints=critical, CA:TRUE\nkeyUsage=keyCertSign, cRLSign, digitalSignature')) ----- - -. Generate the domain key: -+ -[subs="+quotes"] ----- -$ openssl genrsa -out domain.key 2048 ----- - -. Generate the certificate signing request for the domain: -+ -[subs="+attributes,quotes"] ----- -$ openssl req -new -sha256 \ - -key domain.key \ - -subj "/O=Local {prod}/CN=$\{DOMAIN}" \ - -reqexts SAN \ - -config <(cat $\{OPENSSL_CNF} \ - <(printf "\n[SAN]\nsubjectAltName=DNS:$\{DOMAIN}\nbasicConstraints=critical, CA:FALSE\nkeyUsage=digitalSignature, keyEncipherment, keyAgreement, dataEncipherment\nextendedKeyUsage=serverAuth")) \ - -out domain.csr ----- - -. Generate the domain certificate: -+ -[subs="+quotes"] ----- -$ openssl x509 \ - -req \ - -sha256 \ - -extfile <(printf "subjectAltName=DNS:${DOMAIN}\nbasicConstraints=critical, CA:FALSE\nkeyUsage=digitalSignature, keyEncipherment, keyAgreement, dataEncipherment\nextendedKeyUsage=serverAuth") \ - -days 365 \ - -in domain.csr \ - -CA ca.crt \ - -CAkey ca.key \ - -CAcreateserial -out domain.crt ----- - -This procedure allows to use `domain.crt` and `domain.key` for TLS Route and Ingress, and `ca.crt` for importing into browsers. - -.Additional resources - -* xref:end-user-guide:importing-certificates-to-browsers.adoc[] diff --git a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates-old.adoc b/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates-old.adoc deleted file mode 100644 index ef9e3109bf..0000000000 --- a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates-old.adoc +++ /dev/null @@ -1,263 +0,0 @@ - -[id="importing-untrusted-tls-certificates_{context}"] -= Importing untrusted TLS certificates to {prod-short} - -==== -NOTE: This obsolete method is kept for backward compatibility . See xref:importing-untrusted-tls-certificates.adoc[] -==== - -Internal communications between {prod-short} components are, by default, encrypted with TLS. Communications of {prod-short} components with external services such as proxies, source code repositories, identity providers may require TLS tool. Those communications require the use of TLS certificates signed by trusted Certificate Authorities. - -When the certificates used by {prod-short} components or by an external service are signed by an untrusted CA it can be necessary to import the CA certificate in the {prod-short} installation, so that every {prod-short} component will consider them as signed by a trusted CA. - -Typical cases that may require this addition are: - -* when the underlying {orch-name} cluster uses TLS certificates signed by a CA that is not trusted, -* when {prod-short} server or workspace components connect to external services such as {identity-provider} or a Git server that use TLS certificates signed by an untrusted CA. - -To store those certificates, {prod-short} uses a dedicated ConfigMap. Its default name is `ca-certs` but {prod-short} allows configuring its name. - -[NOTE] -==== -ifeval::["{project-context}" == "che"] -On OpenShift, when -endif::[] -ifeval::["{project-context}" != "che"] -When -endif::[] -the cluster contains cluster-wide trusted CA certificates added using the link:https://docs.openshift.com/container-platform/4.4/networking/configuring-a-custom-pki.html#nw-proxy-configure-object_configuring-a-custom-pki[cluster-wide-proxy configuration], {prod-short} Operator detects them and automatically injects them into this ConfigMap: - -- {prod-short} automatically labels the ConfigMap with the `config.openshift.io/inject-trusted-cabundle="true"` label. -- Based on this annotation, OpenShift automatically injects the cluster-wide trusted CA certificates inside the `ca-bundle.crt` key of ConfigMap -==== - -== At {prod-short} installation time - -.Prerequisites - -* The `{orch-cli}` tool is available. -* You are ready to create `CheCluster` custom resource. - -.Procedure - -include::example$snip_importing-untrusted-tls-certificates_1.adoc[] - -. Create a new ConfigMap with the required TLS certificates: -+ -[subs="+attributes,+quotes"] ----- -$ {orch-cli} create configmap ca-certs --from-file=__<certificate-file-path>__ -n={prod-namespace} ----- -+ -To apply more than one certificate, add another `--from-file=_<certificate-file-path>_` option to the above command. - -. During the installation process, when creating the `CheCluster` custom resource, configure the right name for the created ConfigMap. -+ -==== -For a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Operator] deployment, -ensure you add the `spec.server.ServerTrustStoreConfigMapName` field with the name of the ConfigMap, to the `CheCluster` Custom Resource you will create during the installation: - -[source,yaml,subs="+quotes",options="nowrap",role=white-space-pre] ----- -spec: - server: - ... - spec.server.ServerTrustStoreConfigMapName: ca-certs ----- -==== - -== On already-running {prod-short} installations - -.Prerequisites - -* The `{orch-cli}` tool is available. - -* You should first gather the name of the ConfigMap used to import certificates: -+ -==== -On instances of {prod-short} deployed with the {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Operator], -retrieve the name of the ConfigMap by reading the `spec.server.ServerTrustStoreConfigMapName` `CheCluster` Custom Resource property: - -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath={.spec.server.serverTrustStoreConfigMapName} ----- -==== -+ -[NOTE] -==== -If the existing installation did not define any name for the ConfigMap, just use `ca-certs`. -==== - -.Procedure - -include::example$snip_importing-untrusted-tls-certificates_1.adoc[] - -. Add the required TLS certificates in the ConfigMap: -+ -[subs="+attributes,+quotes"] ----- -$ {orch-cli} create configmap __<config-map-name>__ --from-file=__<certificate-file-path>__ -n={prod-namespace} -o yaml --dry-run | {orch-cli} apply -f - ----- -+ -To apply more than one certificate, add another `--from-file=_<certificate-file-path>_` option to the above command. - -. Configure the {prod-short} installation to use the ConfigMap: -+ -==== -For a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Operators] deployment: - -. Edit the `spec.server.ServerTrustStoreConfigMapName` `CheCluster` Custom Resource property to match the name of the ConfigMap: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p '[{"op": "replace", "path": "/spec/server/serverTrustStoreConfigMapName", "value": "<config-map-name>"}]' ----- -+ -==== - -. Restart the {prod-short} Operator, the {prod-short} server and {identity-provider} to load the new certificates: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ kubectl rollout restart -n {prod-namespace} deployment/{prod-id-short}-operator -$ kubectl rollout restart -n {prod-namespace} deployment/keycloak -$ kubectl rollout restart -n {prod-namespace} deployment/{prod-id-short} ----- -+ -[NOTE] -==== -Restarting the {prod-short} components is not required anymore on {prod-short} -ifeval::["{project-context}" == "che"] -v7.20.0 -endif::[] -ifeval::["{project-context}" != "che"] -2.5.0 -endif::[] -and higher. -==== - -== Verification at the {prod-short} installation level - -If you added the certificates without error, the {prod-short} server starts and obtains {identity-provider} configuration over https. Otherwise here is a list of things to verify: - -. In case of a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Operator] deployment, the `CheCluster` attribute `serverTrustStoreConfigMapName` value matches the name of the ConfigMap. Get the value using the following command : -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get -o json checluster/{prod-checluster} -n {prod-namespace} | jq .spec.server.serverTrustStoreConfigMapName ----- -+ -. {prod-short} Pod Volumes list contains one Volume that uses the ConfigMap as data-source. To get the list of Volumes of the {prod-short} Pod: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get pod -o json __<{prod-id-short}-pod-name>__ -n {prod-namespace} | jq .spec.volumes ----- -+ -. {prod-short} mounts certificates in folder `/public-certs/` of the {prod-short} server container. This command returns the list of files in that folder: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} exec -t __<{prod-id-short}-pod-name>__ -n {prod-namespace} -- ls /public-certs/ ----- -+ -. In the {prod-short} server logs there is a line for every certificate added to the Java truststore, including configured {prod-short} certificates. -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} logs __<{prod-id-short}-pod-name>__ -n {prod-namespace} -(...) -Found a custom cert. Adding it to java trust store based on /usr/lib/jvm/java-1.8.0/jre/lib/security/cacerts -(...) ----- -+ -. {prod-short} server Java truststore contains the certificates. The certificates SHA1 fingerprints are among the list of the SHA1 of the certificates included in the truststore returned by the following command: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} exec -t __<{prod-id-short}-pod-name>__ -n {prod-namespace} -- keytool -list -keystore {prod-home}/cacerts -Your keystore contains 141 entries - -(...) ----- -+ -To get the SHA1 hash of a certificate on the local filesystem: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ openssl x509 -in __<certificate-file-path>__ -fingerprint -noout -SHA1 Fingerprint=3F:DA:BF:E7:A7:A7:90:62:CA:CF:C7:55:0E:1D:7D:05:16:7D:45:60 ----- - -== Verification at the workspace level - -. Start a workspace, get the {orch-namespace} in which it has been created, and wait for it to be started. - -. Get the name of the workspace Pod: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get pods -o=jsonpath='{.items[0].metadata.name}' -n __<workspace namespace>__ | grep '^workspace.*' ----- - -. Get the name of the Che-Theia IDE container in the workspace Pod: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get -o json pod __<workspace pod name>__ -n __<workspace namespace>__ | \ - jq -r '.spec.containers[] | select(.name | startswith("theia-ide")).name' ----- - -. Look for a `ca-certs` ConfigMap inside the workspace namespace: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get cm ca-certs __<workspace namespace>__ ----- - -. Check that the entries in the `ca-certs` ConfigMap contain all the additional entries you added in the certificate ConfigMap at the {prod-short} installation level, in addition to the reserved `ca-bundle.crt` entry: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get cm ca-certs -n __<workspace namespace>__ -o json | jq -r '.data | keys[]' -ca-bundle.crt -manually-added-certificate.crt ----- - -. Make sure that the `ca-certs` ConfigMap has been added as a volume in the workspace Pod: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get -o json pod __<workspace pod name>__ -n {prod-namespace} | \ - jq '.spec.volumes[] | select(.configMap.name == "ca-certs")' -{ - "configMap": { - "defaultMode": 420, - "name": "ca-certs" - }, - "name": "che-self-signed-certs" -} ----- - -. Confirm that the volume has been mounted into containers, especially in the Che-Theia IDE container: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get -o json pod __<workspace pod name>__ -n __<workspace namespace>__ | \ - jq '.spec.containers[] | select(.name == "__<theia ide container name>__").volumeMounts[] | select(.name == "che-self-signed-certs")' -{ - "mountPath": "/public-certs", - "name": "che-self-signed-certs", - "readOnly": true -} ----- - -. Inspect `/public-certs` folder on the Che-Theia IDE container and check that its contents match the list of entries in the `ca-certs` ConfigMap: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} exec __<workspace pod name>__ -c __<theia ide container name>__ -n __<workspace namespace>__ -- ls /public-certs -ca-bundle.crt -manually-added-certificate.crt ----- diff --git a/modules/installation-guide/partials/proc_installing-cert-manager-on-kubernetes.adoc b/modules/installation-guide/partials/proc_installing-cert-manager-on-kubernetes.adoc deleted file mode 100644 index 36eec7f71d..0000000000 --- a/modules/installation-guide/partials/proc_installing-cert-manager-on-kubernetes.adoc +++ /dev/null @@ -1,140 +0,0 @@ -// Module included in the following assemblies: -// -// preparing-google-cloud-platform-for-installing-che - -[id="installing-cert-manager-on-kubernetes_{context}"] -= Installing cert-manager on {kubernetes} - - -.Procedure - -. To install cert-manager: -+ ----- -$ kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true - -$ kubectl apply \ - -f https://github.com/jetstack/cert-manager/releases/download/v0.15.0/cert-manager.yaml \ - --validate=false ----- - -. Create the *che* {orch-namespace} if it does not exist already: -+ -[subs="+quotes,+attributes"] ----- -$ kubectl create namespace __{prod-namespace}__ -namespace/__{prod-namespace}__ created ----- - -. Create the certificate issuer. Replace your email address in the `email` field: -+ ----- -$ cat <<EOF | kubectl apply -f - -apiVersion: cert-manager.io/v1alpha2 -kind: ClusterIssuer -metadata: - name: che-certificate-issuer -spec: - acme: - solvers: - - dns01: - clouddns: - project: eclipse-che-1 - serviceAccountSecretRef: - key: key.json - name: clouddns-dns01-solver-svc-acct - email: joe@example.com - privateKeySecretRef: - name: letsencrypt - server: https://acme-v02.api.letsencrypt.org/directory -EOF ----- - -. Create the certificate. Edit the domain name: -+ -[subs="+quotes,+attributes"] ----- -$ cat <<EOF | kubectl apply -f - -apiVersion: cert-manager.io/v1alpha2 -kind: Certificate -metadata: - name: che-tls - namespace: {prod-namespace} -spec: - secretName: che-tls - issuerRef: - name: che-certificate-issuer - kind: ClusterIssuer - dnsNames: - - '*.gcp.my-ide.cloud' -EOF - ----- - -. Check that the `issuerRef` name is the same as the `ClusterIssuer`. A new DNS challenge is added to the DNS zone for _Let’s Encrypt_. -+ -image::installation/dns-challenge-gcp.png[DNS challenge,link="../_images/installation/dns-challenge-gcp.png"] - -. The cert-manager logs contain information about the DNS challenge. To get the logs (here, `cert-manager-8d478bb45-2924h` is the name of the cert-manager Pod): -+ -[subs="+quotes,+attributes"] ----- -$ kubectl logs -f -n cert-manager cert-manager-8d478bb45-2924h - -I0729 13:50:39.414729 1 dns.go:112] Checking DNS propagation for "gcp.my-ide.cloud" using name servers: [10.112.0.10:53] - -E0729 13:50:39.422521 1 sync.go:180] cert-manager/controller/challenges "msg"="propagation check failed" "error"="DNS record for \"gcp.my-ide.cloud\" not yet propagated" "dnsName"="gcp.my-ide.cloud" "resource_kind"="Challenge" "resource_name"="che-tls-3529929423-0" "resource_namespace"="che" "type"="dns-01" - -I0729 13:50:39.422598 1 controller.go:219] cert-manager/controller/challenges "level"=0 "msg"="finished processing work item" "key"="che/che-tls-3529929423-0" - -I0729 13:50:49.406767 1 controller.go:213] cert-manager/controller/challenges "level"=0 "msg"="syncing resource" "key"="che/che-tls-3529929423-0" - -I0729 13:50:49.409802 1 dns.go:112] Checking DNS propagation for "gcp.my-ide.cloud" using name servers: [10.112.0.10:53] - -E0729 13:50:49.420131 1 sync.go:180] cert-manager/controller/challenges "msg"="propagation check failed" "error"="DNS record for \"gcp.my-ide.cloud\" not yet propagated" "dnsName"="gcp.my-ide.cloud" "resource_kind"="Challenge" "resource_name"="che-tls-3529929423-0" "resource_namespace"="__<{prod-namespace}>__" "type"="dns-01" - -I0729 13:50:49.420198 1 controller.go:219] cert-manager/controller/challenges "level"=0 "msg"="finished processing work item" "key"="che/che-tls-3529929423-0" ----- - -. Ensure that the certificate is ready: -+ -[subs="+quotes,+attributes"] ----- -$ kubectl describe certificate/che-tls -n {prod-namespace} - -Status: - Conditions: - Last Transition Time: 2019-07-29T13:50:35Z - Message: Certificate issuance in progress. Temporary certificate issued. - Reason: TemporaryCertificate - Status: False - Type: Ready -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Generated 47s cert-manager Generated new private key - Normal GenerateSelfSigned 47s cert-manager Generated temporary self signed certificate - Normal OrderCreated 47s cert-manager Created Order resource "che-tls-3529929423" ----- -+ -Wait for the `Status` to become `OK`, and ensure that the log contains the following entry: -+ ----- -I0729 13:56:26.140886 1 conditions.go:143] Found status change for Certificate "che-tls" condition "Ready": "False" -> "True"; setting lastTransitionTime to 2019-07-29 13:56:26.140866531 +0000 UTC m=+4557.134131468 ----- - -. Ensure that the status is up-to-date: -+ -[subs="+quotes,+attributes"] ----- -$ kubectl describe certificate/che-tls -n __<{prod-namespace}>__ - -Status: - Conditions: - Last Transition Time: 2019-07-29T13:56:26Z - Message: Certificate is up to date and has not expired - Reason: Ready - Status: True - Type: Ready - Not After: 2019-10-27T12:56:24Z ----- diff --git a/modules/installation-guide/partials/proc_installing-cert-manager.adoc b/modules/installation-guide/partials/proc_installing-cert-manager.adoc deleted file mode 100644 index 3d550559f9..0000000000 --- a/modules/installation-guide/partials/proc_installing-cert-manager.adoc +++ /dev/null @@ -1,175 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-microsoft-azure - -[id="installing-cert-manager-on-azure_{context}"] -= Installing cert-manager on Azure - - -.Prerequisites - -* The `{orch-cli}` tool is available. - -.Procedure - -. To install the cert-manager on Azure, create the *cert-manager* namespace: -+ -[subs="+attributes"] ----- -$ {orch-cli} create namespace cert-manager -namespace/cert-manager created - -$ {orch-cli} label namespace cert-manager certmanager.k8s.io/disable-validation=true ----- -+ -[subs="+attributes"] ----- -$ {orch-cli} apply \ - -f https://github.com/jetstack/cert-manager/releases/download/v1.3.2/cert-manager.yaml ----- -+ -[subs="+attributes"] ----- -$ {orch-cli} apply \ - --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.3.2/cert-manager.crds.yaml ----- - - -. Create the *che* {orch-namespace} if it does not already exist: -+ -[subs="+attributes"] ----- -$ {orch-cli} create namespace {prod-namespace} -namespace/{prod-namespace} created ----- - -. Create the certificate issuer. Enter your email address in the *email* field and set *clientID*, *CLIENT_SECRET* *subscriptionID*, *tenantID*, *hostedZoneName* fields: -+ -[source,yaml,subs="+attributes"] ----- -cat <<EOF | {orch-cli} apply -f - -apiVersion: cert-manager.io/v1alpha2 -kind: ClusterIssuer -metadata: - name: che-certificate-issuer -spec: - acme: - solvers: - - dns01: - azuredns: - # Service principal clientId (It's the value printed in the previous lines: echo ID=$AZURE_CERT_MANAGER_SP_APP_ID ) - clientID: <AZURE_CERT_MANAGER_SP_APP_ID> - # A secretKeyRef to a service principal ClientSecret (password) - # ref: https://docs.microsoft.com/en-us/azure/container-service/kubernetes/container-service-kubernetes-service-principal - clientSecretSecretRef: - name: azuredns-config - key: CLIENT_SECRET - # Azure subscription Id that can be obtained with command: - # $ az account show | jq -r '.id' - subscriptionID: <SUBSCRIPTION_ID> - # Azure AD tenant Id that can be obtained with command: - # $ az account show | jq -r '.tenantId' - tenantID: <TENANT_ID> - resourceGroupName: eclipseCheResourceGroup - # The DNS Zone to use - hostedZoneName: azr.my-ide.cloud - email: florent@example.com - privateKeySecretRef: - name: letsencrypt - server: https://acme-v02.api.letsencrypt.org/directory -EOF ----- - -. Create the certificate and edit the domain name: -+ -[source,yaml,subs="+attributes"] ----- -cat <<EOF | {orch-cli} apply -f - -apiVersion: cert-manager.io/v1alpha2 -kind: Certificate -metadata: - name: che-tls - namespace: {prod-namespace} -spec: - secretName: che-tls - issuerRef: - name: che-certificate-issuer - kind: ClusterIssuer - dnsNames: - - '*.azr.my-ide.cloud' -EOF ----- - -. Check that the `issuerRef` name is the same as the `ClusterIssuer`. A new DNS challenge is added to the DNS zone for _Let’s Encrypt_. -+ -image::installation/new-dns-challenge-added.png[link="../_images/installation/new-dns-challenge-added.png"] -+ -The cert-manager logs contain information about the DNS challenge. - -. Obtain the logs using the following command (here, `cert-manager-8d478bb45-2924h` is the name of the cert-manager Pod): -+ -[subs="+attributes"] ----- -$ {orch-cli} logs -f -n cert-manager cert-manager-8d478bb45-2924h ----- - -. Ensure that the certificate is ready: -+ -[subs="+attributes"] ----- -$ {orch-cli} describe certificate/che-tls -n {prod-namespace} - -Status: - Conditions: - Last Transition Time: 2019-07-29T13:50:35Z - Message: Certificate issuance in progress. Temporary certificate issued. - Reason: TemporaryCertificate - Status: False - Type: Ready - -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Generated 47s cert-manager Generated new private key - Normal GenerateSelfSigned 47s cert-manager Generated temporary self signed certificate - Normal OrderCreated 47s cert-manager Created Order resource "che-tls-3529929423” ----- - -. Wait for the status to show *OK* and ensure that the log contains the following: -+ -[subs="+attributes"] ----- -$ {orch-cli} describe certificate/che-tls -n {prod-namespace} -Name: che-tls -Namespace: che -Labels: <none> -Annotations: API Version: cert-manager.io/v1alpha3 -Kind: Certificate -Metadata: - Creation Timestamp: 2020-07-29T10:32:49Z - Generation: 1 - Resource Version: 7961 - Self Link: /apis/cert-manager.io/v1alpha3/namespaces/che/certificates/che-tls - UID: 2034c6d5-bce3-4ce8-8489-df31d02b84e9 -Spec: - Dns Names: - *.azr.my-ide.cloud - Issuer Ref: - Kind: ClusterIssuer - Name: che-certificate-issuer - Secret Name: che-tls -Status: - Conditions: - Last Transition Time: 2020-07-29T10:35:05Z - Message: Certificate is up to date and has not expired - Reason: Ready - Status: True - Type: Ready - Not After: 2020-10-27T09:35:02Z -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal GeneratedKey 5m49s cert-manager Generated a new private key - Normal Requested 5m49s cert-manager Created new CertificateRequest resource "che-tls-2082883576" - Normal Issued 3m34s cert-manager Certificate issued successfully ----- diff --git a/modules/installation-guide/partials/proc_installing-che-on-docker-desktop-using-chectl.adoc b/modules/installation-guide/partials/proc_installing-che-on-docker-desktop-using-chectl.adoc deleted file mode 100644 index 8f11bc60ef..0000000000 --- a/modules/installation-guide/partials/proc_installing-che-on-docker-desktop-using-chectl.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// installing-che-on-docker-desktop - -[id="installing{prod-id-short}_on-docker-desktop-using-{prod-cli}_{context}"] -= Installing {prod-short} on Docker Desktop using {prod-cli} - -This section describes how to install {prod-short} on Docker Desktop using {prod-cli}. - -.Prerequisites - -* The `{prod-cli}` management tool is available. See xref:using-the-chectl-management-tool.adoc[]. -* Running macOS or Windows. -* An installation of Docker Desktop running {kubernetes} version `{kube-ver-min}` or higher. See link:https://www.docker.com/products/docker-desktop[Installing Docker Desktop]. - -.Procedure - -* Run the following command: -+ -[subs="+attributes"] ----- -$ {prod-cli} server:deploy --platform docker-desktop ----- diff --git a/modules/installation-guide/partials/proc_installing-che-on-kind-using-chectl.adoc b/modules/installation-guide/partials/proc_installing-che-on-kind-using-chectl.adoc deleted file mode 100644 index 517bcf39bb..0000000000 --- a/modules/installation-guide/partials/proc_installing-che-on-kind-using-chectl.adoc +++ /dev/null @@ -1,136 +0,0 @@ -// Module included in the following assemblies: -// -// running-{prod-id-short}-locally - -[id="installing-{prod-id-short}-on-kind-using-{prod-cli}_{context}"] -= Installing {prod-short} on kind using {prod-cli} - -This section describes how to install {prod-short} on https://github.com/kubernetes-sigs/kind[kind] using {prod-cli}. kind is a tool for running local {kubernetes} clusters using Docker-formatted containers as nodes. It is useful for quickly creating ephemeral clusters, and is used as part of the test infrastructure of the {kubernetes} project. Running {prod-short} in kind is a way to try the application, or for a contributor to test their change quickly with a real cluster. - -.Prerequisites - -* The `{prod-cli}` management tool is available. See xref:using-the-chectl-management-tool.adoc[]. -* A running kind cluster. See link:https://kind.sigs.k8s.io/#installation-and-usage[kind installation and usage documentation]. - -.Procedure - -For {prod-short} installation, kind cluster should have an Ingress backend and a persistent volumes storage backend. If these requirements are met, go directly to xref:installing-che-on-kind.adoc#run-{prod-cli}-on-kind[deploying {prod-short}]. - -Following instruction is a way of configuring Kind cluster to have all needed for {prod} components: - -. Install https://github.com/kubernetes-csi/csi-driver-host-path[csi-driver-host-path] in the kind cluster: -+ -Install `snapshotter` CRDs as described in the https://github.com/kubernetes-csi/csi-driver-host-path/blob/master/docs/deploy-1.17-and-later.md#user-content-volumesnapshot-crds-and-snapshot-controller-installation[docs]: -+ -[subs="+quotes"] ----- -$ SNAPSHOTTER_VERSION=v2.1.1 - -# Apply VolumeSnapshot CRDs -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml - -# Create snapshot controller -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/deploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/deploy/kubernetes/snapshot-controller/setup-snapshot-controller.yaml ----- -Value of the latest `SNAPSHOTTER_VERSION` could be found on https://github.com/kubernetes-csi/external-snapshotter/releases[corresponding release page]. -+ -Then deploy: -+ -[subs="+quotes"] ----- -$ git clone https://github.com/kubernetes-csi/csi-driver-host-path && cd csi-driver-host-path -$ ./deploy/kubernetes-__<version>__/deploy.sh -$ kubectl apply -f examples/csi-storageclass.yaml ----- -{kubernetes} version could be obtained via `kubectl version` command (see `Server Version`). - -. Set `csi-hostpath-sc` as the default `StorageClass`: -+ ----- -$ kubectl patch storageclass csi-hostpath-sc -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}' -$ kubectl patch storageclass standard -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "false"}}}' ----- - -. Install the https://kubernetes.github.io/ingress-nginx/deploy/[NGINX Ingress Controller]: -+ ----- -$ VERSION=v0.41.0 -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-${VERSION}/deploy/static/provider/aws/deploy.yaml ----- - -. Install the https://metallb.universe.tf/[MetalLB] load balancer: -+ -[subs="+quotes"] ----- -$ kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.3/manifests/namespace.yaml -$ kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.3/manifests/metallb.yaml -$ kubectl create secret generic -n metallb-system memberlist --from-literal=secretkey="$(openssl rand -base64 128)" ----- -+ -[NOTE] -==== -The above command may apply to an out-of-date version of MetalLB {kubernetes} manifests. See https://metallb.universe.tf/installation/[the installation instructions] for the most up-to-date command. -==== - -. Determine an IP range to allocate to MetalLB from the `docker` bridge network: -+ ----- -$ docker inspect bridge | grep -C 5 Subnet -"IPAM": { - "Driver": "default", - "Options": null, - "Config": [ - { - "Subnet": "172.17.0.0/16", - "Gateway": "172.17.0.1" - } - ] - }, - "Internal": false, ----- -+ -In this case, there is a `/16` subnet range to allocate. Choose a section in the `172.17.250.0` range. - -. Create a `ConfigMap` for MetalLB specifying the IP range to expose: -+ ----- -$ cat << EOF > metallb-config.yaml -apiVersion: v1 -kind: ConfigMap -metadata: - namespace: metallb-system - name: config -data: - config: | - address-pools: - - name: default - protocol: layer2 - addresses: - - 172.17.250.1-172.17.250.250 -EOF -$ kubectl apply -f metallb-config.yaml ----- - -. The external IP was added to the `ingress-nginx` service: -+ ----- -$ kubectl get svc -n ingress-nginx -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ingress-nginx LoadBalancer 10.107.194.26 172.17.250.1 80:32033/TCP,443:30428/TCP 19h ----- - -[id="run-{prod-cli}-on-kind"] -. Run `{prod-cli}`, using the external IP of the `ingress-nginx` Service as an https://nip.io[nip.io] URL: -+ -[subs="+quotes,+attributes"] ----- -$ {prod-cli} server:deploy --installer operator --platform k8s --domain 172.17.250.1.nip.io ----- -+ -[NOTE] -==== -After completing these steps, if you cannot reach {prod-short} from the host machine, see the `kind` cluster documentation or forums. Look for information about making an endpoint available outside the `kind` cluster for your system and network configuration. -==== diff --git a/modules/installation-guide/partials/proc_installing-che-on-kubernetes_using_chectl.adoc b/modules/installation-guide/partials/proc_installing-che-on-kubernetes_using_chectl.adoc deleted file mode 100644 index 157127e146..0000000000 --- a/modules/installation-guide/partials/proc_installing-che-on-kubernetes_using_chectl.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-google-cloud-platform -// installing-{prod-id-short}-on-aws -// installing-{prod-id-short}-on-microsoft-azure - -[id="installing-{prod-id-short}-on-kubernetes-using-{prod-cli}_{context}"] -= Installing {prod-short} on {kubernetes} using {prod-cli} - -Kubernetes is an open-source system for automating deployment, scaling, and managing containerized applications. The following section describes the process of deploying {prod-short} on {kubernetes} by using the `{prod-cli}` tool. - -.Prerequisites - -* The `{prod-cli}` management tool is available. See xref:using-the-chectl-management-tool.adoc[]. - -.Procedure - -. Install {prod-short} on {kubernetes}: -+ -[subs="+attributes"] ----- -$ {prod-cli} server:deploy --platform=k8s --domain={domain} -› Current Kubernetes context: 'current-context' - ✔ Verify Kubernetes API...OK - ✔ 👀 Looking for an already existing Eclipse Che instance - ✔ Verify if Eclipse Che is deployed into namespace "{prod-namespace}"...it is not - ✔ ✈️ Kubernetes preflight checklist - ✔ Verify if kubectl is installed - ✔ Verify remote kubernetes status...done. - ✔ Check Kubernetes version: Found v1.22.2. - ✔ Verify domain is set...set to {domain}. - ↓ Check if cluster accessible [skipped] - ✔ Following Eclipse Che logs - ✔ Start following Operator logs...done - ✔ Start following Eclipse Che Server logs...done - ✔ Start following PostgreSQL logs...done - ✔ Start following Keycloak logs...done - ✔ Start following Plug-in Registry logs...done - ✔ Start following Devfile Registry logs...done - ✔ Start following Eclipse Che Dashboard logs...done - ✔ Start following namespace events...done - › Warning: Consider using the more reliable 'OLM' installer when deploying a stable release of Eclipse Che (--installer=olm). - ✔ Create Namespace {prod-namespace}...[Exists] - ✔ 🏃‍ Running the Eclipse Che operator - ✔ Create ServiceAccount che-operator in namespace {prod-namespace}...done. - ✔ Read Roles and Bindings...done. - ✔ Creating Roles and Bindings...done. - ✔ Create CRD checlusters.org.eclipse.che...done. - ✔ Create backup and restore CRDs...done. - ✔ Waiting 5 seconds for the new Kubernetes resources to get flushed...done. - ✔ Create deployment che-operator in namespace {prod-namespace}...done. - ✔ Operator pod bootstrap - ✔ Scheduling...done - ✔ Downloading images...done - ✔ Starting...done - ✔ Prepare Eclipse Che cluster CR...Done. - ✔ Create the Custom Resource of type checlusters.org.eclipse.che in the namespace {prod-namespace}...done. - ✔ ✅ Post installation checklist - ✔ PostgreSQL pod bootstrap - ✔ Scheduling...done - ✔ Downloading images...done - ✔ Starting...done - ✔ Keycloak pod bootstrap - ✔ Scheduling...done - ✔ Downloading images...done - ✔ Starting...done - ✔ Devfile Registry pod bootstrap - ✔ Scheduling...done - ✔ Downloading images...done - ✔ Starting...done - ✔ Plug-in Registry pod bootstrap - ✔ Scheduling...done - ✔ Downloading images...done - ✔ Starting...done - ✔ Eclipse Che Dashboard pod bootstrap - ✔ Scheduling...done - ✔ Downloading images...done - ✔ Starting...done - ✔ Eclipse Che Server pod bootstrap - ✔ Scheduling...done - ✔ Downloading images...done - ✔ Starting...done - ✔ Eclipse Che status check...done - ✔ Retrieving Che self-signed CA certificate...OK - ✔ Prepare post installation output...done - ✔ Show important messages - ✔ {prod} {prod-ver} has been successfully deployed. - ✔ Documentation : {prod-docs-url} - ✔ ------------------------------------------------------------------------------- - ✔ Users Dashboard : https://{prod-namespace}-{prod-namespace}.{domain} - ✔ Admin user login : "XXX:XXX". NOTE: must change after first login. - ✔ ------------------------------------------------------------------------------- - ✔ Plug-in Registry : https://plugin-registry-{prod-namespace}.{domain}/v3 - ✔ Devfile Registry : https://devfile-registry-{prod-namespace}.{domain} - ✔ ------------------------------------------------------------------------------- - ✔ Identity Provider URL : https://keycloak-{prod-namespace}.{domain}/auth - ✔ Identity Provider login : "XXX:XXX". - ✔ ------------------------------------------------------------------------------- - ✔ [ACTION REQUIRED] Please add Che self-signed CA certificate into your browser: /tmp/cheCA.crt. - Documentation how to add a CA certificate into a browser: https://www.eclipse.org/che/docs/che-7/end-user-guide/importing-certificates-to-browsers/ -Command server:deploy has completed successfully in 04:25. ----- - -.Verification steps - -. Investigate the {prod-short} logs: -+ -[subs="+attributes"] ----- -$ {prod-cli} server:logs --namespace {prod-namespace} ----- - -. Verify that the certificate settings are correct. -.. Open {prod} server URL from the output of the previous command. -.. Click on the lock icon in the address bar. -.. Verify that the pop-up window displays the **Connection is secure** message. - -.Additional resources - -* xref:end-user-guide:navigating-che-using-the-dashboard.adoc[]. diff --git a/modules/installation-guide/partials/proc_installing-che-on-kubespray-using-chectl.adoc b/modules/installation-guide/partials/proc_installing-che-on-kubespray-using-chectl.adoc deleted file mode 100644 index c41edab89e..0000000000 --- a/modules/installation-guide/partials/proc_installing-che-on-kubespray-using-chectl.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-with-kubespray - -[id="installing-{prod-id-short}-on-kubespray-using-{prod-cli}_{context}"] -= Installing {prod-short} on Kubespray using {prod-cli} - -This section describes how to install {prod-short} on {kubernetes} provisioned by Kubespray. - -.Prerequisites - -* A running {kubernetes} cluster deployed using Kubespray on bare metal. See xref:using-kubespray-to-set-up-kubernetes_{context}[]. -* A load balancer is running on your cluster. See xref:configuring-the-metallb-load-balancer-on-kubernetes_{context}[] -* A storage is defined with a provisioner. See xref:installing-storage-for-kubernetes_{context}[]. -* The `{prod-cli}` management tool is available. See xref:using-the-chectl-management-tool.adoc[]. - -.Procedure - -. Deploy an Ingress controller (using Nginx, the `cloud` deployment because a load balancer is used): -+ ----- -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud/deploy.yaml ----- - -. Get the IP attributed by the load balancer: -+ ----- -$ kubectl get svc -n ingress-nginx ----- -+ -It corresponds to the `EXTERNAL-IP` of the `ingress-nginx-controller` service. Use it as `_<ip-from-load-balancer>_` in the following step. - -* Deploy {prod-short}: -+ -[subs="+attributes,quotes"] ----- -$ {prod-cli} server:deploy --platform k8s --domain _<ip-from-load-balancer>_.nip.io ----- - diff --git a/modules/installation-guide/partials/proc_installing-che-on-minishift-using-chectl.adoc b/modules/installation-guide/partials/proc_installing-che-on-minishift-using-chectl.adoc deleted file mode 100644 index 67372c4bc5..0000000000 --- a/modules/installation-guide/partials/proc_installing-che-on-minishift-using-chectl.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-minishift - -[id="installing-{prod-id-short}-on-minishift-using-{prod-cli}_{context}"] -= Installing {prod-short} on Minishift using {prod-cli} - -This section describes how to install {prod-short} on Minishift using {prod-cli}. - -.Prerequisites - -* The `{prod-cli}` management tool is available. See xref:using-the-chectl-management-tool.adoc[]. -* A running instance of Minishift. See xref:using-minishift-to-set-up-openshift-3_{context}[]. - -.Procedure - -* Run the following command: -+ -[subs="+attributes"] ----- -$ {prod-cli} server:deploy --platform minishift ----- diff --git a/modules/installation-guide/partials/proc_installing-che-on-openshift-3-using-the-operator.adoc b/modules/installation-guide/partials/proc_installing-che-on-openshift-3-using-the-operator.adoc deleted file mode 100644 index d66d85b695..0000000000 --- a/modules/installation-guide/partials/proc_installing-che-on-openshift-3-using-the-operator.adoc +++ /dev/null @@ -1,68 +0,0 @@ - - -// installing-che-on-openshift-3-using-the-operator - -[id="installing-{prod-id-short}-on-openshift-3-using-the-operator_{context}"] -= Installing {prod-short} on OpenShift 3 using the Operator - -This section describes how to install {prod-short} on OpenShift 3 with the `{prod-cli}` CLI management tool. The method of installation is using the Operator and enable TLS (HTTPS). - -Operators are a method of packaging, deploying, and managing a {platforms-name} application which also provide the following: - -* Repeatability of installation and upgrade. -* Constant health checks of every system component. -* Over-the-air (OTA) updates for OpenShift components and independent software vendor (ISV) content. -* A place to encapsulate knowledge from field engineers and spread it to all users. - -[NOTE] -==== -This approach is only supported for use with {ocp} and {osd} version 3.11, but also work for newer versions of {ocp} and {osd}, and serves as a backup installation method for situations when the installation method using OperatorHub is not available. -==== - -.Prerequisites - -* Administrator rights on a running instance of OpenShift 3.11. - -* An installation of the `oc` OpenShift 3.11 CLI management tool. See link:https://docs.openshift.com/container-platform/3.11/cli_reference/get_started_cli.html#installing-the-cli[Installing the OpenShift 3.11 CLI]. - -* An installation of the `{prod-cli}` management tool. See xref:using-the-chectl-management-tool.adoc[]. - -* To apply settings that the main {prod-cli} command-line parameters cannot set, prepare a configuration file `operator-cr-patch.yaml` that will override the default values in the `CheCluster` Custom Resource used by the Operator. See xref:configuring-the-che-installation.adoc[]. - -* Use the {prod-namespace} namespace as the default installation project. - -* Configure OpenShift to pull images from `registry.redhat.com`. See link:https://access.redhat.com/RegistryAuthentication[Red Hat Container Registry Authentication]. - -.Procedure - -. Log in to OpenShift. See link:https://docs.openshift.com/container-platform/3.11/cli_reference/get_started_cli.html#basic-setup-and-login[Basic Setup and Login]. -+ -[subs="+attributes,+quotes",options="nowrap"] ----- -$ oc login ----- - -. Run the following command to verify that the version of the `oc` OpenShift CLI management tool is 3.11: -+ -[subs="+attributes,+quotes",options="nowrap"] ----- -$ oc version -oc v3.11.0+0cbc58b ----- - -. Run the following command to create the {prod-short} instance in the default {orch-namespace} called {prod-namespace}: -+ -[subs="+quotes,+attributes",options="nowrap"] ----- -$ {prod-cli} server:deploy -p openshift ----- - -.Verification steps - -. The output of the previous command ends with: -+ ----- -Command server:deploy has completed successfully. ----- - -. Navigate to the {prod-short} cluster instance: `pass:c,a,q[{prod-url}]`. diff --git a/modules/installation-guide/partials/proc_installing-che-using-the-che-operator-in-openshift-4-web-console.adoc b/modules/installation-guide/partials/proc_installing-che-using-the-che-operator-in-openshift-4-web-console.adoc deleted file mode 100644 index 273d016fe4..0000000000 --- a/modules/installation-guide/partials/proc_installing-che-using-the-che-operator-in-openshift-4-web-console.adoc +++ /dev/null @@ -1,107 +0,0 @@ - -[id="installing-{prod-id-short}-using-the-{prod-id-short}-operator-in-openshift-4-web-console_{context}"] -= Installing {prod-short} using the {prod-short} Operator in OpenShift 4 web console - -This section describes how to install {prod-short} using the {prod-short} Operator available in OpenShift 4 web console. - -Operators are a method of packaging, deploying, and managing a {platforms-name} application which also provide the following: - -* Repeatability of installation and upgrade. - -* Constant health checks of every system component. - -* Over-the-air (OTA) updates for OpenShift components and independent software vendor (ISV) content. - -* A place to encapsulate knowledge from field engineers and spread it to all users. - - - - -.Prerequisites - -* An administrator account on a running instance of OpenShift 4. - - -.Procedure - -. Open the OpenShift web console. - -. To create the `{prod}` project, in the left panel, navigate to the *Home* -> *Projects* section. - -. Click the btn:[Create Project] button. - -. In the *Create Project* pop-up window, enter the project details and validate. -+ -* *Name*: `{prod-short}`. -* *Display Name*: `{prod}`. -* *Description*: `{prod}`. - -. To install the *{prod}* Operator, in the left panel, navigate to the *Operators* -> *OperatorHub* section. - -. In the *Filter by keyword* field, type `{prod}`. - -. Click the *{prod}* tile. - -. In the *{prod}* pop-up window, click the btn:[Install] button . - -. On the *Install Operator* screen, specify the following options: -+ -* *Installation mode*: *A specific {orch-namespace} on the cluster*. -* *Installed NaAmespace*: *Operator recommended Namespace: Project `openshift-workspaces`* - -. Click the btn:[Install] button. - -. In the *Installed Operators* screen, click the *{prod}* name. - -. In the *Operator Details* screen, in the *Details* tab, inside of the *Provided APIs* section, click the *Create Instance* link. - -. The *Create CheCluster* page contains the configuration of the overall {prod-short} instance to create. It is the `CheCluster` Custom Resource. For an installation using the default configuration, keep the default values. -To modify the configuration, see xref:installation-guide:configuring-the-che-installation.adoc[]. - -. To create the *{prod-checluster}* cluster, click the btn:[Create] button in the lower left corner of the window. - -. On the *Operator Details* screen, in the *{prod} Cluster* tab, click on the *{prod-checluster}* link. - -. To navigate to the *{prod-checluster}* instance, click the link under *{prod-short} URL*. The URL might take a few minutes to display. - -.Validation steps - -. To validate the installation of the *{prod}* Operator, in the left panel, navigate to the *Operators* -> *Installed Operators* section. - -. In the *Installed Operators* screen, click on the *{prod}* name. - -. Navigate to the *Details* tab. - -. In the *ClusterServiceVersion Details* section at the bottom of the page, wait for these messages: -+ -* *Status*: `Succeeded`. -* *Status Reason*: `install strategy completed with no errors`. - -. Navigate to the *Events* tab. - -. Wait for this message: `install strategy completed with no errors`. - -. To validate the installation of the *{prod}* instance, navigate to the *{prod2} Cluster* tab. - -. The *CheClusters* screen displays the list of *{prod}* instances and their status. - -. Click *{prod-checluster}* `CheCluster` in the table. - -. Navigate to the *Details* tab. - -. Watch the content of following fields: -+ -* *Message*: the field contains error messages, if any. The expected content is `None`. -* *{prod} URL*: displays the URL of the *{prod}* instance, once the deployment is successful. An empty field means the deployment has not succeeded. - -. Navigate to the *Resources* tab. - -. The screen displays the list of the resources assigned to the {prod-short} deployment. - -. To see more details about the state of a resource, click its name and inspect the content of the available tabs. - -.Additional resources - -* xref:end-user-guide:navigating-che-using-the-dashboard.adoc[]. -* xref:administration-guide:viewing-operator-events.adoc[]. -* xref:end-user-guide:importing-certificates-to-browsers.adoc[] diff --git a/modules/installation-guide/partials/proc_installing-dns-on-google-cloud-platform.adoc b/modules/installation-guide/partials/proc_installing-dns-on-google-cloud-platform.adoc deleted file mode 100644 index db0a3a85aa..0000000000 --- a/modules/installation-guide/partials/proc_installing-dns-on-google-cloud-platform.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// preparing-google-cloud-platform-for-installing-che - -[id="installing-dns-on-google-cloud-platform_{context}"] -= Installing DNS on Google Cloud Platform - -.Procedure - -. Using the Cloud DNS, create a zone called *eclipse-che* and, for example, a DNS name `gcp.my-ide.cloud`. Click the btn:[Create] button. -+ -image::installation/creating-dns-zone-on-gcp.png[Creating DNS zone on Google Cloud Platform,link="../_images/installation/creating-dns-zone-on-gcp.png"] -+ -The Cloud DNS zone is created. -+ -image::installation/cloud-dns-zone-on-gcp.png[Cloud DNS zone on Google Cloud Platform,link="../_images/installation/cloud-dns-zone-on-gcp.png"] - -. Click the *Registrar Setup* link in the upper right corner of the window. The name servers (NS) to be added to the registrar are displayed. -+ -image::installation/registrar-setup-gcp.png[Registrar setup on Google Cloud Platform,link="../_images/installation/registrar-setup-gcp.png"] - -. Update the DNS zone (example: `ovh` domain). -. Add the `*.gcp.my-ide.cloud` entry to the external Ingress IP on the cloud DNS. -+ -image::installation/dns-settings-gcp.png[DNS settings on Google Cloud Platform,link="../_images/installation/dns-settings-gcp.png"] diff --git a/modules/installation-guide/partials/proc_installing-ingress-on-kubernetes.adoc b/modules/installation-guide/partials/proc_installing-ingress-on-kubernetes.adoc deleted file mode 100644 index 5c13c06f57..0000000000 --- a/modules/installation-guide/partials/proc_installing-ingress-on-kubernetes.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-microsoft-azure -// preparing-google-cloud-platform-for-installing-che - -[id="installing-ingress-on-kubernetes_{context}"] -= Installing Ingress on {kubernetes} - -{prod} uses Ingress. - -.Procedure - -To install Ingress-nginx: - -. Install the cloud configuration: -+ ----- -$ kubectl apply \ - -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.41.0/deploy/static/provider/cloud/deploy.yaml ----- - -+ -The following output confirms that the Ingress controller is running: -+ ----- -$ kubectl get pods --namespace ingress-nginx -NAME READY STATUS RESTARTS AGE -nginx-ingress-controller-76c86d76c4-gswmg 1/1 Running 0 9m3s ----- -+ -Wait for the container to run. - -. Wait for the external IP. Note that a `<pending>` status for the external IP is shown before the exact external IP address is displayed. -+ ----- -$ kubectl get services --namespace ingress-nginx -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ingress-nginx LoadBalancer 10.0.97.244 40.89.129.194 80:31107/TCP,443:30629/TCP 8m59s ----- - -. Get the external IP of Ingress-nginx. -+ ----- -$ kubectl get services --namespace ingress-nginx \ - -o jsonpath='{.items[].status.loadBalancer.ingress[0].ip}' -40.89.129.194 ----- diff --git a/modules/installation-guide/partials/proc_installing-storage-for-kubernetes.adoc b/modules/installation-guide/partials/proc_installing-storage-for-kubernetes.adoc deleted file mode 100644 index 4d31d7d865..0000000000 --- a/modules/installation-guide/partials/proc_installing-storage-for-kubernetes.adoc +++ /dev/null @@ -1,117 +0,0 @@ -[id="installing-storage-for-kubernetes_{context}"] -= Installing storage for {kubernetes} - -This section describes how to enable persistent storage for {kubernetes} using NFS. - -.Procedure - -. Install the NFS server on a machine on the same network as your cluster nodes: -+ ----- -# apt-get install -y nfs-kernel-server ----- - -. Create the export directory: -+ ----- -# mkdir -p /mnt/my-nfs ----- -+ -Change its permissions: -+ ----- -# chown nobody:nogroup /mnt/my-nfs -# chmod 777 /mnt/my-nfs ----- - -. Start the NFS export: -+ -[subs="+quotes"] ----- -# echo "__<mount-path>__ __<subnet>__(rw,sync,no_subtree_check)" | tee /etc/exports -# exportfs -a -# systemctl restart nfs-kernel-server ----- -+ -NOTE: Replace `_<subnet>_` and `_<mount-path>_` with your `nfs` settings. - -. Define the `StorageClass` settings and the provisioner (using the link:https://github.com/kubernetes-incubator/external-storage[external-storage] template): -+ ----- -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes-incubator/external-storage/master/nfs-client/deploy/rbac.yaml ----- - -. Set `StorageClass`: -+ ----- -$ cat << EOF | kubectl apply -f - -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: managed-nfs-storage - annotations: - storageclass.kubernetes.io/is-default-class: "true" -provisioner: nfs-provisioner -parameters: - archiveOnDelete: "false" -EOF ----- -+ -Declare `StorageClass` as the default one to be automatically selected by PVCs. - -. Set the provisioner: -+ -[subs="+quotes"] ----- -$ cat << EOF | kubectl apply -f - -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nfs-client-provisioner - labels: - app: nfs-client-provisioner - # replace with {orch-namespace} where provisioner is deployed - namespace: default -spec: - replicas: 1 - strategy: - type: Recreate - selector: - matchLabels: - app: nfs-client-provisioner - template: - metadata: - labels: - app: nfs-client-provisioner - spec: - serviceAccountName: nfs-client-provisioner - containers: - - name: nfs-client-provisioner - image: quay.io/external_storage/nfs-client-provisioner:latest - volumeMounts: - - name: nfs-client-root - mountPath: /persistentvolumes - env: - - name: PROVISIONER_NAME - value: nfs-provisioner - - name: NFS_SERVER - value: _<nfs-server-ip>_ - - name: NFS_PATH - value: _<mount-path>_ - volumes: - - name: nfs-client-root - nfs: - server: _<nfs-server-ip>_ - path: _<mount-path>_ -EOF ----- -+ -NOTE: Replace `_<subnet>_` and `_<mount-path>_` with your `nfs` settings. - -. Verify the configuration: -+ ----- -$ kubectl get deployments.apps,pods,sc -n default ----- -+ -You should see the `Deployment` of the provisioner, the corresponding `Pod` and also the `StorageClass` as the default one. diff --git a/modules/installation-guide/partials/proc_logging-in-to-identity-provider.adoc b/modules/installation-guide/partials/proc_logging-in-to-identity-provider.adoc deleted file mode 100644 index 19491e3eab..0000000000 --- a/modules/installation-guide/partials/proc_logging-in-to-identity-provider.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="logging-in-to-identity-provider_{context}"] -= Logging in to {identity-provider} - -The following procedure describes how to log in to {identity-provider}, which acts as a route for OpenShift platforms. To log in to {identity-provider}, a user has to obtain the {identity-provider} URL and a user's credentials first. - -.Prerequisites - -* The `{orch-cli}` tool installed. -* Logged in to OpenShift cluster using the `{orch-cli}` tool. - -.Procedure - -. Obtain a user {identity-provider} login: -+ -[subs="+attributes,+quotes"] ----- -{orch-cli} get secret che-identity-secret -n {prod-namespace} -o json | jq -r '.data.user' | base64 -d ----- - -. Obtain a user {identity-provider} password: -+ -[subs="+attributes,+quotes"] ----- -{orch-cli} get secret che-identity-secret -n {prod-namespace} -o json | jq -r '.data.password' | base64 -d ----- - -. Obtain the {identity-provider} URL: -+ -[subs="+attributes,+quotes"] ----- -{orch-cli} get ingress -n {prod-namespace} -l app=che,component=keycloak -o 'custom-columns=URL:.spec.rules[0].host' --no-headers ----- - -. Open the URL in a browser and log in to {identity-provider} using the obtained login and password. diff --git a/modules/installation-guide/partials/proc_preparing-azure-for-installing-che.adoc b/modules/installation-guide/partials/proc_preparing-azure-for-installing-che.adoc deleted file mode 100644 index c12d9dfd52..0000000000 --- a/modules/installation-guide/partials/proc_preparing-azure-for-installing-che.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-microsoft-azure - -[id="preparing-azure-for-installing-che_{context}"] -= Preparing Azure for installing {prod-short} - -.Procedure - -To configure the Azure environment for {prod-short}: - -. Install the Azure command-line tool. For details, see https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest[Install the Azure CLI]. -+ -For example, on macOS: -+ ----- -$ brew update && brew install azure-cli ----- - -. Log in to Azure: -+ ----- -$ az login ----- - -. Create an Azure group (to list the locations, use the `az account list-locations` command): -+ ----- -$ az group create --name eclipseCheResourceGroup --location francecentral -{ - "id": "/subscriptions/ab0f7986-a280-481c-a47d-98fa45ff94ca/resourceGroups/eclipseCheResourceGroup", - "location": "francecentral", - "managedBy": null, - "name": "eclipseCheResourceGroup", - "properties": { - "provisioningState": "Succeeded" - }, - "tags": null, - "type": null -} ----- - -. Create the cluster: -+ ----- -$ az aks create --resource-group eclipseCheResourceGroup \ - --name eclipse-che --node-count 1 --enable-addons monitoring --generate-ssh-keys ----- - -. Configure `kubectl`: -+ ----- -$ az aks get-credentials --name eclipse-che --resource-group eclipseCheResourceGroup -Merged "eclipse-che" as current context in /Users/benoitf/.kube/config ----- - -. Check the {kubernetes} context: -+ ----- -$ kubectl config current-context -eclipse-che - -$ kubectl get pods --all-namespaces ----- -+ -All the Pods in the running state are displayed. diff --git a/modules/installation-guide/partials/proc_preparing-the-aws-system-for-installing-che.adoc b/modules/installation-guide/partials/proc_preparing-the-aws-system-for-installing-che.adoc deleted file mode 100644 index 14f971f14a..0000000000 --- a/modules/installation-guide/partials/proc_preparing-the-aws-system-for-installing-che.adoc +++ /dev/null @@ -1,523 +0,0 @@ -[id="preparing-the-aws-system-for-installing-che_{context}"] -= Preparing the AWS system for installing {prod-short} - -The following sections describe how to Configure {kubernetes} for {prod} -on Amazon Elastic Compute Cloud (Amazon EC2). - - -.Prerequisites - -* A running instance of {kubernetes}, version {kube-ver-min} or higher, and Ingress. -* The `{orch-cli}` tool installed. -* The `{prod-cli}` tool installed. - - -== Installing {kubernetes} on Amazon EC2 - -. Configure the AWS Command Line Interface (AWS CLI). For detailed installation instructions, see link:https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html[Installing the AWS CLI]. - -. Check the `PATH` environment variable if the `aws` tool is not available. - -. Install {kubernetes} on EC2. There are several ways to have a running {kubernetes} instance on EC2. Here, the `kops` tool is used to install {kubernetes}. For details, see link:https://kubernetes.io/docs/setup/production-environment/tools/kops/[Installing {kubernetes} with `kops`]. - -This document assumes that {prod} must be configured to run on following domain: `http://che.aws.my-ide.cloud`. - - -== Setting up DNS - -One way to Configure Domain Name System (DNS) is to create the Amazon Route53 to manage the `aws.my-ide.cloud` domain. - -To Configure DNS: - -. Create the zone on AWS: -+ -[subs="+quotes",options="nowrap"] ----- -$ aws route53 create-hosted-zone --name aws.my-ide.cloud --caller-reference 1 - -\{ - "Location": "https://route53.amazonaws.com/2013-04-01/hostedzone/__<ZONE-ID>__", - "HostedZone": \{ - "Id": "/hostedzone/__<ZONE-ID>__", - "Name": "aws.my-ide.cloud.", - "CallerReference": "1", - "Config": \{ - "PrivateZone": false - }, - "ResourceRecordSetCount": 2 - }, - "ChangeInfo": \{ - "Id": "/change/C1ZNLBU45DJUJL", - "Status": "PENDING", - "SubmittedAt": "2019-07-08T08:14:39.772Z" - }, - "DelegationSet": \{ - "NameServers": [ - "ns-1693.awsdns-19.co.uk", - "ns-1133.awsdns-13.org", - "ns-150.awsdns-18.com", - "ns-965.awsdns-56.net" - ] - } -} ----- - -. Configure the four DNS `nameservers` on the `my-ide.cloud` DNS. Note that when a custom DNS provider, updating the record takes a few hours. -+ -image::installation/dns-nameservers.png[DNS name servers] - -. Create the Simple Storage Service (s3) storage to store the `kops` configuration. -+ ----- -$ aws s3 mb s3://clusters.aws.my-ide.cloud -make_bucket: clusters.aws.my-ide.cloud ----- - -. Inform `kops` of this new service: -+ ----- -$ export KOPS_STATE_STORE=s3://clusters.aws.my-ide.cloud ----- - -. Create the `kops` cluster by providing the cluster zone. For example, for Europe, the zone is `eu-west-1c`. -+ ----- -$ kops create cluster --zones=eu-west-1c eu.aws.my-ide.cloud ----- - -. Create the cluster: -+ ----- -$ kops update cluster eu.aws.my-ide.cloud --yes ----- - -. After the cluster is ready, validate it: -+ -[subs="+quotes",options="nowrap"] ----- -$ kops validate cluster - -Using cluster from {orch-cli} context: eu.aws.my-ide.cloud - -Validating cluster eu.aws.my-ide.cloud - -INSTANCE GROUPS -NAME ROLE MACHINETYPE MIN MAX SUBNETS -master-eu-west-1c Master m3.medium 1 1 eu-west-1c -nodes Node t2.medium 2 2 eu-west-1c - -NODE STATUS -NAME ROLE READY -ip-172-20-38-26.eu-west-1.compute.internal node True -ip-172-20-43-198.eu-west-1.compute.internal node True -ip-172-20-60-129.eu-west-1.compute.internal master True - -Your cluster eu.aws.my-ide.cloud is ready ----- - -. Check the cluster using the `{orch-cli} ` command. The `{orch-cli} ` context is also configured automatically by the `kops` tool: -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} config current-context -eu.aws.my-ide.cloud - -$ {orch-cli} get pods --all-namespaces - -All the pods in the running state are displayed. ----- - - -== Installing Ingress-nginx - -To install Ingress-nginx: - -. Install the configuration for AWS. -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} apply \ - -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.41.0/deploy/static/provider/aws/deploy.yaml ----- -+ -The following output confirms that the Ingress controller is running. -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} get pods --namespace ingress-nginx -NAME READY STATUS RESTARTS AGE -nginx-ingress-controller-76c86d76c4-gswmg 1/1 Running 0 9m3s ----- - -. Find the external IP of ingress-nginx. -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} get services --namespace ingress-nginx -o jsonpath='{.items[].status.loadBalancer.ingress[0].hostname}' -Ade9c9f48b2cd11e9a28c0611bc28f24-1591254057.eu-west-1.elb.amazonaws.com ----- -+ -*Troubleshooting*: If the output is empty, it implies that the cluster has configuration issues. Use the following command to find the cause of the issue: -+ ----- -$ {orch-cli} describe service -n ingress-nginx ingress-nginx ----- -+ -Output similar to the following means a needed role must be created manually: -+ -[subs="+quotes",options="nowrap"] ----- -arn:aws:sts::269287474311:assumed-role...4bff is not authorized to perform: iam:CreateServiceLinkedRole on resource: arn:aws:iam::269287474311:role/aws-service-role/elasticloadbalancing.amazonaws.com/AWSServiceRoleForElasticLoadBalancing ----- -+ -Run the following command to create the role: -+ -[subs="+quotes",options="nowrap"] ----- -$ aws iam create-service-linked-role --aws-service-name "elasticloadbalancing.amazonaws.com" ----- - -. Add hosts on route 53 with this given host name `https://console.aws.amazon.com/route53/home?region=eu-west-1#hosted-zones:`. Ensure that you include the colon (`:`) at the end of this URL. -. Create the wildcard DNS `*` (for `*.aws-my-ide.cloud`) with the previous host name and ensure to add the dot (`.`) at the end of the host name. In the *Type* drop-down list, select *CNAME*. -+ -image::installation/create-record-set.png[link="../_images/installation/create-record-set.png"] -+ -The following is an example of the resulting window after adding all the values. -+ -image::installation/create-record-set-all-values.png[link="../_images/installation/create-record-set-all-values.png"] -+ -The `che.aws.my-ide.cloud` address must resolve to an IP address. -+ -[subs="+quotes",options="nowrap"] ----- -$ host che.aws.my-ide.cloud -che.aws.my-ide.cloud is an alias for ade9c9f48b2cd11e9a28c0611bc28f24-1591254057.eu-west-1.elb.amazonaws.com. -ade9c9f48b2cd11e9a28c0611bc28f24-1591254057.eu-west-1.elb.amazonaws.com has address 54.77.155.195 ----- -+ -The existing {kubernetes} instance is prepare to host an {prod-short} installation. - - -== Enabling the TLS and DNS challenge - -pass:[<!-- vale IBM.Terms = NO -->] - -To use the Cloud DNS and TLS, some service accounts must be enabled to have cert-manager managing the DNS challenge for the _Let's Encrypt_ service. - -pass:[<!-- vale IBM.Terms = YES -->] - -. Create a new `permission` file. -. Use the following command to obtain the zone ID: -+ -[subs="+quotes",options="nowrap"] ----- -$ aws route53 list-hosted-zones -{ - "HostedZones": [ - { - "Id": "/hostedzone/ABCDEFGH", - "Name": "aws.my-ide.cloud.", - "CallerReference": "1", - "Config": { - "PrivateZone": false - }, - "ResourceRecordSetCount": 5 - } - ] -} ----- - -. Copy the following content and replace `INSERT_ZONE_ID` with the route53 zone ID: -+ -[subs="+quotes",options="nowrap"] ----- -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "route53:GetChange", - "route53:ListHostedZonesByName" - ], - "Resource": [ - "*" - ] - }, - { - "Effect": "Allow", - "Action": [ - "route53:ChangeResourceRecordSets" - ], - "Resource": [ - "arn:aws:route53:::hostedzone/<INSERT_ZONE_ID>" - ] - } - ] -} ----- - -. In the *EC2 Dashboard*, identify the *IAM role* used by the master node. -+ -image::installation/aws-lauch-instance.png[start AWS instance,link="../_images/installation/aws-lauch-instance.png"] -+ -It is located under the *Description* tab, in the *IAM role* field. -+ -image::installation/describtion-tab-iam-role.png[Description tab IAM role,link="../_images/installation/describtion-tab-iam-role.png"] - -. Click the *IAM role* link (`masters.eu.aws.my-ide.cloud`, in this case). -. Click the *Add inline policy* link at the bottom of the window. -+ -image::installation/aws-summary-iam-role.png[AWS summary IAM role,link="../_images/installation/aws-summary-iam-role.png"] - -. In the *Create policy* window, on the *JSON* tab, paste the content of the JSON file created earlier and click the *Review policy* button. -+ -image::installation/aws-create-policy.png[link="../_images/installation/aws-create-policy.png"] - -. In the *Name* field, type `eclipse-che-route53` and click *Create Policy*. -+ -image::installation/create-policy-review-policy.png[link="../_images/installation/create-policy-review-policy.png"] - - -== Installing cert-manager - -. To install cert-manager, run the following commands (for details, see link:https://cert-manager.io/docs/installation/[Installing Cert on {kubernetes}]): -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} create namespace cert-manager -namespace/cert-manager created -$ {orch-cli} label namespace cert-manager certmanager.k8s.io/disable-validation=true -namespace/cert-manager labeled ----- - -. Set `validate=false`. If set to `true`, it will only work with the latest {kubernetes}: -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} apply \ - -f https://github.com/jetstack/cert-manager/releases/download/v0.15.0/cert-manager.yaml \ - --validate=false ----- - -. Create the {prod-short} {orch-namespace} if it does not already exist: -+ -[subs="+quotes,+attributes",options="nowrap"] ----- -$ {orch-cli} create namespace {prod-namespace} -namespace/{prod-namespace} created ----- - -. Create the *cert-manager* user: -+ -[subs="+quotes",options="nowrap"] ----- -$ aws iam create-user --user-name cert-manager -{ - "User": { - "Path": "/", - "UserName": "cert-manager", - "userId": "ABCDEF", - "Arn": "arn:aws:iam::1234:user/cert-manager", - "CreateDate": "2019-07-30T13:50:48Z" - } -} ----- - -. Create the access key: -+ -[subs="+quotes",options="nowrap"] ----- -$ aws iam create-access-key --user-name cert-manager -{ - "AccessKey": { - "UserName": "cert-manager", - "AccessKeyId": "ABCDEF", - "Status": "Active", - "SecretAccessKey": "mySecret", - "CreateDate": "2019-07-30T13:52:59Z" - } -} ----- -+ -IMPORTANT: Remember the access key for later use. - -. Create a secret from the `SecretAccessKey` content. -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} create secret generic aws-cert-manager-access-key \ - --from-literal=CLIENT_SECRET=<REPLACE WITH SecretAccessKey content> -n cert-manager ----- - -. Use the *Add inline policy* link to add the inline policy to link:https://console.aws.amazon.com/iam/home#/users/cert-manager[AWS Cert-Manager]. -+ -image::installation/aws-summary-iam-role.png[AWS summary IAM role,link="../_images/installation/aws-summary-iam-role.png"] - -. Paste the following inline policy in the *JSON* tab: -+ -[subs="+quotes",options="nowrap"] ----- -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "route53:GetChange", - "Resource": "arn:aws:route53:::change/\*" - }, - { - "Effect": "Allow", - "Action": "route53:ChangeResourceRecordSets", - "Resource": "arn:aws:route53:::hostedzone/*" - }, - { - "Effect": "Allow", - "Action": "route53:ListHostedZonesByName", - "Resource": "*" - } - ] -} ----- - -+ -image::installation/json-review-policy.png[link="../_images/installation/json-review-policy.png"] - -. Click *Review policy*. -+ -image::installation/create-policy-review.png[link="../_images/installation/create-policy-review.png"] - -. In the *Name* field, type `route53`, and click *Create policy*. -. To create the certificate issuer, change the email address and specify the `accessKeyID`: -+ ----- -$ cat <<EOF | {orch-cli} apply -f - -apiVersion: cert-manager.io/v1alpha2 -kind: ClusterIssuer -metadata: - name: che-certificate-issuer - namespace: cert-manager -spec: - acme: - server: https://acme-v02.api.letsencrypt.org/directory - email: your-email@example.com - privateKeySecretRef: - name: letsencrypt - solvers: - - selector: - dnsZones: - - "YOUR DOMAIN" - dns01: - route53: - region: eu-west-1 - accessKeyID: <USE ACCESS_KEY_ID_CREATED_BEFORE> - secretAccessKeySecretRef: - name: aws-cert-manager-access-key - key: CLIENT_SECRET -EOF ----- - -. Add the certificate by editing the domain name value (`aws.my-ide.cloud`, in this case) and the `dnsName` value: -+ ----- -$ cat <<EOF | {orch-cli} apply -f - -apiVersion: certmanager.k8s.io/v1alpha1 -kind: Certificate -metadata: - name: che-tls - namespace: __<{prod-namespace}>__ -spec: - secretName: che-tls - issuerRef: - name: che-certificate-issuer - kind: ClusterIssuer - dnsNames: - - '*.aws.my-ide.cloud' - acme: - config: - - dns01: - provider: route53 - domains: - - '*.aws.my-ide.cloud' -EOF ----- - -. Check if the `issuerRef` name is the same as the `ClusterIssuer`. A new DNS challenge is being added to the DNS zone for _Let’s encrypt_. -+ -image::installation/aws-hosted-zones-dns.png[AWS hosted zones DNS,link="../_images/installation/aws-hosted-zones-dns.png"] -+ -The cert-manager logs contain information about the DNS challenge. - -. Obtain the name of the Pods: -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} get pods --namespace cert-manager -NAME READY STATUS RESTARTS AGE -cert-manager-6587688cb8-wj68p 1/1 Running 0 6h -cert-manager-cainjector-76d56f7f55-zsqjp 1/1 Running 0 6h -cert-manager-webhook-7485dd47b6-88m6l 1/1 Running 0 6h ----- -+ - -. Obtain the logs using the following command (here, `cert-manager-8d478bb45-sdfmz` is the name of the cert-manager Pod): -+ -[subs="+quotes",options="nowrap"] ----- -$ {orch-cli} logs -f cert-manager-8d478bb45-sdfmz -n cert-manager -I0730 14:46:25.382385 1 sync.go:274] Need to create 0 challenges -I0730 14:46:25.382401 1 sync.go:319] Waiting for all challenges for order "che-tls-3365293372" to enter 'valid' state -I0730 14:46:25.382431 1 controller.go:204] cert-manager/controller/orders "level"=0 "msg"="finished processing work item" "key"="che/che-tls-3365293372" -I0730 14:46:25.382813 1 controller.go:219] cert-manager/controller/challenges "level"=0 "msg"="finished processing work item" "key"="che/che-tls-3365293372-0" -I0730 14:46:25.382843 1 controller.go:213] cert-manager/controller/challenges "level"=0 "msg"="syncing resource" "key"="che/che-tls-3365293372-0" -I0730 14:46:25.383037 1 dns.go:101] Presenting DNS01 challenge for domain "aws.my-ide.cloud" -I0730 14:47:03.061546 1 dns.go:112] Checking DNS propagation for "aws.my-ide.cloud" using name servers: [100.64.0.10:53] -I0730 14:47:03.220952 1 dns.go:124] Waiting DNS record TTL (60s) to allow propagation of DNS record for domain "_acme-challenge.aws.my-ide.cloud.” ----- - -. Ensure that the certificate is ready: -+ -[subs="+quotes,+attributes",options="nowrap"] ----- -$ {orch-cli} describe certificate/che-tls -n {prod-namespace} -Status: - Conditions: - Last Transition Time: 2019-07-30T14:46:23Z - Message: Certificate issuance in progress. Temporary certificate issued. - Reason: TemporaryCertificate - Status: False - Type: Ready -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal OrderCreated 50s cert-manager Created Order resource "che-tls-3365293372" ----- - -. Wait for the status to become `OK` and ensure that the log contains the following entry: -+ -[subs="+quotes",options="nowrap"] ----- -I0729 13:56:26.140886 1 conditions.go:143] Found status change for Certificate "che-tls" condition "Ready": "False" -> "True"; setting lastTransitionTime to 2019-07-29 13:56:26.140866531 +0000 UTC m=+4557.134131468 ----- - -. Ensure that the status is up-to-date using the following command: -+ -[subs="+quotes,+attributes",options="nowrap"] ----- -$ {orch-cli} describe certificate/che-tls -n {prod-namespace} - -Status: - Conditions: - Last Transition Time: 2019-07-30T14:48:07Z - Message: Certificate is up to date and has not expired - Reason: Ready - Status: True - Type: Ready - Not After: 2019-10-28T13:48:05Z -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal OrderCreated 5m29s cert-manager Created Order resource "che-tls-3365293372" - Normal OrderComplete 3m46s cert-manager Order "che-tls-3365293372" completed successfully - Normal CertIssued 3m45s cert-manager Certificate issued successfully ----- diff --git a/modules/installation-guide/partials/proc_setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc b/modules/installation-guide/partials/proc_setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc deleted file mode 100644 index 855013d69e..0000000000 --- a/modules/installation-guide/partials/proc_setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc +++ /dev/null @@ -1,38 +0,0 @@ -:parent-context-of-setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page: {context} -// Module included in the following assemblies: -// -// configuring-che - -[id="setting-up-the-{identity-provider-id}-{prod-id-short}-username-readonly-theme-for-the-{prod-id}-login-page_{context}"] -= Setting up the {identity-provider} {prod-id-short}-username-readonly theme for the {prod} login page - -:context: setting-up-the-{identity-provider-id}-{prod-id-short}-username-readonly-theme-for-the-{prod-id}-login-page - -The following procedure is relevant for all {prod-short} instances with the OpenShift OAuth service enabled. - -When a user with pre-created namespaces logs in to {prod} Dashboard for the first time, a page allowing the user to update account information is displayed. It is possible to change the username, but choosing a username that doesn't match the OpenShift username, prevents the user's workspaces from running. This is caused by {prod-short} attempts to use a non-existing namespace, the name of which is derived from a user OpenShift username, to create a workspace. To prevent this, log in to {identity-provider} and modify the theme settings. - - -include::partial$proc_logging-in-to-identity-provider.adoc[leveloffset=+1] - - -== Setting up the {identity-provider} `{prod-id-short}-username-readonly` theme - -.Prerequisites - -* An instance of {prod-short} running in OpenShift. -* A user is logged in to the {identity-provider} service. - -.Procedure - -After changing a username, set the *Login Theme* option to `readonly`. - -. In the main *Configure* menu on the left, select *Realm Settings*: -+ -image::keycloak/{project-context}-keycloak-username-readonly-theme.png[link="../_images/keycloak/{project-context}-keycloak-username-readonly-theme.png"] - -. Navigate to the *Themes* tab. - -. In the *Login Theme* field, select the `{prod-id-short}-username-readonly` option and click the btn:[Save] button to apply the changes. - -:context: {parent-context-of-setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page} diff --git a/modules/installation-guide/partials/proc_sizing-google-cloud-node-pools-for-your-eclipse-che-workspaces.adoc b/modules/installation-guide/partials/proc_sizing-google-cloud-node-pools-for-your-eclipse-che-workspaces.adoc deleted file mode 100644 index 32810beb1a..0000000000 --- a/modules/installation-guide/partials/proc_sizing-google-cloud-node-pools-for-your-eclipse-che-workspaces.adoc +++ /dev/null @@ -1,18 +0,0 @@ - - -[id="sizing-google-cloud-node-pools-for-your-eclipse-che-workspaces_{context}"] -= Sizing Google Cloud node pools for your Eclipse Che workspaces - -The default node pool is using machine types `n1-standard-1`. You may need to use different kind of machine to run your workspaces. See link:https://cloud.google.com/compute/docs/machine-types?hl=en#n1_standard_machine_types[] - -With Google Cloud Platform, you cannot change the machine type configuration of an existing node pool. - -One solution is to create a new node pool and delete the existing one afterwards. Google {kubernetes} Engine would then transfer the workloads to the new node pool automatically. - -Another solution is to have two node pools with one dedicated to the workspaces by configuring {prod} with a NodeSelector. See xref:configuring-workspaces-nodeselector.adoc[]. - -image::installation/gcp-new-nodepool.png[Google Cloud Platform new node pool,link="../_images/installation/gcp-new-nodepool.png"] - -image::installation/gcp-new-nodepool-select-machine-type-standard.png[Google Cloud Platform new node pool select machine type,link="../_images/installation/gcp-new-nodepool-select-machine-type-standard.png"] - -Preferably choose machine types according the workspaces CPU and memory requirements. diff --git a/modules/installation-guide/partials/proc_upgrading-che-and-backing-up-user-data.adoc b/modules/installation-guide/partials/proc_upgrading-che-and-backing-up-user-data.adoc deleted file mode 100644 index bac3d571cd..0000000000 --- a/modules/installation-guide/partials/proc_upgrading-che-and-backing-up-user-data.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// upgrading-{prod-id-short}-namespace-strategies-other-than-per-user - -[id="upgrading-{prod-id-short}-and-backing-up-user-data_{context}"] - -= Upgrading {prod-short} and backing up user data - -.Procedure - -. Notify all {prod-short} users about the upcoming data wipe. -+ -[NOTE] -==== -To back up the data, you can commit workspace configuration to an SCM server and use factories to restore it later. -==== -+ -. Re-install {prod-short} with `per user` namespace strategy. diff --git a/modules/installation-guide/partials/proc_upgrading-che-and-losing-user-data.adoc b/modules/installation-guide/partials/proc_upgrading-che-and-losing-user-data.adoc deleted file mode 100644 index b15b13b788..0000000000 --- a/modules/installation-guide/partials/proc_upgrading-che-and-losing-user-data.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// upgrading-{prod-id-short}-namespace-strategies-other-than-per-user - -[id="upgrading-{prod-id-short}-and-losing-user-data_{context}"] - -= Upgrading {prod-short} and losing user data - -When {prod-short} is upgraded and user data is not backed up, workspace configuration and user preferences are going to be preserved but all runtime data will be wiped out. - -.Procedure - - . Notify all {prod-short} users about the upcoming data wipe. - . Change {orch-namespace} strategy to `per user`. - -NOTE: Upgrading without backing up user data has disadvantage. Original PVs with runtime data are going to be preserved and will no longer be used. This may lead to the waste of resources. diff --git a/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc b/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc deleted file mode 100644 index a2d3d86f7e..0000000000 --- a/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// upgrading-{prod-id-short} - -[id="proc_upgrading-{prod-id-short}-using-the-cli-management-tool-in-restricted-environment_{context}"] -= Upgrading {prod-short} using the CLI management tool in restricted environment - -This section describes how to upgrade {prod} using the CLI management tool in restricted environment. - -.Prerequisites - -* An administrative account on an OpenShift instance. - -* A running instance version {prod-prev-ver} of {prod}, installed using the CLI management tool on the same instance of {platforms-name}, with the {prod-cli} `--installer operator` method, in the `_<{prod-namespace}>_` project. See xref:installing-che-in-a-restricted-environment.adoc[]. - -* Essential container images are available to the {prod-short} server running in the cluster. See xref:preparing-a-private-registry_{context}[]. - -* The `{prod-cli}` {prod-ver} management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. - -.Procedure - -. In all running workspaces in the {prod-short} {prod-prev-ver} instance, save and push changes back to the Git repositories. - -. Stop all workspaces in the {prod-short} {prod-prev-ver} instance. - -. Run the following command: -+ -[subs="+attributes,+quotes"] ----- -$ {prod-cli} server:update --che-operator-image=__<image-registry>__/__<organization>__/{prod-operator-image-name}:{prod-ver} -n {prod-namespace} ----- -+ -* _<image-registry>_: A host name and a port of the container-image registry accessible in the restricted environment. -* _<organization>_: An organization of the container-image registry. See: xref:preparing-a-private-registry_{context}[]. - -.Verification steps - -. Navigate to the {prod-short} instance. - -. The {prod-ver} version number is visible at the bottom of the page. - -[NOTE] -==== -For slow systems or internet connections, add the `--k8spodwaittimeout=1800000` flag option to the `{prod-cli} server:update` command to extend the Pod timeout period to 1800000 ms or longer. -==== - diff --git a/modules/installation-guide/partials/proc_using-kubespray-to-set-up-kubernetes.adoc b/modules/installation-guide/partials/proc_using-kubespray-to-set-up-kubernetes.adoc deleted file mode 100644 index a7b452f9f6..0000000000 --- a/modules/installation-guide/partials/proc_using-kubespray-to-set-up-kubernetes.adoc +++ /dev/null @@ -1,225 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-with-kubespray - -[id="using-kubespray-to-set-up-kubernetes_{context}"] -= Configuring {kubernetes} using Kubespray - -Commands are given for bash on Ubuntu. - -.System update - -Start with a system update before installing new packages. - ----- -$ sudo apt-get update -$ sudo apt-get upgrade ----- - -NOTE: This step is only required on the machine used to run Kubespray. Kubespray will handle system updates on the cluster nodes. - -.SSH access - -* Install SSH server -+ -If a node does not have SSH server installed by default, you have to install it to remotely control this machine. -+ ----- -$ sudo apt-get install openssh-server ----- - -* Create SSH key pair -+ -You have to generate one or multiple SSH key pair(s) to allow the Kubespray or Ansible automatic login using SSH. You can use a different key pair for each node or use the same for all nodes. -+ ----- -$ ssh-keygen -b 2048 -t rsa -f /home/<local-user>/.ssh/id_rsa -q -N "" ----- - -* Copy your public key(s) on nodes -+ -Copy your public key(s) in the `~/.ssh/authorized_keys` file of the user accounts you will use on each node for deployment. -You will be prompted twice for the password corresponding to account, the first time for the public key upload using SSH and the second time for adding the public key in the authorized_keys file. -+ ----- -for ip in <node1-ip> <node2-ip> ...; do - scp /home/<local-user>/.ssh/id_rsa.pub <node-user>@$ip:/home/<node-user>/.ssh - ssh <node-user>@$ip "cat ~/.ssh/id_rsa.pub > ~/.ssh/authorized_keys" -done ----- -+ -You will never be prompted again for password using SSH, the key will be used to authenticate you! - -.IPv4 forwarding - -Kubespray requires to turn on IPv4 forwarding. This should be done automatically by Kubespray. - -To do it manually, run the following command: - ----- -for ip in <node1-ip> <node2-ip> ...; do - ssh <node-user>@$ip "echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward" -done ----- - -.Turn off swap - -Turning swap off is required by {orch-name}. See this issue for more information. - ----- -for ip in <node1-ip> <node2-ip> ...; do - ssh <node-user>@$ip "sudo swapoff -a && sudo sed -i '/ swap / s/^/#/' /etc/fstab" -done ----- - -.Get Kubespray - -Start by installing curl. - ----- -sudo apt-get install curl ----- - -Get the latest Kubespray source code from its code repository. - -WARNING: The latest release when writing this tutorial, v2.12.5, throws error not encountered in the master version. - ----- -mkdir -p ~/projects/ && \ -curl -LJO https://github.com/kubernetes-sigs/kubespray/archive/master.zip && \ -unzip kubespray-master.zip -d kubespray && \ -rm kubespray-master.zip && \ -cd kubespray ----- - -.Install Kubespray requirements - -Kubespray uses Python 3 and several dependencies to be installed. - -* Install Python 3 -+ -Install Python 3 but also `pip` (package installer for Python) and `venv` to create virtual environments (see below). -+ ----- -sudo apt-get install python3.7 python3-pip python3-venv ----- - -* Create a virtual environment -+ -This is a best isolation practice using Python to use virtual environments (or `conda` environments for `conda` users). -+ ----- -python3 -m venv ~/projects/kubespray-venv -source ~/projects/kubespray-venv/bin/activate ----- - -* Install Kubespray dependencies -+ ----- -pip install -r requirements.txt ----- - -.Create a new cluster configuration - -Start creating a copy of the default settings from sample cluster. - ----- -cp -rfp inventory/sample inventory/mycluster ----- - -Be sure you are still in the `~/projects/kubespray/` directory before executing this command! - -Then customize your new cluster - -. Update Ansible inventory file with inventory builder -+ ----- -declare -a IPS=(<node1-ip> <node2-ip> ...) -CONFIG_FILE=inventory/mycluster/hosts.yaml python contrib/inventory_builder/inventory.py ${IPS[@]} ----- - -. (optional) Rename your nodes or deactivate host name renaming -+ -If you skip this step, your cluster host names will be renamed node1, node2, and so on. -+ -You can either edit the file `~/projects/kubespray/inventory/mycluster/hosts.yaml` -+ ----- -sed -e 's/node1/tower/g' -e 's/node2/laptop/g' ... -i inventory/mycluster/hosts.yaml ----- -+ -OR -+ -keep the current host names -+ ----- -echo "override_system_hostname: false" >> inventory/mycluster/group_vars/all/all.yml ----- - -. Check localhost vs nodes usernames -+ -If your localhost username differ from a node username (the one that owns your SSH public key), you must specify it to Ansible by editing (manually) the hosts.yaml file. -+ -Example: -+ -[width="50%",cols="^.^,^.^",options="header"] -,=== -localhost username, node1 username -foo, bar -,=== -+ ----- -> cat inventory/mycluster/hosts.yaml -all: - hosts: - node1: - ansible_ssh_user: bar ----- - -.Deploy your cluster! - -It's time to deploy {kubernetes} by running the Ansible playbook command. - ----- -ansible-playbook -i inventory/mycluster/hosts.yaml --become --become-user=root cluster.yml ----- - -.Access your cluster API - -The cluster is created but you currently have no access to its API for configuration purpose. -`{orch-cli} ` has been installed by Kubespray on master nodes of your cluster and configuration files are saved in root home directories of master nodes. - -When you are about to access the cluster API from another computer on your network, install {orch-cli} first. - ----- -curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl -chmod +x ./kubectl -sudo mv ./kubectl /usr/local/bin/kubectl ----- - -. Copy the configuration files from the root home directory of a master node: - -.. On the master node, copy configurations files from root to your user account: -+ ----- -$ ssh <node-user>@<master-node-ip> "sudo cp -R /root/.kube ~ && sudo chown -R <node-user>:<node-user> ~/.kube" ----- - -. Download the configuration files to a remote computer: -+ ----- -$ scp -r <node-user>@<master-node-ip>:~/.kube ~ -$ sudo chown -R <local-user>:<local-user> ~/.kube ----- - -. Keep secrets protected on the master node: -+ ----- -$ ssh <node-user>@<master-node-ip> "rm -r ~/.kube" ----- -+ -Use autocompletion for the sake of sanity: -+ ----- -$ echo 'source <(kubectl completion bash)' >>~/.bashrc ----- diff --git a/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc b/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc deleted file mode 100644 index 3eb812aa18..0000000000 --- a/modules/installation-guide/partials/proc_using-minishift-to-set-up-openshift-3.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-minishift - -[id="using-minishift-to-set-up-openshift-3_{context}"] -= Using Minishift to configure OpenShift 3 - -This section describes how to use Minishift to configure OpenShift 3. - -.Prerequisites - -* The `minishift` tool is available, with version `1.34.1` or greater. See link:https://docs.okd.io/3.11/minishift/getting-started/installing.html[Installing Minishift]. -* The `oc` tool is available. See link:https://docs.okd.io/3.11/minishift/command-ref/minishift_oc-env.html[Setting the path of the `oc` tool]. - -.Procedure - -* Start Minishift with at least 4 GB of RAM: -+ ----- -$ minishift start --memory=4096 ----- diff --git a/modules/overview/nav.adoc b/modules/overview/nav.adoc index 2aa7ab5dae..ed2b812313 100644 --- a/modules/overview/nav.adoc +++ b/modules/overview/nav.adoc @@ -1,2 +1 @@ * xref:introduction-to-eclipse-che.adoc[] -** xref:architecture-overview.adoc[] diff --git a/modules/overview/pages/architecture-overview.adoc b/modules/overview/pages/architecture-overview.adoc deleted file mode 100644 index aed9d3ad22..0000000000 --- a/modules/overview/pages/architecture-overview.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="{prod-id-short}-architecture"] -// = {prod-short} architectural elements -:navtitle: Architecture overview -:keywords: overview, che-architecture, che-architectural-elements -:page-aliases: che-architecture - -include::administration-guide:partial$con_architecture-overview.adoc[] diff --git a/modules/overview/pages/introduction-to-eclipse-che.adoc b/modules/overview/pages/introduction-to-eclipse-che.adoc index 30537f708d..1d59cb5ad5 100644 --- a/modules/overview/pages/introduction-to-eclipse-che.adoc +++ b/modules/overview/pages/introduction-to-eclipse-che.adoc @@ -2,6 +2,6 @@ // = Introduction to {prod-short} :navtitle: Introduction to {prod-short} :keywords: overview, introduction-to-eclipse-che -:page-aliases: .:introduction-to-eclipse-che .:known-issues +:page-aliases: .:introduction-to-eclipse-che, .:known-issues include::partial$assembly_introduction-to-eclipse-che.adoc[] diff --git a/modules/overview/partials/assembly_introduction-to-eclipse-che.adoc b/modules/overview/partials/assembly_introduction-to-eclipse-che.adoc index ec4c453ad6..22a31bd478 100644 --- a/modules/overview/partials/assembly_introduction-to-eclipse-che.adoc +++ b/modules/overview/partials/assembly_introduction-to-eclipse-che.adoc @@ -20,10 +20,10 @@ == Getting started with {prod-short} * xref:what-is-{prod-id-short}_{context}[] -* xref:che-architecture.adoc[] -* xref:hosted-che.adoc[] -* xref:installation-guide:running-che-locally.adoc[] -* xref:installation-guide:supported-platforms.adoc[] +* xref:architecture-overview.adoc[] +* xref:hosted-che:hosted-che.adoc[] +* xref:administration-guide:installing-che-locally.adoc[] +* xref:administration-guide:supported-platforms.adoc[] * xref:administration-guide:calculating-che-resource-requirements.adoc[] @@ -48,7 +48,7 @@ Visit StackOverflow to help other users of {prod}: link:https://stackoverflow.co Community blog:: -Learn about the latest of {prod} and submit your blog posts to the link:https://che.eclipse.org[{prod} blog]. +Learn about the latest of {prod} and submit your blog posts to the link:https://che.eclipseprojects.io[{prod} blog]. Weekly meetings:: @@ -63,7 +63,7 @@ See the development link:https://github.com/eclipse/che/wiki/Roadmap[roadmap] on {prod} is a {kubernetes}-native IDE and developer collaboration platform. -As an open-source project, the core goals of {prod} are to: +As an open source project, the core goals of {prod} are to: * *Accelerate project and developer onboarding:* As a zero-install development environment that runs in your browser, {prod} makes it easy for anyone to join your team and contribute to a project. * **Remove inconsistency between developer environments:** No more: “But it works on my machine.” Your code works exactly the same way in everyone’s environment. @@ -111,7 +111,7 @@ video::B6aCqywKpyY[youtube] + video::VooNzKxRFgw[youtube] -For situations in which the default IDE does not cover the use cases of the users or to use a dedicated tool rather than an IDE. +For situations where the default IDE does not cover the use cases of the users or to use a dedicated tool rather than an IDE. === Extensible platform @@ -125,7 +125,7 @@ For situations in which the default IDE does not cover the use cases of the user * *Alternative IDEs* to provide specialized tools within {prod}. Build your own, based on Eclipse Theia, or pick existing ones such as Jupyter. * *Marketplace (soon)* to easily distribute tools and custom IDEs, which can be tried online, to users and communities. -{prod} uses Che-Theia as its default browser-based IDE. Che-Theia provides a framework to build web IDEs. It is built in TypeScript and gives contributors a programming model that is flexible, relies on state-of-the-art tools protocols, and makes it faster to build new tools. +{prod} uses Che-Theia as its default browser-based IDE. Che-Theia provides a framework to build web IDEs. It is built-in TypeScript and gives contributors a programming model that is flexible, relies on state-of-the-art tools protocols, and makes it faster to build new tools. In {prod}, the dependencies needed for the tools running in the user's workspace are available when needed. This means that a Che-Theia plug-in provides its dependencies, its back-end services (which could be running in a sidecar container connected to the user’s workspace), and the IDE UI extension. {prod-short} packages all these elements together, so that the user does not have to configure different tools together. diff --git a/supplemental-ui/.htaccess b/supplemental-ui/.htaccess deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/supplemental-ui/_headers b/supplemental-ui/_headers deleted file mode 100644 index 22edcb7da3..0000000000 --- a/supplemental-ui/_headers +++ /dev/null @@ -1,3 +0,0 @@ -# We could switch to /_/* and use an indefinite age if we append a cache buster to all asset URLs -/_/font/* - Cache-Control: public,max-age=604800 diff --git a/supplemental-ui/css/search.css b/supplemental-ui/css/search.css new file mode 100644 index 0000000000..bc341849bc --- /dev/null +++ b/supplemental-ui/css/search.css @@ -0,0 +1,76 @@ +.search-result-dropdown-menu { + position: absolute; + z-index: 100; + display: block; + right: 0; + left: inherit; + top: 100%; + border-radius: 4px; + margin: 6px 0 0; + padding: 0; + text-align: left; + height: auto; + background: transparent; + border: none; + max-width: 600px; + min-width: 500px; + box-shadow: 0 1px 0 0 rgba(0, 0, 0, 0.2), 0 2px 3px 0 rgba(0, 0, 0, 0.1); + } + + @media screen and (max-width: 768px) { + .search-result-dropdown-menu { + min-width: calc(100vw - 3.75rem); + } + } + + .search-result-dataset { + position: relative; + border: 1px solid #d9d9d9; + background: #fff; + border-radius: 4px; + overflow: auto; + padding: 0 8px; + max-height: calc(100vh - 5.25rem); + line-height: 1.5; + } + + .search-result-item { + display: flex; + margin: 0.5rem 0; + } + + .search-result-document-title { + width: 33%; + border-right: 1px solid #ddd; + color: #02060c; + font-weight: 500; + font-size: 0.8rem; + padding: 0.5rem 0.5rem 0.5rem 0; + text-align: right; + position: relative; + word-wrap: break-word; + } + + .search-result-document-hit { + flex: 1; + font-size: 0.75rem; + color: #63676d; + } + + .search-result-document-hit > a { + color: inherit; + display: block; + padding: 0.55rem 0.25rem 0.55rem 0.75rem; + } + + .search-result-document-hit > a:hover { + background-color: rgba(69, 142, 225, 0.05); + } + + .search-result-highlight { + color: #174d8c; + background: rgba(143, 187, 237, 0.1); + padding: 0.1em 0.05em; + font-weight: 500; + } + \ No newline at end of file diff --git a/supplemental-ui/favicon.ico b/supplemental-ui/img/favicon.ico similarity index 100% rename from supplemental-ui/favicon.ico rename to supplemental-ui/img/favicon.ico diff --git a/supplemental-ui/js/search-ui.js b/supplemental-ui/js/search-ui.js new file mode 100644 index 0000000000..144ddf7b49 --- /dev/null +++ b/supplemental-ui/js/search-ui.js @@ -0,0 +1,229 @@ +; (function (globalScope) { + /* eslint-disable no-var */ + var config = document.getElementById('search-ui-script').dataset + var snippetLength = parseInt(config.snippetLength || 100, 10) + var siteRootPath = config.siteRootPath || '' + appendStylesheet(config.stylesheet) + var searchInput = document.getElementById('search-input') + var searchResult = document.createElement('div') + searchResult.classList.add('search-result-dropdown-menu') + searchInput.parentNode.appendChild(searchResult) + + function appendStylesheet(href) { + if (!href) return + document.head.appendChild(Object.assign(document.createElement('link'), { rel: 'stylesheet', href: href })) + } + + function highlightText(doc, position) { + var hits = [] + var start = position[0] + var length = position[1] + + var text = doc.text + var highlightSpan = document.createElement('span') + highlightSpan.classList.add('search-result-highlight') + highlightSpan.innerText = text.substr(start, length) + + var end = start + length + var textEnd = text.length - 1 + var contextAfter = end + snippetLength > textEnd ? textEnd : end + snippetLength + var contextBefore = start - snippetLength < 0 ? 0 : start - snippetLength + if (start === 0 && end === textEnd) { + hits.push(highlightSpan) + } else if (start === 0) { + hits.push(highlightSpan) + hits.push(document.createTextNode(text.substr(end, contextAfter))) + } else if (end === textEnd) { + hits.push(document.createTextNode(text.substr(0, start))) + hits.push(highlightSpan) + } else { + hits.push(document.createTextNode('...' + text.substr(contextBefore, start - contextBefore))) + hits.push(highlightSpan) + hits.push(document.createTextNode(text.substr(end, contextAfter - end) + '...')) + } + return hits + } + + function highlightTitle(hash, doc, position) { + var hits = [] + var start = position[0] + var length = position[1] + + var highlightSpan = document.createElement('span') + highlightSpan.classList.add('search-result-highlight') + var title + if (hash) { + title = doc.titles.filter(function (item) { + return item.id === hash + })[0].text + } else { + title = doc.title + } + highlightSpan.innerText = title.substr(start, length) + + var end = start + length + var titleEnd = title.length - 1 + if (start === 0 && end === titleEnd) { + hits.push(highlightSpan) + } else if (start === 0) { + hits.push(highlightSpan) + hits.push(document.createTextNode(title.substr(length, titleEnd))) + } else if (end === titleEnd) { + hits.push(document.createTextNode(title.substr(0, start))) + hits.push(highlightSpan) + } else { + hits.push(document.createTextNode(title.substr(0, start))) + hits.push(highlightSpan) + hits.push(document.createTextNode(title.substr(end, titleEnd))) + } + return hits + } + + function highlightHit(metadata, hash, doc) { + var hits = [] + for (var token in metadata) { + var fields = metadata[token] + for (var field in fields) { + var positions = fields[field] + if (positions.position) { + var position = positions.position[0] // only higlight the first match + if (field === 'title') { + hits = highlightTitle(hash, doc, position) + } else if (field === 'text') { + hits = highlightText(doc, position) + } + } + } + } + return hits + } + + function createSearchResult(result, store, searchResultDataset) { + result.forEach(function (item) { + var url = item.ref + var hash + if (url.includes('#')) { + hash = url.substring(url.indexOf('#') + 1) + url = url.replace('#' + hash, '') + } + var doc = store[url] + var metadata = item.matchData.metadata + var hits = highlightHit(metadata, hash, doc) + searchResultDataset.appendChild(createSearchResultItem(doc, item, hits)) + }) + } + + function createSearchResultItem(doc, item, hits) { + var documentTitle = document.createElement('div') + documentTitle.classList.add('search-result-document-title') + documentTitle.innerText = doc.title + var documentHit = document.createElement('div') + documentHit.classList.add('search-result-document-hit') + var documentHitLink = document.createElement('a') + documentHitLink.href = siteRootPath + item.ref + documentHit.appendChild(documentHitLink) + hits.forEach(function (hit) { + documentHitLink.appendChild(hit) + }) + var searchResultItem = document.createElement('div') + searchResultItem.classList.add('search-result-item') + searchResultItem.appendChild(documentTitle) + searchResultItem.appendChild(documentHit) + searchResultItem.addEventListener('mousedown', function (e) { + e.preventDefault() + }) + return searchResultItem + } + + function createNoResult(text) { + var searchResultItem = document.createElement('div') + searchResultItem.classList.add('search-result-item') + var documentHit = document.createElement('div') + documentHit.classList.add('search-result-document-hit') + var message = document.createElement('strong') + message.innerText = 'No results found for query "' + text + '"' + documentHit.appendChild(message) + searchResultItem.appendChild(documentHit) + return searchResultItem + } + + function clearSearchResults(reset) { + if (reset === true) searchInput.value = '' + searchResult.innerHTML = '' + } + + function search(index, text) { + // execute an exact match search + var result = index.search(text) + if (result.length > 0) { + return result + } + // no result, use a begins with search + result = index.search(text + '*') + if (result.length > 0) { + return result + } + // no result, use a contains search + result = index.search('*' + text + '*') + return result + } + + function searchIndex(index, store, text) { + clearSearchResults(false) + if (text.trim() === '') { + return + } + var result = search(index, text) + var searchResultDataset = document.createElement('div') + searchResultDataset.classList.add('search-result-dataset') + searchResult.appendChild(searchResultDataset) + if (result.length > 0) { + createSearchResult(result, store, searchResultDataset) + } else { + searchResultDataset.appendChild(createNoResult(text)) + } + } + + function confineEvent(e) { + e.stopPropagation() + } + + function debounce(func, wait, immediate) { + var timeout + return function () { + var context = this + var args = arguments + var later = function () { + timeout = null + if (!immediate) func.apply(context, args) + } + var callNow = immediate && !timeout + clearTimeout(timeout) + timeout = setTimeout(later, wait) + if (callNow) func.apply(context, args) + } + } + + function initSearch(lunr, data) { + var index = Object.assign({ index: lunr.Index.load(data.index), store: data.store }) + var debug = 'URLSearchParams' in globalScope && new URLSearchParams(globalScope.location.search).has('lunr-debug') + searchInput.addEventListener( + 'keydown', + debounce(function (e) { + if (e.key === 'Escape' || e.key === 'Esc') return clearSearchResults(true) + try { + var query = searchInput.value + if (!query) return clearSearchResults() + searchIndex(index.index, index.store, searchInput.value) + } catch (err) { + if (debug) console.debug('Invalid search query: ' + query + ' (' + err.message + ')') + } + }, 100) + ) + searchInput.addEventListener('click', confineEvent) + searchResult.addEventListener('click', confineEvent) + document.documentElement.addEventListener('click', clearSearchResults) + } + + globalScope.initSearch = initSearch +})(typeof globalThis !== 'undefined' ? globalThis : window) diff --git a/supplemental-ui/partials/footer-content.hbs b/supplemental-ui/partials/footer-content.hbs index 24e44eba9e..8d58ab28e2 100644 --- a/supplemental-ui/partials/footer-content.hbs +++ b/supplemental-ui/partials/footer-content.hbs @@ -5,23 +5,3 @@ <a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">Eclipse Public License</a> | <a href="https://www.eclipse.org/legal" target="_blank">Legal Resources</a></div> </footer> - -{{#if env.ALGOLIA_API_KEY}} -<script src="{{uiRootPath}}/js/vendor/docsearch.min.js"></script> -<!-- fetched from https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js --> -<script> -var search = docsearch({ - {{#with env.ALGOLIA_APP_ID}} - appId: '{{this}}', - {{/with}} - apiKey: '{{env.ALGOLIA_API_KEY}}', - indexName: '{{env.ALGOLIA_IDX_NAME}}', - inputSelector: '#search-input', - autocompleteOptions: { hint: false, keyboardShortcuts: ['s'] }, - algoliaOptions: { hitsPerPage: 10 } -}).autocomplete -search.on('autocomplete:closed', function () { search.autocomplete.setVal() }) -function focusSearchInput () { document.querySelector('#search-input').focus() } -if (document.querySelector('.home-link.is-current')) window.addEventListener('load', focusSearchInput) -</script> -{{/if}} diff --git a/supplemental-ui/partials/head-meta.hbs b/supplemental-ui/partials/head-meta.hbs index 06340da7dd..48547c4475 100644 --- a/supplemental-ui/partials/head-meta.hbs +++ b/supplemental-ui/partials/head-meta.hbs @@ -1,3 +1,4 @@ <link rel="stylesheet" href="{{uiRootPath}}/css/extra.css"> <link rel="stylesheet" href="{{uiRootPath}}/font-awesome-4.7.0/css/font-awesome.min.css"> -<link rel="icon" href="{{siteRootPath}}/favicon.ico" type="image/x-icon"> +<link rel="icon" href="{{uiRootPath}}/img/favicon.ico" type="image/x-icon"> +<script>var uiRootPath = '{{uiRootPath}}'</script> diff --git a/supplemental-ui/partials/header-content.hbs b/supplemental-ui/partials/header-content.hbs index f9a4791e2e..639d14518a 100644 --- a/supplemental-ui/partials/header-content.hbs +++ b/supplemental-ui/partials/header-content.hbs @@ -1,4 +1,4 @@ -<header class="header" role="banner"> +<header class="header"> <nav class="navbar"> <div class="navbar-brand"> <div class="navbar-item"> @@ -14,14 +14,15 @@ <div id="topbar-nav" class="navbar-menu"> <div class="navbar-end"> <div class="navbar-item hide-for-print"> - <script async src="https://cse.google.com/cse.js?cx=002898025167115630151:gnr5edrg2eo"></script> - <div class="gcse-searchbox" enableAutoComplete="true"></div> + <div id="search-field" class="field"> + <input id="search-input" type="text" placeholder="Search the docs" autofocus> + </div> </div> <a class="navbar-item" href="https://www.eclipse.org/che/">Home</a> - <a class="navbar-item" href="https://che.eclipse.org/">Blog</a> + <a class="navbar-item" href="https://che.eclipseprojects.io/">Blog</a> <a class="navbar-item" href="https://github.com/eclipse/che">Source Code</a> </div> </div> </nav> - <div class="gcse-searchresults"></div> -</header> \ No newline at end of file + </header> + \ No newline at end of file diff --git a/supplemental-ui/ui.yml b/supplemental-ui/ui.yml index 5d1df0f579..705b9c4a0d 100644 --- a/supplemental-ui/ui.yml +++ b/supplemental-ui/ui.yml @@ -1,4 +1,2 @@ static_files: - - _headers - - favicon.ico - .nojekyll diff --git a/tools/antora-to-plain-asciidoc.sh b/tools/antora-to-plain-asciidoc.sh new file mode 100755 index 0000000000..5db646af8f --- /dev/null +++ b/tools/antora-to-plain-asciidoc.sh @@ -0,0 +1,87 @@ +#!/usr/bin/env bash +# +# Copyright (c) 2022 Red Hat, Inc. +# This program and the accompanying materials are made +# available under the terms of the Eclipse Public License 2.0 +# which is available at https://www.eclipse.org/legal/epl-2.0/ +# +# SPDX-License-Identifier: EPL-2.0 +# + +# Exit on any error +set -e + +# Variables for the project +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" + +# Variables for SOURCE +SOURCE_SRC="${SCRIPT_DIR%tools*}modules" +SOURCE_GUIDES="administration-guide end-user-guide" + +# Variables for DESTINATION +DESTINATION_ROOT_DIR="${SCRIPT_DIR%tools*}build/plain-asciidoc" +DESTINATION_TEMPLATES_DIR="${DESTINATION_ROOT_DIR}/templates" + +mkdir -p "$DESTINATION_TEMPLATES_DIR" + +for GUIDE in ${SOURCE_GUIDES} +do + # Generate title, copy topics, examples and images. + SOURCE_GUIDE="${SOURCE_SRC}/${GUIDE}" + DESTINATION_DIR="${DESTINATION_ROOT_DIR}/${GUIDE}" + DESTINATION_TITLE="${DESTINATION_DIR}/index.adoc" + DESTINATION_TOPICS_DIR="${DESTINATION_DIR}/topics" + DESTINATION_EXAMPLES_DIR="${DESTINATION_TOPICS_DIR}/examples" + DESTINATION_IMAGES_DIR="${DESTINATION_DIR}/images" + mkdir -p "${DESTINATION_TOPICS_DIR}" "${DESTINATION_EXAMPLES_DIR}" "${DESTINATION_IMAGES_DIR}" + + # Generate title.adoc from Antora navigation file" + # Convert xref into include, and list depth into leveloffset + sed -E "\ + s@xref:@include::topics/@; + s@\*\*\*\*\* (.*)\]@\1leveloffset=+5]@; + s@\*\*\*\* (.*)\]@\1leveloffset=+4]@; + s@\*\*\* (.*)\]@\1leveloffset=+3]@; + s@\*\* (.*)\]@\1leveloffset=+2]@; + s@\* (.*)\]@\1leveloffset=+1]@; + " "${SOURCE_GUIDE}/nav.adoc" > "${DESTINATION_TITLE}" + + # Copy topics, examples, and images + # Remove old topics, but keep examples and images as they may mix content + find "${DESTINATION_TOPICS_DIR}" -maxdepth 1 -name '*.adoc' -exec rm {} + + # shellcheck disable=SC2086 + cp ${VERBOSE} -t "${DESTINATION_TOPICS_DIR}" "${SOURCE_GUIDE}/pages/"* "${SOURCE_GUIDE}/partials/"* + # shellcheck disable=SC2086 + cp ${VERBOSE} -f -r -t "${DESTINATION_EXAMPLES_DIR}" "${SOURCE_GUIDE}/examples/"* + # shellcheck disable=SC2086 + cp -R ${VERBOSE} -t "${DESTINATION_IMAGES_DIR}/" "${SOURCE_GUIDE}/images/"* +done + +# Prepare convert xref to file name into xref to id +FILE_TO_ID_MAP=$(grep -ire '\[id="' "${DESTINATION_ROOT_DIR}"/*/topics/) +FILE_TO_ID=$(echo "$FILE_TO_ID_MAP" | sed -E 's@.?*/(.?*adoc).?*"(.?*)"\]@s#xref:\1#xref:\2#g;@') +FILE_TO_ID_CROSS=$(echo "$FILE_TO_ID_MAP" | sed -E 's@.?*/(.?*adoc).?*"(.?*)"\]@s#xref:(.?*):\1#link:{\\1-url}\2#g;@') + +# Convert partial$ and example$ statements +SUBSTITUTIONS="s@partial\\\$@@g; +s@example\\\$@examples/@g; +${FILE_TO_ID} +${FILE_TO_ID_CROSS} +" + +# Convert include statements using `partial$` and `example$`` in plain AsciiDoc include statements +shopt -s globstar nullglob +for file in "${DESTINATION_ROOT_DIR}"/**/*.adoc +do + # Substitutions + sed -E -i "${SUBSTITUTIONS}" "$file" +done + +# Validate asciidoctor build +for GUIDE in ${SOURCE_GUIDES} +do + asciidoctor -a project-context=che -a context=che "${DESTINATION_ROOT_DIR}/${GUIDE}/index.adoc" +done + +# Validate xref and links +vale --config="${SCRIPT_DIR%tools*}.vale/styles/PlainAsciiDoc/.vale.ini" "${DESTINATION_ROOT_DIR}/" diff --git a/tools/build-for-publication.sh b/tools/build-for-publication.sh deleted file mode 100755 index a949d80143..0000000000 --- a/tools/build-for-publication.sh +++ /dev/null @@ -1,19 +0,0 @@ -#!/usr/bin/env sh -# -# Copyright (c) 2021 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# - -# Fail on errors and display commands -set -ex - -# Fetch all branches (on Jenkins) -git config --add remote.origin.fetch +refs/heads/*:refs/remotes/origin/* -git fetch - -CI=true antora generate antora-playbook-for-publication.yml --stacktrace -htmltest --skip-external diff --git a/tools/checluster_docs_gen.sh b/tools/checluster_docs_gen.sh index d7f1fd8ec4..f6735041a8 100755 --- a/tools/checluster_docs_gen.sh +++ b/tools/checluster_docs_gen.sh @@ -19,26 +19,26 @@ TABLE_HEADER="$NEWLINE[cols=\"2,5\", options=\"header\"]$NEWLINE:=== $NEWLINE Pr TABLE_FOOTER=":=== $NEWLINEx2" PARENT_PATH=$(cd "$(dirname "${BASH_SOURCE[0]}")/.."; pwd -P) BUFF="" -OUTPUT_PATH="$PARENT_PATH/modules/installation-guide/examples/checluster-properties.adoc" +OUTPUT_PATH="$PARENT_PATH/modules/administration-guide/examples/checluster-properties.adoc" fetch_current_version() { - echo "Trying to read current product version from $PARENT_PATH/antora.yml..." >&2 + # echo "Trying to read current product version from $PARENT_PATH/antora.yml..." >&2 # remove spaces, single and double quotes from the value of prod-ver, then append x. CURRENT_VERSION=$(yq -M '.asciidoc.attributes."prod-ver"' "$PARENT_PATH/antora.yml" | tr -d " '\"" ).x - if [[ "$CURRENT_VERSION" == *-SNAPSHOT ]]; then - CURRENT_VERSION="master" + if [[ "$CURRENT_VERSION" == 'main.x' ]]; then + CURRENT_VERSION="main" fi echo "Detected version: $CURRENT_VERSION" >&2 } fetch_product_name() { - echo "Trying to read product name from $PARENT_PATH/antora.yml..." >&2 + # echo "Trying to read product name from $PARENT_PATH/antora.yml..." >&2 PRODUCT=$(yq -rM '.asciidoc.attributes."prod-id-short"' "$PARENT_PATH/antora.yml") echo "Detected product: $PRODUCT" >&2 } fetch_conf_files_content() { - echo "Fetching property files content from GitHub..." >&2 + # echo "Fetching property files content from GitHub..." >&2 if [[ $PRODUCT == "che" ]]; then CHECLUSTER_PROPERTIES_URL="https://raw.githubusercontent.com/eclipse-che/che-operator/$CURRENT_VERSION/config/crd/bases/org_v1_che_crd.yaml" @@ -75,7 +75,7 @@ parse_section() { local id="[id=\"checluster-custom-resource-$sectionName-settings_{context}\"]" local caption=$2 local crdVersion=$(echo "$RAW_CONTENT" | yq -r '.apiVersion') - echo "Parsing section: "$sectionName + # echo "Parsing section: "$sectionName if [[ $sectionName == "status" ]]; then if [[ $crdVersion == "apiextensions.k8s.io/v1beta1" ]]; then diff --git a/tools/detect-unused-content.sh b/tools/detect-unused-content.sh new file mode 100755 index 0000000000..726cff31f0 --- /dev/null +++ b/tools/detect-unused-content.sh @@ -0,0 +1,128 @@ +#!/bin/bash +# +# Copyright (c) 2021 Red Hat, Inc. +# This program and the accompanying materials are made +# available under the terms of the Eclipse Public License 2.0 +# which is available at https://www.eclipse.org/legal/epl-2.0/ +# +# SPDX-License-Identifier: EPL-2.0 +# + +# Exit on any error +set -e + +# This is a configuration parameters that can be che or crwctl +PROJECT_CONTEXT=${PROJECT_CONTEXT:-che} + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" +DOCS_PROJECT_PATH=$SCRIPT_DIR/.. + +# we need to move it to make find print relative paths +pushd "$DOCS_PROJECT_PATH/modules" > /dev/null +readarray -d '' modules < <(find . -mindepth 1 -maxdepth 1 -type d -print0) + +unused_images="" +for module in "${modules[@]}" +do + pushd "$module" > /dev/null + relative_dir="modules${module#.}" + + if [ ! -d "./images" ]; then + # This module does not have images" + popd > /dev/null + continue + fi + + readarray -d '' images < <(find "images" -type f -not -name .placeholder -print0) + for image in "${images[@]}" + do + #`../` instead of `images/` is used in the documentation references + image=${image#"images/"} + image_with_che_context="${image/che/{project-context\}}" + image_with_crw_context="${image/${PROJECT_CONTEXT}/{project-context\}}" + if ! grep -q -r "$image" . && ! grep -q -r "$image_with_che_context" . && ! grep -q -r "$image_with_crw_context" . ; then + unused_images="$unused_images - $relative_dir/$image\n" + fi + done + + popd > /dev/null +done + +unused_pages="" +for module in "${modules[@]}" +do + pushd "$module" > /dev/null + relative_dir="modules${module#.}" + + if [ ! -d "./pages" ]; then + # This module does not have pages" + popd > /dev/null + continue + fi + + readarray -d '' pages < <(find "pages" -name '*.adoc' -print0) + for page in "${pages[@]}" + do + page=${page#pages/} + if ! grep -q "$page" nav.adoc ; then + unused_pages="$unused_pages - $relative_dir/$page\n" + fi + done + + popd > /dev/null +done + +unused_partials="" +for module in "${modules[@]}" +do + pushd "$module" > /dev/null + relative_dir="modules${module#.}" + + if [ ! -d "./partials" ]; then + # This module does not have partials" + popd > /dev/null + continue + fi + + readarray -d '' partials < <(find "partials" -name '*.adoc' -print0) + for partial in "${partials[@]}" + do + #`../` instead of `partials/` is used in the documentation references + partial=${partial#"partials/"} + partial_with_che_context="${partial/che/{project-context\}}" + partial_with_crw_context="${partial/${PROJECT_CONTEXT}/{project-context\}}" + if ! grep -q -r "$partial" . && ! grep -q -r "$partial_with_che_context" . && ! grep -q -r "$partial_with_crw_context" . ; then + unused_partials="$unused_partials - $relative_dir/$partial\n" + fi + done + + popd > /dev/null +done + +popd > /dev/null + +if [[ "$unused_images" ]]; then + echo "ERROR: The following images are not used in their modules. Remove the files or reference them in the content." + echo -e "${unused_images}" + exit_status=1 +else + echo "INFO: All images have reference in the modules." +fi + +if [[ "$unused_pages" ]]; then + echo "ERROR: The following pages are not used in the navigation. Remove the files or reference them in the nav.adoc file." + echo -e "${unused_pages}" + exit_status=1 +else + echo "INFO: All pages have reference in the navigation." +fi + +if [[ "$unused_partials" ]]; then + echo "ERROR: The following partials are not used in their module. Remove the files or include them in a page." + echo -e "${unused_partials}" + exit_status=1 +else + echo "INFO: All partials have reference in the modules." +fi + +exit $exit_status diff --git a/tools/detect-unused-images.sh b/tools/detect-unused-images.sh deleted file mode 100755 index e550e5e91e..0000000000 --- a/tools/detect-unused-images.sh +++ /dev/null @@ -1,59 +0,0 @@ -#!/bin/bash -# -# Copyright (c) 2021 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# - -# Exit on any error -set -e - -# This is a configuration parameters that can be che or crwctl -PROJECT_CONTEXT=${PROJECT_CONTEXT:-che} - -SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" -DOCS_PROJECT_PATH=$SCRIPT_DIR/.. - -# we need to move it to make find print relative paths -pushd "$DOCS_PROJECT_PATH/modules" > /dev/null -readarray -d '' modules < <(find . -mindepth 1 -maxdepth 1 -type d -print0) - -unused_images="" -for module in "${modules[@]}" -do - pushd "$module" > /dev/null - - if [ ! -d "./images" ]; then - # This module does not images" - popd > /dev/null - continue - fi - - readarray -d '' images < <(find "images" -name '*.png' -print0) - for image in "${images[@]}" - do - #`../` instead of `images/` is used in the documentation references - image=${image#"images/"} - image_with_che_context="${image/che/{project-context\}}" - image_with_crw_context="${image/${PROJECT_CONTEXT}/{project-context\}}" - if ! grep -q -r "$image" . && ! grep -q -r "$image_with_che_context" . && ! grep -q -r "$image_with_crw_context" . ; then - unused_images="$unused_images\n$image" - fi - done - - popd > /dev/null -done - -popd > /dev/null - -if [[ "$unused_images" ]]; then - echo "!!! The following images are not used in their modules." - echo "!!! Remove them to fix the issue." - echo -e "${unused_images}" - exit 1 -else - echo "All images have references in their the modules." -fi diff --git a/tools/environment_docs_gen.sh b/tools/environment_docs_gen.sh index 760158ad8e..2a84c21bc1 100755 --- a/tools/environment_docs_gen.sh +++ b/tools/environment_docs_gen.sh @@ -17,25 +17,25 @@ NEWLINEx2="$NEWLINE$NEWLINE" # TABLE_FOOTER=",=== $NEWLINEx2" PARENT_PATH=$( cd "$(dirname "${BASH_SOURCE[0]}")/.." ; pwd -P ) BUFF="" -OUTPUT_PATH="$PARENT_PATH/modules/installation-guide/examples/system-variables.adoc" +OUTPUT_PATH="$PARENT_PATH/modules/administration-guide/examples/system-variables.adoc" fetch_current_version() { - echo "Trying to read current product version from $PARENT_PATH/antora.yml..." >&2 + # echo "Trying to read current product version from $PARENT_PATH/antora.yml..." >&2 # remove spaces, single and double quotes from the value of prod-ver, then append .x CURRENT_VERSION=$(grep 'prod-ver:' "$PARENT_PATH/antora.yml" | cut -d: -f2 | tr -d " '\"").x if [ $? -ne 0 ]; then echo "Failure: Cannot read version from $PARENT_PATH/antora.yml" >&2 exit 1 fi - if [[ "$CURRENT_VERSION" == *-SNAPSHOT ]]; then - CURRENT_VERSION="master" + if [[ "$CURRENT_VERSION" == 'main.x' ]]; then + CURRENT_VERSION="main" fi echo "Detected version: $CURRENT_VERSION" >&2 } fetch_conf_files_content() { - echo "Fetching property files content from GitHub..." >&2 + # echo "Fetching property files content from GitHub..." >&2 CHE_PROPERTIES_URL="https://raw.githubusercontent.com/eclipse-che/che-server/$CURRENT_VERSION/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che/che.properties" RAW_CONTENT=$(curl -sf "$CHE_PROPERTIES_URL") if [ $? -ne 0 ]; then @@ -48,7 +48,7 @@ fetch_conf_files_content() { echo "Failure: Cannot read multiuser.properties from URL $MULTIUSER_PROPERTIES_URL" >&2 exit 1 fi - echo "Fetching content done. Trying to parse it." >&2 + # echo "Fetching content done. Trying to parse it." >&2 } parse_content() { @@ -65,7 +65,7 @@ parse_content() { # replace spaces with dashes, create topic ID, convert to lowercase chars # remove non alpha-num, wrap in AsciiDoc ID markup TOPICID=${TOPICID,,} - echo " Found begin of topic: $TOPIC" >&2 + # echo " Found begin of topic: $TOPIC" >&2 BUFF="${BUFF}${NEWLINE}${TOPICID}${NEWLINE}= ${TOPIC}${NEWLINEx2}" # new topic and table header elif [[ $LINE == '#'* ]] && [[ -n $TOPIC ]]; then # line starting with single # means property description (can be multiline) TRIM_LINE=${LINE/\#} # read description, stripping first # diff --git a/tools/get_vale_styles.sh b/tools/get_vale_styles.sh new file mode 100755 index 0000000000..62f20229b8 --- /dev/null +++ b/tools/get_vale_styles.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env sh +# +# Copyright (c) 2021 Red Hat, Inc. +# This program and the accompanying materials are made +# available under the terms of the Eclipse Public License 2.0 +# which is available at https://www.eclipse.org/legal/epl-2.0/ +# +# SPDX-License-Identifier: EPL-2.0 +# + +# Fail on errors +set -e + +# Get fresh Vale styles +cd .vale/styles || exit +rm -rf RedHat CheDocs +wget -qO- https://github.com/redhat-documentation/vale-at-red-hat/releases/latest/download/RedHat.zip | unzip -q - +wget -qO- https://github.com/eclipse-che/che-docs-vale-style/releases/latest/download/CheDocs.zip | unzip -q - diff --git a/tools/newtopic.sh b/tools/newtopic.sh index 5bd0e298e8..d94388762c 100755 --- a/tools/newtopic.sh +++ b/tools/newtopic.sh @@ -10,7 +10,7 @@ echo 'Choose the target guide:' PS3='Please select the target guide: ' -options=("administration-guide" "contributor-guide" "end-user-guide" "extensions" "installation-guide" "overview") +options=("administration-guide" "contributor-guide" "end-user-guide" "extensions" "overview") select guide in "${options[@]}" do case $guide in @@ -30,10 +30,6 @@ do echo "you chose choice $REPLY which is $guide" break ;; - "installation-guide") - echo "you chose choice $REPLY which is $guide" - break - ;; "overview") echo "you chose choice $REPLY which is $guide" break diff --git a/tools/podmanlinkchecker.sh b/tools/podmanlinkchecker.sh deleted file mode 120000 index ca6c740ddb..0000000000 --- a/tools/podmanlinkchecker.sh +++ /dev/null @@ -1 +0,0 @@ -runnerhtmltest.sh \ No newline at end of file diff --git a/tools/podmanpreview.sh b/tools/podmanpreview.sh deleted file mode 120000 index bd316ce328..0000000000 --- a/tools/podmanpreview.sh +++ /dev/null @@ -1 +0,0 @@ -runnerpreview.sh \ No newline at end of file diff --git a/tools/preview.sh b/tools/preview.sh index 22c4f8442e..85717c51d4 100755 --- a/tools/preview.sh +++ b/tools/preview.sh @@ -11,4 +11,6 @@ # Fail on errors and display commands set -ex +./tools/get_vale_styles.sh + LIVERELOAD=true gulp diff --git a/tools/push-to-eclipse-repository.sh b/tools/push-to-eclipse-repository.sh deleted file mode 100755 index 25048a0d47..0000000000 --- a/tools/push-to-eclipse-repository.sh +++ /dev/null @@ -1,37 +0,0 @@ -#!/usr/bin/env sh -# -# Copyright (c) 2021 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# - -# Fail on errors and display commands -set -ex - -PROJECT_NAME="${PROJECT_NAME:-che}" -PROJECT_BOT_NAME="${PROJECT_BOT_NAME:-CHE Bot}" - -GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no" -export GIT_SSH_COMMAND -git clone "ssh://genie.${PROJECT_NAME}@git.eclipse.org:29418/www.eclipse.org/${PROJECT_NAME}.git" . -git checkout master -ls -ltr -rm -rf docs/ -mkdir -p docs -cp -Rvf ../che-docs/build/site/* docs/ -git add -A -if ! git diff --cached --exit-code; then - echo "Changes have been detected, publishing to repo 'www.eclipse.org/${PROJECT_NAME}'" - git config --global user.email "${PROJECT_NAME}-bot@eclipse.org" - git config --global user.name "${PROJECT_BOT_NAME}" - DOC_COMMIT_MSG=$(git log --oneline --format=%B -n 1 HEAD | tail -1) - export DOC_COMMIT_MSG - git commit -s -m "[docs] ${DOC_COMMIT_MSG}" - git log --graph --abbrev-commit --date=relative -n 5 - git push origin HEAD:master -else - echo "No change have been detected since last build, nothing to publish" -fi diff --git a/tools/runner.sh b/tools/runner.sh deleted file mode 100755 index 98d55c39b9..0000000000 --- a/tools/runner.sh +++ /dev/null @@ -1,20 +0,0 @@ -#!/usr/bin/env sh -# -# Copyright (c) 2021 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# - -# Detect available runner for containers - -if command -v podman > /dev/null - then RUNNER=podman -elif command -v docker > /dev/null - then RUNNER=docker -else echo "No installation of podman or docker found in the PATH" ; exit 1 -fi - -export RUNNER diff --git a/tools/runnerhtmltest.sh b/tools/runnerhtmltest.sh deleted file mode 100755 index 8c000494ac..0000000000 --- a/tools/runnerhtmltest.sh +++ /dev/null @@ -1,22 +0,0 @@ -#!/usr/bin/env sh -# -# Copyright (c) 2021 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# - -# Detect available runner -. tools/runner.sh - -# Fail on errors and display commands -set -ex - -# Run htmltest in a container -${RUNNER} run --rm -ti \ - --name che-docs-htmltest \ - -v "$PWD:/htmltest:z" -w /htmltest \ - --entrypoint="htmltest" \ - "${CHE_DOCS_IMAGE:-quay.io/eclipse/che-docs}" diff --git a/tools/runnerpreview.sh b/tools/runnerpreview.sh index 47b5df94fa..c98b6c0087 100755 --- a/tools/runnerpreview.sh +++ b/tools/runnerpreview.sh @@ -9,10 +9,21 @@ # # Detect available runner -. tools/runner.sh +if command -v podman > /dev/null + then RUNNER=podman +elif command -v docker > /dev/null + then RUNNER=docker +else echo "No installation of podman or docker found in the PATH" ; exit 1 +fi -# Fail on errors and display commands -set -ex +# Fail on errors +set -e + +# Pull the image unless using a container defined in environment variable +[ -z ${CHE_DOCS_IMAGE} ] && ${RUNNER} pull quay.io/eclipse/che-docs + +# Display commands +set -x ${RUNNER} run --rm -ti \ --name che-docs \ diff --git a/tools/runnerpublication.sh b/tools/runnerpublication.sh deleted file mode 100755 index 433f737eb2..0000000000 --- a/tools/runnerpublication.sh +++ /dev/null @@ -1,24 +0,0 @@ -#!/usr/bin/env sh -# -# Copyright (c) 2021 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# - -# Detect available runner -. tools/runner.sh - -# Fail on errors and display commands -set -ex - -# Setting same memory limit as in JenkinsFile - -${RUNNER} run --rm -ti --memory 512m \ - --name che-docs \ - -v "$PWD:/projects:z" -w /projects \ - --entrypoint="./tools/publication.sh" \ - -p 4000:4000 -p 35729:35729 \ - "${CHE_DOCS_IMAGE:-quay.io/eclipse/che-docs}" diff --git a/tools/substitutions.sed b/tools/substitutions.sed deleted file mode 100755 index 5715433295..0000000000 --- a/tools/substitutions.sed +++ /dev/null @@ -1,79 +0,0 @@ -#!/bin/sed -i -f - -# Replace long and short project name by an attribute -s/Eclipse Che\b/{prod}/g -s/\bChe\b/{prod-short}/g - -# Put back hardcoded project name in Jekyll headers which doesn't understand attributes -# Run twice: we may have 2 occurences in a title -s/\(\(title:\|tags:\)\(.*\?\)\){prod-short}/\1Che/ -s/\(\(title:\|tags:\)\(.*\?\)\){prod-short}/\1Che/ -s/\(\(title:\|tags:\)\(.*\?\)\){prod}/\1Eclipse Che/ -s/\(\(title:\|tags:\)\(.*\?\)\){prod}/\1Eclipse Che/ - -# Replace project id by an attribute -# Run twice: we may have 2 occurences in the same id -s/\(\(\[id=\|xref\|<<\).*\)\bche\b/\1{prod-id-short}/g -s/\(\(\[id=\|xref\|<<\).*\)\bche\b/\1{prod-id-short}/g - -# Replace version numbers -s/\({prod-id-short}-\|{prod-short} \|{prod} \)6/\1{prod-prev-ver}/g -s/\({prod-id-short}-\|{prod-short} \|{prod} \)7/\1{prod-ver}/g - -# Revert back attributes in include statements -/^include::/ s/{prod-id-short}/che/g - -# Revert back baseurl in xref to hardcoded values -s/{site-baseurl}{prod-id-short}-{prod-ver}/{site-baseurl}che-7/g - -# Revert back Che-Theia -s/{prod-short}-Theia/Che-Theia/g -s/{prod-id-short}-theia/che-theia/g - -# Revert back Hosted Che -s/Hosted {prod-short}/Hosted Che/g -s/hosted-{prod-id-short}/hosted-che/g -s/{prod} hosted by Red Hat/Eclipse Che hosted by Red Hat/ - -# Revert back {prod-short} plug-ins types: `type: Che Plugin` `Che Editor` -s/{prod-short} Plugin/Che Plugin/g -s/\*Che Plugins\* panel/*{prod-short} Plugins* panel/g -s/Che Plugin metadata/{prod-short} plug-in metadata/g -s/Che Plugin registry/{prod-short} plug-in registry/g -#s/metadata of Che Plugin/metadata of {prod-short} plug-in/g -s/{prod-short} Editor/Che Editor/g - -# Replace version numbers -s/\({prod-id-short}-\|{prod-short} \|{prod} \)6/\1{prod-prev-ver}/g -s/\({prod-id-short}-\|{prod-short} \|{prod} \)7/\1{prod-ver}/g - -# Replace with care chectl by prod-cli attribute. -s/\bchectl\b/{prod-cli}/g -s/\bchectl_/{prod-cli}_/g -# Revert chectl in file names -s/\(include::.*\?\){prod-cli}/\1chectl/g -# Revert chectl in attributes names -s/\(:parent.*\?\){prod-cli}/\1chectl/g -s/\(:parent.*\?\){prod-cli}/\1chectl/g -s/\({parent[^}]*\){prod-cli}/\1chectl/g -# Revert chectl in jekyll headers -s/\(title:[^\[]*\){prod-cli}/\1chectl/g -s/\(permalink:[^\[]*\){prod-cli}/\1chectl/g - -s/config map/ConfigMap/g -s/custom resource/Custom Resource/g -s/the operator/the Operator/ -s/the {prod-short} operator/the {prod-short} Operator/ - -s/ namespace / {orch-namespace} /g -s/ namespace\./ {orch-namespace}./g -s/ namespace,/ {orch-namespace},/g -s/ namespaces/ {orch-namespace}s/g -s/oc create {orch-namespace}/oc create namespace/g -s/oc label {orch-namespace}/oc label namespace/g -s/kubectl create {orch-namespace}/kubectl create namespace/g -s/kubectl label {orch-namespace}/kubectl label namespace/g -s/\(API.*\?\){orch-namespace}/\1namespace/g -s/{orch-namespace}\(.*\?API\)/namespace\1/g -s/\(theia.*\?\){orch-namespace}/\1namespace/g -s/\(^title:.*\?\){orch-namespace}/\1namespace/g diff --git a/tools/substitutions.sh b/tools/substitutions.sh deleted file mode 100755 index 2e7f558af6..0000000000 --- a/tools/substitutions.sh +++ /dev/null @@ -1,19 +0,0 @@ -#!/usr/bin/env bash -# -# Copyright (c) 2021 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# - -# Exit on any error -set -e - -# Variables for the project -TOOLSDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" -ROOTDIR="${TOOLSDIR%tools*}" - -find ${ROOTDIR}/modules/*/{partials,examples} -name '*.adoc' -exec \ - sed -i -f "${TOOLSDIR}/substitutions.sed" {} + diff --git a/tools/test-adoc.sh b/tools/test-adoc.sh deleted file mode 100755 index 2fdc8afd33..0000000000 --- a/tools/test-adoc.sh +++ /dev/null @@ -1,918 +0,0 @@ -#!/bin/bash - -# test-adoc.sh - test an AsciiDoc file and report possible issues -# Copyright (C) 2013, 2014, 2019 Jaromir Hradilek <jhradilek@gmail.com> - -# This program is free software: you can redistribute it and/or modify it -# under the terms of the GNU General Public License as published by the -# Free Software Foundation, version 3 of the License. -# -# This program is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTA- -# BILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public -# License for more details. -# -# You should have received a copy of the GNU General Public License along -# with this program. If not, see <http://www.gnu.org/licenses/>. - -set -o errexit -set -o nounset -set -o pipefail - -# ------------------------------------------------------------------------- -# GLOBAL VARIABLES -# ------------------------------------------------------------------------- - -# General information about the script: -declare -r NAME=${0##*/} -declare -r VERSION='0.0.1' - -# Counters for tested items: -declare -i ISSUES=0 -declare -i NOTES=0 -declare -i CHECKED=0 -declare -i FILES=0 - -# Command line options: -declare -i OPT_VERBOSITY=0 -declare -i OPT_INCLUDES=0 -declare -i OPT_LINKS=0 - - -# ------------------------------------------------------------------------- -# GENERIC FUNCTIONS REQUIRED FOR TESTING OF ASCIIDOC MODULES -# ------------------------------------------------------------------------- - -# Prints an error message to standard error output and terminates the -# script with a selected exit status. -# -# Usage: exit_with_error ERROR_MESSAGE [EXIT_STATUS] -function exit_with_error { - local -r error_message=${1:-'An unexpected error has occurred.'} - local -r exit_status=${2:-1} - - # Print the supplied message to standard error output: - echo -e "$NAME: $error_message" >&2 - - # Terminate the script with the selected exit status: - exit $exit_status -} - -# Prints a warning message to standard error output. -# -# Usage: warn WARNING_MESSAGE -function warn { - local -r warning_message="$1" - - # Print the supplied message to standard error output: - echo -e "$NAME: $warning_message" >&2 -} - -# Formats a test result message result and prints it to standard output. -# -# Usage: print_test_result STATUS EXPLANATION -function print_test_result { - local -ru status="$1" - local -r explanation="$2" - - # Format the message and print it to standard output: - printf " %-9s %s\n" "[ $status ]" "$explanation" -} - -# Records a test as passed and prints a related message to standard output. -# -# Usage: pass EXPLANATION -function pass { - local -r explanation="$1" - - # Update the counter: - (( CHECKED++ )) - - # Report a successfully passed test: - [[ "$OPT_VERBOSITY" -gt 0 ]] && print_test_result " ok " "$explanation" -} - -# Records a test as failed and prints a related message to standard output. -# -# Usage: fail EXPLANATION -function fail { - local -r explanation="$1" - - # Update the counters: - (( CHECKED++ )) - (( ISSUES++ )) - - # Report a failed test: - print_test_result "fail" "$explanation" -} - -# Records a test as passed but prints a message to standard output to -# report a possible problem. -# -# Usage: note EXPLANATION -function note { - local -r explanation="$1" - - # Update the counters: - (( CHECKED++ )) - (( NOTES++)) - - # Report a possible problem: - print_test_result "note" "$explanation" -} - -# Deduces the documentat type from the file name and prints the result to -# standard output. If the document type cannot be determined, prints -# 'unknown'. -# -# Usage: detect_type FILE -function detect_type { - local -r filename="${1##*/}" - - # Analyze the file name: - case "$filename" in - con_*) echo 'concept';; - ref_*) echo 'reference';; - proc_*) echo 'procedure';; - assembly_*) echo 'assembly';; - master.adoc) echo 'master';; - local-attributes.adoc|attributes.adoc) echo 'attributes';; - master-docinfo.xml|docinfo.xml) echo 'docinfo';; - *) echo 'unknown';; - esac -} - -# Reads an AsciiDoc file, removes unwanted content such as comments from -# it, and prints the result to standard output. -# -# Usage: print_adoc FILE -function print_adoc { - local -r filename="$1" - - # Remove both single-line and multiline comments from the supplied file: - perl -0pe 's{^////\s*\n.*?^////\s*\n}{}msg;s{^//.*\n}{}gm;' "$filename" -} - -# Reads an AsciiDoc file and prints a list of all included files to -# standard output. -# -# Usage: print_includes FILE -function print_includes { - local -r filename="$1" - - # Parse the AsciiDoc file, get a complete list of included files, and - # print their full paths to standard output: - ruby <<-EOF 2>/dev/null -#!/usr/bin/env ruby - -require 'asciidoctor' - -document = Asciidoctor.load_file("$filename", doctype: :book, safe: :safe) -document.reader.includes.each { |filename| - dirname = File.dirname("$filename") - fullpath = File.join(dirname, "#{filename}.adoc") - puts File.realpath(fullpath) -} -EOF - - # Verify that the AsciiDoc file could be processed and print a warning - # if it could not: - [[ "$?" -eq 0 ]] || warn "$filename: Unable to list included files" -} - -# Processes the supplied AsciiDoc file and reports problems to standard -# output. -# -# Usage: print_report FILE -function print_report { - local -r filename="$1" - - # Verify that the supplied file exists and is readable: - [[ -e "$file" ]] || exit_with_error "$file: No such file or directory" 2 - [[ -r "$file" ]] || exit_with_error "$file: Permission denied" 13 - [[ -f "$file" ]] || exit_with_error "$file: Not a file" 21 - - # Determine the document type: - local -r type=$(detect_type "$filename") - - # Verify that the supplied file is either an AsciiDoc file, or a docinfo - # file: - [[ "${file##*.}" == 'adoc' ]] || [[ "$type" == 'docinfo' ]] || \ - exit_with_error "$file: Not an AsciiDoc file" 22 - - # Get the full path for the tested file: - local -r fullpath=$(realpath "$filename") - - # Print the header: - echo -e "\nTesting file: $fullpath\n" - echo -e " Document type: $type\n" - - # Run test cases depending on the detected document type. If the document - # type could not be determined, treat the file just like a module or - # assembly: - if [[ "$type" == 'docinfo' ]]; then - # Run test cases for docinfo XML files: - test_docinfo_abstract "$filename" - test_docinfo_name "$filename" - elif [[ "$type" == 'attributes' ]]; then - # Run test cases for attribute definition files: - test_attributes_location "$filename" - test_internal_definition "$filename" - test_replaced_projects "$filename" - elif [[ "$type" == 'master' ]]; then - # Run test cases for master.adoc: - test_context_definition "$filename" - test_internal_definition "$filename" - test_rhel_in_headings "$filename" - test_replaced_projects "$filename" - test_extarnal_links "$filename" - test_old_title_links "$filename" - test_old_rhel_links "$filename" - test_preview_links "$filename" - else - # Run test cases for modules and assemblies: - test_internal_definition "$filename" - test_module_prefix "$filename" - test_steps_in_proc "$filename" - test_steps_in_con "$filename" - test_steps_in_ref "$filename" - test_context_in_ids "$filename" - test_rhel_in_headings "$filename" - test_replaced_projects "$filename" - test_extarnal_links "$filename" - test_old_title_links "$filename" - test_old_rhel_links "$filename" - test_preview_links "$filename" - test_leveloffsets "$filename" - test_module_headings "$filename" - fi - - # Update the counter: - (( FILES++ )) -} - -# Prints the summary of the test results to standard output. -# -# Usage: print_summary -function print_summary { - # Print the summary: - echo -e "\nChecked $CHECKED item(s) in $FILES file(s), found $ISSUES problem(s)." -} - - -# ------------------------------------------------------------------------- -# TEST CASES AND FUNCTIONS RELATED TO THEM -# ------------------------------------------------------------------------- - -# Parses the AsciiDoc file and prints all IDs to standard output. -# -# Usage: list_ids FILE -function list_ids { - local -r filename="$1" - - # Parse IDs: - print_adoc "$filename" | sed -ne "s/^\[id=['\"]\(.*\)['\"]\].*/\1/p" -} - -# Parses the AsciiDoc file and prints all headings to standard output. -# -# Usage: list_headings FILE -function list_headings { - local -r filename="$1" - - # Parse headings: - print_adoc "$filename" | sed -ne "s/^=\+ \+\(.*\)$/\1/p" -} - -# Parses the AsciiDoc file and prints all external links to standard -# output. -# -# Usage: list_links FILE -function list_links { - local -r filename="$1" - - # Convert the AsciiDoc file to DocBook 4.5 and store the output in a - # variable: - local -r docbook=$(asciidoctor -S secure -b docbook45 -o - "$filename" 2>/dev/null) - - # Verify that the AsciiDoc file could be converted and print a warning - # if it could not: - if [[ "$?" -gt 0 ]]; then - warn "$filename: Unable to convert to DocBook 4.5" - return 1 - fi - - # Parse the DocBook 4.5 output and print all external links to standard - # output: - echo "$docbook" | \ - xmlstarlet sel -t -v '//ulink/@url' 2>/dev/null | \ - grep -e '^https\?://' | \ - sort -u | sed '/^$/d' -} - -# Determines whether an external link is functional. If the target URL is -# not accessible, the function prints the broken link to standard output. -# -# Usage: print_broken URL -function print_broken { - local -r url="$1" - - # Verify whether the supplied link is accessible: - curl -A 'Mozilla/5.0 (X11; Fedora; Linux x86_64; rv:65.0) Gecko/20100101 Firefox/65.0' \ - --connect-timeout 5 --retry 3 \ - -4ILfks "$url" &>/dev/null \ - || echo "$url" -} - -# Parses the AsciiDoc file and determines whether it contains any steps. -# -# Usage: has_steps FILE -function has_steps { - local -r filename=$1 - - # Parse steps: - print_adoc "$filename" | grep -qP '^\.+\s+\S+' -} - -# Verifies that the docinfo XML file includes a <para> within <abstract>. -# -# Usage: test_docinfo_abstract FILE -function test_docinfo_abstract { - local -r filename="$1" - - # Read the content of the <para> tag inside of <abstract>: - local -r abstract=$(sed -e '1s/^/<x>\n/;$ s/$/\n<\/x>/' "$filename" | xmlstarlet sel -t -v '/x/abstract/para' 2>/dev/null) - - # Check whether the content is a non-empty string and report the result: - if [[ ! -z "$abstract" ]]; then - pass "The abstract includes the <para> tag." - else - fail "The abstract does not include the <para> tag." - fi -} - -# Verify that the docinfo XML file is named docinfo.xml. -# -# Usage: test_docinfo_name FILE -function test_docinfo_name { - local -r filename="${1##*/}" - - # Check the file name and report the result: - if [[ "$filename" == "docinfo.xml" ]]; then - pass "The file name is 'docinfo.xml'." - else - fail "The file name is not 'docinfo.xml'." - fi -} - -# Verifies that all attribute definitions are stored in the -# meta/attributes.adoc file to allow their reuse. -# -# Usage: test_attributes_location FILE -function test_attributes_location { - local -r filename=$(realpath "$1") - - # Check if the file is located in meta/attribute.doc and report the - # result: - if [[ "$filename" == */meta/attributes.adoc ]]; then - pass "Attribute definitions are stored in meta/attributes.adoc." - else - note "Attribute definitions belong to meta/attributes.adoc to enable reuse." - fi -} - -# Verifies that the AsciiDoc file sets the value of the 'context' attribute -# to a non-empty string. -# -# Usage: test_context_definition FILE -function test_context_definition { - local -r filename="$1" - - # Check if the file contains the attribute definition and report the - # result: - if print_adoc "$filename" | grep -qP '^:context:\s*\S+'; then - pass "The 'context' attribute is set to a non-empty string." - else - fail "The 'context' attribute is not set to a non-empty string." - fi -} - -# Verifies that the AsciiDoc file does not define the 'internal' attribute. -# -# Usage: test_internal_definition FILE -function test_internal_definition { - local -r filename="$1" - - # Check that the file does not contain the attribute definition and - # report the result: - if ! print_adoc "$filename" | grep -qP '^:internal:'; then - pass "The 'internal' attribute is not defined." - else - fail "The 'internal' attribute is defined. Editorial comments are visible." - fi -} - -# Verifies that modules and assemblies follow prescribed naming conventions -# and use one of the following prefixes to signify their type: -# -# con_ - a concept module -# ref_ - a reference module -# proc_ - a procedure module -# assembly_ - an assembly -# -# Usage: test_module_prefix FILE -function test_module_prefix { - local -r filename="$1" - - # Deduce the documentation type from the file name: - local -r type=$(detect_type "$filename") - - # Check if the type could be deduced and report the result: - if [[ "$type" != 'unknown' ]]; then - pass "The file name uses the con_, ref_, proc_, or assembly prefix." - else - fail "The file name does not use the con_, ref_, proc_, or assembly_ prefix." - fi -} - -# Verifies that a procedure module contains at least one step. -# -# Usage: test_steps_in_proc FILE -function test_steps_in_proc { - local -r filename="$1" - - # Determine the document type: - local -r type=$(detect_type "$filename") - - # Check if the file is a procedure module and report the result, - # otherwise do nothing: - if [[ "$type" == 'procedure' ]]; then - # Check if the file contains at least one step: - if has_steps "$filename"; then - pass "The procedure module contains at least one step." - else - fail "The procedure module does not contain any steps." - fi - fi -} - -# Verifies that a concept module does not include any steps. -# -# Usage: test_steps_in_con FILE -function test_steps_in_con { - local -r filename="$1" - - # Determine the document type: - local -r type=$(detect_type "$filename") - - # Check if the file is a concept module and report the result, - # otherwise do nothing: - if [[ "$type" == 'concept' ]]; then - # Check if the file contains at least one step: - if ! has_steps "$filename"; then - pass "The concept module does not contain any steps." - else - note "The concept module contains one or more steps." - fi - fi -} - -# Verifies that a reference module does not include any steps. -# -# Usage: test_steps_in_ref FILE -function test_steps_in_ref { - local -r filename="$1" - - # Determine the document type: - local -r type=$(detect_type "$filename") - - # Check if the file is a reference module and report the result, - # otherwise do nothing: - if [[ "$type" == 'reference' ]]; then - # Check if the file contains at least one step: - if ! has_steps "$filename"; then - pass "The reference module does not contain any steps." - else - note "The reference module contains one or more steps." - fi - fi -} - -# Verifies that all IDs have the 'context' attribute in them to remain -# reusable in different assemblies. -# -# Usage: test_context_in_ids FILE -function test_context_in_ids { - local -r filename="$1" - - # Locate all IDs used in the AsciiDoc file: - while read unique_id; do - # Check if the ID contains the 'context' attribute and report the - # result: - if echo "$unique_id" | grep -q '{context}'; then - pass "The '$unique_id' ID includes the 'context' attribute." - else - fail "The '$unique_id' ID does not include the 'context' attribute." - fi - done < <(list_ids "$filename") -} - -# Verifies that Red Hat Enterprise Linux is abbreviated in section headings -# for brevity. -# -# Usage: test_rhel_in_headings FILE -function test_rhel_in_headings { - local -r filename="$1" - - # Locate all headings used in the AsciiDoc file: - while read heading; do - # Check that the heading does not spell out Red Hat Enterprise Linux - # and report the result: - if ! echo "$heading" | \ - grep -qP 'Red({nbsp}| )Hat({nbsp}| )Enterprise({nbsp}| )Linux|{RHEL}'; then - # Check if the abbreviation is used to see if the success is worth - # mentioning: - if echo "$heading" | grep -qP '\bRHEL\b'; then - pass "The heading '$heading' does not expand the RHEL abbreviation." - fi - else - fail "The heading '$heading' does not use the RHEL abbreviation." - fi - done < <(list_headings "$filename") -} - -# Verifies that none of the renamed or replaced projects are mentioned. -# -# Usage: test_replaced_projects FILE -function test_replaced_projects { - local -r filename="$1" - - # Define a glossary of old and new project names: - local -A projects - projects['Cockpit']='RHEL web console' - - # Iterate over the project names: - for name in "${!projects[@]}"; do - # Check if the AsciiDoc file mentions the replaced project and report - # the result: - if ! print_adoc "$filename" | grep -qP "\b$name\b"; then - pass "The '$name' project is not mentioned." - else - fail "The '$name' project is mentioned. Use ${projects[$name]} instead." - fi - done -} - -# Verifies that all external links are functional. -# -# Usage: test_external_links FILE -function test_extarnal_links { - local -r filename="$1" - - # Verify that the link testing is enabled as this slows down the script - # significantly: - [[ "$OPT_LINKS" -gt 0 ]] || return - - # Locate all external links used in the AsciiDoc file: - local -r links=$(list_links "$filename") - - # Get a list of all broken links: - export -f print_broken - local -r broken=$(echo "$links" | xargs -n 1 -P 0 bash -c 'print_broken "$@"' --) - - # Report the results for broken links: - while read link; do - fail "Link is broken: '$link'" - done < <(echo "$broken" | sed '/^$/d') - - # Report the results for functional links: - while read link; do - pass "Link is functional: '$link'" - done < <(echo -e "$links\n$broken" | sed '/^$/d' | sort | uniq -u ) -} - -# Verifies that there are no links to older RHEL documentation, including -# a previous beta release. -# -# Usage: test_old_rhel_links FILE -function test_old_rhel_links { - local -r filename="$1" - - # Locate all external links pointing to documentation for Red Hat - # Enterprise Linux: - local -r links=$(list_links "$filename" | grep -i '://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/') - - # Get a list of all links for older RHEL releases: - local -r wrong=$(echo "$links" | grep -ie '://access\.redhat\.com/documentation/en-us/red_hat_enterprise_linux/\([1-7]\|.-beta\)/') - - # Report the results for problematic links: - while read link; do - fail "Link refers to an older RHEL release: '$link'" - done < <(echo "$wrong" | sed '/^$/d') - - # Report the results for non-problematic links: - while read link; do - pass "Link refers to the current RHEL release: '$link'" - done < <(echo -e "$links\n$wrong" | sed '/^$/d' | sort | uniq -u ) -} - -# Verifies that there are no links to removed or renamed titles. -# -# Usage: test_old_title_links FILE -function test_old_title_links { - local -r filename="$1" - - # Define a glossary of old and new title fragments: - local -A titles - titles['comparing_rhel_8_to_rhel_7']='considerations_in_adopting_rhel_8' - titles['comparing-rhel-8-to-rhel-7']='considerations-in-adopting-rhel-8' - - # Locate all external links pointing to documentation for Red Hat - # Enterprise Linux: - local -r links=$(list_links "$filename" | grep -i '://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/') - - # Stop here if there are no documentation links: - [[ -z "$links" ]] && return - - # Iterate over title fragments: - for fragment in "${!titles[@]}"; do - # Get a list of all links containing the old URL fragment: - local wrong=$(echo "$links" | grep "$fragment") - - # Determine if there were any problematic links: - if [[ -z "$wrong" ]]; then - # Report the result for non-problematic links: - pass "Links do not refer to deprecated title '$fragment'." - else - # Report the results for problematic links: - while read link; do - fail "Link refers to a deprecated title: '$link'. Use '${titles[$fragment]}' instead." - done < <(echo "$wrong" | sed '/^$/d') - fi - done -} - -# Verifies that there are no links to internal previews. -# -# Usage: test_preview_links FILE -function test_preview_links { - local -r filename="$1" - - # Locate all external links pointing to Red Hat product documentation: - local -r links=$(list_links "$filename" | grep -i '://[^/]\+\.redhat\.com/documentation/') - - # Get a list of all preview links: - local -r wrong=$(echo "$links" | sed -ne '/lb_target=\(stage\|preview\)/p;/access\.redhat\.com/!p') - - # Report the results for preview links: - while read link; do - fail "Link refers to a preview build: '$link'" - done < <(echo "$wrong" | sed '/^$/d') - - # Report the results for non-problematic links: - while read link; do - pass "Link does not refer to a preview build: '$link'" - done < <(echo -e "$links\n$wrong" | sed '/^$/d' | sort | uniq -u ) -} - -# Verifies that only assemblies have includes, and that these always add -# exactly one level. -# -# Usage: test_leveloffsets FILE -function test_leveloffsets { - local -r filename="$1" - - # Look for different types of include statements in the AsciiDoc file: - (print_adoc "$filename" | grep -qP "include::[^\[]+\[leveloffset=\+1\]") - local -r good_leveloffsets="$?" - (print_adoc "$filename" | grep -qP "include::[^\[]+\[(?!leveloffset=\+1)") - local -r bad_leveloffsets="$?" - (print_adoc "$filename" | grep -qP "include::[^\[]+\[") - local -r any_includes="$?" - - # Determine the document type: - local -r type=$(detect_type "$filename") - - # Produce different results for assemblies and modules: - if [[ "$type" == 'assembly' ]] ; then - # Verify that the assembly contains at least one include: - if [[ "$any_includes" -gt 0 ]] ; then - fail "Assembly does not contain any included modules." - else - pass "Assembly contains includes." - fi - elif [[ "$type" =~ ^(procedure|concept|reference|unknown)$ ]]; then - # Verify that modules do not contain any includes: - if [[ "$any_includes" -eq 0 ]]; then - fail "Module contains one or more includes." - else - pass "Module does not contain any includes." - fi - fi - - # Report unclean leveloffsets in all document types: - if [[ "$bad_leveloffsets" -eq 0 ]]; then - fail "Found leveloffsets that do not add exactly one level." - else - pass "Found only leveloffsets that add exactly one level." - fi -} - - -# Verifies that there is exactly one non-[discrete] heading in the module. -# -# Usage: test_module_headings FILE -function test_module_headings { - local -r filename="$1" - - local -r type=$(detect_type "$filename") - if [[ "$type" == 'assembly' ]] ; then - return 0 # check only modules - fi - local -r num_headings=$(print_adoc "$filename" | perl -pe 's/\[discrete\][\n\r]+/removed-discrete-heading-endline/g' | grep -oP '^[\n\r]*=+[\s]+[^\s]+.+' | wc -l) - # explanation: 1. change all [discrete]+newline into text, thus making them into text=== heading form 2. count the actual headings after that - if [[ "$num_headings" -eq 0 ]]; then - fail "Module does not have any heading." - elif [[ "$num_headings" -eq 1 ]]; then - pass "Module has exactly one heading." - elif [[ "$num_headings" -gt 1 ]]; then - fail "Module has more than one heading." - fi -} - - -# ------------------------------------------------------------------------- -# MAIN SCRIPT -# ------------------------------------------------------------------------- - -# Process command-line options: -while getopts ':hilvV' OPTION; do - case "$OPTION" in - h) - # Print usage information to standard output: - echo "Usage: $NAME [-ilv] FILE..." - echo -e " $NAME -hV\n" - echo ' -i also test included files' - echo ' -l test external links (slow)' - echo ' -v include successful test results in the report' - echo ' -h display this help and exit' - echo ' -V display version and exit' - - # Terminate the script: - exit 0 - ;; - i) - # Enable processing of included files: - OPT_INCLUDES=1 - ;; - l) - # Enable testing of external links: - OPT_LINKS=1 - ;; - v) - # Increase the verbosity level: - OPT_VERBOSITY=1 - ;; - V) - # Print version information to standard output: - echo "$NAME $VERSION" - - # Terminate the script: - exit 0 - ;; - *) - # Report invalid option and terminate the script: - exit_with_error "Invalid option -- '$OPTARG'" 22 - ;; - esac -done - -# Shift positional parameters: -shift $(($OPTIND - 1)) - -# Verify the number of command line arguments: -[[ "$#" -gt 0 ]] || exit_with_error 'Invalid number of arguments' 22 - -# Verify that all required utilities are present in the system: -for dependency in asciidoctor curl xmlstarlet; do - if ! type "$dependency" &>/dev/null; then - exit_with_error "Missing dependency -- '$dependency'" 1 - fi -done - -# Process the rest of the remaining command-line arguments: -for file in "$@"; do - # Process the file and print the report: - print_report "$file" - - # Check whether to also process included files provided the file is an - # AsciiDoc file: - if [[ "$file" == *.adoc ]] && [[ "$OPT_INCLUDES" -gt 0 ]]; then - # Process each included file and print the report for it: - while read include; do - print_report "$include" - done < <(print_includes "$file") - fi -done - -# Print the summary: -print_summary - -# Terminate the script: -[[ "$ISSUES" -eq 0 ]] && exit 0 || exit 1 - -# Manual page: -:<<-=cut - -=head1 NAME - -test-adoc - test an AsciiDoc file and report possible issues - -=head1 SYNOPSIS - -B<test-adoc> [B<-ilv>] I<file>... - -B<test-adoc> B<-hV> - -=head1 DESCRIPTION - -The B<test-adoc> utility reads one or more AsciiDoc files, runs a series of -test cases on them, and prints the test results to standard output. - -=head1 OPTIONS - -=over - -=item B<-i> - -Enables processing of included files. By default, the script only reads -AsciiDoc files supplied on the command line. - -=item B<-l> - -Enables testing of external links. As verifying that all external links in -a large number of AsciiDoc files can be slow, this functionality is -disabled by default. - -=item B<-v> - -Includes successful test results in the report. By default, the script only -reports failed tests. - -=item B<-h> - -Displays usage information and terminates the script. - -=item B<-V> - -Displays the script version and terminates the script. - -=back - -=head1 EXAMPLES - -=over - -=item * - -To test a single AsciiDoc module named I<my_module.adoc>, include broken -links in the report, and include successful test results in the output, -type the following command at a shell prompt: - - test-adoc -lv my_module.adoc - -=item * - -To test all AsciiDoc modules in the current working directory without -looking for broken links or printing successful test results, type: - - test-adoc *.adoc - -=item * - -To test I<master.adoc> and all assemblies and modules included in this -file, type: - - test-adoc -i master.adoc - -=back - -=head1 SEE ALSO - -B<asciidoctor>(1), B<curl>(1), B<xmlstarlet>(1) - -=head1 BUGS - -To report a bug or submit a patch, please visit -L<https://github.com/jhradilek/check-links/>. - -=head1 COPYRIGHT - -Copyright (C) 2013, 2014, 2019 Jaromir Hradilek E<lt>jhradilek@gmail.comE<gt> - -This program is free software; see the source for copying conditions. It is -distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; -without even the implied warranty of MERCHANTABILITY or FITNESS FOR A -PARTICULAR PURPOSE. - -=cut