diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index daa635b834..e958f6d772 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,2 +1,2 @@ # Global Owners -* @rkratky @themr0c @boczkowska @MichalMaler @eclipse/ecd-che-docs-reviewers +* @rkratky @themr0c @max-cx @tstastna @eclipse/ecd-che-docs-reviewers diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 659a4560ad..4f8f579493 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,22 +1,30 @@ -> Read our [Contribution guide](https://github.com/eclipse/che-docs/blob/master/CONTRIBUTING.adoc) before submitting a PR. -### What does this PR do? + + -### What issues does this PR fix or reference? +## What does this pull request change? +## What issues does this pull request fix or reference? -### Specify the version of the product this PR applies to. +## Specify the version of the product this pull request applies to +## Pull Request checklist -### PR Checklist +The author and the reviewers validate the content of this pull request with the following checklist, in addition to the [automated tests](code_review_checklist.adoc). -As the author of this Pull Request I made sure that: - -- [ ] `vale` has been run successfully against the PR branch -- [ ] Link checker has been run successfully against the PR branch -- [ ] Documentation describes a scenario that is already covered by QE tests, otherwise an issue has been created and acknowledged by Che QE team -- [ ] Changed article references are updated where they are used (or a redirect has been set up on the docs side): - - [ ] Dashboard [branding.json](https://github.com/eclipse/che-dashboard/blob/master/src/components/branding/branding.json) +- Any procedure: + - [ ] Successfully tested. +- Any page or link rename: + - [ ] The page contains a redirection for the previous URL. + - Propagate the URL change in: + - [ ] Dashboard [default branding data](https://github.com/eclipse-che/che-dashboard/blob/main/packages/dashboard-frontend/src/services/bootstrap/branding.constant.ts) - [ ] Chectl [constants.ts](https://github.com/che-incubator/chectl/blob/master/src/constants.ts) - +- [ ] Builds on [Eclipse Che hosted by Red Hat](https://workspaces.openshift.com). +- [ ] the *`Validate language on files added or modified`* step reports no vale warnings. diff --git a/.github/workflows/build-and-validate-on-pr.yaml b/.github/workflows/build-and-validate-on-pr.yaml new file mode 100644 index 0000000000..a6eb14625e --- /dev/null +++ b/.github/workflows/build-and-validate-on-pr.yaml @@ -0,0 +1,84 @@ +# +# 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 is reused in `publish-netlify.yml` +name: "Build and validate PR" + +on: + - pull_request + +jobs: + build: + name: link checker # This job name is set as mandatory in the GitHub configuration. + runs-on: ubuntu-20.04 + container: "quay.io/eclipse/che-docs:latest" + steps: + - name: Checkout code + uses: actions/checkout@v2 + with: + fetch-depth: 0 # Necessary for git diff in vale step + + # 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 # 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) + + - name: Upload artifact doc-content + uses: actions/upload-artifact@v2 + with: + name: doc-content + path: build/site + + - name: Store PR info 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 + uses: actions/upload-artifact@v2 + with: + name: pull-request-sha + path: PR_SHA + + - name: Validate links using htmltest + id: validate-links + run: htmltest + + - name: Report Unused Images + run: tools/detect-unused-images.sh + + - name: Validate language on files added or modified + run: | + tools/get_vale_styles.sh + tools/validate_language_changes.sh diff --git a/.github/workflows/build-and-validate-on-push.yaml b/.github/workflows/build-and-validate-on-push.yaml new file mode 100644 index 0000000000..e16a06fe96 --- /dev/null +++ b/.github/workflows/build-and-validate-on-push.yaml @@ -0,0 +1,68 @@ +# +# 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 +# + +# GitHub Actions configuration file for htmltest +# See: https://github.com/wjdp/htmltest + +name: Build and validate +on: + push: + branches: + - main + - master +jobs: + build: + name: Build and validate + runs-on: ubuntu-20.04 + container: "quay.io/eclipse/che-docs:latest" + steps: + - name: Checkout code + uses: actions/checkout@v2 + 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 + + - name: Upload artifact doc-content + uses: actions/upload-artifact@v2 + with: + name: doc-content + path: build/site + + - name: Validate links using htmltest + id: validate-links + run: htmltest + + - name: Report Unused Images + run: tools/detect-unused-images.sh + + - name: Count Vale alerts + run: tools/count_vale_errors.sh diff --git a/.github/workflows/build-pr-docs.yaml b/.github/workflows/build-pr-docs.yaml deleted file mode 100644 index eac73b6747..0000000000 --- a/.github/workflows/build-pr-docs.yaml +++ /dev/null @@ -1,39 +0,0 @@ -# -# 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: build-documentation-pr -on: pull_request -jobs: - build: - name: Build the documentation - runs-on: ubuntu-20.04 - container: "quay.io/eclipse/che-docs:latest" - steps: - - name: Checkout code - uses: actions/checkout@v2 - - name: build - id: antora-build - run: | - antora generate antora-playbook.yml - - uses: actions/upload-artifact@v2 - with: - name: doc-content - path: build/site - - name: Store PR info - run: | - echo "${{ github.event.number }}" > PR_NUMBER - echo "${{ github.event.pull_request.head.sha }}" > PR_SHA - - uses: actions/upload-artifact@v2 - with: - name: pull-request-number - path: PR_NUMBER - - uses: actions/upload-artifact@v2 - with: - name: pull-request-sha - path: PR_SHA 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 new file mode 100644 index 0000000000..cc88f56791 --- /dev/null +++ b/.github/workflows/che-variables-update.yml @@ -0,0 +1,37 @@ +# 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/che.yaml b/.github/workflows/che.yaml deleted file mode 100644 index 548bfda120..0000000000 --- a/.github/workflows/che.yaml +++ /dev/null @@ -1,16 +0,0 @@ -# Add Che link on PRs -name: che - -on: - pull_request: - types: [opened, synchronize] - -jobs: - add-link: - runs-on: ubuntu-latest - steps: - - name: Eclipse Che Pull Request Check - id: che-pr-check-gh-action - uses: benoitf/che-pr-check-gh-action@master - with: - github-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/link-checker.yaml b/.github/workflows/link-checker.yaml deleted file mode 100644 index 40a64b5611..0000000000 --- a/.github/workflows/link-checker.yaml +++ /dev/null @@ -1,26 +0,0 @@ -# -# 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: linkchecker-pr-check -on: [push, pull_request] -jobs: - linkchecker: - name: link checker - runs-on: ubuntu-20.04 - container: "quay.io/eclipse/che-docs:latest" - steps: - - name: Checkout code - uses: actions/checkout@v2 - - name: run linkchecker - run: | - # Build and serve - gulp & - sleep 20 - # Run link checker - linkchecker -f /doc/linkcheckerrc http://localhost:4000 diff --git a/.github/workflows/publish-netlify.yaml b/.github/workflows/publish-netlify.yml similarity index 61% rename from .github/workflows/publish-netlify.yaml rename to .github/workflows/publish-netlify.yml index 36bd2dfe63..d21beded39 100644 --- a/.github/workflows/publish-netlify.yaml +++ b/.github/workflows/publish-netlify.yml @@ -1,3 +1,4 @@ +--- # # Copyright (c) 2020 Red Hat, Inc. # This program and the accompanying materials are made @@ -7,31 +8,36 @@ # SPDX-License-Identifier: EPL-2.0 # -name: Publish Doc Content +# NOTE: Because this worklow is using secrets, it cannot run directly on a pull-request workflow, which is running in the context of the forked repository. + +name: Publish doc-content using netlify on: workflow_run: - workflows: ["build-documentation-pr"] + workflows: + - "Build and validate PR" types: - completed jobs: publish: - name: publish + name: Publish doc-content using netlify runs-on: ubuntu-20.04 steps: - - name: download doc artifact + - name: Download doc-content artifact uses: dawidd6/action-download-artifact@v2 with: workflow: ${{ github.event.workflow_run.workflow_id }} name: doc-content path: content - - name: PR number + + - name: Download pull-request-number artifact uses: dawidd6/action-download-artifact@v2 with: workflow: ${{ github.event.workflow_run.workflow_id }} name: pull-request-number - - name: Grab pull request number + + - name: Set PR_NUMBER variable run: | pr_number=$(cat "PR_NUMBER") if ! [[ "$pr_number" =~ ^[0-9]+$ ]]; then @@ -39,16 +45,19 @@ jobs: exit 1 fi echo "PR_NUMBER=$pr_number" >> $GITHUB_ENV - - name: PR sha + + - name: Download pull-request-sha artifact uses: dawidd6/action-download-artifact@v2 with: workflow: ${{ github.event.workflow_run.workflow_id }} name: pull-request-sha - - name: Grab pull request sha1 + + - name: Set PR_SHA variable run: | pr_sha=$(cat "PR_SHA") echo "PR_SHA=$pr_sha" >> $GITHUB_ENV - - name: Publish + + - name: Publish doc-content using netlify uses: netlify/actions/cli@master id: netlify-publish with: @@ -56,10 +65,11 @@ jobs: env: NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} - - name: 'Comment PR' + + - name: Comment the pull-request uses: actions/github-script@v3.0.0 with: - script: | - const { repo: { owner, repo } } = context; - const netlifyUrl = '${{ steps.netlify-publish.outputs.NETLIFY_URL }}'; - await github.repos.createCommitStatus({ owner, repo, sha: process.env.PR_SHA, state: "success", target_url: netlifyUrl, description: "Browse PR documentation online", context: "browse built doc"}) + script: | + const { repo: { owner, repo } } = context; + const netlifyUrl = '${{ steps.netlify-publish.outputs.NETLIFY_URL }}'; + await github.repos.createCommitStatus({ owner, repo, sha: process.env.PR_SHA, state: "success", target_url: netlifyUrl, description: "Browse PR documentation online", context: "browse built doc"}) diff --git a/.github/workflows/pull-request-assigned.yml b/.github/workflows/pull-request-assigned.yml new file mode 100644 index 0000000000..39ddc3dad5 --- /dev/null +++ b/.github/workflows/pull-request-assigned.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 assigned + +on: + pull_request_target: + types: + - assigned + +jobs: + automate-project-columns: + runs-on: ubuntu-latest + steps: + - uses: alex-page/github-project-automation-plus@v0.8.1 + with: + project: Reviews + column: In progress + repo-token: ${{ secrets.CHE_BOT_GITHUB_TOKEN }} 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 new file mode 100644 index 0000000000..2515681cb9 --- /dev/null +++ b/.github/workflows/pull-request-opened.yml @@ -0,0 +1,28 @@ +# +# 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: + - opened + - ready_for_review + - unassigned + +jobs: + automate-project-columns: + runs-on: ubuntu-latest + steps: + - uses: alex-page/github-project-automation-plus@v0.8.1 + with: + project: Reviews + column: Triage + repo-token: ${{ secrets.CHE_BOT_GITHUB_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 22f6c88c99..75cca9a8fd 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -6,16 +6,59 @@ on: version: description: 'The version that is going to be released. Should be in format 7.y.z' required: true - default: '7.y.z' + 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.GITHUB_TOKEN }} + 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/.github/workflows/vale-on-push.yaml b/.github/workflows/try-in-web-ide.yaml similarity index 51% rename from .github/workflows/vale-on-push.yaml rename to .github/workflows/try-in-web-ide.yaml index 886f990ccf..e71a9ecdb8 100644 --- a/.github/workflows/vale-on-push.yaml +++ b/.github/workflows/try-in-web-ide.yaml @@ -6,21 +6,20 @@ # # SPDX-License-Identifier: EPL-2.0 # +# Add Web IDE link on PRs +name: web-ide -name: vale-push-check on: - - push + pull_request_target: + types: + - opened + jobs: - vale-all-content: - name: Validate style on all content on push + add-link: runs-on: ubuntu-20.04 - container: "quay.io/eclipse/che-docs:latest" steps: - - name: Checkout code - uses: actions/checkout@v2 + - name: Web IDE Pull Request Check + id: try-in-web-ide + uses: redhat-actions/try-in-web-ide@main with: - fetch-depth: 0 - - name: Vale - run: | - vale -v - vale . + github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/unused-images.yaml b/.github/workflows/unused-images.yaml deleted file mode 100644 index 4cba3d0d07..0000000000 --- a/.github/workflows/unused-images.yaml +++ /dev/null @@ -1,20 +0,0 @@ -# -# 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: unused-images-pr-check -on: [push, pull_request] -jobs: - linkchecker: - name: unused-images - runs-on: ubuntu-20.04 - steps: - - name: Checkout code - uses: actions/checkout@v2 - - name: Detect Unused Images - run: tools/detect-unused-images.sh diff --git a/.github/workflows/vale-on-pr.yaml b/.github/workflows/vale-on-pr.yaml deleted file mode 100644 index e2eb2b6630..0000000000 --- a/.github/workflows/vale-on-pr.yaml +++ /dev/null @@ -1,28 +0,0 @@ -# -# 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 -# - -name: vale-pr-check -on: - - pull_request -jobs: - vale-diff: - name: Validate style on new and modified files in PR - 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: Vale - run: | - vale -v - echo "Changed files, in comparison to branch $GITHUB_BASE_REF" - git diff --name-only --diff-filter=AM origin/$GITHUB_BASE_REF - vale $(git diff --name-only --diff-filter=AM origin/$GITHUB_BASE_REF) diff --git a/.gitignore b/.gitignore index aedce8a761..7f9a58857a 100644 --- a/.gitignore +++ b/.gitignore @@ -30,8 +30,18 @@ build/site build/site.zip build/site-unbranded +# Keep Vale styles external +.vale/styles/ + linkchecker-out.html +.ash_history .bash_history .cache .local .yarnrc +yarn.lock + +.DS_Store + +# Do not commit diagrams generated for downstream +crw* diff --git a/.htmltest.yml b/.htmltest.yml index fd217ee889..77132a4475 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -1,8 +1,24 @@ --- -DirectoryPath: build/site/che-7 # Not build/site to avoid false positives on 404.html -IgnoreInternalEmptyHash: true # Legit empty hash present in every page +# +# 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 +# + +# Configuration file for htmltest +# See: https://github.com/wjdp/htmltest + +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: "6h" # Default is 2 weeks. +CacheExpires: "12h" # Default is 2 weeks. +ExternalTimeout: 60 # (seconds) default is 15. IgnoreURLs: - https://cse.google.com/cse.js - https://marketplace.visualstudio.com + - https://github.com/eclipse/che-docs/edit/master/ + - https://www.eclipse.org/che/docs/che-7/ + - https://projectlombok.org/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c150c845c9..e173314ceb 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -16,7 +16,7 @@ repos: name: Build documentation with Antora description: Build documentation with Antora language: docker_image - entry: docker.io/antora/antora antora-playbook.yml + entry: docker.io/antora/antora antora-playbook-for-development.yml pass_filenames: false always_run: true verbose: true diff --git a/.vale.ini b/.vale.ini index ef83225077..38b9a2724c 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,63 +1,57 @@ -# Vale configuration file, taken from https://errata-ai.github.io/vale/config/ +# Vale configuration file for `che-docs` repository. +# See: https://docs.errata.ai/vale/config -# The relative path to the folder containing linting rules (styles) -# ----------------------------------------------------------------- +# The relative path to the folder containing linting rules (styles). StylesPath = .vale/styles - -Vocab = Che # Minimum alert level # ------------------- -# The minimum alert level to display (suggestion, warning, or error). -# If integrated into CI, builds fail by default on error-level alerts, -# unless you execute Vale with the --no-exit flag +# 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 -IgnoredScopes = code, tt, img, url, a -SkippedScopes = script, style, pre, figure - - -# What file types should Vale test? -# ---------------------------------- -[*.adoc] - -# Styles to load -# -------------- -# What styles, located in the StylesPath folder, should Vale load? -BasedOnStyles = CheDocs,IBM,Vale - - -# Enabling or disabling specific rules in a style -# ----------------------------------------------- -# To disable a rule in an enabled style, use the following format: -# {style}.{filename} = NO -# To enable a single rule in a disabled style, use the following format: -# vale.Editorializing = YES - -# For testing and editing purposes on local. Commented out for now. -# CheDocs.CommonTerms = NO -# CheDocs.Links-che6 = NO -# CheDocs.Links = NO -# CheDocs.SentenceLength = NO -# IBM.Foreign = NO -# IBM.HeadingPunctuation = NO -# IBM.Spacing = NO -# IBM.PassiveVoice = NO -# IBM.Slash = NO -# IBM.Wordiness = NO -# IBM.Words = NO -# IBM.Annotations = NO -# IBM.Spelling = NO -# IBM.Very = NO -# IBM.ThereIs = NO -# IBM.terms = NO -# IBM.Usage = NO -Vale.Spelling = YES -Vale.Repetition = NO - - - -# Altering the severity of a rule in a style -# ------------------------------------------ -# To change the reporting level (suggestion, warning, error) of a rule, -# use the following format: {style}.{filename} = {level} -IBM.Usage = suggestion + +# IgnoredScopes specifies inline-level HTML tags to ignore. +# 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. +# Default: ignore `script`, `style`, `pre`, and `figure`. +# For AsciiDoc: by default, listingblock, and literalblock. +SkippedScopes = script, style, pre, figure, code, tt, blockquote, listingblock, literalblock + +# Rules for matching file types. See: https://docs.errata.ai/vale/scoping +[[!.]*.adoc] + +# Styles to load, located in the `StylesPath` folder: +# Project specific (CheDocs) +# IBM Style Guide (IBM) +# Generic (Vale) +BasedOnStyles = CheDocs,RedHat + +# Ignore attributes definition, id statements +TokenIgnores = (:[^\n]+: [^\n]+), (\[id=[^\n]+) + +# To validate the `che.properties` file, associate it with the `md` format +[formats] +properties = md + +# Define specific rules for the `md` format, hijacked to process `che.properties`. +[*.md] +BasedOnStyles = RedHat +# Ignore code surrounded by backticks or plus sign, parameters defaults, URLs. +TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[) +RedHat.Annotations = suggestion +RedHat.HeadingPunctuation = NO +RedHat.Headings = NO +RedHat.Slash = warning +RedHat.Usage = suggestion + +[*.ini] +BasedOnStyles = RedHat +RedHat.Slash = NO +RedHat.Spacing = NO +RedHat.Spelling = NO +RedHat.url = NO +RedHat.ConfigMap = NO +RedHat.write = NO + diff --git a/.vale/fixtures/CheDocs/Attributes/.vale.ini b/.vale/fixtures/CheDocs/Attributes/.vale.ini index 050fc78f48..532eaaf0ec 100644 --- a/.vale/fixtures/CheDocs/Attributes/.vale.ini +++ b/.vale/fixtures/CheDocs/Attributes/.vale.ini @@ -2,5 +2,9 @@ StylesPath = ../../../styles MinAlertLevel = suggestion -[*.adoc] +# 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 new file mode 100644 index 0000000000..ac745b8b9e --- /dev/null +++ b/.vale/fixtures/CheDocs/Attributes/invalid.testadoc @@ -0,0 +1,28 @@ +`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/test.adoc b/.vale/fixtures/CheDocs/Attributes/test.adoc deleted file mode 100644 index 7930f07183..0000000000 --- a/.vale/fixtures/CheDocs/Attributes/test.adoc +++ /dev/null @@ -1,24 +0,0 @@ -Image Puller: image-puller-name-short -Keycloak: identity-provider -`kubectl` or `oc`: orch-family-cli -kubectl: orch-cli -kubernetes: orch-name, platforms-name or kubernetes -Kubernetes: 'orch-name, platforms-name or kubernetes' -Kubernetes Image Puller: image-puller-name -KubernetesImagePuller: image-puller-cr-name -kubernetes-image-puller: image-puller-deployment-name -Kubernetes Image Puller Operator: image-puller-operator-name -Kubernetes Ingress or OpenShift Route: platforms-ingress -Kubernetes and OpenShift: platforms-name -Kubernetes or OpenShift: platforms-name -namespace: platforms-namespace or orch-namespace -OpenShift and Kubernetes: platforms-name -OpenShift or Kubernetes: platforms-name -prod-shor: prod-short -Kubernetes Ingress or OpenShift route: platforms-ingress -Kubernetes Ingress: platforms-ingress - namespace -namespace} -namespace: -namespace: platforms-namespace or orch-namespace -namespace or project: platforms-namespace \ No newline at end of file diff --git a/.vale/fixtures/CheDocs/Attributes/valid.testadoc b/.vale/fixtures/CheDocs/Attributes/valid.testadoc new file mode 100644 index 0000000000..6eb1650c42 --- /dev/null +++ b/.vale/fixtures/CheDocs/Attributes/valid.testadoc @@ -0,0 +1,20 @@ +{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 new file mode 100644 index 0000000000..8e1a5a7bfa --- /dev/null +++ b/.vale/fixtures/CheDocs/CommonTerms/.vale.ini @@ -0,0 +1,6 @@ +StylesPath = ../../../styles + +MinAlertLevel = suggestion + +[*.adoc] +CheDocs.CommonTerms = YES diff --git a/.vale/fixtures/CheDocs/CommonTerms/testinvalid.adoc b/.vale/fixtures/CheDocs/CommonTerms/testinvalid.adoc new file mode 100644 index 0000000000..283115db5e --- /dev/null +++ b/.vale/fixtures/CheDocs/CommonTerms/testinvalid.adoc @@ -0,0 +1,3 @@ +invalid content: Che +invalid content: che + diff --git a/.vale/fixtures/CheDocs/CommonTerms/testvalid.adoc b/.vale/fixtures/CheDocs/CommonTerms/testvalid.adoc new file mode 100644 index 0000000000..0c0ddf8eed --- /dev/null +++ b/.vale/fixtures/CheDocs/CommonTerms/testvalid.adoc @@ -0,0 +1 @@ +valid content: Che-Theia diff --git a/.vale/fixtures/CheDocs/ConfigMap/.vale.ini b/.vale/fixtures/CheDocs/ConfigMap/.vale.ini new file mode 100644 index 0000000000..a67e1e75f6 --- /dev/null +++ b/.vale/fixtures/CheDocs/ConfigMap/.vale.ini @@ -0,0 +1,6 @@ +StylesPath = ../../../styles + +MinAlertLevel = suggestion + +[*.adoc] +CheDocs.ConfigMap = YES diff --git a/.vale/fixtures/CheDocs/ConfigMap/testinvalid.adoc b/.vale/fixtures/CheDocs/ConfigMap/testinvalid.adoc new file mode 100644 index 0000000000..0934261adb --- /dev/null +++ b/.vale/fixtures/CheDocs/ConfigMap/testinvalid.adoc @@ -0,0 +1,11 @@ +invalid content: config: +invalid content: config, +invalid content: config. +invalid content: config directory +invalid content: config file +invalid content: config file map +invalid content: config-map +invalid content: config mail +invalid content: config mapping +invalid content: config abc +invalid content: config \ No newline at end of file diff --git a/.vale/fixtures/CheDocs/ConfigMap/testvalid.adoc b/.vale/fixtures/CheDocs/ConfigMap/testvalid.adoc new file mode 100644 index 0000000000..767aae38fc --- /dev/null +++ b/.vale/fixtures/CheDocs/ConfigMap/testvalid.adoc @@ -0,0 +1,3 @@ +valid content: config map +valid content: config maps +valid content: configure \ No newline at end of file diff --git a/.vale/fixtures/CheDocs/InternalLinks/.vale.ini b/.vale/fixtures/CheDocs/InternalLinks/.vale.ini new file mode 100644 index 0000000000..a63dcc5114 --- /dev/null +++ b/.vale/fixtures/CheDocs/InternalLinks/.vale.ini @@ -0,0 +1,6 @@ +StylesPath = ../../../styles + +MinAlertLevel = suggestion + +[*.adoc] +CheDocs.InternalLinks = YES diff --git a/.vale/fixtures/CheDocs/InternalLinks/testinvalid.adoc b/.vale/fixtures/CheDocs/InternalLinks/testinvalid.adoc new file mode 100644 index 0000000000..070663b41e --- /dev/null +++ b/.vale/fixtures/CheDocs/InternalLinks/testinvalid.adoc @@ -0,0 +1,5 @@ +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 new file mode 100644 index 0000000000..3cb5108993 --- /dev/null +++ b/.vale/fixtures/CheDocs/InternalLinks/testvalid.adoc @@ -0,0 +1,7 @@ +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 new file mode 100644 index 0000000000..f4e266d364 --- /dev/null +++ b/.vale/fixtures/CheDocs/Spelling/.vale.ini @@ -0,0 +1,11 @@ +; 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 new file mode 100644 index 0000000000..83944245a4 --- /dev/null +++ b/.vale/fixtures/CheDocs/Spelling/testinvalid.adoc @@ -0,0 +1,90 @@ +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 new file mode 100644 index 0000000000..6a715a8b7e --- /dev/null +++ b/.vale/fixtures/CheDocs/Spelling/testvalid.adoc @@ -0,0 +1,136 @@ +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 new file mode 100644 index 0000000000..813d5d9a9c --- /dev/null +++ b/.vale/fixtures/CheDocs/TechnicalTerms/.vale.ini @@ -0,0 +1,11 @@ +; 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 new file mode 100644 index 0000000000..0cf23f296e --- /dev/null +++ b/.vale/fixtures/CheDocs/TechnicalTerms/testinvalid.adoc @@ -0,0 +1,7 @@ +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 new file mode 100644 index 0000000000..eaecd29e69 --- /dev/null +++ b/.vale/fixtures/CheDocs/TechnicalTerms/testvalid.adoc @@ -0,0 +1 @@ +valid content: config map diff --git a/build/.placeholder b/.vale/styles/.placeholder similarity index 100% rename from build/.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 7b54ee34c1..0000000000 --- a/.vale/styles/CheDocs/Attributes.yml +++ /dev/null @@ -1,25 +0,0 @@ ---- -extends: substitution -message: Use the attribute '%s' instead of '%s'. -level: warning -ignorecase: true -scope: raw -# swap maps tokens in form of bad: good -swap: - Image Puller: image-puller-name-short - '`kubectl` or `oc`': orch-family-cli - Kubernetes Image Puller: image-puller-name - KubernetesImagePuller: image-puller-cr-name - kubernetes-image-puller: image-puller-deployment-name - Kubernetes Image Puller Operator: image-puller-operator-name - Kubernetes Ingress or OpenShift Route: platforms-ingress - 'Kubernetes (?:and|or) OpenShift': platforms-name - namespace or project: platforms-namespace - 'OpenShift (?:and|or) Kubernetes': platforms-name - Kubernetes Ingress or OpenShift route: platforms-ingress - Kubernetes Ingress: platforms-ingress - quay.io/eclipse/kubernetes-image-puller: image-puller-image-name - '\s[^[:punct:]]keycloak[^[:punct:]\.]': identity-provider - '\s[^[:punct:]]kubectl[^[:punct:]]': orch-cli - '\s[^[:punct:]]namespace[^[:punct:]]': platforms-namespace or orch-namespace - '\s[^[:punct:]]kubernetes[^[:punct:]]': orch-name, platforms-name or kubernetes \ No newline at end of file diff --git a/.vale/styles/CheDocs/CommonTerms.yml b/.vale/styles/CheDocs/CommonTerms.yml deleted file mode 100644 index 62f25ab3c8..0000000000 --- a/.vale/styles/CheDocs/CommonTerms.yml +++ /dev/null @@ -1,25 +0,0 @@ ---- -extends: substitution -message: Consider using '%s' instead of '%s' -ignorecase: false -level: warning -swap: - '\sche': '{prod-short}' - '\sChe': '{prod-short}' - '\sContainer Registry': Red Hat Ecosystem Catalog - '\sContainer Catalog': Red Hat Ecosystem Catalog - '\s[^n] binary': tool - '\sconfig map': ConfigMap - '\sconfig maps': ConfigMaps - '\sDotnet': .NET - '\sdotnet': .NET - '\sis installed': is available - '\sjava': Java - '\soperator': Operator - '\spostgres': PostgreSQL - '\sPostgres': PostgreSQL - '\spresent': available - '\sprogram': tool - '\sSsl': TLS - '\sssl': TLS - '\sSSL': TLS diff --git a/.vale/styles/CheDocs/ConfigMap.yml b/.vale/styles/CheDocs/ConfigMap.yml new file mode 100644 index 0000000000..d2453bae5c --- /dev/null +++ b/.vale/styles/CheDocs/ConfigMap.yml @@ -0,0 +1,7 @@ +# Ensures that 'config' is always followed by a white space. +extends: existence +message: "Do not use 'config', unless it is followed by 'map'." +level: error +ignorecase: true +raw: + - 'config([[:punct:]]|$|\s(?!maps?\b))' \ No newline at end of file diff --git a/.vale/styles/CheDocs/Links-che6.yml b/.vale/styles/CheDocs/Links-che6.yml deleted file mode 100644 index 39ccc5eb92..0000000000 --- a/.vale/styles/CheDocs/Links-che6.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: Eclipse Che 6 is obsolete. Consider removing '%s' -level: suggestion -code: false -ignorecase: true -tokens: - - www.eclipse.org\S*che-6 \ No newline at end of file diff --git a/.vale/styles/CheDocs/Links.yml b/.vale/styles/CheDocs/Links.yml deleted file mode 100644 index 66507682af..0000000000 --- a/.vale/styles/CheDocs/Links.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: substitution -message: Use '%s' instead of '%s.' -level: error -ignorecase: true -swap: - \slink\:https\://www.eclipse.org\S*\s: link:{site-baseurl}che-7/ - \shttps\://www.eclipse.org\S*\s: link:{site-baseurl}che-7/ \ No newline at end of file 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 c94febc965..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: warning -max: 21 -token: '\b(\w+)\b' 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 402076869f..0000000000 --- a/.vale/styles/IBM/README-proselint.md +++ /dev/null @@ -1,12 +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 3edcc9b376..0000000000 --- a/.vale/styles/IBM/README-write-good.md +++ /dev/null @@ -1,27 +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 8756d3453e..0000000000 --- a/.vale/styles/IBM/README.md +++ /dev/null @@ -1,4 +0,0 @@ -IBM styleguide was created by the IBM : https://www.ibm.com/developerworks/library/styleguidelines/index.html -All rights for the styleguide 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 6903dc3979..0000000000 --- a/.vale/styles/IBM/Terms.yml +++ /dev/null @@ -1,208 +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 - okay: OK - 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 - patch: fix|test fix|interim fix|fix pack|program temporary fix - 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 - prior to: before - 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 - transparent: indiscernible|not visible - 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/Vocab/Che/accept.txt b/.vale/styles/Vocab/Che/accept.txt deleted file mode 100644 index 2dcbb123cd..0000000000 --- a/.vale/styles/Vocab/Che/accept.txt +++ /dev/null @@ -1,106 +0,0 @@ -.NET -adoc -Antora -API -Asciidoc -AWS -boolean -Boolean -breakpoint -btn -Btrfs -CentOS -CentOS -Ceph -Che-Theia -Che-Theia -Classloading|classloading -ConfigMap -ConfigMaps -DaemonSet -DaemonSet -Developer Perspective -devfile -devfiles -DNS -Docker -Dockerfile -Dockerfile -Dotnet -Endevor -endif -factories -factory -git|Git -GitHub -GitLab -Gluster -Gradle -Grafana -GUI -HTTPS|https -IDE -IDEs -Intelephense -Java -jvm|JVM -helm -kbd -Keycloak -Keycloak -Kubernetes -Mattermost -Maven -mebibytes -Microsoft Azure -millicores -Minikube -minishift|Minishift -mixin|Mixin -mixins|Mixins -multiuser -MySQL -namespace -namespaces -Node.js -npm -NuGet -OAuth -ocp -OpenShift -OpenTracing -Operator -OperatorHub -osd -PHP -Pod -Pods -podman|Podman -PostgreSQL -preconfigured -runtime -runtimes -Spring Boot -stack -stacks -subnetwork -subpath -subpaths -SVG -Theia -tolerations -Uber -uninstallation -unstaged -URI -URIs -URL -URLs -Velero -Visual Studio Code -VS Code -workspace|Workspace -workspaces -YAML -Yeoman -Zowe diff --git a/.vale/styles/Vocab/Che/reject.txt b/.vale/styles/Vocab/Che/reject.txt deleted file mode 100644 index 82011706b3..0000000000 --- a/.vale/styles/Vocab/Che/reject.txt +++ /dev/null @@ -1,39 +0,0 @@ -admin -almost -clicking -config -e.g. -etc. -grab -I -i.e. -if -info -K8S -k8s -Kube -let's -like -look up -maybe -mostly -next -now -operator -our -out of the box -please -pod -previous -probably -refer -repo -set up -should -Stack -start up -take care of -usage -usually -want -we diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index e14350a33b..bb01d2551e 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -4,35 +4,45 @@ == Understanding Che Documentation ecosystem -* See the link:CODE_OF_CONDUCT.adoc[Code of conduct]. +* See the xref:CODE_OF_CONDUCT.adoc[Code of conduct]. * Use the following editorial resources: -** Minimalism in writing. See: https://docs.google.com/presentation/d/1Yeql9FrRBgKU-QlRU-nblPJ9pfZKgoKcU8SW6SQ_UqI/edit#slide=id.g1f4790d380_2_257[The Wisdom of Crowds slides] and https://youtu.be/s3Em8QSXyn8[The Wisdom of Crowds video]. See also: https://www.nngroup.com/articles/chunking/[Chunking]. +** Minimalism in writing. +*** link:https://docs.google.com/presentation/d/1Yeql9FrRBgKU-QlRU-nblPJ9pfZKgoKcU8SW6SQ_UqI/edit#slide=id.g1f4790d380_2_257[The Wisdom of Crowds slides] +*** link:https://youtu.be/s3Em8QSXyn8[The Wisdom of Crowds video] +*** link:https://www.nngroup.com/articles/chunking/[Chunking]. -** _IBM Style Guide_. See: link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[The IBM Style Guide: Conventions for Writers and Editors] and -https://www.ibm.com/developerworks/library/styleguidelines/index.html[developerWorks editorial style guide]. +** _IBM Style Guide_. + +*** link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[The IBM Style Guide, Conventions for Writers and Editors] + +*** link:https://github.com/errata-ai/IBM[A Vale-compatible implementation of IBM's _Developer Editorial Style Guide_] ** Guidelines from the -https://redhat-documentation.github.io/modular-docs/[Modular Documentation Initiative]. As Antora is using the term of _module_ with a different meaning, this project is referring to modules as _topics_. To understand the nature of topics, see the https://redhat-documentation.github.io/modular-docs/#modular-docs-terms-definitions[Appendix A: Modular Documentation Terms and Definitions]. +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]. + +* Use the link:https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow[Git Forking Workflow]. -* 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. -* link:https://www.eclipse.org/che/docs/che-7/hosted-che/[Eclipse Che hosted by Red Hat] 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]. -* link:https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc] is the markup language. +** link:https://docs.antora.org[Antora] builds the documentation. -* 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/redhat-documentation/newdoc[Newdoc] generates the topics templates. -* link:https://docs.errata.ai/vale/about/[Vale] validates the language. +** link:https://github.com/wjdp/htmltest[htmltest] validates the links. -* link:https://github.com/jhradilek/check-links[Test-adoc] validates the topic files. +** link:https://docs.errata.ai/vale/about/[Vale] validates the language. -* link:https://linkchecker.github.io/linkchecker/[Linkchecker] validates the links. +** link:https://www.shellcheck.net/[ShellCheck] validates the shell scripts. -* link:https://www.shellcheck.net/[ShellCheck] validates the shell scripts. +** link:https://github.com/jhradilek/check-links[Test-adoc] validates the topic files. [id="documentation-workflow"] @@ -40,9 +50,9 @@ https://redhat-documentation.github.io/modular-docs/[Modular Documentation Initi .Procedure -. Contributor submits a new code pull request in one of the Che repositories with a `status/doc-impact` label. +. 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 that a documentation pull request for the `master` branch of the `che-docs` repository is provided and referenced from the code pull request: +. 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. @@ -66,9 +76,13 @@ https://redhat-documentation.github.io/modular-docs/[Modular Documentation Initi [id="editing-submitting-and-reviewing-new-content"] == Editing, submitting and reviewing new content +.Prerequisites + +* A fork of the link:https://github.com/eclipse/che-docs/[] project, accessible at the following URL, where `____` is your GitHub organization or username: `++https++://github.com/____/che-docs/tree/____/` +. Open a che-docs workspace running on Eclipse Che hosted by Red Hat: `++https++://workspaces.openshift.com/f?url=https://github.com/____/che-docs/`. . Create a branch `____` for your work. @@ -82,7 +96,7 @@ https://redhat-documentation.github.io/modular-docs/[Modular Documentation Initi . To review the pull request: -.. Validate the accuracy of content, as well as build, language, links and modular docs requirements. +.. See the xref:code_review_checklist.adoc[code review checklist]. .. 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. @@ -108,26 +122,28 @@ To build the Eclipse Che documentation from a Che workspace, follow the steps be .Procedure -. Open _My Workspace_. +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 process generated documentation: Open _User Runtimes / bash-curl / Generate reference tables_. +. To validate the links: open _User Runtimes / che-docs / Validate links_. -. To build the documentation and start the preview server: open _User Runtimes / che-docs-dev / Start preview server_. +. To validate the language changes: open _My Workspace / User Runtimes / che-docs / Validate language changes_. -. To validate the language of the files currently open, look at the _Problems_ panel in the _Bottom Panel_. To toggle the view of this panel use the _View > Problems_ menu entry. +. 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. . To validate the compliance of an AsciiDoc file with Modular Documentation guidelines: .. In the _Explorer_, right-click on file to validate and select _Copy Path_. -.. Open _User Runtimes / che-docs-dev / Validate Modular Doc_. +.. Open _My Workspace / User Runtimes / che-docs / Validate Modular Doc_. .. In the _Validate Modular Doc_ panel in the _Bottom Panel_, paste the path of the file to validate. .. The tool `+test-adoc+` tests the file and produces some output. -. To validate all links: open _User Runtimes / linkchecker / Validate links_. - [id="creating-a-new-topic-using-che"] == Creating a new topic using Che @@ -165,6 +181,7 @@ Eclipse Che4z, OpenShift Connector. . The file is generated in the `+src/main/pages-che-7//+` directory and the script displays related information. +pass:[] == Adding images @@ -199,7 +216,7 @@ pass:[VARIABLE_NAME__WITH__UNDERSCORES] .... ==== -== Building and validating Documentation on a local environment +== Building and validating Documentation on a local environment using the `che-docs` container This section describes how to build and validate the documentation on a local environment. @@ -207,59 +224,46 @@ WARNING: This is not the preferred method. For the supported method, see: xref:b .Prerequisites: -* 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]. -* An installation of link:https://github.com/mrksu/newdoc[newdoc]. - -* An installation of -https://docs.errata.ai/vale/install[vale]. - -* An installation of https://github.com/linkchecker/linkchecker[linkchecker]. - - .Procedure -. Open a shell into the project directory. - -. Install Antora and Gulp using yarn: -+ ----- -$ yarn ----- - -. To build documentation locally, run: +. Open a terminal into the project directory, and build the documentation using and instance of the `che-docs` container: + ---- -$ gulp +$ ./tools/runnerpreview.sh ---- . Navigate to `+localhost:4000+` in your browser. -. To create a new topic using, run following command: +. Open a second terminal, and attach to the running `che-docs` container. Run all following steps from this context. ++ +---- +$ podman exec -ti che-docs bash +---- + +. To validate links, run: + ---- -$ bash ./tools/newtopic.sh +$ htmltest ---- -. To validate the compliance of an Asciidoc file with Modular Documentation standards, execute following command from a `+bash+` terminal, from the root directory of the project: +. To validate language on changed files, run: + ---- -$ bash ./tools/test-adoc.sh +$ ./tools/validate_language_changes.sh ---- -. To validate compliance of a file with the style guide, execute following command in a terminal, from the root directory of the project: +. To create a new topic using templates, run following command: + ---- -$ vale " +$ ./tools/newtopic.sh ---- -. To validate links, execute following command in a terminal, from the root directory of the project: +. To validate the compliance of an AsciiDoc file with Modular Documentation standards, run: + ---- -$ ./tools/linkchecker.sh +$ ./tools/test-adoc.sh ---- diff --git a/Dockerfile b/Dockerfile index 29dd0a4b08..4110db152d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -9,19 +9,41 @@ # Red Hat, Inc. - initial implementation # -FROM golang:1.15.6-alpine3.12 as vale-builder -WORKDIR /vale -RUN wget -qO- https://github.com/errata-ai/vale/archive/v2.8.0.tar.gz | tar --strip-components=1 -zxvf - -RUN export ARCH="$(uname -m)" && if [[ ${ARCH} == "x86_64" ]]; then export ARCH="amd64"; elif [[ ${ARCH} == "aarch64" ]]; then export ARCH="arm64"; fi && \ - GOOS=linux GOARCH=${ARCH} CGO_ENABLED=0 go build -tags closed -o bin/vale ./cmd/vale +FROM docker.io/library/rust:1.51-alpine3.13 as newdoc-builder +RUN apk add --no-cache --update musl-dev \ + && cargo install newdoc + +FROM docker.io/library/golang:1.15-alpine3.13 as htmltest-builder +WORKDIR /htmltest +ARG HTMLTEST_VERSION=0.15.0 +RUN wget -qO- https://github.com/wjdp/htmltest/archive/refs/tags/v${HTMLTEST_VERSION}.tar.gz | tar --strip-components=1 -zxvf - \ + && export ARCH="$(uname -m)" \ + && if [[ ${ARCH} == "x86_64" ]]; \ + then export ARCH="amd64"; \ + elif [[ ${ARCH} == "aarch64" ]]; \ + then export ARCH="arm64"; \ + fi \ + && GOOS=linux GOARCH=${ARCH} CGO_ENABLED=0 go build -tags closed -ldflags "-X main.date=`date -u +%Y-%m-%dT%H:%M:%SZ` -X main.version=${HTMLTEST_VERSION}" -o bin/htmltest . \ + && /htmltest/bin/htmltest --version -FROM rust:1.49.0-alpine3.12 as newdoc-builder -RUN cargo install newdoc +FROM docker.io/library/golang:1.17-alpine3.13 as vale-builder +WORKDIR /vale +ARG VALE_VERSION=2.12.1 +RUN wget -qO- https://github.com/errata-ai/vale/archive/v${VALE_VERSION}.tar.gz | tar --strip-components=1 -zxvf - \ + && export ARCH="$(uname -m)" \ + && if [[ ${ARCH} == "x86_64" ]]; \ + then export ARCH="amd64"; \ + elif [[ ${ARCH} == "aarch64" ]]; \ + then export ARCH="arm64"; \ + fi \ + && GOOS=linux GOARCH=${ARCH} CGO_ENABLED=0 go build -tags closed -ldflags "-X main.date=`date -u +%Y-%m-%dT%H:%M:%SZ` -X main.version=${VALE_VERSION}" -o bin/vale ./cmd/vale \ + && /vale/bin/vale --version -FROM alpine:3.13 +FROM docker.io/library/alpine:3.13 COPY --from=newdoc-builder /usr/local/cargo/bin/newdoc /usr/local/bin/newdoc COPY --from=vale-builder /vale/bin/vale /usr/local/bin/vale +COPY --from=htmltest-builder /htmltest/bin/htmltest /usr/local/bin/htmltest EXPOSE 4000 EXPOSE 35729 @@ -37,21 +59,24 @@ LABEL description="Tools to build Eclipse Che documentation: antora, asciidoctor summary="Tools to build Eclipse Che documentation" \ URL="quay.io/eclipse/che-docs" \ vendor="Eclipse Che Documentation Team" \ - version="2021.1" + version="2021.11" RUN apk add --no-cache --update \ bash \ curl \ findutils \ git \ + grep \ jq \ nodejs \ + perl \ py3-pip \ py3-wheel \ shellcheck \ tar \ + xmlstarlet \ yarn \ - && pip3 install --no-cache-dir --no-input jinja2-cli linkchecker yq \ + && pip3 install --no-cache-dir --no-input diagrams jinja2-cli yq \ && yarnpkg global add --ignore-optional --non-interactive @antora/cli@latest @antora/site-generator-default@latest asciidoctor gulp gulp-connect \ && rm -rf $(yarnpkg cache dir)/* \ && rm -rf /tmp/* \ @@ -61,12 +86,13 @@ RUN apk add --no-cache --update \ && curl --version \ && git --version \ && gulp --version \ + && htmltest --version \ && jinja2 --version \ && jq --version \ && linkchecker --version \ + && newdoc --version \ && vale -v \ - && yq --version \ - && newdoc --version + && yq --version VOLUME /projects WORKDIR /projects diff --git a/Jenkinsfile b/Jenkinsfile deleted file mode 100644 index 953d7495cd..0000000000 --- a/Jenkinsfile +++ /dev/null @@ -1,130 +0,0 @@ -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" - - name: che-docs - image: quay.io/eclipse/che-docs - command: - - cat - tty: true - volumes: - - configMap: - name: known-hosts - name: volume-known-hosts -""" - } - } - - environment { - PROJECT_NAME = "che" - PROJECT_BOT_NAME = "CHE Bot" - CI = true - } - - triggers { pollSCM('H/10 * * * *') - - } - - options { - buildDiscarder(logRotator(numToKeepStr: '5')) - checkoutToSubdirectory('che-docs') - timeout(time: 15, unit: 'MINUTES') - } - - stages { - - stage('Checkout www repo (master)') { - when { - branch 'master' - beforeAgent true - } - steps { - milestone 1 - container('jnlp') { - dir('www') { - sshagent(['git.eclipse.org-bot-ssh']) { - sh ''' - GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no" git clone ssh://genie.${PROJECT_NAME}@git.eclipse.org:29418/www.eclipse.org/${PROJECT_NAME}.git . - git checkout master - ''' - } - } - } - milestone 2 - } - } - - stage('Build che-docs website') { - steps { - milestone 21 - container('che-docs') { - dir('che-docs') { - sh './tools/environment_docs_gen.sh' - sh 'CI=true antora generate antora-playbook.yml --stacktrace' - } - } - milestone 22 - } - } - - stage('Push to www repo (master)') { - when { - branch 'master' - beforeAgent true - } - steps { - milestone 41 - sh 'ls -la' - dir('www') { - sshagent(['git.eclipse.org-bot-ssh']) { - sh ''' - cd "${WEBSITE}" - 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}" - export DOC_COMMIT_MSG=$(git log --oneline --format=%B -n 1 HEAD | tail -1) - 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 - ''' - } - } - milestone 42 - } - } - - } - - post { - always { - archiveArtifacts artifacts: 'che-docs/build/**', fingerprint: true - } - } - -} - - diff --git a/README.md b/README.md index cea9634c25..aaccb331f9 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ # Eclipse Che documentation project -[![Contribute](https://www.eclipse.org/che/contribute.svg)](https://che.openshift.io/f?url=https://github.com/eclipse/che-docs) +[![Contribute](https://www.eclipse.org/che/contribute.svg)](https://workspaces.openshift.com/f?url=https://github.com/eclipse/che-docs) This repository contains sources for the [documentation for Eclipse Che](https://www.eclipse.org/che/docs/). To contribute to the documentation, see the [Contribution guide](CONTRIBUTING.adoc). We love pull requests and appreciate contributions that make docs more helpful for users. To ask a question, [file an issue](https://github.com/eclipse/che/issues/new?labels=area/doc,kind/question). To learn more about the Eclipse Che project, see the [Eclipse Che repository on GitHub](https://github.com/eclipse/che). - diff --git a/RELEASE.md b/RELEASE.md index d81829653c..76f0ccfcbf 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,22 +1,3 @@ -# Eclipse Che release process +# Eclipse Che Docs release -##### 1. Create branch for release preparation and next bugfixes: -* `git branch {branchname} #e.g 7.7.x` -* `git push --set-upstream origin {branchname}` -##### 2. Create PR for switch master to the next development version : -* `git branch set_next_version_in_master_{next_version} #e.g 7.8.0-SNAPSHOT` -* `mvn versions:set versions:commit -DnewVersion=${next_version}` -* Update parent version : `mvn versions:update-parent versions:commit -DallowSnapshots=true -DparentVersion={next_version}` -* `git push --set-upstream origin set_next_version_in_master_{next_version}` -* Create PR -##### 3. Merge branch to the `release` branch and push changes, release process will start by webhook: -* `git checkout release` -* `git merge -X theirs {branchname}` -* `git push -f` -##### 4. Close/release staging repository on Nexus - https://oss.sonatype.org/#stagingRepositories - - > **Note:** For bugfix release procedure will be similar except creating new branch on first step and update version in master branch - -# Script -`make-release.sh` performs the first 3 steps. Release to Nexus is still a manual process for now. +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 new file mode 100644 index 0000000000..a37f8c7381 --- /dev/null +++ b/antora-playbook-for-development.yml @@ -0,0 +1,28 @@ +--- +# Use this Antora Playbook for development, to build current state in HEAD. +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: 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}" +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-playbook.yml b/antora-playbook.yml deleted file mode 100644 index dcccae7609..0000000000 --- a/antora-playbook.yml +++ /dev/null @@ -1,119 +0,0 @@ ---- -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: HEAD - edit_url: "https://github.com/eclipse/che-docs/edit/master/{path}" -output: - destinations: - - provider: fs - clean: true - path: build/site - - provider: archive - path: build/site.zip -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 -asciidoc: - attributes: - # for antora - context: che - experimental: "" - favicon: favicon.png - icons: font - # for the project - broker-ver: v3.4.0 - building-a-custom-devfile-registry: xref:end-user-guide:making-a-workspace-portable-using-a-devfile.adoc[] - 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 - identity-provider-docs-url: https://www.keycloak.org/docs/ - identity-provider-image-url: quay.io/eclipse/che-keycloak - identity-provider-url: https://www.keycloak.org/ - identity-provider-version: "6.0" - identity-provider: Keycloak - identity-provider-id: keycloak - image-puller-cr-name: KubernetesImagePuller - image-puller-deployment-name: kubernetes-image-puller - image-puller-image-tag: latest - image-puller-image-name: quay.io/eclipse/kubernetes-image-puller - image-puller-images: "java11-maven=quay.io/eclipse/che-java11-maven:nightly;che-theia=quay.io/eclipse/che-theia:next;java-plugin-runner=eclipse/che-remote-plugin-runner-java8:latest;" - image-puller-operator-name: Kubernetes Image Puller Operator - image-puller-name: Kubernetes Image Puller - image-puller-name-short: Image Puller - image-puller-serviceaccount-name: k8s-image-puller - 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/6.0//server_admin/#github" - link-identity-provider-oidc: "https://www.keycloak.org/docs/6.0/server_admin/#_oidc" - link-identity-provider-saml: "https://www.keycloak.org/docs/6.0/server_admin/#saml-v2-0-identity-providers" - link-installing-an-instance: xref:installation-guide:installing-che.adoc[] - link-postgres-dockerfile-location: https://github.com/eclipse/che/tree/master/dockerfiles/postgres - link-server-identity-provider-dockerfile-location: https://github.com/eclipse/che/tree/master/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[] - namespace: namespace # In context: API namespace - nodejs-stack: nodejs - oc4-ver: 4.6 - ocp: OpenShift Container Platform - ocp3-ver: 3.11 - ocp4-ver: 4.6 - orch-cli: kubectl - orch-cli-link: link:https://kubernetes.io/docs/reference/kubectl/overview/[Overview of kubectl] - platforms-cli: "`kubectl` or `oc`" - platforms-ingress: Kubernetes Ingress or OpenShift Route - platforms-name: Kubernetes or OpenShift - platforms-namespace: Kubernetes namespace or OpenShift project - orch-name: Kubernetes - orch-namespace: namespace # In context: orch-name orch-namespace - osd: OpenShift Dedicated - postgresql-image-url: quay.io/eclipse/che-postgres - prod-checluster: eclipse-che - prod-cli: chectl - prod-deployment: che - prod-home: /home/user - prod-host: che-host - prod-id-short: che - prod-id: eclipse-che - prod-namespace: eclipse-che - prod-operator: che-operator - prod-operator-image-name: che-operator - prod-prev-ver-major: 6 - prod-prev-ver: 7.24 - prod-short: Che - prod-upstream: Eclipse{nbsp}Che - prod-url-secure: \https://che-host - prod-url: \https://che-host:che-port - prod-ver-major: 7 - prod-ver: 7.25 - prod-ver-patch: 7.25.0 - prod-docs-url: https://www.eclipse.org/che/docs - 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/antora.yml b/antora.yml index 2932a9b3e2..af0b3aad2e 100644 --- a/antora.yml +++ b/antora.yml @@ -1,8 +1,8 @@ --- -name: che-7 +name: docs title: Documentation -version: master -display_version: master +version: next +display_version: next start_page: overview:introduction-to-eclipse-che.adoc nav: - modules/overview/nav.adoc @@ -13,4 +13,98 @@ nav: - modules/contributor-guide/nav.adoc - modules/extensions/nav.adoc - modules/glossary/nav.adoc - +asciidoc: + attributes: + # for antora + context: che + experimental: "" + favicon: favicon.png + 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 + identity-provider-docs-url: https://www.keycloak.org/docs/ + identity-provider-id: keycloak + identity-provider-image-url: quay.io/eclipse/che-keycloak + identity-provider-url: https://www.keycloak.org/ + identity-provider-version: "15.0" + identity-provider: Keycloak + image-puller-cr-name: KubernetesImagePuller + image-puller-deployment-id: kubernetes-image-puller-operator + image-puller-deployment-name: kubernetes-image-puller + image-puller-image-name: quay.io/eclipse/kubernetes-image-puller + image-puller-image-tag: latest + image-puller-images: "java11-maven=quay.io/eclipse/che-java11-maven:nightly;che-theia=quay.io/eclipse/che-theia:next;java-plugin-runner=eclipse/che-remote-plugin-runner-java8:latest;" + image-puller-name-short: Image Puller + image-puller-name: Kubernetes Image Puller + image-puller-namespace: k8s-image-puller + image-puller-operator-id: kubernetes-image-puller-operator + 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" + 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-oidc-issuer: link:https://dexidp.io/[Dex] + 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 + orch-ingress: Kubernetes Ingress + orch-name: Kubernetes + orch-namespace: namespace # In context: orch-name orch-namespace + osd: OpenShift Dedicated + platforms-cli: "`kubectl` or `oc`" + platforms-identity-provider: "Identity Provider (Keycloak or RH-SSO)" + platforms-ingress: Kubernetes Ingress or OpenShift Route + platforms-name: Kubernetes or OpenShift + platforms-namespace: Kubernetes namespace or OpenShift project + postgresql-image-url: quay.io/eclipse/che-postgres + prod-checluster: eclipse-che + prod-cli: chectl + prod-deployment: che + prod-docs-url: https://www.eclipse.org/che/docs + prod-home: /home/user + prod-host: che-host + prod-id-short: che + prod-id: eclipse-che + prod-namespace: eclipse-che + prod-operator-image-name: che-operator + prod-operator: che-operator + prod-prev-ver-major: "6" + prod-prev-ver: "7.40" + prod-short: Che + prod-upstream: Eclipse{nbsp}Che + prod-url: https://che-host:che-port + prod-ver-major: "7" + prod-ver-patch: "7.41.0" + prod-ver: "7.41" + 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/code_review_checklist.adoc b/code_review_checklist.adoc new file mode 100644 index 0000000000..13ea87ccae --- /dev/null +++ b/code_review_checklist.adoc @@ -0,0 +1,44 @@ +# Pull request review checklist for committers and reviewers +:toc: auto + +The reviewer validates the content of a pull request with this checklist. + +## Automated validation steps + +These automated steps block the pull request merge. + +* [ ] *`Build and validate PR / link checker (pull_request)`* is successful +** [ ] *`Build using Antora`* step is successful: documentation is building without warnings, and all AsciiDoc attributes have a definition. +** [ ] *`Validate links using htmltest`* step is successful: internal and external links are valid. +** [ ] *`Validate language on files added or modified`* step is successful and reports no vale errors: basic language validation, no major deviations from link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[IBM Style Guide] and link:https://redhat-documentation.github.io/supplementary-style-guide/[Supplementary Style Guide], and project specific language rules. +* [ ] *`eclipsefdn/eca`* is successful: all contributors have signed the Eclipse Contributor Agreement (ECA). + +## Non automated validation steps + +The author and the reviewers validate the content of a pull request with this additional checklist: + +* Any procedure: +** [ ] Successfully tested. +* Any page or link rename: +** [ ] The page contains a redirection for the previous URL. +** Propagate the URL change in: +*** [ ] Dashboard [default branding data](https://github.com/eclipse-che/che-dashboard/blob/main/src/services/bootstrap/branding.constant.ts) +*** [ ] Chectl [constants.ts](https://github.com/che-incubator/chectl/blob/master/src/constants.ts) +* [ ] Builds on https://workspaces.openshift.com[Eclipse Che hosted by Red Hat]. +* [ ] *`Validate language on files added or modified`* step reports no vale warnings. + +## In depth language review checklist + +The technical writer reviewers validate the language with this additional in depth checklist. We do recognize the subjectivity of some of these objectives. + +- [ ] Content is appropriate for the intended audience. +- [ ] Downstream friendly: correct use of attributes, `ifdef` statements, examples. +- [ ] Effective titles. +- [ ] Follows modularization guidelines. See: link:https://redhat-documentation.github.io/modular-docs/[Modular Documentation Reference Guide]. +- [ ] Follows the principles of minimalism. See: link:https://docs.google.com/presentation/d/1Yeql9FrRBgKU-QlRU-nblPJ9pfZKgoKcU8SW6SQ_UqI/edit#slide=id.g1f4790d380_2_257[The Wisdom of Crowds slides], link:https://youtu.be/s3Em8QSXyn8[The Wisdom of Crowds video], link:https://www.nngroup.com/articles/chunking/[Chunking]. +- [ ] Information is clear, valuable, and concise, no ambiguity. +- [ ] Language is consistent with the rest of the docs. +- [ ] Language is compliant with link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[IBM Style Guide] and link:https://redhat-documentation.github.io/supplementary-style-guide/[Supplementary Style Guide] rules not implemented in vale. +- [ ] The information flow is logical. +- [ ] Uses screenshot and other visuals when required. +- [ ] Uses verification steps when necessary. diff --git a/devfile.yaml b/devfile.yaml index 8a64089b95..22bce337f5 100644 --- a/devfile.yaml +++ b/devfile.yaml @@ -20,23 +20,44 @@ components: - name: Open-Preview-server port: 4000 attributes: - path: /che-7/overview/introduction-to-eclipse-che/ - - id: testthedocs/vale/latest - type: chePlugin + 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 + preferences: + vale.core.useCLI: true - id: ms-vscode/vscode-github-pullrequest/latest type: chePlugin - - id: joaompinto/asciidoctor-vscode/latest - type: chePlugin - - id: timonwong/shellcheck/latest - type: chePlugin + - type: chePlugin + reference: https://che-plugin-registry-main.surge.sh/v3/plugins/joaompinto/asciidoctor-vscode/latest/meta.yaml + alias: asciidoctor-vscode + - type: chePlugin + reference: https://che-plugin-registry-main.surge.sh/v3/plugins/timonwong/shellcheck/latest/meta.yaml + alias: shellcheck + - type: chePlugin + id: redhat/vscode-yaml/latest + - type: chePlugin + id: redhat/vscode-xml/latest + - type: chePlugin + id: vscode/typescript-language-features/latest + - type: chePlugin + id: redhat/java/latest + - type: chePlugin + id: golang/go/latest commands: - - name: Generate reference tables + - name: Generate reference tables for environment variables actions: - type: exec component: che-docs workdir: /projects/che-docs command: bash tools/environment_docs_gen.sh + - name: Generate reference tables for CheCluster + actions: + - type: exec + component: che-docs + workdir: /projects/che-docs + command: bash tools/checluster_docs_gen.sh - name: Start preview server actions: - type: exec @@ -63,7 +84,13 @@ commands: - type: exec component: che-docs workdir: /projects/che-docs - command: sh tools/linkchecker.sh + command: htmltest + - name: Validate language changes + actions: + - type: exec + component: che-docs + workdir: /projects/che-docs + command: sh tools/validate_language_changes.sh - name: Detect unused images actions: - type: exec diff --git a/gulpfile.js b/gulpfile.js index 47022cb178..a264bd29e5 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -1,13 +1,15 @@ 'use strict' const connect = require('gulp-connect') +const util = require('util'); +const exec = util.promisify(require('child_process').exec); const fs = require('fs') const generator = require('@antora/site-generator-default') const { reload: livereload } = process.env.LIVERELOAD === 'true' ? require('gulp-connect') : {} -const { series, src, watch } = require('gulp') +const { parallel, series, src, watch } = require('gulp') const yaml = require('js-yaml') -const playbookFilename = 'antora-playbook.yml' +const playbookFilename = 'antora-playbook-for-development.yml' const playbook = yaml.safeLoad(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 } @@ -18,8 +20,7 @@ const watchPatterns = playbook.content.sources.filter((source) => !source.url.in return accum }, []) - -function generate (done) { +function generate(done) { generator(antoraArgs, process.env) .then(() => done()) .catch((err) => { @@ -28,12 +29,73 @@ function generate (done) { }) } -function serve (done) { +async function serve(done) { connect.server(serverConfig, function () { this.server.on('close', done) - watch(watchPatterns, generate) + watch(watchPatterns, series(generate, testlang, testhtml)) if (livereload) watch(this.root).on('change', (filepath) => src(filepath, { read: false }).pipe(livereload())) }) } -module.exports = { serve, generate, default: series(generate, serve) } +async function checluster_docs_gen() { + // Report script errors but don't make gulp fail. + try { + const { stdout, stderr } = await exec('tools/checluster_docs_gen.sh') + console.log(stdout); + console.error(stderr); + } + catch (error) { + console.log(error.stdout); + console.log(error.stderr); + return; + } +} + +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); + } + catch (error) { + console.log(error.stdout); + console.log(error.stderr); + return; + } +} + +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); + } + catch (error) { + console.log(error.stdout); + console.log(error.stderr); + return; + } +} + +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); + } + catch (error) { + console.log(error.stdout); + console.log(error.stderr); + return; + } +} + +exports.default = series( + parallel(checluster_docs_gen, environment_docs_gen), + generate, + serve, + parallel(testlang, testhtml) +); diff --git a/linkcheckerrc b/linkcheckerrc index 8e843b778d..e6a6e3498a 100644 --- a/linkcheckerrc +++ b/linkcheckerrc @@ -37,11 +37,12 @@ ignorewarnings=url-rate-limited # Multiline option. Each line has to be indented for that to work. # Lines starting with a hash (#) will be ignored, though they must still be indented. ignore= - file:///* + file:///projects* http://che.aws.my-ide.cloud - https://che.openshift.io/* https://console.aws.amazon.com/* https://github.com/eclipse/che-devfile-registry/blob/master/devfiles/quarkus-command-mode/devfile.yaml#L* https://maven.apache.org/settings.html* https://github.com/eclipse/che-docs/edit/master/* + https://workspaces.openshift.com/* https://www.eclipse.org/che/docs/che-7/* + https://che-plugin-registry.openshift.io/* diff --git a/make-release.sh b/make-release.sh index e74f7e1985..21232febc5 100755 --- a/make-release.sh +++ b/make-release.sh @@ -1,18 +1,61 @@ #!/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. -# Used to create branch/tag, update versions in pom.xml -# and and trigger release by force pushing changes to the release branch +# 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 +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'|'--no-commit') docommit=0; shift 0;; + '-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 @@ -24,139 +67,180 @@ Usage: $0 --version [VERSION TO RELEASE] Example: $0 --version 7.25.2 -t Options: - --trigger-release, -t tag this release - --no-commit, -n do not commit changes to branches + --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 -else # clone into a temp folder so we don't collide with local changes to this script - cd /tmp/ && tmpdir=tmp-${0##*/}-$VERSION && git clone $REPO $tmpdir && cd /tmp/$tmpdir fi -# where in other repos we have a VERSION file, here we have an antora-playbook.yml file which contains some 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 -playbookfile=antora-playbook.yml -updateYaml() { - NEWVERSION=${1} - echo "[INFO] update $playbookfile with prod-ver = $NEWVERSION" - - [[ $NEWVERSION =~ ^([0-9]+)\.([0-9]+)\.([0-9]+) ]] && BASE1="${BASH_REMATCH[1]}"; BASE2="${BASH_REMATCH[2]}"; # for VERSION=7.25.2, get BASE1=7; BASE2=25 - # prod-ver should never go down, only up - OLDVERSION=$(cat $playbookfile | yq -r '.asciidoc.attributes."prod-ver-patch"') # existing prod-ver-patch version 7.yy.z - VERSIONS="${OLDVERSION} ${NEWVERSION}" - VERSIONS_SORTED="$(echo $VERSIONS | tr " " "\n" | sort -V | tr "\n" " ")" - # echo "Compare '$VERSIONS_SORTED' with '$VERSIONS '" - if [[ "${VERSIONS_SORTED}" != "${VERSIONS} " ]] || [[ "${OLDVERSION}" == "${NEWVERSION}" ]]; then # note trailing space after VERSIONS is required! - echo "[WARN] Existing prod-ver ${OLDVERSION} is greater or equal than planned update to ${NEWVERSION}. Version should not go backwards, so nothing to do!" - else - replaceFieldSed $playbookfile 'prod-ver' "${BASE1}.${BASE2}" - replaceFieldSed $playbookfile 'prod-ver-patch' $NEWVERSION - # set prod-prev-ver = 7.y-1 - (( BASE2=BASE2-1 )) - replaceFieldSed $playbookfile 'prod-prev-ver' "${BASE1}.${BASE2}" +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 } -replaceFieldSed() -{ - YAMLFILE=$1 - updateName=$2 - updateVal=$3 - # echo "[INFO] * ${YAMLFILE} ==> ${updateName}: ${updateVal}" - sed -i ${YAMLFILE} -r -e "s#( $updateName: ).+#\1${updateVal}#" +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 } -bump_version() { - CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) - - NEXTVERSION=$1 - BUMP_BRANCH=$2 - - git checkout ${BUMP_BRANCH} - - echo "[INFO] Update project version to ${NEXTVERSION}" - updateYaml ${NEXTVERSION} - - if [[ ${docommit} -eq 1 ]]; then - COMMIT_MSG="[release] Bump to ${NEXTVERSION} in ${BUMP_BRANCH}" - git commit -s -m "${COMMIT_MSG}" $playbookfile - git pull origin "${BUMP_BRANCH}" - - PUSH_TRY="$(git push origin "${BUMP_BRANCH}")" - # shellcheck disable=SC2181 - if [[ $? -gt 0 ]] || [[ $PUSH_TRY == *"protected branch hook declined"* ]] || [[ $PUSH_TRY == *"Protected branch update"* ]]; then - PR_BRANCH=pr-${BUMP_BRANCH}-to-${NEXTVERSION} - # create pull request for master branch, as branch is restricted - git branch "${PR_BRANCH}" - git checkout "${PR_BRANCH}" - git pull origin "${PR_BRANCH}" - git push origin "${PR_BRANCH}" - lastCommitComment="$(git log -1 --pretty=%B)" - hub pull-request -f -m "${lastCommitComment} -${lastCommitComment}" -b "${BUMP_BRANCH}" -h "${PR_BRANCH}" - fi +gitCommit() { + if [[ ${DOCOMMIT} -eq 1 ]]; then + git add "antora*.yml" "modules/installation-guide/examples/*" + git commit -s -m "release: Bump version to ${VERSION}" fi - git checkout ${CURRENT_BRANCH} } -# derive branch from version -BRANCH=${VERSION%.*}.x +gitPush() { + if [[ ${DOPUSH} -eq 1 ]]; then + git pull origin "${TARGET_BRANCH}" || true + git push origin "${TARGET_BRANCH}" + fi +} -# if doing a .0 release, use master; if doing a .z release, use $BRANCH -if [[ ${VERSION} == *".0" ]]; then - BASEBRANCH="master" -else - BASEBRANCH="${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 +} -# get sources from ${BASEBRANCH} branch -git fetch origin "${BASEBRANCH}":"${BASEBRANCH}" -git checkout "${BASEBRANCH}" +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 +} -EXISTING_BRANCH=0 -# create new branch off ${BASEBRANCH} (or check out latest commits if branch already exists), then push to origin -if [[ "${BASEBRANCH}" != "${BRANCH}" ]]; then +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." +} - # note: if branch already exists, do not recreate it! - if [[ $(git branch "${BRANCH}" 2>&1 || true) == *"already exists"* ]]; then - EXISTING_BRANCH=1 +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}." +} - if [[ ${EXISTING_BRANCH} -eq 0 ]]; then - git push origin "${BRANCH}" - fi -fi +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}#" +} -# now update ${BASEBRANCH} to the new version -git fetch origin "${BASEBRANCH}":"${BASEBRANCH}" -git checkout "${BASEBRANCH}" - -if [[ "${BASEBRANCH}" != "${BRANCH}" ]]; then - # bump the y digit, if it is a major release - [[ $BRANCH =~ ^([0-9]+)\.([0-9]+)\.x ]] && BASE=${BASH_REMATCH[1]}; NEXT=${BASH_REMATCH[2]}; # for BRANCH=7.25.x, get BASE=7, NEXT=25 [DO NOT BUMP] - NEXTVERSION_Y="${BASE}.${NEXT}.0" - bump_version ${NEXTVERSION_Y} ${BASEBRANCH} - bump_version ${NEXTVERSION_Y} ${BRANCH} -else - # bump the z digit - [[ $VERSION =~ ^([0-9]+)\.([0-9]+)\.([0-9]+) ]] && BASE="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}"; NEXT="${BASH_REMATCH[3]}"; # for VERSION=7.25.2, get BASE=7.25, NEXT=2 [DO NOT BUMP] - NEXTVERSION_Z="${BASE}.${NEXT}" - bump_version ${NEXTVERSION_Z} ${BASEBRANCH} - bump_version ${NEXTVERSION_Z} ${BRANCH} -fi +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}.." +} -if [[ $TAG_RELEASE -eq 1 ]]; then - git checkout "${BRANCH}" && git pull origin "${BRANCH}" - git tag "${VERSION}" - git push origin "${VERSION}" || true -fi +# 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" -# cleanup -rm -fr /tmp/$tmpdir +if [[ ${USE_TMP_DIR} -eq 1 ]]; then + rm -fr "/tmp/${TMPDIR}" +fi diff --git a/modules/administration-guide/examples/assembly_che-building-custom-registry-images.adoc b/modules/administration-guide/examples/assembly_che-building-custom-registry-images.adoc deleted file mode 100644 index 9d99068a59..0000000000 --- a/modules/administration-guide/examples/assembly_che-building-custom-registry-images.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="building-custom-registry-images_{context}"] -= Building custom registry images - -:registry-mode: custom -:registry-mode-name: a custom -:registry-id: devfile -:registry-name: devfile - -include::installation-guide:partial$proc_building-a-registry-image.adoc[leveloffset=+1] - - -:registry-id: plugin -:registry-name: plug-in - -include::installation-guide:partial$proc_building-a-registry-image.adoc[leveloffset=+1] - diff --git a/modules/administration-guide/examples/prometheus-config.adoc b/modules/administration-guide/examples/prometheus-config.adoc index eb3f57039c..1df67b25b1 100644 --- a/modules/administration-guide/examples/prometheus-config.adoc +++ b/modules/administration-guide/examples/prometheus-config.adoc @@ -1,3 +1,5 @@ +[source,yaml,subs="+attributes"] +---- apiVersion: v1 kind: ConfigMap metadata: @@ -11,3 +13,5 @@ data: - job_name: 'che' static_configs: - targets: ['[che-host]:8087'] <4> +---- + diff --git a/modules/administration-guide/examples/snip_a-che-workspace-example.adoc b/modules/administration-guide/examples/snip_a-che-workspace-example.adoc new file mode 100644 index 0000000000..75f92a7638 --- /dev/null +++ b/modules/administration-guide/examples/snip_a-che-workspace-example.adoc @@ -0,0 +1,24 @@ +[source,yaml] +---- +apiVersion: 1.0.0 +metadata: + generateName: nodejs-web-app- +projects: + - + name: react-web-app + source: + type: git + location: "https://github.com/che-samples/react-web-app" +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 +---- diff --git a/modules/administration-guide/examples/snip_bitbucket-personal-access-token-secret.adoc b/modules/administration-guide/examples/snip_bitbucket-personal-access-token-secret.adoc index 50c4b1553e..f450550cda 100644 --- a/modules/administration-guide/examples/snip_bitbucket-personal-access-token-secret.adoc +++ b/modules/administration-guide/examples/snip_bitbucket-personal-access-token-secret.adoc @@ -1,15 +1,19 @@ -apiVersion: v1 +[source,yaml,subs="+quotes,+attributes"] +---- kind: Secret +apiVersion: v1 metadata: - name: bitbucket-personal-access-token-secret labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: scm-personal-access-token + app.kubernetes.io/component: 'scm-personal-access-token' <1> + app.kubernetes.io/part-of: che.eclipse.org 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://bitbucket.apps.cluster-example.com' + che.eclipse.org/che-userid: '____' <2> + che.eclipse.org/scm-userid: '____' <3> + che.eclipse.org/scm-username: '____' <4> + che.eclipse.org/scm-url: '____' <5> + che.eclipse.org/expired-after: '-1' <6> + name: bitbucket-personal-access-token-secret + data: - token: TlRnNE1UazRORFl5TWpNeU9sMTI1aDFFT2dRbXBlTUYvbmhiLzNQUC9hT08= \ No newline at end of file + token: '____' <7> +---- \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-architecture-overview-with-devworkspace-additional-resources.adoc b/modules/administration-guide/examples/snip_che-architecture-overview-with-devworkspace-additional-resources.adoc new file mode 100644 index 0000000000..14ec7e0c06 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-architecture-overview-with-devworkspace-additional-resources.adoc @@ -0,0 +1 @@ +* link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[Kubernetes documentation - Custom Resources] \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-build-a-custom-devfile-registry.adoc b/modules/administration-guide/examples/snip_che-build-a-custom-devfile-registry.adoc new file mode 100644 index 0000000000..3642e74699 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-build-a-custom-devfile-registry.adoc @@ -0,0 +1,6 @@ +[subs="+attributes,+quotes"] +---- +$ ./build.sh --organization __ \ + --registry __ \ + --tag __ +---- diff --git a/modules/administration-guide/examples/snip_che-build-a-custom-plug-in-registry.adoc b/modules/administration-guide/examples/snip_che-build-a-custom-plug-in-registry.adoc new file mode 100644 index 0000000000..3642e74699 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-build-a-custom-plug-in-registry.adoc @@ -0,0 +1,6 @@ +[subs="+attributes,+quotes"] +---- +$ ./build.sh --organization __ \ + --registry __ \ + --tag __ +---- diff --git a/modules/administration-guide/examples/snip_che-che-server-additional-resources.adoc b/modules/administration-guide/examples/snip_che-che-server-additional-resources.adoc new file mode 100644 index 0000000000..d7384de94c --- /dev/null +++ b/modules/administration-guide/examples/snip_che-che-server-additional-resources.adoc @@ -0,0 +1,2 @@ +* link:https://quay.io/repository/eclipse/che-server?tab=history[`quay.io/eclipse/che-server` container image] +* link:https://github.com/eclipse-che/che-server[{prod} server repository] \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-clone-the-devfile-registry-repository.adoc b/modules/administration-guide/examples/snip_che-clone-the-devfile-registry-repository.adoc new file mode 100644 index 0000000000..a79db8eccf --- /dev/null +++ b/modules/administration-guide/examples/snip_che-clone-the-devfile-registry-repository.adoc @@ -0,0 +1,6 @@ +[subs="+attributes,+quotes"] +---- +$ git clone git@github.com:eclipse/che-devfile-registry.git +$ cd che-devfile-registry +$ git checkout {prod-ver}.x +---- \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-clone-the-plug-in-registry-repository.adoc b/modules/administration-guide/examples/snip_che-clone-the-plug-in-registry-repository.adoc new file mode 100644 index 0000000000..f509612ff1 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-clone-the-plug-in-registry-repository.adoc @@ -0,0 +1,6 @@ +[subs="+attributes,+quotes"] +---- +$ git clone git@github.com:eclipse/che-plugin-registry.git +$ cd che-plugin-registry +$ git checkout {prod-ver}.x +---- \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-cloning-image-puller-project.adoc b/modules/administration-guide/examples/snip_che-cloning-image-puller-project.adoc index d365f5eda4..65194ac26a 100644 --- a/modules/administration-guide/examples/snip_che-cloning-image-puller-project.adoc +++ b/modules/administration-guide/examples/snip_che-cloning-image-puller-project.adoc @@ -1,4 +1,5 @@ +[subs="+attributes"] ---- -$ git clone https://github.com/che-incubator/kubernetes-image-puller -$ cd kubernetes-image-puller/deploy/openshift +$ git clone https://github.com/che-incubator/{image-puller-repository-name} +$ cd {image-puller-repository-name}/deploy/openshift ---- diff --git a/modules/administration-guide/examples/che-cluster-deployment-openshift-logs.adoc b/modules/administration-guide/examples/snip_che-cluster-deployment-openshift-logs.adoc similarity index 91% rename from modules/administration-guide/examples/che-cluster-deployment-openshift-logs.adoc rename to modules/administration-guide/examples/snip_che-cluster-deployment-openshift-logs.adoc index be08446d43..26545bd546 100644 --- a/modules/administration-guide/examples/che-cluster-deployment-openshift-logs.adoc +++ b/modules/administration-guide/examples/snip_che-cluster-deployment-openshift-logs.adoc @@ -1,3 +1,5 @@ +[options="nowrap",role="white-space-pre",subs="+quotes,+attributes"] +---- time="2019-07-12T09:48:29Z" level=info msg="Exec successfully completed" time="2019-07-12T09:48:29Z" level=info msg="Updating eclipse-che CR with status: provisioned with OpenShift identity provider: true" time="2019-07-12T09:48:29Z" level=info msg="Custom resource eclipse-che updated" @@ -7,3 +9,5 @@ time="2019-07-12T09:48:29Z" level=info msg="Creating a new object: Deployment, n time="2019-07-12T09:48:30Z" level=info msg="Updating eclipse-che CR with status: {prod-short} API: Unavailable" time="2019-07-12T09:48:30Z" level=info msg="Custom resource eclipse-che updated" time="2019-07-12T09:48:30Z" level=info msg="Waiting for deployment che. Default timeout: 420 seconds" +---- + diff --git a/modules/administration-guide/examples/snip_che-dashboard-additional-resources.adoc b/modules/administration-guide/examples/snip_che-dashboard-additional-resources.adoc new file mode 100644 index 0000000000..b6d998f998 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-dashboard-additional-resources.adoc @@ -0,0 +1,2 @@ +* link:https://quay.io/repository/eclipse/che-dashboard?tab=history[`quay.io/eclipse/che-dashboard` container image] +* link:https://github.com/eclipse-che/che-dashboard[{prod-short} Dashboard repository] diff --git a/modules/administration-guide/examples/snip_che-devfile-meta.adoc b/modules/administration-guide/examples/snip_che-devfile-meta.adoc index dcd24ce52d..564eac6298 100644 --- a/modules/administration-guide/examples/snip_che-devfile-meta.adoc +++ b/modules/administration-guide/examples/snip_che-devfile-meta.adoc @@ -1,5 +1,9 @@ +[source,yaml] +---- displayName: Rust description: Rust Stack with Rust 1.39 tags: ["Rust"] icon: https://www.eclipse.org/che/images/logo-eclipseche.svg globalMemoryLimit: 1686Mi +---- + diff --git a/modules/administration-guide/examples/snip_che-devfile-registry-additional-resources.adoc b/modules/administration-guide/examples/snip_che-devfile-registry-additional-resources.adoc new file mode 100644 index 0000000000..a760f93cd6 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-devfile-registry-additional-resources.adoc @@ -0,0 +1 @@ +* link:https://github.com/eclipse/che-devfile-registry[{prod-short} devfile registry repository] diff --git a/modules/administration-guide/examples/snip_che-devworkspace-additional-resources.adoc b/modules/administration-guide/examples/snip_che-devworkspace-additional-resources.adoc new file mode 100644 index 0000000000..eb18be23c3 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-devworkspace-additional-resources.adoc @@ -0,0 +1,2 @@ +* link:https://quay.io/repository/devfile/devworkspace-controller?tab=history[`quay.io/devfile/devworkspace-controller` container image] +* link:https://github.com/devfile/devworkspace-operator[{devworkspace} Operator repository] 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 index 88e95deec2..73e7c8789a 100644 --- 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 @@ -2,8 +2,9 @@ ==== [subs="+attributes,+quotes,+macros"] ---- -$ curl -sSLo- https://raw.githubusercontent.com/eclipse/che-operator/master/olm/eclipse-che-preview-kubernetes/deploy/olm-catalog/eclipse-che-preview-kubernetes/{prod-ver-patch}/eclipse-che-preview-kubernetes.v{prod-ver-patch}.clusterserviceversion.yaml | \ - yq -r '.spec.relatedImages[]' +$ 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 ---- ==== + @@ -11,7 +12,8 @@ $ curl -sSLo- https://raw.githubusercontent.com/eclipse/che-operator/master/olm/ ==== [subs="+attributes,+quotes,+macros"] ---- -$ curl -sSLo- https://raw.githubusercontent.com/eclipse/che-operator/master/olm/eclipse-che-preview-openshift/deploy/olm-catalog/eclipse-che-preview-openshift/{prod-ver-patch}/eclipse-che-preview-openshift.v{prod-ver-patch}.clusterserviceversion.yaml | \ - yq -r '.spec.relatedImages[]' +$ 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 ---- -==== \ No newline at end of file +==== diff --git a/modules/administration-guide/examples/snip_che-image-puller-dockerfile.adoc b/modules/administration-guide/examples/snip_che-image-puller-dockerfile.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/modules/administration-guide/examples/snip_che-images-incompatibles-with-image-puller.adoc b/modules/administration-guide/examples/snip_che-images-incompatibles-with-image-puller.adoc deleted file mode 100644 index d111c6a2aa..0000000000 --- a/modules/administration-guide/examples/snip_che-images-incompatibles-with-image-puller.adoc +++ /dev/null @@ -1,5 +0,0 @@ -.Images incompatibles with {image-puller-name-short}, missing the `sleep` command -==== -* `FROM scratch` images. -* `che-machine-exec` -==== \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-installing-image-puller-using-che-operator-prerequisites.adoc b/modules/administration-guide/examples/snip_che-installing-image-puller-using-che-operator-prerequisites.adoc new file mode 100644 index 0000000000..fe60f68450 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-installing-image-puller-using-che-operator-prerequisites.adoc @@ -0,0 +1 @@ +* Operator Lifecycle Manager and OperatorHub are available on the {platforms-name} instance. OpenShift provides them starting with version 4.2. \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-keycloak-additional-resources.adoc b/modules/administration-guide/examples/snip_che-keycloak-additional-resources.adoc new file mode 100644 index 0000000000..882bdcb43f --- /dev/null +++ b/modules/administration-guide/examples/snip_che-keycloak-additional-resources.adoc @@ -0,0 +1,2 @@ +* link:https://quay.io/repository/eclipse/che-keycloack?tab=history[`quay.io/eclipse/che-keycloak` container image] +* link:https://github.com/eclipse-che/che-server/tree/main/dockerfiles/keycloak[{prod-short} {identity-provider} repository] 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 new file mode 100644 index 0000000000..dbf90dd1ba --- /dev/null +++ b/modules/administration-guide/examples/snip_che-list-of-images-for-faster-workspace-start.adoc @@ -0,0 +1,5 @@ +* `che-theia` +* `che-theia-endpoint-runtime-binary` +* `che-machine-exec` +* `che-plugin-artifacts-broker` +* `che-plugin-metadata-broker` diff --git a/modules/administration-guide/examples/snip_che-memory-requirement-note.adoc b/modules/administration-guide/examples/snip_che-memory-requirement-note.adoc new file mode 100644 index 0000000000..a4547ee934 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-memory-requirement-note.adoc @@ -0,0 +1 @@ +// Intentionally keeping the file empty diff --git a/modules/administration-guide/examples/snip_che-plug-in-tree.adoc b/modules/administration-guide/examples/snip_che-plug-in-tree.adoc deleted file mode 100644 index e620b7206b..0000000000 --- a/modules/administration-guide/examples/snip_che-plug-in-tree.adoc +++ /dev/null @@ -1,15 +0,0 @@ -$ tree che-plugin-registry/v3/plugins/redhat/java/ -che-plugin-registry/v3/plugins/redhat/java/ -├── 0.38.0 -│   └── meta.yaml -├── 0.43.0 -│   └── meta.yaml -├── 0.45.0 -│   └── meta.yaml -├── 0.46.0 -│   └── meta.yaml -├── 0.50.0 -│   └── meta.yaml -└── latest.txt -$ cat che-plugin-registry/v3/plugins/redhat/java/latest.txt -0.50.0 diff --git a/modules/administration-guide/examples/snip_che-plugin-registry-build-output.adoc b/modules/administration-guide/examples/snip_che-plugin-registry-build-output.adoc new file mode 100644 index 0000000000..38144c4e2a --- /dev/null +++ b/modules/administration-guide/examples/snip_che-plugin-registry-build-output.adoc @@ -0,0 +1,12 @@ +. Observe the contents of `./{che-plugin-registry-directory}/v3/plugins/` present in the container after building the registry. All `meta.yaml` files resulting from a successful plug-ins registry build will be located here. ++ +[subs="+attributes,quotes"] +---- +./{che-plugin-registry-directory}/v3/plugins/ +├── __ +│   └── __ +│   ├── latest +│   │   └── meta.yaml +│   └── latest.txt +---- ++ \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-postgresql-additional-resources.adoc b/modules/administration-guide/examples/snip_che-postgresql-additional-resources.adoc new file mode 100644 index 0000000000..73941daa40 --- /dev/null +++ b/modules/administration-guide/examples/snip_che-postgresql-additional-resources.adoc @@ -0,0 +1,2 @@ +* link:https://quay.io/repository/eclipse/che-postgres?tab=history[`quay.io/eclipse/che-postgres` container image] +* link:https://github.com/eclipse-che/che-server/tree/main/dockerfiles/postgres[{prod-short} Postgres repository] diff --git a/modules/administration-guide/examples/snip_customizing-the-devfile-registry.adoc b/modules/administration-guide/examples/snip_customizing-the-devfile-registry.adoc deleted file mode 100644 index 87c8ac6b72..0000000000 --- a/modules/administration-guide/examples/snip_customizing-the-devfile-registry.adoc +++ /dev/null @@ -1,33 +0,0 @@ -. In the `./{che-devfile-registry-directory}/devfiles/` directory, create a subdirectory `____/` and add the `devfile.yaml` and `meta.yaml` files. -+ -.File organization for a devfile -[subs="+attributes,+quotes"] ----- -./{che-devfile-registry-directory}/devfiles/ -└── ____ - ├── 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:making-a-workspace-portable-using-a-devfile.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. -globalMemoryLimit, 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. -icon, Link to an `.svg` file that is displayed on the user dashboard. -tags, List of tags. Tags usually include the tools included in the stack. -|=== -+ -.Example devfile `meta.yaml` -==== -[source,yaml] ----- -include::example$snip_{project-context}-devfile-meta.adoc[] ----- -==== \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_customizing-the-plug-in-registry.adoc b/modules/administration-guide/examples/snip_customizing-the-plug-in-registry.adoc deleted file mode 100644 index c35981d202..0000000000 --- a/modules/administration-guide/examples/snip_customizing-the-plug-in-registry.adoc +++ /dev/null @@ -1,25 +0,0 @@ - . In the `./{che-plugin-registry-directory}/v3/plugins/` directory, create new directories `____/____/____/` and a `meta.yaml` file in the last directory. -+ -.File organization for a plugin -[subs="+attributes,+quotes"] ----- -./{che-plugin-registry-directory}/v3/plugins/ -├── __ -│   └── __ -│   ├── __ -│   │   └── meta.yaml -│   └── latest.txt ----- - -. Add valid content to the `meta.yaml` file. See: xref:end-user-guide:publishing-metadata-for-a-vs-code-extension.adoc[]. - -. Create a file named `latest.txt` with content the name of the latest `__` directory. -+ -.Example plug-in files tree -==== -[subs="+attributes"] ----- -include::example$snip_{project-context}-plug-in-tree.adoc[] ----- -==== - diff --git a/modules/administration-guide/examples/snip_using-devworkspace-warning.adoc b/modules/administration-guide/examples/snip_using-devworkspace-warning.adoc new file mode 100644 index 0000000000..65ab7e647f --- /dev/null +++ b/modules/administration-guide/examples/snip_using-devworkspace-warning.adoc @@ -0,0 +1,10 @@ +[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/administration-guide/images/architecture/che-architecture-with-che-server-engine.png b/modules/administration-guide/images/architecture/che-architecture-with-che-server-engine.png new file mode 100644 index 0000000000..6066c14103 Binary files /dev/null and b/modules/administration-guide/images/architecture/che-architecture-with-che-server-engine.png 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 new file mode 100644 index 0000000000..380d4d50ba --- /dev/null +++ b/modules/administration-guide/images/architecture/che-architecture-with-devworkspace.drawio @@ -0,0 +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==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=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/ diff --git a/modules/administration-guide/images/architecture/che-dashboard-interactions.png b/modules/administration-guide/images/architecture/che-dashboard-interactions.png new file mode 100644 index 0000000000..76332e435e Binary files /dev/null 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 new file mode 100644 index 0000000000..107bce3ec0 Binary files /dev/null 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 new file mode 100644 index 0000000000..e11a7bb91c Binary files /dev/null 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 new file mode 100644 index 0000000000..953d76179f Binary files /dev/null and b/modules/administration-guide/images/architecture/che-gateway-interactions.png differ diff --git a/modules/administration-guide/images/architecture/che-high-level.png b/modules/administration-guide/images/architecture/che-high-level.png deleted file mode 100644 index 1fce82841b..0000000000 Binary files a/modules/administration-guide/images/architecture/che-high-level.png and /dev/null 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 new file mode 100644 index 0000000000..9ec7675930 Binary files /dev/null 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 new file mode 100644 index 0000000000..77c4dd4b79 Binary files /dev/null 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 new file mode 100644 index 0000000000..1db96b51a4 Binary files /dev/null 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 new file mode 100644 index 0000000000..5f2a4355e6 Binary files /dev/null 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 new file mode 100644 index 0000000000..3a66b8666d Binary files /dev/null and b/modules/administration-guide/images/architecture/che-user-workspaces-interactions.png differ diff --git a/modules/administration-guide/images/architecture/workspace-components-with-dw.png b/modules/administration-guide/images/architecture/workspace-components-with-dw.png new file mode 100644 index 0000000000..aecab7ffec Binary files /dev/null and b/modules/administration-guide/images/architecture/workspace-components-with-dw.png 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/nav.adoc b/modules/administration-guide/nav.adoc index b9443c0e28..5dfa6206c7 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -1,8 +1,20 @@ .Administration Guide - -* xref:che-architecture-overview.adoc[] -** xref:che-workspace-controller.adoc[] -** xref:che-workspaces-architecture.adoc[] + +* xref: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:server-components.adoc[] +**** 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[] +*** xref:user-workspaces.adoc[] * xref:calculating-che-resource-requirements.adoc[] @@ -10,13 +22,6 @@ ** xref:building-custom-registry-images.adoc[] ** xref:running-custom-registries.adoc[] -* xref:managing-users.adoc[] -** xref:authenticating-users.adoc[] -** xref:authorizing-users.adoc[] -** xref:configuring-authorization.adoc[] -** xref:removing-user-data.adoc[] -** xref:authenticating-users-3rd-party-services.adoc[] - * xref:retrieving-che-logs.adoc[] ** xref:configuring-server-logging.adoc[] ** xref:viewing-kubernetes-events.adoc[] @@ -28,16 +33,42 @@ * xref:monitoring-che.adoc[] +* xref:monitoring-the-dev-workspace-operator.adoc[] + * xref:tracing-che.adoc[] * xref:backup-and-disaster-recovery.adoc[] -** xref:external-database-setup.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-on-kubernetes-using-the-operator.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:installing-image-puller-on-kubernetes-using-helm.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:configuring-minikube-github-authentication.adoc[] + +** xref:removing-user-data.adoc[] diff --git a/modules/administration-guide/pages/architecture-overview-with-che-server.adoc b/modules/administration-guide/pages/architecture-overview-with-che-server.adoc new file mode 100644 index 0000000000..c48fbe5e4b --- /dev/null +++ b/modules/administration-guide/pages/architecture-overview-with-che-server.adoc @@ -0,0 +1,6 @@ +[id="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 new file mode 100644 index 0000000000..6dc042c8d6 --- /dev/null +++ b/modules/administration-guide/pages/architecture-overview-with-devworkspace.adoc @@ -0,0 +1,7 @@ +[id="architecture-overview-with-devworkspace"] +// = Che architecture with {devworkspace} +:navtitle: {devworkspace} based +:keywords: administration-guide, 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 new file mode 100644 index 0000000000..17dbae963b --- /dev/null +++ b/modules/administration-guide/pages/architecture-overview.adoc @@ -0,0 +1,7 @@ +[id="architecture-overview"] +// = Che architecture overview +:navtitle: Architecture overview +:keywords: administration-guide, 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 + +include::partial$con_architecture-overview.adoc[] diff --git a/modules/administration-guide/pages/authenticating-users-3rd-party-services.adoc b/modules/administration-guide/pages/authenticating-users-3rd-party-services.adoc deleted file mode 100644 index cd51fb401b..0000000000 --- a/modules/administration-guide/pages/authenticating-users-3rd-party-services.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authenticating-users-3rd-party-services"] -// = Authenticating users on 3-rd party services -:navtitle: Authenticating users on 3-rd party services -:keywords: administration-guide, authenticating-users -:page-aliases: .:authenticating-users-3rd party services - -include::partial$assembly_authenticating-users-on-3rd-party-services.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/building-custom-registry-images.adoc b/modules/administration-guide/pages/building-custom-registry-images.adoc index 3f94f40d3a..9903fdd06a 100644 --- a/modules/administration-guide/pages/building-custom-registry-images.adoc +++ b/modules/administration-guide/pages/building-custom-registry-images.adoc @@ -4,10 +4,5 @@ :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 -:registry-mode: custom -:registry-mode-name: a custom -:registry-id: devfile -:registry-name: devfile - -include::example$assembly_{project-context}-building-custom-registry-images.adoc[] +include::partial$assembly_building-custom-registry-images.adoc[] diff --git a/modules/administration-guide/pages/che-architecture-overview.adoc b/modules/administration-guide/pages/che-architecture-overview.adoc deleted file mode 100644 index a4b069f1c8..0000000000 --- a/modules/administration-guide/pages/che-architecture-overview.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-architecture-overview"] -// = Che architecture overview -:navtitle: Che architecture -: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 - -include::partial$con_che-architecture-overview.adoc[] diff --git a/modules/administration-guide/pages/che-operator.adoc b/modules/administration-guide/pages/che-operator.adoc new file mode 100644 index 0000000000..73e4dece92 --- /dev/null +++ b/modules/administration-guide/pages/che-operator.adoc @@ -0,0 +1,6 @@ +[id="{prod-id-short}-operator"] +:navtitle: {prod-short} operator +:keywords: administration-guide, architecture, operator +// :page-aliases: + +include::partial$con_che-operator.adoc[] diff --git a/modules/administration-guide/pages/che-server.adoc b/modules/administration-guide/pages/che-server.adoc new file mode 100644 index 0000000000..43b7c535aa --- /dev/null +++ b/modules/administration-guide/pages/che-server.adoc @@ -0,0 +1,6 @@ +[id="{prod-id-short}-server"] +:navtitle: {prod-short} server +:keywords: administration-guide, architecture, server, devworkspace +// :page-aliases: + +include::partial$con_che-server-with-devworkspace.adoc[] diff --git a/modules/administration-guide/pages/che-workspace-controller.adoc b/modules/administration-guide/pages/che-workspace-controller.adoc deleted file mode 100644 index 7f86780ec0..0000000000 --- a/modules/administration-guide/pages/che-workspace-controller.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-workspace-controller"] -// = Che workspace controller -:navtitle: Che workspace controller -:keywords: administration-guide, che-workspace-controller -:page-aliases: .:che-workspace-controller - -include::partial$assembly_understanding-che-workspace-controller.adoc[] 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 new file mode 100644 index 0000000000..1f3b20030a --- /dev/null +++ b/modules/administration-guide/pages/che-workspaces-architecture-with-che-server.adoc @@ -0,0 +1,7 @@ +[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/administration-guide/pages/che-workspaces-architecture.adoc b/modules/administration-guide/pages/che-workspaces-architecture.adoc deleted file mode 100644 index 028814c983..0000000000 --- a/modules/administration-guide/pages/che-workspaces-architecture.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="che-workspaces-architecture"] -// = Che workspaces architecture -:navtitle: Che workspaces architecture -:keywords: administration-guide, che-workspaces-architecture -:page-aliases: .:che-workspaces-architecture - -include::partial$assembly_understanding-che-workspaces-architecture.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 new file mode 100644 index 0000000000..342f0ddc52 --- /dev/null +++ b/modules/administration-guide/pages/configuring-chectl-to-use-backup-server.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..8eb95ee0b5 --- /dev/null +++ b/modules/administration-guide/pages/configuring-cli-to-use-backup-server.adoc @@ -0,0 +1,7 @@ +[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/administration-guide/pages/configuring-minikube-github-authentication.adoc b/modules/administration-guide/pages/configuring-minikube-github-authentication.adoc new file mode 100644 index 0000000000..587baa9c2c --- /dev/null +++ b/modules/administration-guide/pages/configuring-minikube-github-authentication.adoc @@ -0,0 +1,7 @@ +[id="configuring-openshift-oauth"] +// = Configuring OpenShift OAuth +:navtitle: Configuring Minikube GitHub Authentication +:keywords: administration-guide, configuring-openshift-oauth +:page-aliases: .:configuring-minikube-github-authentication + +include::partial$proc_configuring-minikube-github-authentication.adoc[] diff --git a/modules/end-user-guide/pages/configuring-openshift-oauth.adoc b/modules/administration-guide/pages/configuring-openshift-oauth.adoc similarity index 77% rename from modules/end-user-guide/pages/configuring-openshift-oauth.adoc rename to modules/administration-guide/pages/configuring-openshift-oauth.adoc index f234084068..11a1f5cfee 100644 --- a/modules/end-user-guide/pages/configuring-openshift-oauth.adoc +++ b/modules/administration-guide/pages/configuring-openshift-oauth.adoc @@ -1,7 +1,7 @@ [id="configuring-openshift-oauth"] // = Configuring OpenShift OAuth :navtitle: Configuring OpenShift OAuth -:keywords: end-user-guide, configuring-openshift-oauth +:keywords: administration-guide, configuring-openshift-oauth :page-aliases: .:configuring-openshift-oauth include::partial$proc_configuring-openshift-oauth.adoc[] diff --git a/modules/administration-guide/pages/dashboard.adoc b/modules/administration-guide/pages/dashboard.adoc new file mode 100644 index 0000000000..ce686998c4 --- /dev/null +++ b/modules/administration-guide/pages/dashboard.adoc @@ -0,0 +1,6 @@ +[id="dashboard"] +:navtitle: User dashboard +:keywords: administration-guide, architecture, server, devworkspace, user, dashboard +// :page-aliases: + +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 new file mode 100644 index 0000000000..e47705adfd --- /dev/null +++ b/modules/administration-guide/pages/define-backup-server-for-operator.adoc @@ -0,0 +1,7 @@ +[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/devfile-registries.adoc b/modules/administration-guide/pages/devfile-registries.adoc new file mode 100644 index 0000000000..3a7209478a --- /dev/null +++ b/modules/administration-guide/pages/devfile-registries.adoc @@ -0,0 +1,6 @@ +[id="devfile-registries"] +:navtitle: Devfile registries +:keywords: administration-guide, architecture, server, devworkspace, devfile, registry +// :page-aliases: + +include::partial$con_devfile-registries.adoc[] diff --git a/modules/administration-guide/pages/devworkspace-operator.adoc b/modules/administration-guide/pages/devworkspace-operator.adoc new file mode 100644 index 0000000000..f39f8f9e2c --- /dev/null +++ b/modules/administration-guide/pages/devworkspace-operator.adoc @@ -0,0 +1,7 @@ +[id="devworkspace-operator"] +:navtitle: {devworkspace} operator +:keywords: administration-guide, workspace operator, devworkspace +:page-aliases: .:devworkspace-operator + + +include::partial$con_devworkspace-operator.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 new file mode 100644 index 0000000000..38570f22e0 --- /dev/null +++ b/modules/administration-guide/pages/disabling-readiness-init-containers-for-the-olm-installer.adoc @@ -0,0 +1,6 @@ +[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 new file mode 100644 index 0000000000..6c715efe5c --- /dev/null +++ b/modules/administration-guide/pages/disabling-readiness-init-containers-for-the-operator-installer.adoc @@ -0,0 +1,6 @@ +[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 new file mode 100644 index 0000000000..997c539a59 --- /dev/null +++ b/modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc @@ -0,0 +1,6 @@ +[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 new file mode 100644 index 0000000000..2971a5ac29 --- /dev/null +++ b/modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc @@ -0,0 +1,6 @@ +[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 new file mode 100644 index 0000000000..7ecef17f45 --- /dev/null +++ b/modules/administration-guide/pages/enabling-readiness-init-containers-for-the-olm-installer.adoc @@ -0,0 +1,6 @@ +[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 new file mode 100644 index 0000000000..0ca06760f5 --- /dev/null +++ b/modules/administration-guide/pages/enabling-readiness-init-containers-for-the-operator-installer.adoc @@ -0,0 +1,6 @@ +[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/gateway.adoc b/modules/administration-guide/pages/gateway.adoc new file mode 100644 index 0000000000..435535745b --- /dev/null +++ b/modules/administration-guide/pages/gateway.adoc @@ -0,0 +1,6 @@ +[id="gateway"] +:navtitle: Gateway +:keywords: administration-guide, architecture, server, devworkspace, gateway +// :page-aliases: + +include::partial$con_gateway.adoc[] diff --git a/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-helm.adoc b/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-helm.adoc deleted file mode 100644 index bb3b121fa9..0000000000 --- a/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-helm.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="installing-image-puller-on-kubernetes-using-helm"] -:navtitle: Installing using Helm -:keywords: administration-guide, image-puller, kubernetes, helm -:page-aliases: .:installing-image-puller-on-kubernetes-using-helm - -include::partial$proc_installing-image-puller-using-helm.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 new file mode 100644 index 0000000000..2c0b306b35 --- /dev/null +++ b/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc @@ -0,0 +1,6 @@ +[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-kubernetes-using-the-operator.adoc b/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-the-operator.adoc deleted file mode 100644 index 570e0ad845..0000000000 --- a/modules/administration-guide/pages/installing-image-puller-on-kubernetes-using-the-operator.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="installing-image-puller-on-kubernetes-using-the-operator"] -:navtitle: Installing using the Operator -:keywords: administration-guide, image-puller, kubernetes, operator -:page-aliases: .:installing-image-puller-on-kubernetes-using-the-operator - -include::partial$proc_installing-image-puller-on-kubernetes-using-the-operator.adoc[] 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 new file mode 100644 index 0000000000..5dc38ff4d9 --- /dev/null +++ b/modules/administration-guide/pages/installing-image-puller-using-che-operator.adoc @@ -0,0 +1,6 @@ +[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 new file mode 100644 index 0000000000..dba9d41e7a --- /dev/null +++ b/modules/administration-guide/pages/managing-backups-using-cli.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..b6ab64fa56 --- /dev/null +++ b/modules/administration-guide/pages/managing-backups-using-custom-resources.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..2adc2dc4f7 --- /dev/null +++ b/modules/administration-guide/pages/managing-identities-and-authorizations.adoc @@ -0,0 +1,7 @@ +[id="managing-identities-and-authorizations"] +// = Managing identities and authorizations +:navtitle: Managing identities and authorizations +:keywords: administration-guide, managing-identities-and-authorizations +:page-aliases: .:managing-identities-and-authorizations + +include::partial$assembly_managing-identities-and-authorizations.adoc[] diff --git a/modules/administration-guide/pages/managing-users.adoc b/modules/administration-guide/pages/managing-users.adoc deleted file mode 100644 index c4f4c54cef..0000000000 --- a/modules/administration-guide/pages/managing-users.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="managing-users"] -// = Managing users -:navtitle: Managing users -:keywords: administration-guide, managing-users -:page-aliases: .:managing-users, .:securing-che, securing-che - -include::partial$assembly_managing-users.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 new file mode 100644 index 0000000000..628223e5dd --- /dev/null +++ b/modules/administration-guide/pages/migration-from-postgresql-9-to-postgresql-13.adoc @@ -0,0 +1,6 @@ +[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-the-dev-workspace-operator.adoc b/modules/administration-guide/pages/monitoring-the-dev-workspace-operator.adoc new file mode 100644 index 0000000000..a5338af989 --- /dev/null +++ b/modules/administration-guide/pages/monitoring-the-dev-workspace-operator.adoc @@ -0,0 +1,7 @@ +[id="monitoring-the-dev-workspace-operator"] +// = Monitoring the {devworkspace} operator +:navtitle: Monitoring the {devworkspace} operator +:keywords: administration-guide, monitoring-the-dev-workspace-operator +:page-aliases: .:monitoring-the-dev-workspace-operator + +include::partial$assembly_monitoring-the-dev-workspace-operator.adoc[] diff --git a/modules/administration-guide/pages/plug-in-registry.adoc b/modules/administration-guide/pages/plug-in-registry.adoc new file mode 100644 index 0000000000..63ced1f6d2 --- /dev/null +++ b/modules/administration-guide/pages/plug-in-registry.adoc @@ -0,0 +1,6 @@ +[id="plug-in-registry"] +:navtitle: Plug-in registry +:keywords: administration-guide, architecture, server, devworkspace, plug-in, registry +// :page-aliases: + +include::partial$con_plug-in-registry.adoc[] diff --git a/modules/administration-guide/pages/postgresql.adoc b/modules/administration-guide/pages/postgresql.adoc new file mode 100644 index 0000000000..46fe96ba39 --- /dev/null +++ b/modules/administration-guide/pages/postgresql.adoc @@ -0,0 +1,6 @@ +[id="postgresl"] +:navtitle: PostgreSQL +:keywords: administration-guide, architecture, server, devworkspace, postgresql, database +// :page-aliases: + +include::partial$con_postgresql.adoc[] diff --git a/modules/administration-guide/pages/readiness-init-containers.adoc b/modules/administration-guide/pages/readiness-init-containers.adoc new file mode 100644 index 0000000000..a22565c85a --- /dev/null +++ b/modules/administration-guide/pages/readiness-init-containers.adoc @@ -0,0 +1,6 @@ +[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/running-custom-registries.adoc b/modules/administration-guide/pages/running-custom-registries.adoc index 12465740d7..306716f6c8 100644 --- a/modules/administration-guide/pages/running-custom-registries.adoc +++ b/modules/administration-guide/pages/running-custom-registries.adoc @@ -4,10 +4,5 @@ :keywords: contributor-guide, running-custom-registries :page-aliases: .:running-custom-registries, -:registry-mode: custom -:registry-mode-name: a custom -:registry-id: plugin -:registry-name: plug-in - 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 new file mode 100644 index 0000000000..e231e60072 --- /dev/null +++ b/modules/administration-guide/pages/server-components-with-che-server.adoc @@ -0,0 +1,8 @@ +[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 new file mode 100644 index 0000000000..3ee4234777 --- /dev/null +++ b/modules/administration-guide/pages/server-components.adoc @@ -0,0 +1,7 @@ +[id="server-components-with-the-devworkspace-engine"] +:navtitle: Server components +:keywords: administration-guide, architecture, server, devworkspace +// :page-aliases: + +include::partial$con_che-server-components.adoc[] + diff --git a/modules/administration-guide/pages/setup-backup-server.adoc b/modules/administration-guide/pages/setup-backup-server.adoc new file mode 100644 index 0000000000..23d881dcfe --- /dev/null +++ b/modules/administration-guide/pages/setup-backup-server.adoc @@ -0,0 +1,7 @@ +[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/administration-guide/pages/user-workspaces.adoc b/modules/administration-guide/pages/user-workspaces.adoc new file mode 100644 index 0000000000..ae8e6de428 --- /dev/null +++ b/modules/administration-guide/pages/user-workspaces.adoc @@ -0,0 +1,6 @@ +[id="user-workspaces"] +:navtitle: User workspaces +:keywords: administration-guide, architecture, workspace, devworkspace +// :page-aliases: + +include::partial$con_user-workspaces.adoc[] diff --git a/modules/administration-guide/pages/viewing-kubernetes-events.adoc b/modules/administration-guide/pages/viewing-kubernetes-events.adoc index 499a5f9d26..1230afd7e9 100644 --- a/modules/administration-guide/pages/viewing-kubernetes-events.adoc +++ b/modules/administration-guide/pages/viewing-kubernetes-events.adoc @@ -1,6 +1,6 @@ [id="viewing-kubernetes-events"] -// = Accessing Kubernetes events on OpenShift -:navtitle: Accessing Kubernetes events on OpenShift +// = Accessing {kubernetes} events on OpenShift +:navtitle: Accessing {kubernetes} events on OpenShift :keywords: administration-guide, viewing-kubernetes-events :page-aliases: .:viewing-kubernetes-events 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 index c426d6de3e..f488fec318 100644 --- a/modules/administration-guide/partials/assembly_authenticating-to-the-che-server.adoc +++ b/modules/administration-guide/partials/assembly_authenticating-to-the-che-server.adoc @@ -7,7 +7,6 @@ :context: authenticating-to-the-{prod-id-short}-server -include::partial$proc_authenticating-to-the-che-server-using-openid.adoc[leveloffset=+1] include::partial$proc_authenticating-to-the-che-server-using-other-authentication-implementations.adoc[leveloffset=+1] diff --git a/modules/administration-guide/partials/assembly_authenticating-users-on-3rd-party-services.adoc b/modules/administration-guide/partials/assembly_authenticating-users-on-3rd-party-services.adoc deleted file mode 100644 index e57da5f03c..0000000000 --- a/modules/administration-guide/partials/assembly_authenticating-users-on-3rd-party-services.adoc +++ /dev/null @@ -1,15 +0,0 @@ - -:parent-context-of-authorizing-users: {context} - -[id="authenticating-users-on-3rd-party-services_{context}"] -= Authenticating users on 3-rd party services - -:context: authenticating-users-on-3rd-party-services - -This topic covers authentication of users on 3-rd party services such as Bitbucket. - -include::partial$proc_configuring_bitbucket_servers.adoc[leveloffset=+1] - -include::partial$proc_configuring_bitbucket_authentication.adoc[leveloffset=+1] - -:context: {parent-context-of-authorizing-users} diff --git a/modules/administration-guide/partials/assembly_authenticating-users.adoc b/modules/administration-guide/partials/assembly_authenticating-users.adoc index 85ada86deb..21779d22e4 100644 --- a/modules/administration-guide/partials/assembly_authenticating-users.adoc +++ b/modules/administration-guide/partials/assembly_authenticating-users.adoc @@ -15,10 +15,6 @@ All authentication types use the link:https://jwt.io/introduction/[JWT open stan 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]. -ifeval::["{project-context}" == "che"] -include::partial$con_authentication-modes.adoc[leveloffset=+1] -endif::[] - include::partial$assembly_authenticating-to-the-che-server.adoc[leveloffset=+1] include::partial$assembly_authenticating-in-a-che-workspace.adoc[leveloffset=+1] diff --git a/modules/administration-guide/partials/assembly_authorizing-users.adoc b/modules/administration-guide/partials/assembly_authorizing-users.adoc index 43f6bfd42a..5e0af58bac 100644 --- a/modules/administration-guide/partials/assembly_authorizing-users.adoc +++ b/modules/administration-guide/partials/assembly_authorizing-users.adoc @@ -33,6 +33,4 @@ include::partial$proc_listing-che-permissions.adoc[leveloffset=+1] include::partial$proc_assigning-che-permissions.adoc[leveloffset=+1] -include::partial$proc_sharing-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 index 92e51f7341..f9b488b100 100644 --- a/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc +++ b/modules/administration-guide/partials/assembly_backup-and-disaster-recovery.adoc @@ -7,9 +7,29 @@ :context: backup-and-disaster-recovery -This section describes aspects of the {prod-short} 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[] -* xref:persistent-volumes-backups.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 new file mode 100644 index 0000000000..f90d6471da --- /dev/null +++ b/modules/administration-guide/partials/assembly_building-custom-registry-images.adoc @@ -0,0 +1,8 @@ +[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/administration-guide/partials/assembly_calculating-che-resource-requirements.adoc b/modules/administration-guide/partials/assembly_calculating-che-resource-requirements.adoc index 37fd299f25..f4a18c36e2 100644 --- a/modules/administration-guide/partials/assembly_calculating-che-resource-requirements.adoc +++ b/modules/administration-guide/partials/assembly_calculating-che-resource-requirements.adoc @@ -18,13 +18,14 @@ include::partial$con_a-workspace-example.adoc[leveloffset=+1] .Additional resources -* xref:che-architecture-overview.adoc[] +* xref: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:making-a-workspace-portable-using-a-devfile.adoc[] -* xref:end-user-guide:making-a-workspace-portable-using-a-devfile.adoc#a-minimal-devfile_{context}[] +* xref:end-user-guide:authoring-devfiles-version-2.adoc[] * xref:authenticating-users.adoc[] -* link:https://github.com/eclipse/che-plugin-registry[che-plugin-registry GitHub repository] +* 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_configuring-authorization.adoc b/modules/administration-guide/partials/assembly_configuring-authorization.adoc index 7473e630a6..c990619f6a 100644 --- a/modules/administration-guide/partials/assembly_configuring-authorization.adoc +++ b/modules/administration-guide/partials/assembly_configuring-authorization.adoc @@ -5,6 +5,8 @@ [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] @@ -19,16 +21,22 @@ include::partial$proc_enabling-authentication-with-social-accounts-and-brokering 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] -ifeval::["{project-context}" == "che"] -include::partial$proc_configuring-che-to-work-without-identity-provider.adoc[leveloffset=+1] -endif::[] - 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_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 new file mode 100644 index 0000000000..e9698f73e8 --- /dev/null +++ b/modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc @@ -0,0 +1,13 @@ +: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 new file mode 100644 index 0000000000..c2c5f217da --- /dev/null +++ b/modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc @@ -0,0 +1,13 @@ +: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_managing-identities-and-authorizations.adoc b/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc new file mode 100644 index 0000000000..3528756b34 --- /dev/null +++ b/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc @@ -0,0 +1,18 @@ + +: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[] +* xref:configuring-minikube-github-authentication.adoc[] + +:context: {parent-context-of-managing-identities-and-authorizations} diff --git a/modules/administration-guide/partials/assembly_managing-users.adoc b/modules/administration-guide/partials/assembly_managing-users.adoc deleted file mode 100644 index 9a89a218e6..0000000000 --- a/modules/administration-guide/partials/assembly_managing-users.adoc +++ /dev/null @@ -1,22 +0,0 @@ - - -:parent-context-of-managing-users: {context} - -[id="managing-users_{context}"] -= Managing users - -:context: managing-users - -This section describes how to configure authorization and authentication in {prod} and how to administer user groups and users. - -* xref:authenticating-users.adoc[] - -* xref:authorizing-users.adoc[] - -* xref:configuring-authorization.adoc[] - -* xref:removing-user-data.adoc[] - -* xref:authenticating-users-3rd-party-services.adoc[] - -:context: {parent-context-of-managing-users} diff --git a/modules/administration-guide/partials/assembly_monitoring-che.adoc b/modules/administration-guide/partials/assembly_monitoring-che.adoc index 0e867413c1..22b8bf8b5e 100644 --- a/modules/administration-guide/partials/assembly_monitoring-che.adoc +++ b/modules/administration-guide/partials/assembly_monitoring-che.adoc @@ -23,6 +23,4 @@ include::partial$proc_developing-grafana-dashboards.adoc[leveloffset=+1] endif::[] -include::partial$proc_extending-che-monitoring-metrics.adoc[leveloffset=+1] - :context: {parent-context-of-monitoring-che} diff --git a/modules/administration-guide/partials/assembly_monitoring-the-dev-workspace-operator.adoc b/modules/administration-guide/partials/assembly_monitoring-the-dev-workspace-operator.adoc new file mode 100644 index 0000000000..0fb189e7d0 --- /dev/null +++ b/modules/administration-guide/partials/assembly_monitoring-the-dev-workspace-operator.adoc @@ -0,0 +1,26 @@ + + +: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. +You must enable the {devworkspace} operator to follow the instructions in this chapter. +See xref:installation-guide:enabling-dev-workspace-operator.adoc[]. + +include::partial$proc_collecting-dev-workspace-operator-metrics-with-prometheus.adoc[leveloffset=+1] + +include::partial$ref_devworkspace-specific-metrics.adoc[leveloffset=+1] + +ifeval::["{project-context}" == "che"] + +include::partial$proc_viewing-dev-workspace-operator-metrics-on-grafana-dashboards.adoc[leveloffset=+1] + +include::partial$ref_grafana-dashboards-for-the-dev-workspace-operator.adoc[leveloffset=+1] + +endif::[] + +:context: {parent-context-of-monitoring-the-dev-workspace-operator} diff --git a/modules/administration-guide/partials/assembly_readiness-init-containers.adoc b/modules/administration-guide/partials/assembly_readiness-init-containers.adoc new file mode 100644 index 0000000000..9f7f08a419 --- /dev/null +++ b/modules/administration-guide/partials/assembly_readiness-init-containers.adoc @@ -0,0 +1,16 @@ +: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_running-custom-registries.adoc b/modules/administration-guide/partials/assembly_running-custom-registries.adoc index cb13140325..d60865f85f 100644 --- a/modules/administration-guide/partials/assembly_running-custom-registries.adoc +++ b/modules/administration-guide/partials/assembly_running-custom-registries.adoc @@ -23,14 +23,9 @@ These images can be then pushed to: * A public container registry such as `quay.io`, or the DockerHub. * A private registry. -ifeval::["{project-context}" == "che"] -:context: running-custom-registries-on-kubernetes - -include::partial$proc_deploying-registries-in-kubernetes.adoc[leveloffset=+1] -endif::[] - :context: running-custom-registries-on-openshift include::partial$proc_deploying-registries-in-openshift.adoc[leveloffset=+1] -:context: {parent-context-of-running-custom-registries} +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_understanding-che-workspace-controller.adoc b/modules/administration-guide/partials/assembly_server-components-with-che-server.adoc similarity index 60% rename from modules/administration-guide/partials/assembly_understanding-che-workspace-controller.adoc rename to modules/administration-guide/partials/assembly_server-components-with-che-server.adoc index 31f63c89d6..0761752fbf 100644 --- a/modules/administration-guide/partials/assembly_understanding-che-workspace-controller.adoc +++ b/modules/administration-guide/partials/assembly_server-components-with-che-server.adoc @@ -2,16 +2,18 @@ :parent-context-of-understanding-che-workspace-controller: {context} -[id="understanding-{prod-id-short}-workspace-controller_{context}"] -= Understanding {prod-short} workspace controller +[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.adoc[leveloffset=+1] +include::partial$con_che-workspace-controller-with-che-server.adoc[leveloffset=+1] include::partial$con_che-server.adoc[leveloffset=+1] -include::partial$con_che-user-dashboard.adoc[leveloffset=+1] +include::partial$con_che-dashboard.adoc[leveloffset=+1] include::partial$con_che-devfile-registry.adoc[leveloffset=+1] diff --git a/modules/administration-guide/partials/assembly_tracing-che.adoc b/modules/administration-guide/partials/assembly_tracing-che.adoc index 23df871fb3..ee0178084e 100644 --- a/modules/administration-guide/partials/assembly_tracing-che.adoc +++ b/modules/administration-guide/partials/assembly_tracing-che.adoc @@ -11,11 +11,11 @@ Tracing helps gather timing data to troubleshoot latency problems in microservic 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 transparent 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. +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 instead of repeating the whole instrumentation process for the new distributed tracing system, the developer can simply change the configuration of the tracer back end. +{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 diff --git a/modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture.adoc b/modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture-with-che-server.adoc similarity index 75% rename from modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture.adoc rename to modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture-with-che-server.adoc index 08f62fe92e..d8b19060af 100644 --- a/modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture.adoc +++ b/modules/administration-guide/partials/assembly_understanding-che-workspaces-architecture-with-che-server.adoc @@ -7,7 +7,9 @@ :context: understanding-{prod-id-short}-workspaces-architecture -include::partial$con_che-workspaces-architecture.adoc[leveloffset=+1] +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] diff --git a/modules/administration-guide/partials/assembly_viewing-che-server-logs.adoc b/modules/administration-guide/partials/assembly_viewing-che-server-logs.adoc index 8363c42a98..400b95ad46 100644 --- a/modules/administration-guide/partials/assembly_viewing-che-server-logs.adoc +++ b/modules/administration-guide/partials/assembly_viewing-che-server-logs.adoc @@ -10,9 +10,6 @@ This section describes how to view the {prod-short} server logs using the command line. -//// -include::partial$proc_viewing-che-server-logs-in-the-web-console.adoc[leveloffset=+1] -//// 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/con_a-workspace-example.adoc b/modules/administration-guide/partials/con_a-workspace-example.adoc index eb7c2e0fb1..7acccd1352 100644 --- a/modules/administration-guide/partials/con_a-workspace-example.adoc +++ b/modules/administration-guide/partials/con_a-workspace-example.adoc @@ -7,27 +7,8 @@ This section describes a {prod-short} workspace example. The following devfile defines the {prod-short} workspace: -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - generateName: guestbook-nodejs-sample- -projects: - - name: guestbook-nodejs-sample - source: - type: git - location: "https://github.com/l0rd/nodejs-sample" -components: - - type: chePlugin - id: che-incubator/typescript/latest - - type: kubernetes - alias: guestbook-frontend - reference: https://raw.githubusercontent.com/l0rd/nodejs-sample/master/kubernetes-manifests/guestbook-frontend.deployment.yaml - mountSources: true - entrypoints: - - command: ['sleep'] - args: ['infinity'] ----- +include::example$snip_a-{project-context}-workspace-example.adoc[] + This table provides the memory requirements for each workspace component: @@ -40,22 +21,22 @@ This table provides the memory requirements for each workspace component: |Default memory request |Workspace -|theia-ide (default `cheEditor`) +|`theia-ide` (default `cheEditor`) |512 MiB |512 MiB |Workspace -|machine-exec (default `chePlugin`) -|128 MiB +|`machine-exec` (default `chePlugin`) |128 MiB +|32 MiB |Workspace -|vscode-typescript (`chePlugin`) +|`vscode-typescript` (`chePlugin`) |512 MiB |512 MiB |Workspace -|frontend (`kubernetes`) +|`nodejs` (`dockerimage`) |1 GiB |512 MiB @@ -66,14 +47,15 @@ This table provides the memory requirements for each workspace component: 2+>s|Total >s|2.25 GiB ->s|1.75 GiB +>s|1.38 GiB |=== + * 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 `kubernetes` component type: a memory limit of *1 GiB* and a memory request of *512 MiB*. This is because the `kubernetes` component references a `Deployment` manifest that has a container specification with no resource limits or requests. +* {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.75 GiB* of memory requests with a *2.25 GiB* limit. +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 new file mode 100644 index 0000000000..f5660cdd1a --- /dev/null +++ b/modules/administration-guide/partials/con_architecture-overview-with-che-server.adoc @@ -0,0 +1,22 @@ +[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 new file mode 100644 index 0000000000..f8513420e2 --- /dev/null +++ b/modules/administration-guide/partials/con_architecture-overview-with-devworkspace.adoc @@ -0,0 +1,36 @@ +[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 new file mode 100644 index 0000000000..f85c89366d --- /dev/null +++ b/modules/administration-guide/partials/con_architecture-overview.adoc @@ -0,0 +1,32 @@ +[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_authentication-modes.adoc b/modules/administration-guide/partials/con_authentication-modes.adoc deleted file mode 100644 index 20b9711c8a..0000000000 --- a/modules/administration-guide/partials/con_authentication-modes.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// authenticating-users - -[id="authentication-modes_{context}"] -= Authentication modes - -{prod-short} supports multiuser and single-user mode. - -.Single-user mode - -Single-user mode requires no authentication and anyone can access all cluster resources. In single-user mode, the server performs all operations as the predefined user, regardless of who accesses the server. Therefore, this mode is suitable only for use in a private instance for testing product possibilities and configurations. - -* H2 database is used. - -{prod-short} deployed in single-user mode has no authentication and anyone who can access the URL of the {prod-short} deployment sees all workspaces and owns all resources. Because the deployment in this mode requires fewer containers, RAM and CPU requirements are lower. This mode is useful when the whole {prod-short} deployment is used by a single person or for lowering resources used. As the server does not authenticate, actions of multiple users logged in the same workspace can interfere with each other. - -Use third-party services, such as HAproxy or NGINX, to secure {prod-short} in single-user mode. - -.Multiuser mode - -Multiuser mode is the default mode for {prod-short}. It requires user authentication and offers isolated workspaces and their resources. In multiuser mode, workspaces are used in the scope of registered users and workspace definitions, and devfiles of particular workspaces can be shared and reused between many users. - -* {identity-provider} is used to authenticate users. -* PostgreSQL database is used. - - -["changing-the-authentication-mode_{context}"] -== Changing the authentication mode - -This procedure describes how to change authentication mode for various deployment types. - -.Procedure - -{prod-short} deployed using the {prod-short} Operator defaults to multiuser mode. To change to sing-user mode: - -. Update the `CheCluster` Custom Resource (CR) to set the `CHE_MULTIUSER` property to `false`: -+ -[source, yaml] ----- -spec: - server: - customCheProperties: - CHE_MULTIUSER: "false" ----- - -{prod-short} deployed using the Helm installer defaults to single-user mode. To change to multiuser mode: - -. Set the `multiuser` Helm chart field to `true`: -+ -[subs="+quotes,+attributes"] ----- -$ helm upgrade --install che --force --namespace {prod-namespace} --set global.cheDomain=__<{prod-host}>__ -f multi-user.yaml ----- - -{prod-short} deployed using the `{prod-cli}` command-line tool defaults to single-user mode. To change to multiuser mode: - -. Use the `--multiuser` (`-m`) option with the `{prod-cli} server:deploy` command: -+ -[subs="+quotes,+attributes"] ----- -$ {prod-cli} server:deploy --platfrom=minikube --installer=helm --multiuser ----- - diff --git a/modules/administration-guide/partials/con_authorization-and-user-management.adoc b/modules/administration-guide/partials/con_authorization-and-user-management.adoc index 65a61d8b53..bc171d962c 100644 --- a/modules/administration-guide/partials/con_authorization-and-user-management.adoc +++ b/modules/administration-guide/partials/con_authorization-and-user-management.adoc @@ -12,7 +12,7 @@ The default {identity-provider} credentials are `admin:admin`. You can use the ` .Identifying the {identity-provider} URL ifeval::["{project-context}" == "che"] -{prod-short} running on Kubernetes:: +{prod-short} running on {kubernetes}:: Go to `+$CHE_HOST:5050/auth+`. {prod-short} is running on OpenShift:: 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 index 7e0e0a1ecd..7ba77951ab 100644 --- 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 @@ -2,17 +2,15 @@ [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}. -The {image-puller-name-short} is an additional {platforms-name} deployment. -It creates a _DaemonSet_ downloading and running the relevant container images on each node. These images are already available when a {prod-short} workspace starts. +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} loads its configuration from a `ConfigMap` accepting following parameters. The installation method determines the procedure to configure the ConfigMap. +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} `ConfigMap` parameters +.{image-puller-name-short} parameters [options="header"] |=== |Parameter |Usage |Default @@ -51,31 +49,35 @@ endif::[] |`k8s-image-puller` |`IMAGES` -pass:[] -|Semicolon separated list of images to pull, in the format `____=____;...` See xref:defining-the-list-of-images-to-pull.adoc[]. +|Semicolon separated list of images to pull, in the format `____=____;____=____` See xref:defining-the-list-of-images-to-pull.adoc[]. | -pass:[] |`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 -pass:[] +.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-operator.adoc[] +* 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[] -ifeval::["{project-context}" == "che"] -* xref:installing-image-puller-on-kubernetes-using-helm.adoc[] -endif::[] -* link:https://github.com/che-incubator/kubernetes-image-puller[{image-puller-name} source code repository] -pass:[] +* 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-architecture-overview.adoc b/modules/administration-guide/partials/con_che-architecture-overview.adoc deleted file mode 100644 index 8c46038bf1..0000000000 --- a/modules/administration-guide/partials/con_che-architecture-overview.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="{prod-id-short}-architecture-overview_{context}"] -= {prod-short} architecture overview - -{prod} components are: - -* A central workspace controller: an always running service that manages users workspaces through the {orch-name} API. -* Users workspaces: container-based IDEs that the controller stops when the user stops coding. - -.High-level {prod-short} architecture -image::administration-guide:architecture/{project-context}-high-level.png[] - -When {prod-short} is installed on a {platforms-name} cluster, the workspace controller is the only component that is deployed. A {prod-short} workspace is created immediately after a user requests it. - -.Additional resources - -* xref:administration-guide:che-workspace-controller.adoc[] -* xref:administration-guide:che-workspaces-architecture.adoc[] diff --git a/modules/administration-guide/partials/con_che-dashboard.adoc b/modules/administration-guide/partials/con_che-dashboard.adoc new file mode 100644 index 0000000000..1ca23fe1af --- /dev/null +++ b/modules/administration-guide/partials/con_che-dashboard.adoc @@ -0,0 +1,17 @@ +// 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 index 50cc033433..a101c80184 100644 --- a/modules/administration-guide/partials/con_che-devfile-registry.adoc +++ b/modules/administration-guide/partials/con_che-devfile-registry.adoc @@ -1,22 +1,15 @@ // Module included in the following assemblies: // -// {prod-id-short}-workspace-controller +// {prod-id-short}-workspace-controller-with-che-server [id="{prod-id-short}-devfile-registry_{context}"] -= {prod-short} Devfile registry += {prod-short} devfile registry -The {prod-short} devfile registry is a service that provides a list of {prod-short} stacks to create ready-to-use workspaces. This list of stacks 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. +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. -// TODO: add link to "Customizing devfile registry" -For more information about devfile registry customization, see the Customizing devfile registry section. -[cols=2*] -|=== -ifeval::["{project-context}" == "che"] -| Source code -| link:{url-devfile-registry-repo}[{prod-short} Devfile registry] -endif::[] +.Additional resources -| Container image -| `{che-devfile-registry-container-image}` -|=== +* 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 index 8267c63bff..86d3e2f196 100644 --- a/modules/administration-guide/partials/con_che-editor-plug-in.adoc +++ b/modules/administration-guide/partials/con_che-editor-plug-in.adoc @@ -7,14 +7,14 @@ 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-theia[Che-Theia]. +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-theia[Che-Theia] +| link:https://github.com/eclipse-che/che-theia[Che-Theia] | Container image | `eclipse/che-theia` @@ -26,7 +26,7 @@ It has a plug-in system that supports VS Code extensions. .Additional resources -* link:https://github.com/eclipse/che-theia[Che-Theia] +* 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 index 6e39fb41ee..2dee164239 100644 --- a/modules/administration-guide/partials/con_che-keycloak.adoc +++ b/modules/administration-guide/partials/con_che-keycloak.adoc @@ -6,17 +6,11 @@ [id="{prod-id-short}-keycloak_{context}"] = {prod-short} and {identity-provider} -{identity-provider} is a prerequisite to configure {prod-short} in multi-user mode. 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. +{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. -[cols=2*] -|=== -ifeval::["{project-context}" == "che"] -| Source code -| link:{link-server-identity-provider-dockerfile-location}[{prod-short} {identity-provider}] -endif::[] +.Additional resources + +include::example$snip_che-keycloak-additional-resources.adoc[] -| Container image -| `{identity-provider-image-url}` -|=== diff --git a/modules/administration-guide/partials/con_che-operator.adoc b/modules/administration-guide/partials/con_che-operator.adoc new file mode 100644 index 0000000000..a6e89e9b2c --- /dev/null +++ b/modules/administration-guide/partials/con_che-operator.adoc @@ -0,0 +1,31 @@ +[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 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:installation-guide:configuring-the-che-installation.adoc[] +* xref:installation-guide:installing-che.adoc[] diff --git a/modules/administration-guide/partials/con_che-plug-in-registry.adoc b/modules/administration-guide/partials/con_che-plug-in-registry.adoc index 5480a3fd95..5e08432db3 100644 --- a/modules/administration-guide/partials/con_che-plug-in-registry.adoc +++ b/modules/administration-guide/partials/con_che-plug-in-registry.adoc @@ -1,25 +1,12 @@ // Module included in the following assemblies: // -// {prod-id-short}-workspace-controller +// {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 the {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. +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. -[cols=2*] -|=== -ifeval::["{project-context}" == "che"] -| Source code -| link:{url-plug-in-registry-repo}[{prod-short} plug-in registry] -endif::[] - -| Container image -| `{che-plugin-registry-container-image}` -|=== - -ifeval::["{project-context}" == "che"] .Additional resources -* xref:building-and-running-a-custom-registry-image.adoc[] -endif::[] +include::example$snip_che-plugin-registry-additional-resources.adoc[] diff --git a/modules/administration-guide/partials/con_che-postgresql.adoc b/modules/administration-guide/partials/con_che-postgresql.adoc index b1ed05a69d..717c354fac 100644 --- a/modules/administration-guide/partials/con_che-postgresql.adoc +++ b/modules/administration-guide/partials/con_che-postgresql.adoc @@ -1,21 +1,28 @@ // Module included in the following assemblies: // -// {prod-id-short}-workspace-controller +// {prod-id-short}-workspace-controller-with-che-server [id="{prod-id-short}-postgresql_{context}"] = {prod-short} and PostgreSQL -The PostgreSQL database is a prerequisite to configure {prod-short} in multi-user mode. The {prod-short} administrator can choose to connect {prod-short} to an existing PostgreSQL instance or let the {prod-short} deployment start a new dedicated PostgreSQL instance. +The PostgreSQL database is a prerequisite for {prod-short} server and {identity-provider}. -The {prod-short} server uses the database to persist user configurations (workspaces metadata, Git credentials). {identity-provider} uses the database as its back end to persist user information. +The {prod-short} administrator can choose to: -[cols=2*] -|=== -ifeval::["{project-context}" == "che"] -| Source code -| link:{link-postgres-dockerfile-location}[{prod-short} Postgres] -endif::[] +* 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[] -| Container image -| `{postgresql-image-url}` -|=== diff --git a/modules/administration-guide/partials/con_che-server-components.adoc b/modules/administration-guide/partials/con_che-server-components.adoc new file mode 100644 index 0000000000..13bf27be0f --- /dev/null +++ b/modules/administration-guide/partials/con_che-server-components.adoc @@ -0,0 +1,20 @@ +[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 new file mode 100644 index 0000000000..eb47b3bb80 --- /dev/null +++ b/modules/administration-guide/partials/con_che-server-with-devworkspace.adoc @@ -0,0 +1,30 @@ +// 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 index 2921b49e9c..2cbac86402 100644 --- a/modules/administration-guide/partials/con_che-server.adoc +++ b/modules/administration-guide/partials/con_che-server.adoc @@ -1,25 +1,17 @@ // Module included in the following assemblies: // -// {prod-id-short}-workspace-controller +// {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 the workspaces controller. It is a Java web service that exposes an HTTP REST API to manage {prod-short} workspaces and, in multi-user mode, {prod-short} users. - -[cols=2*] -|=== -ifeval::["{project-context}" == "che"] -| Source code -| link:https://github.com/eclipse/che[{prod} GitHub] -endif::[] - -| Container image -| `eclipse/che-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 index 3d688dc291..af3132c400 100644 --- a/modules/administration-guide/partials/con_che-system-permissions.adoc +++ b/modules/administration-guide/partials/con_che-system-permissions.adoc @@ -21,4 +21,4 @@ | Allows accessing endpoints used for monitoring the state of the server. |=== -All system permissions are granted to the administrative user who is configured in the `CHE_SYSTEM_ADMIN__NAME` property (the default is `admin`). The system permissions are granted when the {prod-short} server starts. If the user is not present in the {prod-short} user database, it happens after the first user’s login. +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-dashboard.adoc b/modules/administration-guide/partials/con_che-user-dashboard.adoc deleted file mode 100644 index d37db63393..0000000000 --- a/modules/administration-guide/partials/con_che-user-dashboard.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// {prod-id-short}-workspace-controller - -[id="{prod-id-short}-user-dashboard_{context}"] -= {prod-short} user dashboard - -The user dashboard is the landing page of {prod}. It is an Angular front-end application. {prod-short} users create, start, and manage {prod-short} workspaces from their browsers through the user dashboard. - -[cols=2*] -|=== -ifeval::["{project-context}" == "che"] -| Source code -| link:https://github.com/eclipse/che-dashboard[{prod-short} Dashboard] -endif::[] - -| Container image -| `eclipse/che-server` -|=== diff --git a/modules/administration-guide/partials/con_che-user-runtimes.adoc b/modules/administration-guide/partials/con_che-user-runtimes.adoc index 2d60ce465a..63f5087f25 100644 --- a/modules/administration-guide/partials/con_che-user-runtimes.adoc +++ b/modules/administration-guide/partials/con_che-user-runtimes.adoc @@ -7,6 +7,6 @@ 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 app dev/prod parity. +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 new file mode 100644 index 0000000000..d9f59b2b2a --- /dev/null +++ b/modules/administration-guide/partials/con_che-workspace-controller-with-che-server.adoc @@ -0,0 +1,17 @@ + +[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-controller.adoc b/modules/administration-guide/partials/con_che-workspace-controller.adoc deleted file mode 100644 index 672f3db612..0000000000 --- a/modules/administration-guide/partials/con_che-workspace-controller.adoc +++ /dev/null @@ -1,19 +0,0 @@ - -[id="{prod-id-short}-workspace-controller_{context}"] -= {prod-short} workspace controller - -The workspaces controller manages the container-based development environments: {prod-short} workspaces. Following deployment scenarios are available: - -* *Single-user*: The deployment contains no authentication service. Development environments are not secured. This configuration requires fewer resources. It is more adapted for local installations. - -* *Multi-user*: This is a multi-tenant configuration. Development environments are secured, and this configuration requires more resources. Appropriate for cloud installations. - -The following diagram shows the different services that are a part of the {prod-short} workspaces controller. Note that {identity-provider} and PostgreSQL are only needed in the multi-user configuration. - - -.{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-jwt-proxy.adoc b/modules/administration-guide/partials/con_che-workspace-jwt-proxy.adoc index 79fb035654..bca1f25eb5 100644 --- a/modules/administration-guide/partials/con_che-workspace-jwt-proxy.adoc +++ b/modules/administration-guide/partials/con_che-workspace-jwt-proxy.adoc @@ -5,7 +5,7 @@ [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. The {prod-short} workspace JWT proxy is included in a {prod-short} workspace only if the {prod-short} server is configured in multi-user mode. +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. diff --git a/modules/administration-guide/partials/con_che-workspaces-architecture.adoc b/modules/administration-guide/partials/con_che-workspaces-architecture-with-che-server.adoc similarity index 64% rename from modules/administration-guide/partials/con_che-workspaces-architecture.adoc rename to modules/administration-guide/partials/con_che-workspaces-architecture-with-che-server.adoc index a4de92d092..14b2d8bb1b 100644 --- a/modules/administration-guide/partials/con_che-workspaces-architecture.adoc +++ b/modules/administration-guide/partials/con_che-workspaces-architecture-with-che-server.adoc @@ -1,16 +1,16 @@ -[id="{prod-id-short}-workspaces-architecture_{context}"] +[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 a number of 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 related components, such as: +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/routes +* ingresses or routes * secrets -* PVs +* 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 Kubernetes resources. +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. @@ -19,7 +19,7 @@ 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 three running workspaces: two belonging to *User A* and one to *User C*. A fourth workspace is getting provisioned where the plug-in broker is verifying and completing the workspace configuration. +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 5296b2e9df..0c0a09c7b4 100644 --- a/modules/administration-guide/partials/con_controller-requirements.adoc +++ b/modules/administration-guide/partials/con_controller-requirements.adoc @@ -19,28 +19,28 @@ The Workspace Controller consists of a set of five services running in five dist |512 MiB |PostgreSQL -|postgres +|`postgres` |1 GiB |512 MiB |{identity-provider} -|{identity-provider-id} +|`{identity-provider-id}` |2 GiB |512 MiB |Devfile registry -|che-devfile-registry +|`che-devfile-registry` |256 MiB |16 MiB |Plug-in registry -|che-plugin-registry +|`che-plugin-registry` |256 MiB |16 MiB |=== -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 hosted version of {prod-short} that runs on link:https://che.openshift.io[] uses 1 GB of memory. +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. .Additional resources -* xref:administration-guide:che-workspace-controller.adoc[]. +* xref:administration-guide:server-components-with-che-server.adoc[]. diff --git a/modules/administration-guide/partials/con_dashboard.adoc b/modules/administration-guide/partials/con_dashboard.adoc new file mode 100644 index 0000000000..58aa524e2d --- /dev/null +++ b/modules/administration-guide/partials/con_dashboard.adoc @@ -0,0 +1,40 @@ +// 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 new file mode 100644 index 0000000000..a5fa4110eb --- /dev/null +++ b/modules/administration-guide/partials/con_define-backup-server-for-operator.adoc @@ -0,0 +1,98 @@ +[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 new file mode 100644 index 0000000000..0d9a2fd5da --- /dev/null +++ b/modules/administration-guide/partials/con_devfile-registries.adoc @@ -0,0 +1,20 @@ +[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 new file mode 100644 index 0000000000..ce8a4b4fcd --- /dev/null +++ b/modules/administration-guide/partials/con_devworkspace-operator.adoc @@ -0,0 +1,25 @@ +[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_gateway.adoc b/modules/administration-guide/partials/con_gateway.adoc new file mode 100644 index 0000000000..30e2e71e29 --- /dev/null +++ b/modules/administration-guide/partials/con_gateway.adoc @@ -0,0 +1,27 @@ +[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/administration-guide/partials/con_plug-in-registry.adoc b/modules/administration-guide/partials/con_plug-in-registry.adoc new file mode 100644 index 0000000000..8e41c25470 --- /dev/null +++ b/modules/administration-guide/partials/con_plug-in-registry.adoc @@ -0,0 +1,23 @@ +// 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 new file mode 100644 index 0000000000..7a0d7ab000 --- /dev/null +++ b/modules/administration-guide/partials/con_postgresql.adoc @@ -0,0 +1,21 @@ +// 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 new file mode 100644 index 0000000000..b3605b0d16 --- /dev/null +++ b/modules/administration-guide/partials/con_setup-backup-server.adoc @@ -0,0 +1,29 @@ +[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 index ac41b644a8..1207c1fea4 100644 --- a/modules/administration-guide/partials/con_super-privileged-mode.adoc +++ b/modules/administration-guide/partials/con_super-privileged-mode.adoc @@ -10,7 +10,7 @@ The *super-privileged* mode is disabled by default. To change to the *super-priv [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. +|`/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/administration-guide/partials/con_user-workspaces.adoc b/modules/administration-guide/partials/con_user-workspaces.adoc new file mode 100644 index 0000000000..378febfe4e --- /dev/null +++ b/modules/administration-guide/partials/con_user-workspaces.adoc @@ -0,0 +1,41 @@ +[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/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 new file mode 100644 index 0000000000..d91502d427 --- /dev/null +++ b/modules/administration-guide/partials/proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc @@ -0,0 +1,73 @@ +// 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_authenticating-to-the-che-server-using-openid.adoc b/modules/administration-guide/partials/proc_authenticating-to-the-che-server-using-openid.adoc deleted file mode 100644 index 26048ae8b8..0000000000 --- a/modules/administration-guide/partials/proc_authenticating-to-the-che-server-using-openid.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// authenticating-to-the-{prod-id-short}-server - -[id="authenticating-to-the-{prod-id-short}-server-using-openid_{context}"] -= Authenticating to the {prod-short} server using OpenID - -OpenID authentication on the {prod-short} server implies the presence of an external OpenID Connect provider and has the following main steps: - -* Authenticate the user through a JWT token that is retrieved from an HTTP request or, in case of a missing or invalid token, redirect the user to the {identity-provider} login page. - -* Send authentication tokens in an *Authorization* header. In limited cases, when it is impossible to use the *Authorization* header, the token can be sent in the token query parameter. Example: OAuth authentication initialization. - -* Compose an internal `subject` object that represents the current user inside the {prod-short} server code. - -NOTE: The only supported and tested OpenID provider is {identity-provider}. - -.Procedure - -To authenticate to the {prod-short} server using OpenID authentication: - -. Request the OpenID settings service where clients can find all the necessary URLs and properties of the OpenId provider, such as `jwks.endpoint`, `token.endpoint`, `logout.endpoint`, `realm.name`, or `client_id` returned in the JSON format. - -. The service URL is `pass:c,a,q[{prod-url}/api/keycloak/settings]`, and it is only available in the {prod-short} multiuser mode. The presence of the service in the URL confirms that the authentication is enabled in the current deployment. -+ -Example output: -+ -[source,json] ----- -{ - "che.keycloak.token.endpoint": "http://172.19.20.9:5050/auth/realms/che/protocol/openid-connect/token", - "che.keycloak.profile.endpoint": "http://172.19.20.9:5050/auth/realms/che/account", - "che.keycloak.client_id": "che-public", - "che.keycloak.auth_server_url": "http://172.19.20.9:5050/auth", - "che.keycloak.password.endpoint": "http://172.19.20.9:5050/auth/realms/che/account/password", - "che.keycloak.logout.endpoint": "http://172.19.20.9:5050/auth/realms/che/protocol/openid-connect/logout", - "che.keycloak.realm": "che" -} ----- -+ -The service allows downloading the JavaScript client library to interact with the provider using the `pass:c,a,q[{prod-url}/api/keycloak/OIDCKeycloak.js]` URL. - -. Redirect the user to the appropriate provider's login page with all the necessary parameters, including `client_id` and the return redirection path. This can be done with any client library (JS or Java). - -. When the user is logged in to the provider, the client side-code is obtained, and the JWT token has validated the token, the creation of the `subject` begins. - -The verification of the token signature occurs in two main steps: - -. Authentication: The token is extracted from the *Authorization* header or from the `token` query parameter and is parsed using the public key retrieved from the provider. In case of expired, invalid, or malformed tokens, a `403` error is sent to the user. The minimal use of the query parameter is recommended, due to its support limitations or complete removal in upcoming versions. -+ -If the validation is successful, the parsed form of the token is passed to the environment initialization step: - -. Environment initialization: The filter extracts data from the JWT token claims, creates the user in the local database if it is not yet available, and constructs the `subject` object and sets it into the per-request *EnvironmentContext* object, which is statically accessible everywhere. -+ -If the request was made using only a JWT token, the following single authentication filter is used: -+ -*org.eclipse.che.multiuser.machine.authentication.server.MachineLoginFilter*: The filter finds the user that the `userId` token belongs to, retrieves the user instance, and sets the principal to the session. The {prod-short} server-to-server requests are performed using a dedicated request factory that signs every request with the current subject token obtained from the `EnvironmentContext` object. - -[NOTE] -==== -.Providing user-specific data - -Since {identity-provider} may store user-specific information (first and last name, phone number, job title), there is a special implementation of the *ProfileDao* that can provide this data to consumers. The implementation is read-only, so users cannot perform create and update operations. -==== - - -[id="obtaining-the-token-from-keycloak_{context}"] -== Obtaining the token from credentials through {identity-provider} - -Clients that cannot run JavaScript or other clients (such as command-line clients or Selenium tests) must request the authorization token directly from {identity-provider}. - -To obtain the token, send a request to the token endpoint with the username and password credentials. This request can be schematically described as the following cURL request: - -[subs="+quotes,+attributes"] ----- -$ curl --insecure --data "grant_type=password&client_id={prod-deployment}-public&username=____&password=____" \ <1> <2> -https:///auth/realms/{prod-deployment}/protocol/openid-connect/token <3> ----- -<1> {prod} username -<2> {prod} user's password -<3> {identity-provider} host - -The {prod-short} dashboard uses a customized {identity-provider} login page and an authentication mechanism based on `grant_type=authorization_code`. It is a two-step authentication process: - -. Logging in and obtaining the authorization code. -. Obtaining the token using this authorization code. - -[id="obtaining-the-token-from-openshift-token-through-keycloak_{context}"] -== Obtaining the token from the OpenShift token through {identity-provider} - -When {prod-short} was installed on OpenShift using the Operator, and the OpenShift OAuth integration is enabled, as it is by default, -the user's {prod-short} authentication token can be retrieved from the user's OpenShift token. - -To retrieve the authentication token from the OpenShift token, send a schematically described cURL request to the OpenShift token endpoint: - -[subs="+quotes,+attributes"] ----- -$ curl --insecure -X POST \ --d "client_id={prod-deployment}-public" \ --d "subject_token=____" \ <1> --d "subject_issuer=____" \ <2> ---data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \ ---data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \ -https://____/auth/realms/{prod-deployment}/protocol/openid-connect/token <3> ----- -<1> The token retrieved by the end-user with the command `oc whoami --show-token` -<2> `openshift-v4` for OpenShift 4.x and `openshift-v3` for OpenShift 3.11 -<3> {identity-provider} host - - -WARNING: Before using this token exchange feature, it is required for an end user to be interactively logged in at least once to the {prod-short} Dashboard using the OpenShift login page. This step is needed to link the OpenShift and {identity-provider} user accounts properly and set the required user profile information. 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 new file mode 100644 index 0000000000..e0fafeef97 --- /dev/null +++ b/modules/administration-guide/partials/proc_building-a-custom-devfile-registry-image.adoc @@ -0,0 +1,69 @@ +// 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 `____/` and add the `devfile.yaml` and `meta.yaml` files. ++ +.File organization for a devfile +==== +[subs="+attributes,+quotes"] +---- +./{che-devfile-registry-directory}/devfiles/ +└── ____ + ├── 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 new file mode 100644 index 0000000000..31e7044271 --- /dev/null +++ b/modules/administration-guide/partials/proc_building-a-custom-plug-in-registry-image.adoc @@ -0,0 +1,49 @@ +// 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/administration-guide/partials/proc_collecting-che-metrics-with-prometheus.adoc b/modules/administration-guide/partials/proc_collecting-che-metrics-with-prometheus.adoc index 232d8b2fd6..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,31 +3,26 @@ [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 che metrics]. +* {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 * Configure Prometheus to scrape metrics from the `8087` port: + .Prometheus configuration example -[source,yaml,subs="+attributes"] ----- +==== include::example$prometheus-config.adoc[] ----- -ifeval::["{project-context}" == "che"] -+ -Latest version: link:https://github.com/eclipse/che/blob/master/deploy/openshift/templates/monitoring/prometheus-config.yaml[example `prometheus-config.yaml` on GitHub]. -endif::[] +==== + <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 @@ -36,7 +31,7 @@ endif::[] + Metrics are available at: `http://__: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..02bc26ce19 --- /dev/null +++ b/modules/administration-guide/partials/proc_collecting-dev-workspace-operator-metrics-with-prometheus.adoc @@ -0,0 +1,114 @@ +[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 link:https://github.com/devfile/devworkspace-operator/blob/v0.10.0/deploy/deployment/kubernetes/objects/devworkspace-controller-metrics.Service.yaml[`devworkspace-controller-metrics` service] is exposing metrics on port `8443`. + +* The `devworkspace-webhookserver` service is exposing metrics on port `9443`. By default, the service exposes metrics on port `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="+attributes"] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: devworkspace-controller-metrics-binding +subjects: + - kind: ServiceAccount + name: + namespace: +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: devworkspace-controller-metrics-reader +---- +==== + +. 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="+attributes"] +---- +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' + authorization: + type: Bearer + credentials_file: '/var/run/secrets/kubernetes.io/serviceaccount/token' + tls_config: + insecure_skip_verify: true + static_configs: + - targets: ['devworkspace-controller-metrics:8443'] <4> + - job_name: 'DevWorkspace webhooks' + authorization: + type: Bearer + credentials_file: '/var/run/secrets/kubernetes.io/serviceaccount/token' + tls_config: + insecure_skip_verify: true + static_configs: + - targets: ['devworkspace-webhookserver: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 new file mode 100644 index 0000000000..fc955a3c18 --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc @@ -0,0 +1,185 @@ +// 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 ____ 2048 +---- ++ +[subs="+quotes"] +---- +$ openssl rsa -in ____ -pubout > ____ +---- ++ +[subs="+quotes"] +---- +$ openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in ____ -out ____ +---- ++ +[subs="+quotes"] +---- +$ cat ____ | sed 's/-----BEGIN PUBLIC KEY-----//g' | sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n' > ____ +---- + +. Generate a consumer key and a shared secret. ++ +[subs="+quotes"] +---- +$ openssl rand -base64 24 > ____ +---- ++ +[subs="+quotes"] +---- +$ openssl rand -base64 24 > ____ +---- + +. 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 `____` file. + +Shared secret:: Paste the content of the `____` file. + +Request Token URL:: `____/plugins/servlet/oauth/request-token` + +Access token URL:: `____/plugins/servlet/oauth/access-token` + +Authorize 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 `____` file. + +Consumer name:: `__<{prod-short}>__` + +Public Key:: Paste the content of the `____` 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 - <__ <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: '____' <2> +type: Opaque +data: + private.key: '____' <3> + consumer.key: '____' <4> +EOF +---- ++ +<1> {prod-short} namespace. The default is {prod-namespace} +<2> Bitbucket Server URL +<3> base64 encoded content of the `____` file without first and last lines. +<4> base64 encoded content of the `____` 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='____' +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 <__ -n {prod-namespace} +---- + +. Edit the CheCluster Custom Resource (CR) to configure the {prod-short} server. ++ +[source,yaml,subs="+quotes"] +---- +spec: + server: + # … + gitSelfSignedCert: ____ <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 index f88eb7bff3..0ad13fc902 100644 --- 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 @@ -5,15 +5,11 @@ 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. -ifeval::["{project-context}" == "che"] -NOTE: A dedicated {identity-provider} instance is only deployed with {prod-short} installed in multiuser mode. -endif::[] - .Placeholders used in examples [cols="1,2"] |=== | `__` -| Identity provider realm name intended for use by {prod-short} +| {identity-provider} realm name intended for use by {prod-short} | `__` | Name of the `oidc` client defined in `__` @@ -24,21 +20,17 @@ endif::[] .Prerequisites -ifeval::["{project-context}" == "che"] -* This procedure is only applicable to {prod-short} installations done using the {prod-short} Operator. When using the `{prod-cli}` management tool and Helm to install {prod-short}, no supported method is available to use an external {identity-provider} instance. -endif::[] - -* 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] containing the users intended to connect to {prod-short}: +* 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[link="../_images/keycloak/external_keycloak_realm.png"] +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[link="../_images/keycloak/external_keycloak_public_client.png"] +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`. +* *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. @@ -52,16 +44,16 @@ 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 identity provider ins {identity-provider}. When using an external {identity-provider}, set up the identity provider manually. For instructions, see the appropriate {identity-provider} documentations for either link:{link-identity-provider-documentation-openshift-3}[OpenShift 3] or link:{link-identity-provider-documentation-openshift-4}[OpenShift 4]. +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. +* 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] +[source, yaml, subs="+quotes,macros,attributes"] ---- spec: auth: @@ -77,13 +69,13 @@ on OpenShift endif::[] with OpenShift OAuth support enabled, set the following properties in the `CheCluster` Custom Resource (CR): + -[source, yaml] +[source, yaml, subs="+quotes,macros,attributes"] ---- spec: auth: openShiftoAuth: true -# Note: only if the OpenShift identity provider alias is different from 'openshift-v3' or 'openshift-v4' +# 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: + CHE_INFRA_OPENSHIFT_OAUTH__IDENTITY__PROVIDER: ---- 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 index 0b09a6ad48..89a0f64209 100644 --- 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 @@ -20,26 +20,44 @@ $ {orch-cli} create namespace {prod-namespace} + [subs="+quotes,attributes"] ---- -$ {orch-cli} create secret generic \ <1> ---from-literal=user= \ <2> ---from-literal=password= \ <3> +$ {orch-cli} create secret generic ____ \ <1> +--from-literal=user=____ \ <2> +--from-literal=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 ____ \ <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 \ <1> ---from-literal=password= \ <2> +$ {orch-cli} create secret generic ____ \ <1> +--from-literal=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 ____ \ <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"] @@ -62,7 +80,7 @@ spec: auth: identityProviderPostgresSecret: <5> ---- -<1> External database hostname +<1> External database host name <2> External database port <3> Secret name with {prod-short} server database credentials <4> {prod-short} server database name diff --git a/modules/administration-guide/partials/proc_configuring-che-to-work-without-identity-provider.adoc b/modules/administration-guide/partials/proc_configuring-che-to-work-without-identity-provider.adoc deleted file mode 100644 index 18b4fe3733..0000000000 --- a/modules/administration-guide/partials/proc_configuring-che-to-work-without-identity-provider.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-authorization - -[id="configuring-prod-short-to-work-without-identity-provider_{context}"] -= Configuring {prod-short} to work without {identity-provider} - -By default, {prod-short} is deployed in multiuser mode where {identity-provider} and PostgreSQL are enabled by default. However, it is possible to deploy it in the single-user mode too, by changing the `CHE_MULTIUSER` value to `false`. In that case, neither {identity-provider} nor PostgreSQL is installed. - - -.Prerequisites - -* The `{prod-cli}` management tool is available. See the xref:overview:using-the-chectl-management-tool.adoc[] section. Alternatively, the OpenShift command line tool, `oc`, can be used. - -.Procedure - -. Prepare the `cr-patch.yaml` file with the following content: -+ -[source,yaml] ----- -spec: - server: - customCheProperties: - CHE_MULTIUSER: false ----- - -. Install {prod-short} in the single-user mode: -+ -[subs="+quotes,+attributes"] ----- -$ {prod-cli} server:deploy --platform ____ --installer operator --che-operator-cr-patch-yaml cr-patch.yaml ----- -+ -Depending on the strategy used, replace the `__` option in the above example with `crc`, `minishift`, or `openshift`. -ifeval::["{project-context}" == "che"] -{kubernetes}-native platforms such as `minikube`, `microk8s`, `k8s`, and `docker-desktop` are also available. -endif::[] - -.Verification - -. Wait for the console log output to display the `Command server:deploy has completed successfully.` message: -+ -[subs="+quotes,+attributes"] ----- -✔ Retrieving {prod} server URL... - ✔ {prod} status check -Command server:deploy has completed successfully. ----- - -. Use the following command for correct boolean verification: -+ -[subs="+quotes"] ----- -$ {prod-cli} get checluster -o=jsonpath='{.items[0].spec.server.customCheProperties.CHE_MULTIUSER}' ----- -+ -If the output of the command is `false`, {prod-short} has been successfully configured in single-user mode. - - 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 new file mode 100644 index 0000000000..0a1670f2ff --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-chectl-to-use-backup-server.adoc @@ -0,0 +1,35 @@ +[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 new file mode 100644 index 0000000000..0a1670f2ff --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-cli-to-use-backup-server.adoc @@ -0,0 +1,35 @@ +[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 index f7d4ca6390..2a30e0210f 100644 --- a/modules/administration-guide/partials/proc_configuring-external-PostgreSQL.adoc +++ b/modules/administration-guide/partials/proc_configuring-external-PostgreSQL.adoc @@ -3,27 +3,39 @@ [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 -. Use the following SQL script to create user and database for the {prod-short} server to persist workspaces metadata etc: +. Define the values of the following placeholders: ++ +-- +* `` is the {prod-short} server database user name +* `` is the {prod-short} server database password +* `` 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 WITH PASSWORD '' <1> <2> -CREATE DATABASE <3> +CREATE USER WITH PASSWORD '' +CREATE DATABASE GRANT ALL PRIVILEGES ON DATABASE TO ALTER USER WITH SUPERUSER ---- -<1> {prod-short} server database username -<2> {prod-short} server database password -<3> {prod-short} server database name -. Use the following SQL script to create database for {identity-provider} back end to persist user information: +. Define the value of the following placeholder: ++ +-- +* `` 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 '' <1> +CREATE USER keycloak WITH PASSWORD '' CREATE DATABASE keycloak GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak ----- -<1> {identity-provider} database password +---- \ 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 index a8b706c368..ccb2b521d5 100644 --- a/modules/administration-guide/partials/proc_configuring-github-oauth.adoc +++ b/modules/administration-guide/partials/proc_configuring-github-oauth.adoc @@ -14,12 +14,16 @@ OAuth for GitHub allows for automatic SSH key upload to GitHub. .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}.____/` and `++https://++keycloak-{prod-namespace}.____/auth/realms/{prod-deployment}/broker/github/endpoint` respectively, where `____` is {orch-name} cluster domain. +. Create an link:https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app[OAuth application in GitHub] with the following URLs: + +* Enter the {prod-short} URL as `Homepage URL`. The default value is `++https://++{prod-deployment}-{prod-namespace}.____/`. + +* Enter the `Authorization callback URL` as follows: + +** If the {devworkspace} engine is not enabled, enter the {identity-provider} GitHub endpoint URL as `Authorization callback URL`. The default value is `++https://++keycloak-{prod-namespace}.____/auth/realms/{prod-deployment}/broker/github/endpoint`. + +** If the {devworkspace} engine is enabled, enter the {prod-short} OAuth callback URL as `Authorization callback URL`. The default value is `++https://++{prod-deployment}-{prod-namespace}.____/api/oauth/callback`. -ifeval::["{project-context}" == "che"] -* For {prod-short} deployed in multi-user mode: -+ -endif::[] . Create a new secret in the {orch-namespace} where {prod-short} is deployed. + @@ -29,20 +33,17 @@ $ {orch-cli} apply -f - < <1> labels: app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: keycloak-secret + app.kubernetes.io/component: oauth-scm-configuration annotations: - che.eclipse.org/github-oauth-credentials: 'true' - che.eclipse.org/mount-as: env - che.eclipse.org/id_env-name: GITHUB_CLIENT_ID - che.eclipse.org/secret_env-name: GITHUB_SECRET + che.eclipse.org/oauth-scm-server: github +type: Opaque data: id: <...> <2> secret: <...> <3> -type: Opaque EOF ---- <1> {prod-short} namespace. The default is {prod-namespace} @@ -51,24 +52,3 @@ EOF . If {prod-short} was already installed wait until rollout of {identity-provider} component finishes. -ifeval::["{project-context}" == "che"] -+ - -* For {prod-short} deployed in single-user mode: -. On {platforms-name}, update the deployment configuration (see xref:installation-guide:configuring-the-che-installation.adoc[] and xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc#authentication-parameters[]). -+ -[subs=+quotes] ----- -CHE_OAUTH_GITHUB_CLIENTID=____ -CHE_OAUTH_GITHUB_CLIENTSECRET=____ ----- - -. In the *Authorization callback URL* field of the GitHub OAuth application, enter `___` with the URL and port of the {prod-short} installation. -* Substitute `__` and `__` with your GitHub client ID and secret. -* This configuration only applies to single-user deployments of {prod-short}. -==== -endif::[] diff --git a/modules/administration-guide/partials/proc_configuring-gitlab-oauth2.adoc b/modules/administration-guide/partials/proc_configuring-gitlab-oauth2.adoc new file mode 100644 index 0000000000..d1b50d0308 --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-gitlab-oauth2.adoc @@ -0,0 +1,48 @@ +// 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}.____/auth/realms/{prod-deployment}/broker/gitlab/endpoint`, where `____` 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://____/oauth/authorize` format; +Token URL:: a URL which have a `https://____/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 `__` 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 new file mode 100644 index 0000000000..0a79db05aa --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-gitlab-servers.adoc @@ -0,0 +1,16 @@ + +[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-minikube-github-authentication.adoc b/modules/administration-guide/partials/proc_configuring-minikube-github-authentication.adoc new file mode 100644 index 0000000000..e9942432ab --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-minikube-github-authentication.adoc @@ -0,0 +1,69 @@ +[id="configuring-minikube-github-authentication_{context}"] += Configuring Minikube with GitHub Authentication + + +On Minikube, {prod-cli} provides a default OpenID Connect (OIDC) issuer, which can serve as a bridge to third party {identity-provider}, such as GitHub. +{link-oidc-issuer} is the default OIDC issuer, preconfigured with static users. +Configure {link-oidc-issuer} to use GitHub authentication. + +.Prerequisites + +* {prod-short} is installed on Minikube. See xref:installation-guide:installing-che-on-minikube.adoc[]. + + +.Procedure +. Get Minikube IP and remember it as `__`: ++ +---- +$ minikube ip +---- + +. link:https://github.com/settings/applications/new[Create an OAuth App] for your Minikube instance in GitHub. See link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub documentation]. ++ +[source,subs="+attributes,macros,quotes"] +---- +Application name: {prod-short} <1> +Homepage URL: https://.nip.io <2> +Authorization callback URL: https://dex..nip.io/callback <3> +---- ++ +<1> Name is only displayed on GitHub. It is not used internally so it can be any name. +<2> Main URL to {prod-short} instance. +<3> Callback URL to Dex. {prod-cli} deploys Dex on `dex.` subdomain. + + +. In the GitHub OAuth application page, click btn:[Generate a new client secret] and remember the value of the generated client secret as `__`. + +. Edit the {link-oidc-issuer} config map: ++ +---- +$ kubectl edit configmap dex -n dex +---- ++ +[source,yaml,subs="+attributes,macros,quotes"] +---- +connectors: +- type: github + id: github + name: GitHub + config: + clientID: __ <1> + clientSecret: __ <2> + redirectURI: https://dex.__.nip.io/callback <3> +---- ++ +<1> OAuth client id copied from GitHub OAuth application +<2> OAuth client secret, generated at GitHub in previous step +<3> Callback URL to Dex. This must match configuration in GitHub OAuth application from step 1. + +Note: To remove Dex static users, delete all `enablePasswordDB` and `staticPasswords` sections. + +. Restart the {link-oidc-issuer} pod: ++ +---- +$ kubectl delete pod dex -n dex +---- + +.Verification steps + +* Open {prod-short} URL. The dashboard displays GitHub login prompt. 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 new file mode 100644 index 0000000000..bc187dad84 --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-openshift-oauth-with-initial-user.adoc @@ -0,0 +1,34 @@ +[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 new file mode 100644 index 0000000000..48c701191a --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-openshift-oauth-without-initial-user.adoc @@ -0,0 +1,37 @@ +[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 new file mode 100644 index 0000000000..076a9f5b35 --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-openshift-oauth.adoc @@ -0,0 +1,24 @@ +// 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_bitbucket_servers.adoc b/modules/administration-guide/partials/proc_configuring_bitbucket_servers.adoc deleted file mode 100644 index 79e5d51099..0000000000 --- a/modules/administration-guide/partials/proc_configuring_bitbucket_servers.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// configuring-bitbucket-servers - -[id="configuring_bitbucket_servers_{context}"] -= Configuring Bitbucket servers - - -To make it possible to use the Bitbucket server as a project sources supplier, -Bitbucket server URL should be registered on {prod} using the `CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS` property. -Value of the property must contain the hostname of the server to register. -Examples on how to change configuration options using Helm/Operator can be found here: - -* xref:installation-guide:advanced-configuration-options-for-the-che-server-component.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 index 574ec2ef18..f5cfdefec9 100644 --- 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 @@ -1,6 +1,14 @@ [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]. @@ -9,19 +17,16 @@ .Procedure -. Get the list of relevant container images. +. Gather a list of relevant container images for the {platforms-name} platform: + include::example$snip_{project-context}-getting-the-list-of-relevant-images.adoc[] -. Exclude from the list the container images not containing the `sleep` command. +. Determine images from the list for pre-pulling. + -include::example$snip_{project-context}-images-incompatibles-with-image-puller.adoc[] - - -. Exclude from the list the container images mounting volumes in Dockerfile. - - +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 @@ -29,12 +34,9 @@ pass:[] * xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. ifeval::["{project-context}" == "che"] -* xref:installing-image-puller-on-kubernetes-using-the-operator.adoc[] +* 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[] -ifeval::["{project-context}" == "che"] -* xref:installing-image-puller-on-kubernetes-using-helm.adoc[] -endif::[] pass:[] 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 index ff20b5e549..313d4adb7a 100644 --- 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 @@ -25,11 +25,7 @@ Pulling 5 images on 20 nodes, with a container memory limit of `20Mi` requires ` .Additional resources ifeval::["{project-context}" == "che"] -* xref:installing-image-puller-on-kubernetes-using-the-operator.adoc[] +* 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[] -ifeval::["{project-context}" == "che"] -* xref:installing-image-puller-on-kubernetes-using-helm.adoc[] -endif::[] - diff --git a/modules/administration-guide/partials/proc_deploying-registries-in-kubernetes.adoc b/modules/administration-guide/partials/proc_deploying-registries-in-kubernetes.adoc deleted file mode 100644 index 08d9baa74a..0000000000 --- a/modules/administration-guide/partials/proc_deploying-registries-in-kubernetes.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// deploying-the-registries - -[id="deploying-registries-in-kubernetes_{context}"] -= Deploying registries in {kubernetes} - -.Procedure - -A Helm chart for the plug-in registry is available in the `/kubernetes/che-plugin-registry/` directory of the GitHub repository. - -. To deploy the plug-in registry using the Helm chart, run the following command: -+ -[subs="+quotes,+attributes"] ----- -NAMESPACE=____ <1> -DOMAIN=____ <2> -IMAGE="my-plug-in-registry" -helm upgrade --install che-plugin-registry \ - --debug \ - --namespace $\{NAMESPACE} \ - --set global.ingressDomain=$\{DOMAIN} \ - --set chePluginRegistryImage=$\{IMAGE} \ - --set chePluginRegistryImagePullPolicy="Always" \ - ./kubernetes/che-plugin-registry/ ----- -<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}. -<2> On Minikube, use `$(minikube ip).nip.io` - -. The devfile registry also has a Helm chart in the `deploy/kubernetes/che-devfile-registry/` directory of the GitHub repository. To deploy it, run the command: -+ -[subs="+quotes,+attributes"] ----- -NAMESPACE=____ <1> -DOMAIN=____ <2> -IMAGE="my-devfile-registry" -helm upgrade --install che-devfile-registry \ - --debug \ - --namespace $\{NAMESPACE} \ - --set global.ingressDomain=$\{DOMAIN} \ - --set cheDevfileRegistryImage=$\{IMAGE} \ - --set cheDevfileRegistryImagePullPolicy="Always" \ - ./deploy/kubernetes/che-devfile-registry/ ----- -<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}. -<2> On Minikube, use `$(minikube ip).nip.io` - -. The Helm chart creates a Pod, a service, and an Ingress. To get them, use `component=plugin-registry` (or `component=plugin-registry` for the devfile registry) -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} get -o custom-columns=TYPE:.kind,NAME:.metadata.name \ - -l component=plugin-registry pod,svc,ingress -TYPE NAME -Pod che-plugin-registry-5c7cd8d5c9-zlqlz -Service che-plugin-registry -Ingress che-plugin-registry ----- - -:platform-routing: ingress -:platform-routing-host-path: .spec.rules[0].host - -include::partial$proc_verification-custom-registries.adoc[] diff --git a/modules/administration-guide/partials/proc_developing-grafana-dashboards.adoc b/modules/administration-guide/partials/proc_developing-grafana-dashboards.adoc index 57f795485f..b19ed0dbe6 100644 --- a/modules/administration-guide/partials/proc_developing-grafana-dashboards.adoc +++ b/modules/administration-guide/partials/proc_developing-grafana-dashboards.adoc @@ -13,14 +13,14 @@ 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[link="../_images/monitoring/monitoring-che-new-grafana-dashboard-queries.png"] +image::monitoring/monitoring-che-new-grafana-dashboard-queries.png[Grafana Dashboard queries, link="../_images/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[link="../_images/monitoring/monitoring-che-new-grafana-dashboard-visualization.png"] +image::monitoring/monitoring-che-new-grafana-dashboard-visualization.png[Grafana dashboard visualization, link="../_images/monitoring/monitoring-che-new-grafana-dashboard-visualization.png"] -. Save changes to the dashboard by clicking the btn:[Save] button, and copy and paste the JSON code to the deployment. +. Save changes to the dashboard using the btn:[Save] button, and copy and paste the JSON code to the deployment. . Load changes in the configuration of a running Grafana deployment. First remove the deployment: + 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 new file mode 100644 index 0000000000..e7ce32bcdf --- /dev/null +++ b/modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-olm-installer.adoc @@ -0,0 +1,42 @@ +:_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 -n {prod-namespace} -o yaml | grep installedCSV +---- + +. Edit the `ClusterServiceVersion` YAML manifest: ++ +[source,shell,subs="+quotes,+attributes"] +---- +$ {orch-cli} edit csv __ -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 new file mode 100644 index 0000000000..7dd93a5393 --- /dev/null +++ b/modules/administration-guide/partials/proc_disabling-readiness-init-containers-for-the-operator-installer.adoc @@ -0,0 +1,28 @@ +[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-authentication-with-social-accounts-and-brokering.adoc b/modules/administration-guide/partials/proc_enabling-authentication-with-social-accounts-and-brokering.adoc index da6b6325c6..c4f9ab3652 100644 --- 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 @@ -8,5 +8,3 @@ See {identity-provider} documentation to learn how to link:{link-identity-provid // TODO: To use {prod-short}'s OAuth Authenticator, set `che.oauth.service_mode` to `embedded` and use xref:end-user-guide:version-control.adoc[]. - -// TODO: See link:ide_projects.html#importing-projects-in-the-ide[SSH key management] for more information. 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 new file mode 100644 index 0000000000..6badd9eee1 --- /dev/null +++ b/modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-olm-installer.adoc @@ -0,0 +1,44 @@ +:_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 -n {prod-namespace} -o yaml | grep installedCSV +---- + +. Edit the `ClusterServiceVersion` YAML manifest: ++ +[source,shell,subs="+quotes,+attributes"] +---- +$ {orch-cli} edit csv __ -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 new file mode 100644 index 0000000000..59ea5c8df6 --- /dev/null +++ b/modules/administration-guide/partials/proc_enabling-readiness-init-containers-for-the-operator-installer.adoc @@ -0,0 +1,30 @@ +[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 new file mode 100644 index 0000000000..39e913bca3 --- /dev/null +++ b/modules/administration-guide/partials/proc_enabling-self-registration.adoc @@ -0,0 +1,20 @@ +// 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/administration-guide/partials/proc_extending-che-monitoring-metrics.adoc b/modules/administration-guide/partials/proc_extending-che-monitoring-metrics.adoc deleted file mode 100644 index 8410df7277..0000000000 --- a/modules/administration-guide/partials/proc_extending-che-monitoring-metrics.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// monitoring-{prod-id-short} - -[id="extending-{prod-id-short}-monitoring-metrics_{context}"] -= Extending {prod-short} monitoring metrics - -This section describes how to create a metric or a group of metrics to extend the monitoring metrics that {prod-short} is exposing. - -{prod-short} has two major modules metrics: - -* `che-core-metrics-core` -- contains core metrics module -* `che-core-api-metrics` -- contains metrics that are dependent on core {prod-short} components, such as workspace or user managers - - -.Procedure - -* Create a class that extends the `MeterBinder` class. This allows to register the created metric in the overridden `bindTo(MeterRegistry registry)` method. -+ -The following is an example of a metric that has a function that supplies the value for it: -+ -.Example metric -[source,java] ----- -public class UserMeterBinder implements MeterBinder { - - private final UserManager userManager; - - @Inject - public UserMeterBinder(UserManager userManager) { - this.userManager = userManager; - } - - @Override - public void bindTo(MeterRegistry registry) { - Gauge.builder("che.user.total", this::count) - .description("Total amount of users") - .register(registry); - } - - private double count() { - try { - return userManager.getTotalCount(); - } catch (ServerException e) { - return Double.NaN; - } - } ----- -+ -Alternatively, the metric can be stored with a reference and updated manually in other place in the code. - - -.Additional resources - -* link:https://prometheus.io/docs/practices/naming/[Metric and label naming for Prometheus] -* link:https://prometheus.io/docs/concepts/metric_types/[Metric types for Prometheus] diff --git a/modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-operator.adoc b/modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc similarity index 76% rename from modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-operator.adoc rename to modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc index 721ebef5ce..182b5ae645 100644 --- a/modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-operator.adoc +++ b/modules/administration-guide/partials/proc_installing-image-puller-on-kubernetes-using-the-image-puller-operator.adoc @@ -1,7 +1,7 @@ ifeval::["{project-context}" == "che"] [id="installing-image-puller-on-kubernetes-using-the-operator_{context}"] -= Installing {image-puller-name-short} on {kubernetes} using the Operator += 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. @@ -24,11 +24,11 @@ kubectl create namespace __<{image-puller-deployment-name}>__ [source,shell,subs="+quotes,+attributes"] ---- export NAMESPACE=__<{image-puller-deployment-name}>__ -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/kubernetes-image-puller-operator/master/deploy/crds/che.eclipse.org_kubernetesimagepullers_crd.yaml -n $NAMESPACE -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/kubernetes-image-puller-operator/master/deploy/role.yaml -n $NAMESPACE -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/kubernetes-image-puller-operator/master/deploy/role_binding.yaml -n $NAMESPACE -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/kubernetes-image-puller-operator/master/deploy/service_account.yaml -n $NAMESPACE -{orch-cli} apply -f https://raw.githubusercontent.com/che-incubator/kubernetes-image-puller-operator/master/deploy/operator.yaml -n $NAMESPACE +{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: 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 new file mode 100644 index 0000000000..410f4d45ae --- /dev/null +++ b/modules/administration-guide/partials/proc_installing-image-puller-using-che-operator.adoc @@ -0,0 +1,95 @@ +[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-helm.adoc b/modules/administration-guide/partials/proc_installing-image-puller-using-helm.adoc deleted file mode 100644 index e31305a824..0000000000 --- a/modules/administration-guide/partials/proc_installing-image-puller-using-helm.adoc +++ /dev/null @@ -1,150 +0,0 @@ -// caching-images-for-faster-workspace-start -ifeval::["{project-context}" == "che"] - -[id="installing-image-puller-using-helm_{context}"] -= Installing {image-puller-name-short} using Helm - -This section describes how to install the {image-puller-name-short} using Helm. - -.Prerequisites - -* A running {platforms-name} cluster. -* The `helm` tool is available. -* xref:defining-the-list-of-images-to-pull.adoc[] -* xref:defining-the-memory-parameters-for-the-image-puller.adoc[]. -* The {platforms-cli} tool is available. -+ -NOTE: When installing on OpenShift, replace the `{orch-cli}` command by `oc`. - -.Procedure - -*Installing* - -. Clone the {image-puller-name} repository: -+ ----- -$ git clone https://github.com/che-incubator/kubernetes-image-puller -$ cd kubernetes-image-puller ----- - -. Create a {orch-namespace} to deploy the puller into: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} create namespace k8s-image-puller ----- - -. To configure the installation, edit the `deploy/helm/values.yaml` file using following parameters: -+ -.Helm parameters for the {image-puller-name-short} -[options="header",subs="+attributes"] -|=== -|Value |Usage |Default - -|`deploymentName` -|The value of `DAEMONSET_NAME` and `DEPLOYMENT_NAME` to be set in the ConfigMap -| `{image-puller-deployment-name}` - -|`image.repository` -|The repository to pull the image from -| `{image-puller-image-name}` - -|`image.tag` -|The image tag to pull -|`{image-puller-image-tag}` - -|`serviceAccount.name` -|The name of the ServiceAccount to create -|`k8s-image-puller` - -|`configMap.name` -|The name of the ConfigMap to create -|`k8s-image-puller` - -|configMap.images -|The value of IMAGES in the ConfigMap -|none - -|`configMap.cachingIntervalHours` -|The value of `CACHING_INTERVAL_HOURS` in the ConfigMap -|``"1"`` - -|`configMap.cachingMemoryRequest` -|The value of `CACHING_MEMORY_REQUEST` in the ConfigMap -|`"10Mi"` - -|`configMap.cachingMemoryLimit` -|The value of `CACHING_MEMORY_LIMIT` in the ConfigMap -|`"20Mi"`` - -|`configMap.cachingCpuRequest` -|The value of `CACHING_CPU_REQUEST` in the ConfigMap -|`.05` - -|`configMap.cachingCpuLimit` -|The value of `CACHING_CPU_LIMIT` in the ConfigMap -|`.2` - -|`configMap.nodeSelector` -|The value of `NODE_SELECTOR` in the ConfigMap -|`"{}"` -|=== - -. Run the `helm` installation command: -+ ----- -$ helm install kubernetes-image-puller --namespace k8s-image-puller deploy/helm ----- -+ -[NOTE] -==== -Use the `--set property.name=____` parameter to override the values set in the `deploy/helm/values.yaml` file. -==== - -*Verifying the installation* - -. Confirm that a new deployment, `{image-puller-deployment-name}`, and a DaemonSet (named based on the value of the `DAEMONSET_NAME` parameter) exist. The DaemonSet needs to have a Pod for each node in the cluster: -+ -[source%nowrap,dummy,subs="+quotes,+attributes"] ----- -$ {orch-cli} get deployment,daemonset,pod --namespace k8s-image-puller -NAME READY UP-TO-DATE AVAILABLE AGE -deployment.apps/{image-puller-deployment-name} 1/1 1 1 4m21s - -NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE -daemonset.apps/{image-puller-deployment-name} 3 3 3 3 3 3m40s - -NAME READY STATUS RESTARTS AGE -pod/{image-puller-deployment-name}-b556c8bd4-qxwwl 1/1 Running 0 4m21s -pod/{image-puller-deployment-name}-glh87 3/3 Running 0 3m40s -pod/{image-puller-deployment-name}-h7lxf 3/3 Running 0 3m40s -pod/{image-puller-deployment-name}-nrt6p 3/3 Running 0 3m40s ----- - -. Check that the `ConfigMap` named `k8s-image-puller` has the values specified in the Helm configuration, or that they contain the default values: -+ -[source%nowrap,dummy,subs="+quotes,+attributes"] ----- -$ {orch-cli} get configmap k8s-image-puller --output yaml -apiVersion: v1 -data: - CACHING_INTERVAL_HOURS: "1" - CACHING_MEMORY_LIMIT: 20Mi - CACHING_MEMORY_REQUEST: 10Mi - DAEMONSET_NAME: {image-puller-deployment-name} - IMAGES: java11-maven=quay.io/eclipse/che-java11-maven:nightly; che-theia=eclipse/che-theia:next; - java-plugin-runner=eclipse/che-remote-plugin-runner-java8:latest; - NAMESPACE: k8s-image-puller - NODE_SELECTOR: '{}' -kind: ConfigMap -metadata: - creationTimestamp: "2020-02-17T22:15:22Z" - name: k8s-image-puller - namespace: k8s-image-puller - resourceVersion: "3078" - selfLink: /api/v1/namespaces/k8s-image-puller/configmaps/k8s-image-puller - uid: 71bc5ce4-d095-468e-ab7b-23c1e0a36638 ----- - -endif::[] - 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 index bb9792b9e0..38494b83aa 100644 --- 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 @@ -40,7 +40,7 @@ include::example$snip_{project-context}-cloning-image-puller-project.adoc[] |`SERVICEACCOUNT_NAME` |The name of the ServiceAccount created and used by the deployment -|`{image-puller-serviceaccount-name}` +|`kubernetes-image-puller` |=== + @@ -63,7 +63,7 @@ include::example$snip_{project-context}-cloning-image-puller-project.adoc[] |`CACHING_MEMORY_LIMIT` |The value of `CACHING_MEMORY_LIMIT` in the ConfigMap -|`"20Mi"`` +|`"20Mi"` |`CACHING_MEMORY_REQUEST` |The value of `CACHING_MEMORY_REQUEST` in the ConfigMap @@ -81,6 +81,10 @@ include::example$snip_{project-context}-cloning-image-puller-project.adoc[] |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 |`"{}"` @@ -93,7 +97,7 @@ include::example$snip_{project-context}-cloning-image-puller-project.adoc[] |`SERVICEACCOUNT_NAME` |The name of the ServiceAccount created and used by the deployment -|`{image-puller-serviceaccount-name}` +|`kubernetes-image-puller` |=== @@ -103,7 +107,7 @@ include::example$snip_{project-context}-cloning-image-puller-project.adoc[] + [subs="+attributes,+quotes"] ---- -$ oc new-project __<{image-puller-deployment-name}>__ +$ oc new-project __<{image-puller-namespace}>__ ---- . Process and apply the templates to install the puller: @@ -122,7 +126,7 @@ $ oc process -f app.yaml | oc apply -f - + [source%nowrap,dummy,subs="+quotes,+attributes"] ---- -$ oc get deployment,daemonset,pod --namespace __<{image-puller-deployment-name}>__ +$ oc get deployment,daemonset,pod --namespace __<{image-puller-namespace}>__ ---- . Verify the values of the __<{image-puller-deployment-name}>__ `ConfigMap`. diff --git a/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc new file mode 100644 index 0000000000..4d3c723830 --- /dev/null +++ b/modules/administration-guide/partials/proc_managing-backups-through-cli.adoc @@ -0,0 +1,78 @@ +[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-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-password=____ --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=____ --snapshot-id=____ --repository-url=____ --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=____ +---- + + +* 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 new file mode 100644 index 0000000000..f480bfb75f --- /dev/null +++ b/modules/administration-guide/partials/proc_managing-backups-through-custom-resources.adoc @@ -0,0 +1,141 @@ +[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 __ -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 __ -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: ' <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: ' <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/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 new file mode 100644 index 0000000000..b1731416ec --- /dev/null +++ b/modules/administration-guide/partials/proc_migration_from_postgresql_9_to_postgresql_13.adoc @@ -0,0 +1,121 @@ + +[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/administration-guide/partials/proc_removing-initial-openshift-user.adoc b/modules/administration-guide/partials/proc_removing-initial-openshift-user.adoc new file mode 100644 index 0000000000..c5de8862dd --- /dev/null +++ b/modules/administration-guide/partials/proc_removing-initial-openshift-user.adoc @@ -0,0 +1,20 @@ +[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 index 1cf92afd36..e2d9e30b1e 100644 --- a/modules/administration-guide/partials/proc_removing-user-data.adoc +++ b/modules/administration-guide/partials/proc_removing-user-data.adoc @@ -29,7 +29,7 @@ If needed, use commands below for creating the `admin` user: + [subs="+quotes,macros,attributes"] ---- -$ oc patch checluster {prod-checluster} \ +$ {orch-cli} patch checluster/{prod-checluster} \ --type merge \ -p '{ "spec": { "server": {"customCheProperties": {"pass:[CHE_SYSTEM_SUPER__PRIVILEGED__MODE]": "true"} } }}' \ -n __{prod-namespace}__ @@ -37,7 +37,7 @@ $ oc patch checluster {prod-checluster} \ + [subs="+quotes,macros,attributes"] ---- -$ oc patch checluster {prod-checluster} \ +$ {orch-cli} patch checluster/{prod-checluster} \ --type merge \ -p '{ "spec": { "server": {"customCheProperties": {"pass:[CHE_SYSTEM_ADMIN__NAME]": "____"} } }}' \ -n __{prod-namespace}__ @@ -45,7 +45,7 @@ $ oc patch checluster {prod-checluster} \ + [NOTE] ==== -All system permissions are granted to the administrative user who is configured in the `CHE_SYSTEM_ADMIN__NAME` property (the default is `admin`). The system permissions are granted when the {prod-short} server starts. If the user is not present in the {prod-short} user database, it happens after the first user’s login. +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: @@ -98,6 +98,7 @@ $ curl -X GET \ The user ID is at the bottom of the curl command output. +[source,json] ---- { "name": "vparfono", @@ -120,7 +121,7 @@ The user ID is at the bottom of the curl command output. + [subs="+quotes,macros,attributes"] ---- -$ oc patch checluster/{prod-checluster} \ +$ {orch-cli} patch checluster/{prod-checluster} \ --patch "{\"spec\":{\"server\":{\"customCheProperties\": {\"pass:[CHE_KEYCLOAK_CASCADE__USER__REMOVAL__ENABLED]\": \"true\"}}}}" \ --type=merge -n _{prod-namespace}_ ---- diff --git a/modules/administration-guide/partials/proc_sharing-che-permissions.adoc b/modules/administration-guide/partials/proc_sharing-che-permissions.adoc deleted file mode 100644 index 8558d0a437..0000000000 --- a/modules/administration-guide/partials/proc_sharing-che-permissions.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// authorizing-users - -[id="sharing-{prod-id-short}-permissions_{context}"] -= Sharing {prod-short} permissions - -A user with *setPermissions* privileges can share a workspace and grant `read`, `use`, `run`, `configure`, or `setPermissions` privileges for other users. - - -.Procedure - -To share workspace permissions: - -. Select a workspace in the user dashboard. - -. Navigate to the *Share* tab and enter the email IDs of the users. Use commas or spaces as separators for multiple emails. diff --git a/modules/administration-guide/partials/proc_verification-custom-registries.adoc b/modules/administration-guide/partials/proc_verification-custom-registries.adoc index 227d9b5e29..07b55364d6 100644 --- a/modules/administration-guide/partials/proc_verification-custom-registries.adoc +++ b/modules/administration-guide/partials/proc_verification-custom-registries.adoc @@ -1,74 +1,92 @@ // deploying-the-registries -[id="verification-custom_registries-_{context}"] - .Verification steps -. To verify that the new plug-in is correctly published to the plug-in registry, make a request to the registry path `/v3/plugins/index.json` (or `/devfiles/index.json` for the devfile registry). +. The ____ plug-in is available in the plug-in registry. ++ +.Find ____ 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 == "my-plug-in")' -{ - "id": "my-org/my-plug-in/1.0.0", - "displayName":"This is my first plug-in for {prod-short}", - "version":"1.0.0", - "type":"VS Code extension", - "name":"my-plug-in", - "description":"This plugins shows that we are able to add plugins to the registry...", - "publisher":"my-org", - "links": {"self":"/v3/plugins/my-org/my-plug-in/1.0.0"} -} --- --- -{ - "id": "my-org/my-plug-in/latest", - "displayName":"This is my first plug-in for {prod-short}", - "version":"latest", - "type":"VS Code extension", - "name":"my-plug-in", - "description":"This plugins shows that we are able to add plugins to the registry...", - "publisher":"my-org", - "links": {"self":"/v3/plugins/my-org/my-plug-in/latest" } -} +$ echo $\{INDEX_JSON} | jq '.[] | select(.name == "____")' +---- +==== + +. The ____ devfile is available in the devfile registry. ++ +.Find ____ 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 == "____")' ---- +==== -. Verify that the {prod-short} server points to the URL of the registry. To do so, compare the value of the `pass:[CHE_WORKSPACE_PLUGIN__REGISTRY__URL]` parameter in the `che` ConfigMap (or `pass:[CHE_WORKSPACE_DEVFILE__REGISTRY__URL]` for the devfile registry): +. {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 -URL -http://che-plugin-registry-che.192.168.99.100.nip.io/v3 ---- -+ -with the URL of the {platform-routing}: -+ +.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 -che-plugin-registry-che.192.168.99.100.nip.io ---- +==== -.. If they do not match, update the ConfigMap and restart the {prod-short} server. +. {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} edit cm/che +$ {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/che -$ {orch-cli} scale --replicas=1 deployment/che +$ {orch-cli} scale --replicas=0 deployment/{prod-deployment} +$ {orch-cli} scale --replicas=1 deployment/{prod-deployment} ---- -. When the new plugin registry is deployed and the {prod-short} server is configured to use them, UI should be reflected in the following places: -.. The new plug-ins are available in the completion to *chePlugin* components in *Devfile* tab of a workspace details; -.. The new plug-ins are available in the *Plugin* Theia view of a workspace. +pass:[] + +* 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:[] -. When the new devfile registry is deployed the {prod-short} server is configured to use them, the new devfiles are displayed in the *Get Started* and *Create Custom Workspace* tab of the user dashboard. +* 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-metrics-on-grafana-dashboards.adoc b/modules/administration-guide/partials/proc_viewing-che-metrics-on-grafana-dashboards.adoc index bc130ac184..38fa40d6df 100644 --- a/modules/administration-guide/partials/proc_viewing-che-metrics-on-grafana-dashboards.adoc +++ b/modules/administration-guide/partials/proc_viewing-che-metrics-on-grafana-dashboards.adoc @@ -18,7 +18,7 @@ This section describes how to view {prod-short} metrics on Grafana dashboards. + Three ConfigMaps are used to configure Grafana: + -* `grafana-datasources` -- configuration for Grafana datasource, a Prometheus endpoint +* `grafana-datasources` -- configuration for Grafana data source, a Prometheus endpoint * `grafana-dashboards` -- configuration of Grafana dashboards and panels * `grafana-dashboard-provider` -- configuration of the Grafana dashboard provider API object, which tells Grafana where to look in the file system for pre-provisioned dashboards 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 index ac67049ec1..1e874164db 100644 --- 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 @@ -3,7 +3,7 @@ [id="viewing-{prod-id-short}-traces-in-jaeger-ui_{context}"] = Viewing {prod-short} traces in Jaeger UI -This section demonstrates how to utilize the Jaeger UI to overview traces of {prod-short} operations. +This section demonstrates how to use the Jaeger UI to overview traces of {prod-short} operations. .Procedure diff --git a/modules/administration-guide/partials/proc_viewing-dev-workspace-operator-metrics-on-grafana-dashboards.adoc b/modules/administration-guide/partials/proc_viewing-dev-workspace-operator-metrics-on-grafana-dashboards.adoc new file mode 100644 index 0000000000..d9afbc5e49 --- /dev/null +++ b/modules/administration-guide/partials/proc_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.5.3 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/proc_viewing-keycloak-server-logs.adoc b/modules/administration-guide/partials/proc_viewing-keycloak-server-logs.adoc index 2850b8f34d..e89abef0ac 100644 --- a/modules/administration-guide/partials/proc_viewing-keycloak-server-logs.adoc +++ b/modules/administration-guide/partials/proc_viewing-keycloak-server-logs.adoc @@ -13,8 +13,11 @@ This section describes how to view the {identity-provider} OpenID provider serve . In the *Filter by label* search field, type `keycloak` to see the {identity-provider} logs. +pass:[] . In the *Deployment Configs* section, click the `keycloak` link to open it. +pass:[] + . In the *History* tab, click the *View log* link for the active {identity-provider} deployment. . The {identity-provider} logs are displayed. diff --git a/modules/administration-guide/partials/proc_viewing-postgresql-server-logs.adoc b/modules/administration-guide/partials/proc_viewing-postgresql-server-logs.adoc index e203e79f1d..66d879aab2 100644 --- a/modules/administration-guide/partials/proc_viewing-postgresql-server-logs.adoc +++ b/modules/administration-guide/partials/proc_viewing-postgresql-server-logs.adoc @@ -1,10 +1,16 @@ // viewing-external-service-logs +pass:[] +pass:[] [id="viewing-postgresql-server-logs_{context}"] = Viewing the {prod-short} database logs +pass:[] + +pass:[] + This section describes how to view the database logs in {prod-short}, such as PostgreSQL server logs. .Procedure @@ -15,9 +21,9 @@ This section describes how to view the database logs in {prod-short}, such as Po ** `app=che` and press kbd:[Enter] ** `component=postgres` and press kbd:[Enter] + -The OpenShift Web Console now searches base on those two keys and displays PostgreSQL logs. +The OpenShift Web Console is searching base on those two keys and displays PostgreSQL logs. -. Click *postgres* deployment to open it. +. Click *`postgres`* deployment to open it. . Click the *View log* link for the active PostgreSQL deployment. + 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 index c783fc0c30..4830682eb3 100644 --- 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 @@ -52,8 +52,5 @@ $ oc logs --tail=10 -f `(oc get pods -o name | grep operator)` + .Logs of the Operator: ==== -[options="nowrap",role="white-space-pre",subs="+quotes,+attributes"] ----- -include::example${project-context}-cluster-deployment-openshift-logs.adoc[] ----- +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 c44ad9415b..55fbd7c479 100644 --- a/modules/administration-guide/partials/proc_workspaces-requirements.adoc +++ b/modules/administration-guide/partials/proc_workspaces-requirements.adoc @@ -7,24 +7,24 @@ This section describes how to calculate the resources required for a workspace. These examples demonstrate the necessity of a proper calculation: -* A workspace with 10 active plug-ins requires more resources then the same workspace with fewer plug-ins. +* 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. .Procedure -. Identify the workspace components explicitly specified in the `components` section of the xref:end-user-guide:making-a-workspace-portable-using-a-devfile.adoc[]. +. 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. -.. When {prod-short} is running in multiuser mode, it loads the `JWT Proxy` component. The JWT Proxy is responsible for the authentication and authorization of the external communications of the workspace components. +.. 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 presents the default requirements for all workspace components. It also presents the corresponding {prod-short} server property to modify the defaults cluster-wide. +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 @@ -60,7 +60,7 @@ The following table presents the default requirements for all workspace componen + ... Custom memory limit and request: + -If present, the `memoryLimit` and `memoryRequest` attributes of the `containers` section of the `meta.yaml` file define the memory limit of the `chePlugins` or `cheEditors` components. {prod-short} automatically sets the memory request to match the memory limit in case it is not specified explicitly. +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` ==== @@ -75,7 +75,7 @@ spec: memoryRequest: 256Mi ---- -It results in a container with the following memory limit and request: +This results in a container with the following memory limit and request: |=== |Memory limit | 512 MiB @@ -83,11 +83,13 @@ It results in a container with the following memory limit and request: |=== ==== + +include::example$snip_{project-context}-memory-requirement-note.adoc[] ++ [NOTE] ==== .How to find the `meta.yaml` file of `chePlugin` -Community plug-ins are available in the link:https://github.com/eclipse/che-plugin-registry[che-plugin-registry GitHub repository] in folder `v3/plugins/$\{organization}/$\{name}/$\{version}/`. +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}/`. 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`. @@ -135,7 +137,7 @@ Note that the `LimitRange` object of the {platforms-namespace} may specify defau .. Custom requirements for `dockerimage` components + -If present, the `memoryLimit` and `memoryRequest` attributes of the devfile define the memory limit of a `dockerimage` container. {prod-short} automatically sets the memory request to match the memory limit in case it is not specified explicitly. +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] ---- @@ -149,9 +151,9 @@ If present, the `memoryLimit` and `memoryRequest` attributes of the devfile defi + The referenced manifest may define the memory requirements and limits. -. Add all requirements previously calculated. +. Add all previously calculated requirements. .Additional resources -* xref:administration-guide:che-workspaces-architecture.adoc[]. +* xref:administration-guide:che-workspaces-architecture-with-che-server.adoc[]. diff --git a/modules/administration-guide/partials/prometheus-config.adoc b/modules/administration-guide/partials/prometheus-config.adoc deleted file mode 100644 index eb3f57039c..0000000000 --- a/modules/administration-guide/partials/prometheus-config.adoc +++ /dev/null @@ -1,13 +0,0 @@ -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: 'che' - static_configs: - - targets: ['[che-host]:8087'] <4> 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_grafana-dashboards-for-che.adoc b/modules/administration-guide/partials/ref_grafana-dashboards-for-che.adoc index d975a9c279..a896df75dc 100644 --- a/modules/administration-guide/partials/ref_grafana-dashboards-for-che.adoc +++ b/modules/administration-guide/partials/ref_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[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="../_images/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[link=" * *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[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="../_images/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[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="../_images/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,20 +42,20 @@ image::monitoring/monitoring-che-che-server-dashboard-tomcat-panel.png[link="../ * *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[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="../_images/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[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="../_images/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. * *Threads created* - number of threads created by thread factory for given executor service. -* *Created thread/minute* - Speed of thread creating for the given executor service. +* *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[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="../_images/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. @@ -66,9 +66,9 @@ image::monitoring/monitoring-che-che-server-dashboard-executors-panel-2.png[link image::monitoring/monitoring-che-che-server-dashboard-executors-panel-3.png[link="../_images/monitoring/monitoring-che-che-server-dashboard-executors-panel-3.png"] * *Rejected task* - the number of tasks that were rejected from execution. -* *Rejected task/minute* - the speed of task rejections +* *Rejected task per minute* - the speed of task rejections * *Completed tasks* - the number of completed tasks -* *Completed tasks/minute* - the speed of task execution +* *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"] @@ -125,7 +125,7 @@ image::monitoring/monitoring-che-che-server-dashboard-workspace-detailed-panel-2 == {prod-short} server JVM dashboard -Use case: JVM metrics of the {prod-short} server, such as JVM memory or classloading. +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"] @@ -148,7 +148,7 @@ image::monitoring/monitoring-che-che-server-jvm-dashboard-jvm-memory-pools-non-h .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"] -.Classloading +.Class loading image::monitoring/monitoring-che-che-server-jvm-dashboard-classloading.png[link="../_images/monitoring/monitoring-che-che-server-jvm-dashboard-classloading.png"] .Buffer Pools diff --git a/modules/administration-guide/partials/ref_grafana-dashboards-for-the-dev-workspace-operator.adoc b/modules/administration-guide/partials/ref_grafana-dashboards-for-the-dev-workspace-operator.adoc new file mode 100644 index 0000000000..11225808bc --- /dev/null +++ b/modules/administration-guide/partials/ref_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/partials/ref_managesystem-permission.adoc b/modules/administration-guide/partials/ref_managesystem-permission.adoc index e0b6ac1e48..efc4cb8ba1 100644 --- a/modules/administration-guide/partials/ref_managesystem-permission.adoc +++ b/modules/administration-guide/partials/ref_managesystem-permission.adoc @@ -8,17 +8,17 @@ 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. +|`/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/snip_internal-backup-server-warning.adoc b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc new file mode 100644 index 0000000000..8f23f8bcd0 --- /dev/null +++ b/modules/administration-guide/partials/snip_internal-backup-server-warning.adoc @@ -0,0 +1,6 @@ +[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/contributor-guide/partials/assembly_che-extensibility-reference.adoc b/modules/contributor-guide/partials/assembly_che-extensibility-reference.adoc index d078419f6f..f8b6d690ab 100644 --- a/modules/contributor-guide/partials/assembly_che-extensibility-reference.adoc +++ b/modules/contributor-guide/partials/assembly_che-extensibility-reference.adoc @@ -7,11 +7,11 @@ :context: {prod-id-short}-extensibility-reference -This section contains reference material to extend {prod-short} functionalities. +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} +:context: {parent-context-of-che-extensibility-reference} \ No newline at end of file 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 index 39ea6ae7b7..3eb98c4b30 100644 --- a/modules/contributor-guide/partials/assembly_testing-che-theia-plug-ins.adoc +++ b/modules/contributor-guide/partials/assembly_testing-che-theia-plug-ins.adoc @@ -36,13 +36,13 @@ image::extensibility/hosted-instance-output.png[link="../_images/extensibility/h == 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 context menu with the available actions is displayed. You can stop and restart the running hosted Che-Theia instance from the context menu. When a hosted instance is stopped, use the context menu to start it again. +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 -There is a full code completion provided to help you write your plug-in. Code completion covers both the `Che Editor` plug-in API and the `Che Plugin` plug-in API. +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] diff --git a/modules/contributor-guide/partials/con_che-extension-points.adoc b/modules/contributor-guide/partials/con_che-extension-points.adoc index a2ef341936..07ba15b1e5 100644 --- a/modules/contributor-guide/partials/con_che-extension-points.adoc +++ b/modules/contributor-guide/partials/con_che-extension-points.adoc @@ -107,7 +107,7 @@ pluginPrefs.inspect('logLevel'); [id="view-containers_{context}"] == View containers -A *view container* is a container that holds xref:views_{context}[views]. In Che-Theia, views are usually 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. +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: @@ -253,7 +253,6 @@ Note that kbd:[Ctrl+f] kbd:[Alt+b] defines a _chord_: the command is invoked aft 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. -// TODO: For instruction on how to add a debugger, see link:link[Adding support for a new debugger]. See the link:https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/[list of debuggers] from the official DAP site for reference and examples. @@ -288,8 +287,8 @@ To add a language server into Che-Theia using a plug-in: <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 (TODO: our section or just link to link:https://code.visualstudio.com/api/language-extensions/language-configuration-guide[VS Code docs]?). +<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: + @@ -336,7 +335,7 @@ webViewPanel.webview.html ='

Hello from web view

__/__<{project-context}>__.git' ---- + -For additional information, see the xref:making-a-workspace-portable-using-a-devfile.adoc#devfile-reference_{context}[Devfile reference] section. \ No newline at end of file +For additional information, see the xref:authoring-devfiles-version-1.adoc[Devfile reference] section. diff --git a/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-a-file.adoc b/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-a-file.adoc index aaa6e0d3d5..5d59340933 100644 --- a/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-a-file.adoc +++ b/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-a-file.adoc @@ -1,10 +1,4 @@ -[NOTE] -==== -Note that the following example describes variations in the usage of the `target-container` annotation in versions 7.14 and 7.15 of {prod}. -==== -+ .Example: -+ [source,yaml] ---- apiVersion: v1 @@ -16,8 +10,8 @@ metadata: app.kubernetes.io/component: workspace-secret ... ---- -+ -Annotations must indicate the given secret is mounted as a file, provide the mount path, and, optionally, specify the name of the container in which the secret is mounted. If there is no target-container annotation, the secret will be mounted into all user containers of the {prod-short} workspace, but this is applicable *_only for the {prod-short} version 7.14_*. + +* The following example shows how to mount the secret as a file by including the `/mount-as: file` annotation: + [source,yaml,subs="+attributes"] ---- @@ -32,8 +26,10 @@ metadata: labels: ... ---- -+ -*_Since the {prod-short} version 7.15_*, the `target-container` annotation is deprecated and `automount-workspace-secret` annotation with Boolean values is introduced. Its purpose is to define the default secret mounting behavior, with the ability to be overridden in a devfile. The `true` value enables the automatic mounting into all workspace containers. In contrast, the `false` value disables the mounting process until it is explicitly requested in a devfile component using the `automountWorkspaceSecrets:true` property. + +* To define the default behavior for mounting secrets, use the `/automount-workspace-secret` annotation. Developers can override this default in a devfile. This annotation takes a boolean value: +** `'true'` enables automatic mounting into all workspace containers. +** `'false'` disables automatic mounting into all workspace containers. To mount a secret, a user must request it in the devfile component by using the `automountWorkspaceSecrets:true` property. + [source,yaml,subs="+attributes"] ---- @@ -48,8 +44,8 @@ metadata: labels: ... ---- -+ -Data of the {orch-name} secret may contain several items, whose names must match the desired file name mounted into the container. + +* The following example shows how to mount the `settings.xml` file at the `{prod-home}/.m2/` path of all workspace containers: + [source,yaml,subs="+quotes,attributes"] ---- @@ -68,9 +64,16 @@ data: settings.xml: ____ ---- + -This results in a file named `settings.xml` being mounted at the `{prod-home}/.m2/` path of all workspace containers. +NOTE: The `data` of the {orch-name} secret can contain several items. The names of these items must match the desired file name mounted into the container. + +* To override the mount path of the secret for a workspace component, edit the devfile as follows: ++ +. Declare a component alias for the containers in the override path. +. Declare an additional volume for the component. +. Use the name of the secret as the name of the volume. +. Provide the new mount path for the secret as `containerPath`. + -The secret-s mount path can be overridden for specific components of the workspace using devfile. To change mount path, an additional volume should be declared in a component of the devfile, with name matching overridden secret name, and desired mount path. +See the following example: + [source,yaml,subs="+quotes"] ---- @@ -86,5 +89,3 @@ components: containerPath: /my/new/path ... ---- -+ -Note that for this kind of overrides, components must declare an alias to be able to distinguish containers which belong to them and apply override path exclusively for those containers. diff --git a/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-an-variable.adoc b/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-an-variable.adoc index 6cc76e0605..029204e78f 100644 --- a/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-an-variable.adoc +++ b/modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as-an-variable.adoc @@ -1,10 +1,4 @@ -[NOTE] -==== -Note that the following example describes variations in the usage of the `target-container` annotation in versions 7.14 and 7.15 of {prod}. -==== -+ .Example: -+ [source,yaml] ---- apiVersion: v1 @@ -16,28 +10,11 @@ metadata: app.kubernetes.io/component: workspace-secret ... ---- -+ -Annotations must indicate that the given secret is mounted as an environment variable, provides variable names, and optionally, specifies the container name where this mount will be applied. If there is no target-container annotation defined, the secret will be mounted into all user containers of the {prod-short} workspace, but this is applicable *_only for the {prod-short} version 7.14_*. -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: mvn-settings-secret - annotations: - che.eclipse.org/target-container: maven - che.eclipse.org/env-name: FOO_ENV - che.eclipse.org/mount-as: env - labels: - ... -data: - mykey: myvalue ----- -+ -This results in the environment variable named `FOO_ENV` and the value `myvalue` being provisioned into the `maven` container. -+ -*_Since the {prod-short} version 7.15_*, the `target-container` annotation is deprecated and `automount-workspace-secret` annotation with Boolean values is introduced. Its purpose is to define the default secret mounting behavior, with the ability to be overridden in a devfile. The `true` value enables automatic mounting into all workspace containers. In contrast, the `false` value disables the mounting process until it is explicitly requested in a devfile component using the `automountWorkspaceSecrets:true` property. + +// The corresponding procedure is underdeveloped. Parts of this example will likely end up in the procedure. A comprehensive rewrite is needed. max-cx + +* The following example shows how to mount the secret as an environment variable by including the `/mount-as: env` annotation: + + [source,yaml] ---- @@ -55,9 +32,17 @@ data: mykey: myvalue ---- + -This results in the environment variable named `FOO_ENV` and the value `myvalue` being provisioned into all workspace containers. -+ -If the secret provides more than one data item, the environment variable name must be provided for each of the data keys as follows: +In this example, the `FOO_ENV` environment variable and `myvalue` key value are provisioned into all workspace containers as follows: + +** The secret's environment variable, `env-name`, is declared as `FOO_ENV` in the `annotations`. + +** The `automount-workspace-secret` annotation with a boolean value defines the default secret mounting behavior (that can be overridden in a devfile): + +*** `'true'` enables automatic mounting into all workspace containers. + +*** `'false'` disables the mounting process until it is explicitly requested in a devfile component using the `automountWorkspaceSecrets:true` property. + +* If the secret has more than one data key, declare an environment variable name using a `<__key__>_env-name` annotation for each data key, as shown in the following example. In this example, you provision the `myvalue` and `othervalue` data key values, and the environment variable names, `FOO_ENV` and `OTHER_ENV`, into all workspace containers. + [source,yaml] ---- @@ -76,7 +61,5 @@ data: mykey: myvalue otherkey: othervalue ---- -+ -This results in two environment variables with names `FOO_ENV`, `OTHER_ENV`, and values `myvalue` and `othervalue`, being provisioned into all workspace containers. -+ -NOTE: The maximum length of annotation names in a {orch-name} secret is 63 characters, where 9 characters are reserved for a prefix that ends with `/`. This acts as a restriction for the maximum length of the key that can be used for the secret. + +* The maximum length of an annotation name in a {orch-name} secret is 63 characters, of which 9 characters are reserved for a prefix that ends with `/`. This acts as a restriction for the maximum length of the key that can be used for the secret. diff --git a/modules/end-user-guide/examples/che-ref_annotations-description.adoc b/modules/end-user-guide/examples/che-ref_annotations-description.adoc index 137f1f37a0..37411bf85b 100644 --- a/modules/end-user-guide/examples/che-ref_annotations-description.adoc +++ b/modules/end-user-guide/examples/che-ref_annotations-description.adoc @@ -4,8 +4,8 @@ * `che.eclipse.org/env-name`: The name of the environment variable that is used to mount a secret. -* `che.eclipse.org/mount-as`: This item describes if a secret will be mounted as an environmental variable or a file. Options: `env` or `file`. +* `che.eclipse.org/mount-as`: Describes if a secret will be mounted as an environmental variable or a file. Options: `env` or `file`. * `che.eclipse.org/__-env-name: FOO_ENV`: The name of the environment variable used when data contains multiple items. `mykeyName` is used as an example. -* `che.eclipse.org/git-credential: 'true'`: The flag indicates that the secret contains git credential file. +* `che.eclipse.org/git-credential: 'true'`: The flag indicates that the secret contains Git credential file. 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 index 9b0e1c7f97..a1362613df 100644 --- 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 @@ -19,5 +19,5 @@ data: ---- + 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. +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/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 new file mode 100644 index 0000000000..e69de29bb2 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 new file mode 100644 index 0000000000..999d2627b8 --- /dev/null +++ b/modules/end-user-guide/examples/snip_bitbucket-personal-access-token-secret.adoc @@ -0,0 +1,19 @@ +[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: '____' <2> + che.eclipse.org/scm-userid: '____' <3> + che.eclipse.org/scm-username: '____' <4> + che.eclipse.org/scm-url: '____' <5> + che.eclipse.org/expired-after: '-1' <6> + name: bitbucket-personal-access-token-secret + +data: + token: '____' <7> +---- 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 new file mode 100644 index 0000000000..db2c6b09fc --- /dev/null +++ b/modules/end-user-guide/examples/snip_che-configuring-a-workspace-to-use-intellij-idea-community.adoc @@ -0,0 +1,6 @@ +[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_github-personal-access-token-secret.adoc b/modules/end-user-guide/examples/snip_github-personal-access-token-secret.adoc new file mode 100644 index 0000000000..63f0197d46 --- /dev/null +++ b/modules/end-user-guide/examples/snip_github-personal-access-token-secret.adoc @@ -0,0 +1,18 @@ +[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 new file mode 100644 index 0000000000..ae95fd39aa --- /dev/null +++ b/modules/end-user-guide/examples/snip_gitlab-personal-access-token-secret.adoc @@ -0,0 +1,18 @@ +[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/jetbrains/activation-code.jpg b/modules/end-user-guide/images/jetbrains/activation-code.jpg deleted file mode 100644 index ba6e45fe84..0000000000 Binary files a/modules/end-user-guide/images/jetbrains/activation-code.jpg and /dev/null differ diff --git a/modules/end-user-guide/images/jetbrains/jetbrains-account.jpg b/modules/end-user-guide/images/jetbrains/jetbrains-account.jpg deleted file mode 100644 index aab24375cc..0000000000 Binary files a/modules/end-user-guide/images/jetbrains/jetbrains-account.jpg and /dev/null differ diff --git a/modules/end-user-guide/images/loggingin/copy_login_command_menu.png b/modules/end-user-guide/images/loggingin/copy_login_command_menu.png deleted file mode 100644 index 85db5f1c58..0000000000 Binary files a/modules/end-user-guide/images/loggingin/copy_login_command_menu.png and /dev/null differ diff --git a/modules/end-user-guide/images/loggingin/copy_login_command_notification.png b/modules/end-user-guide/images/loggingin/copy_login_command_notification.png deleted file mode 100644 index 48297fdf4b..0000000000 Binary files a/modules/end-user-guide/images/loggingin/copy_login_command_notification.png and /dev/null differ diff --git a/modules/end-user-guide/images/troubleshooting/download_logs.png b/modules/end-user-guide/images/troubleshooting/download_logs.png deleted file mode 100644 index b871c024eb..0000000000 Binary files a/modules/end-user-guide/images/troubleshooting/download_logs.png and /dev/null differ diff --git a/modules/end-user-guide/images/troubleshooting/run_workspace_in_debug_mode.png b/modules/end-user-guide/images/troubleshooting/run_workspace_in_debug_mode.png deleted file mode 100644 index 830f4a57fc..0000000000 Binary files a/modules/end-user-guide/images/troubleshooting/run_workspace_in_debug_mode.png and /dev/null differ diff --git a/modules/end-user-guide/images/troubleshooting/starting_workspace_debug_logs.png b/modules/end-user-guide/images/troubleshooting/starting_workspace_debug_logs.png deleted file mode 100644 index 9acbec579a..0000000000 Binary files a/modules/end-user-guide/images/troubleshooting/starting_workspace_debug_logs.png and /dev/null differ diff --git a/modules/end-user-guide/images/troubleshooting/try_again_in_debug_mode.png b/modules/end-user-guide/images/troubleshooting/try_again_in_debug_mode.png deleted file mode 100644 index 78dff03e40..0000000000 Binary files a/modules/end-user-guide/images/troubleshooting/try_again_in_debug_mode.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/che-config-projects-add-git.png b/modules/end-user-guide/images/workspaces/che-config-projects-add-git.png deleted file mode 100644 index 6ae85a2995..0000000000 Binary files a/modules/end-user-guide/images/workspaces/che-config-projects-add-git.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/che-config-projects-add-github.png b/modules/end-user-guide/images/workspaces/che-config-projects-add-github.png deleted file mode 100644 index 6b648b46f2..0000000000 Binary files a/modules/end-user-guide/images/workspaces/che-config-projects-add-github.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/che-create-and-open.png b/modules/end-user-guide/images/workspaces/che-create-and-open.png deleted file mode 100644 index fca9944b51..0000000000 Binary files a/modules/end-user-guide/images/workspaces/che-create-and-open.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/che-run-from-recent-workspaces.png b/modules/end-user-guide/images/workspaces/che-run-from-recent-workspaces.png deleted file mode 100644 index 3d32a8a0f0..0000000000 Binary files a/modules/end-user-guide/images/workspaces/che-run-from-recent-workspaces.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/che-sample-card.png b/modules/end-user-guide/images/workspaces/che-sample-card.png deleted file mode 100644 index 1b2c76e253..0000000000 Binary files a/modules/end-user-guide/images/workspaces/che-sample-card.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/che-select-sample.png b/modules/end-user-guide/images/workspaces/che-select-sample.png deleted file mode 100644 index a915cf0a10..0000000000 Binary files a/modules/end-user-guide/images/workspaces/che-select-sample.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/component_as_a_referenceContent.png b/modules/end-user-guide/images/workspaces/component_as_a_referenceContent.png deleted file mode 100644 index 46e06fbf39..0000000000 Binary files a/modules/end-user-guide/images/workspaces/component_as_a_referenceContent.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/configure-workspace-devfile.png b/modules/end-user-guide/images/workspaces/configure-workspace-devfile.png deleted file mode 100644 index 5cc1181131..0000000000 Binary files a/modules/end-user-guide/images/workspaces/configure-workspace-devfile.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/configure-workspace.png b/modules/end-user-guide/images/workspaces/configure-workspace.png deleted file mode 100644 index ffa32f4ba5..0000000000 Binary files a/modules/end-user-guide/images/workspaces/configure-workspace.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/minimal-devfile.png b/modules/end-user-guide/images/workspaces/minimal-devfile.png deleted file mode 100644 index b2f56c35c2..0000000000 Binary files a/modules/end-user-guide/images/workspaces/minimal-devfile.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/save-and-start-the-new-che-workspace.png b/modules/end-user-guide/images/workspaces/save-and-start-the-new-che-workspace.png deleted file mode 100644 index 6e49284934..0000000000 Binary files a/modules/end-user-guide/images/workspaces/save-and-start-the-new-che-workspace.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 new file mode 100644 index 0000000000..9e2412baec Binary files /dev/null and b/modules/end-user-guide/images/workspaces/workspace-add-editor.png 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 new file mode 100644 index 0000000000..b03a1fba5d Binary files /dev/null and b/modules/end-user-guide/images/workspaces/workspace-add-plugin.png differ diff --git a/modules/end-user-guide/images/workspaces/workspace-config-overview.png b/modules/end-user-guide/images/workspaces/workspace-config-overview.png deleted file mode 100644 index 4985561fa9..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace-config-overview.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/workspace-config-yaml.png b/modules/end-user-guide/images/workspaces/workspace-config-yaml.png deleted file mode 100644 index 805d1e8e96..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace-config-yaml.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/workspace-devfile-changes.png b/modules/end-user-guide/images/workspaces/workspace-devfile-changes.png deleted file mode 100644 index bac2f6bd21..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace-devfile-changes.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 index ba65f0da58..deed91ca41 100644 Binary files a/modules/end-user-guide/images/workspaces/workspace-devfile-editor.png and b/modules/end-user-guide/images/workspaces/workspace-devfile-editor.png differ diff --git a/modules/end-user-guide/images/workspaces/workspace-devfile.png b/modules/end-user-guide/images/workspaces/workspace-devfile.png deleted file mode 100644 index 3b3c46f431..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace-devfile.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/workspace-save-apply-cancel.png b/modules/end-user-guide/images/workspaces/workspace-save-apply-cancel.png deleted file mode 100644 index 23154ffaf2..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace-save-apply-cancel.png and /dev/null differ diff --git a/modules/end-user-guide/images/workspaces/workspace_devfile_che_7_.png b/modules/end-user-guide/images/workspaces/workspace_devfile_che_7_.png deleted file mode 100644 index 43b2fc4d03..0000000000 Binary files a/modules/end-user-guide/images/workspaces/workspace_devfile_che_7_.png and /dev/null differ diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index b12f0ee35f..21c157bc6d 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -4,35 +4,39 @@ ** 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:configuring-a-workspace-using-a-devfile.adoc[] -** xref:making-a-workspace-portable-using-a-devfile.adoc[] -** xref:creating-and-configuring-a-new-workspace.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:creating-a-workspace-from-code-sample.adoc[] -** xref:creating-a-workspace-by-importing-source-code-of-a-project.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:support-for-jetbrains-ides.adoc[] -**** xref:using-jetbrains-intellij-idea-community-edition.adoc[] -**** xref:using-jetbrains-intellij-idea-ultimate-edition.adoc[] -**** xref:using-jetbrains-webstorm.adoc[] -**** xref:provisioning-jetbrains-activation-code-for-offline-use.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:configuring-oauth-authorization.adoc[] -** xref:configuring-openshift-oauth.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[] @@ -42,7 +46,6 @@ ** xref:using-npm-artifact-repositories.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:starting-a-che-workspace-in-debug-mode.adoc[] -** xref:restarting-a-che-workspace-in-debug-mode-after-start-failure.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 index 0fe42497ee..95a581eccf 100644 --- 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 @@ -1,6 +1,6 @@ [id="adding-a-vscode-extension-to-a-workspace"] // = Adding tools to Che after creating a workspace -:navtitle: Adding a VSCode extension +: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 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 new file mode 100644 index 0000000000..b22f083be1 --- /dev/null +++ b/modules/end-user-guide/pages/adding-a-vs-code-extension-to-the-che-plugin-registry.adoc @@ -0,0 +1,7 @@ +[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/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 new file mode 100644 index 0000000000..a881291895 --- /dev/null +++ b/modules/end-user-guide/pages/authenticating-on-scm-server-with-a-personal-access-token.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..ab5fb760b1 --- /dev/null +++ b/modules/end-user-guide/pages/authoring-devfiles-version-1.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..04dea70b12 --- /dev/null +++ b/modules/end-user-guide/pages/authoring-devfiles-version-2.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..c80078aec4 --- /dev/null +++ b/modules/end-user-guide/pages/authoring-devfiles.adoc @@ -0,0 +1,7 @@ +[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/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 new file mode 100644 index 0000000000..88a8b45fec --- /dev/null +++ b/modules/end-user-guide/pages/building-images-for-ides-based-on-the-intellij-platform.adoc @@ -0,0 +1,5 @@ +[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/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 new file mode 100644 index 0000000000..7b99a8ea4c --- /dev/null +++ b/modules/end-user-guide/pages/configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc @@ -0,0 +1,6 @@ +[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-using-a-devfile.adoc b/modules/end-user-guide/pages/configuring-a-workspace-using-a-devfile.adoc deleted file mode 100644 index 3d8ce2043a..0000000000 --- a/modules/end-user-guide/pages/configuring-a-workspace-using-a-devfile.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-a-workspace-using-a-devfile"] -// = Configuring a workspace using a devfile -:navtitle: Configuring a workspace using a devfile -:keywords: end-user-guide, configuring-a-workspace-using-a-devfile -:page-aliases: .:configuring-a-workspace-using-a-devfile - -include::partial$assembly_configuring-a-workspace-using-a-devfile.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 new file mode 100644 index 0000000000..d04f8dc8d4 --- /dev/null +++ b/modules/end-user-guide/pages/configuring-a-workspace-with-dashboard.adoc @@ -0,0 +1,6 @@ +[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-oauth-authorization.adoc b/modules/end-user-guide/pages/configuring-oauth-authorization.adoc deleted file mode 100644 index a2b6ece359..0000000000 --- a/modules/end-user-guide/pages/configuring-oauth-authorization.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-oauth-authorization"] -// = Configuring OAuth authorization -:navtitle: Configuring OAuth authorization -:keywords: end-user-guide, configuring-oauth-authorization -:page-aliases: .:configuring-oauth-authorization - -include::partial$assembly_configuring-oauth-authorization.adoc[] diff --git a/modules/end-user-guide/pages/creating-a-workspace-by-importing-source-code-of-a-project.adoc b/modules/end-user-guide/pages/creating-a-workspace-by-importing-source-code-of-a-project.adoc deleted file mode 100644 index 78894aa78e..0000000000 --- a/modules/end-user-guide/pages/creating-a-workspace-by-importing-source-code-of-a-project.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="creating-a-workspace-by-importing-source-code-of-a-project"] -// = Creating a workspace by importing source code of a project -:navtitle: Creating a workspace by importing source code of a project -:keywords: end-user-guide, creating-a-workspace-by-importing-source-code-of-a-project -:page-aliases: .:creating-a-workspace-by-importing-source-code-of-a-project - -include::partial$proc_creating-a-workspace-by-importing-source-code-of-a-project.adoc[] 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 new file mode 100644 index 0000000000..c07e6aad50 --- /dev/null +++ b/modules/end-user-guide/pages/creating-a-workspace-from-a-code-sample.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..b236f9323d --- /dev/null +++ b/modules/end-user-guide/pages/creating-a-workspace-from-a-template-devfile.adoc @@ -0,0 +1,7 @@ +[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-code-sample.adoc b/modules/end-user-guide/pages/creating-a-workspace-from-code-sample.adoc deleted file mode 100644 index 5aac3a6534..0000000000 --- a/modules/end-user-guide/pages/creating-a-workspace-from-code-sample.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="creating-a-workspace-from-code-sample"] -// = Creating a workspace from code sample -:navtitle: Creating a workspace from code sample -:keywords: end-user-guide, creating-a-workspace-from-code-sample -:page-aliases: .:creating-a-workspace-from-code-sample - -include::partial$assembly_creating-a-workspace-from-code-sample.adoc[] 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 new file mode 100644 index 0000000000..5c2d73deee --- /dev/null +++ b/modules/end-user-guide/pages/creating-a-workspace-from-local-devfile-using-chectl.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..d4fce324a0 --- /dev/null +++ b/modules/end-user-guide/pages/creating-a-workspace-from-remote-devfile.adoc @@ -0,0 +1,7 @@ +[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/creating-and-configuring-a-new-workspace.adoc b/modules/end-user-guide/pages/creating-and-configuring-a-new-workspace.adoc deleted file mode 100644 index def142c661..0000000000 --- a/modules/end-user-guide/pages/creating-and-configuring-a-new-workspace.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="creating-and-configuring-a-new-workspace"] -// = Creating and configuring a new workspace -:navtitle: Creating and configuring a new workspace -:keywords: end-user-guide, creating-and-configuring-a-new-workspace -:page-aliases: .:creating-and-configuring-a-new-workspace - -include::partial$assembly_creating-and-configuring-a-new-workspace.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 index 5453fd2d75..f845ea015d 100644 --- 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 @@ -1,6 +1,6 @@ [id="differences-in-how-che-theia-webview-works-on-a-single-host-mode-comparing-to-a-multi-host-mode"] -// = Differences in how Che-Theia Webview works on a single-host mode comparing to a multi-host mode -:navtitle: 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 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 index 77f9b81535..e493b570b0 100644 --- 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 @@ -1,6 +1,6 @@ [id="importing-kubernetes-applications-into-a-workspace"] -// = Importing a Kubernetes application into a workspace -:navtitle: 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 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 new file mode 100644 index 0000000000..d2ce652481 --- /dev/null +++ b/modules/end-user-guide/pages/importing-the-source-code-of-a-project-into-a-workspace.adoc @@ -0,0 +1,6 @@ +[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/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 new file mode 100644 index 0000000000..62547ecde0 --- /dev/null +++ b/modules/end-user-guide/pages/investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc @@ -0,0 +1,6 @@ +[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 +: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[] diff --git a/modules/end-user-guide/pages/making-a-workspace-portable-using-a-devfile.adoc b/modules/end-user-guide/pages/making-a-workspace-portable-using-a-devfile.adoc deleted file mode 100644 index 4d96c817c7..0000000000 --- a/modules/end-user-guide/pages/making-a-workspace-portable-using-a-devfile.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="making-a-workspace-portable-using-a-devfile"] -// = Making a workspace portable using a devfile -:navtitle: Making a workspace portable using a devfile -:keywords: end-user-guide, making-a-workspace-portable-using-a-devfile -:page-aliases: .:making-a-workspace-portable-using-a-devfile - -include::partial$assembly_making-a-workspace-portable-using-a-devfile.adoc[] diff --git a/modules/end-user-guide/pages/provisioning-jetbrains-activation-code-for-offline-use.adoc b/modules/end-user-guide/pages/provisioning-jetbrains-activation-code-for-offline-use.adoc deleted file mode 100644 index 0c1d2eda6a..0000000000 --- a/modules/end-user-guide/pages/provisioning-jetbrains-activation-code-for-offline-use.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="provisioning-jetbrains-activation-code-for-offline-use"] -// = Provision activation code for offline usage -:navtitle: Provisioning activation code for offline use -:keywords: end-user-guide, jetbrains-activation-code-for-offline-use - -include::partial$proc_provisioning-jetbrains-activation-code-for-offline-use.adoc[] 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 new file mode 100644 index 0000000000..04cecdaabd --- /dev/null +++ b/modules/end-user-guide/pages/provisioning-the-jetbrains-offline-activation-code.adoc @@ -0,0 +1,6 @@ +[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/restarting-a-che-workspace-in-debug-mode-after-start-failure.adoc b/modules/end-user-guide/pages/restarting-a-che-workspace-in-debug-mode-after-start-failure.adoc deleted file mode 100644 index ba5d97c538..0000000000 --- a/modules/end-user-guide/pages/restarting-a-che-workspace-in-debug-mode-after-start-failure.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="restarting-a-che-workspace-in-debug-mode-after-start-failure"] -// = Restarting a workspace in debug mode after start failure -:navtitle: Restarting a workspace in debug mode after start failure -:keywords: end-user-guide, restarting-a-che-workspace-in-debug-mode-after-start-failure -:page-aliases: .:restarting-a-che-workspace-in-debug-mode-after-start-failure - -include::partial$proc_restarting-a-che-workspace-in-debug-mode-after-start-failure.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 new file mode 100644 index 0000000000..abc64dfca5 --- /dev/null +++ b/modules/end-user-guide/pages/running-a-workspace-with-dashboard.adoc @@ -0,0 +1,6 @@ +[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/pages/starting-a-che-workspace-in-debug-mode.adoc b/modules/end-user-guide/pages/starting-a-che-workspace-in-debug-mode.adoc deleted file mode 100644 index 451abda339..0000000000 --- a/modules/end-user-guide/pages/starting-a-che-workspace-in-debug-mode.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="starting-a-che-workspace-in-debug-mode"] -// = Starting a workspace in debug mode -:navtitle: Starting a workspace in debug mode -:keywords: end-user-guide, starting-a-che-workspace-in-debug-mode -:page-aliases: .:starting-a-che-workspace-in-debug-mode - -include::partial$proc_starting-a-che-workspace-in-debug-mode.adoc[] diff --git a/modules/end-user-guide/pages/support-for-jetbrains-ides.adoc b/modules/end-user-guide/pages/support-for-jetbrains-ides.adoc deleted file mode 100644 index d56c996c67..0000000000 --- a/modules/end-user-guide/pages/support-for-jetbrains-ides.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="support-for-jetbrains-ides"] -// = JetBrains IDEs -:navtitle: JetBrains IDEs -:keywords: end-user-guide, jetbrains-ides -// :page-aliases: .:jetbrains-ides - -include::partial$con_support-for-jetbrains-ides.adoc[] 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 new file mode 100644 index 0000000000..6c99ed38d2 --- /dev/null +++ b/modules/end-user-guide/pages/support-for-theia-based-ides.adoc @@ -0,0 +1,7 @@ +[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/using-jetbrains-intellij-idea-community-edition.adoc b/modules/end-user-guide/pages/using-jetbrains-intellij-idea-community-edition.adoc deleted file mode 100644 index 9e4152fe56..0000000000 --- a/modules/end-user-guide/pages/using-jetbrains-intellij-idea-community-edition.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="using-jetbrains-intellij-idea-community-edition"] -// = IntelliJ Idea Community Edition -:navtitle: Using IntelliJ Idea Community Edition -:keywords: end-user-guide, jetbrains-intellij-idea-community-edition - -include::partial$proc_using-jetbrains-intellij-idea-community-edition.adoc[] diff --git a/modules/end-user-guide/pages/using-jetbrains-intellij-idea-ultimate-edition.adoc b/modules/end-user-guide/pages/using-jetbrains-intellij-idea-ultimate-edition.adoc deleted file mode 100644 index 5ae5ebaf23..0000000000 --- a/modules/end-user-guide/pages/using-jetbrains-intellij-idea-ultimate-edition.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="using-jetbrains-intellij-idea-ultimate-edition"] -// = IntelliJ Idea Ultimate Edition -:navtitle: Using IntelliJ Idea Ultimate Edition -:keywords: end-user-guide, jetbrains-intellij-idea-ultimate-edition - -include::partial$proc_using-jetbrains-intellij-idea-ultimate-edition.adoc[] diff --git a/modules/end-user-guide/pages/using-jetbrains-webstorm.adoc b/modules/end-user-guide/pages/using-jetbrains-webstorm.adoc deleted file mode 100644 index 41b57aa781..0000000000 --- a/modules/end-user-guide/pages/using-jetbrains-webstorm.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="using-jetbrains-webstorm"] -// = WebStorm -:navtitle: Using WebStorm -:keywords: end-user-guide, jetbrains-webstorm - -include::partial$proc_using-jetbrains-webstorm.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 new file mode 100644 index 0000000000..34c5afc8c0 --- /dev/null +++ b/modules/end-user-guide/pages/using-private-container-registries.adoc @@ -0,0 +1,7 @@ +[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/workspaces-overview.adoc b/modules/end-user-guide/pages/workspaces-overview.adoc index ad19c2c638..3c7177faef 100644 --- a/modules/end-user-guide/pages/workspaces-overview.adoc +++ b/modules/end-user-guide/pages/workspaces-overview.adoc @@ -2,6 +2,6 @@ // = Using developer workspaces :navtitle: Using developer workspaces :keywords: end-user-guide, workspaces-overview -:page-aliases: .:workspaces-overview, .:what-are-workspaces.html +: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_accessing-che-from-openshift-developer-perspective.adoc b/modules/end-user-guide/partials/assembly_accessing-che-from-openshift-developer-perspective.adoc index 6a9207945f..a49baa5469 100644 --- a/modules/end-user-guide/partials/assembly_accessing-che-from-openshift-developer-perspective.adoc +++ b/modules/end-user-guide/partials/assembly_accessing-che-from-openshift-developer-perspective.adoc @@ -7,14 +7,20 @@ :context: accessing-{prod-id-short}-from-openshift-developer-perspective -OpenShift Container Platform provides a view switcher to make a transition between: -* *Administrator* - The traditional administration-focused console. -* *Developer* - A high-level of abstraction over {platforms-name} components to allow developers to focus on application development. +The OpenShift Container Platform web console provides two perspectives; the *Administrator* perspective and the *Developer* perspective. -The OpenShift Developer Perspective enables a developer-focused view in the OpenShift 4 web console. +The Developer perspective provides workflows specific to developer use cases, such as the ability to: -NOTE: OpenShift Developer Perspective is a default part of OpenShift Container Platform starting with version 4.2. +* Create and deploy applications on 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. + +* Group components within an application and connect the components within and across applications. + +* Integrate serverless capabilities (Technology Preview). + +* Create workspaces to edit your application code using {prod-short}. include::partial$con_openshift-developer-perspective-integration-with-che.adoc[leveloffset=+1] 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 index a5f1810b74..7d9e0d72d4 100644 --- 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 @@ -9,14 +9,14 @@ :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 *{prod-short} Plugins* panel or the workspace configuration. +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-che-plugins-panel.adoc[leveloffset=+1] - 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 index 9be96ae145..35368f111a 100644 --- 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 @@ -10,7 +10,7 @@ When installed in a workspace, {prod-short} plug-ins bring new capabilities to { * 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. +* Enhanced code navigation, auto-completion, and error highlighting. This chapter provides basic information about installing, enabling, and using {prod-short} plug-ins in workspaces. 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 new file mode 100644 index 0000000000..31ac9e0864 --- /dev/null +++ b/modules/end-user-guide/partials/assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc @@ -0,0 +1,26 @@ + + +: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 new file mode 100644 index 0000000000..cddafd49b9 --- /dev/null +++ b/modules/end-user-guide/partials/assembly_authoring-devfiles-version-1.adoc @@ -0,0 +1,22 @@ +: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 new file mode 100644 index 0000000000..d6280d20b9 --- /dev/null +++ b/modules/end-user-guide/partials/assembly_authoring-devfiles-version-2.adoc @@ -0,0 +1,22 @@ +: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 new file mode 100644 index 0000000000..7a8efd2b10 --- /dev/null +++ b/modules/end-user-guide/partials/assembly_authoring-devfiles.adoc @@ -0,0 +1,12 @@ +: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 new file mode 100644 index 0000000000..ea2ad76d82 --- /dev/null +++ b/modules/end-user-guide/partials/assembly_building-images-for-ides-based-on-the-intellij-platform.adoc @@ -0,0 +1,18 @@ +: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-remote-plugin-image.adoc b/modules/end-user-guide/partials/assembly_che-theia-remote-plugin-image.adoc index 523c8d2744..a517d1542c 100644 --- 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 @@ -17,8 +17,8 @@ The remote plug-in endpoint executable command is stored in the environment vari {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. +* 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] diff --git a/modules/end-user-guide/partials/assembly_che-theia-troubleshooting.adoc b/modules/end-user-guide/partials/assembly_che-theia-troubleshooting.adoc index 7e76a75307..193745d00f 100644 --- a/modules/end-user-guide/partials/assembly_che-theia-troubleshooting.adoc +++ b/modules/end-user-guide/partials/assembly_che-theia-troubleshooting.adoc @@ -7,7 +7,7 @@ :context: che-theia-troubleshooting -This section describes some of the most frequent issues with the Che-Theia IDE. +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.`:: 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 new file mode 100644 index 0000000000..2c3def6605 --- /dev/null +++ b/modules/end-user-guide/partials/assembly_configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc @@ -0,0 +1,31 @@ +: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-using-a-devfile.adoc b/modules/end-user-guide/partials/assembly_configuring-a-workspace-using-a-devfile.adoc deleted file mode 100644 index 3ee0f6b6e6..0000000000 --- a/modules/end-user-guide/partials/assembly_configuring-a-workspace-using-a-devfile.adoc +++ /dev/null @@ -1,31 +0,0 @@ - - -:parent-context-of-configuring-a-workspace-using-a-devfile: {context} - -[id="configuring-a-workspace-using-a-devfile_{context}"] -= Configuring a workspace using a devfile - -:context: configuring-a-workspace-using-a-devfile - -To quickly and easily configure a {prod-short} workspace, use a devfile. For an introduction to devfiles and instructions for their use, see the instructions in this section. - -include::partial$con_what-is-a-devfile.adoc[leveloffset=+1] - -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_creating-a-workspace-using-chectl-and-a-local-devfile.adoc[leveloffset=+1] - -include::partial$proc_allowing-users-to-define-workspace-deployment-labels-and-annotations.adoc[leveloffset=+1] - - -.Additional resources - -* xref:making-a-workspace-portable-using-a-devfile.adoc[] - -:context: {parent-context-of-configuring-a-workspace-using-a-devfile} 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 new file mode 100644 index 0000000000..69b3c30d9d --- /dev/null +++ b/modules/end-user-guide/partials/assembly_configuring-a-workspace-with-dashboard.adoc @@ -0,0 +1,21 @@ + +// 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_configuring-oauth-authorization.adoc b/modules/end-user-guide/partials/assembly_configuring-oauth-authorization.adoc deleted file mode 100644 index 890bfe830f..0000000000 --- a/modules/end-user-guide/partials/assembly_configuring-oauth-authorization.adoc +++ /dev/null @@ -1,14 +0,0 @@ - - -:parent-context-of-configuring-oauth-authorization: {context} - -[id="configuring-oauth-authorization_{context}"] -= Configuring OAuth authorization - -:context: configuring-oauth-authorization - -This section describes how to connect {prod} as an OAuth application to supported OAuth providers. - -* xref:configuring-openshift-oauth.adoc[] - -:context: {parent-context-of-configuring-oauth-authorization} 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 new file mode 100644 index 0000000000..ada5f13036 --- /dev/null +++ b/modules/end-user-guide/partials/assembly_creating-a-workspace-from-a-code-sample.adoc @@ -0,0 +1,23 @@ +[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 new file mode 100644 index 0000000000..e65980666f --- /dev/null +++ b/modules/end-user-guide/partials/assembly_creating-a-workspace-from-a-template-devfile.adoc @@ -0,0 +1,33 @@ +// 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-code-sample.adoc b/modules/end-user-guide/partials/assembly_creating-a-workspace-from-code-sample.adoc deleted file mode 100644 index 42b0287aa6..0000000000 --- a/modules/end-user-guide/partials/assembly_creating-a-workspace-from-code-sample.adoc +++ /dev/null @@ -1,28 +0,0 @@ - - -:parent-context-of-creating-a-workspace-from-code-sample: {context} - -[id="creating-a-workspace-from-code-sample_{context}"] -= Creating a workspace from code sample - -:context: creating-a-workspace-from-code-sample - -Every stack includes a sample codebase, which is defined by the devfile of the stack. This section explains how to create a workspace from this code sample in a sequence of three procedures. - -. Creating a workspace from the user dashboard: -.. Using the xref:creating-a-workspace-from-get-started-view-of-user-dashboard_{context}[Get Started view]. -.. Using the xref:creating-a-workspace-from-custom-workspace-view-of-user-dashboard_{context}[Custom Workspace view]. -. xref:changing-the-configuration-of-an-existing-workspace_{context}[Changing the configuration of the workspace] to add code sample. -. xref:running-an-existing-workspace-from-the-user-dashboard_{context}[Running an existing workspace from the user dashboard]. - -For more information about devfiles, see xref:configuring-a-workspace-using-a-devfile.adoc[]. - -include::partial$proc_creating-a-workspace-from-user-dashboard-get-started.adoc[leveloffset=+1] - -include::partial$proc_creating-a-workspace-from-user-dashboard.adoc[leveloffset=+1] - -include::partial$proc_changing-the-configuration-of-an-existing-workspace.adoc[leveloffset=+1] - -include::partial$assembly_running-an-existing-workspace-from-the-user-dashboard.adoc[leveloffset=+1] - -:context: {parent-context-of-creating-a-workspace-from-code-sample} 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 new file mode 100644 index 0000000000..9c63b032ca --- /dev/null +++ b/modules/end-user-guide/partials/assembly_creating-a-workspace-from-remote-devfile.adoc @@ -0,0 +1,28 @@ + + +: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_creating-and-configuring-a-new-workspace.adoc b/modules/end-user-guide/partials/assembly_creating-and-configuring-a-new-workspace.adoc deleted file mode 100644 index a818a20367..0000000000 --- a/modules/end-user-guide/partials/assembly_creating-and-configuring-a-new-workspace.adoc +++ /dev/null @@ -1,17 +0,0 @@ - -// using-developer-environments-workspaces - -:parent-context-of-creating-and-configuring-a-new-workspace: {context} - -[id="creating-and-configuring-a-new-workspace_{context}"] -= Creating and configuring a new {prod-short} {prod-ver} workspace - -:context: creating-and-configuring-a-new-workspace - -include::partial$proc_creating-a-new-workspace-from-the-dashboard.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] - -:context: {parent-context-of-creating-and-configuring-a-new-workspace} diff --git a/modules/end-user-guide/partials/assembly_customizing-developer-environments.adoc b/modules/end-user-guide/partials/assembly_customizing-developer-environments.adoc index a849d11789..a6d96f3295 100644 --- a/modules/end-user-guide/partials/assembly_customizing-developer-environments.adoc +++ b/modules/end-user-guide/partials/assembly_customizing-developer-environments.adoc @@ -15,6 +15,10 @@ You can extend {prod} in three different ways: * *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:[] + +pass:[] + * *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 @@ -25,5 +29,10 @@ A user can extend {prod-short} by using `self-hosted` mode, which {prod-short} p * 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:[] + +pass:[] :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 index ebdb4c0e5b..a685fcf07b 100644 --- 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 @@ -17,7 +17,7 @@ This is useful, for example, for: * Allowing lead developers to customize workspaces based on team requirements. * Reducing time needed to onboard new team members. -See also xref:configuring-a-workspace-using-a-devfile.adoc[]. +See also xref:authoring-devfiles-version-2.adoc[]. include::partial$con_che-theia-task-types.adoc[leveloffset=+1] 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 index 19c67da178..54f43b68c3 100644 --- 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 @@ -3,25 +3,25 @@ :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 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 :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 multi-host, there’re differences in how Che-Theia Webview API works. +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 a multi-host mode +== Webview in multihost mode -When {prod} is deployed in a multi-host 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: +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 a 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. +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 index f7e609cc25..e60022db45 100644 --- 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 @@ -7,31 +7,12 @@ :context: importing-kubernetes-applications-into-a-workspace -This section describes how to import {platforms-name} applications into a {prod-short} workspace. +To deploy a new instance of an application in a {prod-short} workspace, use one of the following scenarios: -For demonstration purposes, the section uses a sample {platforms-name} application having the following two Pods: +* 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}`] -* A Node.js application specified by this link:https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/nodejs-app.yaml[nodejs-app.yaml] - -* A MongoDB Pod specified by this link:https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/mongo-db.yaml[mongo-db.yaml] - -To run the application on a {platforms-name} cluster: - -[subs="+attributes"] ----- -$ node=https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/nodejs-app.yaml && \ -mongo=https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/mongo-db.yaml && \ -{orch-cli} apply -f $\{mongo} && \ -{orch-cli} apply -f $\{node} ----- - -To deploy a new instance of this application in a {prod-short} workspace, use one of the following three scenarios: - -* Starting from scratch: link:#including-kubernetes-applications-in-a-workspace-devfile-definition_{context}[Writing a new devfile] -* Modifying an existing workspace: link:#adding-a-kubernetes-application-to-an-existing-workspace-using-the-dashboard_{context}[Using the Dashboard user interface] -* From a running application: link:#generating-a-devfile-from-an-existing-kubernetes-application_{context}[Generating a devfile with `{prod-cli}`] - -include::partial$proc_including-kubernetes-applications-in-a-workspace-devfile-definition.adoc[leveloffset=+1] +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] diff --git a/modules/end-user-guide/partials/assembly_making-a-workspace-portable-using-a-devfile.adoc b/modules/end-user-guide/partials/assembly_making-a-workspace-portable-using-a-devfile.adoc deleted file mode 100644 index 0800a5a679..0000000000 --- a/modules/end-user-guide/partials/assembly_making-a-workspace-portable-using-a-devfile.adoc +++ /dev/null @@ -1,26 +0,0 @@ - - -:parent-context-of-making-a-workspace-portable-using-a-devfile: {context} - -[id="making-a-workspace-portable-using-a-devfile_{context}"] -= Making a workspace portable using a devfile - -:context: making-a-workspace-portable-using-a-devfile - -To transfer a configured {prod-short} workspace, create and export the devfile of the workspace and load the devfile on a different host to initialize a new instance of the workspace. For detailed instructions on how to create such a devfile, see below. - -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] - -.Additional resources - -* link:https://redhat-developer.github.io/devfile/devfile[Devfile specifications] - -:context: {parent-context-of-making-a-workspace-portable-using-a-devfile} 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/partials/assembly_mounting-secrets-as-file-or-env-variable-in-workspace-container.adoc index af3e8146f8..c0ff2b5896 100644 --- a/modules/end-user-guide/partials/assembly_mounting-secrets-as-file-or-env-variable-in-workspace-container.adoc +++ b/modules/end-user-guide/partials/assembly_mounting-secrets-as-file-or-env-variable-in-workspace-container.adoc @@ -11,6 +11,8 @@ Secrets are {platforms-name} objects that store sensitive data such as user name Users can mount a secret that contains sensitive data in a workspace container. This reapplies the stored data from the secret automatically for every newly created workspace. As a result, the user does not have to provide these credentials and configuration settings manually. +Do not mount secrets that you define in a devfile. + The following section describes how to automatically mount a {platforms-name} secret in a workspace container and create permanent mount points for components such as: * Maven configuration, the `settings.xml` file 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 index 19673c7a79..155b939d92 100644 --- 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 @@ -7,7 +7,7 @@ :context: navigating-{prod-id-short}-using-the-dashboard -The *Dashboard* is accessible on your cluster from a URL like `http://__<{prod-url}>__/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 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 index 422a9bbc42..d8b7ee7ae2 100644 --- 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 @@ -1,11 +1,11 @@ :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 += 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. +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] diff --git a/modules/end-user-guide/partials/assembly_troubleshooting-che.adoc b/modules/end-user-guide/partials/assembly_troubleshooting-che.adoc index 63e1e5ddd1..1f97738165 100644 --- a/modules/end-user-guide/partials/assembly_troubleshooting-che.adoc +++ b/modules/end-user-guide/partials/assembly_troubleshooting-che.adoc @@ -12,9 +12,8 @@ This section provides troubleshooting procedures for the most frequent issues a .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[] -* xref:starting-a-che-workspace-in-debug-mode.adoc[] -* xref:restarting-a-che-workspace-in-debug-mode-after-start-failure.adoc[] :context: {parent-context-of-troubleshooting-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 index 125ade8c68..e493af2d33 100644 --- 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 @@ -7,34 +7,10 @@ :context: using-alternative-ides-in-che -Extending {prod} developer workspaces using different IDEs (integrated development environments) enables: +{prod} provides a default web IDE to use in the developer workspaces. To use another editor, see: -* Re-purposing the environment for different use cases. +* xref:configuring-a-workspace-to-use-an-ide-based-on-the-intellij-platform.adoc[] -* Providing a dedicated custom IDE for specific tools. - -* Providing different perspectives for individual users or groups of users. - -// In the traditional Eclipse IDE world, that was done with RCP applications. -// find out what's RCP? - -{prod} provides a default web IDE to be used with the developer workspaces. This IDE is completely decoupled. You can bring your own custom IDE for {prod}: - -* *Built from Eclipse Theia*, which is a framework to build web IDEs. Example: link:https://www.youtube.com/watch?v=B6aCqywKpyY[Sirius on the web]. -// TODO: Learn more link:[LINK]. - -* *Completely different web IDEs*, such as Jupyter, Eclipse Dirigible, or others. Example: link:https://www.youtube.com/watch?v=VooNzKxRFgw[Jupyter in {prod} workspaces]. - -.Bringing custom IDE built from Eclipse Theia - -* Creating your own custom IDE based on Eclipse Theia. -* Adding {prod-short}-specific tools to your custom IDE. -* Packaging your custom IDE into the available editors for {prod-short}. -// TODO: all bullets needs links to docs - -.Bringing your completely different web IDE into {prod-short} - -* Packaging your custom IDE into the available editors for {prod-short}. -// TODO: bullet needs a link to docs +* 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 index fa258a7ff4..6398f7de01 100644 --- 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 @@ -7,7 +7,7 @@ :context: using-artifact-repositories-in-a-restricted-environment -This section describes how to manually configure various technology stacks to work with artifacts from in-house repositories using self-signed certificates. +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[] 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 index 1c5cc6d4b2..b1ec944c3c 100644 --- a/modules/end-user-guide/partials/assembly_using-go-artifact-repositories.adoc +++ b/modules/end-user-guide/partials/assembly_using-go-artifact-repositories.adoc @@ -8,13 +8,15 @@ :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 datastore and proxy. +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[GitHub - gomods/athens: A Go module datastore and proxy] + +* 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 index cc8a7c2f72..461eb66704 100644 --- a/modules/end-user-guide/partials/assembly_using-gradle-artifact-repositories.adoc +++ b/modules/end-user-guide/partials/assembly_using-gradle-artifact-repositories.adoc @@ -8,6 +8,8 @@ :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] diff --git a/modules/end-user-guide/partials/assembly_viewing-logs-for-dotnet-with-netcoredebugoutput-plug-in.adoc b/modules/end-user-guide/partials/assembly_viewing-logs-for-dotnet-with-netcoredebugoutput-plug-in.adoc index 2c62256784..b4ff309a9a 100644 --- a/modules/end-user-guide/partials/assembly_viewing-logs-for-dotnet-with-netcoredebugoutput-plug-in.adoc +++ b/modules/end-user-guide/partials/assembly_viewing-logs-for-dotnet-with-netcoredebugoutput-plug-in.adoc @@ -3,7 +3,7 @@ :parent-context-of-viewing-logs-for-dotnet-with-netcoredebugoutput-plug-in: {context} [id="viewing-logs-for-dotnet-with-netcoredebugoutput-plug-in_{context}"] -= Viewing logs for Dotnet with NetcoredebugOutput plug-in += Viewing logs for .NET with NetcoredebugOutput plug-in :context: viewing-logs-for-dotnet-with-netcoredebugoutput-plug-in diff --git a/modules/end-user-guide/partials/assembly_viewing-logs-for-dotnet-with-omnisharp-theia-plug-in.adoc b/modules/end-user-guide/partials/assembly_viewing-logs-for-dotnet-with-omnisharp-theia-plug-in.adoc index 1a595dfd1d..1f62848737 100644 --- a/modules/end-user-guide/partials/assembly_viewing-logs-for-dotnet-with-omnisharp-theia-plug-in.adoc +++ b/modules/end-user-guide/partials/assembly_viewing-logs-for-dotnet-with-omnisharp-theia-plug-in.adoc @@ -3,7 +3,7 @@ :parent-context-of-viewing-logs-for-dotnet-with-omnisharp-theia-plug-in: {context} [id="viewing-logs-for-dotnet-with-omnisharp-theia-plug-in_{context}"] -= Viewing logs for Dotnet with Omnisharp-Theia plug-in += Viewing logs for .NET with OmniSharp-Theia plug-in :context: viewing-logs-for-dotnet-with-omnisharp-theia-plug-in 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 index 8a82c8e93b..12bb5ff58c 100644 --- 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 @@ -16,8 +16,8 @@ Extending Che-Theia using plug-ins can enable the following capabilities: * *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, formatters, and syntax highlighting:* Enhance comfort of use with supported programming languages. -* *Keybindings:* Add new keymaps and popular keybindings to make the environment feel natural. +* *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 diff --git a/modules/end-user-guide/partials/assembly_workspaces-overview.adoc b/modules/end-user-guide/partials/assembly_workspaces-overview.adoc index ef32aea877..b1812711be 100644 --- a/modules/end-user-guide/partials/assembly_workspaces-overview.adoc +++ b/modules/end-user-guide/partials/assembly_workspaces-overview.adoc @@ -7,12 +7,12 @@ :context: developer-workspaces -{prod} provides developer workspaces with everything needed to a code, build, test, run, and debug applications. To allow that, the developer workspaces provide four main components: +{prod} provides developer workspaces with everything you need to code, build, test, run, and debug applications: -. The source code of a project. -. A 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. +* 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. @@ -20,15 +20,15 @@ The embedded browser-based IDE is the point of access for everything running in [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, patch the checluster: +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"] ---- -$ oc patch checluster {prod-checluster} -n {prod-namespace} --type=merge \ +$ {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[Users workspace limits]. +For additional information, see: xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc#users-workspace-limits[]. ==== @@ -55,7 +55,7 @@ For additional information, see: xref:installation-guide:advanced-configuration- | No. Or not easily | Yes. Developer workspaces are shareable with a URL. -| Versionable +| Capable of being versioned | No | Yes. Devfiles exist with project source code. @@ -64,19 +64,18 @@ For additional information, see: xref:installation-guide:advanced-configuration- | Yes. Only requires a browser. |=== -To start a {prod-short} workspace, following options are available: +Start a {prod-short} workspace: -* xref:creating-and-configuring-a-new-workspace.adoc[] -* xref:configuring-a-workspace-using-a-devfile.adoc[] +* xref:configuring-a-workspace-with-dashboard.adoc[] Use the Dashboard to discover {prod-short} {prod-ver}: -* xref:creating-a-workspace-from-code-sample.adoc[] -* xref:creating-a-workspace-by-importing-source-code-of-a-project.adoc[] +* 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:making-a-workspace-portable-using-a-devfile.adoc[] +* 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[]. diff --git a/modules/end-user-guide/partials/con_a-minimal-devfile.adoc b/modules/end-user-guide/partials/con_a-minimal-devfile.adoc index daa0e7ffa5..d76b4f7d99 100644 --- a/modules/end-user-guide/partials/con_a-minimal-devfile.adoc +++ b/modules/end-user-guide/partials/con_a-minimal-devfile.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// making-a-workspace-portable-using-a-devfile +// configuring-a-workspace-using-a-devfile [id="a-minimal-devfile_{context}"] = A minimal devfile @@ -17,7 +17,7 @@ metadata: name: {project-context}-in-{project-context}-out ---- -For a complete devfile example, see link:https://github.com/eclipse/che/blob/master/devfile.yaml[{prod} in {prod-short} devfile.yaml]. +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] ==== 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 index fb6121e4ed..42741f9035 100644 --- 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 @@ -5,7 +5,7 @@ [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 oc 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. +{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. @@ -14,15 +14,13 @@ The Che-Theia IDE is generally compatible with the VS Code extensions API and VS .Adding a plug-in * Using the Dashboard: -** Add a plug-in from the plug-in registry using the *Plugins* tab in the *Workspace details* page. - ** 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 usage. +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:making-a-workspace-portable-using-a-devfile.adoc#adding-components-to-a-devfile_{context}[] +* 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 index ea670dd707..663b84fdf1 100644 --- 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 @@ -26,11 +26,9 @@ The same Che-Theia plug-in API is exposed to plug-ins running on the client side [id="che-theia-plug-in-apis_{context}"] == Che-Theia plug-in APIs -For the purpose of providing 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. -// TODO: VS Code extensions as Che-Theia plug-ins. Read more at link:[LINK]. +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. -// TODO: Learn more about the {prod-short} APIs at link:[LINK]. [id="che-theia-plug-in-capabilities_{context}"] @@ -46,27 +44,27 @@ Che-Theia plug-ins have the following capabilities: | *{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-theia/tree/master/plugins/task-plugin[Task plug-in] +|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-theia/tree/master/extensions/eclipse-che-theia-terminal[Extended Terminal extension] +|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-theia/tree/master/plugins/workspace-plugin[Workspace plug-in] +|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-theia/tree/master/plugins/containers-plugin[Containers plug-in] +| 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-theia/tree/master/extensions/eclipse-che-theia-dashboard[Che-Theia Dashbord extension] +|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-theia/tree/master/extensions/eclipse-che-theia-plugin-ext[Che-Theia API extension] +|link:https://github.com/eclipse-che/che-theia/tree/master/extensions/eclipse-che-theia-plugin-ext[Che-Theia API extension] |=== @@ -79,7 +77,6 @@ A Che-Theia plug-in can be based on a VS Code extension or an Eclipse Theia plug 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}. -// TODO: Learn more about how to package a Che-Theia plug-in at link:[LINK]. .Additional resources 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 index be51553023..afd8f10950 100644 --- 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 @@ -1,6 +1,6 @@ // This assembly is included in the following assemblies: // -// what-is-a-che-theia-plug-in +// `what-is-a-che-theia-plug-in` [id="che-theia-plug-in-lifecycle_{context}"] = Che-Theia plug-in lifecycle @@ -14,7 +14,6 @@ Every time a user starts a Che workspace, a Che-Theia plug-in life cycle process NOTE: Plug-ins exist in various types. A broker ensures the success of a plug-in deployment by meeting all installation requirements. -// TODO: plug-in types (link:link[LINK]) .Che-Theia plug-in lifecycle 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 index b2b785cdee..513a073233 100644 --- a/modules/end-user-guide/partials/con_che-theia-task-types.adoc +++ b/modules/end-user-guide/partials/con_che-theia-task-types.adoc @@ -52,17 +52,16 @@ The {prod-short} commands are to be used to define tasks that will be executed i * 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:: `Attach remote debugger` + -VS Code launch configurations are usually 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.). +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]. +* 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*. Launch configurations are available in the Che-Theia debugger. +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 -.Examples -* link:https://github.com/eclipse/che-devfile-registry/blob/master/devfiles/quarkus-command-mode/devfile.yaml#L63-L71[An example of a theia task] -* link:https://github.com/eclipse/che-devfile-registry/blob/master/devfiles/quarkus-command-mode/devfile.yaml#L84-L100[An example of a vscode-launch task] +* 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_support-for-jetbrains-ides.adoc b/modules/end-user-guide/partials/con_support-for-jetbrains-ides.adoc deleted file mode 100644 index 2065142c09..0000000000 --- a/modules/end-user-guide/partials/con_support-for-jetbrains-ides.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="con_support-for-jetbrains-ides_{context}"] -= Support for JetBrains IDEs - -This section contains information about supported JetBrains IDEs that can be used in {prod} workspaces. - -{prod} supports running a workspace with the following list of JetBrains IDEs: - -* IntelliJ Idea Community Edition -* IntelliJ Idea Ultimate Edition -* WebStorm - -List of JetBrains IDEs that are planned to be supported: - -* GoLand -* PhpStorm -* PyCharm Professional Edition -* PyCharm Community Edition - -NOTE: The version of supported JetBrains products should is 2018.1 or higher. - -The following sections describe how to create an image with a specific IDE and workspace based on the built image: - -* xref:using-jetbrains-intellij-idea-community-edition.adoc[] -* xref:using-jetbrains-intellij-idea-ultimate-edition.adoc[] -* xref:using-jetbrains-webstorm.adoc[] 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 new file mode 100644 index 0000000000..1b757ef8c6 --- /dev/null +++ b/modules/end-user-guide/partials/con_support-for-theia-based-ides.adoc @@ -0,0 +1,61 @@ +[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: "" + mountSources: true + ports: + - exposedPort: 3100 + memoryLimit: "512M" +---- ++ +`targetPort` and `exposedPort` must be the same as the Theia-based IDE running inside the container. +Replace `` 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: '' +---- ++ +`` 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 index 3d1c91479c..3845dd6d1c 100644 --- a/modules/end-user-guide/partials/con_what-is-a-devfile.adoc +++ b/modules/end-user-guide/partials/con_what-is-a-devfile.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: // // configuring-a-workspace-using-a-devfile -// making-a-workspace-portable-using-a-devfile +// configuring-a-workspace-using-a-devfile [id="what-is-a-devfile_{context}"] @@ -16,7 +16,7 @@ A devfile is a file that describes and define a development environment: 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. +* 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]. @@ -27,7 +27,7 @@ Devfiles can be versioned with the project source code. When there is a need for {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. +* 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-ssh.adoc b/modules/end-user-guide/partials/proc_accessing-a-git-repository-via-ssh.adoc index bfdcf2b536..d5e337e67f 100644 --- 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 @@ -7,19 +7,19 @@ == Generating an SSH key using the {prod-short} command palette -The following section describes a generation of an SSH key using the {prod-short} command palette and its further use in Git provider communication. This SSH key restricts permissions for the specific Git provider, therefore, the user has to create a unique SSH key for each Git provider in use. +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:creating-and-configuring-a-new-workspace.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 -A common SSH key pair that works with all the Git providers is present by default. To start using it, add the public key to the Git provider. - . 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. @@ -28,13 +28,13 @@ The *command palette* can be also activated by pressing kbd:[Ctrl+Shift+p] (or k ** Search for *SSH: generate key pair for particular host* by entering `generate` into the search box and pressing kbd:[Enter] once filled. -** Provide the hostname for the SSH key pair such as, for example, `github.com`. +** 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. + -You can now use another command from the command palette: *Clone git repository* by providing an SSH secured URL. +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 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 6dda5b4f17..1745d9a7da 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 @@ -13,11 +13,11 @@ This section describes how to access {prod-short} workspaces from the *Red Hat A .Procedure -. Open the *Red Hat Applications* menu by clicking the three-by-three matrix icon in the upper right corner of the main screen. +. Open the *Red Hat Applications* menu by using the three-by-three matrix icon in the upper right corner of the main screen. + The drop-down menu displays the available applications. + -image::installation/{project-context}-red-hat-application-menu-che-odp.png[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="../_images/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 index f6ae38e760..148d6d600f 100644 --- 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 @@ -53,7 +53,7 @@ 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: +. 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"] -- 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 index 79e41ce54a..a05be8a896 100644 --- 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 @@ -9,20 +9,13 @@ This procedure demonstrates how to modify an existing workspace and import the { .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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} xref:creating-and-configuring-a-new-workspace.adoc[]. +* An existing workspace defined on this instance of {prod-short}. .Procedure -. After the creation of a workspace, use the *Workspace* menu and then the *Configure workspace* icon to manage the workspace. -+ -image::workspaces/configure-workspace.png[] - -. To modify the workspace details, use the *Devfile* tab. The workspace details are displayed in this tab in the devfile format. -+ -image::workspaces/configure-workspace-devfile.png[] - -. To add a {platforms-name} component, use the *Devfile* editor on the dashboard. +. 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 new file mode 100644 index 0000000000..d927b11c0d --- /dev/null +++ b/modules/end-user-guide/partials/proc_adding-a-vs-code-extension-to-the-che-plugin-registry.adoc @@ -0,0 +1,107 @@ +[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: <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 index 648cf75170..89c422057a 100644 --- 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 @@ -5,61 +5,57 @@ [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 an existing workspace by enabling a dedicated plug-in from the Dashboard. +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: +//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-from-the-plugin-tab_{context}[Enable the plug-in from the Dashboard *Plugins* tab.] * xref:installing-the-plug-in-by-adding-content-to-the-devfile_{context}[Edit the workspace devfile from the Dashboard *Devfile* tab.] -This procedure uses the Language Support for Java plug-in as an example. - .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. - -* An existing workspace defined in this instance of {prod}; see: -** xref:creating-and-configuring-a-new-workspace.adoc[] -** xref:creating-a-workspace-from-code-sample.adoc#creating-a-workspace-from-custom-workspace-view-of-user-dashboard_{context}[] - - * The workspace must be in a **stopped** state. To stop a workspace, +* A running instance of {prod-short}. ++ +See {link-installing-an-instance}. -.. Navigate to the {prod-short} Dashboard. See xref:navigating-che-using-the-dashboard.adoc[]. +* 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. -.. On the same row with the displayed workspace, on the right side of the screen, click the square btn:[Stop] button to stop the workspace. - -.. Wait a few seconds for the workspace to stop (the workspace's icon on the list will turn grey), then configure the workspace by clicking on it. - +//Is there a different section that describes the procedure on the previous lines? max-cx + .Procedure -To add the plug-in from the Plug-in registry to an existing {prod-short} workspace, use one of the following methods: - -[id="installing-the-plug-in-from-the-plugin-tab_{context}"] - -//<> - -** Installing the plug-in from the *Plugins* tab. -. Navigate to the *Plugins* tab. The list of available plug-ins is displayed. -. Enable the desired plug-in, for example, the Language Support for Java 11, by using the *Enable* slide-toggle. This will add the plug-in's ID to the workspace's devfile, enabling the plug-in. -. On the bottom right side of the screen, save the changes by clicking the btn:[Save] button. After changes are saved, the workspace can be restarted and will include the new plug-in. +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. -. Navigate to the *Devfile* tab. The devfile YAML is displayed. -. Locate the `components` section of the devfile and add the following lines to add the Java language plugin with Java 8 to the workspace: +//** 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[] + -An example of the final result: +.Example: The end result + include::example${project-context}-workspace-from-the-php-stack-java-language-support.adoc[] -. On the bottom right side of the screen, save the changes by clicking the btn:[Save] button. After changes are saved, the workspace can be restarted and will include the new plug-in. - +. Click btn:[Save] to save the changes. +. Restart the workspace. +. Verify that the workspace includes the new plug-in. .Additional resources 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 index 7615c7630f..470e586377 100644 --- 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 @@ -1,44 +1,30 @@ // Module included in the following assemblies: // -// creating-and-configuring-a-new-workspace +// configuring-a-workspace-with-dashboard [id="adding-projects-to-your-workspace_{context}"] = Adding projects to your workspace .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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}. See xref:creating-and-configuring-a-new-workspace.adoc[Creating and configuring a new {prod-short} {prod-ver} workspace]. +* An existing workspace defined on this instance of {prod-short}. .Procedure To add a project to your workspace: -. Navigate to *Workspaces* page and click the workspace you want to update. -+ -Here you have two ways to add a project to your workspace: - -. From the *Projects* tab. +. Navigate to the *Workspaces* page and click the workspace, which is about to be updated. -.. Open the *Projects* tab, and then click the btn:[Add Project] button. +. Open the *Devfile* tab. -.. Choose if you want to import the project by Git URL or from your GitHub account. -+ -image::workspaces/che-config-projects-add-git.png[Add Git Project, link="../_images/workspaces/che-config-projects-add-git.png"] - -. From the *Devfile* tab. - -.. Open the *Devfile* tab. - -.. In the *Devfile editor*, add `projects` section with desired project. +. 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] - -. Once the project is added, click btn:[Save] button to save this workspace configuration, or click btn:[Apply] button to apply changes to the running workspace. -+ -image::workspaces/workspace-save-apply-cancel.png[Save Workspace Configuration] 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 new file mode 100644 index 0000000000..e877b58aa3 --- /dev/null +++ b/modules/end-user-guide/partials/proc_adding-the-vs-code-extension-using-recommendations.adoc @@ -0,0 +1,21 @@ +// 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 index f2bde60085..e7d748cba5 100644 --- 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 @@ -7,14 +7,14 @@ .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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*. +. 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. 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 index 16b62ab626..2709d54c7e 100644 --- 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 @@ -7,9 +7,9 @@ .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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} xref:end-user-guide:creating-and-configuring-a-new-workspace.adoc[]. +* 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[]. @@ -17,7 +17,9 @@ To add a VS Code extension using the workspace configuration: -. Click the *Workspaces* tab on the *Dashboard* and select the workspace in which you want to add the plug-in. The *Workspace ____* window is opened showing the details of the workspace. +. Click the *Workspaces* tab on the *Dashboard* and select the plug-in destination workspace. ++ +The *Workspace ____* window is opened showing the details of the workspace. . Click the *devfile* tab. @@ -28,7 +30,7 @@ To add a VS Code extension using the workspace configuration: - type: chePlugin id: <1> ---- -<1> ID format: _//_ +<1> ID format: `_//_` + {prod-short} automatically adds the other fields to the new component. + 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 new file mode 100644 index 0000000000..4517e50953 --- /dev/null +++ b/modules/end-user-guide/partials/proc_allowing-users-to-define-workspace-creation-strategy.adoc @@ -0,0 +1,32 @@ +// 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 ____ is available over HTTPS. + + +.Procedure + +pass:[] + +* Run the workspace by opening the factory URL and specify the additional strategy parameter: ++ +`pass:c,a,q[{prod-url}/f?url=__&policies.create=__]` ++ + +pass:[] 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 index 451fc00861..adbe23e594 100644 --- 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 @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// configuring-a-workspace-using-a-devfile +// 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 @@ -9,14 +9,17 @@ This section describes how to customize workspace deployment labels and annotati .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:making-a-workspace-portable-using-a-devfile.adoc[] for detailed information about creating and using devfiles. +* 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://____/devfile.yaml&workspaceDeploymentLabels=____&workspaceDeploymentAnnotations=____]` -.Example of overriding the `deployment labels` +.Example of overriding the `deployment labels` +==== Consider the following labels to add: [subs="+quotes"] @@ -30,14 +33,13 @@ To add or override labels, use the following factory URL: [subs="+quotes"] ---- -https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&workspaceDeploymentLabels=ike.target%3Dpreference-v1%2Cike.session%3Dtest +https://workspaces.openshift.com/f?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: @@ -57,9 +59,11 @@ metadata: spec: ... ---- +==== .Example of overriding the `deployment annotations` +==== Consider the following annotations to add: [subs="+quotes"] @@ -73,7 +77,7 @@ To add or override annotations, use the following factory URL: [subs="+quotes"] ---- -https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&workspaceDeploymentAnnotations=ike.A1%3Dpreference-v1%2Cike.A%3Dtest +https://workspaces.openshift.com/f?url=____&workspaceDeploymentAnnotations=ike.A1%3Dpreference-v1%2Cike.A%3Dtest ---- @@ -81,7 +85,6 @@ The resulting workspace has the following deployment annotations: [subs="+quotes"] ---- ---- apiVersion: apps/v1 kind: Deployment metadata: @@ -100,3 +103,53 @@ metadata: resourceVersion: "213191" ... ---- +==== + +.Verification steps + +To display the deployment labels and annotations: + +. Get the name of the user's namespace: + +pass:[] + +.. Using {prod-short} Dashboard, move to the *Workspaces* tab and read the name of the *{orch-name} {namespace}* field. + +pass:[] + +. 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 __ -p __ __ +---- + +pass:[] + +. 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 ____ -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/____ -n ____ -o=custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,LABELS:.metadata.labels,ANNOTATIONS:.metadata.annotations" +---- +//// + +pass:[] \ 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 new file mode 100644 index 0000000000..07423473d6 --- /dev/null +++ b/modules/end-user-guide/partials/proc_building-an-image-for-an-ide-based-on-the-intellij-platform.adoc @@ -0,0 +1,177 @@ +[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 ____ --url ____ +---- ++ +`--tag ____`:: +The name and tag to apply to the image after build in `name:tag` format. ++ +`--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 ____ +---- ++ +.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: __/:__. + +. Create a `+meta.yaml+` file containing the IDE metadata for {prod-short}: ++ +[source,yaml,subs="+quotes,macros,attributes"] +---- +apiVersion: v2 +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: __/:__ <2> + mountSources: true + volumes: + - mountPath: "/home/projector-user" + name: projector-user + ports: + - exposedPort: 8887 + memoryLimit: "4096M" +---- +<1> `____`: Your publisher name. +<2> `__/:__`: 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 `____` 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 new file mode 100644 index 0000000000..feb6042bb5 --- /dev/null +++ b/modules/end-user-guide/partials/proc_building-an-image-for-intellij-idea-community-or-pycharm-community.adoc @@ -0,0 +1,99 @@ +[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: `__/:__`. + +. Create a `+meta.yaml+` file with the following content: ++ +[source,yaml,subs="+quotes,macros,attributes"] +---- +apiVersion: v2 +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: __/:__ <2> + mountSources: true + volumes: + - mountPath: "/home/projector-user" + name: projector-user + ports: + - exposedPort: 8887 + memoryLimit: "4096M" +---- +<1> `____`: Your publisher name. +<2> `__/:__`: 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 `____` 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 index 9fedfb4578..525ea79de2 100644 --- 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 @@ -1,17 +1,17 @@ // Module included in the following assemblies: // -// creating-a-workspace-from-code-sample +// 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. +This section describes how to change the configuration of an existing workspace from the user Dashboard. .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* A running instance of {prod-short}. See {link-installing-an-instance}. -* An existing workspace defined on this instance of {prod} xref:creating-and-configuring-a-new-workspace.adoc[]. +* An existing workspace defined on this instance of {prod-short}. .Procedure @@ -27,55 +27,6 @@ This section describes how to change the configuration of an existing workspace ** Select *Storage Type*. -** *Export* the workspace configuration to a file or private cloud. +** Review *{orch-namespace}*. -** *Delete* the workspace. -+ -image::workspaces/workspace-config-overview.png[Workspace configuration overview,link="../_images/workspaces/workspace-config-overview.png"] - -. In the *Projects* section, choose the projects to integrate in the workspace. - -.. Click the btn:[Add Project] button and do one of the following: - -... Enter the project Git repository URL to integrate in the workspace: -+ -image::workspaces/che-config-projects-add-git.png[Add project by URL to workspace,link="../_images/workspaces/che-config-projects-add-git.png"] - -... Connect your GitHub account and select projects to integrate: -+ -image::workspaces/che-config-projects-add-github.png[Add project from GitHub to workspace,link="../_images/workspaces/che-config-projects-add-github.png"] - -.. Click the btn:[Add] button. - -. In the *Plugins* section, choose the plug-ins to integrate in the workspace. -+ -[NOTE] -.Example -==== -Start with a generic Java-based stack, then add support for Node.js or Python. -==== - -. In the *Editors* section, choose the editors to integrate in the workspace. The {prod-short} {prod-ver} editor is based on Che-Theia. -+ -. From the *Devfile* tab, edit YAML configuration of the workspace. See xref:making-a-workspace-portable-using-a-devfile.adoc[]. -+ -[NOTE] -.Example: add commands -==== -image::workspaces/workspace-config-yaml.png[YAML configuration,link="../_images/workspaces/workspace-config-yaml.png"] -==== -+ -[NOTE] -.Example: add a project -==== -To add a project into the workspace, add or edit the following section: - -[source,yaml] ----- -projects: - - name: che - source: - type: git - location: 'https://github.com/eclipse/che.git' ----- -==== +. 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_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 similarity index 63% rename from modules/end-user-guide/partials/proc_including-kubernetes-applications-in-a-workspace-devfile-definition.adoc rename to modules/end-user-guide/partials/proc_che-including-kubernetes-applications-in-a-workspace-devfile-definition.adoc index 790c7e3a47..c2a4409974 100644 --- a/modules/end-user-guide/partials/proc_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 @@ -7,7 +7,7 @@ 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:making-a-workspace-portable-using-a-devfile.adoc[] section. +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 @@ -30,51 +30,17 @@ metadata: + <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. +. 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`: + -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: minimal-workspace -components: - - type: kubernetes - reference: https://raw.githubusercontent.com/.../mongo-db.yaml - - alias: nodejs-app - type: kubernetes - reference: https://raw.githubusercontent.com/.../nodejs-app.yaml - entrypoints: - - command: ['sleep'] <1> - args: ['infinity'] ----- +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: + -[source,yaml] ----- -apiVersion: 1.0.0 -metadata: - name: minimal-workspace -components: - - type: kubernetes - reference: https://raw.githubusercontent.com/.../mongo-db.yaml - - alias: nodejs-app - type: kubernetes - reference: https://raw.githubusercontent.com/.../nodejs-app.yaml - entrypoints: - - command: ['sleep'] - args: ['infinity'] -commands: - - name: run <1> - actions: - - type: exec - component: nodejs-app - command: cd ${CHE_PROJECTS_ROOT}/nodejs-mongo-app/EmployeeDB/ && npm install && sed -i -- ''s/localhost/mongo/g'' app.js && node app.js ----- +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. @@ -82,5 +48,5 @@ commands: + [subs="+attributes,+quotes"] ---- -$ {prod-cli} workspace:start --devfile __ +$ {prod-cli} workspace:start --devfile ____ ---- diff --git a/modules/end-user-guide/partials/proc_checking-omnisharp-theia-plug-in-language-server-features.adoc b/modules/end-user-guide/partials/proc_checking-omnisharp-theia-plug-in-language-server-features.adoc index d8d3dcac75..495c073840 100644 --- a/modules/end-user-guide/partials/proc_checking-omnisharp-theia-plug-in-language-server-features.adoc +++ b/modules/end-user-guide/partials/proc_checking-omnisharp-theia-plug-in-language-server-features.adoc @@ -1,7 +1,7 @@ // viewing-logs-for-dotnet-with-omnisharp-theia-plug-in [id="checking-omnisharp-theia-plug-in-language-server-features_{context}"] -= Checking Omnisharp Che-Theia plug-in language server features += Checking OmniSharp Che-Theia plug-in language server features .Procedure 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 new file mode 100644 index 0000000000..3f5ff834dc --- /dev/null +++ b/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-a-custom-image-with-an-ide-based-on-the-intellij-platform.adoc @@ -0,0 +1,26 @@ +[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: "____" <1> +---- ++ +<1> `____`: 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 new file mode 100644 index 0000000000..19af7e1342 --- /dev/null +++ b/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-intellij-idea-community.adoc @@ -0,0 +1,15 @@ +[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 new file mode 100644 index 0000000000..ca8cf6191d --- /dev/null +++ b/modules/end-user-guide/partials/proc_configuring-a-workspace-to-use-pycharm-community.adoc @@ -0,0 +1,20 @@ +[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-go-to-use-a-non-standard-registry.adoc b/modules/end-user-guide/partials/proc_configuring-go-to-use-a-non-standard-registry.adoc index 644efb56c3..517a4e40d7 100644 --- 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 @@ -5,7 +5,7 @@ [id="configuring-go-to-use-a-non-standard-registry_{context}"] = Configuring Go to use a non-standard-registry -Athens is a Go module datastore and proxy with many configuration options. It can be configured to act only as a module datastore and not as a proxy. An administrator can upload their Go modules to the Athens datastore and have them available across their Go projects. If a project tries to access a Go module that is not in the Athens datastore, the Go build fails. +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: + diff --git a/modules/end-user-guide/partials/proc_configuring-openshift-oauth.adoc b/modules/end-user-guide/partials/proc_configuring-openshift-oauth.adoc deleted file mode 100644 index 588bf3fe85..0000000000 --- a/modules/end-user-guide/partials/proc_configuring-openshift-oauth.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// Configuring OpenShift OAuth - -[id="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}. - -.Prerequisites - -* The `oc` tool is available. -* `{prod-cli}` management tool is available. See xref:overview:using-the-chectl-management-tool.adoc[]. -* Openshift identity providers are configured 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] - -.Procedure - -* OpenShift OAuth will be enabled by default, 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. - -ifeval::["{project-context}" == "che"] -* For {prod-short} deployed in single-user mode: -+ -==== -. Register {prod-short} OAuth client in OpenShift. See the link:https://docs.openshift.com/container-platform/4.3/authentication/configuring-internal-oauth.html#oauth-register-additional-client_configuring-internal-oauth[Register an OAuth client in OpenShift] chapter. -+ -[subs="+quotes,+attributes"] ----- -$ oc create -f <(echo ' -kind: OAuthClient -apiVersion: oauth.openshift.io/v1 -metadata: - name: che -secret: "" -redirectURIs: - - "<{prod-short} api url>/oauth/callback" -grantMethod: prompt -') ----- - -. Add the OpenShift TLS certificate to the {prod-short} Java trust store. -+ -* See xref:installation-guide:importing-untrusted-tls-certificates.adoc[]. -. Update the OpenShift deployment configuration. -+ -[subs="+quotes,macros"] ----- -CHE_OAUTH_OPENSHIFT_CLIENTID: __ -CHE_OAUTH_OPENSHIFT_CLIENTSECRET: __ -pass:[CHE_OAUTH_OPENSHIFT_OAUTH__ENDPOINT]: __ -pass:[CHE_OAUTH_OPENSHIFT_VERIFY__TOKEN__URL]: __ ----- -+ -* `__` a name specified in the OpenShift OAuthClient. -* `__` a secret specified in the OpenShift OAuthClient. -* `__` the URL of the OpenShift OAuth service: -** For OpenShift 3 specify the OpenShift master URL. -** For OpenShift 4 specify the `oauth-openshift` route. -* `__` request URL that is used to verify the token. `/api` can be used for OpenShift 3 and 4. -+ -* See {link-advanced-configuration-options}. -==== - -.Additional resources - -* See xref:administration-guide:authenticating-users.adoc[]. - -endif::[] - - 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 index 8392d2febf..27c2ffba96 100644 --- 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 @@ -1,207 +1,47 @@ // Module included in the following assemblies: // -// creating-and-configuring-a-new-workspace +// configuring-a-workspace-with-dashboard [id="configuring-the-workspace-and-adding-tooling_{context}"] -= Configuring the workspace and adding tools += Configuring the workspace tools [id="adding-plug-ins_{context}"] == Adding plug-ins .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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}. See xref:creating-and-configuring-a-new-workspace.adoc[Creating and configuring a new {prod-short} {prod-ver} workspace]. +* An existing workspace defined on this instance of {prod-short}. .Procedure To add plug-ins to your workspace: -. Click the *Plugins* tab. -. Enable the plug-in that you want to add and click the btn:[Save] button. +. 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}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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}. See xref:creating-and-configuring-a-new-workspace.adoc[Creating and configuring a new {prod-short} {prod-ver} workspace]. +* An existing workspace defined on this instance of {prod-short}. .Procedure To define the editor to use with the workspace: -. Click the *Editors* tab. -+ -NOTE: The recommended editor for {prod-short} {prod-ver} is Che-Theia. - -. Enable the editor to add and click the btn:[Save] button. -. Click the *Devfile* tab to view the changes. -+ -image::workspaces/workspace-devfile.png[] - - -[id="defining-specific-container-images_{context}"] -== Defining specific container images - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod}. See xref:creating-and-configuring-a-new-workspace.adoc[Creating and configuring a new {prod-short} {prod-ver} workspace]. - -.Procedure - -To add a new container image: - -. In the *Devfile* tab, add the following section under the *components* property: -+ -[source,yaml] ----- -components: - - mountSources: true - command: - - sleep - args: - - infinity - memoryLimit: 1Gi - alias: maven3-jdk11 - type: dockerimage - endpoints: - - name: 8080/tcp - port: 8080 - volumes: - - name: projects - containerPath: /projects - image: 'maven:3.6.0-jdk-11' ----- -ifeval::["{project-context}" == "che"] -+ -. When using `type: kubernetes` or `type: openshift`: -+ -* Use separate recipe files. -+ -To use separate recipe files, specify relative or absolute paths: -+ -.Example -+ -[source,yaml] ----- -... - type: kubernetes - reference: deploy_k8s.yaml -... ----- -+ -[source,yaml] ----- -... - type: openshift - reference: deploy_openshift.yaml -... ----- -endif::[] - -. Add a {prod-short} {prod-prev-ver} recipe content to the {prod-short} {prod-ver} devfile as `referenceContent`: -+ -image::workspaces/component_as_a_referenceContent.png[link="../_images/workspaces/component_as_a_referenceContent.png"] - -.. Set the type from the original {prod-short} {prod-prev-ver} configuration. The following is an example of the resulting file: +. Click the *Devfile* tab. +. Add the desired `cheEditor` component and click the btn:[Save] button. + -[source,yaml] ----- - type: kubernetes - referenceContent: | - apiVersion: v1 - kind: Pod - metadata: - name: ws - spec: - containers: - - - image: 'rhche/centos_jdk8:latest' - name: dev - resources: - limits: - memory: 512Mi ----- - -. Copy the required fields, such as `image`, `volumes`, and `endpoints` from the old workspace. See below: +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_devfile_che_7_.png[] +image::workspaces/workspace-add-editor.png[] -. If needed, change the `memoryLimit` and `alias` variables. The field `alias` is used to set a name for the component and if not manually set, it is generated from the values of the `image` attribute field. -+ -[source,yaml] ----- - image: 'maven:3.6.0-jdk-11' - alias: maven3-jdk11 ----- - -. To specify the `RAM` component requirements, set the `memoryLimit`, `memoryRequest`, or both. -+ -[source,yaml] ----- - alias: maven3-jdk11 - memoryLimit: 256M - memoryRequest: 128M ----- - -. Repeat the steps to add additional container images. - - -[id="adding-commands-to-your-workspace_{context}"] -== Adding commands to your workspace - -The following image is a demonstration of workspace configuration commands in {prod-short} {prod-ver}: - -.An example of the Workspace configuration commands in {prod-short} {prod-ver} -image::workspaces/workspace-devfile.png[] - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. - -* An existing workspace defined on this instance of {prod}. See xref:creating-and-configuring-a-new-workspace.adoc[Creating and configuring a new {prod-short} {prod-ver} workspace]. - -.Procedure - -To define commands to your workspace, edit the workspace devfile: - -. Add or edit the `command` section with the first command. Change the `name` and the `command` fields from the original workspace configuration (see the preceding equivalence table). -+ -[source,yaml] ----- -commands: - - name: build - actions: - - type: exec - command: mvn clean install ----- - -. To add a new command or edit command from other devfile, copy the following YAML code into the `command` section and define the a command. - -.. Change the `name` and the `command` fields from the original workspace configuration, as shown in the introduction screenshot of this chapter. -+ -[source,yaml] ----- - - name: build and run - actions: - - type: exec - command: mvn clean install && java -jar ----- - -. Optionally, add the `component` field into `actions`. This indicates the component alias where the command will be performed. - -. Repeat step 2 to add more commands to the devfile. - -. Click the *Devfile* tab to view the changes. -+ -image::workspaces/workspace-devfile-changes.png[] - -. Save changes and start the new {prod-short} {prod-ver} workspace. -+ -image::workspaces/save-and-start-the-new-che-workspace.png[link="../_images/workspaces/save-and-start-the-new-che-workspace.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 new file mode 100644 index 0000000000..d5c441bd93 --- /dev/null +++ b/modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc @@ -0,0 +1,29 @@ +// 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 new file mode 100644 index 0000000000..2c41cdb77d --- /dev/null +++ b/modules/end-user-guide/partials/proc_configuring_github_authentication.adoc @@ -0,0 +1,73 @@ +// 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/administration-guide/partials/proc_configuring_bitbucket_authentication.adoc b/modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc similarity index 50% rename from modules/administration-guide/partials/proc_configuring_bitbucket_authentication.adoc rename to modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc index 802238b879..16f27c89df 100644 --- a/modules/administration-guide/partials/proc_configuring_bitbucket_authentication.adoc +++ b/modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc @@ -1,24 +1,23 @@ -// configuring-bitbucket-authentication +// Module included in the following assemblies: +// +// authenticating-on-scm-server-with-a-personal-access-token -[id="configuring_bitbucket_authentication_{context}"] -= Authentication on Bitbucket servers +[id="configuring_gitlab_authentication_{context}"] += Authenticating on GitLab servers -{prod} users may use public or private repositories Bitbucket SCM (Source Code Management) system as a source of their projects. The standard -factory flow using devfile at the root of the repository is available starting of 7.25 version of {prod}. +Configuring authentication on the GitLab system is similar to Bitbucket. -The use of private repositories, requires some additional configuration described below. +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. -Bitbucket authentication is based on using personal access tokens. Each Bitbucket user is able to request some -amount of personal access tokens with different names, permissions, expiration times, and so on. Those tokens -can be used to sign Bitbucket 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 Bitbucket authentication on {prod} side, personal tokens must be stored in user's namespace in a form of -secret. The secret must look as follows: +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: -[source,yaml] ----- -include::example$snip_bitbucket-personal-access-token-secret.adoc[] ----- +.GitLab personal access token secret +==== +include::example$snip_gitlab-personal-access-token-secret.adoc[] +==== The main parts of the secret are: @@ -34,15 +33,15 @@ The main parts of the secret are: | Annotation | `che.eclipse.org/scm-userid` -| Bitbucket user id to which token belongs +| GitLab user id to which token belongs | Annotation | `che.eclipse.org/scm-username` -| Bitbucket user name to which token belongs +| GitlLab user name to which token belongs | Annotation | `che.eclipse.org/scm-url` -| Bitbucket server URL to which this token belong +| GitLab server URL to which this token belong | Annotation | `che.eclipse.org/expired-after` @@ -56,19 +55,19 @@ The main parts of the secret are: 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 using a call to a REST API URL: -* For Bitbucket: +. 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"] +[subs="+quotes,macros"] ---- -https://____/rest/api/1.0/users/____ +++https++://____/api/v4/users?username=____ ---- * For {prod-short} + -[subs="+attributes,+quotes"] +[subs="+macros,attributes"] ---- -https://{che-hostname}/api/user +{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. diff --git a/modules/end-user-guide/partials/proc_creating-a-new-workspace-from-the-dashboard.adoc b/modules/end-user-guide/partials/proc_creating-a-new-workspace-from-the-dashboard.adoc deleted file mode 100644 index 544a3969fe..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-new-workspace-from-the-dashboard.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// creating-and-configuring-a-new-workspace - -[id="creating-a-new-workspace-from-the-dashboard_{context}"] -= Creating a new workspace from the dashboard - -This procedure describes how to create and edit a new {prod-short} devfile using the *Dashboard*. - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. - -.Procedure - -To edit the devfile: - -. In the *Workspaces* window, click the btn:[Add Workspace] button. The *Custom Workspace* page should be opened. - -. Scroll down to the *Devfile* section and edit the devfile using *Devfile editor*. -+ -image::workspaces/minimal-devfile.png[Devfile editor with the minimal devfile, link="../_images/workspaces/minimal-devfile.png"] -+ -See an example 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_creating-a-workspace-by-importing-source-code-of-a-project.adoc b/modules/end-user-guide/partials/proc_creating-a-workspace-by-importing-source-code-of-a-project.adoc deleted file mode 100644 index 5d3db318b3..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-workspace-by-importing-source-code-of-a-project.adoc +++ /dev/null @@ -1,132 +0,0 @@ - - -:parent-context-of-creating-a-workspace-by-importing-source-code-of-a-project: {context} - -[id="creating-a-workspace-by-importing-source-code-of-a-project_{context}"] -= Creating a workspace by importing the source code of a project - -:context: creating-a-workspace-by-importing-source-code-of-a-project - -This section describes how to create a new workspace to edit an existing codebase. - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. - -* An existing workspace with plug-ins related to your development environment defined on this instance of {prod} xref:creating-and-configuring-a-new-workspace.adoc[]. - -You can do it in two ways *before* starting a workspace: - -* xref:#creating-a-custom-workspace-from-the-dashboard_{context}[Select a sample from the Dashboard, then change the devfile to include your project] -* xref:configuring-a-workspace-using-a-devfile.adoc[] - -To create a new workspace to edit an existing codebase, use one of the following three methods *after* you have started the workspace: - -* xref:#importing-from-the-dashboard-into-an-existing-workspace_{context}[Import from the *Dashboard* into an existing workspace] -* xref:#importing-to-a-running-workspace-using-the-git-clone-command_{context}[Import to a running workspace using the `git clone` command] -* xref:#importing-to-a-running-workspace-with-git-clone-in-a-terminal_{context}[Import to a running workspace using `git clone` in a terminal] - -[id="creating-a-custom-workspace-from-the-dashboard_{context}"] -== Select a sample from the Dashboard, then change the devfile to include your project - -* In the left navigation panel, go to *Get Started*. - -* Click the *Custom Workspace* tab if it's not already selected. - -* In the *Devfile* section, select the devfile template that will be used to build and run projects. -+ -image::workspaces/{project-context}-select-devfile.png[Select a devfile from the list] - -* In the *Devfile editor*, update `projects` section: -+ -image::workspaces/devfile-projects.png[Update projects section of the devfile] -+ -[NOTE] -.Example: add a project -==== -To add a project into the workspace, add or edit the following section: - -[source,yaml] ----- -projects: - - name: che - source: - type: git - location: 'https://github.com/eclipse/che.git' ----- -See the xref:making-a-workspace-portable-using-a-devfile.adoc#devfile-reference_{context}[]. -==== - -* To open the workspace, click the btn:[Create & Open] button. - -[id="importing-from-the-dashboard-into-an-existing-workspace_{context}"] -== Importing from the Dashboard into an existing workspace - -. Import the project. There are at least two ways to import a project using the *Dashboard*. -+ -* From the *Dashboard*, select *Workspaces*, then select your workspace by clicking on its name. This will link you to the workspace's *Overview* tab. - -* Or, use the gear icon. This will link to the *Devfile* tab where you can enter your own YAML configuration. -+ -. Click the *Projects* tab. -. Click *Add Project*. You can then import project by a repository Git URL or from GitHub. - -image::workspaces/che-config-projects-add-git.png[Add projects to workspace] - -[NOTE] -==== -You can add a project to a non-running workspace, but you must start the workspace to delete it. -==== - -=== Editing the commands after importing a project - -After you have a project in your workspace, you can add commands to it. Adding commands to your projects allows you to run, debug, or launch your application in a browser. - -To add commands to the project: - -. Open the workspace configuration in the *Dashboard*, then select the *Devfile* tab. -+ -image::workspaces/workspace-config-yaml.png[Add commands to workspace] - -. 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 to a running workspace using the *Git: Clone* command - -To import to a running workspace using the *Git: Clone* command: - -. Start a workspace, then use the *Git: Clone* command from the command palette or the Welcome screen to import a project to a running workspace. -+ -image::workspaces/{project-context}-welcome.png[Welcome screen] - -. Open the command palette using `F1` or `CTRL-SHIFT-P`, or from the link in the Welcome screen. -+ -image::workspaces/git-clone-command.png[Invoke git clone command] - -. Enter the path to the project 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 to a running workspace with `git clone` in a terminal - -In addition to the approaches above, you can also start a workspace, open a *Terminal*, and type `git clone` 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 change is not reflected in the *Project* and *Devfile* tabs in the dashboard. - -Similarly, if you add a project using the *Dashboard*, then delete it with `rm -fr myproject`, it may still appear in the *Projects* or *Devfile* tab. -==== - -:context: {parent-context-of-creating-a-workspace-by-importing-source-code-of-a-project} 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 index de6458ac00..7717650adc 100644 --- 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 @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// configuring-a-workspace-using-a-devfile +// 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 @@ -9,15 +9,15 @@ A {prod-short} workspace can be created by pointing to devfile that is stored in .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:making-a-workspace-portable-using-a-devfile.adoc[] for detailed information about creating and using devfiles. +* 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}/f?url=____]` +Execute the workspace by opening the following URL: `pass:c,a,q[{prod-url}/#____]` .Example -Use following URL format to open an experimental link:https://github.com/quarkusio/quarkus-quickstarts[quarkus-quickstarts] branch hosted on link:https://che.openshift.io[che.openshift.io]. +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://che.openshift.io/f?url=https://github.com/maxandersen/quarkus-quickstarts/tree/che +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 index a1dfb38583..c98fd16555 100644 --- 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 @@ -1,25 +1,42 @@ // Module included in the following assemblies: // -// configuring-a-workspace-using-a-devfile +// 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 -It is possible to create a {prod-short} workspace by pointing to a devfile that is stored in a Git source repository. The {prod-short} instance then uses the discovered link:https://github.com/eclipse/che/blob/master/devfile.yaml[devfile.yaml] file to build a workspace using the factory URL (`/f?url=`) API. +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}. 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 that is available over HTTPS. See xref:making-a-workspace-portable-using-a-devfile.adoc[] for detailed information about creating and using devfiles. +* A running instance of {prod}. See xref:installation-guide:installing-che.adoc[]. +* The Git repository ____ is available over HTTPS and contains a `devfile.yaml` or `.devfile.yaml` in the root folder. See xref:authoring-devfiles-version-2.adoc[]. .Procedure -Run the workspace by opening the following URL: `pass:c,a,q[{prod-url}/f?url=https://____]` +pass:[] -.Example +* Run the workspace by opening the factory URL. Two formats are available: ++ +`pass:c,a,q[{prod-url}/#____]`:: This is the short format. +`pass:c,a,q[{prod-url}/f?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"] ----- -https://che.openshift.io/f?url=https://github.com/eclipse/che ----- +==== +link:https://workspaces.openshift.com/f?url=https://github.com/eclipse-che/che-server[] +==== + +pass:[] \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard-get-started.adoc b/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard-get-started.adoc deleted file mode 100644 index 60e06b02cb..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard-get-started.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-code-sample - -[id="creating-a-workspace-from-get-started-view-of-user-dashboard_{context}"] -= Creating a workspace from Get Started view of User Dashboard - -This section describes how to create a workspace from the User Dashboard. - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, 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 *Get Started*. - -. Click the btn:[Get Started] tab. - -. In the gallery, there is list of samples that may be used to build and run projects. -+ -image::workspaces/{project-context}-select-sample.png[Select a stack from the gallery] -+ -[NOTE] -.Changing resource limits -==== -Changing the memory requirements is only possible from the devfile. See xref:changing-the-configuration-of-an-existing-workspace_{context}[]. -==== - -. Start the workspace: click the chosen stack card. -+ -image::workspaces/{project-context}-sample-card.png[Create and Open] - - -[NOTE] -.New workspace name -==== -Workspace name can be auto-generated based on the underlying devfile of the stack. Generated names always consist of the devfile `metadata.generateName` property as the prefix and four random characters. -==== 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 new file mode 100644 index 0000000000..e4e068f25b --- /dev/null +++ b/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard-quick-add.adoc @@ -0,0 +1,31 @@ +// 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-user-dashboard.adoc b/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard.adoc deleted file mode 100644 index b3aa2db2f1..0000000000 --- a/modules/end-user-guide/partials/proc_creating-a-workspace-from-user-dashboard.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// creating-a-workspace-from-code-sample - -[id="creating-a-workspace-from-custom-workspace-view-of-user-dashboard_{context}"] -= Creating a workspace from Custom Workspace view of User Dashboard - -This section describes how to create a workspace from the User Dashboard. - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, 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 *Get Started*. - -. Click the btn:[Custom Workspace] tab. - -. Define a *Name* for the workspace. -+ -[NOTE] -.New workspace name -==== -Workspace name can be auto-generated based on the underlying devfile of the stack. Generated names always consist of the devfile `metadata.generateName` property as the prefix and four random characters. -==== - -. In the *Devfile* section, select the devfile template that will be used to build and run projects. -+ -image::workspaces/{project-context}-select-devfile.png[Select a devfile from the list] -+ -[NOTE] -.Changing resource limits -==== -Changing the memory requirements is only possible from the devfile. See xref:changing-the-configuration-of-an-existing-workspace_{context}[]. -==== - -. Start the workspace: click the btn:[Create & Open] button at the bottom of the form: -+ -image::workspaces/che-create-and-open.png[Create and Open] 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 index b23272c70f..4266f73bb1 100644 --- 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 @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// configuring-a-workspace-using-a-devfile +// 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 @@ -9,13 +9,15 @@ A workspace can be created using a devfile, the URL of which is pointing to the .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:making-a-workspace-portable-using-a-devfile.adoc[] for detailed information about creating and using devfiles. +* 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}/f?url=https://____/devfile.yaml]` +. Execute the workspace by opening the following URL: `pass:c,a,q[{prod-url}/#https://____/devfile.yaml]` +ifeval::["{project-context}" == "che"] .Example [subs="+quotes"] ---- -https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml +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 index 9695019124..becd5b3472 100644 --- 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 @@ -10,12 +10,15 @@ A {prod-short} workspace can be created by pointing the `{prod-cli}` tool to a l .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:making-a-workspace-portable-using-a-devfile.adoc[] for detailed information about creating and using devfiles. -* You are logged in to {prod}. See xref:end-user-guide:navigating-che-using-the-dashboard.adoc#logging-in-to-{prod-id-short}-using-{prod-cli}_{context}[Logging in to {prod-short} using {prod-cli}]. +* 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://github.com/eclipse/che/blob/master/devfile.yaml[GitHub repository] to the current working directory. +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: @@ -26,7 +29,7 @@ $ {prod-cli} workspace:create --name=____ \ <1> --devfile=devfile.yaml --start \ -n {prod-namespace} ---- -<1> The workspace name to create +<1> The workspace name to create. -NOTE: If `--devfile` flag is omitted then {prod-cli} looks for `devfile.yaml` or `devfile.yml` files in the current directory to create a workspace from. +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 index c5b6e0955b..3349a377e7 100644 --- 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 @@ -3,7 +3,7 @@ // 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 += 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. 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 index 90d12c61db..570c62d909 100644 --- 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 @@ -3,7 +3,7 @@ // remote-plug-in-endpoint [id="defining-a-launch-remote-plug-in-endpoint-using-dockerfile_{context}"] -= Defining a launch remote plug-in endpoint using Dockerfile += 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. 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 index 0cc831e85a..41705577c2 100644 --- 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 @@ -6,11 +6,11 @@ = Defining repositories in `settings.xml` To specify your own artifact repositories at `example.server.org`, use the `settings.xml` file. -To do that, ensure, that `settings.xml` is present in all the containers that use Maven tools, in particular the Maven container and the Java plug-in container. +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 `____/.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 want to share `/.m2` folder with this container, you have to specify the custom volume for this specific component in the devfile: +In case you have another container that uses Maven tools and you are about to share `/.m2` folder with this container, you have to specify the custom volume for this specific component in the devfile: [source,yaml] ---- 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 index 131dbfb316..ab83fa1aed 100644 --- 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 @@ -48,7 +48,7 @@ metadata: 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/automount-workspace-secret: "true" che.eclipse.org/mount-path: {prod-home}/.m2 che.eclipse.org/mount-as: file type: Opaque @@ -63,9 +63,9 @@ data: $ {orch-cli} apply -f secret.yaml ---- -. Start a new workspace. You will see `{prod-home}/.m2/settings.xml` with your original content in the `maven` container. +. 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 +== OpenShift 3.11 and {platforms-name} <1.13 On OpenShift 3.11 ifeval::["{project-context}" == "che"] diff --git a/modules/end-user-guide/partials/proc_detecting-memory-problems.adoc b/modules/end-user-guide/partials/proc_detecting-memory-problems.adoc index 8e9a6483fc..2b9fabfbcd 100644 --- a/modules/end-user-guide/partials/proc_detecting-memory-problems.adoc +++ b/modules/end-user-guide/partials/proc_detecting-memory-problems.adoc @@ -9,6 +9,6 @@ The plug-in container runs out of memory:: This can happen during plug-in initialization when the container does not have enough RAM to execute the entrypoint of the image. The user can detect this in the logs of the plug-in container. In this case, the logs contain `OOMKilled`, which implies that the processes in the container requested more memory than is available in the container. A process inside the container runs out of memory without the container noticing this:: -For example, the Java language server (Eclipse JDT Language Server, started by the vscode-java extension) throws an **OutOfMemoryException**. This can happen any time after the container is initialized, for example, when a plug-in starts a language server or when a process runs out of memory because of the size of the project it has to handle. +For example, the Java language server (Eclipse JDT Language Server, started by the `vscode-java` extension) throws an **OutOfMemoryException**. This can happen any time after the container is initialized, for example, when a plug-in starts a language server or when a process runs out of memory because of the size of the project it has to handle. + To detect this problem, check the logs of the primary process running in the container. For example, to check the log file of Eclipse JDT Language Server for details, see the relevant plug-in-specific sections. 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 index 31050faaab..700f0d8ca4 100644 --- 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 @@ -5,12 +5,12 @@ [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. +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. For instructions see xref:remotely-accessing-workspaces.adoc[Remotely accessing workspaces]. +* 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: + 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 index 3eaf07c003..ece6595efb 100644 --- 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 @@ -5,13 +5,13 @@ The recommended way to download any version of Gradle is by using the Gradle Wra .Prerequisites -* The Gradle Wrapper is present in your project. +* 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//gradle/wrapper/gradle-wrapper.properties`: - * Change the `distributionUrl` property to point to a URL of the Gradle distribution ZIP file: + * Change the `distributionUrl` property to point to a URL of the Gradle distribution `ZIP` file: + ---- properties 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 index 3bb60f80b5..1f552fb1d9 100644 --- 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 @@ -3,7 +3,7 @@ // defining-custom-commands-for-che-theia [id="editing-task-and-launch-configuration_{context}"] -= Editing a task and launch configuration += Editing a task and `launch` configuration .Procedure diff --git a/modules/end-user-guide/partials/proc_finding-the-gopath.adoc b/modules/end-user-guide/partials/proc_finding-the-gopath.adoc index b2b95f07fb..7c43b8c71c 100644 --- a/modules/end-user-guide/partials/proc_finding-the-gopath.adoc +++ b/modules/end-user-guide/partials/proc_finding-the-gopath.adoc @@ -1,7 +1,7 @@ // viewing-logs-for-go -[id="finding-the-gopath_{context}"] -= Finding the gopath +[id="finding-the-go-path_{context}"] += Finding the Go path This section describes how to find where the `GOPATH` variable points to. @@ -9,6 +9,6 @@ This section describes how to find where the `GOPATH` variable points to. * Execute the `Go: Current GOPATH` command. + -image::logs/finding-the-gopath.png[] +image::logs/finding-the-gopath.png[Finding the Go path] + -image::logs/viewing-gopath.png[] +image::logs/viewing-gopath.png[Viewing the Go path] 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 index 9975657779..18f4c3ebb0 100644 --- 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 @@ -11,10 +11,12 @@ This procedure demonstrates how to generate a devfile from an existing {platform .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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: diff --git a/modules/end-user-guide/partials/proc_generating-workspace-names.adoc b/modules/end-user-guide/partials/proc_generating-workspace-names.adoc index 9ac9a7394c..a822c60a59 100644 --- a/modules/end-user-guide/partials/proc_generating-workspace-names.adoc +++ b/modules/end-user-guide/partials/proc_generating-workspace-names.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// making-a-workspace-portable-using-a-devfile +// configuring-a-workspace-using-a-devfile [id="generating-workspace-names_{context}"] = Generating workspace names 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 index 2c165f2baa..d03d6329c3 100644 --- a/modules/end-user-guide/partials/proc_importing-certificates-to-browsers.adoc +++ b/modules/end-user-guide/partials/proc_importing-certificates-to-browsers.adoc @@ -21,20 +21,18 @@ When a TLS certificate is not trusted, the error message *"Your {prod2} server m . 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 Root certificate authority and export it: +.. 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 Settings], then to the *Authorities* tab -. In the left panel, select *Advanced* and continue to *Privacy and security*. -. At the center of the screen, click *Manage certificates* and navigate to *Authorities* tab. +. 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 and Safari on macOS +== Adding certificates to Google Chrome on macOS .Procedure @@ -42,9 +40,9 @@ When a TLS certificate is not trusted, the error message *"Your {prod2} server m . Save the certificate: .. Click the lock icon on the left of the address bar. .. Click *Certificates*. -.. Select the certificate to use and drag and drop its displayed large icon to the desktop. +.. 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 and drop the saved certificate file to it. +. 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. @@ -59,7 +57,7 @@ When a TLS certificate is not trusted, the error message *"Your {prod2} server m .. 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* +.. 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. 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 new file mode 100644 index 0000000000..0f302c280e --- /dev/null +++ b/modules/end-user-guide/partials/proc_importing-the-source-code-of-a-project-into-a-workspace.adoc @@ -0,0 +1,187 @@ + + +: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 new file mode 100644 index 0000000000..b502129f71 --- /dev/null +++ b/modules/end-user-guide/partials/proc_investigating-failures-at-a-workspace-start-using-the-verbose-mode.adoc @@ -0,0 +1,47 @@ +// 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 index 85e056e5b6..5aaa73fa01 100644 --- 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 @@ -11,6 +11,7 @@ This section describes how to log in to {prod-short} on OpenShift for the first * 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 @@ -23,4 +24,3 @@ This section describes how to log in to {prod-short} on OpenShift for the first .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 index 0463e814e1..ddedabcfe2 100644 --- 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 @@ -1,25 +1,26 @@ [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 {prod-cli} tool by copying login command from {prod} Dashboard. +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 -. Open the user's context menu in the lower-left corner and select `Copy Login Command` -+ -image::loggingin/copy_login_command_menu.png[copy_login_command_menu.png] -. Wait for the notification message: -+ -image::loggingin/copy_login_command_notification.png[copy_login_command_notification.png] +. 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: + -``` -$ chectl auth:login ... -Successfully logged into as -``` +[subs="+attributes,+quotes"] +---- +$ {prod-cli} auth:login ... +Successfully logged into ____ as ____ +---- 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 dadb63f713..b232229a8a 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 @@ -16,8 +16,8 @@ This section describes how to log the exchange between Che-Theia and a debug ada . Expand the *Debug* section in the *Preferences* view. . Set the *trace* preference value to `true` (default is `false`). - -. All the communication events are now logged. ++ +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"] diff --git a/modules/end-user-guide/partials/proc_logging-the-intelephense-client-server-communication.adoc b/modules/end-user-guide/partials/proc_logging-the-intelephense-client-server-communication.adoc index 99c413cbc7..629d26d835 100644 --- a/modules/end-user-guide/partials/proc_logging-the-intelephense-client-server-communication.adoc +++ b/modules/end-user-guide/partials/proc_logging-the-intelephense-client-server-communication.adoc @@ -5,7 +5,7 @@ .Procedure -To configure the PHP Intelephense language support to log the client-server interexchange in the *Output* view: +To configure the PHP Intelephense language support to log the client-server communication in the *Output* view: . Click *File -> Settings*. 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 492117ef2b..845cda4b91 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 @@ -9,4 +9,4 @@ To log the LSP messages to the VS Code *Output* view, enable tracing by setting .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[VS 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 index 52ce170e45..ac6fa2e643 100644 --- a/modules/end-user-guide/partials/proc_managing-git-configuration-identity.adoc +++ b/modules/end-user-guide/partials/proc_managing-git-configuration-identity.adoc @@ -13,14 +13,14 @@ The first thing to do before starting to use Git is to set a user name and email + . Open *File > Settings > Open Preferences* or press kbd:[Ctrl+,]. + -image::git/git-config-identity.png[link="../_images/git/git-config-identity.png"] +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*: +. Navigate to the *My Workspace* view, and open *Plugins > theia-ide > New terminal*: + image::git/terminal-git-command.png[] + 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 index 6b5c1f6d18..dd07c5010c 100644 --- 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 @@ -9,10 +9,10 @@ This section describes how to mount git credentials store as secret from the use .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. .Procedure -. Prepare git credential file in format https://git-scm.com/docs/git-credential-store#_storage_format. +. 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. 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/partials/proc_mounting-a-secret-as-a-file-into-a-workspace-container.adoc index 1d8a0c18af..5d409b8d30 100644 --- a/modules/end-user-guide/partials/proc_mounting-a-secret-as-a-file-into-a-workspace-container.adoc +++ b/modules/end-user-guide/partials/proc_mounting-a-secret-as-a-file-into-a-workspace-container.adoc @@ -15,7 +15,7 @@ This section describes how to mount a secret from the user's {orch-namespace} as .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. .Procedure 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/partials/proc_mounting-a-secret-as-an-environment-variable-into-a-workspace-container.adoc index d334403133..da00e8b385 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/partials/proc_mounting-a-secret-as-an-environment-variable-into-a-workspace-container.adoc @@ -9,13 +9,13 @@ The following section describes how to mount a {platforms-name} secret from the .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. .Procedure -. Create a new {platforms-name} secret in the k8s {orch-namespace} where a {prod-short} workspace will be created. +. In the {platforms-namespace} where a {prod-short} workspace will be created, generate a new {platforms-name} secret. -* 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}. By default, it is a set of two labels: +* The labels of the secret that is about to be generated must match the set of labels configured in `che.workspace.provision.secret.labels` property of {prod-short}. By default, it is a set of two labels: + * `app.kubernetes.io/part-of: che.eclipse.org` * `app.kubernetes.io/component: workspace-secret`: 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 index 7d6b66ad14..b50189acea 100644 --- 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 @@ -1,31 +1,35 @@ // Module included in the following assemblies: // -// configuring-a-workspace-using-a-devfile +// creating-a-workspace-from-a-remote-devfile [id="overriding-devfile-values-using-factory-parameters_{context}"] = Overriding devfile values using factory parameters -Values in the following sections of a remote devfile can be overridden using specially constructed additional 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}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[]. -* A publicly accessible standalone `devfile.yaml` file. See xref:making-a-workspace-portable-using-a-devfile.adoc[] for detailed information about creating and using devfiles. + +* 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://____/devfile.yaml&override.____=____]` .Example of overriding the `generateName` property +==== Consider the following initial devfile: [subs="+quotes"] ---- ---- apiVersion: 1.0.0 metadata: generateName: golang- @@ -37,28 +41,28 @@ To add or override `generateName` value, use the following factory URL: [subs="+quotes"] ---- -https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.metadata.generateName=myprefix +https://workspaces.openshift.com/f?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- @@ -70,11 +74,11 @@ projects: ... ---- -To add or override source `branch` value, use the following factory URL: +To add or override the source `branch` value, use the following factory URL: [subs="+quotes"] ---- -https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.projects.web-java-spring-petclinic.source.branch=1.0.x +https://workspaces.openshift.com/f?url=____&override.projects.web-java-spring-petclinic.source.branch=1.0.x ---- The resulting workspace has the following devfile model: @@ -92,16 +96,16 @@ projects: 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- @@ -111,11 +115,11 @@ projects: ... ---- -To add or override `persistVolumes` attribute value, use the following factory URL: +To add or override the `persistVolumes` attribute value, use the following factory URL: [subs="+quotes"] ---- -https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.attributes.persistVolumes=true +https://workspaces.openshift.com/f?url=____&override.attributes.persistVolumes=true ---- @@ -133,18 +137,17 @@ projects: ... ---- -When overriding attributes, everything that follows the `attributes` keyword is interpreted as an attribute name, so a user can use dot-separated names: +When overriding attributes, everything that follows the `attributes` keyword is interpreted as an attribute name. You can use dot-separated names: [subs="+quotes"] ---- -https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.attributes.dot.name.format.attribute=true +https://workspaces.openshift.com/f?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- @@ -153,3 +156,8 @@ attributes: 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-jetbrains-activation-code-for-offline-use.adoc b/modules/end-user-guide/partials/proc_provisioning-jetbrains-activation-code-for-offline-use.adoc deleted file mode 100644 index 9c82fae826..0000000000 --- a/modules/end-user-guide/partials/proc_provisioning-jetbrains-activation-code-for-offline-use.adoc +++ /dev/null @@ -1,55 +0,0 @@ -[id="provisioning-jetbrains-activation-code-for-offline-use_{context}"] -= Provisioning JetBrains activation code for offline use - -An activation code for offline use is a file with a license code that can be retrieved from the license management section of your JetBrains account for the license that is assigned to you. When you purchase a personal subscription or are assigned a commercial subscription by your organization, you receive an email prompting you to create a JetBrains account that becomes connected with the license. - -NOTE: When using an activation code to activate a product, you need to generate a new activation code and apply it to your product each time the subscription is renewed. - -.Prerequisites - -* JetBrains account -* Personal or organization subscription - -.Procedure - -. Retrieve the activation code from the JetBrains account: -+ -image::jetbrains/jetbrains-account.jpg[] -+ -JetBrains provides a ZIP archive with two types of the activation code. Use the `{nbsp}-{nbsp}for{nbsp}2018.1{nbsp}or{nbsp}later.txt` file: -+ -image::jetbrains/activation-code.jpg[] - -. Provision the activation code for offline use with Che. This procedure is performed through the {orch-name} Secrets. - -. Create a {orch-name} Secret to instruct {prod-short} to mount the activation code into a container based on JetBrains specific product: -+ -[source,yaml,subs="+quotes"] ----- -apiVersion: v1 -kind: Secret -metadata: - name: __ <1> - labels: - app.kubernetes.io/component: workspace-secret - app.kubernetes.io/part-of: che.eclipse.org - annotations: - che.eclipse.org/automount-workspace-secret: 'false' - che.eclipse.org/mount-path: /tmp/ - che.eclipse.org/mount-as: file -data: - ____.key: __ <2> ----- -<1> `` – The section that specifies the secret name. It may have a different name, for example, `ideaiu-offline-activation-code`. Provide the secret name in lowercase. -<2> Product name and activation code: -* `` – Replace with the JetBrains product name. See section -xref:jetbrains-product-name-mapping[]. -* `` – The activation code content encoded in base64. - -Use the `automount-workspace-secret` option set to `false` to disable the mounting process until it is explicitly requested in a devfile component using the `automountWorkspaceSecrets:true` property. See the `workspace.yaml` example file above. This is the default behavior to avoid mounting the activation code into every container except specific ones that have to work with it. - -As a result, in the Che Editor, the file with the activation code for offline use is mounted to the `/tmp/ideaIU.key` or `/tmp/WebStorm.key` path (or similar - based on the type of the build). - -IntelliJ Idea Community Edition does not require this procedure. This has to be done for JetBrains products that need to be registered. - -include::partial$con_jetbrains-product-name-mapping.adoc[leveloffset=+1] 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 new file mode 100644 index 0000000000..d9bdfea363 --- /dev/null +++ b/modules/end-user-guide/partials/proc_provisioning-the-jetbrains-offline-activation-code.adoc @@ -0,0 +1,68 @@ +[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 `____{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 `____`. ++ +[subs="+quotes,+attributes,+macros"] +---- +$ openssl base64 -e -A -in '____{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: ____ + pycharm.key: ____ + webstorm.key: ____ + phpstorm.key: ____ + goland.key: ____ +---- ++ +<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: "____" +---- + +. 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 index 5f98042523..f3a069b323 100644 --- 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 @@ -5,9 +5,11 @@ [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} need to consume metadata describing the extension. The {prod-short} plugin registry is a static website publishing metadata for common VS Code extensions. +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. -How to publish metadata for an additional extension, not available in the {prod-short} plugin registry using the extension configuration. `meta.yaml` file. +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 diff --git a/modules/end-user-guide/partials/proc_restarting-a-che-workspace-in-debug-mode-after-start-failure.adoc b/modules/end-user-guide/partials/proc_restarting-a-che-workspace-in-debug-mode-after-start-failure.adoc deleted file mode 100644 index 8718c81b88..0000000000 --- a/modules/end-user-guide/partials/proc_restarting-a-che-workspace-in-debug-mode-after-start-failure.adoc +++ /dev/null @@ -1,29 +0,0 @@ - -// Module included in the following assemblies: -// -// troubleshooting-che - - - -[id="restarting-a-{prod-id-short}-workspace-in-debug-mode-after-start-failure_{context}"] -= Restarting a {prod-short} workspace in debug mode after start failure - -This section describes how to restart the {prod} workspace in debug mode after a failure during workspace start. - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. - -* An existing workspace that failed to start. - -.Procedure - -. Find the target workspace from the recent workspaces. Click on the target workspace to see the logs: -+ -image::troubleshooting/try_again_in_debug_mode.png[link="../_images/troubleshooting/try_again_in_debug_mode.png",Try again in debug mode] - -. Click the link for restarting in debug mode. - -. Download full logs after start fail with the *Download logs* link: -+ -image::troubleshooting/download_logs.png[link="../_images/troubleshooting/download_logs.png",Download logs] 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 index 677e9a2a16..962f41cdf6 100644 --- 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 @@ -3,15 +3,15 @@ // 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 += 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. +This section describes how to run an existing workspace from the user dashboard using the *Open* button. .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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} xref:creating-and-configuring-a-new-workspace.adoc[]. +* An existing workspace defined on this instance of {prod-short}. .Procedure @@ -22,7 +22,5 @@ This section describes how to run an existing workspace from the User Dashboard . 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. - -. The browser navigates to the workspace. ++ +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 index 8433ee597e..338deb4a30 100644 --- 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 @@ -3,20 +3,18 @@ // 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 += 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. +This section describes how to run an existing workspace from the user dashboard using the Recent Workspaces. .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* 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} xref:creating-and-configuring-a-new-workspace.adoc[]. +* 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. -+ -image::workspaces/{project-context}-run-from-recent-workspaces.png[Run from Recent Workspaces] 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 index 1831ddbd55..2638a82f11 100644 --- 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 @@ -3,14 +3,14 @@ // 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 += 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. +This section describes how to run an existing workspace from the user dashboard using the *Run* button. .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. -* An existing workspace defined on this instance of {prod} xref:creating-and-configuring-a-new-workspace.adoc[]. +* 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 @@ -21,7 +21,5 @@ This section describes how to run an existing workspace from the User Dashboard . 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. - -. The browser *does not* navigates to the workspace. ++ +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 index 57da4439f1..dc18df9a25 100644 --- a/modules/end-user-guide/partials/proc_running-and-debugging.adoc +++ b/modules/end-user-guide/partials/proc_running-and-debugging.adoc @@ -8,16 +8,20 @@ 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}. To install an instance of {prod}, see {link-installing-an-instance}. +* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. + +pass:[] + +pass:[] .Procedure To debug an application: -. Click *Debug* -> *Add Configuration* to add debugging or launch configuration to the project. +. 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 want to debug. +. 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[] @@ -25,11 +29,11 @@ image::ide/che-theia-basics-2.png[] + image::ide/che-theia-basics-3.png[] -. Breakpoints can be toggled by clicking the editor margin. +. Breakpoints can be toggled by selecting the editor margin. + image::ide/che-theia-basics-3-b.png[] -. After opening a context menu, use the *Edit Breakpoint* command to add conditions. +. After opening the breakpoint menu, use the *Edit Breakpoint* command to add conditions. + image::ide/che-theia-basics-3-c.png[] + @@ -41,6 +45,10 @@ image::ide/che-theia-basics-3-d.png[] + 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 *Ctrl+F5*. +. 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:[] + +pass:[] \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_starting-a-che-workspace-in-debug-mode.adoc b/modules/end-user-guide/partials/proc_starting-a-che-workspace-in-debug-mode.adoc deleted file mode 100644 index af34c47f0f..0000000000 --- a/modules/end-user-guide/partials/proc_starting-a-che-workspace-in-debug-mode.adoc +++ /dev/null @@ -1,29 +0,0 @@ - -// Module included in the following assemblies: -// -// troubleshooting-che - - - -[id="starting-a-{prod-id-short}-workspace-in-debug-mode_{context}"] -= Starting a {prod-short} workspace in debug mode - -This section describes how to start the {prod} workspace in debug 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}. See xref:creating-and-configuring-a-new-workspace.adoc[]. - -.Procedure - -. Find the target workspace from the recent workspaces. Right-click the workspace name to open a context menu. Select the *Run in debug mode* item: -+ -image::troubleshooting/run_workspace_in_debug_mode.png[link="../_images/troubleshooting/run_workspace_in_debug_mode.png",Run in debug mode] - -. Click the target workspace to see the logs. - -. The workspace logs are displayed: -+ -image::troubleshooting/starting_workspace_debug_logs.png[link="../_images/troubleshooting/starting_workspace_debug_logs.png",Debug logs] 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 index 7dbc814d11..83d975bece 100644 --- 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 @@ -20,7 +20,7 @@ To add a plug-in that is not in the default plug-in registry, build a custom plu .Prerequisites -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. +* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. * A GitHub account. @@ -73,7 +73,7 @@ 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/master/dependencies/che-plugin-registry/resources/images/default.svg?sanitize=true +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' @@ -147,7 +147,7 @@ commands: 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 (instead of an ID pointing to a definition in the default plug-in registry). +<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: + @@ -209,7 +209,7 @@ $ git add * # Commit $ git commit -m "Initial Commit for the test of our extension" -[master 98dd370] 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 @@ -230,5 +230,5 @@ or: + [subs="+quotes"] ---- -$ echo "https://____/f?url=$(git config --get remote.origin.url)/raw/devfile.yaml" +$ echo "https://____/#$(git config --get remote.origin.url)/raw/devfile.yaml" ---- diff --git a/modules/end-user-guide/partials/proc_troubleshooting-slow-workspaces.adoc b/modules/end-user-guide/partials/proc_troubleshooting-slow-workspaces.adoc index 2704714151..7139d8c92f 100644 --- a/modules/end-user-guide/partials/proc_troubleshooting-slow-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_troubleshooting-slow-workspaces.adoc @@ -10,7 +10,6 @@ Sometimes, workspaces can take a long time to start. Tuning can reduce this star 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 @@ -34,7 +33,7 @@ Installing offline:: + _Role: Administrator_ + -Components of {prod-short} are OCI images. Setup {prod} in offline mode (air-gap scenario) to allow for reducing any extra download at runtime as everything needs to be present from the beginning. See xref:installation-guide:installing-che-in-a-restricted-environment.adoc[]. +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:: + 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 index 928728a9e5..262c95769b 100644 --- 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 @@ -14,14 +14,18 @@ Use this badge and link it to a {prod-short} instance to quickly open a develope .Procedure -Add a link to your repository in the project `README` file. Using link:https://che.openshift.io[che.openshift.io] as an example {prod-short} host, and a GitHub repository: - +. To open a workspace in your {prod-short} installation, substitute your URL and repository: ++ ---- -[![Contribute](https://www.eclipse.org/che/contribute.svg)](https://che.openshift.io/f?url=https://github.com/org/repository) +[![Contribute](https://www.eclipse.org/che/contribute.svg)](https://your-che-host.com/f?url=https://your-repository-url) ---- -The snippet above creates a badge that opens a developer workspace of the repository at `+https://github.com/org/repository+` in link:https://che.openshift.io/[che.openshift.io]. To open a workspace in your {prod-short} installation, substitute your URL and repository: +. 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://your-che-host.com/f?url=https://your-repository-url) +[![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-jetbrains-intellij-idea-community-edition.adoc b/modules/end-user-guide/partials/proc_using-jetbrains-intellij-idea-community-edition.adoc deleted file mode 100644 index 15946a8285..0000000000 --- a/modules/end-user-guide/partials/proc_using-jetbrains-intellij-idea-community-edition.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[id="using-intellij-idea-community-edition_{context}"] -= Using IntelliJ Idea Community Edition - -.Procedure - -. Clone the link:https://github.com/che-incubator/che-editor-intellij-community[che-editor-intellij-community] repository, which is needed to build IntelliJ Idea Community Edition located under the _che-incubator_ organization. - -. Build IntelliJ Idea Community Edition by calling the following command inside the repository folder: -+ ----- -$ podman build -t idea-ic --build-arg PRODUCT_NAME=ideaIC . ----- -+ -This command builds an image with a `2020.2.3` version by default. - -. Tag and push the built image to a user repository: -+ -[subs="+quotes"] ----- -$ podman tag idea-ic:latest ____/idea-ic:latest -$ podman push ____/idea-ic:latest ----- - -. Use this image as the {prod-short} editor. To achive this, create two YAML configuration files: -+ -* `workspace.yaml` – workspace configuration. Do not forget to provide a correct URL to the `meta.yaml` file: -+ -[source,yaml,subs="+quotes"] ----- -metadata: - name: che-ideaic -components: - - type: cheEditor - reference: '____' - alias: ideaic-editor -apiVersion: 1.0.0 ----- - -* `meta.yaml` – {prod-short} editor configuration. Do not forget to replace `` with the user name of the repository to which the image is pushed: -+ -[source,yaml,subs="+quotes,attributes"] ----- -apiVersion: v2 -publisher: __ -name: ideaic-NOVNC -version: 2020.2.3 -type: Che Editor -displayName: IntelliJ IDEA Community Edition -title: IntelliJ IDEA Community Edition (in browser using noVNC) as editor for {prod} -description: IntelliJ IDEA Community Edition running on the Web with noVNC -icon: https://resources.jetbrains.com/storage/products/intellij-idea/img/meta/intellij-idea_logo_300x300.png -category: Editor -repository: https://github.com/che-incubator/che-editor-intellij-community -firstPublicationDate: "2020-10-27" -spec: - endpoints: - - name: "intellij" - public: true - targetPort: 8080 - attributes: - protocol: http - type: ide - path: /vnc.html?resize=remote&autoconnect=true&reconnect=true - containers: - - name: ideaic-novnc - image: "____/idea-ic:latest" - mountSources: true - volumes: - - mountPath: "/JetBrains/ideaIC" - name: ideaic-configuration - ports: - - exposedPort: 8080 - memoryLimit: "2048M" ----- diff --git a/modules/end-user-guide/partials/proc_using-jetbrains-intellij-idea-ultimate-edition.adoc b/modules/end-user-guide/partials/proc_using-jetbrains-intellij-idea-ultimate-edition.adoc deleted file mode 100644 index 0607ec09b8..0000000000 --- a/modules/end-user-guide/partials/proc_using-jetbrains-intellij-idea-ultimate-edition.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id="using-intellij-idea-ultimate-edition_{context}"] -= Using IntelliJ Idea Ultimate Edition - -.Procedure - -. Clone the link:https://github.com/che-incubator/che-editor-intellij-community[che-editor-intellij-community] repository, which is needed to build IntelliJ Idea Community Edition located under the _che-incubator_ organization. - -. Build IntelliJ Idea Ultimate Edition by calling the following command inside the repository folder: -+ ----- -$ podman build -t idea-iu --build-arg PRODUCT_NAME=ideaIU . ----- -+ -This command builds an image with a `2020.2.3` version by default. - -. Tag and push the built image to a user repository: -+ -[subs="+quotes"] ----- -$ podman tag idea-iu:latest ____/idea-iu:latest -$ podman push ____/idea-iu:latest ----- - -. Provision the activation code for offline use to be able to use WebStorm with a registered license. See section xref:provisioning-jetbrains-activation-code-for-offline-use.adoc[]. - -. Create a workspace with the following `workspace.yaml` and `meta.yaml` files: -+ -* `workspace.yaml` – workspace configuration. Do not forget to provide a correct URL to the `meta.yaml` file: -+ -[source,yaml,subs="+quotes"] ----- -metadata: - name: che-ideaiu -components: - - type: cheEditor - reference: '____' - alias: ideaiu-editor - automountWorkspaceSecrets: true -apiVersion: 1.0.0 ----- -+ -NOTE: In the current workspace definition, there is a new property: `automountWorkspaceSecrets: true`. This property instructs {prod} to provision secrets into a specific component. In this case, it provisions it into the {prod-short} editor based on IntelliJ Idea Ultimate Edition. This parameter is *mandatory* to successfully register the IDE with an activation code for offline use. - -* `meta.yaml` – {prod-short} editor configuration. Do not forget to replace `` with the user name of the repository to which the image is pushed: -+ -[source,yaml,subs="+quotes,attributes"] ----- -apiVersion: v2 -publisher: __ -name: ideaIU-NOVNC -version: 2020.2.3 -type: Che Editor -displayName: IntelliJ IDEA Ultimate Edition -title: IntelliJ IDEA Ultimate Edition (in browser using noVNC) as editor for {prod} -description: IntelliJ IDEA Ultimate Edition running on the Web with noVNC -icon: https://resources.jetbrains.com/storage/products/intellij-idea/img/meta/intellij-idea_logo_300x300.png -category: Editor -repository: https://github.com/che-incubator/che-editor-intellij-community -firstPublicationDate: "2020-10-27" -spec: - endpoints: - - name: "intellij" - public: true - targetPort: 8080 - attributes: - protocol: http - type: ide - path: /vnc.html?resize=remote&autoconnect=true&reconnect=true - containers: - - name: ideaiu-novnc - image: "____/idea-iu:latest" - mountSources: true - volumes: - - mountPath: "/JetBrains/ideaIU" - name: ideaiu-configuration - ports: - - exposedPort: 8080 - memoryLimit: "2048M" ----- diff --git a/modules/end-user-guide/partials/proc_using-jetbrains-webstorm.adoc b/modules/end-user-guide/partials/proc_using-jetbrains-webstorm.adoc deleted file mode 100644 index 3d88d9118d..0000000000 --- a/modules/end-user-guide/partials/proc_using-jetbrains-webstorm.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id="using-jetbrains-webstorm_{context}"] -= Using WebStorm - -.Procedure - -. Clone the link:https://github.com/che-incubator/che-editor-intellij-community[che-editor-intellij-community] repository, which is needed to build IntelliJ Idea Community Edition located under the _che-incubator_ organization. - -. Build the image: -+ ----- -$ podman build -t webstorm --build-arg PRODUCT_NAME=WebStorm . ----- -+ -This command builds an image with a `2020.2.3` version by default. - -. Tag and push the built image to a user repository: -+ -[subs="+quotes"] ----- -$ podman tag webstorm:latest ____/webstorm:latest -$ podman push ____/webstorm:latest ----- - -. Provision the activation code for offline use to be able to use WebStorm with a registered license. See section xref:provisioning-jetbrains-activation-code-for-offline-use.adoc[]. - -. Create a workspace with the following `workspace.yaml` and `meta.yaml` files: -+ -* `workspace.yaml` – workspace configuration. Do not forget to provide a correct URL to the `meta.yaml` file: -+ -[source,yaml,subs="+quotes"] ----- -metadata: - name: che-webstorm -components: - - type: cheEditor - reference: '____' - alias: webstorm-editor - automountWorkspaceSecrets: true -apiVersion: 1.0.0 ----- -+ -NOTE: In the current workspace definition, there is a new property: `automountWorkspaceSecrets: true`. This property instructs {prod} to provision secrets into a specific component. In this case, it provisions it into the {prod-short} editor based on IntelliJ Idea Ultimate Edition. This parameter is *mandatory* to successfully register the IDE with an activation code for offline use. - -* `meta.yaml` – {prod-short} editor configuration. Do not forget to replace `` with the user name of the repository to which the image is pushed: -+ -[source,yaml,subs="+quotes,attributes"] ----- -apiVersion: v2 -publisher: __ -name: webstorm-NOVNC -version: 2020.2.3 -type: Che Editor -displayName: WebStorm -title: WebStorm (in browser using noVNC) as editor for {prod} -description: WebStorm running on the Web with noVNC -icon: https://resources.jetbrains.com/storage/products/webstorm/img/meta/webstorm_logo_300x300.png -category: Editor -repository: https://github.com/che-incubator/che-editor-intellij-community -firstPublicationDate: "2020-10-27" -spec: - endpoints: - - name: "intellij" - public: true - targetPort: 8080 - attributes: - protocol: http - type: ide - path: /vnc.html?resize=remote&autoconnect=true&reconnect=true - containers: - - name: webstorm-novnc - image: "____/webstorm:latest" - mountSources: true - volumes: - - mountPath: "/JetBrains/WebStorm" - name: webstorm-configuration - ports: - - exposedPort: 8080 - memoryLimit: "2048M" ----- 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 index ff651b18b3..9cc249da0d 100644 --- a/modules/end-user-guide/partials/proc_using-npm-artifact-repositories.adoc +++ b/modules/end-user-guide/partials/proc_using-npm-artifact-repositories.adoc @@ -7,16 +7,16 @@ :context: using-npm-artifact-repositories -npm is usually configured using the `npm config` command, writing values to the `.npmrc` files. However, configuration values can also be set using the environment variables beginning with `NPM_CONFIG_`. +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 Javascript/Typescript plug-in used in {prod} does not download any artifacts. It is enough to configure npm in the dev-machine component. +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 Kubernetes 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. +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: + 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 new file mode 100644 index 0000000000..02fbabeae3 --- /dev/null +++ b/modules/end-user-guide/partials/proc_using-private-container-registries.adoc @@ -0,0 +1,42 @@ +[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 index 32ac2455e7..c3cd2fad51 100644 --- 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 @@ -5,13 +5,13 @@ [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 usually signed by an internal company authority or are self-signed. Configure your tools to accept these certificates. +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 Kubernetes 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. +. 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: + 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 index c0397904bb..e465be502f 100644 --- 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 @@ -5,11 +5,11 @@ [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 usually signed by an internal company authority or are self-signed. Configure your tools to accept these certificates by adding them to the Java truststore. +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 Kubernetes 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. +. 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: + 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 index 679fdcbf2b..95f08e9f88 100644 --- 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 @@ -5,11 +5,11 @@ [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 usually signed by an internal company authority or are self-signed. Configure your tools to accept these certificates by adding them to the Java truststore. +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 Kubernetes 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. +. 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: + @@ -42,7 +42,7 @@ Certificate was added to keystore env: -name: MAVEN_OPTS value: >- - -Duser.home=/projects/maven -Djavax.net.ssl.trustStore=/projects/maven/truststore.jks + -Duser.home=/projects/maven -Djavax.net.ssl.trustStore=/projects/maven/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit ---- + .. Restart the workspace. @@ -62,5 +62,5 @@ components: -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 index 989caa89da..7205dc88d0 100644 --- 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 @@ -5,11 +5,11 @@ [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 usually signed by an internal company authority or are self-signed. Configure your tools to accept these certificates. +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 Athens server in the Privacy-Enhanced Mail (PEM) format. It is customary for administrators to provide certificates of internal artifact servers as Kubernetes 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. +. 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. + 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 index 124d2b0cfe..c5fbb1fe3c 100644 --- 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 @@ -5,13 +5,13 @@ [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 usually signed by an internal company authority or are self-signed. Configure your tools to accept these certificates. +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 Athens server in the Privacy-Enhanced Mail (PEM) format. It is customary for administrators to provide certificates of internal artifact servers as Kubernetes 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. +. 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] ==== @@ -20,4 +20,4 @@ pip accepts certificates in the Privacy-Enhanced Mail (PEM) format only. Convert + . Configure the devfile: + -include::example${project-context}-python-use-self-signed-cert.adoc[] \ No newline at end of file +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 b74d6eb9cb..0e72b681f3 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 link:#checking-important-logs_{context}[Checking important logs]. +. If you cannot find it, see xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs]. 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 79d39bb98b..f578dfb4f8 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 @@ -17,4 +17,4 @@ usr/lib/jvm/default-jvm/bin/java --add-modules=ALL-SYSTEM --add-opens java.base/ + This message also shows the VSCode Java extension used. If it is not running, the language server has not been started inside the container. -. Check all logs described in link:#checking-important-logs_{context}[Checking important logs] +. Check all logs described in xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs] 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 f025d70d23..635c1292fa 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 @@ -5,21 +5,23 @@ .Procedure -To test the plug-in initialization: - -. Check if there is a netcoredbg debug configuration in the `launch.json` file. The following is an example debug configuration: +. Search for a `netcoredbg` debug configuration in the `launch.json` file. + -[source,json] +.Sample debug configuration +==== +[source,json,subs="+quotes,+attributes"] ---- { "type": "netcoredbg", "request": "launch", - "program": "$\{workspaceFolder}/bin/Debug//", + "program": "$\{workspaceFolder}/bin/Debug/____/____", "args": [], "name": ".NET Core Launch (console)", "stopAtEntry": false, "console": "internalConsole" } ---- +==== + +. 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]. -. To test if it exists, 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 link:#checking-important-logs_{context}[Checking important logs]. 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 1709541b2a..b322637d51 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 @@ -1,15 +1,15 @@ // viewing-logs-for-dotnet-with-omnisharp-theia-plug-in [id="verifying-the-state-of-the-omnisharp-theia-plug-in-language-server_{context}"] -= Verifying the state of the Omnisharp-Theia plug-in language server += Verifying the state of the OmniSharp-Theia plug-in language server .Procedure -To check if the container running the Omnisharp-Theia plug-in is running OmniSharp, execute the `ps aux | grep OmniSharp.exe` command. If the process is running, the following is an example output: +To check if the container running the OmniSharp-Theia plug-in is running OmniSharp, execute the `ps aux | grep OmniSharp.exe` command. If the process is running, the following is an example output: ---- /tmp/theia-unpacked/redhat-developer.che-omnisharp-plugin.0.0.1.zcpaqpczwb.omnisharp_theia_plugin.theia/server/bin/mono /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 link:#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#checking-important-logs_{context}[Checking important logs]. 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 c265d74923..ba2132b2fc 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 link:#checking-important-logs_{context}[Checking important logs] chapter. +If is not, see the xref:viewing-che-workspaces-logs.adoc#checking-important-logs_{context}[Checking important logs] 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 cc43008aa3..2cb3e5f23c 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 @@ -1,5 +1,3 @@ -// viewing-logs-for-yaml - [id="verifying-the-state-of-the-yaml-language-server_{context}"] = Verifying the state of the YAML language server @@ -15,6 +13,6 @@ Check if the container running the YAML plug-in is running the YAML language ser . Verify that a command `node ********/server.js` is running. + -image::logs/verifying-the-state-of-the-yaml-language-server.png[] +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 link:#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#checking-important-logs_{context}[Checking important logs]. 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 index df9f74edd3..314f671964 100644 --- 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 @@ -5,7 +5,7 @@ [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. +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://eclipse-theia.github.io/vscode-theia-comparator/status.html[vscode-theia-comparator] GitHub page. .Prerequisites 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 6fb0579e09..654188c441 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 @@ -7,7 +7,7 @@ This procedure describes how to configure the PHP Debug plug-in to log the PHP D .Procedure -. In the `launch.json` file, add the `"log": true` attribute to the selected launch configuration. +. In the `launch.json` file, add the `"log": true` attribute to the `php` configuration. . Start the debug session. diff --git a/modules/end-user-guide/partials/proc_viewing-netcoredebugoutput-plug-in-logs-in-the-output-panel.adoc b/modules/end-user-guide/partials/proc_viewing-netcoredebugoutput-plug-in-logs-in-the-output-panel.adoc index 928231e786..a4c8f23d12 100644 --- a/modules/end-user-guide/partials/proc_viewing-netcoredebugoutput-plug-in-logs-in-the-output-panel.adoc +++ b/modules/end-user-guide/partials/proc_viewing-netcoredebugoutput-plug-in-logs-in-the-output-panel.adoc @@ -1,12 +1,10 @@ -// viewing-logs-for-dotnet-with-netcoredebugoutput-plug-in - [id="viewing-netcoredebugoutput-plug-in-logs-in-the-output-panel_{context}"] -= Viewing NetcoredebugOutput plug-in logs in the Output panel += Viewing `NetcoredebugOutput` plug-in logs in the Output panel -This section describes how to view NetcoredebugOutput plug-in logs in the *Output* panel. +This section describes how to view `NetcoredebugOutput` plug-in logs in the *Output* panel. .Procedure * Open the *Debug* console. + -image::logs/viewing-netcoredebugoutput-plug-in-logs-in-the-output-panel.png[] +image::logs/viewing-netcoredebugoutput-plug-in-logs-in-the-output-panel.png[Viewing NetcoredebugOutput plug-in logs in the *Output* panel] diff --git a/modules/end-user-guide/partials/proc_viewing-omnisharp-theia-plug-in-logs-in-the-output-panel.adoc b/modules/end-user-guide/partials/proc_viewing-omnisharp-theia-plug-in-logs-in-the-output-panel.adoc index 9ab46613ca..3bac98f6ff 100644 --- a/modules/end-user-guide/partials/proc_viewing-omnisharp-theia-plug-in-logs-in-the-output-panel.adoc +++ b/modules/end-user-guide/partials/proc_viewing-omnisharp-theia-plug-in-logs-in-the-output-panel.adoc @@ -1,8 +1,8 @@ // viewing-logs-for-dotnet-with-omnisharp-theia-plug-in [id="viewing-omnisharp-theia-plug-in-logs-in-the-output-panel_{context}"] -= Viewing Omnisharp-Theia plug-in logs in the Output panel += Viewing OmniSharp-Theia plug-in logs in the Output panel .Procedure -If `Omnisharp.exe` is running, it logs all information in the *Output* panel. To view the logs, open the *Output* view and select *C#* from the drop-down list. +If `OmniSharp.exe` is running, it logs all information in the *Output* panel. To view the logs, open the *Output* view and select *C#* from the drop-down list. 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 index 7b38ed2aee..3fc6b49e48 100644 --- 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 @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// making-a-workspace-portable-using-a-devfile +// configuring-a-workspace-using-a-devfile [id="writing-a-devfile-for-your-project_{context}"] = Writing a devfile for a project @@ -57,7 +57,7 @@ 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. +* 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. @@ -98,5 +98,5 @@ For a detailed explanation of all devfile component assignments and possible val These sample devfiles are a good source of inspiration: -* link:https://github.com/eclipse/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/master/samples[Sample devfiles for {prod} workspaces from Red Hat Developer program]. +* 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 index ed45d3b8a5..f4be37edbf 100644 --- 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 @@ -1,3 +1,13 @@ +pass:[] + +pass:[] + +pass:[] + +pass:[] + +pass:[] + // This assembly is included in the following assemblies: // // what-is-a-che-theia-plug-in @@ -7,30 +17,32 @@ 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. +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 plugin meta YAML files. This document represents the link:https://github.com/eclipse/che-plugin-registry#user-content-plugin-meta-yaml-structure[Plugin meta YAML structure version 3]. +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)]. -The link:https://github.com/eclipse/che-plugin-registry/tree/master/v3/plugins[che-plugin-registry repository] contains: +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 plugin's purpose +|`description`| Short description of the plug-in purpose |`displayName`| Name shown in user dashboard -|`deprecate` | Optional; section for deprecating plugins in favor of others +|`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 present in YAML, as if not present, it will be generated during Plugin Registry dockerimage build -|`latestUpdateDate`| Not required to be present in YAML, as if not present, it will be generated during Plugin Registry dockerimage build + * 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 plugin repository, for example, GitHub -|`title`| Plugin title (long) +|`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) @@ -38,8 +50,8 @@ The link:https://github.com/eclipse/che-plugin-registry/tree/master/v3/plugins[c .`spec` attributes |=== -|`endpoints` | Optional; plugin endpoint. See xref:making-a-workspace-portable-using-a-devfile.adoc#endpoints_{context}[] -|`containers`| Optional; sidecar containers for the plug-in. Che Plugin and VS Code extension supports only one container +|`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 @@ -60,7 +72,7 @@ The link:https://github.com/eclipse/che-plugin-registry/tree/master/v3/plugins[c |`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 plugin +|`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] |=== @@ -134,7 +146,7 @@ The link:https://github.com/eclipse/che-plugin-registry/tree/master/v3/plugins[c 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-machine-exec/ + repository: https://github.com/eclipse-che/che-machine-exec/ firstPublicationDate: "2020-03-18" category: Other spec: @@ -175,3 +187,13 @@ spec: extensions: - https://github.com/asciidoctor/asciidoctor-vscode/releases/download/v2.7.7/asciidoctor-vscode-2.7.7.vsix ---- + +pass:[] + +pass:[] + +pass:[] + +pass:[] + +pass:[] diff --git a/modules/end-user-guide/partials/ref_devfile-reference.adoc b/modules/end-user-guide/partials/ref_devfile-reference.adoc index ea34e3cd6e..4941ab99d4 100644 --- a/modules/end-user-guide/partials/ref_devfile-reference.adoc +++ b/modules/end-user-guide/partials/ref_devfile-reference.adoc @@ -1,15 +1,65 @@ // Module included in the following assemblies: // -// making-a-workspace-portable-using-a-devfile +// 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 `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: `YYYYY` or `YYYYY`. When both `generateName` and `name` are defined, `generateName` takes precedence. +==== + +[id="adding-projects-to-a-devfile_{context}"] == Adding projects to a devfile -Usually a devfile contains one or more projects. A workspace is created to develop those projects. Projects are added in the `projects` section of devfiles. +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: @@ -27,7 +77,7 @@ Project source consists of two mandatory values: `type` and `location`. `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. +`zip`:: Projects with sources in a `.zip` archive. Location points to a `.zip` file. === Project-source type: git @@ -36,11 +86,11 @@ Project source consists of two mandatory values: `type` and `location`. ---- source: type: git - location: https://github.com/eclipse/che.git - startPoint: master <1> - tag: 7.2.0 + location: https://github.com/eclipse-che/che-server.git + startPoint: main <1> + tag: 7.34.0 commitId: 36fe587 - branch: 7.20.x + branch: 7.34.x sparseCheckoutDir: core <2> ---- @@ -118,19 +168,19 @@ To specify that a workspace requires no editor, use the xref:attribute-editorfre === Component type: chePlugin -Describes plug-ins in a workspace by defining their `id`. It is allowed to have several `chePlugin` components. +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/0.0.1 + 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. +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. -List of available {prod-upstream} plug-ins and more information about registry can be found in the link:https://github.com/eclipse/che-plugin-registry[{prod-upstream} plug-in registry] GitHub repository. +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 @@ -142,12 +192,13 @@ To specify an alternative registry for the `cheEditor` and `chePlugin` component - alias: exec-plugin type: chePlugin registryUrl: https://my-customregistry.com - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/che-machine-exec-plugin/latest ---- === Specifying a component by linking to its descriptor -An alternative way of specifying `cheEditor` or `chePlugin`, instead of using the editor or plug-in `id` (and optionally an alternative registry), is to provide a direct link to the component descriptor (typically named `meta.yaml`) by using the `reference` field: + +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] ---- @@ -157,6 +208,8 @@ An alternative way of specifying `cheEditor` or `chePlugin`, instead of using th 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 @@ -165,7 +218,7 @@ A chePlugin component may need to be precisely tuned, and in such case, componen [source,yaml] ---- - id: redhat/java/0.38.0 + id: redhat/java/latest type: chePlugin preferences: java.jdt.ls.vmargs: '-noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication' @@ -175,14 +228,13 @@ Preferences may also be specified as an array: [source,yaml] ---- - id: redhat/java/0.38.0 + id: redhat/java/latest type: chePlugin preferences: go.lintFlags: ["--enable-all", "--new"] ---- - -=== Component type: kubernetes +=== Component type: `kubernetes` A complex component type that allows to apply configuration from a list of {orch-name} components. @@ -288,7 +340,7 @@ If enabled, project sources mounts will be applied to every container of the giv This parameter is also applicable for `chePlugin` type components. [id="component-type-dockerimage_{context}"] -=== Component type: dockerimage +=== 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. @@ -354,7 +406,7 @@ components: 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 +=== 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. @@ -424,7 +476,7 @@ To specify a container(s) memory limit for `dockerimage`, `chePlugin` or `cheEdi components: - alias: exec-plugin type: chePlugin - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/che-machine-exec-plugin/latest memoryLimit: 1Gi - alias: maven type: dockerimage @@ -448,7 +500,7 @@ To specify a container(s) memory request for `dockerimage`, `chePlugin` or `cheE components: - alias: exec-plugin type: chePlugin - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/che-machine-exec-plugin/latest memoryLimit: 1Gi memoryRequest: 512M - alias: maven @@ -474,7 +526,7 @@ To specify a container(s) CPU limit for `chePlugin`, `cheEditor` or `dockerimage components: - alias: exec-plugin type: chePlugin - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/che-machine-exec-plugin/latest cpuLimit: 1.5 - alias: maven type: dockerimage @@ -498,7 +550,7 @@ To specify a container(s) CPU request for `chePlugin`, `cheEditor` or `dockerima components: - alias: exec-plugin type: chePlugin - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/che-machine-exec-plugin/latest cpuLimit: 1.5 cpuRequest: 0.225 - alias: maven @@ -572,12 +624,13 @@ the {platforms-namespace} to which the workspace is deployed. * `CHE_MACHINE_AUTH_SIGNATURE__ALGORITHM`: The encryption algorithm used in the secured communication with the {prod-short} server. -A devfiles may only 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 (for example as part of a devfile command). The environment variables used to securely access the {prod-short} server are mostly out of scope for devfiles and are present only for advanced use cases that are usually handled by the {prod-short} plug-ins. + +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 want to be able to directly interact with it yourself or you want other components to interact with it. +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: @@ -636,9 +689,9 @@ Here, there are two Docker images, each defining a single endpoint. Endpoint is * `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 (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 loopback interface, such as `127.0.0.1`. +* `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 loopback poses a security risk because such server is accessible without the JWT authentication within the cluster network on the corresponding IP addresses. +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. @@ -648,7 +701,8 @@ WARNING: Listening on any other interface than the local loopback poses a securi + 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} autodetects this, and the UI offers to automatically expose this port as a `public` port. This is useful for debugging a web application, for example. It is impossible to do this for servers that autostart with the container (for example, a database server). For such components, specify the endpoints explicitly. + +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: @@ -811,7 +865,7 @@ items: storage: 1Gi ---- -For a basic example of a devfile with an associated {platforms-name} list, see link:https://github.com/redhat-developer/devfile/tree/master/samples/web-nodejs-with-db-sample[web-nodejs-with-db-sample] on redhat-developer GitHub. +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). @@ -833,8 +887,11 @@ components: app: postgres ---- -Additionally, it is also possible to modify the entrypoints (command and arguments) of the containers present in the resource list. For details of the advanced use case, see xref:creating-and-configuring-a-new-workspace.adoc#defining-specific-container-images_{context}[Defining specific container images]. +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. @@ -908,7 +965,7 @@ commands: === 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 present 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. +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] ---- @@ -940,7 +997,7 @@ commands: 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 launch configurations. +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 @@ -980,7 +1037,7 @@ To specify the preferred way of previewing a service URL: * `off` -- disables opening the preview URL (automatically and with a notification) -== Devfile attributes +== Adding attributes to a devfile Devfile attributes can be used to configure various features. @@ -1060,3 +1117,10 @@ projects: attributes: mergePlugins: false ---- + +pass:[] + +pass:[] + +pass:[] + 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 f4f78315d8..d520371571 100644 --- a/modules/end-user-guide/partials/ref_netcoredebugoutput-plug-in.adoc +++ b/modules/end-user-guide/partials/ref_netcoredebugoutput-plug-in.adoc @@ -6,4 +6,4 @@ 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. -The container where the NetcoredebugOutput plug-in is running contains Dotnet SDK v.2.2.105. +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 index 94132b7037..e021a77245 100644 --- a/modules/end-user-guide/partials/ref_objects-supported-in-che.adoc +++ b/modules/end-user-guide/partials/ref_objects-supported-in-che.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// making-a-workspace-portable-using-a-devfile +// configuring-a-workspace-using-a-devfile [id="objects-supported-in-{prod-id-short}_{context}"] = Objects supported in {prod} {prod-ver} @@ -61,7 +61,7 @@ The following table lists the objects that are partially supported in {prod} {pr |OpenShift |No |Yes -|The OpenShift recipe must be made compatible with the {kubernetes} Infrastructure and, instead of the provided route, generate Ingress. +|The OpenShift recipe must be made compatible with the {kubernetes} Infrastructure: OpenShift routes replaced on Ingresses. |Template |OpenShift diff --git a/modules/end-user-guide/partials/ref_omnisharp-theia-plug-in.adoc b/modules/end-user-guide/partials/ref_omnisharp-theia-plug-in.adoc index 17d11bc4d2..f4fa1c0ebf 100644 --- a/modules/end-user-guide/partials/ref_omnisharp-theia-plug-in.adoc +++ b/modules/end-user-guide/partials/ref_omnisharp-theia-plug-in.adoc @@ -1,9 +1,9 @@ // viewing-logs-for-dotnet-with-omnisharp-theia-plug-in [id="omnisharp-theia-plug-in_{context}"] -= Omnisharp-Theia plug-in += OmniSharp-Theia plug-in -{prod-short} uses the Omnisharp-Theia plug-in as a remote plug-in. It is located at +{prod-short} uses the OmniSharp-Theia plug-in as a remote plug-in. It is located at link:https://github.com/redhat-developer/omnisharp-theia-plugin[github.com/redhat-developer/omnisharp-theia-plugin]. In case of an issue, report it, or contribute your fix in the repository. This plug-in registers link:https://github.com/OmniSharp/omnisharp-roslyn[omnisharp-roslyn] as a language server and provides project dependencies and language syntax for C# applications. diff --git a/modules/extensions/images/lombok/lombok.png b/modules/extensions/images/lombok/lombok.png new file mode 100644 index 0000000000..a2243f23f7 Binary files /dev/null and b/modules/extensions/images/lombok/lombok.png differ diff --git a/modules/extensions/nav.adoc b/modules/extensions/nav.adoc index d6631f00bf..a1fce4af11 100644 --- a/modules/extensions/nav.adoc +++ b/modules/extensions/nav.adoc @@ -10,3 +10,4 @@ * xref:telemetry.adoc[] ** xref:creating-a-telemetry-plugin.adoc[] ** xref:the-woopra-telemetry-plugin.adoc[] +* xref:java-lombok.adoc[] diff --git a/modules/extensions/pages/java-lombok.adoc b/modules/extensions/pages/java-lombok.adoc new file mode 100644 index 0000000000..8523084a79 --- /dev/null +++ b/modules/extensions/pages/java-lombok.adoc @@ -0,0 +1,7 @@ +[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/partials/assembly_eclipse-che4z.adoc b/modules/extensions/partials/assembly_eclipse-che4z.adoc index 1c516fee99..85013526e1 100644 --- a/modules/extensions/partials/assembly_eclipse-che4z.adoc +++ b/modules/extensions/partials/assembly_eclipse-che4z.adoc @@ -1,15 +1,16 @@ - - :parent-context-of-eclipse-che4z: {context} [id="eclipse-che4z_{context}"] = Eclipse Che4z +pass:[] +pass:[] + 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 https://www.zowe.org/[Zowe] and link:https://www.eclipse.org/che/docs[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. +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 now 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. +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. @@ -43,11 +44,12 @@ COBOL Language Support enhances the COBOL programming experience on your IDE. Th ** Content assist * Automatic copybook retrieval -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]] -https://join.slack.com/t/che4z/shared_invite/enQtNzk0MzA4NDMzOTIwLWIzMjEwMjJlOGMxNmMyNzQ1NWZlMzkxNmQ3M2VkYWNjMmE0MGQ0MjIyZmY3MTdhZThkZDg3NGNhY2FmZTEwNzQ[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[slack]] +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]. -* For documentation and release information, see the https://github.com/eclipse/che-che4z-lsp-for-cobol[COBOL Language Support Git repository] -* How can we improve COBOL Language Support? 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] @@ -66,35 +68,38 @@ You can learn more about the Zowe Explorer by watching the https://www.youtube.c * Issue TSO commands. * Install additional extensions. -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]] -https://openmainframeproject.slack.com/[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[slack]] +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] -* For documentation, see link:https://docs.zowe.org/stable/user-guide/ze-install.html[Zowe Docs] -* How can we improve Zowe Explorer? link:https://github.com/zowe/vscode-extension-for-zowe/issues[Let us know on our Git repository] ==== Blogs: -* https://medium.com/zowe/beginners-guide-how-to-access-mainframe-via-zowe-in-10-easy-steps-fbec14ed6ed2[Beginner’s Guide: How to access mainframe via Zowe in 10 easy steps] * -* https://medium.com/zowe[Zowe blog] +* 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: +==== 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. -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]] -https://openmainframeproject.slack.com/[image:https://img.shields.io/badge/chat-on%20Slack-blue?style=flat-square[slack]] +* 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]. -* For documentation and release information, see the https://github.com/eclipse/che-che4z-lsp-for-hlasm[HLASM Language Support Git repository] -* How can we improve HLASM Language Support? 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 https://www.broadcom.com/products/mainframe/devops-app-development/app/endevor-software-change-manager[CA Endevor® SCM] elements using a user-friendly, intuitive interface. +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. @@ -104,8 +109,8 @@ This extension offers best developer experience in synergy with https://youtu.be 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] -* How can we improve Explorer for Endevor? https://github.com/eclipse/che-che4z-explorer-for-endevor/issues[Let us know] +* 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 @@ -118,17 +123,18 @@ Debugger for Mainframe provides the debugging interface to https://www.broadcom. 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 https://github.com/BroadcomMFD/debugger-for-mainframe[Debugger for Mainframe Git repository] -* How can we improve Debugger for Mainframe? https://github.com/BroadcomMFD/debugger-for-mainframe/issues[Let us know] +* 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: -* 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] -* 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] -* https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-brightside/3-0/zowe-cli/available-cli-plug-ins/ca-brightside-plug-in-for-ibm-db2-database.html[IBM Db2 plug-in for Zowe CLI] -* https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-brightside/3-0/zowe-cli/available-cli-plug-ins/ca-brightside-plug-in-for-ibm-cics.html[IBM CICS 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-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 @@ -143,7 +149,7 @@ Zowe Command Line-Interface (Zowe CLI) is a command-line interface that lets app === Debugger for Mainframe -* Provide InterTest server location, CICS region, credentials and program/transaction name (either by file or input form). +* 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. @@ -152,6 +158,11 @@ Zowe Command Line-Interface (Zowe CLI) is a command-line interface that lets app === 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 want 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. +* 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:[] + +pass:[] \ No newline at end of file diff --git a/modules/extensions/partials/assembly_openshift-connector-overview.adoc b/modules/extensions/partials/assembly_openshift-connector-overview.adoc index f1ba92096a..500404d3b1 100644 --- a/modules/extensions/partials/assembly_openshift-connector-overview.adoc +++ b/modules/extensions/partials/assembly_openshift-connector-overview.adoc @@ -11,7 +11,7 @@ OpenShift Connector, also referred to as Visual Studio Code OpenShift Connector OpenShift Connector makes it possible to create, build, and debug applications in the {prod-short} IDE and then deploy the applications directly to a running OpenShift cluster. -OpenShift Connector is a GUI for the OpenShift Do (`odo`) utility, which aggregates OpenShift CLI (`oc`) commands into compact units. As such, OpenShift Connector helps new developers who do not have OpenShift background with creating applications and running them on the cloud. Instead of using several `oc` commands, the user creates a new component or service by selecting a preconfigured template, such as a Project, an Application, or a Service, and then deploys it as an OpenShift Component to their cluster. +OpenShift Connector is a GUI for the OpenShift Do (`odo`) utility, which aggregates OpenShift CLI (`oc`) commands into compact units. As such, OpenShift Connector helps new developers who do not have OpenShift background with creating applications and running them on the cloud. Rather than using several `oc` commands, the user creates a new component or service by selecting a preconfigured template, such as a Project, an Application, or a Service, and then deploys it as an OpenShift Component to their cluster. This section provides information about installing, enabling, and basic use of the OpenShift Connector plug-in. diff --git a/modules/extensions/partials/assembly_telemetry-overview.adoc b/modules/extensions/partials/assembly_telemetry-overview.adoc index e715cc1126..679dddcef1 100644 --- a/modules/extensions/partials/assembly_telemetry-overview.adoc +++ b/modules/extensions/partials/assembly_telemetry-overview.adoc @@ -5,7 +5,7 @@ :context: telemetry-overview -Telemetry is the transparent and ethical collection of usage 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. +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]. @@ -14,10 +14,10 @@ This documentation includes a guide describing how to make your own telemetry cl {prod} telemetry API allows tracking: -* Duration of workspace usage -* User-driven actions like file editing, committing, and pushing to remote repositories +* 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 +* 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}"] @@ -29,4 +29,4 @@ If the {prod-short} workspace has a telemetry back-end container running, and it image::telemetry/telemetry_diagram.png[] -:context: {parent-context-of-telemetry-overview} \ No newline at end of file +:context: {parent-context-of-telemetry-overview} diff --git a/modules/extensions/partials/con_features-of-openshift-connector.adoc b/modules/extensions/partials/con_features-of-openshift-connector.adoc index 302da66f6f..46e4a887a2 100644 --- a/modules/extensions/partials/con_features-of-openshift-connector.adoc +++ b/modules/extensions/partials/con_features-of-openshift-connector.adoc @@ -34,4 +34,4 @@ When used in {prod-short}, the OpenShift Connector GUI provides the following be .Monitoring * Working with OpenShift resources directly from the {prod-short} IDE. * Starting and resuming build and deployment configurations. -* Viewing and following logs for deployments, pods, and containers. +* Viewing and following logs for deployments, Pods, and containers. 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 f4ac85692c..401f41a42a 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 @@ -1,53 +1,64 @@ // using-openshift-connector-in-eclipse-che - - [id="authenticating-with-openshift-connector-from-{prod-id-short}_{context}"] -= Authenticating with OpenShift Connector from {prod-short} += Authenticating with OpenShift Connector from {prod-short} when the OpenShift OAuth service does not authenticate the {prod-short} instance -The following section is relevant only when the OpenShift OAuth service does not already authenticate a {prod-short} instance; otherwise, the OpenShift Connector plug-in automatically establishes the authentication with the Openshift instance where {prod-short} runs. +This section describes how to authenticate with an OpenShift cluster when the OpenShift OAuth service does not authenticate the {prod-short} instance. It enables the user to develop and push Components from {prod-short} to the OpenShift instance that contains {prod-short}. -Before the user can develop and push Components from {prod-short}, they need to authenticate with an OpenShift cluster. +[NOTE] +==== +When the OpenShift OAuth service authenticates the {prod-short} instance, the OpenShift Connector plug-in automatically establishes the authentication with the OpenShift instance containing {prod-short}. +==== OpenShift Connector offers the following methods for logging in to the OpenShift Cluster from the {prod-short} instance: -* Using the notification that asks to log in to the OpenShift cluster where {prod-short} is deployed to. +* Using the notification asking to log in to the OpenShift instance containing {prod-short}. * Using the btn:[Log in to the cluster] button. * Using the Command Palette. [NOTE] ==== -.In {prod-short} {prod-ver}, Openshift Connector plug-in requires manual connecting to the target cluster +OpenShift Connector plug-in requires manual connecting to the target cluster. + +The OpenShift Connector plug-in logs in to the cluster as `inClusterUser`. If this user does not have manage project permission, this error message appears when creating a project using OpenShift Application Explorer: -By default, the Openshift Connector plug-in logs into the cluster as `inClusterUser`, which may not have the manage project permission. This causes an error message to be displayed when a new project is being created using Openshift Application Explorer: ----- +[quote] +____ Failed to create Project with error 'Error: Command failed: "/tmp/vscode-unpacked/redhat.vscode-openshift -connector.latest.qvkozqtkba.openshift-connector-0.1.4-523.vsix/extension/out/tools/linux/odo" project create test-project ✗ projectrequests.project.openshift.io is forbidden ----- +____ -To work around this temporary issue, log out from the local cluster and relog in to OpenShift cluster using the OpenShift user's credentials. +To work around this issue: + +. Log out from the local cluster. +. Log in to OpenShift cluster using the OpenShift user's credentials. ==== -When using a local instance of OpenShift (such as CodeReady Containers or Minishift), the user’s credentials are stored in the workspace `~/.kube/config` file, and may be used 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. +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::[] .Prerequisites -* A running instance of {prod-short}. To install an instance of {prod-short}, see xref:installation-guide:installing-che.adoc[]. -* A {prod-short} workspace has been created. -* The OpenShift Connector plug-in is available. -* The OpenShift OAuth provider is configured (only for the auto-login to the OpenShift cluster where {prod-short} is deployed. See xref:end-user-guide:configuring-openshift-oauth.adoc[]). + +* A running instance of {prod-short}. See xref:installation-guide:installing-che.adoc[]. + +* A {prod-short} workspace is available. See xref:end-user-guide:workspaces-overview.adoc[]. + +* 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[]. + .Procedure -. In the left panel, select the *OpenShift Application Explorer* icon. -+ -The OpenShift Connector panel is displayed. -. Log in using the OpenShift Application Explorer. Use one of the following methods: +. In the left panel, click the *OpenShift Application Explorer* icon. + +. In the OpenShift Connector panel, log in using the OpenShift Application Explorer. Use one of the following methods: ** Click the btn:[Log in to cluster] button in the top left corner of the pane. -** Press kbd:[F1] to open the Command Palette, or navigate to *View -> Find Command* in the top menu. +** Press kbd:[F1] to open the Command Palette, or navigate to *View > Find Command* in the top menu. + Search for *OpenShift: Log in to cluster* and press kbd:[Enter]. . If a *You are already logged in a cluster.* message appears, click *Yes*. + +. Select the method to log in to the cluster: *Credentials* or *Token*, and follow the login instructions. + -A selection whether to log in using *Credentials* or *Token* is displayed at the top of the screen. -. Select the method to log in to the cluster and follow the login instructions. -+ -NOTE: For authenticating with a token, the required token information is in the top right corner of the main {ocp} screen, under *____ -> Copy Login Command*. +NOTE: To authenticate with a token, the required token information is in the upper right corner of the main {ocp} screen, under *____ > Copy Login Command*. 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 d0700b9ef9..70d992b498 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 @@ -20,6 +20,6 @@ To make changes to your GitHub component, clone the repository into {prod-short} . In the {prod-short} main screen, open the *Command Palette* by pressing kbd:[F1]. . Type the `Git Clone` command in the *Command Palette* and press kbd:[Enter]. . Provide the GitHub URL and select the destination for the deployment. -. Add source-code files to your Project by clicking the btn:[Add to workspace] button. +. 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 index b8e901997f..bc03b7861b 100644 --- a/modules/extensions/partials/proc_creating-a-telemetry-plugin.adoc +++ b/modules/extensions/partials/proc_creating-a-telemetry-plugin.adoc @@ -3,7 +3,7 @@ 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 or not 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. +* `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`. @@ -34,22 +34,24 @@ For production use cases, consider integrating with a third-party telemetry syst The following Go code starts a server on port 8080 and writes events to standard output: -.main.go +.`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 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 hostname of your {platforms-name} cluster. Then run: +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"] ---- @@ -70,11 +72,13 @@ $ mvn io.quarkus:quarkus-maven-plugin:1.2.1.Final:create \ . Add a dependency to `org.eclipse.che.incubator.workspace-telemetry.back-end-base` in your `pom.xml`: + -.pom.xml +.`pom.xml` +==== [source,xml] ---- include::example$telemetry/pom_snippet.xml[] ---- +==== . Add the Apache HTTP components library to send HTTP requests. @@ -82,11 +86,13 @@ include::example$telemetry/pom_snippet.xml[] . Create a `settings.xml` file in the repository root and add the coordinates and token to the `che-incubator` packages: + -.settings.xml +.`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. @@ -118,107 +124,125 @@ $ mvn quarkus:dev -Dquarkus.http.port=${CHE_WORKSPACE_TELEMETRY_BACKEND_PORT} \ Create two new files in your project: -* `AnalyticsManager.java` - contains the logic specific to our telemetry system. +* `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 +.`AnalyticsManager.java` +==== [source,java] ---- include::example$telemetry/AnalyticsManagerSkeleton.java[] ---- +==== -.MainConfiguration.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 +.`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 our server. The example telemetry server application is deployed to OpenShift at the following URL: `++http://little-telemetry-back-end-che.apps-crc.testing++`. +`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 +.`AnalyticsManager.java` +==== [source,java] ---- include::example$telemetry/onEvent.java[] ---- +==== -This sends an HTTP request to the telemetry server and automatically debounces identical events in a small time period, where the default value is 1500 milliseconds. It is possible to modify this period by setting subclasses. +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, so that a user does not get several identical events sent to the server in a small time frame. This implementation of `increaseDuration()` is a no-op. This method uses the APIs of a user's telemetry provider to alter the event or event properties to reflect an event's increased duration. +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 +.`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 +.`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 +.`AnalyticsManager.java` +==== [source,java] ---- include::example$telemetry/destroy.java[] ---- +==== -Now when you run `mvn quarkus:dev` as described in xref:running-the-application_{context}[], you should see a `WORKSPACE_STOPPED` event sent to the server when you kill the Quarkus application. +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. +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. +== 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 on `meta.yaml`, see xref:end-user-guide:what-is-a-che-theia-plug-in.adoc[]. +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[] ---- +==== -Usually, a user would deploy this file to a corporate web server. For this guide, we create an Apache web server on OpenShift and host the plug-in there. +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. +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. +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 +.`manifests.yaml` +==== [source,yaml,subs="+quotes,+attributes"] ---- include::example$telemetry/webserver.yaml[] ---- +==== ---- $ oc apply -f manifests.yaml @@ -234,16 +258,18 @@ 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 should 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*). +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 e4e79e65f6..7dab2d8b5f 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 @@ -5,7 +5,7 @@ [id="creating-components-with-openshift-connector-in-{prod-id-short}_{context}"] = Creating Components with OpenShift Connector in {prod-short} -In the context of OpenShift, Components and Services are basic structures that need to be stored in Application, which is a part of the OpenShift project that organizes deployables into virtual folders for better readability. +In the context of OpenShift, Components and Services are basic structures that need to be stored in Application, which is a part of the OpenShift project that organizes deployable assets into virtual folders for better readability. This chapter describes how to create OpenShift Components in the {prod-short} using the OpenShift Connector plug-in and push them to an OpenShift cluster. @@ -46,4 +46,4 @@ This prompts you to select a folder from the file explorer. //creates a route with the given name in openshift . The component is ready to be pushed to the OpenShift cluster. To do so, right-click the component and select *Push*. + -The component is now deployed to the cluster. Right-click for selecting additional actions, such as debugging and opening in a browser (requires port `8080` to be exposed). +The component is deployed to the cluster. Use a right-click for selecting additional actions, such as debugging and opening in a browser, which requires the exposure of the port `8080`. 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 f43d4d99d5..bfde4928b7 100644 --- a/modules/extensions/partials/proc_installing-openshift-connector-in-che.adoc +++ b/modules/extensions/partials/proc_installing-openshift-connector-in-che.adoc @@ -19,6 +19,6 @@ To install and enable OpenShift Connector in a {prod-short} instance, use instru 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*. -. Search for *vscode-openshift-connector*, and click the btn:[Install] button. +. Search for *`vscode-openshift-connector`*, and click the btn:[Install] button. . Restart the workspace for the changes to take effect. . The dedicated OpenShift Application Explorer icon is added to the left panel. diff --git a/modules/extensions/partials/proc_java-lombok.adoc b/modules/extensions/partials/proc_java-lombok.adoc new file mode 100644 index 0000000000..019c9a784e --- /dev/null +++ b/modules/extensions/partials/proc_java-lombok.adoc @@ -0,0 +1,42 @@ +[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 index bf1e110fe1..1b1ece8dc3 100644 --- a/modules/extensions/partials/ref_the-woopra-telemetry-plugin.adoc +++ b/modules/extensions/partials/ref_the-woopra-telemetry-plugin.adoc @@ -2,14 +2,14 @@ = 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://che.openshift.io[Hosted Che], 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: +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 your {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: +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] ---- diff --git a/modules/glossary/partials/con_glossary.adoc b/modules/glossary/partials/con_glossary.adoc index 5cc0ddcf40..22da45180b 100644 --- a/modules/glossary/partials/con_glossary.adoc +++ b/modules/glossary/partials/con_glossary.adoc @@ -12,7 +12,7 @@ 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 mostly 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 plugins, which are packaged as containers for ease of deployment and use. Che-Theia plugins 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. @@ -22,7 +22,7 @@ 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. //TODO See for a diagram of {prod-short} extensibility architecture. -Both {prod-short} plugins and editors are distributed through the {prod-short} plugin registry. +Both {prod-short} plugins 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`. diff --git a/modules/hosted-che/examples/snip_github-action-yaml-example-activity-types.adoc b/modules/hosted-che/examples/snip_github-action-yaml-example-activity-types.adoc new file mode 100644 index 0000000000..9c1cc76527 --- /dev/null +++ b/modules/hosted-che/examples/snip_github-action-yaml-example-activity-types.adoc @@ -0,0 +1,9 @@ +.Triggering the workflow on both `opened` and `synchronize` activity types +==== +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +on: + pull_request_target: + types: [opened, synchronize] +---- +==== \ No newline at end of file diff --git a/modules/hosted-che/examples/snip_github-action-yaml-example.adoc b/modules/hosted-che/examples/snip_github-action-yaml-example.adoc new file mode 100644 index 0000000000..aa5bd6d7cd --- /dev/null +++ b/modules/hosted-che/examples/snip_github-action-yaml-example.adoc @@ -0,0 +1,30 @@ +.example.yml +==== +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +name: Try in Web IDE example + +on: + pull_request_target: + types: [opened] + +jobs: + add-link: + runs-on: ubuntu-20.04 + steps: + - name: Web IDE Pull Request Check + id: try-in-web-ide + uses: redhat-actions/try-in-web-ide@v1 + with: + # GitHub action inputs + + # required + github_token: ${{ secrets.GITHUB_TOKEN }} + + # optional - defaults to true + add_comment: true + + # optional - defaults to true + add_status: true +---- +==== \ No newline at end of file diff --git a/modules/hosted-che/images/hosted-che/finding-the-cluster-where-the-hosted-che-workspace-is-running.png b/modules/hosted-che/images/hosted-che/finding-the-cluster-where-the-hosted-che-workspace-is-running.png deleted file mode 100644 index e0da5bccb9..0000000000 Binary files a/modules/hosted-che/images/hosted-che/finding-the-cluster-where-the-hosted-che-workspace-is-running.png and /dev/null differ diff --git a/modules/hosted-che/images/hosted-che/get-started-product-and-community-devfiles.png b/modules/hosted-che/images/hosted-che/get-started-product-and-community-devfiles.png new file mode 100644 index 0000000000..5b6d5df96d Binary files /dev/null and b/modules/hosted-che/images/hosted-che/get-started-product-and-community-devfiles.png differ diff --git a/modules/hosted-che/images/hosted-che/github-action-comment.png b/modules/hosted-che/images/hosted-che/github-action-comment.png new file mode 100644 index 0000000000..b11b1b11f7 Binary files /dev/null and b/modules/hosted-che/images/hosted-che/github-action-comment.png differ diff --git a/modules/hosted-che/images/hosted-che/github-action-status-check.png b/modules/hosted-che/images/hosted-che/github-action-status-check.png new file mode 100644 index 0000000000..aab3d4d7e4 Binary files /dev/null and b/modules/hosted-che/images/hosted-che/github-action-status-check.png differ diff --git a/modules/hosted-che/nav.adoc b/modules/hosted-che/nav.adoc index 0bde164410..d68f2f68ff 100644 --- a/modules/hosted-che/nav.adoc +++ b/modules/hosted-che/nav.adoc @@ -1 +1,2 @@ -* xref:hosted-che.adoc[] \ No newline at end of file +* xref:hosted-che.adoc[] +** xref:try-in-web-ide-github-action.adoc[] \ No newline at end of file diff --git a/modules/hosted-che/pages/try-in-web-ide-github-action.adoc b/modules/hosted-che/pages/try-in-web-ide-github-action.adoc new file mode 100644 index 0000000000..4b5e90803e --- /dev/null +++ b/modules/hosted-che/pages/try-in-web-ide-github-action.adoc @@ -0,0 +1,7 @@ +[id="try-in-web-ide-github-action"] +// = Try in Web IDE GitHub action +:navtitle: Try in Web IDE GitHub action +:keywords: hosted-che, try-in-web-ide-github-action +:page-aliases: .:try-in-web-ide-github-action + +include::partial$assembly_try-in-web-ide-github-action.adoc[] diff --git a/modules/hosted-che/partials/assembly_hosted-che.adoc b/modules/hosted-che/partials/assembly_hosted-che.adoc index 1a9db320c3..5cca51c629 100644 --- a/modules/hosted-che/partials/assembly_hosted-che.adoc +++ b/modules/hosted-che/partials/assembly_hosted-che.adoc @@ -7,7 +7,7 @@ :context: hosted-che -This section describes procedures to get started with Eclipse Che hosted by Red Hat that are not covered by xref:end-user-guide:workspaces-overview.adoc[]. +This section describes procedures to get started with Eclipse Che hosted by Red Hat - https://workspaces.openshift.com include::partial$ref_about-hosted-che.adoc[leveloffset=+1] @@ -17,12 +17,8 @@ include::partial$proc_creating-a-workspace-from-the-user-dashboard.adoc[leveloff include::partial$proc_creating-a-workspace-from-template-in-hosted-che.adoc[leveloffset=+1] -include::partial$proc_importing-projects-from-github-in-hosted-che.adoc[leveloffset=+1] - include::partial$proc_contributing-to-github-projects-in-hosted-che.adoc[leveloffset=+1] -include::partial$proc_finding-the-cluster-where-the-hosted-che-workspace-is-running.adoc[leveloffset=+1] - include::partial$ref_hosted-che-faq-and-troubleshooting.adoc[leveloffset=+1] .Additional resources diff --git a/modules/hosted-che/partials/assembly_try-in-web-ide-github-action.adoc b/modules/hosted-che/partials/assembly_try-in-web-ide-github-action.adoc new file mode 100644 index 0000000000..801e4e1572 --- /dev/null +++ b/modules/hosted-che/partials/assembly_try-in-web-ide-github-action.adoc @@ -0,0 +1,14 @@ +:parent-context-of-hosted-che: {context} + +[id="try_in_web_ide_github_action_{context}"] += Try in Web IDE GitHub action + +:context: hosted-che + +include::partial$ref_about-try-in-web-ide-github-action.adoc[leveloffset=+1] + +include::partial$proc_adding-the-action-to-a-github-repository-workflow.adoc[leveloffset=+1] + +include::partial$proc_providing-a-devfile.adoc[leveloffset=+1] + +: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 new file mode 100644 index 0000000000..641fe4227f --- /dev/null +++ b/modules/hosted-che/partials/proc_adding-the-action-to-a-github-repository-workflow.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// hosted-che + +[id="adding-the-action-to-a-github-repository-workflow_{context}"] += Adding the action to a GitHub repository workflow + +This section describes how to integrate the Try in Web IDE GitHub action to a GitHub repository workflow. + +.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]) + +.Procedure + +. In the GitHub repository, create a `.github/workflows` directory if it does not exist already. + +. Create an `example.yml` file in the `.github/workflows` directory with the following content: ++ +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], + 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. ++ +include::example$snip_github-action-yaml-example-activity-types.adoc[] + +. Optionally configure the `add_comment` and `add_status` GitHub action inputs within `example.yml`. These inputs are sent to the Try in Web IDE GitHub action to customize whether comments and status checks are to be made. 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 a3f849e00f..b886a02035 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 @@ -3,22 +3,18 @@ // hosted-che [id="contributing-to-github-projects-in-hosted-che_{context}"] -= Contributing to GitHub projects in Hosted Che += Contributing to GitHub projects from Eclipse Che hosted by Red Hat -This section describes how to contribute to GitHub projects in Hosted Che. +This section describes how to contribute to GitHub projects from Eclipse Che hosted by Red Hat. .Prerequisites -* A workspace running in Hosted Che, including a project imported from GitHub. See xref:importing-projects-from-github-in-hosted-che_{context}[]. +* A workspace running in Eclipse Che hosted by Red Hat, including a project imported from GitHub. -* The link:https://github.com/eclipse/che-theia/tree/master/plugins/ssh-plugin[SSH Plug-in] is available in the workspace. +* The link:https://github.com/eclipse-che/che-theia/tree/master/plugins/ssh-plugin[SSH Plug-in] is available in the workspace. .Procedure -. Generate an SSH key pair with the link:https://github.com/eclipse/che-theia/tree/master/plugins/ssh-plugin[SSH Plug-in]. +. 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. - -// .Additional resources - -// TODO: * To learn more, see link:end-user-tasks.html#configuring-your-vcs-credentials-for-your-workspaces_end-user-tasks[Configuring your VCS credentials for your workspaces]. 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 064860fbad..51c8beb5b4 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 @@ -3,7 +3,7 @@ // hosted-che [id="creating-a-workspace-from-template-in-hosted-che_{context}"] -= Creating a workspace from a template in Hosted Che += Creating a workspace from a template on the official Eclipse Che website This section describes how to create a workspace from a predefined link:https://www.eclipse.org/che/getting-started/cloud/[template]. @@ -11,7 +11,7 @@ Various programming languages and frameworks are supported. .Prerequisites -* Existing Hosted Che account. See xref:registering-to-hosted-che_{context}[]. +* Existing Eclipse Che hosted by Red Hat account. See xref:registering-to-hosted-che_{context}[]. .Procedure @@ -19,8 +19,12 @@ Various programming languages and frameworks are supported. . Choose the required type of a workspace. +pass:[] + . Click the btn:[Launch Workspace] button. -The workspace is created and displayed in Hosted Che. +pass:[] + +The workspace is created and displayed in the Eclipse Che hosted by Red hat. image::hosted-che/getting-started-devfile.png[] 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 fd63809839..cadd6ce643 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 @@ -6,27 +6,19 @@ [id="creating-a-workspace-from-the-user-dashboard_{context}"] = Creating a workspace from the user dashboard -This section describes how to create a workspace from the user dashboard in Hosted Che. +This section describes how to create a workspace from the user dashboard in Eclipse Che hosted by Red Hat. .Prerequisites -* Existing Hosted Che account. See xref:registering-to-hosted-che_{context}[]. +* Existing Eclipse Che hosted by Red Hat account. See xref:registering-to-hosted-che_{context}[]. .Procedure -. Navigate to the link:https://che.openshift.io/dashboard/[Hosted Che user dashboard]. +. Navigate to link:https://workspaces.openshift.com[`workspaces.openshift.com`]. -. Click the btn:[Create Workspace] button. +. Once login, the redirect to the user dashboard will happen. -. Define a *Name* for the workspace. A generated name is proposed. It can be modified. - -. In the *Stack* section, select the workspace runtime environment that will be used to build and run projects from the list. - -. In the *RAM* section, adapt the memory available for the workspace runtime environment within the limits defined in the xref:about-hosted-che_{context}[terms of service]. - -. In the *Storage Type* section, choose to have persistent storage attached or not. For more details, see xref:installation-guide:configuring-storage-types.adoc[]. - -. In the *Projects* section, choose the projects to integrate in the workspace. For the specific GitHub case, see xref:importing-projects-from-github-in-hosted-che_{context}[Importing projects from GitHub in Hosted Che]. +. 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. .Additional resources diff --git a/modules/hosted-che/partials/proc_finding-the-cluster-where-the-hosted-che-workspace-is-running.adoc b/modules/hosted-che/partials/proc_finding-the-cluster-where-the-hosted-che-workspace-is-running.adoc deleted file mode 100644 index 8839b8f3ff..0000000000 --- a/modules/hosted-che/partials/proc_finding-the-cluster-where-the-hosted-che-workspace-is-running.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// hosted-che - -[id="finding-the-cluster-where-the-hosted-che-workspace-is-running_{context}"] -= Finding the cluster where the Hosted Che workspace is running - -This section describes how to find the cluster where the Hosted Che workspace is running with a query to the OpenShift API on Hosted Che. - -.Prerequisites - -* The _curl_ and _jq_ packages are installed -* Make a note of the *username* or *email* credential that the user used to log into Hosted Che - -.Procedure - -. Find the cluster name using the *username*. -+ ----- -$ curl -sgSL "https://api.openshift.io/api/users?filter[username]=" | jq -r ".data[0].attributes.cluster" ----- - -. Find the cluster name using the *email*. -+ ----- -$ curl -sgSL "https://api.openshift.io/api/users?filter[email]=" | jq -r ".data[0].attributes.cluster" ----- -+ -The output of the query is the OpenShift Online cluster URL -+ -.Example ----- -https://api.starter-us-east-2.openshift.com/ ----- - -. Browse to the previously retrieved URL. - -. Log in using the OpenShift Online credentials. - -The OpenShift Console is displayed. - -The *____-che* {orch-namespace} where all the workspace related Pods are created are accessible in read-only mode: - -image::hosted-che/finding-the-cluster-where-the-hosted-che-workspace-is-running.png[] diff --git a/modules/hosted-che/partials/proc_importing-projects-from-github-in-hosted-che.adoc b/modules/hosted-che/partials/proc_importing-projects-from-github-in-hosted-che.adoc deleted file mode 100644 index b28de7eed8..0000000000 --- a/modules/hosted-che/partials/proc_importing-projects-from-github-in-hosted-che.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// hosted-che - -[id="importing-projects-from-github-in-hosted-che_{context}"] -= Importing projects from GitHub in Hosted Che - -This section describes how to import a GitHub project in Hosted Che. - -The user can import a GitHub project during the creation of a new workspace, or later, in an existing workspace. - -.Prerequisites - -* Existing Hosted Che account. See xref:registering-to-hosted-che_{context}[]. - -* Existing GitHub account. - -.Procedure - -. Navigate to the *Projects* section of the *New Workspace* creation window. -+ -Alternatively if the workspace is already existing, navigate to the *Projects* section of the *Configure Workspace* window. - -. Click the btn:[Add Project] button. - -. Navigate to the *GitHub* tab. - -. Click the btn:[Connect your GitHub account] button. - -. In the pop-up window, review the settings and click the btn:[Authorize openshiftio] button. - -. Type the password as requested and click the btn:[Confirm password] button. - -. Select the required repositories and click the btn:[Add] button. diff --git a/modules/hosted-che/partials/proc_providing-a-devfile.adoc b/modules/hosted-che/partials/proc_providing-a-devfile.adoc new file mode 100644 index 0000000000..8deb508090 --- /dev/null +++ b/modules/hosted-che/partials/proc_providing-a-devfile.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// hosted-che + +[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. + +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. diff --git a/modules/hosted-che/partials/proc_registering-to-hosted-che.adoc b/modules/hosted-che/partials/proc_registering-to-hosted-che.adoc index 6e8403727d..12b8ec8e55 100644 --- a/modules/hosted-che/partials/proc_registering-to-hosted-che.adoc +++ b/modules/hosted-che/partials/proc_registering-to-hosted-che.adoc @@ -3,20 +3,18 @@ // hosted-che [id="registering-to-hosted-che_{context}"] -= Registering to Hosted Che += Registering to Eclipse Che hosted by Red Hat -This section describes how to register to Hosted Che. +This section describes how to register to Eclipse Che hosted by Red Hat. .Procedure -. Navigate to link:https://che.openshift.io/[Hosted Che]. +. Navigate to link:https://developers.redhat.com/developer-sandbox[Developer Sandbox for Red Hat OpenShift]. -. Log in with an existing OpenShift Online, Red Hat Developer Program, or Red Hat Customer Portal account, *or* register for a new Red Hat account. +. Register with an existing OpenShift Online, Red Hat Developer Program, or Red Hat Customer Portal account, *or* create a new Red Hat account. -. Click the btn:[Activate account] button. +. Verify the telephone number -. Wait for an email with a link to connect to the Eclipse {prod-short} instance. It is sent after the environment is ready for use. +IMPORTANT: A valid telephone number is required for reducing the creation of fraudulent accounts on the Developer Sandbox for Red Hat OpenShift. Red Hat will not use this information for any other reason, and you will never receive a telephone call from Red Hat or any third-party because of trying the sandbox. -. Follow the *Get Started* link in the email. - -The Hosted Che user dashboard is displayed. +. Once the account is provisioned, Eclipse Che hosted by Red Hat will be ready for use from both link:https://developers.redhat.com/developer-sandbox/ide[Developer Sandbox] and https://workspaces.openshift.com pages. diff --git a/modules/hosted-che/partials/ref_about-hosted-che.adoc b/modules/hosted-che/partials/ref_about-hosted-che.adoc index 1cb4242929..80d8b06824 100644 --- a/modules/hosted-che/partials/ref_about-hosted-che.adoc +++ b/modules/hosted-che/partials/ref_about-hosted-che.adoc @@ -4,36 +4,42 @@ [id="about-hosted-che_{context}"] -= About Hosted Che += About Eclipse Che hosted by Red Hat -Hosted Che is link:https://www.eclipse.org/che/[Eclipse {prod-short}] hosted by Red Hat. -A {prod-short} server is running on OpenShift Dedicated, and the user base is spread across multiple OpenShift Online clusters where workspaces are created. +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]. + +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. + +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. +==== [id="terms-of-service_{context}"] == Terms of service -Hosted Che has the following usage limits and terms of service: +Eclipse Che hosted by Red Hat has the following usage limits and terms of service: -* Storage: 2 GB +* Storage: 10 GB * RAM: 7 GB * Concurrent workspaces: 1 * Number of workspaces: Unlimited * Number of projects per workspace: Unlimited -* Usage time limit: None -* Maximum time for a running workspace: 8 hours -+ -NOTE: Hosted Che automatically stops workspaces that run more than 8 hours regardless of activity. - -* Maximum account inactivity period: 30 days -+ -NOTE: Hosted Che automatically deactivates accounts that have been inactive for more than 30 days. All existing workspaces in a deactivated account are lost. To start using Hosted Che again, a user must re-register. +* Usage time limit: 30 days ++ +NOTE: The account will be active for 30 days. At the end of the active period, the access will be revoked and all the data will be deleted. All existing workspaces will be lost. To start using Eclipse Che hosted by Red Hat again, a user must re-register. -* Workspace idling time: 15 minutes +* Maximum time for a running workspace: 8 hours + -NOTE: A started workspace can be used for an unlimited period of time. When there are no interactions with the IDE, the workspace is stopped after 15 minutes. +NOTE: Eclipse Che hosted by Red Hat automatically stops workspaces that run more than 8 hours regardless of activity. -* Temporary Storage: Defaults to *Active* +* Workspace idling time: 30 minutes + -NOTE: In the temporary storage mode, workspaces have no persistent storage attached. All content changes are lost when the workspace is stopped unless they are pushed to a source-code repository first. This is done to improve the performance of workspace starts and file-system operations in the IDE. - -It is possible to disable the temporary storage mode while xref:#creating-a-workspace-from-the-user-dashboard_{context}[creating a workspace from the user dashboard]. +NOTE: If there are no interactions with the IDE, the workspace will be stopped after 30 minutes. 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 new file mode 100644 index 0000000000..900342a774 --- /dev/null +++ b/modules/hosted-che/partials/ref_about-try-in-web-ide-github-action.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// hosted-che + + +[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. + +NOTE: The Che documentation repository (https://github.com/eclipse/che-docs) is a real-life example where the Try in Web IDE GitHub action helps reviewers quickly test pull requests. Experience the workflow by navigating to a recent pull request and opening a factory URL. + +.Pull request comment created by the Try in Web IDE GitHub action. Clicking the badge opens a new workspace for reviewers to test the pull request. +image::hosted-che/github-action-comment.png[test] + +.Pull request status check created by the Try in Web IDE GitHub action. Clicking the "Details" link opens a new workspace for reviewers to test the pull request. +image::hosted-che/github-action-status-check.png[test] 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 ba4b1f02b6..aca719e2fb 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 @@ -8,24 +8,18 @@ == FAQs -**Q**: Where can I see the up-to-date status of Eclipse Che hosted by Red Hat? - -**A**: On a dedicated status page - https://che.statuspage.io/ +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 -=== Cannot log into the Hosted Che - Authorization token is missed +.Authentication -To authenticate to https://che.openshift.io, one needs to allow cookies from the `static.developers.redhat.com`. -In case these cookies are blocked (by a browser extension like https://www.eff.org/privacybadger[Privacy Badger]), -authentication fails with the following error: +To authenticate to link:https://workspaces.openshift.com[Red Hat Developer Sandbox], allow cookies from the `static.developers.redhat.com` page. This authentication will fail in a scenario where these cookies are blocked by a browser extension such as link:https://www.eff.org/privacybadger[Privacy Badger]. ----- -Authorization token is missing -Click here to reload page. ----- +.Telemetry -Also, note that telemetry is enabled in Eclipse Che hosted by Red Hat, so Woopra / Segment tracking scripts must be explicitly allowed in case being blocked by a browser extension: +Telemetry is enabled in Eclipse Che hosted by Red Hat, so Woopra or Segment tracking scripts must be explicitly allowed in case being blocked by a browser extension: - https://api.segment.io/v1/t - https://static.woopra.com/js/w.js diff --git a/modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc b/modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc index 03f405c19a..fb96de4666 100644 --- a/modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc +++ b/modules/installation-guide/examples/assembly_che-installing-che-in-a-restricted-environment.adoc @@ -23,7 +23,7 @@ include::example$con_{project-context}-understanding-network-connectivity-in-res include::partial$ref_understanding-the-registries.adoc[leveloffset=+1] -include::example$snip_{project-context}-building-offline-registry-images.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/installation-guide/examples/che-pvc-strategies.adoc b/modules/installation-guide/examples/che-pvc-strategies.adoc deleted file mode 100644 index 694aaab27a..0000000000 --- a/modules/installation-guide/examples/che-pvc-strategies.adoc +++ /dev/null @@ -1,25 +0,0 @@ - -[width="100%",cols="^,^,^,^",options="header"] -|=== -|Strategy |Details |Pros |Cons -|*common (default)* | -One PVC for all workspaces in one {platforms-namespace} - - -| Easy to manage and control storage | If PV does not support `ReadWriteMany` (RWX) access mode, the configuration will work only if one or both of the following apply: - -* Each workspace is in a separate {platforms-namespace} - -* Only one workspace is running per {platforms-namespace} at the same time. See xref:installation-guide:running-more-than-one-workspace-at-a-time.adoc[]. -|*per-workspace* | - -One PVC for one workspace - -| Easier to manage and control storage compared to unique strategy | PV count is not known and depends on workspaces number -|*unique* | - -One PVC per workspace volume or user-defined PVC - -| Storage isolation | An undefined number of PVs is required -|=== - diff --git a/modules/installation-guide/examples/checluster-properties.adoc b/modules/installation-guide/examples/checluster-properties.adoc new file mode 100644 index 0000000000..5bedbe68a7 --- /dev/null +++ b/modules/installation-guide/examples/checluster-properties.adoc @@ -0,0 +1,190 @@ +pass:[] + +[id="checluster-custom-resource-server-settings_{context}"] +.`CheCluster` Custom Resource `server` settings, related to the {prod-short} server component. + +[cols="2,5", options="header"] +:=== + Property: Description +airGapContainerRegistryHostname: Optional host name, or URL, to an alternate container registry to pull images from. This value overrides the container registry host name defined in all the default container images involved in a Che deployment. This is particularly useful to install Che in a restricted environment. +airGapContainerRegistryOrganization: Optional repository name of an alternate container registry to pull images from. This value overrides the container registry organization defined in all the default container images involved in a Che deployment. This is particularly useful to install {prod-short} in a restricted environment. +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. +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. +cheImagePullPolicy: Overrides the image pull policy used in Che deployment. Default value is `Always` for `nightly`, `next` or `latest` images, and `IfNotPresent` in other cases. +cheImageTag: Overrides the tag of the container image used in Che deployment. Omit it or leave it empty to use the default image tag provided by the Operator. +cheLogLevel: Log level for the Che server\: `INFO` or `DEBUG`. Defaults to `INFO`. +cheServerIngress: The Che server ingress custom settings. +cheServerRoute: The Che server route custom settings. +cheWorkspaceClusterRole: Custom cluster role bound to the user for the Che workspaces. The role must have `app.kubernetes.io/part-of=che.eclipse.org` label. The default roles are used when omitted or left blank. +customCheProperties: Map of additional environment variables that will be applied in the generated `che` ConfigMap to be used by the Che server, in addition to the values already generated from other fields of the `CheCluster` custom resource (CR). When `customCheProperties` contains a property that would be normally generated in `che` ConfigMap from other CR fields, the value defined in the `customCheProperties` is used instead. +dashboardCpuLimit: Overrides the CPU limit used in the dashboard deployment. In cores. (500m = .5 cores). Default to 500m. +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. +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. +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. +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. +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. +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. +gitSelfSignedCert: When enabled, the certificate from `che-git-self-signed-cert` ConfigMap will be propagated to the Che components and provide particular configuration for Git. Note, the `che-git-self-signed-cert` ConfigMap must have `app.kubernetes.io/part-of=che.eclipse.org` label. +nonProxyHosts: List of hosts that will be reached directly, bypassing the proxy. Specify wild card domain use the following form `.` and `|` as delimiter, for example\: `localhost|.my.host.com|123.42.12.32` Only use when configuring a proxy is required. Operator respects OpenShift cluster wide proxy configuration and no additional configuration is required, but defining `nonProxyHosts` in a custom resource leads to merging non proxy hosts lists from the cluster proxy configuration and ones defined in the custom resources. See the doc https\://docs.openshift.com/container-platform/4.4/networking/enable-cluster-wide-proxy.html. See also the `proxyURL` fields. +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. +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. +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. +proxySecret: The secret that contains `user` and `password` for a proxy server. When the secret is defined, the `proxyUser` and `proxyPassword` are ignored. The secret must have `app.kubernetes.io/part-of=che.eclipse.org` label. +proxyURL: URL (protocol+host name) of the proxy server. This drives the appropriate changes in the `JAVA_OPTS` and `https(s)_proxy` variables in the Che server and workspaces containers. Only use when configuring a proxy is required. Operator respects OpenShift cluster wide proxy configuration and no additional configuration is required, but defining `proxyUrl` in a custom resource leads to overrides the cluster proxy configuration with fields `proxyUrl`, `proxyPort`, `proxyUser` and `proxyPassword` from the custom resource. See the doc https\://docs.openshift.com/container-platform/4.4/networking/enable-cluster-wide-proxy.html. See also the `proxyPort` and `nonProxyHosts` fields. +proxyUser: User name of the proxy server. Only use when configuring a proxy is required. See also the `proxyURL`, `proxyPassword` and `proxySecret` fields. +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. +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. +singleHostGatewayConfigMapLabels: The labels that need to be present in the ConfigMaps representing the gateway configuration. +singleHostGatewayConfigSidecarImage: The image used for the gateway sidecar that provides configuration to the gateway. Omit it or leave it empty to use the default container image provided by the Operator. +singleHostGatewayImage: The image used for the gateway in the single host mode. Omit it or leave it empty to use the default container image provided by the Operator. +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 ``, `` and `` placeholders, such as che-workspace-. In that case, a new namespace will be created for each user or workspace. +:=== + +[id="checluster-custom-resource-database-settings_{context}"] +.`CheCluster` Custom Resource `database` configuration settings related to the database used by {prod-short}. + +[cols="2,5", options="header"] +:=== + Property: Description +chePostgresContainerResources: PostgreSQL container custom settings +chePostgresDb: PostgreSQL database name that the Che server uses to connect to the DB. Defaults to `dbche`. +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. +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. +postgresImagePullPolicy: Overrides the image pull policy used in the PostgreSQL database deployment. Default value is `Always` for `nightly`, `next` or `latest` images, and `IfNotPresent` in other cases. +postgresVersion: Indicates a PostgreSQL version image to use. Allowed values are\: `9.6` and `13.3`. Migrate your PostgreSQL database to switch from one version to another. +pvcClaimSize: Size of the persistent volume claim for database. Defaults to `1Gi`. To update pvc storageclass that provisions it must support resize when {prod-short} has been already deployed. +:=== + +[id="checluster-custom-resource-auth-settings_{context}"] +.Custom Resource `auth` configuration settings related to authentication used by {prod-short}. + +[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`. +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. +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. +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`. +:=== + +[id="checluster-custom-resource-storage-settings_{context}"] +.`CheCluster` Custom Resource `storage` configuration settings related to persistent storage used by {prod-short}. + +[cols="2,5", options="header"] +:=== + Property: Description +postgresPVCStorageClassName: Storage class for the Persistent Volume Claim dedicated to the PostgreSQL database. When omitted or left blank, a default storage class is used. +preCreateSubPaths: Instructs the Che server to start a special Pod to pre-create a sub-path in the Persistent Volumes. Defaults to `false`, however it will need to enable it according to the configuration of your Kubernetes cluster. +pvcClaimSize: Size of the persistent volume claim for workspaces. Defaults to `10Gi`. +pvcJobsImage: Overrides the container image used to create sub-paths in the Persistent Volumes. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. See also the `preCreateSubPaths` field. +pvcStrategy: Persistent volume claim strategy for the Che server. This Can be\:`common` (all workspaces PVCs in one volume), `per-workspace` (one PVC per workspace for all declared volumes) and `unique` (one PVC per declared volume). Defaults to `common`. +workspacePVCStorageClassName: Storage class for the Persistent Volume Claims dedicated to the Che workspaces. When omitted or left blank, a default storage class is used. +:=== + +[id="checluster-custom-resource-k8s-settings_{context}"] +.`CheCluster` Custom Resource `k8s` configuration settings specific to {prod-short} installations on {platforms-name}. + +[cols="2,5", options="header"] +:=== + 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. +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`. +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. +:=== + +[id="checluster-custom-resource-metrics-settings_{context}"] +.`CheCluster` Custom Resource `metrics` settings, related to the {prod-short} metrics collection used by {prod-short}. + +[cols="2,5", options="header"] +:=== + Property: Description +enable: Enables `metrics` the Che server endpoint. Default to `true`. +:=== + +[id="checluster-custom-resource-status-settings_{context}"] +.`CheCluster` Custom Resource `status` defines the observed state of {prod-short} installation + +[cols="2,5", options="header"] +:=== + Property: Description +cheClusterRunning: Status of a Che installation. Can be `Available`, `Unavailable`, or `Available, Rolling Update in Progress`. +cheURL: Public URL to the Che server. +cheVersion: Current installed Che version. +dbProvisioned: Indicates that a PostgreSQL instance has been correctly provisioned or not. +devfileRegistryURL: Public URL to the devfile registry. +devworkspaceStatus: The status of the Devworkspace subsystem +gitHubOAuthProvisioned: Indicates whether an Identity Provider instance, Keycloak or RH-SSO, has been configured to integrate with the GitHub OAuth. +helpLink: A URL that points to some URL where to find help related to the current Operator status. +keycloakProvisioned: Indicates whether an Identity Provider instance, Keycloak or RH-SSO, has been provisioned with realm, client and user. +keycloakURL: Public URL to the Identity Provider server, Keycloak or RH-SSO,. +message: A human readable message indicating details about why the Pod is in this condition. +openShiftOAuthUserCredentialsSecret: OpenShift OAuth secret in `openshift-config` namespace that contains user credentials for HTPasswd identity provider. +openShiftoAuthProvisioned: Indicates whether an Identity Provider instance, Keycloak or RH-SSO, has been configured to integrate with the OpenShift OAuth. +pluginRegistryURL: Public URL to the plugin registry. +reason: A brief CamelCase message indicating details about why the Pod is in this state. +:=== + + diff --git a/modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc b/modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc index 8d9095cc99..1a260bb959 100644 --- a/modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc +++ b/modules/installation-guide/examples/proc_che-configuring-che-to-run-in-a-restricted-environment.adoc @@ -21,10 +21,10 @@ This procedure uses the following placeholders: | organization of the container-image registry | `` -| offline plug-in registry, see xref:building-offline-plugin-registry-image_{context}[] +| offline plug-in registry, see xref:building-an-offline-plug-in-registry-image_{context}[] | `` -| offline devfile registry, see xref:building-offline-devfile-registry-image_{context}[] +| offline devfile registry, see xref:building-an-offline-devfile-registry-image_{context}[] | `` | release of {prod-short} that is being deployed @@ -34,12 +34,12 @@ The `CheCluster` Custom Resource, which is managed by the {prod-short} Operator, [source,yaml,subs="+quotes"] ---- -# [...] +# ... spec: server: airGapContainerRegistryHostname: '____' airGapContainerRegistryOrganization: '____' -# [...] +# ... ---- Setting these values uses `` and `` for all images. This means that the Operator expects the offline plug-in and devfile registries to be available at: diff --git a/modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc b/modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc index fe27075a3f..539990790a 100644 --- a/modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc +++ b/modules/installation-guide/examples/proc_che-preparing-a-private-registry.adoc @@ -20,17 +20,17 @@ 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.adoc#che-workspace-jwt-proxy_{context}[Che workspace JWT proxy]. +| 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]. | `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.adoc#che-plug-in-broker_{context}[Che plug-ins 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]. | `quay.io/eclipse/che-plugin-registry` -| Plug-in registry that store information about plugins and the runtime containers they require. See xref:building-offline-plugin-registry-image_{context}[]. +| Plug-in registry that store information about plugins 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 store descriptions of the sample projects and how to load them as workspaces via the Getting Started tab in the dashboard. See xref:building-offline-devfile-registry-image_{context}[]. +| 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}[]. |=== .Workspace-specific images @@ -42,7 +42,7 @@ To avoid issues when only a subset of the images described in this section is ne .Plug-in sidecar images -Many workspace plug-ins are run in sidecar containers to ensure their dependencies are available. The offline plug-in registry (see xref:building-offline-plugin-registry-image_{context}[]) includes a file with the list of all images referenced in its plug-ins. +Many workspace plug-ins are run in sidecar containers to ensure their dependencies are available. The offline plug-in registry (see xref:building-an-offline-plug-in-registry-image_{context}[]) includes a file with the list of all images referenced in its plug-ins. To get a list of images required for plug-ins, display this file: @@ -58,7 +58,7 @@ In the example above, substitute `` for the image name and Every {prod-short} workspace uses one or more _base_ images, which contain the development dependencies for projects that are being built. To use the samples, {prod-short} pull these images from the references to them in the devfile registry. This is needed because the sample devfiles included in the devfile registry apply to images suited for this purpose. -An offline devfile registry (see xref:building-offline-devfile-registry-image_{context}[]) contains a file with the list of all images referenced in its devfiles: +An offline devfile registry (see xref:building-an-offline-devfile-registry-image_{context}[]) contains a file with the list of all images referenced in its devfiles: [subs="+quotes"] ---- 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 index 6abf439d9e..60dd8de4f7 100644 --- 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 @@ -6,7 +6,7 @@ The following section provides information about the availability of {prod-short {prod} can be installed on: -* {kubernetes} infrastructures starting at version 1.9 +* {kubernetes} infrastructures starting at version {kube-ver-min} * {ocp} versions 3.11, 4.3, and 4.4 The following options are available: @@ -17,11 +17,11 @@ The following options are available: |{kubernetes} |Installation method -a|* minikube -* microk8s -* docker-desktop -* kind -|`{prod-cli}` using Helm Chart or Operator +a|* `minikube` +* `microk8s` +* `docker-desktop` +* `kind` +|`{prod-cli}` using the Operator |=== .Local installation on OpenShift @@ -39,7 +39,7 @@ a|* minikube |=== | |{kubernetes} + -1.9 or higher +{kube-ver-min} or higher |{ocp} + 3.11 |{ocp} + @@ -49,8 +49,8 @@ a|* Microsoft Azure * Amazon Web Services * Google Cloud * IBM Cloud -.^|`{prod-cli}` using Helm Chart -.^|`{prod-cli}` using Operator +.^|`{prod-cli}` using the Operator +.^|`{prod-cli}` using the Operator .^|OperatorHub |=== diff --git a/modules/installation-guide/examples/snip_che-build-a-registry.adoc b/modules/installation-guide/examples/snip_che-build-a-registry.adoc deleted file mode 100644 index c09b2f77bd..0000000000 --- a/modules/installation-guide/examples/snip_che-build-a-registry.adoc +++ /dev/null @@ -1,7 +0,0 @@ -./build.sh --organization __ \ - --registry __ \ - --tag __ \ -ifeval::["{registry-mode}" == "offline"] - --offline \ -endif::[] - --latest-only \ No newline at end of file diff --git a/modules/installation-guide/examples/snip_che-build-an-offline-devfile-registry.adoc b/modules/installation-guide/examples/snip_che-build-an-offline-devfile-registry.adoc new file mode 100644 index 0000000000..39db9692ea --- /dev/null +++ b/modules/installation-guide/examples/snip_che-build-an-offline-devfile-registry.adoc @@ -0,0 +1,7 @@ +[subs="+attributes,+quotes"] +---- +$ ./build.sh --organization __ \ + --registry __ \ + --tag __ \ + --offline +---- \ No newline at end of file diff --git a/modules/installation-guide/examples/snip_che-build-an-offline-plug-in-registry.adoc b/modules/installation-guide/examples/snip_che-build-an-offline-plug-in-registry.adoc new file mode 100644 index 0000000000..0c1ee7fc3e --- /dev/null +++ b/modules/installation-guide/examples/snip_che-build-an-offline-plug-in-registry.adoc @@ -0,0 +1,7 @@ +[subs="+attributes,+quotes"] +---- +$ ./build.sh --organization __ \ + --registry __ \ + --tag __ \ + --offline +---- diff --git a/modules/installation-guide/examples/snip_che-building-offline-registry-images.adoc b/modules/installation-guide/examples/snip_che-building-offline-registry-images.adoc deleted file mode 100644 index 174887cc8c..0000000000 --- a/modules/installation-guide/examples/snip_che-building-offline-registry-images.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="building-offline-registry-images_{context}"] -= Building offline registry images - -:registry-mode: offline -:registry-mode-name: an offline -:registry-id: devfile -:registry-name: devfile - -include::partial$proc_building-a-registry-image.adoc[leveloffset=+1] - - -:registry-id: plugin -:registry-name: plug-in - -include::partial$proc_building-a-registry-image.adoc[leveloffset=+1] - diff --git a/modules/installation-guide/examples/snip_che-clone-the-devfile-registry-repository.adoc b/modules/installation-guide/examples/snip_che-clone-the-devfile-registry-repository.adoc new file mode 100644 index 0000000000..a79db8eccf --- /dev/null +++ b/modules/installation-guide/examples/snip_che-clone-the-devfile-registry-repository.adoc @@ -0,0 +1,6 @@ +[subs="+attributes,+quotes"] +---- +$ git clone git@github.com:eclipse/che-devfile-registry.git +$ cd che-devfile-registry +$ git checkout {prod-ver}.x +---- \ No newline at end of file diff --git a/modules/installation-guide/examples/snip_che-clone-the-plug-in-registry-repository.adoc b/modules/installation-guide/examples/snip_che-clone-the-plug-in-registry-repository.adoc new file mode 100644 index 0000000000..f509612ff1 --- /dev/null +++ b/modules/installation-guide/examples/snip_che-clone-the-plug-in-registry-repository.adoc @@ -0,0 +1,6 @@ +[subs="+attributes,+quotes"] +---- +$ git clone git@github.com:eclipse/che-plugin-registry.git +$ cd che-plugin-registry +$ git checkout {prod-ver}.x +---- \ No newline at end of file diff --git a/modules/installation-guide/examples/snip_che-clone-the-registry-repository.adoc b/modules/installation-guide/examples/snip_che-clone-the-registry-repository.adoc deleted file mode 100644 index a73cf18054..0000000000 --- a/modules/installation-guide/examples/snip_che-clone-the-registry-repository.adoc +++ /dev/null @@ -1,3 +0,0 @@ -$ git clone git@github.com:eclipse/che-{registry-id}-registry.git -$ cd che-{registry-id}-registry -$ git checkout {prod-ver}.x \ No newline at end of file diff --git a/modules/installation-guide/examples/system-variables.adoc b/modules/installation-guide/examples/system-variables.adoc index 674bbf1993..b2bdca34f8 100644 --- a/modules/installation-guide/examples/system-variables.adoc +++ b/modules/installation-guide/examples/system-variables.adoc @@ -1,342 +1,1754 @@ -[id="che-server"] -= Che server - -.Che server -,=== - Environment Variable Name,Default value, Description - - `+CHE_DATABASE+`,"`+${che.home}/storage+`","Folder where {prod-short} stores internal data objects." - `+CHE_API+`,"`+http://${CHE_HOST}:${CHE_PORT}/api+`","API service. Browsers initiate REST communications to {prod-short} server with this URL." - `+CHE_API_INTERNAL+`,"`+http://${CHE_HOST}:${CHE_PORT}/api+`","API service internal network url. Back-end services should initiate REST communications to {prod-short} server with this URL" - `+CHE_WEBSOCKET_ENDPOINT+`,"`+ws://${CHE_HOST}:${CHE_PORT}/api/websocket+`","{prod-short} websocket major endpoint. Provides basic communication endpoint for major websocket interactions and messaging." - `+CHE_WORKSPACE_PROJECTS_STORAGE+`,"`+/projects+`","Your projects are synchronized from the {prod-short} server into the machine running each workspace. This is the directory in the machine where your projects are placed." - `+CHE_WORKSPACE_PROJECTS_STORAGE_DEFAULT_SIZE+`,"`+1Gi+`","Used when Kubernetes or OpenShift-type components in a devfile request project PVC creation (Applied in case of 'unique' and 'per workspace' PVC strategy. In case of the 'common' PVC strategy, it is rewritten with the value of the `che.infra.kubernetes.pvc.quantity` property.)" - `+CHE_WORKSPACE_LOGS_ROOT__DIR+`,"`+/workspace_logs+`","Defines the directory inside the machine where all the workspace logs are placed. Provide this value into the machine, for example, as an environment variable. This is to ensure that agent developers can use this directory to back up agent logs." - `+CHE_WORKSPACE_HTTP__PROXY+`,"","Configures proxies used by runtimes powering workspaces." - `+CHE_WORKSPACE_HTTPS__PROXY+`,"","Configuresproxies used by runtimes powering workspaces." - `+CHE_WORKSPACE_NO__PROXY+`,"","Configuresproxiesused by runtimes powering workspaces." - `+CHE_WORKSPACE_AUTO__START+`,"`+true+`","By default, when users access a workspace with its URL, the workspace automatically starts (if currently stopped). Set this to `false` to disable this behavior." - `+CHE_WORKSPACE_POOL_TYPE+`,"`+fixed+`","Workspace threads pool configuration. This pool is used for workspace-related operations that require asynchronous execution, for example, starting and stopping. Possible values are `fixed` and `cached`." - `+CHE_WORKSPACE_POOL_EXACT__SIZE+`,"`+30+`","This property is ignored when pool type is different from `fixed`. It configures the exact size of the pool. When set, the `multiplier` property is ignored. If this property is not set (`0`, `<0`, `NULL`), then the pool size equals the number of cores. See also `che.workspace.pool.cores_multiplier`." - `+CHE_WORKSPACE_POOL_CORES__MULTIPLIER+`,"`+2+`","This property is ignored when pool type is not set to `fixed`, `che.workspace.pool.exact_size` is set. When set, the pool size is `N_CORES * multiplier`." - `+CHE_WORKSPACE_PROBE__POOL__SIZE+`,"`+10+`","This property specifies how many threads to use for workspace server liveness probes." - `+CHE_WORKSPACE_HTTP__PROXY__JAVA__OPTIONS+`,"`+NULL+`","HTTP proxy setting for workspace JVM." - `+CHE_WORKSPACE_JAVA__OPTIONS+`,"`+-XX:MaxRAM=150m-XX:MaxRAMFraction=2 -XX:+UseParallelGC -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xms20m -Djava.security.egd=file:/dev/./urandom+`","Java command-line options added to JVMs running in workspaces." - `+CHE_WORKSPACE_MAVEN__OPTIONS+`,"`+-XX:MaxRAM=150m-XX:MaxRAMFraction=2 -XX:+UseParallelGC -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xms20m -Djava.security.egd=file:/dev/./urandom+`","Maven command-line options added to JVMs running agents in workspaces." - `+CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB+`,"`+1024+`","RAM limit default for each machine that has no RAM settings in its environment. Value less or equal to 0 is interpreted as disabling the limit." - `+CHE_WORKSPACE_DEFAULT__MEMORY__REQUEST__MB+`,"`+200+`","RAM request for each container that has no explicit RAM settings in its environment. This amount is allocated when the workspace container is created. This property may not be supported by all infrastructure implementations. Currently it is supported by Kubernetes and OpenShift. A memory request exceeding the memory limit is ignored, and only the limit size is used. Value less or equal to 0 is interpreted as disabling the limit." - `+CHE_WORKSPACE_DEFAULT__CPU__LIMIT__CORES+`,"`+-1+`","CPU limit for each container that has no CPU settings in its environment. Specify either in floating point cores number, for example, `0.125`, or using the Kubernetes format, integer millicores, for example, `125m`. Value less or equal to 0 is interpreted as disabling the limit." - `+CHE_WORKSPACE_DEFAULT__CPU__REQUEST__CORES+`,"`+-1+`","CPU request for each container that has no CPU settings in environment. A CPU request exceeding the CPU limit is ignored, and only limit number is used. Value less or equal to 0 is interpreted as disabling the limit." - `+CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__LIMIT__MB+`,"`+128+`","RAM limit and request for each sidecar that has no RAM settings in the {prod-short} plug-in configuration. Value less or equal to 0 is interpreted as disabling the limit." - `+CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__REQUEST__MB+`,"`+64+`","RAMlimit and request for each sidecar that has no RAM settings in the {prod-short} plug-in configuration. Value less or equal to 0 is interpreted as disabling the limit." - `+CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__LIMIT__CORES+`,"`+-1+`","CPU limit and request default for each sidecar that has no CPU settings in the {prod-short} plug-in configuration. Specify either in floating point cores number, for example, `0.125`, or using the Kubernetes format, integer millicores, for example, `125m`. Value less or equal to 0 is interpreted as disabling the limit." - `+CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__REQUEST__CORES+`,"`+-1+`","CPUlimit and request default for each sidecar that has no CPU settings in the {prod-short} plug-in configuration. Specify either in floating point cores number, for example, `0.125`, or using the Kubernetes format, integer millicores, for example, `125m`. Value less or equal to 0 is interpreted as disabling the limit." - `+CHE_WORKSPACE_SIDECAR_IMAGE__PULL__POLICY+`,"`+Always+`","Defines image-pulling strategy for sidecars. Possible values are: `Always`, `Never`, `IfNotPresent`. For any other value, `Always` is assumed for images with the `:latest` tag, or `IfNotPresent` for all other cases." - `+CHE_WORKSPACE_ACTIVITY__CHECK__SCHEDULER__PERIOD__S+`,"`+60+`","Period of inactive workspaces suspend job execution." - `+CHE_WORKSPACE_ACTIVITY__CLEANUP__SCHEDULER__PERIOD__S+`,"`+3600+`","The period of the cleanup of the activity table. The activity table can contain invalid or stale data if some unforeseen errors happen, like a server crash at a peculiar point in time. The default is to run the cleanup job every hour." - `+CHE_WORKSPACE_ACTIVITY__CLEANUP__SCHEDULER__INITIAL__DELAY__S+`,"`+60+`","The delay after server startup to start the first activity clean up job." - `+CHE_WORKSPACE_ACTIVITY__CHECK__SCHEDULER__DELAY__S+`,"`+180+`","Delay before first workspace idleness check job started to avoid mass suspend if ws master was unavailable for period close to inactivity timeout." - `+CHE_WORKSPACE_CLEANUP__TEMPORARY__INITIAL__DELAY__MIN+`,"`+5+`","Period of stopped temporary workspaces cleanup job execution." - `+CHE_WORKSPACE_CLEANUP__TEMPORARY__PERIOD__MIN+`,"`+180+`","Periodof stopped temporary workspaces cleanup job execution." - `+CHE_WORKSPACE_SERVER_PING__SUCCESS__THRESHOLD+`,"`+1+`","Number of sequential successful pings to server after which it is treated as available. Note: the property is common for all servers e.g. workspace agent, terminal, exec etc." - `+CHE_WORKSPACE_SERVER_PING__INTERVAL__MILLISECONDS+`,"`+3000+`","Interval, in milliseconds, between successive pings to workspace server." - `+CHE_WORKSPACE_SERVER_LIVENESS__PROBES+`,"`+wsagent/http,exec-agent/http,terminal,theia,jupyter,dirigible,cloud-shell,intellij+`","List of servers names which require liveness probes" - `+CHE_WORKSPACE_STARTUP__DEBUG__LOG__LIMIT__BYTES+`,"`+10485760+`","Limit size of the logs collected from single container that can be observed by che-server when debugging workspace startup. default 10MB=10485760" - `+CHE_WORKSPACE_STOP_ROLE_ENABLED+`,"`+true+`","If true, 'stop-workspace' role with the edit privileges will be granted to the 'che' ServiceAccount if OpenShift OAuth is enabled. This configuration is mainly required for workspace idling when the OpenShift OAuth is enabled." -,=== +pass:[] + + +[id="{prod-id-short}-server"] += {prod-short} server + + +== `+CHE_API+` + +API service. Browsers initiate REST communications to {prod-short} server with this URL. + +Default::: `+http://${CHE_HOST}:${CHE_PORT}/api+` + +''' + + +== `+CHE_API_INTERNAL+` + +API service internal network URL. Back-end services should initiate REST communications to {prod-short} server with this URL + +Default::: `+NULL+` + +''' + + +== `+CHE_WEBSOCKET_ENDPOINT+` + +{prod-short} WebSocket major endpoint. Provides basic communication endpoint for major WebSocket interactions and messaging. + +Default::: `+ws://${CHE_HOST}:${CHE_PORT}/api/websocket+` + +''' + + +== `+CHE_WEBSOCKET_INTERNAL_ENDPOINT+` + +{prod-short} WebSocket major internal endpoint. Provides basic communication endpoint for major WebSocket interactions and messaging. + +Default::: `+NULL+` + +''' + + +== `+CHE_WORKSPACE_PROJECTS_STORAGE+` + +Your projects are synchronized from the {prod-short} server into the machine running each workspace. This is the directory in the machine where your projects are placed. + +Default::: `+/projects+` + +''' + + +== `+CHE_WORKSPACE_PROJECTS_STORAGE_DEFAULT_SIZE+` + +Used when {orch-name}-type components in a devfile request project PVC creation (Applied in case of `unique` and `per workspace` PVC strategy. In case of the `common` PVC strategy, it is rewritten with the value of the `che.infra.kubernetes.pvc.quantity` property.) + +Default::: `+1Gi+` + +''' + + +== `+CHE_WORKSPACE_LOGS_ROOT__DIR+` + +Defines the directory inside the machine where all the workspace logs are placed. Provide this value into the machine, for example, as an environment variable. This is to ensure that agent developers can use this directory to back up agent logs. + +Default::: `+/workspace_logs+` + +''' + + +== `+CHE_WORKSPACE_HTTP__PROXY+` + +Configures environment variable HTTP_PROXY to a specified value in containers powering workspaces. + +Default::: empty + +''' + + +== `+CHE_WORKSPACE_HTTPS__PROXY+` + +Configures environment variable HTTPS_PROXY to a specified value in containers powering workspaces. + +Default::: empty + +''' + + +== `+CHE_WORKSPACE_NO__PROXY+` + +Configures environment variable NO_PROXY to a specified value in containers powering workspaces. + +Default::: empty + +''' + + +== `+CHE_WORKSPACE_AUTO__START+` + +By default, when users access a workspace with its URL, the workspace automatically starts (if currently stopped). Set this to `false` to disable this behavior. + +Default::: `+true+` + +''' + + +== `+CHE_WORKSPACE_POOL_TYPE+` + +Workspace threads pool configuration. This pool is used for workspace-related operations that require asynchronous execution, for example, starting and stopping. Possible values are `fixed` and `cached`. + +Default::: `+fixed+` + +''' + + +== `+CHE_WORKSPACE_POOL_EXACT__SIZE+` + +This property is ignored when pool type is different from `fixed`. It configures the exact size of the pool. When set, the `multiplier` property is ignored. If this property is not set (`0`, `<0`, `NULL`), then the pool size equals the number of cores. See also `che.workspace.pool.cores_multiplier`. + +Default::: `+30+` + +''' + + +== `+CHE_WORKSPACE_POOL_CORES__MULTIPLIER+` + +This property is ignored when pool type is not set to `fixed`, `che.workspace.pool.exact_size` is set. When set, the pool size is `N_CORES * multiplier`. + +Default::: `+2+` + +''' + + +== `+CHE_WORKSPACE_PROBE__POOL__SIZE+` + +This property specifies how many threads to use for workspace server liveness probes. + +Default::: `+10+` + +''' + + +== `+CHE_WORKSPACE_HTTP__PROXY__JAVA__OPTIONS+` + +HTTP proxy setting for workspace JVM. + +Default::: `+NULL+` + +''' + + +== `+CHE_WORKSPACE_JAVA__OPTIONS+` + +Java command-line options added to JVMs running in workspaces. + +Default::: `+-XX:MaxRAM=150m-XX:MaxRAMFraction=2 -XX:+UseParallelGC -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xms20m -Djava.security.egd=file:/dev/./urandom+` + +''' + + +== `+CHE_WORKSPACE_MAVEN__OPTIONS+` + +Maven command-line options added to JVMs running agents in workspaces. + +Default::: `+-XX:MaxRAM=150m-XX:MaxRAMFraction=2 -XX:+UseParallelGC -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xms20m -Djava.security.egd=file:/dev/./urandom+` + +''' + + +== `+CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB+` + +RAM limit default for each machine that has no RAM settings in its environment. Value less or equal to 0 is interpreted as disabling the limit. + +Default::: `+1024+` + +''' + + +== `+CHE_WORKSPACE_DEFAULT__MEMORY__REQUEST__MB+` + +RAM request for each container that has no explicit RAM settings in its environment. This amount is allocated when the workspace container is created. This property may not be supported by all infrastructure implementations. Currently it is supported by {orch-name}. A memory request exceeding the memory limit is ignored, and only the limit size is used. Value less or equal to 0 is interpreted as disabling the limit. + +Default::: `+200+` + +''' + + +== `+CHE_WORKSPACE_DEFAULT__CPU__LIMIT__CORES+` + +CPU limit for each container that has no CPU settings in its environment. Specify either in floating point cores number, for example, `0.125`, or using the Kubernetes format, integer millicores, for example, `125m`. Value less or equal to 0 is interpreted as disabling the limit. + +Default::: `+-1+` + +''' + + +== `+CHE_WORKSPACE_DEFAULT__CPU__REQUEST__CORES+` + +CPU request for each container that has no CPU settings in environment. A CPU request exceeding the CPU limit is ignored, and only limit number is used. Value less or equal to 0 is interpreted as disabling the limit. + +Default::: `+-1+` + +''' + + +== `+CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__LIMIT__MB+` + +RAM limit for each sidecar that has no RAM settings in the {prod-short} plug-in configuration. Value less or equal to 0 is interpreted as disabling the limit. + +Default::: `+128+` + +''' + + +== `+CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__REQUEST__MB+` + +RAM request for each sidecar that has no RAM settings in the {prod-short} plug-in configuration. + +Default::: `+64+` + +''' + + +== `+CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__LIMIT__CORES+` + +CPU limit default for each sidecar that has no CPU settings in the {prod-short} plug-in configuration. Specify either in floating point cores number, for example, `0.125`, or using the Kubernetes format, integer millicores, for example, `125m`. Value less or equal to 0 is interpreted as disabling the limit. + +Default::: `+-1+` + +''' + + +== `+CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__REQUEST__CORES+` + +CPU request default for each sidecar that has no CPU settings in the {prod-short} plug-in configuration. Specify either in floating point cores number, for example, `0.125`, or using the Kubernetes format, integer millicores, for example, `125m`. + +Default::: `+-1+` + +''' + + +== `+CHE_WORKSPACE_SIDECAR_IMAGE__PULL__POLICY+` + +Defines image-pulling strategy for sidecars. Possible values are: `Always`, `Never`, `IfNotPresent`. For any other value, `Always` is assumed for images with the `:latest` tag, or `IfNotPresent` for all other cases. + +Default::: `+Always+` + +''' + + +== `+CHE_WORKSPACE_ACTIVITY__CHECK__SCHEDULER__PERIOD__S+` + +Period of inactive workspaces suspend job execution. + +Default::: `+60+` + +''' + + +== `+CHE_WORKSPACE_ACTIVITY__CLEANUP__SCHEDULER__PERIOD__S+` + +The period of the cleanup of the activity table. The activity table can contain invalid or stale data if some unforeseen errors happen, as a server failure at a peculiar point in time. The default is to run the cleanup job every hour. + +Default::: `+3600+` + +''' + + +== `+CHE_WORKSPACE_ACTIVITY__CLEANUP__SCHEDULER__INITIAL__DELAY__S+` + +The delay after server startup to start the first activity clean up job. + +Default::: `+60+` + +''' + + +== `+CHE_WORKSPACE_ACTIVITY__CHECK__SCHEDULER__DELAY__S+` + +Delay before first workspace idleness check job started to avoid mass suspend if {prod-short} server was unavailable for period close to inactivity timeout. + +Default::: `+180+` + +''' + + +== `+CHE_WORKSPACE_CLEANUP__TEMPORARY__INITIAL__DELAY__MIN+` + +Time to delay the first execution of temporary workspaces cleanup job. + +Default::: `+5+` + +''' + + +== `+CHE_WORKSPACE_CLEANUP__TEMPORARY__PERIOD__MIN+` + +Time to delay between the termination of one execution and the commencement of the next execution of temporary workspaces cleanup job + +Default::: `+180+` + +''' + + +== `+CHE_WORKSPACE_SERVER_PING__SUCCESS__THRESHOLD+` + +Number of sequential successful pings to server after which it is treated as available. the {prod-short} Operator: the property is common for all servers, for example, workspace agent, terminal, exec. + +Default::: `+1+` + +''' + + +== `+CHE_WORKSPACE_SERVER_PING__INTERVAL__MILLISECONDS+` + +Interval, in milliseconds, between successive pings to workspace server. + +Default::: `+3000+` + +''' + + +== `+CHE_WORKSPACE_SERVER_LIVENESS__PROBES+` + +List of servers names which require liveness probes + +Default::: `+wsagent/http,exec-agent/http,terminal,theia,jupyter,dirigible,cloud-shell,intellij+` + +''' + + +== `+CHE_WORKSPACE_STARTUP__DEBUG__LOG__LIMIT__BYTES+` + +Limit size of the logs collected from single container that can be observed by che-server when debugging workspace startup. default 10MB=10485760 + +Default::: `+10485760+` + +''' + + +== `+CHE_WORKSPACE_STOP_ROLE_ENABLED+` + +If true, 'stop-workspace' role with the edit privileges will be granted to the 'che' ServiceAccount if OpenShift OAuth is enabled. This configuration is mainly required for workspace idling when the OpenShift OAuth is enabled. + +Default::: `+true+` + +''' + + +== `+CHE_DEVWORKSPACES_ENABLED+` + +Specifies whether {prod-short} is deployed with DevWorkspaces enabled. This property is set by the {prod-short} Operator if it also installed the support for DevWorkspaces. This property is used to advertise this fact to the {prod-short} dashboard. It does not make sense to change the value of this property manually. + +Default::: `+false+` + +''' + [id="authentication-parameters"] = Authentication parameters -.Authentication parameters -,=== - Environment Variable Name,Default value, Description - - `+CHE_AUTH_USER__SELF__CREATION+`,"`+false+`","{prod-short} has a single identity implementation, so this does not change the user experience. If true, enables user creation at API level" - `+CHE_AUTH_ACCESS__DENIED__ERROR__PAGE+`,"`+/error-oauth+`","Authentication error page address" - `+CHE_AUTH_RESERVED__USER__NAMES+`,"","Reserved user names" - `+CHE_OAUTH_GITHUB_CLIENTID+`,"`+NULL+`","You can setup GitHub OAuth to automate authentication to remote repositories. You need to first register this application with GitHub OAuth." - `+CHE_OAUTH_GITHUB_CLIENTSECRET+`,"`+NULL+`","Youcan setup GitHub OAuth to automate authentication to remote repositories. You need to first register this application with GitHub OAuth." - `+CHE_OAUTH_GITHUB_AUTHURI+`,"`+https://github.com/login/oauth/authorize+`","Youcansetup GitHub OAuth to automate authentication to remote repositories. You need to first register this application with GitHub OAuth." - `+CHE_OAUTH_GITHUB_TOKENURI+`,"`+https://github.com/login/oauth/access_token+`","YoucansetupGitHub OAuth to automate authentication to remote repositories. You need to first register this application with GitHub OAuth." - `+CHE_OAUTH_GITHUB_REDIRECTURIS+`,"`+http://localhost:${CHE_PORT}/api/oauth/callback+`","YoucansetupGitHubOAuth to automate authentication to remote repositories. You need to first register this application with GitHub OAuth." - `+CHE_OAUTH_OPENSHIFT_CLIENTID+`,"`+NULL+`","Configuration of OpenShift OAuth client. Used to obtain OpenShift OAuth token." - `+CHE_OAUTH_OPENSHIFT_CLIENTSECRET+`,"`+NULL+`","Configurationof OpenShift OAuth client. Used to obtain OpenShift OAuth token." - `+CHE_OAUTH_OPENSHIFT_OAUTH__ENDPOINT+`,"`+NULL+`","ConfigurationofOpenShift OAuth client. Used to obtain OpenShift OAuth token." - `+CHE_OAUTH_OPENSHIFT_VERIFY__TOKEN__URL+`,"`+NULL+`","ConfigurationofOpenShiftOAuth client. Used to obtain OpenShift OAuth token." -,=== -[id="internal"] -= Internal +== `+CHE_AUTH_USER__SELF__CREATION+` + +{prod-short} has a single identity implementation, so this does not change the user experience. If true, enables user creation at API level + +Default::: `+false+` + +''' + + +== `+CHE_AUTH_ACCESS__DENIED__ERROR__PAGE+` + +Authentication error page address + +Default::: `+/error-oauth+` + +''' + + +== `+CHE_AUTH_RESERVED__USER__NAMES+` + +Reserved user names + +Default::: empty + +''' + + +== `+CHE_OAUTH_GITHUB_CLIENTID+` + +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. + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH_GITHUB_CLIENTSECRET+` + +GitHub OAuth client secret. + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH_GITHUB_AUTHURI+` + +GitHub OAuth authorization URI. + +Default::: `+https://github.com/login/oauth/authorize+` + +''' + + +== `+CHE_OAUTH_GITHUB_TOKENURI+` + +GitHub OAuth token URI. + +Default::: `+https://github.com/login/oauth/access_token+` + +''' + + +== `+CHE_OAUTH_GITHUB_REDIRECTURIS+` + +GitHub OAuth redirect URIs. Separate multiple values with comma, for example: URI,URI,URI + +Default::: `+http://localhost:${CHE_PORT}/api/oauth/callback+` + +''' + + +== `+CHE_OAUTH_OPENSHIFT_CLIENTID+` + +Configuration of OpenShift OAuth client. Used to obtain OpenShift OAuth token. OpenShift OAuth client ID. + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH_OPENSHIFT_CLIENTSECRET+` + +Configurationof OpenShift OAuth client. Used to obtain OpenShift OAuth token. OpenShift OAuth client ID. OpenShift OAuth client secret. + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH_OPENSHIFT_OAUTH__ENDPOINT+` + +ConfigurationofOpenShift OAuth client. Used to obtain OpenShift OAuth token. OpenShift OAuth client ID. OpenShift OAuth client secret. OpenShift OAuth endpoint. + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH_OPENSHIFT_VERIFY__TOKEN__URL+` + +ConfigurationofOpenShiftOAuth client. Used to obtain OpenShift OAuth token. OpenShift OAuth client ID. OpenShift OAuth client secret. OpenShift OAuth endpoint. OpenShift OAuth verification token URL. + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH1_BITBUCKET_CONSUMERKEYPATH+` + +Configuration of Bitbucket Server OAuth1 client. Used to obtain Personal access tokens. Location of the file with Bitbucket Server application consumer key (equivalent to a username). + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH1_BITBUCKET_PRIVATEKEYPATH+` + +Configurationof Bitbucket Server OAuth1 client. Used to obtain Personal access tokens. Location of the file with Bitbucket Server application consumer key (equivalent to a username). Location of the file with Bitbucket Server application private key + +Default::: `+NULL+` + +''' + + +== `+CHE_OAUTH1_BITBUCKET_ENDPOINT+` + +ConfigurationofBitbucket Server OAuth1 client. Used to obtain Personal access tokens. Location of the file with Bitbucket Server application consumer key (equivalent to a username). Location of the file with Bitbucket Server application private key Bitbucket Server URL. To work correctly with factories the same URL has to be part of `che.integration.bitbucket.server_endpoints` too. + +Default::: `+NULL+` + +''' + + +[id="internal"] += Internal + + +== `+SCHEDULE_CORE__POOL__SIZE+` + +{prod-short} extensions can be scheduled executions on a time basis. This configures the size of the thread pool allocated to extensions that are launched on a recurring schedule. + +Default::: `+10+` + +''' + + +== `+DB_SCHEMA_FLYWAY_BASELINE_ENABLED+` + +DB initialization and migration configuration If true, ignore scripts up to the version configured by baseline.version. + +Default::: `+true+` + +''' + + +== `+DB_SCHEMA_FLYWAY_BASELINE_VERSION+` + +Scripts with version up to this are ignored. Note that scripts with version equal to baseline version are also ignored. + +Default::: `+5.0.0.8.1+` + +''' + + +== `+DB_SCHEMA_FLYWAY_SCRIPTS_PREFIX+` + +Prefix of migration scripts. + +Default::: empty + +''' + + +== `+DB_SCHEMA_FLYWAY_SCRIPTS_SUFFIX+` + +Suffix of migration scripts. + +Default::: `+.sql+` + +''' + + +== `+DB_SCHEMA_FLYWAY_SCRIPTS_VERSION__SEPARATOR+` + +Separator of version from the other part of script name. + +Default::: `+__+` + +''' + + +== `+DB_SCHEMA_FLYWAY_SCRIPTS_LOCATIONS+` + +Locations where to search migration scripts. + +Default::: `+classpath:che-schema+` + +''' + + +[id="kubernetes-infra-parameters"] += Kubernetes Infra parameters + + +== `+CHE_INFRA_KUBERNETES_MASTER__URL+` + +Configuration of Kubernetes client master URL that Infra will use. + +Default::: empty + +''' + + +== `+CHE_INFRA_KUBERNETES_TRUST__CERTS+` + +Boolean to configure Kubernetes client to use trusted certificates. + +Default::: `+false+` + +''' + + +== `+CHE_INFRA_KUBERNETES_CLUSTER__DOMAIN+` + +Kubernetes cluster domain. If not set, svc names will not contain information about the cluster domain. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_SERVER__STRATEGY+` + +Defines the way how servers are exposed to the world in Kubernetes infra. List of strategies implemented in {prod-short}: `default-host`, `multi-host`, `single-host`. + +Default::: `+multi-host+` + +''' + + +== `+CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_EXPOSURE+` + +Defines the way in which the workspace plugins and editors are exposed in the single-host mode. Supported exposures: `native`: Exposes servers using Kubernetes Ingresses. Works only on Kubernetes. `gateway`: Exposes servers using reverse-proxy gateway. + +Default::: `+native+` + +''' + + +== `+CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE+` + +Defines the way how to expose devfile endpoints, as end-user's applications, in single-host server strategy. They can either follow the single-host strategy and be exposed on subpaths, or they can be exposed on subdomains. `multi-host`: expose on subdomains `single-host`: expose on subpaths + +Default::: `+multi-host+` + +''' + + +== `+CHE_INFRA_KUBERNETES_SINGLEHOST_GATEWAY_CONFIGMAP__LABELS+` + +Defines labels which will be set to ConfigMaps configuring single-host gateway. + +Default::: `+app=che,component=che-gateway-config+` + +''' + + +== `+CHE_INFRA_KUBERNETES_INGRESS_DOMAIN+` + +Used to generate domain for a server in a workspace in case property `che.infra.kubernetes.server_strategy` is set to `multi-host` + +Default::: empty + +''' + + +== `+CHE_INFRA_KUBERNETES_NAMESPACE_CREATION__ALLOWED+` + +Indicates whether {prod-short} server is allowed to create {orch-namespace} for user workspaces, or they're intended to be created manually by cluster administrator. This property is also used by the OpenShift infra. + +Default::: `+true+` + +''' + + +== `+CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT+` + +Defines Kubernetes default namespace in which user's workspaces are created if user does not override it. It's possible to use `` and `` placeholders (for example: `che-workspace-`). In that case, new namespace will be created for each user. Used by OpenShift infra as well to specify a Project. The `` or `` placeholder is mandatory. + +Default::: `+-che+` + +''' + + +== `+CHE_INFRA_KUBERNETES_NAMESPACE_LABEL+` + +Defines whether che-server should try to label the workspace namespaces. + +Default::: `+true+` + +''' + + +== `+CHE_INFRA_KUBERNETES_NAMESPACE_ANNOTATE+` + +Defines whether che-server should try to annotate the workspace namespaces. + +Default::: `+true+` + +''' + + +== `+CHE_INFRA_KUBERNETES_NAMESPACE_LABELS+` + +List of labels to find {orch-namespace} that are used for {prod-short} Workspaces. They are used to: - find prepared {orch-namespace} for users in combination with `che.infra.kubernetes.namespace.annotations`. - actively label {orch-namespace} with any workspace. + +Default::: `+app.kubernetes.io/part-of=che.eclipse.org,app.kubernetes.io/component=workspaces-namespace+` + +''' + + +== `+CHE_INFRA_KUBERNETES_NAMESPACE_ANNOTATIONS+` + +List of annotations to find {orch-namespace} prepared for {prod-short} users workspaces. Only {orch-namespace} matching the `che.infra.kubernetes.namespace.labels` will be matched against these annotations. {orch-namespace} that matches both `che.infra.kubernetes.namespace.labels` and `che.infra.kubernetes.namespace.annotations` will be preferentially used for User's workspaces. It's possible to use `` placeholder to specify the {orch-namespace} to concrete user. They are used to: - find prepared {orch-namespace} for users in combination with `che.infra.kubernetes.namespace.labels`. - actively annotate {orch-namespace} with any workspace. + +Default::: `+che.eclipse.org/username=+` + +''' + + +== `+CHE_INFRA_KUBERNETES_SERVICE__ACCOUNT__NAME+` + +Defines Kubernetes Service Account name which should be specified to be bound to all workspaces Pods. the {prod-short} Operator that Kubernetes Infrastructure will not create the service account and it should exist. OpenShift infrastructure will check if project is predefined(if `che.infra.openshift.project` is not empty): - if it is predefined then service account must exist there - if it is 'NULL' or empty string then infrastructure will create new OpenShift project per workspace and prepare workspace service account with needed roles there + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_WORKSPACE__SA__CLUSTER__ROLES+` + +Specifies optional, additional cluster roles to use with the workspace service account. the {prod-short} Operator that the cluster role names must already exist, and the {prod-short} service account needs to be able to create a Role Binding to associate these cluster roles with the workspace service account. The names are comma separated. This property deprecates `che.infra.kubernetes.cluster_role_name`. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_USER__CLUSTER__ROLES+` + +Cluster roles to assign to user in his namespace + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_WORKSPACE__START__TIMEOUT__MIN+` + +Defines wait time that limits the Kubernetes workspace start time. + +Default::: `+8+` + +''' + + +== `+CHE_INFRA_KUBERNETES_INGRESS__START__TIMEOUT__MIN+` + +Defines the timeout in minutes that limits the period for which Kubernetes Ingress become ready + +Default::: `+5+` + +''' + + +== `+CHE_INFRA_KUBERNETES_WORKSPACE__UNRECOVERABLE__EVENTS+` + +If during workspace startup an unrecoverable event defined in the property occurs, stop the workspace immediately rather than waiting until timeout. the {prod-short} Operator that this SHOULD NOT include a mere "Failed" reason, because that might catch events that are not unrecoverable. A failed container startup is handled explicitly by {prod-short} server. + +Default::: `+FailedMount,FailedScheduling,MountVolume.SetUpfailed,Failed to pull image,FailedCreate,ReplicaSetCreateError+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_ENABLED+` + +Defines whether use the Persistent Volume Claim for {prod-short} workspace needs, for example: backup projects, logs, or disable it. + +Default::: `+true+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_STRATEGY+` + +Defined which strategy will be used while choosing PVC for workspaces. Supported strategies: `common`: All workspaces in the same {orch-namespace} will reuse the same PVC. Name of PVC may be configured with `che.infra.kubernetes.pvc.name`. Existing PVC will be used or a new one will be created if it does not exist. `unique`: Separate PVC for each workspace's volume will be used. Name of PVC is evaluated as `'{che.infra.kubernetes.pvc.name} + '-' + \{generated_8_chars}'`. Existing PVC will be used or a new one will be created if it does not exist. `per-workspace`: Separate PVC for each workspace will be used. Name of PVC is evaluated as `'{che.infra.kubernetes.pvc.name} + '-' + \{WORKSPACE_ID}'`. Existing PVC will be used or a new one will be created if it doesn't exist. + +Default::: `+common+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_PRECREATE__SUBPATHS+` + +Defines whether to run a job that creates workspace's subpath directories in persistent volume for the `common` strategy before launching a workspace. Necessary in some versions of {orch-name} as workspace subpath volume mounts are created with root permissions, and therefore cannot be modified by workspaces running as a user (presents an error importing projects into a workspace in {prod-short}). The default is `true`, but should be set to `false` if the version of {orch-name} creates subdirectories with user permissions. See: link:https://github.com/kubernetes/kubernetes/issues/41638[subPath in volumeMount is not writable for non-root users #41638] the {prod-short} Operator that this property has effect only if the `common` PVC strategy used. + +Default::: `+true+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_NAME+` + +Defines the settings of PVC name for {prod-short} workspaces. Each PVC strategy supplies this value differently. See documentation for `che.infra.kubernetes.pvc.strategy` property + +Default::: `+claim-che-workspace+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_STORAGE__CLASS__NAME+` + +Defines the storage class of Persistent Volume Claim for the workspaces. Empty strings means "use default". + +Default::: empty + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_QUANTITY+` + +Defines the size of Persistent Volume Claim of {prod-short} workspace. See: link:https://docs.openshift.com/container-platform/4.4/storage/understanding-persistent-storage.html[Understanding persistent storage] + +Default::: `+10Gi+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_JOBS_IMAGE+` + +Pod that is launched when performing persistent volume claim maintenance jobs on OpenShift + +Default::: `+registry.access.redhat.com/ubi8-minimal:8.3-230+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_JOBS_IMAGE_PULL__POLICY+` + +Image pull policy of container that used for the maintenance jobs on {orch-name} cluster + +Default::: `+IfNotPresent+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_JOBS_MEMORYLIMIT+` + +Defines Pod memory limit for persistent volume claim maintenance jobs + +Default::: `+250Mi+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_ACCESS__MODE+` + +Defines Persistent Volume Claim access mode. the {prod-short} Operator that for common PVC strategy changing of access mode affects the number of simultaneously running workspaces. If the OpenShift instance running {prod-short} is using Persistent Volumes with RWX access mode, then a limit of running workspaces at the same time is bounded only by {prod-short} limits configuration: RAM, CPU, and so on. See: link:https://docs.openshift.com/container-platform/4.4/storage/understanding-persistent-storage.html[Understanding persistent storage] + +Default::: `+ReadWriteOnce+` + +''' + + +== `+CHE_INFRA_KUBERNETES_PVC_WAIT__BOUND+` + +Defines if {prod-short} Server should wait workspaces Persistent Volume Claims to become bound after creating. Default value is `true`. The parameter is used by all Persistent Volume Claim strategies. It should be set to `false` when `volumeBindingMode` is configured to `WaitForFirstConsumer` otherwise workspace starts will hangs up on phase of waiting PVCs. + +Default::: `+true+` + +''' + + +== `+CHE_INFRA_KUBERNETES_INGRESS_ANNOTATIONS__JSON+` + +Defines annotations for ingresses which are used for servers exposing. Value depends on the kind of ingress controller. OpenShift infrastructure ignores this property because it uses Routes rather than Ingresses. the {prod-short} Operator that for a single-host deployment strategy to work, a controller supporting URL rewriting has to be used (so that URLs can point to different servers while the servers do not need to support changing the app root). The `che.infra.kubernetes.ingress.path.rewrite_transform` property defines how the path of the ingress should be transformed to support the URL rewriting and this property defines the set of annotations on the ingress itself that instruct the chosen ingress controller to actually do the URL rewriting, potentially building on the path transformation (if required by the chosen ingress controller). For example for Nginx ingress controller 0.22.0 and later the following value is recommended: `{"ingress.kubernetes.io/rewrite-target": "/$1","ingress.kubernetes.io/ssl-redirect": "false",\ "ingress.kubernetes.io/proxy-connect-timeout": "3600","ingress.kubernetes.io/proxy-read-timeout": "3600", "nginx.org/websocket-services": ""}` and the `che.infra.kubernetes.ingress.path.rewrite_transform` should be set to `"%s(.*)"`. For nginx ingress controller older than 0.22.0, the rewrite-target should be set to merely `/` and the path transform to `%s` (see the `che.infra.kubernetes.ingress.path.rewrite_transform` property). See the Nginx ingress controller documentation for the explanation of how the ingress controller uses the regular expression available in the ingress path and how it achieves the URL rewriting. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_INGRESS_PATH__TRANSFORM+` + +Defines a recipe on how to declare the path of the ingress that should expose a server. The `%s` represents the base public URL of the server and is guaranteed to end with a forward slash. This property must be a valid input to the `String.format()` method and contain exactly one reference to `%s`. See the description of the `che.infra.kubernetes.ingress.annotations_json` property to see how these two properties interplay when specifying the ingress annotations and path. If not defined, this property defaults to `%s` (without the quotes) which means that the path is not transformed in any way for use with the ingress controller. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_INGRESS_LABELS+` + +Additional labels to add into every Ingress created by {prod-short} server to allow clear identification. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_POD_SECURITY__CONTEXT_RUN__AS__USER+` + +Defines security context for Pods that will be created by Kubernetes Infra This is ignored by OpenShift infra + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_POD_SECURITY__CONTEXT_FS__GROUP+` + +Defines security context for Pods that will be created by Kubernetes Infra. A special supplemental group that applies to all containers in a Pod. This is ignored by OpenShift infra. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_POD_TERMINATION__GRACE__PERIOD__SEC+` + +Defines grace termination period for Pods that will be created by {orch-name} infrastructures. Default value: `0`. It allows to stop Pods quickly and significantly decrease the time required for stopping a workspace. the {prod-short} Operator: if `terminationGracePeriodSeconds` have been explicitly set in {orch-name} recipe it will not be overridden. + +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. + +Default::: `+false+` + +''' + + +== `+CHE_INFRA_KUBERNETES_TLS__SECRET+` + +Name of a secret that should be used when creating workspace ingresses with TLS. This property is ignored by OpenShift infrastructure. + +Default::: empty + +''' + + +== `+CHE_INFRA_KUBERNETES_TLS__KEY+` + +Data for TLS Secret that should be used for workspaces Ingresses. `cert` and `key` should be encoded with Base64 algorithm. These properties are ignored by OpenShift infrastructure. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_TLS__CERT+` + +Certificate data for TLS Secret that should be used for workspaces Ingresses. Certificate should be encoded with Base64 algorithm. This property is ignored by OpenShift infrastructure. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_RUNTIMES__CONSISTENCY__CHECK__PERIOD__MIN+` + +Defines the period with which runtimes consistency checks will be performed. If runtime has inconsistent state then runtime will be stopped automatically. Value must be more than 0 or `-1`, where `-1` means that checks won't be performed at all. It is disabled by default because there is possible {prod-short} Server configuration when {prod-short} Server doesn't have an ability to interact with Kubernetes API when operation is not invoked by user. It DOES work on the following configurations: - workspaces objects are created in the same namespace where {prod-short} Server is located; - `cluster-admin` service account token is mounted to {prod-short} Server Pod. It DOES NOT work on the following configurations: - {prod-short} Server communicates with Kubernetes API using token from OAuth provider. + +Default::: `+-1+` + +''' + + +== `+CHE_INFRA_KUBERNETES_TRUSTED__CA_SRC__CONFIGMAP+` + +Name of the ConfigMap in {prod-short} server namespace with additional CA TLS certificates to be propagated into all user's workspaces. If the property is set on OpenShift 4 infrastructure, and `che.infra.openshift.trusted_ca.dest_configmap_labels` includes the `config.openshift.io/inject-trusted-cabundle=true` label, then cluster CA bundle will be propagated too. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_TRUSTED__CA_DEST__CONFIGMAP+` + +Name of the ConfigMap in a workspace namespace with additional CA TLS certificates. Holds the copy of `che.infra.kubernetes.trusted_ca.src_configmap` but in a workspace namespace. Content of this ConfigMap is mounted into all workspace containers including plugin brokers. Do not change the ConfigMap name unless it conflicts with the already existing ConfigMap. the {prod-short} Operator that the resulting ConfigMap name can be adjusted eventually to make it unique in {orch-namespace}. The original name would be stored in `che.original_name` label. + +Default::: `+ca-certs+` + +''' + + +== `+CHE_INFRA_KUBERNETES_TRUSTED__CA_MOUNT__PATH+` + +Configures path on workspace containers where the CA bundle should be mounted. Content of ConfigMap specified by `che.infra.kubernetes.trusted_ca.dest_configmap` is mounted. + +Default::: `+/public-certs+` + +''' + + +== `+CHE_INFRA_KUBERNETES_TRUSTED__CA_DEST__CONFIGMAP__LABELS+` + +Comma separated list of labels to add to the CA certificates ConfigMap in user workspace. See the `che.infra.kubernetes.trusted_ca.dest_configmap` property. + +Default::: empty + +''' + + +[id="openshift-infra-parameters"] += OpenShift Infra parameters + + +== `+CHE_INFRA_OPENSHIFT_TRUSTED__CA_DEST__CONFIGMAP__LABELS+` + +Comma separated list of labels to add to the CA certificates ConfigMap in user workspace. See `che.infra.kubernetes.trusted_ca.dest_configmap` property. This default value is used for automatic cluster CA bundle injection in OpenShift 4. + +Default::: `+config.openshift.io/inject-trusted-cabundle=true+` + +''' + + +== `+CHE_INFRA_OPENSHIFT_ROUTE_LABELS+` + +Additional labels to add into every Route created by {prod-short} server to allow clear identification. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_OPENSHIFT_ROUTE_HOST_DOMAIN__SUFFIX+` + +The hostname that should be used as a suffix for the workspace routes. For example: Using `domain_suffix=__<{prod-host}>__`, the route resembles: `routed3qrtk.__<{prod-host}>__`. It has to be a valid DNS name. + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_OPENSHIFT_PROJECT_INIT__WITH__SERVER__SA+` + +Initialize OpenShift project with {prod-short} server's service account if OpenShift OAuth is enabled. + +Default::: `+true+` + +''' + + +[id="experimental-properties"] += Experimental properties + + +== `+CHE_WORKSPACE_PLUGIN__BROKER_METADATA_IMAGE+` + +Docker image of {prod-short} plugin broker app that resolves workspace tools configuration and copies plugins dependencies to a workspace. The {prod-short} Operator overrides these images by default. Changing the images here will not have an effect if {prod-short} is installed using the Operator. + +Default::: `+quay.io/eclipse/che-plugin-metadata-broker:v3.4.0+` + +''' + + +== `+CHE_WORKSPACE_PLUGIN__BROKER_ARTIFACTS_IMAGE+` + +Docker image of {prod-short} plugin artifacts broker. This broker runs as an init container on the workspace Pod. Its job is to take in a list of plugin identifiers (either references to a plugin in the registry or a link to a plugin meta.yaml) and ensure that the correct .vsix and .theia extensions are downloaded into the /plugins directory, for each plugin requested for the workspace. + +Default::: `+quay.io/eclipse/che-plugin-artifacts-broker:v3.4.0+` + +''' + + +== `+CHE_WORKSPACE_PLUGIN__BROKER_DEFAULT__MERGE__PLUGINS+` + +Configures the default behavior of the plugin brokers when provisioning plugins into a workspace. If set to true, the plugin brokers will attempt to merge plugins when possible: they run in the same sidecar image and do not have conflicting settings. This value is the default setting used when the devfile does not specify the `mergePlugins` attribute. + +Default::: `+false+` + +''' + + +== `+CHE_WORKSPACE_PLUGIN__BROKER_PULL__POLICY+` + +Docker image of {prod-short} plugin broker app that resolves workspace tools configuration and copies plugins dependencies to a workspace + +Default::: `+Always+` + +''' + + +== `+CHE_WORKSPACE_PLUGIN__BROKER_WAIT__TIMEOUT__MIN+` + +Defines the timeout in minutes that limits the max period of result waiting for plugin broker. + +Default::: `+3+` + +''' + + +== `+CHE_WORKSPACE_PLUGIN__REGISTRY__URL+` + +Workspace plug-ins registry endpoint. Should be a valid HTTP URL. Example: ++http://che-plugin-registry-eclipse-che.192.168.65.2.nip.io++ In case {prod-short} plug-ins registry is not needed value 'NULL' should be used + +Default::: `+https://che-plugin-registry.prod-preview.openshift.io/v3+` + +''' + + +== `+CHE_WORKSPACE_PLUGIN__REGISTRY__INTERNAL__URL+` + +Workspace plugins registry internal endpoint. Should be a valid HTTP URL. Example: ++http://devfile-registry.che.svc.cluster.local:8080++ In case {prod-short} plug-ins registry is not needed value 'NULL' should be used + +Default::: `+NULL+` + +''' + + +== `+CHE_WORKSPACE_DEVFILE__REGISTRY__URL+` + +Devfile Registry endpoint. Should be a valid HTTP URL. Example: ++http://che-devfile-registry-eclipse-che.192.168.65.2.nip.io++ In case {prod-short} plug-ins registry is not needed value 'NULL' should be used + +Default::: `+https://che-devfile-registry.prod-preview.openshift.io/+` + +''' + + +== `+CHE_WORKSPACE_DEVFILE__REGISTRY__INTERNAL__URL+` + +Devfile Registry "internal" endpoint. Should be a valid HTTP URL. Example: ++http://plugin-registry.che.svc.cluster.local:8080++ In case {prod-short} plug-ins registry is not needed value 'NULL' should be used + +Default::: `+NULL+` + +''' + + +== `+CHE_WORKSPACE_STORAGE_AVAILABLE__TYPES+` + +The configuration property that defines available values for storage types that clients such as the Dashboard should propose to users during workspace creation and update. Available values: - `persistent`: Persistent Storage slow I/O but persistent. - `ephemeral`: Ephemeral Storage allows for faster I/O but may have limited storage and is not persistent. - `async`: Experimental feature: Asynchronous storage is combination of Ephemeral and Persistent storage. Allows for faster I/O and keep your changes, will backup on stop and restore on start workspace. Will work only if: - `che.infra.kubernetes.pvc.strategy='common'` - `che.limits.user.workspaces.run.count=1` - `che.infra.kubernetes.namespace.default` contains `` in other cases remove `async` from the list. + +Default::: `+persistent,ephemeral,async+` + +''' + + +== `+CHE_WORKSPACE_STORAGE_PREFERRED__TYPE+` + +The configuration property that defines a default value for storage type that clients such as the Dashboard should propose to users during workspace creation and update. The `async` value is an experimental feature, not recommended as default type. + +Default::: `+persistent+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER+` + +Configures in which way secure servers will be protected with authentication. Suitable values: - `default`: `jwtproxy` is configured in a pass-through mode. Servers should authenticate requests themselves. - `jwtproxy`: `jwtproxy` will authenticate requests. Servers will receive only authenticated requests. + +Default::: `+jwtproxy+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_TOKEN_ISSUER+` + +`Jwtproxy` issuer string, token lifetime, and optional auth page path to route unsigned requests to. + +Default::: `+wsmaster+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_TOKEN_TTL+` + +JWTProxy issuer token lifetime. + +Default::: `+8800h+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_AUTH_LOADER_PATH+` + +Optional authentication page path to route unsigned requests to. + +Default::: `+/_app/loader.html+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_IMAGE+` + +JWTProxy image. + +Default::: `+quay.io/eclipse/che-jwtproxy:0.10.0+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_MEMORY__REQUEST+` + +JWTProxy memory request. + +Default::: `+15mb+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_MEMORY__LIMIT+` + +JWTProxy memory limit. + +Default::: `+128mb+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_CPU__REQUEST+` + +JWTProxy CPU request. + +Default::: `+0.03+` + +''' + + +== `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_CPU__LIMIT+` + +JWTProxy CPU limit. + +Default::: `+0.5+` + +''' + + +[id="configuration-of-the-major-websocket-endpoint"] += Configuration of the major WebSocket endpoint + + +== `+CHE_CORE_JSONRPC_PROCESSOR__MAX__POOL__SIZE+` + +Maximum size of the JSON RPC processing pool in case if pool size would be exceeded message execution will be rejected + +Default::: `+50+` + +''' + + +== `+CHE_CORE_JSONRPC_PROCESSOR__CORE__POOL__SIZE+` -.Internal -,=== - Environment Variable Name,Default value, Description - - `+SCHEDULE_CORE__POOL__SIZE+`,"`+10+`","{prod-short} extensions can be scheduled executions on a time basis. This configures the size of the thread pool allocated to extensions that are launched on a recurring schedule." - `+DB_SCHEMA_FLYWAY_BASELINE_ENABLED+`,"`+true+`","DB initialization and migration configuration" - `+DB_SCHEMA_FLYWAY_BASELINE_VERSION+`,"`+5.0.0.8.1+`","DBinitialization and migration configuration" - `+DB_SCHEMA_FLYWAY_SCRIPTS_PREFIX+`,"","DBinitializationand migration configuration" - `+DB_SCHEMA_FLYWAY_SCRIPTS_SUFFIX+`,"`+.sql+`","DBinitializationandmigration configuration" - `+DB_SCHEMA_FLYWAY_SCRIPTS_VERSION__SEPARATOR+`,"`+__+`","DBinitializationandmigrationconfiguration" - `+DB_SCHEMA_FLYWAY_SCRIPTS_LOCATIONS+`,"`+classpath:che-schema+`","DBinitializationandmigrationconfiguration" -,=== +Initial JSON processing pool. Minimum number of threads that used to process major JSON RPC messages. -[id="kubernetes-infra-parameters"] -= Kubernetes Infra parameters +Default::: `+5+` -.Kubernetes Infra parameters -,=== - Environment Variable Name,Default value, Description - - `+CHE_INFRA_KUBERNETES_MASTER__URL+`,"","Configuration of Kubernetes client that Infra will use" - `+CHE_INFRA_KUBERNETES_TRUST__CERTS+`,"","Configurationof Kubernetes client that Infra will use" - `+CHE_INFRA_KUBERNETES_SERVER__STRATEGY+`,"`+multi-host+`","Defines the way how servers are exposed to the world in {orch-name} infra. List of strategies implemented in {prod-short}: default-host, multi-host, single-host" - `+CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_EXPOSURE+`,"`+native+`","Defines the way in which the workspace plugins and editors are exposed in the single-host mode. Supported exposures: - 'native': Exposes servers using {orch-name} Ingresses. Works only on Kubernetes. - 'gateway': Exposes servers using reverse-proxy gateway." - `+CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE+`,"`+multi-host+`","Defines the way how to expose devfile endpoints, thus end-user's applications, in single-host server strategy. They can either follow the single-host strategy and be exposed on subpaths, or they can be exposed on subdomains. - 'multi-host': expose on subdomains - 'single-host': expose on subpaths" - `+CHE_INFRA_KUBERNETES_SINGLEHOST_GATEWAY_CONFIGMAP__LABELS+`,"`+app=che,component=che-gateway-config+`","Defines labels which will be set to ConfigMaps configuring single-host gateway." - `+CHE_INFRA_KUBERNETES_INGRESS_DOMAIN+`,"","Used to generate domain for a server in a workspace in case property `che.infra.kubernetes.server_strategy` is set to `multi-host`" - `+CHE_INFRA_KUBERNETES_NAMESPACE+`,"","DEPRECATED - please do not change the value of this property otherwise the existing workspaces will loose data. Do not set it on new installations. Defines Kubernetes namespace in which all workspaces will be created. If not set, every workspace will be created in a new namespace, where namespace = workspace id It's possible to use and placeholders (e.g.: che-workspace-). In that case, new namespace will be created for each user. Service account with permission to create new namespace must be used. Ignored for OpenShift infra. Use `che.infra.openshift.project` instead If the namespace pointed to by this property exists, it will be used for all workspaces. If it does not exist, the namespace specified by the che.infra.kubernetes.namespace.default will be created and used." - `+CHE_INFRA_KUBERNETES_NAMESPACE_CREATION__ALLOWED+`,"`+true+`","Indicates whether {prod-short} server is allowed to create namespaces/projects for user workspaces, or they're intended to be created manually by cluster administrator. This property is also used by the OpenShift infra." - `+CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT+`,"`+-che+`","Defines Kubernetes default namespace in which user's workspaces are created if user does not override it. It's possible to use , and placeholders (e.g.: che-workspace-). In that case, new namespace will be created for each user (or workspace). Is used by OpenShift infra as well to specify Project" - `+CHE_INFRA_KUBERNETES_NAMESPACE_LABEL+`,"`+true+`","Defines whether che-server should try to label the workspace namespaces." - `+CHE_INFRA_KUBERNETES_NAMESPACE_LABELS+`,"`+app.kubernetes.io/part-of=che.eclipse.org,app.kubernetes.io/component=workspaces-namespace+`","List of labels to find Namespaces/Projects that are used for {prod-short} Workspaces. They are used to: - find prepared Namespaces/Projects for users in combination with `che.infra.kubernetes.namespace.annotations`. - actively label namespaces with any workspace." - `+CHE_INFRA_KUBERNETES_NAMESPACE_ANNOTATIONS+`,"`+che.eclipse.org/username=+`","List of annotations to find Namespaces/Projects prepared for {prod-short} users workspaces. Only Namespaces/Projects matching the `che.infra.kubernetes.namespace.labels` will be matched against these annotations. Namespaces/Projects that matches both `che.infra.kubernetes.namespace.labels` and `che.infra.kubernetes.namespace.annotations` will be preferentially used for User's workspaces. It's possible to use `` placeholder to specify the Namespace/Project to concrete user." - `+CHE_INFRA_KUBERNETES_NAMESPACE_ALLOW__USER__DEFINED+`,"`+false+`","Defines if a user is able to specify Kubernetes namespace (or OpenShift project) different from the default. It's NOT RECOMMENDED to configured true without OAuth configured. This property is also used by the OpenShift infra." - `+CHE_INFRA_KUBERNETES_SERVICE__ACCOUNT__NAME+`,"`+NULL+`","Defines Kubernetes Service Account name which should be specified to be bound to all workspaces pods. Note that Kubernetes Infrastructure won't create the service account and it should exist. OpenShift infrastructure will check if project is predefined(if `che.infra.openshift.project` is not empty): - if it is predefined then service account must exist there - if it is 'NULL' or empty string then infrastructure will create new OpenShift project per workspace and prepare workspace service account with needed roles there" - `+CHE_INFRA_KUBERNETES_WORKSPACE__SA__CLUSTER__ROLES+`,"`+NULL+`","Specifies optional, additional cluster roles to use with the workspace service account. Note that the cluster role names must already exist, and the {prod-short} service account needs to be able to create a Role Binding to associate these cluster roles with the workspace service account. The names are comma separated. This property deprecates 'che.infra.kubernetes.cluster_role_name'." - `+CHE_INFRA_KUBERNETES_WORKSPACE__START__TIMEOUT__MIN+`,"`+8+`","Defines time frame that limits the Kubernetes workspace start time" - `+CHE_INFRA_KUBERNETES_INGRESS__START__TIMEOUT__MIN+`,"`+5+`","Defines the timeout in minutes that limits the period for which Kubernetes Ingress become ready" - `+CHE_INFRA_KUBERNETES_WORKSPACE__UNRECOVERABLE__EVENTS+`,"`+FailedMount,FailedScheduling,MountVolume.SetUpfailed,Failed to pull image,FailedCreate+`","If during workspace startup an unrecoverable event defined in the property occurs, terminate workspace immediately instead of waiting until timeout Note that this SHOULD NOT include a mere 'Failed' reason, because that might catch events that are not unrecoverable. A failed container startup is handled explicitly by {prod-short} server." - `+CHE_INFRA_KUBERNETES_PVC_ENABLED+`,"`+true+`","Defines whether use the Persistent Volume Claim for che workspace needs e.g backup projects, logs etc or disable it." - `+CHE_INFRA_KUBERNETES_PVC_STRATEGY+`,"`+common+`","Defined which strategy will be used while choosing PVC for workspaces. Supported strategies: - 'common' All workspaces in the same Kubernetes Namespace will reuse the same PVC. Name of PVC may be configured with 'che.infra.kubernetes.pvc.name'. Existing PVC will be used or new one will be created if it doesn't exist. - 'unique' Separate PVC for each workspace's volume will be used. Name of PVC is evaluated as '{che.infra.kubernetes.pvc.name} + '-' + {generated_8_chars}'. Existing PVC will be used or a new one will be created if it doesn't exist. - 'per-workspace' Separate PVC for each workspace will be used. Name of PVC is evaluated as '{che.infra.kubernetes.pvc.name} + '-' + {WORKSPACE_ID}'. Existing PVC will be used or a new one will be created if it doesn't exist." - `+CHE_INFRA_KUBERNETES_PVC_PRECREATE__SUBPATHS+`,"`+true+`","Defines whether to run a job that creates workspace's subpath directories in persistent volume for the 'common' strategy before launching a workspace. Necessary in some versions of OpenShift/Kubernetes as workspace subpath volume mounts are created with root permissions, and thus cannot be modified by workspaces running as a user (presents an error importing projects into a workspace in {prod-short}). The default is 'true', but should be set to false if the version of Openshift/Kubernetes creates subdirectories with user permissions. Relevant issue: \https://github.com/kubernetes/kubernetes/issues/41638 Note that this property has effect only if the 'common' PVC strategy used." - `+CHE_INFRA_KUBERNETES_PVC_NAME+`,"`+claim-che-workspace+`","Defines the settings of PVC name for che workspaces. Each PVC strategy supplies this value differently. See doc for che.infra.kubernetes.pvc.strategy property" - `+CHE_INFRA_KUBERNETES_PVC_STORAGE__CLASS__NAME+`,"","Defines the storage class of Persistent Volume Claim for the workspaces. Empty strings means 'use default'." - `+CHE_INFRA_KUBERNETES_PVC_QUANTITY+`,"`+10Gi+`","Defines the size of Persistent Volume Claim of che workspace. Format described here: \https://docs.openshift.com/container-platform/4.4/storage/understanding-persistent-storage.html" - `+CHE_INFRA_KUBERNETES_PVC_JOBS_IMAGE+`,"`+centos:centos7+`","Pod that is launched when performing persistent volume claim maintenance jobs on OpenShift" - `+CHE_INFRA_KUBERNETES_PVC_JOBS_IMAGE_PULL__POLICY+`,"`+IfNotPresent+`","Image pull policy of container that used for the maintenance jobs on Kubernetes/OpenShift cluster" - `+CHE_INFRA_KUBERNETES_PVC_JOBS_MEMORYLIMIT+`,"`+250Mi+`","Defines pod memory limit for persistent volume claim maintenance jobs" - `+CHE_INFRA_KUBERNETES_PVC_ACCESS__MODE+`,"`+ReadWriteOnce+`","Defines Persistent Volume Claim access mode. Note that for common PVC strategy changing of access mode affects the number of simultaneously running workspaces. If OpenShift flavor where che running is using PVs with RWX access mode then a limit of running workspaces at the same time bounded only by che limits configuration like(RAM, CPU etc). Detailed information about access mode is described here: \https://docs.openshift.com/container-platform/4.4/storage/understanding-persistent-storage.html" - `+CHE_INFRA_KUBERNETES_PVC_WAIT__BOUND+`,"`+true+`","Defines whether {prod-short} Server should wait workspaces PVCs to become bound after creating. It's used by all PVC strategies. It should be set to `false` in case if `volumeBindingMode` is configured to `WaitForFirstConsumer` otherwise workspace starts will hangs up on phase of waiting PVCs. Default value is true (means that PVCs should be waited to be bound)" - `+CHE_INFRA_KUBERNETES_INSTALLER__SERVER__MIN__PORT+`,"`+10000+`","Defined range of ports for installers servers By default, installer will use own port, but if it conflicts with another installer servers then OpenShift infrastructure will reconfigure installer to use first available from this range" - `+CHE_INFRA_KUBERNETES_INSTALLER__SERVER__MAX__PORT+`,"`+20000+`","Definedrange of ports for installers servers By default, installer will use own port, but if it conflicts with another installer servers then OpenShift infrastructure will reconfigure installer to use first available from this range" - `+CHE_INFRA_KUBERNETES_INGRESS_ANNOTATIONS__JSON+`,"`+NULL+`","Defines annotations for ingresses which are used for servers exposing. Value depends on the kind of ingress controller. OpenShift infrastructure ignores this property because it uses Routes instead of ingresses. Note that for a single-host deployment strategy to work, a controller supporting URL rewriting has to be used (so that URLs can point to different servers while the servers don't need to support changing the app root). The che.infra.kubernetes.ingress.path.rewrite_transform property defines how the path of the ingress should be transformed to support the URL rewriting and this property defines the set of annotations on the ingress itself that instruct the chosen ingress controller to actually do the URL rewriting, potentially building on the path transformation (if required by the chosen ingress controller). For example for nginx ingress controller 0.22.0 and later the following value is recommended: {'ingress.kubernetes.io/rewrite-target': '/$1','ingress.kubernetes.io/ssl-redirect': 'false',\ 'ingress.kubernetes.io/proxy-connect-timeout': '3600','ingress.kubernetes.io/proxy-read-timeout': '3600'} and the che.infra.kubernetes.ingress.path.rewrite_transform should be set to '%s(.*)' For nginx ingress controller older than 0.22.0, the rewrite-target should be set to merely '/' and the path transform to '%s' (see the the che.infra.kubernetes.ingress.path.rewrite_transform property). Please consult the nginx ingress controller documentation for the explanation of how the ingress controller uses the regular expression present in the ingress path and how it achieves the URL rewriting." - `+CHE_INFRA_KUBERNETES_INGRESS_PATH__TRANSFORM+`,"`+NULL+`","Defines a 'recipe' on how to declare the path of the ingress that should expose a server. The '%s' represents the base public URL of the server and is guaranteed to end with a forward slash. This property must be a valid input to the String.format() method and contain exactly one reference to '%s'. Please see the description of the che.infra.kubernetes.ingress.annotations_json property to see how these two properties interplay when specifying the ingress annotations and path. If not defined, this property defaults to '%s' (without the quotes) which means that the path is not transformed in any way for use with the ingress controller." - `+CHE_INFRA_KUBERNETES_INGRESS_LABELS+`,"`+NULL+`","Additional labels to add into every Ingress created by {prod-short} server to allow clear identification." - `+CHE_INFRA_KUBERNETES_POD_SECURITY__CONTEXT_RUN__AS__USER+`,"`+NULL+`","Defines security context for pods that will be created by Kubernetes Infra This is ignored by OpenShift infra" - `+CHE_INFRA_KUBERNETES_POD_SECURITY__CONTEXT_FS__GROUP+`,"`+NULL+`","Definessecurity context for pods that will be created by Kubernetes Infra This is ignored by OpenShift infra" - `+CHE_INFRA_KUBERNETES_POD_TERMINATION__GRACE__PERIOD__SEC+`,"`+0+`","Defines grace termination period for pods that will be created by Kubernetes / OpenShift infrastructures Grace termination period of Kubernetes / OpenShift workspace's pods defaults '0', which allows to terminate pods almost instantly and significantly decrease the time required for stopping a workspace. Note: if `terminationGracePeriodSeconds` have been explicitly set in Kubernetes / OpenShift recipe it will not be overridden." - `+CHE_INFRA_KUBERNETES_CLIENT_HTTP_ASYNC__REQUESTS_MAX+`,"`+1000+`","Number of maximum concurrent async web requests (http requests or ongoing web socket calls) supported in the underlying shared http client of the `KubernetesClient` instances. Default values are 64, and 5 per-host, which doesn't seem correct for multi-user scenarios knowing that {prod-short} keeps a number of connections opened (e.g. for command or ws-agent logs)" - `+CHE_INFRA_KUBERNETES_CLIENT_HTTP_ASYNC__REQUESTS_MAX__PER__HOST+`,"`+1000+`","Numberof maximum concurrent async web requests (http requests or ongoing web socket calls) supported in the underlying shared http client of the `KubernetesClient` instances. Default values are 64, and 5 per-host, which doesn't seem correct for multi-user scenarios knowing that {prod-short} keeps a number of connections opened (e.g. for command or ws-agent logs)" - `+CHE_INFRA_KUBERNETES_CLIENT_HTTP_CONNECTION__POOL_MAX__IDLE+`,"`+5+`","Max number of idle connections in the connection pool of the Kubernetes-client shared http client" - `+CHE_INFRA_KUBERNETES_CLIENT_HTTP_CONNECTION__POOL_KEEP__ALIVE__MIN+`,"`+5+`","Keep-alive timeout of the connection pool of the Kubernetes-client shared http client in minutes" - `+CHE_INFRA_KUBERNETES_TLS__ENABLED+`,"`+false+`","Creates Ingresses with Transport Layer Security (TLS) enabled In OpenShift infrastructure, Routes will be TLS-enabled" - `+CHE_INFRA_KUBERNETES_TLS__SECRET+`,"","Name of a secret that should be used when creating workspace ingresses with TLS Ignored by OpenShift infrastructure" - `+CHE_INFRA_KUBERNETES_TLS__KEY+`,"`+NULL+`","Data for TLS Secret that should be used for workspaces Ingresses cert and key should be encoded with Base64 algorithm These properties are ignored by OpenShift infrastructure" - `+CHE_INFRA_KUBERNETES_TLS__CERT+`,"`+NULL+`","Datafor TLS Secret that should be used for workspaces Ingresses cert and key should be encoded with Base64 algorithm These properties are ignored by OpenShift infrastructure" - `+CHE_INFRA_KUBERNETES_RUNTIMES__CONSISTENCY__CHECK__PERIOD__MIN+`,"`+-1+`","Defines the period with which runtimes consistency checks will be performed. If runtime has inconsistent state then runtime will be stopped automatically. Value must be more than 0 or `-1`, where `-1` means that checks won't be performed at all. It is disabled by default because there is possible {prod-short} Server configuration when {prod-short} Server doesn't have an ability to interact with Kubernetes API when operation is not invoked by user. It DOES work on the following configurations: - workspaces objects are created in the same namespace where {prod-short} Server is located; - cluster-admin service account token is mount to {prod-short} Server pod; It DOES NOT work on the following configurations: - {prod-short} Server communicates with Kubernetes API using token from OAuth provider;" - `+CHE_INFRA_KUBERNETES_TRUSTED__CA_SRC__CONFIGMAP+`,"`+NULL+`","Name of cofig map in {prod-short} server namespace with additional CA TLS certificates to be propagated into all user's workspaces. If the property is set on OpenShift 4 infrastructure, and che.infra.openshift.trusted_ca.dest_configmap_labels includes config.openshift.io/inject-trusted-cabundle=true label, then cluster CA bundle will be propagated too." - `+CHE_INFRA_KUBERNETES_TRUSTED__CA_DEST__CONFIGMAP+`,"`+ca-certs+`","" - `+CHE_INFRA_KUBERNETES_TRUSTED__CA_MOUNT__PATH+`,"`+/public-certs+`","Configures path on workspace containers where the CA bundle should be mount. Content of config map specified by che.infra.kubernetes.trusted_ca.dest_configmap is mounted." - `+CHE_INFRA_KUBERNETES_TRUSTED__CA_DEST__CONFIGMAP__LABELS+`,"","Comma separated list of labels to add to the CA certificates config map in user workspace. See che.infra.kubernetes.trusted_ca.dest_configmap property." -,=== +''' -[id="openshift-infra-parameters"] -= OpenShift Infra parameters -.OpenShift Infra parameters -,=== - Environment Variable Name,Default value, Description - - `+CHE_INFRA_OPENSHIFT_PROJECT+`,"","DEPRECATED - please do not change the value of this property otherwise the existing workspaces will loose data. Do not set it on new installations. Defines OpenShift namespace in which all workspaces will be created. If not set, every workspace will be created in a new project, where project name = workspace id It's possible to use and placeholders (e.g.: che-workspace-). In that case, new project will be created for each user. OpenShift oauth or service account with permission to create new projects must be used. If the project pointed to by this property exists, it will be used for all workspaces. If it does not exist, the namespace specified by the che.infra.kubernetes.namespace.default will be created and used." - `+CHE_INFRA_OPENSHIFT_TRUSTED__CA_DEST__CONFIGMAP__LABELS+`,"`+config.openshift.io/inject-trusted-cabundle=true+`","Comma separated list of labels to add to the CA certificates config map in user workspace. See che.infra.kubernetes.trusted_ca.dest_configmap property. This default value is used for automatic cluster CA bundle injection in Openshift 4." - `+CHE_INFRA_OPENSHIFT_ROUTE_LABELS+`,"`+NULL+`","Additional labels to add into every Route created by {prod-short} server to allow clear identification." -,=== +== `+CHE_CORE_JSONRPC_PROCESSOR__QUEUE__CAPACITY+` -[id="experimental-properties"] -= Experimental properties +Configuration of queue used to process JSON RPC messages. + +Default::: `+100000+` + +''' + + +== `+CHE_METRICS_PORT+` + +Port the HTTP server endpoint that would be exposed with Prometheus metrics. + +Default::: `+8087+` + +''' -.Experimental properties -,=== - Environment Variable Name,Default value, Description - - `+CHE_WORKSPACE_PLUGIN__BROKER_METADATA_IMAGE+`,"`+quay.io/eclipse/che-plugin-metadata-broker:v3.4.0+`","Docker image of {prod-short} plugin broker app that resolves workspace tooling configuration and copies plugins dependencies to a workspace Note these images are overridden by the {prod-short} Operator by default; changing the images here will not have an effect if {prod-short} is installed via Operator." - `+CHE_WORKSPACE_PLUGIN__BROKER_ARTIFACTS_IMAGE+`,"`+quay.io/eclipse/che-plugin-artifacts-broker:v3.4.0+`","Dockerimage of {prod-short} plugin broker app that resolves workspace tooling configuration and copies plugins dependencies to a workspace Note these images are overridden by the {prod-short} Operator by default; changing the images here will not have an effect if {prod-short} is installed via Operator." - `+CHE_WORKSPACE_PLUGIN__BROKER_DEFAULT__MERGE__PLUGINS+`,"`+false+`","Configures the default behavior of the plugin brokers when provisioning plugins into a workspace. If set to true, the plugin brokers will attempt to merge plugins when possible (i.e. they run in the same sidecar image and do not have conflicting settings). This value is the default setting used when the devfile does not specify otherwise, via the 'mergePlugins' attribute." - `+CHE_WORKSPACE_PLUGIN__BROKER_PULL__POLICY+`,"`+Always+`","Docker image of {prod-short} plugin broker app that resolves workspace tooling configuration and copies plugins dependencies to a workspace" - `+CHE_WORKSPACE_PLUGIN__BROKER_WAIT__TIMEOUT__MIN+`,"`+3+`","Defines the timeout in minutes that limits the max period of result waiting for plugin broker." - `+CHE_WORKSPACE_PLUGIN__REGISTRY__URL+`,"`+https://che-plugin-registry.prod-preview.openshift.io/v3+`","Workspace tooling plugins registry endpoint. Should be a valid HTTP URL. Example: \http://che-plugin-registry-eclipse-che.192.168.65.2.nip.io In case {prod-short} plugins tooling is not needed value 'NULL' should be used" - `+CHE_WORKSPACE_PLUGIN__REGISTRY__INTERNAL__URL+`,"`+NULL+`","Workspace tooling plugins registry 'internal' endpoint. Should be a valid HTTP URL. Example: \http://devfile-registry.che.svc.cluster.local:8080 In case {prod-short} plugins tooling is not needed value 'NULL' should be used" - `+CHE_WORKSPACE_DEVFILE__REGISTRY__URL+`,"`+https://che-devfile-registry.prod-preview.openshift.io/+`","Devfile Registry endpoint. Should be a valid HTTP URL. Example: \http://che-devfile-registry-eclipse-che.192.168.65.2.nip.io In case {prod-short} plugins tooling is not needed value 'NULL' should be used" - `+CHE_WORKSPACE_DEVFILE__REGISTRY__INTERNAL__URL+`,"`+NULL+`","Devfile Registry 'internal' endpoint. Should be a valid HTTP URL. Example: \http://plugin-registry.che.svc.cluster.local:8080 In case {prod-short} plugins tooling is not needed value 'NULL' should be used" - `+CHE_WORKSPACE_STORAGE_AVAILABLE__TYPES+`,"`+persistent,ephemeral,async+`","The configuration property that defines available values for storage types that clients like Dashboard should propose for users during workspace creation/update. Available values: - 'persistent': Persistent Storage slow I/O but persistent. - 'ephemeral': Ephemeral Storage allows for faster I/O but may have limited storage and is not persistent. - 'async': Experimental feature: Asynchronous storage is combination of Ephemeral and Persistent storage. Allows for faster I/O and keep your changes, will backup on stop and restore on start workspace. Will work only if: - che.infra.kubernetes.pvc.strategy='common' - che.limits.user.workspaces.run.count=1 - che.infra.kubernetes.namespace.allow_user_defined=false - che.infra.kubernetes.namespace.default contains in other cases remove 'async' from the list." - `+CHE_WORKSPACE_STORAGE_PREFERRED__TYPE+`,"`+persistent+`","The configuration property that defines a default value for storage type that clients like Dashboard should propose for users during workspace creation/update. The 'async' value not recommended as default type since it's experimental" - `+CHE_SERVER_SECURE__EXPOSER+`,"`+jwtproxy+`","Configures in which way secure servers will be protected with authentication. Suitable values: - 'default': jwtproxy is configured in a pass-through mode. So, servers should authenticate requests themselves. - 'jwtproxy': jwtproxy will authenticate requests. So, servers will receive only authenticated ones." - `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_TOKEN_ISSUER+`,"`+wsmaster+`","Jwtproxy issuer string, token lifetime and optional auth page path to route unsigned requests to." - `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_TOKEN_TTL+`,"`+8800h+`","Jwtproxyissuer string, token lifetime and optional auth page path to route unsigned requests to." - `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_AUTH_LOADER_PATH+`,"`+/_app/loader.html+`","Jwtproxyissuerstring, token lifetime and optional auth page path to route unsigned requests to." - `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_IMAGE+`,"`+quay.io/eclipse/che-jwtproxy:0.10.0+`","Jwtproxyissuerstring,token lifetime and optional auth page path to route unsigned requests to." - `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_MEMORY__REQUEST+`,"`+15mb+`","Jwtproxyissuerstring,tokenlifetime and optional auth page path to route unsigned requests to." - `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_MEMORY__LIMIT+`,"`+128mb+`","Jwtproxyissuerstring,tokenlifetimeand optional auth page path to route unsigned requests to." - `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_CPU__REQUEST+`,"`+0.03+`","Jwtproxyissuerstring,tokenlifetimeandoptional auth page path to route unsigned requests to." - `+CHE_SERVER_SECURE__EXPOSER_JWTPROXY_CPU__LIMIT+`,"`+0.5+`","Jwtproxyissuerstring,tokenlifetimeandoptionalauth page path to route unsigned requests to." -,=== - -[id="configuration-of-major-websocket-endpoint"] -= Configuration of major "/websocket" endpoint - -.Configuration of major "/websocket" endpoint -,=== - Environment Variable Name,Default value, Description - - `+CHE_CORE_JSONRPC_PROCESSOR__MAX__POOL__SIZE+`,"`+50+`","Maximum size of the JSON RPC processing pool in case if pool size would be exceeded message execution will be rejected" - `+CHE_CORE_JSONRPC_PROCESSOR__CORE__POOL__SIZE+`,"`+5+`","Initial json processing pool. Minimum number of threads that used to process major JSON RPC messages." - `+CHE_CORE_JSONRPC_PROCESSOR__QUEUE__CAPACITY+`,"`+100000+`","Configuration of queue used to process Json RPC messages." - `+CHE_METRICS_PORT+`,"`+8087+`","Port the the http server endpoint that would be exposed with Prometheus metrics" -,=== [id="cors-settings"] = CORS settings -.CORS settings -,=== - Environment Variable Name,Default value, Description - - `+CHE_CORS_ALLOWED__ORIGINS+`,"`+*+`","CORS filter on WS Master is turned off by default. Use environment variable 'CHE_CORS_ENABLED=true' to turn it on 'cors.allowed.origins' indicates which request origins are allowed" - `+CHE_CORS_ALLOW__CREDENTIALS+`,"`+false+`","'cors.support.credentials' indicates if it allows processing of requests with credentials (in cookies, headers, TLS client certificates)" -,=== + +== `+CHE_CORS_ALLOWED__ORIGINS+` + +Indicates which request origins are allowed. CORS filter on WS Master is turned off by default. Use environment variable "CHE_CORS_ENABLED=true" to turn it on. + +Default::: `+*+` + +''' + + +== `+CHE_CORS_ALLOW__CREDENTIALS+` + +Indicates if it allows processing of requests with credentials (in cookies, headers, TLS client certificates). + +Default::: `+false+` + +''' + [id="factory-defaults"] = Factory defaults -.Factory defaults -,=== - Environment Variable Name,Default value, Description - - `+CHE_FACTORY_DEFAULT__EDITOR+`,"`+eclipse/che-theia/latest+`","Editor and plugin which will be used for factories which are created from remote git repository which doesn't contain any {prod-short}-specific workspace descriptor Multiple plugins must be comma-separated, for example: pluginFooPublisher/pluginFooName/pluginFooVersion,pluginBarPublisher/pluginBarName/pluginBarVersion" - `+CHE_FACTORY_DEFAULT__PLUGINS+`,"`+eclipse/che-machine-exec-plugin/latest+`","Editorand plugin which will be used for factories which are created from remote git repository which doesn't contain any {prod-short}-specific workspace descriptor Multiple plugins must be comma-separated, for example: pluginFooPublisher/pluginFooName/pluginFooVersion,pluginBarPublisher/pluginBarName/pluginBarVersion" - `+CHE_FACTORY_DEFAULT__DEVFILE__FILENAMES+`,"`+devfile.yaml,.devfile.yaml+`","Devfile filenames to look on repository-based factories (like GitHub etc). Factory will try to locate those files in the order they enumerated in the property." -,=== + +== `+CHE_FACTORY_DEFAULT__PLUGINS+` + +Editor and plugin which will be used for factories that are created from a remote Git repository which does not contain any {prod-short}-specific workspace descriptor Multiple plugins must be comma-separated, for example: `pluginFooPublisher/pluginFooName/pluginFooVersion,pluginBarPublisher/pluginBarName/pluginBarVersion` + +Default::: `+redhat/vscode-commons/latest+` + +''' + + +== `+CHE_FACTORY_DEFAULT__DEVFILE__FILENAMES+` + +Devfile filenames to look on repository-based factories (for example GitHub). Factory will try to locate those files in the order they enumerated in the property. + +Default::: `+devfile.yaml,.devfile.yaml+` + +''' + [id="devfile-defaults"] = Devfile defaults -.Devfile defaults -,=== - Environment Variable Name,Default value, Description - - `+CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR+`,"`+eclipse/che-theia/latest+`","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." - `+CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR_PLUGINS+`,"`+eclipse/che-machine-exec-plugin/latest+`","Default Plugins which should be provisioned for Default Editor. All the plugins from this list that are not explicitly mentioned in the user-defined devfile will be provisioned but only when the default editor is used or if the user-defined editor is the same as the default one (even if in different version). Format is comma-separated `pluginPublisher/pluginName/pluginVersion` values, and URLs. For example: eclipse/che-theia-exec-plugin/0.0.1,eclipse/che-theia-terminal-plugin/0.0.1,https://cdn.pluginregistry.com/vi-mode/meta.yaml If the plugin is a URL, the plugin's meta.yaml is retrieved from that URL." - `+CHE_WORKSPACE_PROVISION_SECRET_LABELS+`,"`+app.kubernetes.io/part-of=che.eclipse.org,app.kubernetes.io/component=workspace-secret+`","Defines comma-separated list of labels for selecting secrets from a user namespace, which will be mount into workspace containers as a files or env variables. Only secrets that match ALL given labels will be selected." - `+CHE_WORKSPACE_DEVFILE_ASYNC_STORAGE_PLUGIN+`,"`+eclipse/che-async-pv-plugin/latest+`","Plugin is added in case async storage feature will be enabled in workspace config and supported by environment" - `+CHE_INFRA_KUBERNETES_ASYNC_STORAGE_IMAGE+`,"`+quay.io/eclipse/che-workspace-data-sync-storage:0.0.1+`","Docker image for the {prod-short} async storage" - `+CHE_WORKSPACE_POD_NODE__SELECTOR+`,"`+NULL+`","Optionally configures node selector for workspace pod. Format is comma-separated key=value pairs, e.g: disktype=ssd,cpu=xlarge,foo=bar" - `+CHE_WORKSPACE_POD_TOLERATIONS__JSON+`,"`+NULL+`","Optionally configures tolerations for workspace pod. Format is a string representing a JSON Array of taint tolerations, or `NULL` to disable it. The objects contained in the array have to follow this link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#toleration-v1-core[spec]. Example: [{'effect':'NoExecute','key':'aNodeTaint','operator':'Equal','value':'aValue'}]" - `+CHE_INFRA_KUBERNETES_ASYNC_STORAGE_SHUTDOWN__TIMEOUT__MIN+`,"`+120+`","The timeout for the Asynchronous Storage Pod shutdown after stopping the last used workspace. Value less or equal to 0 interpreted as disabling shutdown ability." - `+CHE_INFRA_KUBERNETES_ASYNC_STORAGE_SHUTDOWN__CHECK__PERIOD__MIN+`,"`+30+`","Defines the period with which the Asynchronous Storage Pod stopping ability will be performed (once in 30 minutes by default)" - `+CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS+`,"`+NULL#+`","Bitbucket endpoints used for factory integrations. Comma separated list of bitbucket server URLs or NULL if no integration expected." -,=== + +== `+CHE_FACTORY_DEFAULT__EDITOR+` + +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+` + +''' + + +== `+CHE_FACTORY_SCM__FILE__FETCHER__LIMIT__BYTES+` + +File size limit for the URL fetcher which fetch files from the SCM repository. + +Default::: `+102400+` + +''' + + +== `+CHE_FACTORY_DEVFILE2__FILES__RESOLUTION__LIST+` + +Additional files which may be present in repository to complement devfile v2, and should be referenced as links to SCM resolver service in factory to retrieve them. + +Default::: `+.che/che-editor.yaml,.che/che-theia-plugins.yaml,.vscode/extensions.json+` + +''' + + +== `+CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR+` + +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+` + +''' + + +== `+CHE_WORKSPACE_DEVFILE_DEFAULT__EDITOR_PLUGINS+` + +Default Plug-ins which should be provisioned for Default Editor. All the plugins from this list that are not explicitly mentioned in the user-defined devfile will be provisioned but only when the default editor is used or if the user-defined editor is the same as the default one (even if in different version). Format is comma-separated `pluginPublisher/pluginName/pluginVersion` values, and URLs. For example: `eclipse/che-theia-exec-plugin/0.0.1,eclipse/che-theia-terminal-plugin/0.0.1,https://cdn.pluginregistry.com/vi-mode/meta.yaml` If the plugin is a URL, the plugin's `meta.yaml` is retrieved from that URL. + +Default::: `+NULL+` + +''' + + +== `+CHE_WORKSPACE_PROVISION_SECRET_LABELS+` + +Defines comma-separated list of labels for selecting secrets from a user namespace, which will be mount into workspace containers as a files or environment variables. Only secrets that match ALL given labels will be selected. + +Default::: `+app.kubernetes.io/part-of=che.eclipse.org,app.kubernetes.io/component=workspace-secret+` + +''' + + +== `+CHE_WORKSPACE_DEVFILE_ASYNC_STORAGE_PLUGIN+` + +Plugin is added in case asynchronous storage feature will be enabled in workspace configuration and supported by environment + +Default::: `+eclipse/che-async-pv-plugin/latest+` + +''' + + +== `+CHE_INFRA_KUBERNETES_ASYNC_STORAGE_IMAGE+` + +Docker image for the {prod-short} asynchronous storage + +Default::: `+quay.io/eclipse/che-workspace-data-sync-storage:0.0.1+` + +''' + + +== `+CHE_WORKSPACE_POD_NODE__SELECTOR+` + +Optionally configures node selector for workspace Pod. Format is comma-separated key=value pairs, for example: `disktype=ssd,cpu=xlarge,foo=bar` + +Default::: `+NULL+` + +''' + + +== `+CHE_WORKSPACE_POD_TOLERATIONS__JSON+` + +Optionally configures tolerations for workspace Pod. Format is a string representing a JSON Array of taint tolerations, or `NULL` to disable it. The objects contained in the array have to follow the link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#toleration-v1-core[toleration v1 core specifications]. Example: `[{"effect":"NoExecute","key":"aNodeTaint","operator":"Equal","value":"aValue"}]` + +Default::: `+NULL+` + +''' + + +== `+CHE_INFRA_KUBERNETES_ASYNC_STORAGE_SHUTDOWN__TIMEOUT__MIN+` + +The timeout for the Asynchronous Storage Pod shutdown after stopping the last used workspace. Value less or equal to 0 interpreted as disabling shutdown ability. + +Default::: `+120+` + +''' + + +== `+CHE_INFRA_KUBERNETES_ASYNC_STORAGE_SHUTDOWN__CHECK__PERIOD__MIN+` + +Defines the period with which the Asynchronous Storage Pod stopping ability will be performed (once in 30 minutes by default) + +Default::: `+30+` + +''' + + +== `+CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS+` + +Bitbucket endpoints used for factory integrations. Comma separated list of Bitbucket server URLs or NULL if no integration expected. + +Default::: `+NULL+` + +''' + + +== `+CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS+` + +GitLab endpoints used for factory integrations. Comma separated list of GitLab server URLs or NULL if no integration expected. + +Default::: `+NULL+` + +''' + + +== `+CHE_INTEGRATION_GITLAB_OAUTH__ENDPOINT+` + +Address of the GitLab server with configured OAuth 2 integration + +Default::: `+NULL#+` + +''' + [id="che-system"] = Che system -.Che system -,=== - Environment Variable Name,Default value, Description - - `+CHE_SYSTEM_SUPER__PRIVILEGED__MODE+`,"`+false+`","System Super Privileged Mode. Grants users with the manageSystem permission additional permissions for getByKey, getByNameSpace, stopWorkspaces, and getResourcesInformation. These are not given to admins by default and these permissions allow admins gain visibility to any workspace along with naming themselves with admin privileges to those workspaces." - `+CHE_SYSTEM_ADMIN__NAME+`,"`+admin+`","Grant system permission for 'che.admin.name' user. If the user already exists it'll happen on component startup, if not - during the first login when user is persisted in the database." -,=== + +== `+CHE_SYSTEM_SUPER__PRIVILEGED__MODE+` + +System Super Privileged Mode. Grants users with the manageSystem permission additional permissions for getByKey, getByNameSpace, stopWorkspaces, and getResourcesInformation. These are not given to admins by default and these permissions allow admins gain visibility to any workspace along with naming themselves with administrator privileges to those workspaces. + +Default::: `+false+` + +''' + + +== `+CHE_SYSTEM_ADMIN__NAME+` + +Grant system permission for `che.admin.name` user. If the user already exists it'll happen on component startup, if not - during the first login when user is persisted in the database. + +Default::: `+admin+` + +''' + [id="workspace-limits"] = Workspace limits -.Workspace limits -,=== - Environment Variable Name,Default value, Description - - `+CHE_LIMITS_WORKSPACE_ENV_RAM+`,"`+16gb+`","Workspaces are the fundamental runtime for users when doing development. You can set parameters that limit how workspaces are created and the resources that are consumed. The maximum amount of RAM that a user can allocate to a workspace when they create a new workspace. The RAM slider is adjusted to this maximum value." - `+CHE_LIMITS_WORKSPACE_IDLE_TIMEOUT+`,"`+1800000+`","The length of time that a user is idle with their workspace when the system will suspend the workspace and then stopping it. Idleness is the length of time that the user has not interacted with the workspace, meaning that one of our agents has not received interaction. Leaving a browser window open counts toward idleness." - `+CHE_LIMITS_WORKSPACE_RUN_TIMEOUT+`,"`+0+`","The length of time in milliseconds that a workspace will run, regardless of activity, before the system will suspend it. Set this property if you want to automatically stop workspaces after a period of time. The default is zero, meaning that there is no run timeout." -,=== + +== `+CHE_LIMITS_WORKSPACE_ENV_RAM+` + +Workspaces are the fundamental runtime for users when doing development. You can set parameters that limit how workspaces are created and the resources that are consumed. The maximum amount of RAM that a user can allocate to a workspace when they create a new workspace. The RAM slider is adjusted to this maximum value. + +Default::: `+16gb+` + +''' + + +== `+CHE_LIMITS_WORKSPACE_IDLE_TIMEOUT+` + +The length of time in milliseconds that a user is idle with their workspace when the system will suspend the workspace and then stopping it. Idleness is the length of time that the user has not interacted with the workspace, meaning that one of the agents has not received interaction. Leaving a browser window open counts toward idleness. + +Default::: `+1800000+` + +''' + + +== `+CHE_LIMITS_WORKSPACE_RUN_TIMEOUT+` + +The length of time in milliseconds that a workspace will run, regardless of activity, before the system will suspend it. Set this property if you want to automatically stop workspaces after a period of time. The default is zero, meaning that there is no run timeout. + +Default::: `+0+` + +''' + [id="users-workspace-limits"] = Users workspace limits -.Users workspace limits -,=== - Environment Variable Name,Default value, Description - - `+CHE_LIMITS_USER_WORKSPACES_RAM+`,"`+-1+`","The total amount of RAM that a single user is allowed to allocate to running workspaces. A user can allocate this RAM to a single workspace or spread it across multiple workspaces." - `+CHE_LIMITS_USER_WORKSPACES_COUNT+`,"`+-1+`","The maximum number of workspaces that a user is allowed to create. The user will be presented with an error message if they try to create additional workspaces. This applies to the total number of both running and stopped workspaces." - `+CHE_LIMITS_USER_WORKSPACES_RUN_COUNT+`,"`+1+`","The maximum number of running workspaces that a single user is allowed to have. If the user has reached this threshold and they try to start an additional workspace, they will be prompted with an error message. The user will need to stop a running workspace to activate another." -,=== + +== `+CHE_LIMITS_USER_WORKSPACES_RAM+` + +The total amount of RAM that a single user is allowed to allocate to running workspaces. A user can allocate this RAM to a single workspace or spread it across multiple workspaces. + +Default::: `+-1+` + +''' + + +== `+CHE_LIMITS_USER_WORKSPACES_COUNT+` + +The maximum number of workspaces that a user is allowed to create. The user will be presented with an error message if they try to create additional workspaces. This applies to the total number of both running and stopped workspaces. + +Default::: `+-1+` + +''' + + +== `+CHE_LIMITS_USER_WORKSPACES_RUN_COUNT+` + +The maximum number of running workspaces that a single user is allowed to have. If the user has reached this threshold and they try to start an additional workspace, they will be prompted with an error message. The user will need to stop a running workspace to activate another. + +Default::: `+1+` + +''' + [id="organizations-workspace-limits"] = Organizations workspace limits -.Organizations workspace limits -,=== - Environment Variable Name,Default value, Description - - `+CHE_LIMITS_ORGANIZATION_WORKSPACES_RAM+`,"`+-1+`","The total amount of RAM that a single organization (team) is allowed to allocate to running workspaces. An organization owner can allocate this RAM however they see fit across the team's workspaces." - `+CHE_LIMITS_ORGANIZATION_WORKSPACES_COUNT+`,"`+-1+`","The maximum number of workspaces that a organization is allowed to own. The organization will be presented an error message if they try to create additional workspaces. This applies to the total number of both running and stopped workspaces." - `+CHE_LIMITS_ORGANIZATION_WORKSPACES_RUN_COUNT+`,"`+-1+`","The maximum number of running workspaces that a single organization is allowed. If the organization has reached this threshold and they try to start an additional workspace, they will be prompted with an error message. The organization will need to stop a running workspace to activate another." - `+CHE_MAIL_FROM__EMAIL__ADDRESS+`,"`+che@noreply.com+`","Address that will be used as from email for email notifications" -,=== - -[id="organizations-notifications-settings"] -= Organizations notifications settings - -.Organizations notifications settings -,=== - Environment Variable Name,Default value, Description - - `+CHE_ORGANIZATION_EMAIL_MEMBER__ADDED__SUBJECT+`,"`+You'vebeen added to a Che Organization+`","Organization notifications sunjects and templates" - `+CHE_ORGANIZATION_EMAIL_MEMBER__ADDED__TEMPLATE+`,"`+st-html-templates/user_added_to_organization+`","Organizationnotifications sunjects and templates" - `+CHE_ORGANIZATION_EMAIL_MEMBER__REMOVED__SUBJECT+`,"`+You'vebeen removed from a Che Organization+`","" - `+CHE_ORGANIZATION_EMAIL_MEMBER__REMOVED__TEMPLATE+`,"`+st-html-templates/user_removed_from_organization+`","" - `+CHE_ORGANIZATION_EMAIL_ORG__REMOVED__SUBJECT+`,"`+CheOrganization deleted+`","" - `+CHE_ORGANIZATION_EMAIL_ORG__REMOVED__TEMPLATE+`,"`+st-html-templates/organization_deleted+`","" - `+CHE_ORGANIZATION_EMAIL_ORG__RENAMED__SUBJECT+`,"`+CheOrganization renamed+`","" - `+CHE_ORGANIZATION_EMAIL_ORG__RENAMED__TEMPLATE+`,"`+st-html-templates/organization_renamed+`","" -,=== + +== `+CHE_LIMITS_ORGANIZATION_WORKSPACES_RAM+` + +The total amount of RAM that a single organization (team) is allowed to allocate to running workspaces. An organization owner can allocate this RAM however they see fit across the team's workspaces. + +Default::: `+-1+` + +''' + + +== `+CHE_LIMITS_ORGANIZATION_WORKSPACES_COUNT+` + +The maximum number of workspaces that a organization is allowed to own. The organization will be presented an error message if they try to create additional workspaces. This applies to the total number of both running and stopped workspaces. + +Default::: `+-1+` + +''' + + +== `+CHE_LIMITS_ORGANIZATION_WORKSPACES_RUN_COUNT+` + +The maximum number of running workspaces that a single organization is allowed. If the organization has reached this threshold and they try to start an additional workspace, they will be prompted with an error message. The organization will need to stop a running workspace to activate another. + +Default::: `+-1+` + +''' + [id="multi-user-specific-openshift-infrastructure-configuration"] = Multi-user-specific OpenShift infrastructure configuration -.Multi-user-specific OpenShift infrastructure configuration -,=== - Environment Variable Name,Default value, Description - - `+CHE_INFRA_OPENSHIFT_OAUTH__IDENTITY__PROVIDER+`,"`+NULL+`","Alias of the Openshift identity provider registered in Keycloak, that should be used to create workspace OpenShift resources in Openshift namespaces owned by the current {prod-short} user. Should be set to NULL if `che.infra.openshift.project` is set to a non-empty value. For more information see the following documentation: \https://www.keycloak.org/docs/latest/server_admin/index.html#openshift-4" -,=== + +== `+CHE_INFRA_OPENSHIFT_OAUTH__IDENTITY__PROVIDER+` + +Alias of the OpenShift identity provider registered in Keycloak, that should be used to create workspace OpenShift resources in OpenShift namespaces owned by the current {prod-short} user. Should be set to NULL if `che.infra.openshift.project` is set to a non-empty value. See: link:https://www.keycloak.org/docs/latest/server_admin/#openshift-4[OpenShift identity provider] + +Default::: `+NULL+` + +''' + + +[id="oidc-configuration"] += OIDC configuration + + +== `+CHE_OIDC_AUTH__SERVER__URL+` + +Url to OIDC identity provider server Can be set to NULL only if `che.oidc.oidcProvider` is used + +Default::: `+http://${CHE_HOST}:5050/auth+` + +''' + + +== `+CHE_OIDC_AUTH__INTERNAL__SERVER__URL+` + +Internal network service Url to OIDC identity provider server + +Default::: `+NULL+` + +''' + + +== `+CHE_OIDC_ALLOWED__CLOCK__SKEW__SEC+` + +The number of seconds to tolerate for clock skew when verifying `exp` or `nbf` claims. + +Default::: `+3+` + +''' + + +== `+CHE_OIDC_USERNAME__CLAIM+` + +Username claim to be used as user display name when parsing JWT token if not defined the fallback value is 'preferred_username' in Keycloak installations and `name` in Dex installations. + +Default::: `+NULL+` + +''' + + +== `+CHE_OIDC_OIDC__PROVIDER+` + +Base URL of an alternate OIDC provider that provides a discovery endpoint as detailed in the following specification link:https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Obtaining OpenID Provider Configuration Information] Deprecated, use `che.oidc.auth_server_url` and `che.oidc.auth_internal_server_url` instead. + +Default::: `+NULL+` + +''' + [id="keycloak-configuration"] = Keycloak configuration -.Keycloak configuration -,=== - Environment Variable Name,Default value, Description - - `+CHE_KEYCLOAK_AUTH__SERVER__URL+`,"`+http://${CHE_HOST}:5050/auth+`","Url to keycloak identity provider server Can be set to NULL only if `che.keycloak.oidcProvider` is used" - `+CHE_KEYCLOAK_AUTH__INTERNAL__SERVER__URL+`,"`+NULL+`","Internal network service Url to keycloak identity provider server" - `+CHE_KEYCLOAK_REALM+`,"`+che+`","Keycloak realm is used to authenticate users Can be set to NULL only if `che.keycloak.oidcProvider` is used" - `+CHE_KEYCLOAK_CLIENT__ID+`,"`+che-public+`","Keycloak client id in che.keycloak.realm that is used by dashboard, ide and cli to authenticate users" - `+CHE_KEYCLOAK_OSO_ENDPOINT+`,"`+NULL+`","URL to access OSO oauth tokens" - `+CHE_KEYCLOAK_GITHUB_ENDPOINT+`,"`+NULL+`","URL to access Github oauth tokens" - `+CHE_KEYCLOAK_ALLOWED__CLOCK__SKEW__SEC+`,"`+3+`","The number of seconds to tolerate for clock skew when verifying exp or nbf claims." - `+CHE_KEYCLOAK_USE__NONCE+`,"`+true+`","Use the OIDC optional `nonce` feature to increase security." - `+CHE_KEYCLOAK_JS__ADAPTER__URL+`,"`+NULL+`","URL to the Keycloak Javascript adapter we want to use. if set to NULL, then the default used value is `$++{che.keycloak.auth_server_url}++/js/keycloak.js`, or `/api/keycloak/OIDCKeycloak.js` if an alternate `oidc_provider` is used" - `+CHE_KEYCLOAK_OIDC__PROVIDER+`,"`+NULL+`","Base URL of an alternate OIDC provider that provides a discovery endpoint as detailed in the following specification \https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig" - `+CHE_KEYCLOAK_USE__FIXED__REDIRECT__URLS+`,"`+false+`","Set to true when using an alternate OIDC provider that only supports fixed redirect Urls This property is ignored when `che.keycloak.oidc_provider` is NULL" - `+CHE_KEYCLOAK_USERNAME__CLAIM+`,"`+NULL+`","Username claim to be used as user display name when parsing JWT token if not defined the fallback value is 'preferred_username'" - `+CHE_OAUTH_SERVICE__MODE+`,"`+delegated+`","Configuration of OAuth Authentication Service that can be used in 'embedded' or 'delegated' mode. If set to 'embedded', then the service work as a wrapper to {prod-short}'s OAuthAuthenticator ( as in Single User mode). If set to 'delegated', then the service will use Keycloak IdentityProvider mechanism. Runtime Exception wii be thrown, in case if this property is not set properly." - `+CHE_KEYCLOAK_CASCADE__USER__REMOVAL__ENABLED+`,"`+false+`","Configuration for enabling removing user from Keycloak server on removing user from {prod-short} database. By default it's disabled. Can be enabled in some special cases when deleting a user in {prod-short} database should execute removing related-user from Keycloak. For correct work need to set admin username $++{che.keycloak.admin_username}++ and password $++{che.keycloak.admin_password}++." - `+CHE_KEYCLOAK_ADMIN__USERNAME+`,"`+NULL+`","Keycloak admin username. Will be used for deleting user from Keycloak on removing user from {prod-short} database. Make sense only in case $++{che.keycloak.cascade_user_removal_enabled}++ set to 'true'" - `+CHE_KEYCLOAK_ADMIN__PASSWORD+`,"`+NULL+`","Keycloak admin password. Will be used for deleting user from Keycloak on removing user from {prod-short} database. Make sense only in case $++{che.keycloak.cascade_user_removal_enabled}++ set to 'true'" - `+CHE_KEYCLOAK_USERNAME_REPLACEMENT__PATTERNS+`,"`+NULL+`","User name adjustment configuration. {prod-short} needs to use the usernames as part of K8s object names and labels and therefore has stricter requirements on their format than the identity providers usually allow (it needs them to be DNS-compliant). The adjustment is represented by comma-separated key-value pairs. These are sequentially used as arguments to the String.replaceAll function on the original username. The keys are regular expressions, values are replacement strings that replace the characters in the username that match the regular expression. The modified username will only be stored in the {prod-short} database and will not be advertised back to the identity provider. It is recommended to use DNS-compliant characters as replacement strings (values in the key-value pairs). Example: `\\=-,@=-at-` changes `\` to `-` and `@` to `-at-` so the username `org\user@com` becomes `org-user-at-com.`" -,=== + +== `+CHE_KEYCLOAK_REALM+` + +Keycloak realm is used to authenticate users Can be set to NULL only if `che.keycloak.oidcProvider` is used + +Default::: `+che+` + +''' + + +== `+CHE_KEYCLOAK_CLIENT__ID+` + +Keycloak client identifier in `che.keycloak.realm` to authenticate users in the dashboard, the IDE, and the CLI. + +Default::: `+che-public+` + +''' + + +== `+CHE_KEYCLOAK_OSO_ENDPOINT+` + +URL to access OSO OAuth tokens + +Default::: `+NULL+` + +''' + + +== `+CHE_KEYCLOAK_GITHUB_ENDPOINT+` + +URL to access Github OAuth tokens + +Default::: `+NULL+` + +''' + + +== `+CHE_KEYCLOAK_USE__NONCE+` + +Use the OIDC optional `nonce` feature to increase security. + +Default::: `+true+` + +''' + + +== `+CHE_KEYCLOAK_JS__ADAPTER__URL+` + +URL to the Keycloak Javascript adapter to use. if set to NULL, then the default used value is `$++{che.keycloak.auth_server_url}++/js/keycloak.js`, or `/api/keycloak/OIDCKeycloak.js` if an alternate `oidc_provider` is used + +Default::: `+NULL+` + +''' + + +== `+CHE_KEYCLOAK_USE__FIXED__REDIRECT__URLS+` + +Set to true when using an alternate OIDC provider that only supports fixed redirect Urls This property is ignored when `che.keycloak.oidc_provider` is NULL + +Default::: `+false+` + +''' + + +== `+CHE_OAUTH_SERVICE__MODE+` + +Configuration of OAuth Authentication Service that can be used in "embedded" or "delegated" mode. If set to "embedded", then the service work as a wrapper to {prod-short}'s OAuthAuthenticator ( as in Single User mode). If set to "delegated", then the service will use Keycloak IdentityProvider mechanism. Runtime Exception `wii` be thrown, in case if this property is not set properly. + +Default::: `+delegated+` + +''' + + +== `+CHE_KEYCLOAK_CASCADE__USER__REMOVAL__ENABLED+` + +Configuration for enabling removing user from Keycloak server on removing user from {prod-short} database. By default it's disabled. Can be enabled in some special cases when deleting a user in {prod-short} database should execute removing related-user from Keycloak. For correct work need to set administrator username $++{che.keycloak.admin_username}++ and password $++{che.keycloak.admin_password}++. + +Default::: `+false+` + +''' + + +== `+CHE_KEYCLOAK_ADMIN__USERNAME+` + +Keycloak administrator username. Will be used for deleting user from Keycloak on removing user from {prod-short} database. Make sense only in case $++{che.keycloak.cascade_user_removal_enabled}++ set to 'true' + +Default::: `+NULL+` + +''' + + +== `+CHE_KEYCLOAK_ADMIN__PASSWORD+` + +Keycloak administrator password. Will be used for deleting user from Keycloak on removing user from {prod-short} database. Make sense only in case $++{che.keycloak.cascade_user_removal_enabled}++ set to 'true' + +Default::: `+NULL+` + +''' + + +== `+CHE_KEYCLOAK_USERNAME_REPLACEMENT__PATTERNS+` + +User name adjustment configuration. {prod-short} needs to use the usernames as part of Kubernetes object names and labels and therefore has stricter requirements on their format than the identity providers usually allow (it needs them to be DNS-compliant). The adjustment is represented by comma-separated key-value pairs. These are sequentially used as arguments to the String.replaceAll function on the original username. The keys are regular expressions, values are replacement strings that replace the characters in the username that match the regular expression. The modified username will only be stored in the {prod-short} database and will not be advertised back to the identity provider. It is recommended to use DNS-compliant characters as replacement strings (values in the key-value pairs). Example: `\\=-,@=-at-` changes `\` to `-` and `@` to `-at-` so the username `org\user@com` becomes `org-user-at-com.` + +Default::: `+NULL+` + +''' diff --git a/modules/installation-guide/images/installation/specifying-upgrade-strategy.png b/modules/installation-guide/images/installation/specifying-upgrade-strategy.png new file mode 100644 index 0000000000..b058ffb552 Binary files /dev/null and b/modules/installation-guide/images/installation/specifying-upgrade-strategy.png differ diff --git a/modules/installation-guide/images/keycloak/keycloak_che_public_client.png b/modules/installation-guide/images/keycloak/keycloak_che_public_client.png deleted file mode 100644 index 4d103a6f88..0000000000 Binary files a/modules/installation-guide/images/keycloak/keycloak_che_public_client.png and /dev/null differ diff --git a/modules/installation-guide/nav.adoc b/modules/installation-guide/nav.adoc index d6e950863a..f9953304c6 100644 --- a/modules/installation-guide/nav.adoc +++ b/modules/installation-guide/nav.adoc @@ -4,6 +4,11 @@ * xref:configuring-the-che-installation.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-cli-to-configure-the-checluster-custom-resource.adoc[] + * xref:installing-che.adoc[] @@ -35,24 +40,27 @@ ** xref:configuring-namespace-strategies.adoc[] ** xref:configuring-storage-strategies.adoc[] ** xref:configuring-storage-types.adoc[] -** xref:running-more-than-one-workspace-at-a-time.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-labels-for-ingresses.adoc[] -** xref:configuring-labels-for-routes.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:switching-between-external-and-internal-communication.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[] diff --git a/modules/installation-guide/pages/configuring-communication-between-che-components.adoc b/modules/installation-guide/pages/configuring-communication-between-che-components.adoc new file mode 100644 index 0000000000..35df91d02b --- /dev/null +++ b/modules/installation-guide/pages/configuring-communication-between-che-components.adoc @@ -0,0 +1,6 @@ +[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 new file mode 100644 index 0000000000..9bff9bdf3d --- /dev/null +++ b/modules/installation-guide/pages/configuring-ingresses.adoc @@ -0,0 +1,6 @@ +[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-labels-for-ingresses.adoc b/modules/installation-guide/pages/configuring-labels-for-ingresses.adoc deleted file mode 100644 index 26339045cf..0000000000 --- a/modules/installation-guide/pages/configuring-labels-for-ingresses.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-labels-for-ingresses"] -// = Configuring Labels -:navtitle: Configuring labels for Kubernetes Ingress -:keywords: installation-guide, configuring-labels -:page-aliases: .:configuring-labels-for-ingresses - -include::partial$proc_configuring-labels-for-ingresses.adoc[] diff --git a/modules/installation-guide/pages/configuring-labels-for-routes.adoc b/modules/installation-guide/pages/configuring-labels-for-routes.adoc deleted file mode 100644 index 4e0230bc4e..0000000000 --- a/modules/installation-guide/pages/configuring-labels-for-routes.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-labels-for-routes"] -// = Configuring Labels -:navtitle: Configuring labels for OpenShift Route -:keywords: installation-guide, configuring-labels -:page-aliases: .:configuring-labels-for-routes - -include::partial$proc_configuring-labels-for-routes.adoc[] diff --git a/modules/installation-guide/pages/configuring-namespace-strategies.adoc b/modules/installation-guide/pages/configuring-namespace-strategies.adoc index 87f538a7f7..cbdf184062 100644 --- a/modules/installation-guide/pages/configuring-namespace-strategies.adoc +++ b/modules/installation-guide/pages/configuring-namespace-strategies.adoc @@ -1,7 +1,7 @@ [id="configuring-namespace-strategies"] // = Configuring namespace strategies -:navtitle: Configuring namespace strategies -:keywords: installation-guide, configuring-namespace-strategies -:page-aliases: .: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 new file mode 100644 index 0000000000..09effcbd31 --- /dev/null +++ b/modules/installation-guide/pages/configuring-routes.adoc @@ -0,0 +1,7 @@ +[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-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 new file mode 100644 index 0000000000..ba26c89b8e --- /dev/null +++ b/modules/installation-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-create.adoc @@ -0,0 +1,7 @@ +[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 new file mode 100644 index 0000000000..78540fb7c8 --- /dev/null +++ b/modules/installation-guide/pages/configuring-the-number-of-workspaces-that-a-user-can-run.adoc @@ -0,0 +1,7 @@ +[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/creating-an-instance-of-the-che-operator.adoc b/modules/installation-guide/pages/creating-an-instance-of-the-che-operator.adoc new file mode 100644 index 0000000000..66d8d835c0 --- /dev/null +++ b/modules/installation-guide/pages/creating-an-instance-of-the-che-operator.adoc @@ -0,0 +1,7 @@ +[id="creating-an-instance-of-the-{prod-id-short}-operator"] +// = Creating an instance of the Che Operator +:navtitle: Creating an instance of the Che Operator +:keywords: installation-guide, creating-an-instance-of-the-che-operator +:page-aliases: .:creating-an-instance-of-the-che-operator + +include::partial$proc_creating-an-instance-of-the-che-operator.adoc[] diff --git a/modules/installation-guide/pages/enabling-dev-workspace-operator.adoc b/modules/installation-guide/pages/enabling-dev-workspace-operator.adoc new file mode 100644 index 0000000000..7c510eb5d6 --- /dev/null +++ b/modules/installation-guide/pages/enabling-dev-workspace-operator.adoc @@ -0,0 +1,7 @@ +[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/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 index d3691601ed..325988d557 100644 --- 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 @@ -1,6 +1,6 @@ -[id="mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container"] -:navtitle: Mounting a secret as a file or an environment variable into a {prod} container -:keywords: installation-guide, mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container -:page-aliases: .:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container +[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-as-file-or-env-variable-in-container.adoc[] +include::partial$assembly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc[] diff --git a/modules/installation-guide/pages/running-more-than-one-workspace-at-a-time.adoc b/modules/installation-guide/pages/running-more-than-one-workspace-at-a-time.adoc deleted file mode 100644 index 2f0edeb0ef..0000000000 --- a/modules/installation-guide/pages/running-more-than-one-workspace-at-a-time.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="running-more-than-one-workspace-at-a-time"] -// = Running more than one workspace at a time -:navtitle: Running more than one workspace at a time -:keywords: installation-guide, running-workspaces -:page-aliases: .:running-more-than-one-workspace-at-a-time - -include::partial$proc_running-more-than-one-workspace-at-a-time.adoc[] - diff --git a/modules/installation-guide/pages/switching-between-external-and-internal-communication.adoc b/modules/installation-guide/pages/switching-between-external-and-internal-communication.adoc deleted file mode 100644 index 3949356b8f..0000000000 --- a/modules/installation-guide/pages/switching-between-external-and-internal-communication.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="switching-between-external-and-internal-communication"] -// = Configuring Labels -:navtitle: Switching between external and internal ways in inter-component communication -:keywords: installation-guide -:page-aliases: .:switching-between-external-and-internal-communication - -include::partial$proc_switching-between-external-and-internal-communication.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 new file mode 100644 index 0000000000..6ad4b3f317 --- /dev/null +++ b/modules/installation-guide/pages/upgrading-che-namespace-strategies-other-than-per-user.adoc @@ -0,0 +1,7 @@ +[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 index fbcb73849e..4e3bc6ecf8 100644 --- a/modules/installation-guide/pages/upgrading-che-using-operatorhub.adoc +++ b/modules/installation-guide/pages/upgrading-che-using-operatorhub.adoc @@ -4,4 +4,4 @@ :keywords: installation-guide, upgrading-che-using-operatorhub :page-aliases: .:upgrading-che-using-operatorhub -include::partial$proc_upgrading-che-using-operatorhub.adoc[] +include::partial$assembly_upgrading-che-using-operatorhub.adoc[] diff --git a/modules/installation-guide/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc b/modules/installation-guide/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc new file mode 100644 index 0000000000..14e20d7b9c --- /dev/null +++ b/modules/installation-guide/pages/using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc @@ -0,0 +1,8 @@ +[id="using-{prod-cli}-to-configure-the-checluster-custom-resource-during-installation"] +// = Using {prod-cli} to configure the `CheCluster` Custom Resource during installation +:navtitle: Using {prod-cli} to configure the `CheCluster` Custom Resource during installation +:keywords: installation-guide +:page-aliases: .:using-chectl-to-configure-the-checluster-custom-resource-during-installation + + +include::partial$proc_using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] diff --git a/modules/installation-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc b/modules/installation-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc new file mode 100644 index 0000000000..e9c8ad0b3e --- /dev/null +++ b/modules/installation-guide/pages/using-the-cli-to-configure-the-checluster-custom-resource.adoc @@ -0,0 +1,8 @@ +[id="using-the-cli-to-configure-the-checluster-custom-resource"] +// = Using the CLI to configure the CheCluster Custom Resource +:navtitle: Using the CLI to configure the CheCluster Custom Resource +:keywords: installation-guide +:page-aliases: .:using-the-cli-to-configure-the-checluster-custom-resource, using-cli-to-configure-the-checluster-custom-resource + + +include::partial$proc_using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/installation-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc b/modules/installation-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc new file mode 100644 index 0000000000..d7f9c3f5dd --- /dev/null +++ b/modules/installation-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc @@ -0,0 +1,8 @@ +[id="using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation"] +// = Using the OpenShift web console to configure the `CheCluster` Custom Resource during installation +:navtitle: Using the OpenShift web console to configure the `CheCluster` Custom Resource during installation +:keywords: installation-guide +:page-aliases: .:using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation + + +include::partial$proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc[] diff --git a/modules/installation-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc b/modules/installation-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc new file mode 100644 index 0000000000..84f9751c4d --- /dev/null +++ b/modules/installation-guide/pages/using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc @@ -0,0 +1,8 @@ +[id="using-the-openshift-web-console-to-configure-the-checluster-custom-resource"] +// = Using the OpenShift web console to configure the `CheCluster` Custom Resource +:navtitle: Using the OpenShift web console to configure the `CheCluster` Custom Resource +:keywords: installation-guide +:page-aliases: .:using-the-openshift-web-console-to-configure-the-checluster-custom-resource + + +include::partial$proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/installation-guide/partials/assembly_advanced-configuration.adoc b/modules/installation-guide/partials/assembly_advanced-configuration.adoc index 0a3b99c5e4..b2ba6be60c 100644 --- a/modules/installation-guide/partials/assembly_advanced-configuration.adoc +++ b/modules/installation-guide/partials/assembly_advanced-configuration.adoc @@ -8,23 +8,25 @@ :context: configuring-che -The following chapter describes configuration methods and options for {prod}, with some user stories as example. +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. -The next sections describe some specific user stories. +Specific use-cases: * xref:configuring-namespace-strategies.adoc[] -* xref:running-more-than-one-workspace-at-a-time.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-labels-for-ingresses.adoc[] +* xref:configuring-ingresses.adoc[] -* xref:configuring-labels-for-routes.adoc[] +* xref:configuring-routes.adoc[] * xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[] @@ -34,10 +36,12 @@ The next sections describe some specific user stories. * xref:importing-untrusted-tls-certificates.adoc[] -* xref:switching-between-external-and-internal-communication.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_building-offline-registry-images.adoc b/modules/installation-guide/partials/assembly_building-offline-registry-images.adoc new file mode 100644 index 0000000000..1982fee932 --- /dev/null +++ b/modules/installation-guide/partials/assembly_building-offline-registry-images.adoc @@ -0,0 +1,7 @@ +[id="building-offline-registry-images_{context}"] += Building offline registry images + +include::partial$proc_building-an-offline-devfile-registry-image.adoc[leveloffset=+1] + +include::partial$proc_building-an-offline-plug-in-registry-image.adoc[leveloffset=+1] + 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 index a4c9af70b7..e878b4a650 100644 --- 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 @@ -1,13 +1,7 @@ -ifdef::context[:parent-context-of-configuring-che-on-google-cloud-platform: {context}] +:parent-context-of-configuring-che-on-google-cloud-platform: {context} - -ifndef::context[] -[id="configuring-che-on-google-cloud-platform"] -endif::[] -ifdef::context[] [id="configuring-che-on-google-cloud-platform_{context}"] -endif::[] = Configuring Che on Google Cloud Platform :context: configuring-che-on-google-cloud-platform @@ -18,6 +12,5 @@ include::partial$proc_configuring-the-che-operator-checluster-resource-with-kube include::partial$proc_sizing-google-cloud-node-pools-for-your-eclipse-che-workspaces.adoc[leveloffset=+1] -ifdef::parent-context-of-configuring-che-on-google-cloud-platform[:context: {parent-context-of-configuring-che-on-google-cloud-platform}] -ifndef::parent-context-of-configuring-che-on-google-cloud-platform[:!context:] +:context: {parent-context-of-configuring-che-on-google-cloud-platform} diff --git a/modules/installation-guide/partials/assembly_configuring-the-che-installation.adoc b/modules/installation-guide/partials/assembly_configuring-the-che-installation.adoc index 8790021a04..f02da23209 100644 --- a/modules/installation-guide/partials/assembly_configuring-the-che-installation.adoc +++ b/modules/installation-guide/partials/assembly_configuring-the-che-installation.adoc @@ -20,6 +20,14 @@ endif::[] include::partial$con_understanding-the-checluster-custom-resource.adoc[leveloffset=+1] +include::partial$proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc[leveloffset=+1] + +include::partial$proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc[leveloffset=+1] + +include::partial$proc_using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[leveloffset=+1] + +include::partial$proc_using-the-cli-to-configure-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 index eacbcce708..994cfb5968 100644 --- a/modules/installation-guide/partials/assembly_configuring-workspace-exposure-strategies.adoc +++ b/modules/installation-guide/partials/assembly_configuring-workspace-exposure-strategies.adoc @@ -11,10 +11,6 @@ The following section describes how to configure workspace exposure strategies o include::partial$proc_configuring-workspace-exposure-strategies-using-an-operator.adoc[leveloffset=+1] -ifeval::["{project-context}" == "che"] -include::partial$proc_configuring-workspace-exposure-strategies-using-a-helm-chart.adoc[leveloffset=+1] -endif::[] - include::partial$con_workspace-exposure-strategies.adoc[leveloffset=+1] include::partial$con_security-considerations.adoc[leveloffset=+1] diff --git a/modules/installation-guide/partials/assembly_installing-che-locally.adoc b/modules/installation-guide/partials/assembly_installing-che-locally.adoc index 1b7dc86b05..426a787c6f 100644 --- a/modules/installation-guide/partials/assembly_installing-che-locally.adoc +++ b/modules/installation-guide/partials/assembly_installing-che-locally.adoc @@ -34,7 +34,7 @@ Choose one of the following procedures to start the {prod-short} Server using th .Additional resources -* xref:end-user-guide:creating-a-workspace-from-code-sample.adoc[] -* xref:end-user-guide:creating-a-workspace-by-importing-source-code-of-a-project.adoc[] +* 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-aws.adoc b/modules/installation-guide/partials/assembly_installing-che-on-aws.adoc index c7cced5fe3..ed5705e4b9 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-aws.adoc +++ b/modules/installation-guide/partials/assembly_installing-che-on-aws.adoc @@ -15,7 +15,7 @@ include::partial$proc_preparing-the-aws-system-for-installing-che.adoc[leveloffs :k8s-platform: AWS :domain: aws.my-ide.cloud -include::partial$proc_installing-che-on-kubernetes_using_chectl_and_helm.adoc[leveloffset=+1] +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-codeready-containers.adoc b/modules/installation-guide/partials/assembly_installing-che-on-codeready-containers.adoc index 2fcce3e694..535c47e0b7 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-codeready-containers.adoc +++ b/modules/installation-guide/partials/assembly_installing-che-on-codeready-containers.adoc @@ -7,13 +7,11 @@ :context: installing-{prod-id-short}-on-codeready-containers -This article explains how to create a single-node OpenShift cluster with CodeReady Containers to deploy {prod-short}. +This chapter describes the creation of a single-node OpenShift cluster for deploying a {prod-short} instance using CodeReady Containers. To install {prod-short}, use the`{prod-cli}` command-line tool or the OpenShift web console GUI. -WARNING: Remember that single-node OpenShift clusters are suited only for testing or single-user development. Do *NOT* use such clusters to run {prod-short} for organizations or developer teams. +include::partial$proc_using-chectl-to-install-che-on-codeready-containers.adoc[leveloffset=+1] -include::partial$proc_using-codeready-containers-to-set-up-openshift-4.adoc[leveloffset=+1] - -include::partial$proc_installing-che-on-codeready-containers-using-chectl.adoc[leveloffset=+1] +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] 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 index db54cc2880..e63d50b908 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-docker-desktop.adoc +++ b/modules/installation-guide/partials/assembly_installing-che-on-docker-desktop.adoc @@ -9,9 +9,9 @@ This article explains how to deploy {prod-short} on Docker Desktop. -WARNING: Remember that Docker Desktop is suited only for testing or single-user development. Do *NOT* use such clusters to run {prod-short} for organizations or developer teams. +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-helm.adoc[leveloffset=+1] +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] 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 index abe97ef58b..5a91ccb197 100644 --- 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 @@ -12,7 +12,7 @@ include::partial$assembly_preparing-google-cloud-platform-for-installing-che.ado :k8s-platform: Google Cloud Platform :domain: gcp.my-ide.cloud -include::partial$proc_installing-che-on-kubernetes_using_chectl_and_helm.adoc[leveloffset=+1] +include::partial$proc_installing-che-on-kubernetes_using_chectl.adoc[leveloffset=+1] include::partial$assembly_configuring-che-on-google-cloud-platform.adoc[leveloffset=+1] 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 index c24c6bee79..1c02f0d147 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-microsoft-azure.adoc +++ b/modules/installation-guide/partials/assembly_installing-che-on-microsoft-azure.adoc @@ -26,6 +26,6 @@ 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_and_helm.adoc[leveloffset=+1] +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-minikube.adoc b/modules/installation-guide/partials/assembly_installing-che-on-minikube.adoc index 28b755a2bd..9b45355f9a 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-minikube.adoc +++ b/modules/installation-guide/partials/assembly_installing-che-on-minikube.adoc @@ -9,7 +9,7 @@ This article explains how to create a single-node {kubernetes} cluster with Minikube to deploy {prod-short}. -WARNING: Remember that single-node {kubernetes} clusters are suited only for testing or single-user development. Do *NOT* use such clusters to run {prod-short} for organizations or developer teams. +WARNING: Remember that single-node {kubernetes} 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-minikube-to-set-up-kubernetes.adoc[leveloffset=+1] diff --git a/modules/installation-guide/partials/assembly_installing-che-on-minishift.adoc b/modules/installation-guide/partials/assembly_installing-che-on-minishift.adoc index 2a9a0dcd3c..9232d5dba1 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-minishift.adoc +++ b/modules/installation-guide/partials/assembly_installing-che-on-minishift.adoc @@ -9,7 +9,7 @@ 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 single-user development. Do *NOT* use such clusters to run {prod-short} for organizations or developer teams. +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] diff --git a/modules/installation-guide/partials/assembly_installing-che-on-openshift-4-using-operatorhub.adoc b/modules/installation-guide/partials/assembly_installing-che-on-openshift-4-using-operatorhub.adoc index 82c592e393..8d9f1742a2 100644 --- a/modules/installation-guide/partials/assembly_installing-che-on-openshift-4-using-operatorhub.adoc +++ b/modules/installation-guide/partials/assembly_installing-che-on-openshift-4-using-operatorhub.adoc @@ -19,8 +19,6 @@ Operators are a method of packaging, deploying, and managing an OpenShift applic * An administrator account on a running instance of OpenShift 4. -include::partial$proc_creating-a-project-in-openshift-web-console.adoc[leveloffset=+1] - include::partial$proc_installing-the-che-operator.adoc[leveloffset=+1] include::partial$proc_creating-an-instance-of-the-che-operator.adoc[leveloffset=+1] diff --git a/modules/installation-guide/partials/assembly_installing-che.adoc b/modules/installation-guide/partials/assembly_installing-che.adoc index c5a6787529..a241441671 100644 --- a/modules/installation-guide/partials/assembly_installing-che.adoc +++ b/modules/installation-guide/partials/assembly_installing-che.adoc @@ -10,10 +10,7 @@ This section contains instructions to install {prod}. The installation method depends on the target platform and the environment restrictions. ifeval::["{project-context}" == "che"] -{prod-short} is available in two modes: -* *Single-user*: Non-authenticated {prod-short}, lighter and suited for personal environments -* *Multi-user*: Authenticated {prod-short} suited for organizations and developer teams .Prerequisites @@ -25,9 +22,14 @@ ifeval::["{project-context}" == "che"] 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 single-user development. Do *not* use such clusters to run {prod-short} for organizations or developer teams. +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[] diff --git a/modules/installation-guide/partials/assembly_mounting-secrets-as-file-or-env-variable-in-container.adoc b/modules/installation-guide/partials/assembly_mounting-secrets-as-file-or-env-variable-in-container.adoc deleted file mode 100644 index a3011aed2e..0000000000 --- a/modules/installation-guide/partials/assembly_mounting-secrets-as-file-or-env-variable-in-container.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:parent-context-of-mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container: {context} - -[id="mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container_{context}"] -= Mounting a secret as a file or an environment variable into a {prod} container - -:context: mounting-a-secret-as-a-file-or-an-environment-variable-into-a-eclipse-che-container - -Secrets are {platforms-name} objects that store sensitive data such as user names, passwords, authentication tokens, and configurations in an encrypted form. - - -Users can mount a {platforms-name} secret that contains sensitive data in a {prod} container as: - -* a file -* an environment variable - - -The mounting process uses the standard {platforms-name} mounting mechanism, but it requires additional annotations and labeling. - -include::partial$proc_mounting-a-secret-as-a-file-into-a-container.adoc[leveloffset=+1] - -include::partial$proc_mounting-a-secret-as-an-environment-variable-into-a-container.adoc[leveloffset=+1] - -:context: {parent-context-of-mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container} - diff --git a/modules/installation-guide/partials/assembly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc b/modules/installation-guide/partials/assembly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc new file mode 100644 index 0000000000..078144c9cc --- /dev/null +++ b/modules/installation-guide/partials/assembly_mounting-secrets-or-a-configmap-as-file-or-env-variable-in-container.adoc @@ -0,0 +1,27 @@ +: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}"] += Mounting a Secret or a ConfigMap as a file or an environment variable into a {prod-short} container + +:context: mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-eclipse-che-container + +Secrets are {platforms-name} objects that store sensitive data such as: + +* usernames +* passwords +* authentication tokens + +in an encrypted form. + +Users can mount a {platforms-name} Secret that contains sensitive data or a ConfigMap that contains configuration in a {prod-short} managed containers as: + +* a file +* an environment variable + +The mounting process uses the standard {platforms-name} mounting mechanism, but it requires additional annotations and labeling. + +include::partial$proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc[leveloffset=+1] + +include::partial$proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc[leveloffset=+1] + +:context: {parent-context-of-mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container} 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 index 4733d728fa..b803c4ee4c 100644 --- 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 @@ -9,7 +9,7 @@ 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 set up the GCP environment for installing {prod}. +This section provides information about how to configure the GCP environment for installing {prod}. :context: 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 new file mode 100644 index 0000000000..aa10a58a12 --- /dev/null +++ b/modules/installation-guide/partials/assembly_upgrading-che-namespace-strategies-other-than-per-user.adoc @@ -0,0 +1,29 @@ +// 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-operatorhub.adoc b/modules/installation-guide/partials/assembly_upgrading-che-using-operatorhub.adoc new file mode 100644 index 0000000000..81063dc1f6 --- /dev/null +++ b/modules/installation-guide/partials/assembly_upgrading-che-using-operatorhub.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// upgrading-{prod-id-short} + +[id="upgrading-{prod-id-short}-using-operatorhub_{context}"] += Upgrading {prod-short} using OperatorHub + +This section describes how to upgrade from an earlier minor version using the Operator from OperatorHub in the OpenShift web console. + +OperatorHub supports `Automatic` and `Manual` upgrade strategies: +`Automatic`:: + The upgrade process starts when a new version of the Operator is published. +`Manual`:: + The update must be manually approved every time the new version of the Operator is published. + +include::partial$proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc[leveloffset=+1] + +include::partial$proc_manually-upgrading-che-in-operatorhub.adoc[leveloffset=+1] + +.Additional resources + +* link:https://docs.openshift.com/container-platform/latest/operators/admin/olm-upgrading-operators.html[Upgrading installed Operators] section in the OpenShift documentation. 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 index b6c0bf8393..3bdbab799d 100644 --- 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 @@ -18,7 +18,7 @@ This section describes how to upgrade {prod} using the CLI management tool in re include::example$con_{project-context}-understanding-network-connectivity-in-restricted-environments.adoc[leveloffset=+1] -include::example$snip_{project-context}-building-offline-registry-images.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/installation-guide/partials/assembly_using-the-chectl-management-tool.adoc b/modules/installation-guide/partials/assembly_using-the-chectl-management-tool.adoc index 20885b3c63..58d6bdaf0f 100644 --- a/modules/installation-guide/partials/assembly_using-the-chectl-management-tool.adoc +++ b/modules/installation-guide/partials/assembly_using-the-chectl-management-tool.adoc @@ -9,14 +9,17 @@ `{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. -ifeval::["{project-context}" == "che"] -You can find additional information in the link:https://github.com/che-incubator/{prod-cli}/blob/master/README.md[`{prod-cli}` README]. -endif::[] - 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 index 7b1719762b..1b647dd315 100644 --- a/modules/installation-guide/partials/con_persistent-volume-configuration.adoc +++ b/modules/installation-guide/partials/con_persistent-volume-configuration.adoc @@ -5,93 +5,121 @@ [id="storage-strategies-for-{prod-id-short}-workspaces_{context}"] = Storage strategies for {prod-id-short} workspaces -Workspace Pods use Persistent Volume Claims (PVCs), which are bound to the physical Persistent Volumes (PVs) with link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes[ReadWriteOnce access mode]. It is possible to configure how the {prod-short} server uses PVCs for workspaces. The individual methods for this configuration are called PVC strategies: +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. -include::example${project-context}-pvc-strategies.adoc[] +.Storage strategies comparison +[width="100%",cols="1,1,1,1",options="header"] +|=== +| Storage strategy name +| `common` +| `per-workspace` +| `unique` -{prod} uses the `common` PVC strategy in combination with the "one {orch-namespace} per user" {orch-namespace} strategy when all {prod-short} workspaces operate in the user's {orch-namespace}, sharing one PVC. +| PV count +| One per user +| One per workspace +| Multiple PVs per workspace -[id="the-common-pvc-strategy_{context}"] -== The `common` PVC strategy +| Default +| yes +| no +| no -All workspaces inside a {platforms-namespace} use the same Persistent Volume Claim (PVC) as the default data storage when storing data such as the following in their declared volumes: -* projects -* workspace logs -* additional Volumes defined by a use +| 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 -When the `common` PVC strategy is in use, user-defined PVCs are ignored and volumes that refer to these user-defined PVCs are replaced with a volume that refers to the common PVC. -In this strategy, all {prod-short} workspaces use the same PVC. When the user runs one workspace, it only binds to one node in the cluster at a time. +|=== -The corresponding containers volume mounts link to a common volume, and sub-paths are prefixed with `__` or `____`. For more details, see xref:how-subpaths-are-used-in-pvcs_{context}[]. +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. -The {prod-short} Volume name is identical to the name of the user-defined PVC. It means that if a machine is configured to use a {prod-short} volume with the same name as the user-defined -PVC has, they will use the same shared folder in the common PVC. -When a workspace is deleted, a corresponding subdirectory (`$\{ws-id}`) is deleted in the PV directory. +[id="the-common-storage-strategy_{context}"] +== The `common` storage strategy -.Restrictions on using the `common` PVC strategy +This is the default storage strategy. +For each user, all workspaces use the same PV for the default data storage. -When the `common` strategy is used and a workspace PVC access mode is ReadWriteOnce (RWO), only one node can simultaneously use the PVC. +When the user starts a first non-ephemeral workspace, the workspace engine creates a common PV. -If there are several nodes, you can use the `common` strategy, but: +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 `__` or `____` 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. -* The workspace PVC access mode must be reconfigured to `ReadWriteMany` (RWM), so multiple nodes can use this PVC simultaneously. +When the user deletes a workspace, the workspace engine deletes the corresponding subdirectory (`$\{ws-id}`) in the PV directory. -* Only one workspace in the same {orch-namespace} may be running. See xref:installation-guide:running-more-than-one-workspace-at-a-time.adoc[]. +When the user deletes the last workspace, the workspace engine removes the common PV. -The `common` PVC strategy is not suitable for large multi-node clusters. Therefore, it is best to use it in single-node clusters. However, in combination with the `per-workspace` {orch-namespace} strategy, the `common` PVC strategy is usable for clusters with not more than 75 nodes. The PVC used with this strategy must be large enough to accommodate all projects to prevent a situation in which one project depletes the resources of others. +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[]. -[id="the-per-workspace-pvc-strategy_{context}"] -== The `per-workspace` PVC strategy +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. -The `per-workspace` strategy is similar to the `common` PVC strategy. The only difference is that all workspace Volumes, but not all the workspaces, use the same PVC as the default data storage for: +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. -* projects -* workspace logs -* additional Volumes defined by a user +[id="the-per-workspace-storage-strategy_{context}"] +== The `per-workspace` storage strategy -With this strategy, {prod-short} keeps its workspace data in assigned PVs that are allocated by a single PVC. +Each workspace uses one dedicated PV. +All {prod-short} volumes defined within a single workspace use the same PV. -The `per-workspace` PVC strategy is the most universal strategy out of the PVC strategies available and acts as a proper option for large multi-node clusters with a higher amount of users. Using the `per-workspace` PVC strategy, users can run multiple workspaces simultaneously, results in more PVCs being created. -[id="the-unique-pvc-strategy_{context}"] -== The `unique` PVC strategy +Persistent volumes (PV) provisioning:: +Users can run multiple workspaces simultaneously. This action results in more PVs. -When using the `unique `PVC strategy, every {prod-short} Volume of a workspace has its own PVC. This means that workspace PVCs are: +[id="the-unique-storage-strategy_{context}"] +== The `unique` storage strategy -Created when a workspace starts for the first time. -Deleted when a corresponding workspace is deleted. +Each {prod-short} volume defined in a workspace has its own PV. -User-defined PVCs are created with the following specifics: +When the user starts a workspace, the workspace engine creates the workspace PVs. -* They are provisioned with generated names to prevent naming conflicts with other PVCs in a {orch-namespace}. +The workspace engine generates a unique name for each PV to prevent name conflicts with other PVs in the same {orch-namespace}. -* Subpaths of the mounted Physical persistent volumes that reference user-defined PVCs are prefixed with `__` or `____`. This ensures that the same PV data structure is set up with different PVC strategies. For details, see xref:how-subpaths-are-used-in-pvcs_{context}[]. +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 `__` or `____`. +See xref:how-subpaths-are-used-in-persistent-volumes_{context}[]. -The `unique` PVC strategy is suitable for larger multi-node clusters with a lesser amount of users. Since this strategy operates with separate PVCs for each volume in a workspace, vastly more PVCs are created. +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-pvcs_{context}"] -== How subpaths are used in PVCs -Subpaths illustrate the folder hierarchy in the Persistent Volumes (PV). +[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 - / - / - / + /____ + /____ + /____ + /____ + /____ ... ---- -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 `____`, `____, or `____`. Each component can have this location mounted on a different path in its containers. - - -.Example -Using the `common` PVC strategy, user-defined PVCs are replaced with subpaths on the common PVC. When the user references a volume as `my-volume`, it is mounted in the common-pvc with the `/workspace-id/my-volume` subpath. +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 `____`, `____`, or `____`. +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 index 395b9263ca..d67a9e293a 100644 --- a/modules/installation-guide/partials/con_security-considerations.adoc +++ b/modules/installation-guide/partials/con_security-considerations.adoc @@ -7,7 +7,6 @@ This section explains the security impact of using different {prod-short} workspace exposure strategies. -All the security-related considerations in this section are only applicable to {prod-short} in multiuser mode. The single user mode does not impose any security restrictions. [id="json-web-token-jwt-proxy_{context}"] == JSON web token (JWT) proxy @@ -24,7 +23,7 @@ The JWT proxy accepts the workspace access token from the following places in th == 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 transparent to the user and is governed by the plug-in or editor definition in their `meta.yaml` descriptors. +{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 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 index 17b5429f55..e61b839014 100644 --- 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 @@ -21,5 +21,4 @@ $ kubectl rollout restart deployment/che .Additional resources -* link:https://docs.openshift.com/container-platform/latest/builds/setting-up-trusted-ca.html[Understanding `configMaps`] - +* 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-che-server-advanced-configuration-using-the-operator.adoc b/modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-using-the-operator.adoc index 817f74700d..dbbb679db2 100644 --- a/modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-using-the-operator.adoc +++ b/modules/installation-guide/partials/con_understanding-che-server-advanced-configuration-using-the-operator.adoc @@ -18,25 +18,25 @@ map of additional environment variables to apply to the {prod-short} server comp .Override the default memory limit for workspaces ==== -* Add the `pass:[CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB]` property to `customCheProperties`: +Add the `pass:[CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB]` property to `customCheProperties`: [source,yaml,subs="+quotes,+attributes,+macros"] ---- apiVersion: org.eclipse.che/v1 kind: CheCluster -# [...] +# ... spec: server: - # [...] + # ... customCheProperties: pass:[CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB]: "2048" -# [...] +# ... ---- ==== [NOTE] ==== -Previous versions of the {prod-short} Operator had a configMap named `custom` to fulfill this role. If the {prod-short} Operator finds a `configMap` with the name `custom`, it adds the data it contains into the `customCheProperties` field, redeploys {prod-short}, and deletes the `custom` `configMap`. +Previous versions of the {prod-short} Operator had a ConfigMap named `custom` to fulfill this role. If the {prod-short} Operator finds a `configMap` with the name `custom`, it adds the data it contains into the `customCheProperties` field, redeploys {prod-short}, and deletes the `custom` `configMap`. ==== .Additional resources 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 index 150765ed74..22d356fa40 100644 --- a/modules/installation-guide/partials/con_understanding-the-checluster-custom-resource.adoc +++ b/modules/installation-guide/partials/con_understanding-the-checluster-custom-resource.adoc @@ -1,35 +1,34 @@ [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. +A default deployment of {prod-short} consists of a `CheCluster` Custom Resource parameterized by the {prod} Operator. -`CheCluster` Custom Resource:: +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`. -* A YAML document describing the configuration of the overall {prod-short} installation. -* 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. - -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. +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 ==== -. 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. +. 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/olm-what-operators-are.html[Understanding Operators]. +* link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Understanding Operators]. + +ifeval::["{project-context}" == "crw"] * 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. +endif::[] + +ifeval::["{project-context}" == "che"] + +* link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[Understanding Custom Resources]. + +endif::[] + diff --git a/modules/installation-guide/partials/con_workspace-exposure-strategies.adoc b/modules/installation-guide/partials/con_workspace-exposure-strategies.adoc index f1d95b3795..1fa3dd4366 100644 --- a/modules/installation-guide/partials/con_workspace-exposure-strategies.adoc +++ b/modules/installation-guide/partials/con_workspace-exposure-strategies.adoc @@ -20,11 +20,11 @@ ifeval::["{project-context}" == "che"] endif::[] [id="multi-host-workspace-exposure-strategy_{context}"] -== Multi-host strategy +== Multihost strategy -With multi-host strategy, each workspace component is assigned a new subdomain of the main domain configured for the {prod-short} server. This is the default 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 present in the URL to the component are received as they are by the component. +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. @@ -35,14 +35,14 @@ With single-host strategy, all workspaces are deployed to sub-paths of the main 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. +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}. ==== -There are two ways of exposing the endpoints specified in the devfile. These can be configured using the `++CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE++` environment variable of the {prod-short}. This environment variable is only effective with the single-host server strategy and is applicable to all workspaces of all users. +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` @@ -50,7 +50,7 @@ There are two ways of exposing the endpoints specified in the devfile. These can This single-host configuration exposes the endpoints on subpaths, for example: `++https:///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 `[{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. +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. diff --git a/modules/installation-guide/partials/proc_building-a-registry-image.adoc b/modules/installation-guide/partials/proc_building-a-registry-image.adoc deleted file mode 100644 index 7218d3a188..0000000000 --- a/modules/installation-guide/partials/proc_building-a-registry-image.adoc +++ /dev/null @@ -1,60 +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-{registry-mode}-{registry-id}-registry-image_{context}"] -= Building {registry-mode-name} {registry-name} registry image - -This section describes how to build {registry-mode-name} {registry-name} registry image. -ifeval::["{registry-mode}" == "offline"] -Starting workspaces without relying on resources from the outside Internet requires building this image. -ifeval::["{registry-id}" == "devfile"] -The image contains all sample projects referenced in devfiles as `zip` files. -endif::[] -ifeval::["{registry-id}" == "plugin"] -The image contains plug-in metadata and all plug-in or extension artifacts. -endif::[] -endif::[] -ifeval::["{registry-mode}" == "custom"] -The procedure explains how to add a new {registry-name}. -ifeval::["{registry-id}" == "devfile"] -The image contains all sample projects referenced in devfiles. -endif::[] -ifeval::["{registry-id}" == "plugin"] -The image contains plug-ins or extensions metadata. -endif::[] -endif::[] - - -.Procedure - -. Clone the {registry-name} registry repository and check out the version to deploy: -+ -[subs="+attributes,+quotes"] ----- -include::example$snip_{project-context}-clone-the-registry-repository.adoc[] ----- - -ifeval::["{registry-mode}" == "custom"] -include::administration-guide:example$snip_customizing-the-{registry-name}-registry.adoc[] -endif::[] - -. Build {registry-mode-name} {registry-name} registry image: -+ -[subs="+quotes"] ----- -include::example$snip_{project-context}-build-a-registry.adoc[] ----- -+ -[NOTE] -==== -To display full options for the `build.sh` script, use the `--help` parameter. -ifeval::["{registry-mode}" == "custom"] -ifeval::["{registry-id}" == "plugin"] - -To include the plug-in binaries in the registry image, add the `--offline` parameter. -endif::[] -endif::[] -==== - diff --git a/modules/installation-guide/partials/proc_building-an-offline-devfile-registry-image.adoc b/modules/installation-guide/partials/proc_building-an-offline-devfile-registry-image.adoc new file mode 100644 index 0000000000..a63e2a3794 --- /dev/null +++ b/modules/installation-guide/partials/proc_building-an-offline-devfile-registry-image.adoc @@ -0,0 +1,34 @@ +// Used in: +// * installation-guide/installing-che-in-a-restricted-environment/ +// * installation-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 + +This section describes how to build an offline devfile registry image. +Starting workspaces without relying on resources from the outside Internet requires building this image. +The image contains all sample projects referenced in devfiles as `zip` files. + +.Prerequisites: + +* A running installation of link:http://podman.io[podman] or link:http://docker.io[docker]. + +.Procedure + +. Clone the devfile registry repository and check out the version to deploy: ++ +include::example$snip_{project-context}-clone-the-devfile-registry-repository.adoc[] + +. Build an offline devfile registry image: ++ +include::example$snip_{project-context}-build-an-offline-devfile-registry.adoc[] ++ +[NOTE] +==== +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/installation-guide/partials/proc_building-an-offline-plug-in-registry-image.adoc new file mode 100644 index 0000000000..4e778b077f --- /dev/null +++ b/modules/installation-guide/partials/proc_building-an-offline-plug-in-registry-image.adoc @@ -0,0 +1,41 @@ +// Used in: +// * installation-guide/installing-che-in-a-restricted-environment/ +// * installation-guide/upgrading-che-using-the-cli-management-tool-in-restricted-environment/ + + +[id="building-an-offline-plug-in-registry-image_{context}"] += Building an offline plug-in registry image + +This section describes how to build an offline plug-in registry image. +Starting workspaces without relying on resources from the outside Internet requires building this image. +The image contains plug-in metadata and all plug-in or extension artifacts. + +.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-in registry repository and check out the version to deploy: ++ +include::example$snip_{project-context}-clone-the-plug-in-registry-repository.adoc[] + +. Build offline plug-in registry image: ++ +include::example$snip_{project-context}-build-an-offline-plug-in-registry.adoc[] ++ +[NOTE] +==== +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_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 index 7af300e77c..56e1e9cd24 100644 --- 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 @@ -5,7 +5,7 @@ [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 (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: @@ -15,74 +15,6 @@ A persistent volume claim (PVC) is a request to provision persistent storage of The mounted PVC is displayed as a folder in a container file system. -ifeval::["{project-context}" == "che"] - -[id="configuring-a-pvc-strategy-using-the-helm-chart_{context}"] -== Configuring a PVC strategy using the Helm chart - -The following section describes how to configure workspace persistent volume claim (PVC) strategies of a {prod-short} server using the Helm chart. - -WARNING: It is not recommended to reconfigure PVC strategies on an existing {prod-short} cluster with existing workspaces. Doing so causes data loss. - -.Prerequisites - -* The `helm` tool is available. See link:https://helm.sh/[Helm Chart]. - -.Procedure - -When deploying {prod-short} using Helm Chart, configure the workspace PVC strategy by setting values for the `global.cheWorkspacesPVCStrategy` option. - -* For a new installation, use the `helm install` command with the `global.cheWorkspacesPVCStrategy` option: -+ -[subs="+quotes"] ----- -$ helm install --set global.cheWorkspacesPVCStrategy=per-workspace ----- - -* For an already installed instance, use the `helm upgrade` command with the `global.cheWorkspacesPVCStrategy` option: -+ -[subs="+quotes"] ----- -$ helm upgrade --set global.cheWorkspacesPVCStrategy=per-workspace ----- - -Depending on the strategy used, replace the `per-workspace` value in the above examples with `unique` or `common`. - -[id="configuring-a-pvc-strategy-by-editing-a-configmap_{context}"] -== Configuring a PVC strategy strategy by editing a configMap - -Based on the {prod-short} installation method, configMaps can be used to customize the working environment. A configMap is provided as an editable file that lists options to customize the {prod-short} environment. This method of configuring a persistent volume claim (PVC) strategy for a {prod-short} workspace is available only for the Helm installation. - -Changes to a configMap created during Operator installation are not permanent because the Operator overwrites them back to default. - -.Prerequisites - -* The `helm` tool method was used to deploy {prod-short}. -* The `{orch-cli}` tool is available. - -.Procedure - -. Set the configMap variable to reflect the requested PVC strategy: -+ -[subs="+quotes"] ----- -CHE_INFRA_KUBERNETES_PVC_STRATEGY=per-workspace ----- -+ -Depending on the strategy used, replace the `_per-workspace_` option in the above example with `unique` or `common`. - -. Restart {prod-short} by scaling the deployment to zero and then back to one again: -+ -[subs="+quotes"] ----- -$ oc scale --replicas=0 deployment {prod-deployment} -$ oc scale --replicas=1 deployment {prod-deployment} ----- - -. Restart the workspace for the changes to take effect. -endif::[] - - [id="configuring-a-pvc-strategy-using-the-operator_{context}"] == Configuring a PVC strategy using the Operator @@ -90,7 +22,7 @@ The following section describes how to configure workspace persistent volume cla 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/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. +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. @@ -115,7 +47,7 @@ $ {orch-cli} apply -f __ + [subs="+quotes,+attributes"] ---- -$ {orch-cli} patch checluster {prod-checluster} --type=json \ +$ {orch-cli} patch checluster/{prod-checluster} --type=json \ -p '[{"op": "replace", "path": "/spec/storage/pvcStrategy", "value": "per-workspace"}]' ---- diff --git a/modules/installation-guide/partials/proc_configuring-che-hostname.adoc b/modules/installation-guide/partials/proc_configuring-che-hostname.adoc index 6863caf569..786373c2b3 100644 --- a/modules/installation-guide/partials/proc_configuring-che-hostname.adoc +++ b/modules/installation-guide/partials/proc_configuring-che-hostname.adoc @@ -1,17 +1,20 @@ +:parent-context-of-customize-chehost: {context} [id="customize-chehost_{context}"] -= Configuring {prod} server hostname += Configuring {prod} server host name -This procedure describes how to configure {prod} to use custom hostname. +:context: customize-chehost + +This procedure describes how to configure {prod-short} to use custom host name. .Prerequisites * The `{orch-cli}` tool is available. * The certificate and the private key files are generated. -IMPORTANT: To generate the pair of private key and certificate the same CA must be used as for other {prod} hosts. +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 hostname to the cluster ingress. +IMPORTANT: Ask a DNS provider to point the custom host name to the cluster ingress. .Procedure @@ -22,19 +25,27 @@ IMPORTANT: Ask a DNS provider to point the custom hostname to the cluster ingres $ {orch-cli} create {orch-namespace} {prod-namespace} ---- -. Create a tls secret: +. Create a TLS secret: + [subs="+quotes,attributes"] ---- -$ {orch-cli} create secret tls $\{secret} \ <1> ---key $\{key_file} \ <2> ---cert $\{cert_file} \ <3> +$ {orch-cli} create secret TLS ____ \ <1> +--key ____ \ <2> +--cert ____ \ <3> -n {prod-namespace} ---- -<1> The tls secret name +<1> The TLS secret name <2> A file with the private key <3> A file with the certificate +. Add the required labels to the secret: ++ +[subs="+quotes,attributes"] +---- +$ {orch-cli} label secret ____ \ <1> +app.kubernetes.io/part-of=che.eclipse.org -n {prod-namespace} +---- +<1> The TLS secret name . Set the following values in the Custom Resource: + @@ -45,9 +56,9 @@ spec: cheHost: <1> cheHostTLSSecret: <2> ---- -<1> Custom {prod} server hostname -<2> The tls secret name +<1> Custom {prod} server host name +<2> The TLS secret name -. If {prod-short} has been already deployed and {prod-short} reconfiguring to use a new {prod-short} hostname is required, log in using {identity-provider} and select the `{prod-deployment}-public` client in the `{prod-short}` realm and update `Validate Redirect URIs` and `Web Origins` fields with the value of the {prod-short} hostname. -+ -image::keycloak/keycloak_che_public_client.png[] +. 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/installation-guide/partials/proc_configuring-communication-between-che-components.adoc b/modules/installation-guide/partials/proc_configuring-communication-between-che-components.adoc new file mode 100644 index 0000000000..ea16affd5d --- /dev/null +++ b/modules/installation-guide/partials/proc_configuring-communication-between-che-components.adoc @@ -0,0 +1,65 @@ +[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 `____` 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: ____ +---- +==== + +.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 index 7ff448cd22..9674f8a075 100644 --- a/modules/installation-guide/partials/proc_configuring-dns-on-azure.adoc +++ b/modules/installation-guide/partials/proc_configuring-dns-on-azure.adoc @@ -1,7 +1,3 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-microsoft-azure - [id="configuring-DNS-on-azure_{context}"] = Configuring DNS on Azure @@ -11,27 +7,27 @@ To configure DNS on Azure: . In the Azure web console, navigate to *Home* -> *DNS zones*. + -image::installation/dns-zone-in-microsoft-azure.png[link="../_images/installation/dns-zone-in-microsoft-azure.png"] +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[link="../_images/installation/selecting-the-resource-group.png"] +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). +.. 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[link="../_images/installation/entering-the-name-fo-the-domain.png"] +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[link="../_images/installation/completing-the-creation-of-the-zone.png"] +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[link="../_images/installation/list-of-created-zones-and-NS.png"] +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. @@ -43,8 +39,8 @@ These servers must be configured with the registrar of the domain. .. 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[link="../_images/installation/adding-a-record-set.png"] +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[link="../_images/installation/example-of-an-added-dns-zone.png"] +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-ingresses.adoc b/modules/installation-guide/partials/proc_configuring-ingresses.adoc new file mode 100644 index 0000000000..728b393a3d --- /dev/null +++ b/modules/installation-guide/partials/proc_configuring-ingresses.adoc @@ -0,0 +1,73 @@ + +[id="configuring-ingresses_{context}"] += Configuring {orch-ingress} + +By configuring labels and annotations for {orch-ingress} you can organize and categorize objects by scoping and selecting. + +.Prerequisites + +* The `{orch-cli}` tool is available. +* An instance of {prod-short} running in {orch-name}. + +.Procedure + +. To configure labels for {orch-ingress}, update the Custom Resource: ++ +IMPORTANT: Use commas to separate labels: `key1=value1,key2=value2`. ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/cheServerIngress/labels", '\ +'"value": "____"}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/auth/identityProviderIngress/labels", '\ +'"value": "____"}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/pluginRegistryIngress/labels", '\ +'"value": "____"}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/devfileRegistryIngress/labels",'\ +'"value": "____"}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/dashboardIngress/labels",'\ +'"value": "____"}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/customCheProperties/CHE_INFRA_KUBERNETES_INGRESS_LABELS", '\ +'"value": "____"}]' +---- +. To configure annotations for {orch-ingress}, update the Custom Resource with the following commands: ++ +IMPORTANT: Use objects to specify annotations: `{"key1": "value1", "key2" : "value2"}`. ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/cheServerIngress/annotations", '\ +'"value": ____}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/auth/identityProviderIngress/annotations", '\ +'"value": ____}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/pluginRegistryIngress/annotations", '\ +'"value": ____}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/devfileRegistryIngress/annotations",'\ +'"value": ____}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/dashboardIngress/annotations",'\ +'"value": ____}]' + +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/customCheProperties/CHE_INFRA_KUBERNETES_INGRESS_ANNOTATIONS______JSON", '\ +'"value": "____"}]' +---- diff --git a/modules/installation-guide/partials/proc_configuring-labels-for-ingresses.adoc b/modules/installation-guide/partials/proc_configuring-labels-for-ingresses.adoc deleted file mode 100644 index 1a06da8df5..0000000000 --- a/modules/installation-guide/partials/proc_configuring-labels-for-ingresses.adoc +++ /dev/null @@ -1,35 +0,0 @@ - -[id="configuring-labels-for-ingresses_{context}"] -= Configuring labels for Kubernetes Ingress - -This procedure describes how to configure labels for Kubernetes Ingress to organize and categorize (scope and select) objects. - -.Prerequisites - -* The `{orch-cli}` tool is available. -* An instance of {prod-short} running in {orch-name}. - -IMPORTANT: Use comma to separate labels: `key1=value1,key2=value2` - -.Procedure - -. To configure labels for Kubernetes Ingress update the Custom Resource with the following commands: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/server/cheServerIngress/labels", '\ -'"value": "____"}]' - -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/auth/identityProviderIngress/labels", '\ -'"value": "____"}]' - -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/server/pluginRegistryIngress/labels", '\ -'"value": "____"}]' - -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/server/devfileRegistryIngress/labels",'\ -'"value": "____"}]' ----- diff --git a/modules/installation-guide/partials/proc_configuring-labels-for-routes.adoc b/modules/installation-guide/partials/proc_configuring-labels-for-routes.adoc deleted file mode 100644 index 26b0c86195..0000000000 --- a/modules/installation-guide/partials/proc_configuring-labels-for-routes.adoc +++ /dev/null @@ -1,35 +0,0 @@ - -[id="configuring-labels-for-routes_{context}"] -= Configuring labels for OpenShift Route - -This procedure describes how to configure labels for OpenShift Route to organize and categorize (scope and select) objects. - -.Prerequisites - -* The `{orch-cli}` tool is available. -* An instance of {prod-short} running in OpenShift. - -IMPORTANT: Use comma to separate labels: `key1=value1,key2=value2` - -.Procedure - -. To configure labels for OpenShift Route update the Custom Resource with the following commands: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/server/cheServerRoute/labels",'\ -'"value": "____"}]' - -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/auth/identityProviderRoute/labels", '\ -'"value": "____"}]' - -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/server/pluginRegistryRoute/labels", '\ -'"value": "____"}]' - -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/server/devfileRegistryRoute/labels", '\ -'"value": "____"}]' ----- diff --git a/modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc b/modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc index f3dc4dda4e..679016d199 100644 --- a/modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc +++ b/modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc @@ -1,14 +1,14 @@ [id="configuring-namespace-strategies_{context}"] -= Configuring {orch-namespace} strategies += Configuring workspace target {orch-namespace} -The {platforms-namespace} where a new workspace Pod is deployed depends on the {prod-short} server configuration. By default, every workspace is deployed in a distinct {platforms-namespace}, but the user can configure the {prod-short} server to deploy all workspaces in one specific {platforms-namespace}. The name of a {platforms-namespace} must be provided as a {prod-short} server configuration property and cannot be changed at runtime. +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::[] -With **Operator** installer, {platforms-namespace} strategies are configured using `server.workspaceNamespaceDefault` property. +{platforms-namespace} strategies are configured using `server.workspaceNamespaceDefault` property. *Operator CheCluster CR patch* [subs="+quotes,+attributes"] @@ -21,162 +21,65 @@ spec: server: workspaceNamespaceDefault: ____ <1> ---- -<1> - {prod-short} workspace namespace configuration +<1> - {prod-short} workspace {orch-namespace} configuration -ifeval::["{project-context}" == "che"] -With **Helm** installer, Kubernetes namespaces strategies are configured using `global.cheWorkspacesNamespace` property. - -*Helm* -[subs="+quotes,+attributes"] ----- -$ helm install --namespace - --set global.cheWorkspacesNamespace=____ <1> ----- -or -[subs="+quotes,+attributes"] ----- -$ helm upgrade --namespace - --set global.cheWorkspacesNamespace=____ <1> ----- -<1> - {prod-short} workspace namespace configuration -endif::[] - NOTE: The underlying environment variable that {prod-short} server uses is `CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT`. -WARNING: `CHE_INFRA_KUBERNETES_NAMESPACE` and `CHE_INFRA_OPENSHIFT_PROJECT` are legacy variables. Keep these variables unset for a new installations. Changing these variables during an update can lead to data loss. - -WARNING: By default, only one workspace in the same {orch-namespace} can be running at one time. See xref:running-more-than-one-workspace-at-a-time.adoc[]. +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] ==== -{kubernetes} limits the length of a namespace name to 63 characters (this includes the evaluated placeholders). Additionally, the names (after placeholder evaluation) must be valid DNS names. +{kubernetes} limits the length of a {orch-namespace} name to 63 characters (this includes the evaluated placeholders). Additionally, the names (after placeholder evaluation) must be valid DNS names. -On OpenShift with multi-host server exposure strategy, the length is further limited to 49 characters. +On OpenShift with multihost server exposure strategy, the length is further limited to 49 characters. Be aware that the `__` placeholder is evaluated into a 36 character long UUID string. ==== -WARNING: For strategies where creating new {orch-namespace} is needed, make sure that `che` ServiceAccount has enough permissions to do so. With OpenShift OAuth, the authenticated User must have privileges to create new {orch-namespace}. - -== One {orch-namespace} per user strategy - -The strategy isolates each user in their own {orch-namespace}. - -To use the strategy, set the _{prod-short} workspace namespace configuration_ value to contain one or more user identifiers. Currently supported identifiers are `__` and `__`. - -.One {orch-namespace} per user -==== -To assign {orch-namespace} names composed of a __`{prod-workspace}`__ prefix and individual usernames (`__{prod-workspace}__-user1`, `__{prod-workspace}__-user2`), set: - -*Operator installer (CheCluster CustomResource)* -[subs="+quotes,+attributes"] ----- -... -spec: - server: - workspaceNamespaceDefault: __{prod-workspace}__-____ -... ----- - -ifeval::["{project-context}" == "che"] -*Helm* -[subs="+quotes,+attributes"] ----- -$ helm ... --set global.cheWorkspacesNamespace=__{prod-workspace}__-____ ----- -endif::[] +[WARNING] ==== +Use <> when: -== One {orch-namespace} per workspace strategy - -The strategy creates a new {orch-namespace} for each new workspace. +* `che` ServiceAccount does not have enough permissions when creating new {orch-namespace} -To use the strategy, set the _{prod-short} workspace namespace configuration_ value to contain the `__` identifier. It can be used alone or combined with other identifiers or any string. +pass:[] -.One {orch-namespace} per workspace -==== -To assign {orch-namespace} names composed of a __`{prod-workspace}`__ prefix and workspace id, set: +* OpenShift OAuth with a `self-provisioner` cluster role is not linked to the `system:authenticated:oauth` group -*Operator installer (CheCluster CustomResource)* -[subs="+quotes,+attributes"] ----- -... -spec: - server: - workspaceNamespaceDefault: __{prod-workspace}__-____ -... ----- +pass:[] -ifeval::["{project-context}" == "che"] -*Helm* -[subs="+quotes,+attributes"] ----- -$ helm ... --set global.cheWorkspacesNamespace=__{prod-workspace}__-____ ----- -endif::[] +* {prod-short} cannot create namespaces ==== -== One {orch-namespace} for all workspaces strategy +== One {orch-namespace} per user strategy -The strategy uses one predefined {orch-namespace} for all workspaces. +The strategy isolates each user in their own {orch-namespace}. -To use the strategy, set the _{prod-short} workspace namespace configuration_ value to the name of the desired {orch-namespace} to use. +To use the strategy, set the _{prod-short} workspace {orch-namespace} configuration_ value to contain one or more user identifiers. Currently supported identifiers are `__` and `__`. -.One {orch-namespace} for all workspaces +.One {orch-namespace} per user ==== -To have all workspaces created in __`{prod-workspace}`__ {orch-namespace}, set: +To assign {orch-namespace} names composed of a __`{prod-workspace}`__ prefix and individual usernames (`__{prod-workspace}__-user1`, `__{prod-workspace}__-user2`), set in CheCluster Custom Resource: -*Operator installer (CheCluster CustomResource)* [subs="+quotes,+attributes"] ---- ... spec: server: - workspaceNamespaceDefault: __{prod-workspace}__ + workspaceNamespaceDefault: __{prod-workspace}__-____ ... ---- - -ifeval::["{project-context}" == "che"] -*Helm* -[subs="+quotes,+attributes"] ----- -$ helm ... --set global.cheWorkspacesNamespace=__{prod-workspace}__ ----- -endif::[] ==== -== Allowing user-defined workspace {orch-namespace}s - -{prod-short} server can be configured to honor the user selection of a {orch-namespace} when a workspace is created. This feature is disabled by default. To allow user-defined workspace {orch-namespace}s: - -ifeval::["{project-context}" == "che"] -* For Helm Chart deployments, set the following environment variable in the {prod-short} ConfigMap: -+ -[subs="+quotes,macros"] ----- -pass:[CHE_INFRA_KUBERNETES_NAMESPACE_ALLOW__USER__DEFINED]=true ----- -endif::[] - -* For Operator deployments, set the following field in the CheCluster Custom Resource: -+ ----- -... -server: - allowUserDefinedWorkspaceNamespaces: true -... ----- - == Handling incompatible usernames or user IDs -{prod-short} server automatically checks usernames and IDs for compatibility with Kubernetes objects naming convention before creating a {orch-namespace} from a template. -Incompatible username or IDs are reduced to the nearest valid name by replacing groups of unsuitable symbols with the `-` symbol. To avoid collisions, -a random 6-symbol suffix is added and the result is stored in preferences for reuse. +{prod-short} server automatically checks usernames and IDs for compatibility with {orch-name} objects naming convention before creating a {orch-namespace} from a template. Incompatible usernames or IDs are reduced to the nearest valid name by replacing groups of unsuitable symbols with the `-` symbol. The addition of a random 6-symbol suffix prevents IDs from collisions. The result is stored in preferences for reuse. -== Pre-creating {orch-namespace}s for users +[#pre-creating-namespace] +== Pre-creating a {orch-namespace} for each user -To pre-create {orch-namespace}s for users, use {orch-namespace} labels and annotations. Such namespace is used in preference to `CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT` variable. +To pre-create a {orch-namespace} for each user, use {orch-name} labels and annotations. Such {orch-namespace} is used in preference to `CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT` variable. ---- metadata: @@ -192,12 +95,12 @@ To configure the labels, set the `CHE_INFRA_KUBERNETES_NAMESPACE_LABELS` to desi [WARNING] ==== -We do not recommend to create multiple namespaces for single user. It may lead to undefined behavior. +Do not create multiple namespaces for a single user. It may lead to undefined behavior. ==== [IMPORTANT] ==== -On OpenShift with OAuth, target user must have `admin` role privileges in target namespace: +On OpenShift with OAuth, the target user must have `admin` role privileges in the target namespace: ---- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding @@ -220,7 +123,8 @@ On {kubernetes}, `che` ServiceAccount must have a cluster-wide `list` and `get` ==== == Labeling the namespaces -{prod-short} updates the workspace's namespace on workspace startup by adding the labels defined in `CHE_INFRA_KUBERNETES_NAMESPACE_LABELS`. To do so, `che` ServiceAccout has to have the following cluster-wide permissions to `update` and `get` `namespaces`: + +{prod-short} updates the workspace's {orch-namespace} on workspace startup by adding the labels defined in `CHE_INFRA_KUBERNETES_NAMESPACE_LABELS`. To do so, `che` ServiceAccount has to have the following cluster-wide permissions to `update` and `get` `namespaces`: ---- apiVersion: rbac.authorization.k8s.io/v1 @@ -253,11 +157,11 @@ roleRef: apiGroup: rbac.authorization.k8s.io ---- <1> name of the cluster role binding -<2> name of the che service account +<2> name of the `che` ServiceAccount <3> {prod-short} installation namespace <4> name of the cluster role created in previous step [NOTE] ==== -{prod-short} does not fail to start a workspace for lack of permissions, it only logs the warning. If you see the warnings in {prod-short} logs, consider disabling the feature with setting `CHE_INFRA_KUBERNETES_NAMESPACE_LABEL=false`. +A lack of permissions does not prevent a {prod-short} workspace from starting, it only logs the warning. If you see the warnings in {prod-short} logs, consider disabling the feature by defining `CHE_INFRA_KUBERNETES_NAMESPACE_LABEL=false`. ==== diff --git a/modules/installation-guide/partials/proc_configuring-routes.adoc b/modules/installation-guide/partials/proc_configuring-routes.adoc new file mode 100644 index 0000000000..ce11ef24c6 --- /dev/null +++ b/modules/installation-guide/partials/proc_configuring-routes.adoc @@ -0,0 +1,254 @@ + +[id="configuring-routes_{context}"] += Configuring OpenShift Route to work with Router Sharding + +This procedure describes how to configure labels, annotations, and domains for OpenShift Route to work with link:https://docs.openshift.com/container-platform/4.7/networking/ingress-operator.html#nw-ingress-sharding_configuring-ingress[Router Sharding]. The chapter then mentions the configuration process for existing instances or those about to be installed. + +.Prerequisites + +* The `oc` and `{prod-cli}` tool is available. + +.Procedure + +* 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] + ++ +. Set the following values in {prod-checluster} Custom Resource (CR): ++ +[source,yaml,subs="+quotes"] +---- +spec: + server: + devfileRegistryRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 + pluginRegistryRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 + dashboardRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 + cheServerRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 + customCheProperties: + CHE_INFRA_OPENSHIFT_ROUTE_LABELS: <1> + CHE_INFRA_OPENSHIFT_ROUTE_HOST_DOMAIN__SUFFIX: <2> + auth: + identityProviderRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 +---- +<1> comma separated list of labels that are used by the target ingress controller to filter the set of Routes to service +<2> DNS name serviced by the target ingress controller +<3> unstructured key value map stored with a resource + +* For a new `{prod-cli}` installation: ++ +. Configure the installation using: ++ +[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: + server: + devfileRegistryRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 + pluginRegistryRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 + dashboardRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 + cheServerRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 + customCheProperties: + CHE_INFRA_OPENSHIFT_ROUTE_LABELS: <1> + CHE_INFRA_OPENSHIFT_ROUTE_HOST_DOMAIN__SUFFIX: <2> + auth: + identityProviderRoute: + labels: <1> + domain: <2> + annotations: <3> + key1: value1 + key2: value2 +---- +<1> comma separated list of labels that are used by the target ingress controller to filter the set of Routes to service +<2> DNS name serviced by the target ingress controller +<3> unstructured key value map stored with a resource + +* For already existing {prod-short} installation: ++ +. Update `{prod-checluster}` CR using the `{orch-cli}` tool: ++ +.. To configure labels: ++ +IMPORTANT: Use comma to separate labels: `key1=value1,key2=value2` ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/cheServerRoute/labels",'\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/pluginRegistryRoute/labels", '\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/devfileRegistryRoute/labels", '\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/dashboardRoute/labels", '\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/auth/identityProviderRoute/labels", '\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/customCheProperties/CHE_INFRA_OPENSHIFT_ROUTE_LABELS", '\ +'"value": "____"}]' +---- ++ +.. To configure domains: ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/cheServerRoute/domain",'\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/pluginRegistryRoute/domain", '\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/devfileRegistryRoute/domain", '\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/dashboardRoute/domain", '\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/auth/identityProviderRoute/domain", '\ +'"value": "____"}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/customCheProperties/CHE_INFRA_OPENSHIFT_ROUTE_HOST_DOMAIN______SUFFIX", '\ +'"value": "____"}]' +---- ++ +.. To configure annotations: ++ +IMPORTANT: Use object to specify annotations: `{"key1": "value1", "key2" : "value2"}` ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/cheServerRoute/annotations",'\ +'"value": ____}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/pluginRegistryRoute/annotations", '\ +'"value": ____}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/devfileRegistryRoute/annotations", '\ +'"value": ____}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/server/dashboardRoute/annotations", '\ +'"value": ____}]' +---- ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p \ +'[{"op": "replace", "path": "/spec/auth/identityProviderRoute/annotations", '\ +'"value": ____}]' +---- + + + + + + diff --git a/modules/installation-guide/partials/proc_configuring-storage-types.adoc b/modules/installation-guide/partials/proc_configuring-storage-types.adoc index ef96a8a19c..f240ee3ea5 100644 --- a/modules/installation-guide/partials/proc_configuring-storage-types.adoc +++ b/modules/installation-guide/partials/proc_configuring-storage-types.adoc @@ -47,7 +47,7 @@ attributes: |=== |Command |Ephemeral -|Persitent +|Persistent |Clone {prod} |0 m 19 s @@ -67,7 +67,7 @@ Asynchronous storage is a combination of persistent and ephemeral modes. The ini 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-theia/tree/master/extensions/eclipse-che-theia-file-sync-tracker[Extension in Che-Theia repository]). +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] @@ -117,3 +117,10 @@ 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 index 3fc8becf81..11c62061cc 100644 --- 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 @@ -2,12 +2,12 @@ [id="configuring-the-che-operator-checluster-resource-with-kubectl_{context}"] -= Configuring CheCluster Custom Resource with kubectl -Edit the CheCluster custom resource configuration with kubectl: += Configuring CheCluster Custom Resource with {orch-cli} +Edit the CheCluster custom resource configuration with {orch-cli}: [subs="+attributes"] ---- -kubectl edit CheCluster/eclipse-che -n {prod-namespace} +{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-number-of-workspaces-that-a-user-can-create.adoc b/modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-create.adoc new file mode 100644 index 0000000000..f29f3bec64 --- /dev/null +++ b/modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-create.adoc @@ -0,0 +1,32 @@ +[id="configuring-the-number-of-workspaces-that-a-user-can-create_{context}"] += Configuring the number of workspaces that a user can create + +This procedure describes how to configure the number of workspaces that a user can create. By creating multiple workspaces, users can have access to workspaces with different configurations simultaneously. + +.Prerequisites + +* You have installed an instance of `{prod-short}` by using the Operator. +* You have determined the value of the `__` placeholder. ++ +[NOTE] +==== +If the value is `-1`, users can create an unlimited number of workspaces. If the value is a positive integer, users can create 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 create by adding the `+CHE_LIMITS_USER_WORKSPACES_COUNT+` property to `customCheProperties`: ++ +==== +[source,yaml,subs="+quotes"] +---- +apiVersion: org.eclipse.che/v1 +kind: CheCluster +# ... +spec: + server: + # ... + customCheProperties: + CHE_LIMITS_USER_WORKSPACES_COUNT: "____" +---- +==== 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 new file mode 100644 index 0000000000..7e1876ad84 --- /dev/null +++ b/modules/installation-guide/partials/proc_configuring-the-number-of-workspaces-that-a-user-can-run.adoc @@ -0,0 +1,57 @@ + +[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 `__` 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: "____" +---- +==== diff --git a/modules/installation-guide/partials/proc_configuring-workspace-exposure-strategies-using-a-helm-chart.adoc b/modules/installation-guide/partials/proc_configuring-workspace-exposure-strategies-using-a-helm-chart.adoc deleted file mode 100644 index 0f58cfdc4d..0000000000 --- a/modules/installation-guide/partials/proc_configuring-workspace-exposure-strategies-using-a-helm-chart.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// configuring-workspace-exposure-strategies - -[id="configuring-workspace-exposure-strategies-using-a-helm-chart_{context}"] - -= Configuring workspace exposure strategies using a Helm chart - -A link:https://helm.sh/[Helm Chart] is a {kubernetes} extension for defining, installing, and upgrading {kubernetes} applications. - -.Procedure - -When deploying {prod-short} using the Helm chart, configure the workspace exposure strategy using the `global.serverStrategy`. For single-host, optional `global.singleHostExposure` and `cheSinglehostGateway.deploy` properties may be configured as well. To do so, add the following option to the `helm install` or `helm upgrade` command: - - -Example for `native` single-host strategy type and `multi-host` or `default-host` strategies: - -[subs="+quotes"] ----- -$ helm install --set global.serverStrategy=____ ----- - -or: - -[subs="+quotes"] ----- -$ helm upgrade --set global.serverStrategy=____ ----- - -The supported values for `global.serverStrategy` are: - -* xref:multi-host-workspace-exposure-strategy_{context}[`multi-host`] -* xref:single-host-workspace-exposure-strategy_{context}[`single-host`] -* xref:default-host-workspace-exposure-strategy_{context}[`default-host`] - - -.Gateway single-host on Kubernetes - -Single-host on Kubernetes has 2 implementations, `native`(default) and `gateway`. To deploy with `gateway` use: - -[subs="+quotes,+attributes"] ----- -$ helm install --namespace {prod-namespace} \ ---set global.serverStrategy=single-host \ ---set global.singleHostExposure=gateway \ ---set cheSinglehostGateway.deploy=true ----- - -or: - -[subs="+quotes,+attributes"] ----- -$ helm upgrade --install che --namespace {prod-namespace} \ ---set global.serverStrategy=single-host \ ---set global.singleHostExposure=gateway \ ---set cheSinglehostGateway.deploy=true ----- - -Alternatively, predefined values file can be used as follows: - -[subs="+quotes,+attributes"] ----- -$ helm upgrade --install che --namespace {prod-namespace} \ --f "${SOURCE_HOME_DIR}"/deploy/kubernetes/helm/che/values/single-host-gateway.yaml ----- 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 index 849974f359..27dd0e6854 100644 --- 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 @@ -5,7 +5,7 @@ [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/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. +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 @@ -60,7 +60,7 @@ spec: + [subs="+quotes,+attributes"] ---- -$ {orch-cli} patch checluster {prod-checluster} --type=json \ +$ {orch-cli} patch checluster/{prod-checluster} --type=json \ -p '[{"op": "replace", "path": "/spec/server/serverExposureStrategy", "value": "____"}]' \ <1> @@ -70,8 +70,8 @@ $ {orch-cli} patch checluster {prod-checluster} --type=json \ ifeval::["{project-context}" == "che"] -.Gateway single-host on Kubernetes -Single-host on Kubernetes 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: +.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"] ---- diff --git a/modules/installation-guide/partials/proc_configuring-workspaces-nodeselector.adoc b/modules/installation-guide/partials/proc_configuring-workspaces-nodeselector.adoc index e17fea5b06..d499c50361 100644 --- a/modules/installation-guide/partials/proc_configuring-workspaces-nodeselector.adoc +++ b/modules/installation-guide/partials/proc_configuring-workspaces-nodeselector.adoc @@ -16,7 +16,7 @@ CHE_WORKSPACE_POD_NODE__SELECTOR=disktype=ssd,cpu=xlarge,[key=value] ==== `nodeSelector` must be configured during {prod-short} installation. This prevents existing workspaces from failing to run due to volumes affinity conflict caused by existing workspace PVC and Pod being scheduled in different zones. -To avoid Pods and PVCs to be scheduled in different zones on large, multi-zone clusters, create an additional link:https://kubernetes.io/docs/concepts/storage/storage-classes/[`StorageClass`] object (pay attention to the `allowedTopologies` field), which will coordinate the PVC creation process. +To avoid Pods and PVCs to be scheduled in different zones on large, multizone clusters, create an additional link:https://kubernetes.io/docs/concepts/storage/storage-classes/[`StorageClass`] object (pay attention to the `allowedTopologies` field), which will coordinate the PVC creation process. Pass the name of this newly created `StorageClass` to {prod-short} through the `+CHE_INFRA_KUBERNETES_PVC_STORAGE__CLASS__NAME+` environment variable. A default empty value of this variable instructs {prod-short} to use the cluster's default `StorageClass`. ==== 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 index 665b5dc52e..0c412d8e08 100644 --- 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 @@ -20,7 +20,7 @@ To install the SDK on macOS, use the `$ brew cask install google-cloud-sdk` comm .Procedure -. Ensure the `gcloud` tool is set up: +. Ensure the `gcloud` tool is configured: + ---- $ gcloud init @@ -32,7 +32,7 @@ $ gcloud init $ gcloud projects create eclipse-che-1 ---- -. Check from GCP webconsole that the {kubernetes} engine is available on this project. +. 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: + diff --git a/modules/installation-guide/partials/proc_creating-a-project-in-openshift-web-console.adoc b/modules/installation-guide/partials/proc_creating-a-project-in-openshift-web-console.adoc deleted file mode 100644 index af17e569c2..0000000000 --- a/modules/installation-guide/partials/proc_creating-a-project-in-openshift-web-console.adoc +++ /dev/null @@ -1,20 +0,0 @@ -//This module is included in -// -// * assembly_installing-che-using-the-che-operator-in-openshift-4-web-console - -[id="creating-a-project-in-openshift-web-console_{context}"] -= Creating a project in OpenShift Web Console - -A project allows to organize and manage different resources on the cluster in an isolated unit. Create a project first to host the {prod} Operator. - -.Procedure - -. Open the OpenShift web console, in the left panel navigate to the *Home* -> *Projects* section. - -. Click btn:[Create Project]. - -. Specify the project details: -+ -* *Name*: `{prod-namespace}` -* *Display Name*: `{prod}` -* *Description*: `{prod}` diff --git a/modules/installation-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc b/modules/installation-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc index 6f591f90db..b8b2c76294 100644 --- a/modules/installation-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc +++ b/modules/installation-guide/partials/proc_creating-an-instance-of-the-che-operator.adoc @@ -1,44 +1,44 @@ -//This module is included in +//This module is included in: // -// * assembly_installing-che-using-the-che-operator-in-openshift-4-web-console +// assembly_installing-che-on-openshift-4-using-operatorhub -[id="creating-an-instance-of-the-che-operator_{context}"] +[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[]. .Procedure -. To create an instance of the {prod} Operator, in the left panel, navigate to the *Operators* -> *Installed Operators* section. +// Steps from this procedure are included in installation-guide:proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc[]. -. In the *Installed Operators* screen, click the *{prod}* name. +. In the left panel, click *Operators*, then click *Installed Operators*. -. In the *Operator Details* screen, in the *Details* tab, inside of the *Provided APIs* section, click the *Create Instance* link. +. On the *Installed Operators* page, click the *{prod}* name. -. The *Create CheCluster* page contains the configuration of the overall {prod-short} instance to create. It is the `CheCluster` Custom Resource. Keep the default values. +. 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. -. To create the *{prod-checluster}* cluster, click the btn:[Create] button in the lower left corner of the window. +. Create the *{prod-checluster}* cluster by using the btn:[Create] button at the end of the page using the default values. -. On the *Operator Details* screen, in the *{prod} Cluster* tab, click on the *{prod-checluster}* link. +. On the *Operator details* page, in the *{prod} Cluster* tab, click the *{prod-checluster}* link. -. To navigate to the *{prod-checluster}* instance, click the link under *{prod} URL*. +. 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 after the {prod} installation finishes. +The installation might take more than 5 minutes. The URL appears when the {prod} installation finishes. ==== -.Verification steps +.Verification -. To verify that the {prod} instance has installed correctly, navigate to the *{prod2} Cluster* tab. The *CheClusters* screen displays the list of {prod} instances and their status. +. To verify the {prod-short} instance has installed correctly, navigate to the *{prod2} Cluster* tab of the *Operator details* page. The *CheClusters* page displays the list of {prod-short} instances and their status. -. Click *{prod-checluster}* `CheCluster` in the table and navigate to the *Details* tab. +. Click *{prod-checluster}* `CheCluster` and navigate to the *Details* tab. -. See the content of following fields: +. See the content of the 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. - -. Navigate to the *Resources* tab. The screen displays the list of the resources assigned to the {prod-short} deployment. +* The *Message* field contains error messages. The expected content is `None`. +* The *{prod} URL* field contains the URL of the {prod} instance. The URL appears when the deployment finishes successfully. -. To see more details about the state of a resource, click its name and inspect the content of the available tabs. +. Navigate to the *Resources* tab. View the list of resources assigned to the {prod-short} deployment and their status. diff --git a/modules/installation-guide/partials/proc_deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc b/modules/installation-guide/partials/proc_deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc index 7942a615e8..1e4bf62e74 100644 --- a/modules/installation-guide/partials/proc_deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc +++ b/modules/installation-guide/partials/proc_deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc @@ -8,76 +8,53 @@ This procedure describes how to configure {prod-short} for deployment with suppo .Prerequisites * Git version 2 or later -ifeval::["{project-context}" == "che"] -* link:https://helm.sh/[Helm] version 2.15 or higher -endif::[] .Procedure Configuring support for self-signed Git repositories. -ifeval::["{project-context}" == "che"] -In the instructions below, substitute `kubectl` for `oc` when running {prod-short} on {kubernetes}. -endif::[] - -. Create a new *configMap* with details about the Git server: +. Create a new *ConfigMap* with details about the Git server: + -[subs="+quotes"] +[subs="+quotes,+attributes"] ---- -$ oc create configmap che-git-self-signed-cert --from-file=ca.crt \ - --from-literal=githost=____ -n {prod-namespace} +$ {orch-cli} create configmap che-git-self-signed-cert \ + --from-file=ca.crt=____ \ <1> + --from-literal=githost=____ -n {prod-namespace} <2> ---- -+ -In the command, substitute `__` for the host and port of the HTTPS connection on the Git server (optional). +<1> Path to self-signed certificate +<2> The host and port of the HTTPS connection on the Git server (optional). + [NOTE] ==== * When `githost` is not specified, the given certificate is used for all HTTPS repositories. -* The certificate file must be named `ca.crt`. * Certificate files are typically stored as Base64 ASCII files, such as. `.pem`, `.crt`, `.ca-bundle`. Also, they can be encoded as binary data, for example, `.cer`. All `Secrets` that hold certificate files should use the Base64 ASCII certificate rather than the binary data certificate. ==== -. Configure the workspace exposure strategy: +. Add the required labels to the ConfigMap: + -ifeval::["{project-context}" == "che"] -===== -.For {prod-short} deployed using a Helm Chart - -. Clone the https://github.com/eclipse/che[che] project -. Go to `deploy/kubernetes/helm/che` directory -. Update the `global.useGitSelfSignedCerts` property. To do that, add the following option to the `helm upgrade` command: -+ -[subs="+quotes,+attributes"] +[subs="+quotes,attributes"] ---- -$ helm upgrade che -n {prod-namespace} --set global.useGitSelfSignedCerts=true \ - --set global.ingressDomain=____ . +$ {orch-cli} label configmap che-git-self-signed-cert \ +app.kubernetes.io/part-of=che.eclipse.org -n {prod-namespace} ---- -On Minikube, substitute `__` with `$(minikube ip).nip.io`. -===== -endif::[] +. Configure {prod-short} to use self-signed certificates for git repositories: + -==== - -ifeval::["{project-context}" == "che"] -.For {prod-short} deployed using Operators -endif::[] - Update the `gitSelfSignedCert` property. To do that, execute: - ++ [subs="+attributes"] ---- -$ oc patch checluster {prod-checluster} -n {prod-namespace} --type=json \ - -p '[{"op": "replace", "path": "/spec/server/gitSelfSignedCert", "value": true}]' +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json \ + -p '[{"op": "replace", "path": "/spec/server/gitSelfSignedCert", \ + "value": true}]' ---- -==== // TODO // [discrete] // == Configuring support for self-signed Git repositories on OpenShift . Create and start a new workspace. Every container used by the workspace mounts a special volume that contains a file with the self-signed certificate. The repository's `.git/config` file contains information about the Git server host (its URL) and the path to the certificate in the `http` section (see Git documentation about link:https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslCAInfo[git-config]). For example: -+ + ---- [http "https://10.33.177.118:3000"] - sslCAInfo = /etc/che/git/cert/ca.crt +sslCAInfo = /etc/che/git/cert/ca.crt ---- diff --git a/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc b/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc new file mode 100644 index 0000000000..6b73c09fe8 --- /dev/null +++ b/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc @@ -0,0 +1,74 @@ + +[id="enabling-dev-workspace-operator_{context}"] += Enabling {devworkspace} operator + +This procedure describes how to enable the {devworkspace} operator to support the Devfile v2 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 --workspace-engine=dev-workspace ... +---- + +ifeval::["{project-context}" == "che"] +[WARNING] +==== +{prod-cli} will automatically setup Dex as the OIDC provider on Minikube. For other {kubernetes} clusters setup link:https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server[{kubernetes} OIDC] provider following cluster provider documentation and set the following values in {prod-checluster} Custom Resource (CR): + +[source,yaml,subs="+quotes"] +---- +spec: + auth: + identityProviderURL: '____' <1> +---- + +<1> URL to the OIDC provider. +==== +endif::[] + +* 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_importing-untrusted-tls-certificates-old.adoc b/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates-old.adoc index 53d91ee116..ef9e3109bf 100644 --- a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates-old.adoc +++ b/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates-old.adoc @@ -3,15 +3,7 @@ = Importing untrusted TLS certificates to {prod-short} ==== -NOTE: Starting from {prod-short} version -ifeval::["{project-context}" == "che"] -v7.23.0 -endif::[] -ifeval::["{project-context}" != "che"] -2.5.1 -endif::[] -there is xref:importing-untrusted-tls-certificates.adoc[newer way] to apply additional TLS certificates. -This method is kept for backward compatibility. +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. @@ -20,7 +12,7 @@ When the certificates used by {prod-short} components or by an external service Typical cases that may require this addition are: -* when the underlying Kubernetes cluster uses TLS certificates signed by a CA that is not trusted, +* 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. @@ -33,7 +25,7 @@ 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: +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 @@ -59,10 +51,10 @@ $ {orch-cli} create configmap ca-certs --from-file=____ - + To apply more than one certificate, add another `--from-file=__` option to the above command. -. During the installation process, when creating the `CheCluster` custom resource, take care of configuring the right name for the created ConfigMap. +. 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/olm-what-operators-are.html[Operator] deployment, +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] @@ -73,16 +65,6 @@ spec: spec.server.ServerTrustStoreConfigMapName: ca-certs ---- ==== -ifeval::["{project-context}" == "che"] -+ -==== -For a {prod-short} link:https://helm.sh/[Helm Chart] deployment, ensure you override the `global.tls.serverTrustStoreConfigMapName` Helm Chart property with the name of the ConfigMap when installing the {prod-short} Helm Chart. For this you should add the following arguments to the Helm command line: -[subs="+quotes",options="nowrap",role=white-space-pre] ----- ---set global.tls.serverTrustStoreConfigMapName=ca-certs ----- -==== -endif::[] == On already-running {prod-short} installations @@ -93,7 +75,7 @@ endif::[] * 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/olm-what-operators-are.html[Operator], +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] @@ -101,17 +83,6 @@ retrieve the name of the ConfigMap by reading the `spec.server.ServerTrustStoreC $ {orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath={.spec.server.serverTrustStoreConfigMapName} ---- ==== -ifeval::["{project-context}" == "che"] -+ -==== -On instances of {prod-short} deployed with the {prod-short} link:https://helm.sh/[Helm Chart] deployment, retrieve the name of the ConfigMap by reading the `global.tls.serverTrustStoreConfigMapName` property from the Helm Chart: - -[subs="+quotes",options="nowrap",role=white-space-pre] ----- -$ helm get values che --all --output json | jq -r '.global.tls.serverTrustStoreConfigMapName' ----- -==== -endif::[] + [NOTE] ==== @@ -134,34 +105,16 @@ To apply more than one certificate, add another `--from-file=_"}]' ----- -+ -==== -ifeval::["{project-context}" == "che"] -+ -==== -For a {prod-short} link:https://helm.sh/[Helm Chart] deployment: - -. Clone the https://github.com/eclipse/che[che] project. -. Go to the `deploy/kubernetes/helm/che` directory. -. Update the name of the configMap {prod-short} will use, by editing the `global.tls.serverTrustStoreConfigMapName` Helm Chart property to match the created or updated ConfigMap: -+ -[subs="+quotes,+attributes",options="nowrap",role=white-space-pre] ----- -$ helm upgrade che -n {prod-namespace} --set global.tls.serverTrustStoreConfigMapName= \ - --set global.ingressDomain=____ . +$ {orch-cli} patch checluster/{prod-checluster} -n {prod-namespace} --type=json -p '[{"op": "replace", "path": "/spec/server/serverTrustStoreConfigMapName", "value": ""}]' ---- + -When using Minikube to run {prod-short}, substitute __ with `$(minikube ip).nip.io`. ==== -endif::[] . Restart the {prod-short} Operator, the {prod-short} server and {identity-provider} to load the new certificates: + @@ -188,7 +141,7 @@ and higher. 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/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 : +. 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] ---- @@ -239,16 +192,16 @@ 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 Kubernetes namespace in which it has been created, and wait for it to be started +. 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 with the following command: +. 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 ____ | grep '^workspace.*' ---- -. Get the name of the Theia IDE container in the workspace Pod with the following command: +. Get the name of the Che-Theia IDE container in the workspace Pod: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -256,14 +209,14 @@ $ {orch-cli} get -o json pod ____ -n ____ ---- -. 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 `ca-bundl.crt` entry which is a reserved one: +. 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] ---- @@ -287,7 +240,7 @@ $ {orch-cli} get -o json pod ____ -n {prod-namespace} | \ } ---- -. Confirm that the volume has been mounted into containers, especially in the Theia IDE container: +. 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] ---- @@ -300,7 +253,7 @@ $ {orch-cli} get -o json pod ____ -n __ } ---- -. Inspect `/public-certs` folder on the Theia IDE container and check that its contents match the list of entries in the `ca-certs` ConfigMap: +. 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] ---- diff --git a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc b/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc index 154439fe40..622c022929 100644 --- a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc +++ b/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc @@ -2,19 +2,16 @@ [id="importing-untrusted-tls-certificates_{context}"] = Importing untrusted TLS certificates to {prod-short} -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 using of TLS. -Those communications require the use of TLS certificates signed by trusted Certificate Authorities. +External 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, and {platforms-identity-provider} may require using TLS. 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. +NOTE: 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 Kubernetes 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. +* When the underlying {orch-name} cluster that 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. -{prod-short} uses labeled ConfigMaps in {prod-short} namespace as sources for TLS certificates. -The ConfigMaps can have arbitrary number of keys with arbitrary number of certificates each. +{prod-short} uses labeled ConfigMaps in {orch-namespace} as sources for TLS certificates. The ConfigMaps can have an arbitrary number of keys with a random number of certificates each. [NOTE] ==== @@ -30,19 +27,25 @@ the cluster contains cluster-wide trusted CA certificates added through the link - Based on this annotation, OpenShift automatically injects the cluster-wide trusted CA certificates inside the `ca-bundle.crt` key of ConfigMap ==== +[IMPORTANT] +==== +Some {prod-short} components require to have a full certificate chain to trust the endpoint. +If the cluster is configured with an intermediate certificate, then the whole chain (including self-signed root) should be added to {prod-short}. +==== + == Adding new CA certificates into {prod-short} -This guide can be used before the installations of {prod-short} or when {prod-short} is already installed and running. +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 prior to +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 certiicates. +see xref:importing-untrusted-tls-certificates-old.adoc[this guide] on how to apply additional TLS certificates. ==== .Prerequisites @@ -61,8 +64,7 @@ include::example$snip_importing-untrusted-tls-certificates_1.adoc[] $ {orch-cli} create configmap custom-certs --from-file=____ -n={prod-namespace} ---- + -To apply more than one bundle, add another `--from-file=__` flag to the above command. -Or you may create another ConfigMap. +Add another `-from-file=__` flag to apply more than one bundle. Otherwise, create another ConfigMap. . Label created ConfigMaps with both `app.kubernetes.io/part-of=che.eclipse.org` and `app.kubernetes.io/component=ca-bundle` labels: + @@ -71,63 +73,20 @@ Or you may create another ConfigMap. $ {orch-cli} label configmap custom-certs app.kubernetes.io/part-of=che.eclipse.org app.kubernetes.io/component=ca-bundle -n <{project-context}-namespace-name> ---- -. Deploy {prod-short} if it has not been deployed before otherwise wait until rollout of {prod-short} components finishes. -If there are running workspaces, they should be restarted in order the changes take effect. - -ifeval::["{project-context}" == "che"] - -== Adding CA certificates in case of Helm installer - -For a {prod-short} link:https://helm.sh/[Helm Chart] deployment only one ConfigMap supported. -It is recommended to add the certificates at installation time. - -=== At installation time - -The ConfigMap should be pre-created in the {prod} installation namespace. -Ensure you override the `global.tls.serverTrustStoreConfigMapName` Helm Chart field with the name of the ConfigMap when installing the {prod-short} Helm Chart. For this you should add the following arguments to the Helm command line: -[subs="+quotes",options="nowrap",role=white-space-pre] ----- ---set global.tls.serverTrustStoreConfigMapName=custom-certs ----- - -Or, in case of `{prod-cli}` usage, provide a Helm patch `--helm-patch-yaml` flag that points to an yaml file with: -[subs="+quotes",options="nowrap",role=white-space-pre] ----- -global: - tls: - enabled: true - serverTrustStoreConfigMapName: custom-certs ----- - -=== On already running installations - -Upgrade {prod-short} Helm Chart: - -. Clone the https://github.com/eclipse/che[che] project. -. Go to the `deploy/kubernetes/helm/che` directory. -. Update the name of the configMap {prod-short} will use, by editing the `global.tls.serverTrustStoreConfigMapName` Helm Chart property to match the created or updated ConfigMap: -+ -[subs="+quotes,+attributes",options="nowrap",role=white-space-pre] ----- -$ helm upgrade che -n {prod-namespace} --set global.tls.serverTrustStoreConfigMapName= . ----- -+ -When using Minikube to run {prod-short}, substitute __ with `$(minikube ip).nip.io`. - -endif::[] +. Deploy {prod-short} if it has not been deployed before. Otherwise wait until the rollout of {prod-short} components finishes. If there are running workspaces, they should be restarted for the changes to take effect. == Verification at the {prod-short} installation level -If after adding the certificates something does not work as expected, here is a list of things to verify: +When something does not work as expected after adding the certificates, here is a list of things to verify: -- In case of a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/olm-what-operators-are.html[Operator] deployment, namespace where `CheCluster` located contains labeled ConfigMaps with right content: +- In case of a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/understanding/olm-what-operators-are.html[Operator] deployment, the namespace where the `CheCluster` is located contains labeled ConfigMaps with the right content: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- $ {orch-cli} get cm --selector=app.kubernetes.io/component=ca-bundle,app.kubernetes.io/part-of=che.eclipse.org -n {prod-namespace} ---- + -And to check content of ConfigMap: +Check the content of ConfigMap by running: [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- $ {orch-cli} get cm ____ -n {prod-namespace} -o yaml @@ -148,7 +107,7 @@ $ {orch-cli} get pod -o json __<{prod-id-short}-pod-name>__ -n {prod-namespace} $ {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. +- 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] ---- @@ -160,8 +119,8 @@ $ {orch-cli} logs __<{prod-id-short}-pod-name>__ -n {prod-namespace} [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 - +Your keystore contains 141 entries: ++ (...) ---- + @@ -175,7 +134,7 @@ 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 Kubernetes namespace in which it has been created, and wait for it to be started +- Start a workspace, obtain the {orch-namespace} name in which it has been created, and wait for the workspace to be started. - Get the name of the workspace Pod with the following command: + @@ -184,7 +143,7 @@ SHA1 Fingerprint=3F:DA:BF:E7:A7:A7:90:62:CA:CF:C7:55:0E:1D:7D:05:16:7D:45:60 $ {orch-cli} get pods -o=jsonpath='{.items[0].metadata.name}' -n ____ | grep '^workspace.*' ---- -- Get the name of the Theia IDE container in the workspace Pod with the following command: +- Get the name of the Che-Theia IDE container in the workspace Pod with the following command: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -199,7 +158,7 @@ $ {orch-cli} get -o json pod ____ -n ____ ---- -- Check that the entries in the `ca-certs` ConfigMap contain all the additional entries you added before. In addition it may contain `ca-bundl.crt` entry which is a reserved one: +- Check that the entries in the `ca-certs` ConfigMap contain all the additional entries you added before. In addition, it can contain `ca-bundle.crt` entry which is a reserved one: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -208,7 +167,7 @@ ca-bundle.crt source-config-map-name.data-key.crt ---- -- Make sure that the `ca-certs` ConfigMap has been added as a volume in the workspace Pod: +- Confirm that the `ca-certs` ConfigMap has been added as a volume in the workspace Pod: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -223,7 +182,7 @@ $ {orch-cli} get -o json pod ____ -n __ } ---- -- Confirm that the volume has been mounted into containers, especially in the Theia IDE container: +- Confirm that the volume is mounted into containers, especially in the Che-Theia IDE container: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -236,7 +195,7 @@ $ {orch-cli} get -o json pod ____ -n __ } ---- -- Inspect `/public-certs` folder in the Theia IDE container and check that its contents match the list of entries in the `ca-certs` ConfigMap: +- Inspect the `/public-certs` folder in 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] ---- 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 index b1d7d1ab46..36eec7f71d 100644 --- a/modules/installation-guide/partials/proc_installing-cert-manager-on-kubernetes.adoc +++ b/modules/installation-guide/partials/proc_installing-cert-manager-on-kubernetes.adoc @@ -73,7 +73,7 @@ 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[link="../_images/installation/dns-challenge-gcp.png"] +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): + diff --git a/modules/installation-guide/partials/proc_installing-cert-manager.adoc b/modules/installation-guide/partials/proc_installing-cert-manager.adoc index de640c950b..3d550559f9 100644 --- a/modules/installation-guide/partials/proc_installing-cert-manager.adoc +++ b/modules/installation-guide/partials/proc_installing-cert-manager.adoc @@ -14,22 +14,24 @@ . 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/v0.15.0/cert-manager.yaml + -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/v0.15.0/cert-manager.crds.yaml + --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.3.2/cert-manager.crds.yaml ---- @@ -43,6 +45,7 @@ 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 < + key: CLIENT_SECRET # Azure subscription Id that can be obtained with command: # $ az account show | jq -r '.id' subscriptionID: @@ -78,8 +80,9 @@ spec: EOF ---- -. Create the certificate. Edit the domain name: +. Create the certificate and edit the domain name: + +[source,yaml,subs="+attributes"] ---- cat <__ represents the project of the target installation. +* 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 @@ -53,23 +50,13 @@ $ oc version oc v3.11.0+0cbc58b ---- -. Run the following command to create the {prod-short} instance -+ -** In the {prod-namespace} {orch-namespace}: -+ -[subs="+quotes,+attributes",options="nowrap"] ----- -$ {prod-cli} server:deploy -n {prod-namespace} -p openshift ----- - -** In the default {orch-namespace} called {prod-namespace}: +. 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: diff --git a/modules/installation-guide/partials/proc_installing-che-on-openshift-4-using-the-cli.adoc b/modules/installation-guide/partials/proc_installing-che-on-openshift-4-using-the-cli.adoc index 2b79b013e9..37f1983c0d 100644 --- a/modules/installation-guide/partials/proc_installing-che-on-openshift-4-using-the-cli.adoc +++ b/modules/installation-guide/partials/proc_installing-che-on-openshift-4-using-the-cli.adoc @@ -7,7 +7,7 @@ This section describes how to install {prod-short} on OpenShift 4 with the `{pro * An OpenShift cluster with an administrator account. -* `oc` is available. See link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html#installing-the-cli[Installing the CLI]. `oc` version must match the OpenShift cluster version. +* `oc` is available. See link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. `oc` version must match the OpenShift cluster version. * You have logged in to OpenShift. See link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html#cli-logging-in_cli-developer-commands[Logging in to the CLI]. diff --git a/modules/installation-guide/partials/proc_installing-che-using-storage-classes.adoc b/modules/installation-guide/partials/proc_installing-che-using-storage-classes.adoc index 2cf6ddbd4b..bc447d4cd4 100644 --- a/modules/installation-guide/partials/proc_installing-che-using-storage-classes.adoc +++ b/modules/installation-guide/partials/proc_installing-che-using-storage-classes.adoc @@ -47,7 +47,7 @@ Use the `{prod-cli}` `server:deploy` command with the `--postgres-pvc-storage-cl + [subs="+quotes,+attributes"] ---- -$ {prod-cli} server:deploy -m -p minikube -a operator --postgres-pvc-storage-class-name=postgress-storage +$ {prod-cli} server:deploy -p minikube -a operator --postgres-pvc-storage-class-name=postgress-storage ---- ... Provide the storage class name for the {prod-short} workspaces @@ -56,16 +56,11 @@ Use the `server:deploy` command with the `--workspace-pvc-storage-class-name` fl + [subs="+quotes,+attributes"] ---- -$ {prod-cli} server:deploy -m -p minikube -a operator --workspace-pvc-storage-class-name=workspace-storage +$ {prod-cli} server:deploy -p minikube -a operator --workspace-pvc-storage-class-name=workspace-storage ---- + For {prod-short} workspaces, the storage class name has different behavior depending on the workspace PVC strategy. + -[NOTE] -==== -`postgres-pvc-storage-class-name=postgress-storage` and `workspace-pvc-storage-class-name` work for the Operator installer and the Helm installer. -==== - ** *Define storage class names using a Custom Resources YAML file:* @@ -95,7 +90,7 @@ spec: + [subs="+quotes,+attributes"] ---- -$ {prod-cli} server:deploy -m -p minikube -a operator --che-operator-cr-yaml=/path/to/custom/che/resource/org_v1_che_cr.yaml +$ {prod-cli} server:deploy -p minikube -a operator --che-operator-cr-yaml=/path/to/custom/che/resource/org_v1_che_cr.yaml ---- . Configure {prod-short} to store workspaces in one persistent volume and a PostreSQL database in the second one: @@ -119,7 +114,7 @@ metadata: spec: server: # ... - workspaceNamespaceDefault: 'che' + workspaceNamespaceDefault: __{prod-workspace}__-____ # ... storage: # ... @@ -138,7 +133,7 @@ spec: + [subs="+quotes,+attributes"] ---- -$ {prod-cli} server:deploy -m -p minikube -a operator --che-operator-cr-yaml=/path/to/custom/che/resource/org_v1_che_cr.yaml +$ {prod-cli} server:deploy -p minikube -a operator --che-operator-cr-yaml=/path/to/custom/che/resource/org_v1_che_cr.yaml ---- . Bind static provisioned volumes using class names: 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 index 35a3de9f53..273d016fe4 100644 --- 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 @@ -47,7 +47,7 @@ Operators are a method of packaging, deploying, and managing a {platforms-name} . On the *Install Operator* screen, specify the following options: + * *Installation mode*: *A specific {orch-namespace} on the cluster*. -* *Installed Namespace*: *Pick an existing namespace* -> `{prod-namespace}`. +* *Installed NaAmespace*: *Operator recommended Namespace: Project `openshift-workspaces`* . Click the btn:[Install] button. 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 index 4629193c79..db0a3a85aa 100644 --- 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 @@ -7,19 +7,19 @@ .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. +. 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[link="../_images/installation/creating-dns-zone-on-gcp.png"] +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[link="../_images/installation/cloud-dns-zone-on-gcp.png"] +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[link="../_images/installation/registrar-setup-gcp.png"] +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[link="../_images/installation/dns-settings-gcp.png"] +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-the-che-operator.adoc b/modules/installation-guide/partials/proc_installing-the-che-operator.adoc index e76bc03449..f0c6ea4856 100644 --- a/modules/installation-guide/partials/proc_installing-the-che-operator.adoc +++ b/modules/installation-guide/partials/proc_installing-the-che-operator.adoc @@ -1,38 +1,37 @@ //This module is included in // -// * assembly_installing-che-using-the-che-operator-in-openshift-4-web-console +// assembly_installing-che-on-openshift-4-using-operatorhub [id="installing-the-che-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 also configures all these services. +{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. .Prerequisites -* Access to the Web Console on the cluster. +* Access to the OpenShift web console on the cluster. .Procedure -. To install the {prod} Operator, in the left panel, navigate to the *Operators* -> *OperatorHub* section. +. In the left panel, navigate to the *Operators* -> *OperatorHub* page. -. In the *Filter by keyword* field, type `{prod}` and click the *{prod}* tile. +. In the *Filter by keyword* field, enter `{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 Namespace*: *Pick an existing {orch-namespace} -> `{prod-namespace}` +. On the *Install Operator* page, click the btn:[Install] button. .Verification steps -. To verify the {prod} Operator has installed correctly, in the left panel navigate to the *Operators* -> *Installed Operators* section. +. To verify that the {prod} Operator has installed correctly, in the left panel, navigate to the *Operators* -> *Installed Operators* page. -. In the *Installed Operators* screen, click the *{prod}* name and navigate to the *Details* tab. +. On the *Installed Operators* page, click the *{prod}* name and navigate to the *Details* tab. -. In the *ClusterServiceVersion Details* section at the bottom of the page, wait for these messages: +. In the *ClusterServiceVersion details* section, wait for the following messages: + * *Status*: `Succeeded` -* *Status Reason*: `install strategy completed with no errors` +* *Status reason*: `install strategy completed with no errors` -. Navigate to the *Events* tab and wait for this message: `install strategy completed with no errors`. +. Navigate to the *Events* tab and wait for the following message: `install strategy completed with no errors`. 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 new file mode 100644 index 0000000000..19491e3eab --- /dev/null +++ b/modules/installation-guide/partials/proc_logging-in-to-identity-provider.adoc @@ -0,0 +1,34 @@ +[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_manually-upgrading-che-in-operatorhub.adoc b/modules/installation-guide/partials/proc_manually-upgrading-che-in-operatorhub.adoc new file mode 100644 index 0000000000..e9ff78504f --- /dev/null +++ b/modules/installation-guide/partials/proc_manually-upgrading-che-in-operatorhub.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// upgrading-che-using-operatorhub + +[id="manually-upgrading-che-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. + +.Prerequisites + +* An administrator account on an instance of OpenShift. + +* An instance of {prod-short} {prod-prev-ver} or earlier that was installed by using OperatorHub. + +* The approval strategy in the subscription is `Manual`. + +.Procedure + +. Open the OpenShift web console. + +. Navigate to the *Operators* -> *Installed Operators* page. + +. In the list of the installed Operators, click *{prod}*. + +. Navigate to the *Subscription* tab. + +. Next to the *Upgrade Status*, inspect the upgrades that require approval. The expected message is *1 requires approval*. + +. Click *1 requires approval*. + +. Click *Preview Install Plan*. + +. Review the resources that are available for upgrade and click *Approve*. + +.Verification steps + +. Navigate to the *Operators* -> *Installed Operators* page. + +. Monitor the upgrade progress. When complete, the status changes to *Succeeded* and *Up to date*. The {prod-ver} version number is visible at the end of the page. diff --git a/modules/installation-guide/partials/proc_mounting-a-secret-as-a-file-into-a-container.adoc b/modules/installation-guide/partials/proc_mounting-a-secret-as-a-file-into-a-container.adoc deleted file mode 100644 index 400cb2d6fc..0000000000 --- a/modules/installation-guide/partials/proc_mounting-a-secret-as-a-file-into-a-container.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container - -[id="mounting-a-secret-as-a-file-into-a-container_{context}"] -= Mounting a secret as a file into a {prod} container - - -.Prerequisites - -* A running instance of {prod-short}. To install an instance of {prod-short}, see {link-installing-an-instance}. - - -.Procedure - -. Create a new {platforms-name} secret in the {platforms-name} {orch-namespace} where a {prod-short} is deployed. The labels of the secret that is about to be created must match the set of labels: - -* `app.kubernetes.io/part-of: che.eclipse.org` -* `app.kubernetes.io/component: -secret` - -Where `` is one of the following deployments: `postgres`, `keycloak`, `devfile-registry`, `plugin-registry` or `{prod-deployment}` - -// The following content is downstream friendly - -.Example: - -==== -[source,yaml,subs="+attributes"] ----- -apiVersion: v1 -kind: Secret -metadata: - name: custom-certificate - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: {prod-deployment}-secret -... ----- - - -Annotations must indicate that the given secret is mounted as a file. Set up the annotation values: - -* `che.eclipse.org/mount-as: file` - to indicate that a secret is mounted as a file -* `che.eclipse.org/mount-path: __` - to provide a required mount path - - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: custom-certificate - annotations: - che.eclipse.org/mount-path: /custom-certificates - che.eclipse.org/mount-as: file - labels: -... ----- - - -The {orch-name} secret may contain several items whose names must match the desired file name mounted into the container. - -[source,yaml,subs="+quotes,attributes"] ----- -apiVersion: v1 -kind: Secret -metadata: - name: custom-certificate - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: {prod-deployment}-secret - annotations: - che.eclipse.org/mount-path: /custom-certificates - che.eclipse.org/mount-as: file -data: - ca.crt: ____ ----- - -This results in a file named `ca.crt` being mounted at the `/custom-certificates` path of {prod-short} container. -==== diff --git a/modules/installation-guide/partials/proc_mounting-a-secret-as-an-environment-variable-into-a-container.adoc b/modules/installation-guide/partials/proc_mounting-a-secret-as-an-environment-variable-into-a-container.adoc deleted file mode 100644 index 69619d9880..0000000000 --- a/modules/installation-guide/partials/proc_mounting-a-secret-as-an-environment-variable-into-a-container.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container - -[id="mounting-a-secret-as-an-environment-variable-into-a-container_{context}"] -= Mounting a secret as an environment variable into a {prod} container - -.Prerequisites - -* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. - -.Procedure - -. Create a new {platforms-name} secret in the {platforms-name} {orch-namespace} where a {prod-short} is deployed. The labels of the secret that is about to be created must match the set of labels: - -* `app.kubernetes.io/part-of: che.eclipse.org` -* `app.kubernetes.io/component: -secret` - -Where `` is one of the following deployments: `postgres`, `keycloak`, `devfile-registry`, `plugin-registry` or `{prod-deployment}` - -// The following content is downstream friendly - -.Example: -==== -[source,yaml,subs="+quotes,attributes"] ----- -apiVersion: v1 -kind: Secret -metadata: - name: custom-settings - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: {prod-deployment}-secret -... ----- - - -Annotations must indicate that the given secret is mounted as a environment variable. Set up the annotation values: - -* `che.eclipse.org/mount-as: env` - to indicate that a secret is mounted as an environment variable -* `che.eclipse.org/env-name: __` - to provide an environment variable name, which is required to mount a secret key value - - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: custom-settings - annotations: - che.eclipse.org/env-name: FOO_ENV - che.eclipse.org/mount-as: env - labels: - ... -data: - mykey: myvalue ----- - -This results in the environment variable named `FOO_ENV` and the value `myvalue` being provisioned into a {prod-short} container. - -If the secret provides more than one data item, the environment variable name must be provided for each of the data keys as follows: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: custom-settings - annotations: - che.eclipse.org/mount-as: env - che.eclipse.org/mykey_env-name: FOO_ENV - che.eclipse.org/otherkey_env-name: OTHER_ENV - labels: - ... -data: - mykey: myvalue - otherkey: othervalue ----- - -This results in two environment variables with names `FOO_ENV`, `OTHER_ENV`, and values `myvalue` and `othervalue`, being provisioned into a {prod-short} container. - -NOTE: The maximum length of annotation names in a {orch-name} secret is 63 characters, where 9 characters are reserved for a prefix that ends with `/`. This acts as a restriction for the maximum length of the key that can be used for the secret. - -==== diff --git a/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc b/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc new file mode 100644 index 0000000000..89ee286413 --- /dev/null +++ b/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-a-file-into-a-container.adoc @@ -0,0 +1,93 @@ +// Module included in the following assemblies: +// +// mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container + + +[id="mounting-a-secret-or-a-configmap-as-a-file-into-a-container_{context}"] += Mounting a Secret or a ConfigMap as a file into a {prod-short} container + + +.Prerequisites + +* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. + +.Procedure + +include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[leveloffset=+1] + +Annotations must indicate that the given object is mounted as a file. + +. Configure the annotation values: ++ +* `che.eclipse.org/mount-as: file` - To indicate that a object is mounted as a file. +* `che.eclipse.org/mount-path: __` - To provide a required mount path. + +.Example: +==== +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: custom-data + annotations: + che.eclipse.org/mount-as: file + che.eclipse.org/mount-path: /data + labels: +... +---- +or +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: custom-data + annotations: + che.eclipse.org/mount-as: file + che.eclipse.org/mount-path: /data + labels: +... +---- +==== + +The {orch-name} object may contain several items whose names must match the desired file name mounted into the container. + +.Example: +==== +[source,yaml,subs="+quotes,attributes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: custom-data + labels: + app.kubernetes.io/part-of: che.eclipse.org + app.kubernetes.io/component: {prod-deployment}-secret + annotations: + che.eclipse.org/mount-as: file + che.eclipse.org/mount-path: /data +data: + ca.crt: ____ +---- +or +[source,yaml,subs="+quotes,attributes"] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: custom-data + labels: + app.kubernetes.io/part-of: che.eclipse.org + app.kubernetes.io/component: {prod-deployment}-configmap + annotations: + che.eclipse.org/mount-as: file + che.eclipse.org/mount-path: /data +data: + ca.crt: ____ +---- +==== + +This results in a file named `ca.crt` being mounted at the `/data` path of {prod-short} container. + +IMPORTANT: To make the changes in a {prod-short} container visible, recreate the object entirely. diff --git a/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc b/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc new file mode 100644 index 0000000000..f213493a3a --- /dev/null +++ b/modules/installation-guide/partials/proc_mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container.adoc @@ -0,0 +1,115 @@ +// Module included in the following assemblies: +// +// mounting-a-secret-or-a-configmap-as-a-file-or-an-environment-variable-into-a-container + + +[id="mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container_{context}"] += Mounting a Secret or a ConfigMap as an environment variable into a {prod-short} container + + +.Prerequisites + +* A running instance of {prod}. To install an instance of {prod}, see {link-installing-an-instance}. + +.Procedure + +include::partial$snip_mounting-a-secret-or-a-configmap-into-a-container.adoc[leveloffset=+1] + +Annotations must indicate that the given object is mounted as a environment variable. + +. Configure the annotation values: ++ +* `che.eclipse.org/mount-as: env` - to indicate that a object is mounted as an environment variable +* `che.eclipse.org/env-name: __` - to provide an environment variable name, which is required to mount a object key value + +.Example: +==== +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: custom-settings + annotations: + che.eclipse.org/env-name: FOO_ENV + che.eclipse.org/mount-as: env + labels: + ... +data: + mykey: myvalue +---- +or +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: custom-settings + annotations: + che.eclipse.org/env-name: FOO_ENV + che.eclipse.org/mount-as: env + labels: + ... +data: + mykey: myvalue +---- +==== + +This results in two environment variables: + +* `FOO_ENV` + +* `myvalue` + +being provisioned into a {prod-short} container. + +If the object provides more than one data item, the environment variable name must be provided for each of the data keys as follows: + +.Example: +==== +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: custom-settings + annotations: + che.eclipse.org/mount-as: env + che.eclipse.org/mykey_env-name: FOO_ENV + che.eclipse.org/otherkey_env-name: OTHER_ENV + labels: + ... +data: + mykey: ____ + otherkey: ____ +---- +or +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: custom-settings + annotations: + che.eclipse.org/mount-as: env + che.eclipse.org/mykey_env-name: FOO_ENV + che.eclipse.org/otherkey_env-name: OTHER_ENV + labels: + ... +data: + mykey: ____ + otherkey: ____ +---- +==== + +This results in two environment variables: + +* `FOO_ENV` + +* `OTHER_ENV` + +being provisioned into a {prod-short} container. + +NOTE: The maximum length of annotation names in a {orch-name} object is 63 characters, where 9 characters are reserved for a prefix that ends with `/`. This acts as a restriction for the maximum length of the key that can be used for the object. + +IMPORTANT: To make the changes in a {prod-short} container visible, recreate the object entirely. 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 index e6d9af4b5a..c12d9dfd52 100644 --- a/modules/installation-guide/partials/proc_preparing-azure-for-installing-che.adoc +++ b/modules/installation-guide/partials/proc_preparing-azure-for-installing-che.adoc @@ -7,7 +7,7 @@ .Procedure -To set up the Azure environment for {prod-short}: +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]. + 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 index 7964896dbb..a3d11bf170 100644 --- 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 @@ -1,36 +1,35 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-aws - [id="preparing-the-aws-system-for-installing-che_{context}"] = Preparing the AWS system for installing {prod-short} -The following sections describe how to set up {kubernetes} for {prod} +The following sections describe how to Configure {kubernetes} for {prod} on Amazon Elastic Compute Cloud (Amazon EC2). + .Prerequisites -* A running instance of {kubernetes}, version 1.9 or higher, and Ingress. +* 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 -. Set up 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]. +. 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 at link:http://che.aws.my-ide.cloud[{prod-short} AWS Cloud]. +This document assumes that {prod} must be configured to run on the following domain: ++ +`++http://che.aws.my-ide.cloud++` == Setting up DNS -One way to set up Domain Name System (DNS) is to create the Amazon Route53 to manage the `aws.my-ide.cloud` domain. +One way to Configure Domain Name System (DNS) is to create the Amazon Route53 to manage the `aws.my-ide.cloud` domain. -To set up DNS: +To Configure DNS: . Create the zone on AWS: + @@ -65,9 +64,9 @@ $ aws route53 create-hosted-zone --name aws.my-ide.cloud --caller-reference 1 } ---- -. 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. +. 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[] +image::installation/dns-nameservers.png[DNS name servers] . Create the Simple Storage Service (s3) storage to store the `kops` configuration. + @@ -180,7 +179,7 @@ Run the following command to create the role: $ 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. +. 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"] @@ -197,14 +196,18 @@ $ 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 ---- - -It is now possible to install {prod} on this existing {kubernetes} instance. ++ +The existing {kubernetes} instance is prepare to host an {prod-short} installation. == Enabling the TLS and DNS challenge +pass:[] + 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:[] + . Create a new `permission` file. . Use the following command to obtain the zone ID: + @@ -258,16 +261,16 @@ $ aws route53 list-hosted-zones . In the *EC2 Dashboard*, identify the *IAM role* used by the master node. + -image::installation/aws-lauch-instance.png[link="../_images/installation/aws-lauch-instance.png"] +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[link="../_images/installation/describtion-tab-iam-role.png"] +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[link="../_images/installation/aws-summary-iam-role.png"] +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. + @@ -280,7 +283,7 @@ image::installation/create-policy-review-policy.png[link="../_images/installatio == Installing cert-manager -. To install cert-manager, run the following commands (for details, see link:https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html[Installing Cert on {kubernetes}]): +. 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"] ---- @@ -351,7 +354,7 @@ $ {orch-cli} create secret generic aws-cert-manager-access-key \ . 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[link="../_images/installation/aws-summary-iam-role.png"] +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: + @@ -443,7 +446,7 @@ 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[link="../_images/installation/aws-hosted-zones-dns.png"] +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. diff --git a/modules/installation-guide/partials/proc_running-more-than-one-workspace-at-a-time.adoc b/modules/installation-guide/partials/proc_running-more-than-one-workspace-at-a-time.adoc deleted file mode 100644 index 4649270ca1..0000000000 --- a/modules/installation-guide/partials/proc_running-more-than-one-workspace-at-a-time.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// advanced-configuration - -[id="running-more-than-one-workspace-at-a-time_{context}"] -= Running more than one workspace at a time - -This procedure describes how to run more than one workspace simultaneously. This makes it possible for multiple workspace contexts per user to run in parallel. - -.Prerequisites - -* The `{platforms-cli}` tool is available. -* An instance of {prod-short} running in {platforms-name}. -+ -[NOTE] -==== -The following commands use the default {platforms-namespace}, `{prod-namespace}`, as a user's example for the `-n` option. -==== - -.Procedure - -. Change the default limit of `1` to `-1` to allow an unlimited number of concurrent workspaces per user: - -ifeval::["{project-context}" == "che"] -* For Helm Chart deployments: -+ -[subs="+quotes,+attributes"] ----- -$ helm upgrade che -n {prod-namespace} --set che.limits.userWorkspacesRunCount=-1 ----- -* For Operator deployments: -+ -endif::[] -[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"} } }}' ----- - -. Set the `per-workspace` or `unique` PVC strategy. See xref:configuring-storage-strategies.adoc[]. -+ -[NOTE] -==== -When using the _common PVC_ strategy, configure the persistent volumes to use the `ReadWriteMany` access mode. That way, any of the user's concurrent workspaces can read from and write to the common PVC. -==== 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 index ae88ab7059..855013d69e 100644 --- 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 @@ -1,3 +1,4 @@ +: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 @@ -5,10 +6,17 @@ [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, modify the {identity-provider} settings using the steps below. +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 @@ -27,3 +35,4 @@ image::keycloak/{project-context}-keycloak-username-readonly-theme.png[link="../ . 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 index 9567cc15a6..32810beb1a 100644 --- 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 @@ -5,14 +5,14 @@ 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[] -Changing the machine type configuration of an existing node pool is not possible with Google Cloud Platform. +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. +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[link="../_images/installation/gcp-new-nodepool.png"] +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[link="../_images/installation/gcp-new-nodepool-select-machine-type-standard.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_specifying-the-approval-strategy-of-che-in-operatorhub.adoc b/modules/installation-guide/partials/proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc new file mode 100644 index 0000000000..ec6895da1a --- /dev/null +++ b/modules/installation-guide/partials/proc_specifying-the-approval-strategy-of-che-in-operatorhub.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// upgrading-che-using-operatorhub + +[id="specifying-the-approval-strategy-of-che-in-operatorhub_{context}"] + += Specifying the approval strategy of {prod-short} in OperatorHub + +.Prerequisites + +* An administrator account on an instance of OpenShift. + +* An instance of {prod-short} {prod-prev-ver} or earlier that was installed by using OperatorHub. + +.Procedure + +. Open the OpenShift web console. + +. Navigate to the *Operators* -> *Installed Operators* page. + +. Click *{prod}* in the list of installed Operators. + +. Navigate to the *Subscription* tab. + +. Configure the approval strategy to `Automatic` or `Manual`. ++ +image::installation/specifying-upgrade-strategy.png[Specifying upgrade strategy screenshot] diff --git a/modules/installation-guide/partials/proc_switching-between-external-and-internal-communication.adoc b/modules/installation-guide/partials/proc_switching-between-external-and-internal-communication.adoc deleted file mode 100644 index 0397b7a8e4..0000000000 --- a/modules/installation-guide/partials/proc_switching-between-external-and-internal-communication.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// advanced-configuration - -[id="switching-between-external-and-internal-communication_{context}"] -= Switching between external and internal DNS names in inter-component communication - -By default, new {prod-short} deployments use {orch-name} services DNS names for communications between {prod-short} server, {identity-provider}, registries, and helps with: - -* Bypassing proxy, certificates, and firewalls issues -* Speeding up the traffic - -This type of communication is an alternative to the external method of inter-component communication, which uses {platforms-ingress} cluster host names. In the situations described below, using {orch-name} internal DNS names is not supported. By disabling the use of the internal cluster host name in inter-component communication, the communication using external {platforms-ingress} will come into effect. - -.Internal inter-component communication restrictions in {platforms-name} - -* The {prod-short} components are deployed across multi-cluster {platforms-name} environments. -* The {orch-name} NetworkPolicies restricts communication between namespaces. - -The following section describes how to enable and disable the external inter-component communication for {platforms-ingress}. - - -.Prerequisites - -* The `{orch-cli}` tool is available. -* An instance of {prod-short} running in {platforms-name}. - - -.Procedure - -Switching between external and internal inter-component communication method is reached through the update against Custom Resource (CR). - -ifeval::["{project-context}" == "che"] -* For {prod-short} deployed using Operators -endif::[] -. To use external {platforms-ingress} in inter-component communication: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/server/useInternalClusterSVCNames", "value": false}]' ----- - -. To use internal {orch-name} DNS names in the inter-component communication: -+ -[subs="+quotes,+attributes"] ----- -$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type=json -p \ -'[{"op": "replace", "path": "/spec/server/useInternalClusterSVCNames", "value": true}]' ----- - -ifeval::["{project-context}" == "che"] -* For {prod-short} deployed using a Helm Chart - -. Clone the https://github.com/eclipse/che[che] project -. Go to `deploy/kubernetes/helm/che` directory -. Update the `global.useInternalClusterSVCNames` property. To do that, add the following option to the `helm upgrade` command: -- To use external {platforms-ingress} in inter-component communication: -+ -[subs="+quotes,+attributes"] ----- -$ helm upgrade che -n {prod-namespace} --set global.useInternalClusterSVCNames=false \ --f values/multi-user.yaml -f values/tls.yaml . ----- -- To use internal {orch-name} DNS names in the inter-component communication: -+ -[subs="+quotes,+attributes"] ----- -$ helm upgrade che -n {prod-namespace} --set global.useInternalClusterSVCNames=true \ --f values/multi-user.yaml -f values/tls.yaml . ----- -NOTE: if {prod} has been deployed in single-host mode or without TLS then remove the corresponding flags from the `helm upgrade` command and add others if needed. -endif::[] diff --git a/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc b/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc index c406b37813..ce8e7dcfe2 100644 --- a/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc +++ b/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-cli.adoc @@ -32,36 +32,36 @@ $ oc login -u __ -p __ __ $ 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/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc index 713c0ca352..034103d14e 100644 --- a/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc +++ b/modules/installation-guide/partials/proc_uninstalling-che-after-operatorhub-installation-using-openshift-web-console.adoc @@ -28,7 +28,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/proc_upgrading-che-and-backing-up-user-data.adoc b/modules/installation-guide/partials/proc_upgrading-che-and-backing-up-user-data.adoc new file mode 100644 index 0000000000..bac3d571cd --- /dev/null +++ b/modules/installation-guide/partials/proc_upgrading-che-and-backing-up-user-data.adoc @@ -0,0 +1,18 @@ +// 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 new file mode 100644 index 0000000000..b15b13b788 --- /dev/null +++ b/modules/installation-guide/partials/proc_upgrading-che-and-losing-user-data.adoc @@ -0,0 +1,16 @@ +// 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-operatorhub.adoc b/modules/installation-guide/partials/proc_upgrading-che-using-operatorhub.adoc deleted file mode 100644 index 6db8547829..0000000000 --- a/modules/installation-guide/partials/proc_upgrading-che-using-operatorhub.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// upgrading-{prod-id-short} - -[id="upgrading-{prod-id-short}-using-operatorhub_{context}"] -= Upgrading {prod-short} using OperatorHub - -This section describes how to upgrade from a previous minor version using the Operator from OperatorHub in the OpenShift web console. - -.Prerequisites - -* An administrator account on an OpenShift instance. - -* An instance of a previous minor version of {prod-short}, installed using the Operator from OperatorHub on the same instance of OpenShift. - -.Procedure - -. Open the OpenShift web console. - -. Navigate to the *Operators* -> *Installed Operators* section. - -. Click *{prod}* in the list of the installed Operators. - -. Navigate to the *Subscription* tab and enable the following options: - - * *Channel*: `latest` - * *Approval*: `Automatic` - -.Verification steps - -. Navigate to the {prod-short} instance. - -. The {prod-ver} version number is visible at the bottom of the page. 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 index 50d7f25ba1..a2d3d86f7e 100644 --- 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 @@ -2,7 +2,7 @@ // // upgrading-{prod-id-short} -[id="upgrading-che-using-the-cli-management-tool-in-restricted-environment_{context}"] +[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. diff --git a/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool.adoc b/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool.adoc index a9ec246b7c..46c0e8e18b 100644 --- a/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool.adoc +++ b/modules/installation-guide/partials/proc_upgrading-che-using-the-cli-management-tool.adoc @@ -5,27 +5,36 @@ [id="upgrading-{prod-id-short}-using-the-cli-management-tool_{context}"] = Upgrading {prod-short} using the CLI management tool -This section describes how to upgrade from previous minor version using the CLI management tool. +This section describes how to upgrade from the previous minor version using the CLI management tool. .Prerequisites -* And administrative account on an OpenShift instance. +* An administrative account on {platforms-name}. -* A running instance of a previous minor version of {prod}, installed using the CLI management tool on the same instance of OpenShift, in the `__<{prod-namespace}>__` project. +* A running instance of a previous minor version of {prod}, installed using the CLI management tool on the same instance of {platforms-name}, in the `__<{prod-namespace}>__` project. + +* `{prod-cli}` is available and updated. See xref:using-the-chectl-management-tool.adoc[]. -* An installation of the `{prod-cli}` {prod-ver} version management tool. 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. +. Save and push changes back to the Git repositories for all running {prod-short} {prod-prev-ver} workspaces. . Shut down all workspaces in the {prod-short} {prod-prev-ver} instance. -. Run the following command: +ifeval::["{project-context}" == "che"] +. Update to the latest version of `{prod-cli}`: ++ +---- +$ chectl update +---- +endif::[] + +. Upgrade {prod-short}: + [subs="+attributes,+quotes"] ---- -$ {prod-cli} server:update -n __<{prod-namespace}>__ +$ {prod-cli} server:update -n {prod-namespace} ---- [NOTE] diff --git a/modules/installation-guide/partials/proc_upgrading-the-chectl-management-tool.adoc b/modules/installation-guide/partials/proc_upgrading-the-chectl-management-tool.adoc index 3ddec66527..ab45177871 100644 --- a/modules/installation-guide/partials/proc_upgrading-the-chectl-management-tool.adoc +++ b/modules/installation-guide/partials/proc_upgrading-the-chectl-management-tool.adoc @@ -10,8 +10,8 @@ This section describes how to upgrade the `{prod-cli}` management tool. .Prerequisites * The `{prod-cli}` tool is available. See: -** link:#installing-the-{prod-cli}-management-tool-on-windows_{context}[Installing the {prod-cli} management tool on Windows] -** link:#installing-the-{prod-cli}-management-tool-on-linux-or-macos_{context}[Installing the {prod-cli} management tool on Linux or macOS] +** 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] .Procedure diff --git a/modules/installation-guide/partials/proc_using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc b/modules/installation-guide/partials/proc_using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc new file mode 100644 index 0000000000..9399615b89 --- /dev/null +++ b/modules/installation-guide/partials/proc_using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc @@ -0,0 +1,47 @@ + +[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: + ____: + ____: ____ +---- +==== +* 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 ____ +---- + +.Verification + +. Verify the value of the configured property: ++ +[subs="+attributes,quotes"] +---- +$ oc get configmap che -o jsonpath='{.data.__}' \ +-n {prod-namespace} +---- + +[role="_additional-resources"] +.Additional resources + +* xref:installation-guide:configuring-the-che-installation.adoc[]. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[]. \ No newline at end of file diff --git a/modules/installation-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc b/modules/installation-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc new file mode 100644 index 0000000000..54fda6f94c --- /dev/null +++ b/modules/installation-guide/partials/proc_using-chectl-to-install-che-on-codeready-containers.adoc @@ -0,0 +1,82 @@ +// Module included in the following assemblies: +// +// installing-{prod-id-short}-on-codeready-containers + +[id="using-{prod-cli}-to-install-{prod-id-short}-on-codeready-containers_{context}"] += Using {prod-cli} to install {prod-short} on CodeReady Containers + +This section describes how to install {prod-short} on CodeReady Containers (CRC) using `{prod-cli}`. + +.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]. +* The path to the user's CRC pull secrete is known. + +.Procedure + +. Initiate the CRC platform: + +.. Configure your host machine for CodeReady Containers: ++ +---- +$ crc setup +---- + +.. Remove any previous cluster: ++ +---- +$ crc delete +---- + +.. Initiate the `oc` command line interface within CRC: ++ +---- +$ eval $(crc oc-env) +---- + +.. Start the CodeReady Containers virtual machine with at least 12 GB of RAM and specify the path to your pull secret: ++ +[subs="+quotes"] +---- +$ crc start --memory 12288 --pull-secret-file ____pull-secret.txt +---- + +.. Take note of the password for the user `kubeadmin`, displayed at the end of the CRC initiation. + +. Log into OpenShift cluster using the `kubeadmin` username, the corresponding `____` password, and the CRC URL pointer displayed at the end of the CRC initiation phase: ++ +[subs="+quotes"] +---- +$ oc login --username="kubeadmin" --password="____" https://api.crc.testing:6443 + +---- + +. Install the {prod-short} instance using {prod-cli}: ++ +[subs="+attributes"] +---- +$ {prod-cli} server:deploy --platform crc +---- + +. Use the Users Dashboard CRC testing URL and sign in as: ++ +---- +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}. + + +.Additional resources + +* link:https://access.redhat.com/documentation/en-us/red_hat_codeready_containers/[Product documentation for Red Hat CodeReady Containers]. +* link:https://github.com/code-ready/crc[CodeReady Containers on GitHub]. diff --git a/modules/installation-guide/partials/proc_using-codeready-containers-to-set-up-openshift-4.adoc b/modules/installation-guide/partials/proc_using-codeready-containers-to-set-up-openshift-4.adoc deleted file mode 100644 index 73415f8f2c..0000000000 --- a/modules/installation-guide/partials/proc_using-codeready-containers-to-set-up-openshift-4.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// installing-{prod-id-short}-on-codeready-containers - -[id="using-codeready-containers-to-set-up-openshift-4_{context}"] -= Using CodeReady Containers to set up OpenShift 4 - -This section describes how to use CodeReady Containers to set up OpenShift 4. - -.Prerequisites - -* An installation of CodeReady Containers. See link:https://cloud.redhat.com/openshift/install/crc/installer-provisioned[Installing CodeReady Containers]. - -.Procedure - -. Set up your host machine for CodeReady Containers: -+ ----- -$ crc setup ----- - -. Remove any previous cluster: -+ ----- -$ crc delete ----- - -. Start the CodeReady Containers virtual machine with at least 12 GB of RAM: -+ ----- -$ crc start --memory 12288 ----- - -. When prompted, supply your user pull secret. -. Take note of the password for the user `kubedmin` that is displayed at the end of the installation. -. Access the OpenShift web console: -+ ----- -$ crc console ----- - -. Log in for the first time with the `developer` account (password: `developer`) to initialize the first user using OAuth: -+ ----- -$ oc login --username="developer" --password="developer" ----- - -. Log out: -+ ----- -$ oc logout ----- - -. Log in again with the previously mentioned `kubedmin` user and password: -+ ----- -$ oc login --username="kubeadmin" --password="____" ----- - -. Follow the procedure for xref:installing-che-on-openshift-4-using-operatorhub.adoc[]. - -.Additional resources - -* link:https://access.redhat.com/documentation/en-us/red_hat_codeready_containers/[Product documentation for Red Hat CodeReady Containers]. -* link:https://github.com/code-ready/crc[CodeReady Containers on GitHub]. 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 index 371e9f4444..a7b452f9f6 100644 --- 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 @@ -3,7 +3,7 @@ // installing-{prod-id-short}-with-kubespray [id="using-kubespray-to-set-up-kubernetes_{context}"] -= Set up {kubernetes} using Kubespray += Configuring {kubernetes} using Kubespray Commands are given for bash on Ubuntu. @@ -16,7 +16,7 @@ $ sudo apt-get update $ sudo apt-get upgrade ---- -NOTE: This step is only required on the machine used to run Kubespray. Kubespray will take care of system updates on the cluster nodes. +NOTE: This step is only required on the machine used to run Kubespray. Kubespray will handle system updates on the cluster nodes. .SSH access @@ -30,7 +30,7 @@ $ sudo apt-get install openssh-server * Create SSH key pair + -You have to generate one or multiple SSH key pair(s) to allow Kubespray/Ansible automatic login using SSH. You can use a different key pair for each node or use the same for all nodes. +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//.ssh/id_rsa -q -N "" @@ -38,7 +38,7 @@ $ ssh-keygen -b 2048 -t rsa -f /home//.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. +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. + ---- @@ -52,7 +52,7 @@ You will never be prompted again for password using SSH, the key will be used to .IPv4 forwarding -Kubespray requires to turn on IPv4 forwarding. This should be done automatically by Kubepsray. +Kubespray requires to turn on IPv4 forwarding. This should be done automatically by Kubespray. To do it manually, run the following command: @@ -80,7 +80,7 @@ Start by installing curl. sudo apt-get install curl ---- -Get the latest Kubespray source code from its repo. +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. @@ -98,15 +98,15 @@ 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 environnements (see below). +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 env +* Create a virtual environment + -This is a best isolation pratice using Python to use virtual env (or conda env for conda users). +This is a best isolation practice using Python to use virtual environments (or `conda` environments for `conda` users). + ---- python3 -m venv ~/projects/kubespray-venv @@ -127,7 +127,7 @@ 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! +Be sure you are still in the `~/projects/kubespray/` directory before executing this command! Then customize your new cluster @@ -142,7 +142,7 @@ CONFIG_FILE=inventory/mycluster/hosts.yaml python contrib/inventory_builder/inve + 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 +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 @@ -189,7 +189,7 @@ ansible-playbook -i inventory/mycluster/hosts.yaml --become --become-user=root 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. -If you want to access the cluster API from another computer on your network, install {orch-cli} first. +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 @@ -197,28 +197,29 @@ chmod +x ./kubectl sudo mv ./kubectl /usr/local/bin/kubectl ---- -Then copy the configuration files from the root home directory of a master node: +. Copy the configuration files from the root home directory of a master node: -* On the master node, copy configurations files from root to your useraccount +.. On the master node, copy configurations files from root to your user account: + ---- -ssh @ "sudo cp -R /root/.kube ~ && sudo chown -R : ~/.kube" +$ ssh @ "sudo cp -R /root/.kube ~ && sudo chown -R : ~/.kube" ---- -* Then download the configuration files to a remote computer +. Download the configuration files to a remote computer: + ---- -scp -r @:~/.kube ~ -sudo chown -R : ~/.kube +$ scp -r @:~/.kube ~ +$ sudo chown -R : ~/.kube ---- -* Keep secrets protected on the master node +. Keep secrets protected on the master node: + ---- -ssh @ "rm -r ~/.kube" +$ ssh @ "rm -r ~/.kube" ---- - -For sanity, use autocompletion! ++ +Use autocompletion for the sake of sanity: ++ ---- -echo 'source <(kubectl completion bash)' >>~/.bashrc +$ echo 'source <(kubectl completion bash)' >>~/.bashrc ---- diff --git a/modules/installation-guide/partials/proc_using-minikube-and-lxc.adoc b/modules/installation-guide/partials/proc_using-minikube-and-lxc.adoc index cfc53ba901..39d5db91ec 100644 --- a/modules/installation-guide/partials/proc_using-minikube-and-lxc.adoc +++ b/modules/installation-guide/partials/proc_using-minikube-and-lxc.adoc @@ -5,7 +5,7 @@ [id="using-minikube-with-lxc_{context}"] = Running Minikube inside an LXC container -This section describes how to properly configure an LXC container to set up Minikube when the hypervisor uses ZFS, Btrfs, or LVM to provision the containers storage. +This section describes how to properly configure an LXC container for Minikube when the hypervisor uses ZFS, Btrfs, or LVM to provision the containers storage. [NOTE] ==== @@ -42,7 +42,7 @@ $ parted /dev/mapper/volumegroup_name-dockerstorage --script mklabel gpt $ parted /dev/mapper/volumegroup_name-dockerstorage --script mkpart primary 1 100% #USING LVM ---- + -There is now a reference called: +Observe references called: + * For ZFS: `dockerstorage-part1` inside the `/dev/zvol/zfsPool` directory * For LVM: `volumegroup_name-dockerstorage1` inside the `/dev/mapper` directory diff --git a/modules/installation-guide/partials/proc_using-minikube-to-set-up-kubernetes.adoc b/modules/installation-guide/partials/proc_using-minikube-to-set-up-kubernetes.adoc index f4f618f2e7..504e5ff349 100644 --- a/modules/installation-guide/partials/proc_using-minikube-to-set-up-kubernetes.adoc +++ b/modules/installation-guide/partials/proc_using-minikube-to-set-up-kubernetes.adoc @@ -3,14 +3,14 @@ // installing-{prod-id-short}-on-minikube [id="using-minikube-to-set-up-kubernetes_{context}"] -= Using Minikube to set up {kubernetes} += Using Minikube to configure {kubernetes} -This section describes how to use Minikube to set up a local single-node {kubernetes} cluster. +This section describes how to use Minikube to prepare a local single-node {kubernetes} cluster. .Prerequisites -* An installation of `{orch-cli}`. See link:https://kubernetes.io/docs/tasks/tools/install-kubectl/[Installing and Setting Up {orch-cli} ]. -* An installation of Minikube with {kubernetes} version `1.9` or higher. See link:https://kubernetes.io/docs/tasks/tools/install-minikube/[Installing Minikube]. +* An installation of `{orch-cli}`. See link:https://kubernetes.io/docs/tasks/tools/#kubectl/[Installing and Setting Up {orch-cli} ]. +* An installation of Minikube with {kubernetes} version `{kube-ver-min}` or higher. See link:https://kubernetes.io/docs/tasks/tools/install-minikube/[Installing Minikube]. .Procedure @@ -19,4 +19,3 @@ This section describes how to use Minikube to set up a local single-node {kubern ---- $ minikube start --addons=ingress --vm=true --memory=8192 ---- - 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 index 41e74d4add..3eb812aa18 100644 --- 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 @@ -3,14 +3,14 @@ // installing-{prod-id-short}-on-minishift [id="using-minishift-to-set-up-openshift-3_{context}"] -= Using Minishift to set up OpenShift 3 += Using Minishift to configure OpenShift 3 -This section describes how to use Minishift to set up 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/latest/minishift/command-ref/minishift_oc-env.html[Setting the path of the `oc` tool]. +* 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 diff --git a/modules/installation-guide/partials/proc_using-openshift-web-console-to-install-che-on-codeready-containers.adoc b/modules/installation-guide/partials/proc_using-openshift-web-console-to-install-che-on-codeready-containers.adoc new file mode 100644 index 0000000000..71999468e3 --- /dev/null +++ b/modules/installation-guide/partials/proc_using-openshift-web-console-to-install-che-on-codeready-containers.adoc @@ -0,0 +1,49 @@ +[id="using-openshift-web-console-to-install-{prod-id-short}-on-codeready-containers_{context}"] += Using the OpenShift web console to install {prod-short} on CodeReady Containers + +.Prerequisites + +* An installation of CodeReady Containers. See link:https://cloud.redhat.com/openshift/install/crc/installer-provisioned[Installing CodeReady Containers]. + +.Procedure + +. To configure your host machine for CodeReady Containers, run: ++ +---- +$ crc setup +---- + +. To remove any previous cluster, run: ++ +---- +$ crc delete +---- + +. To start the CodeReady Containers virtual machine with at least 12 GB of RAM, run: ++ +---- +$ crc start --memory 12288 +---- + +. When prompted, supply your user pull secret. + +. Take note of the password for the user `kubeadmin`, which the `crc start --memory 12288` command outputs. + +. To access the OpenShift web console, run: ++ +---- +$ crc console +---- + +. In the web console, log in with the username `developer` and the password `developer`. + +. In the top right corner of the OpenShift web console, click *developer* -> *Log out*. + +. Log in with the `kubeadmin` username and the corresponding password. + +. Follow the procedure for xref:installing-che-on-openshift-4-using-operatorhub.adoc[]. + +.Additional resources + +* link:https://access.redhat.com/documentation/en-us/red_hat_codeready_containers/[Product documentation for Red Hat CodeReady Containers]. +* link:https://github.com/code-ready/crc[CodeReady Containers on GitHub]. diff --git a/modules/installation-guide/partials/proc_using-the-cli-to-configure-the-checluster-custom-resource.adoc b/modules/installation-guide/partials/proc_using-the-cli-to-configure-the-checluster-custom-resource.adoc new file mode 100644 index 0000000000..a0a09b5500 --- /dev/null +++ b/modules/installation-guide/partials/proc_using-the-cli-to-configure-the-checluster-custom-resource.adoc @@ -0,0 +1,36 @@ + +[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.__}' \ +-n {prod-namespace} +---- + +[role="_additional-resources"] +.Additional resources + +* xref:installation-guide:configuring-the-che-installation.adoc[]. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[]. \ No newline at end of file diff --git a/modules/installation-guide/partials/proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc b/modules/installation-guide/partials/proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc new file mode 100644 index 0000000000..5a03861341 --- /dev/null +++ b/modules/installation-guide/partials/proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc @@ -0,0 +1,64 @@ + +[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 installation-guide: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: + ____: + # ... + ____: ____ +---- +==== + +. 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:installation-guide:configuring-the-che-installation.adoc[]. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[]. diff --git a/modules/installation-guide/partials/proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc b/modules/installation-guide/partials/proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc new file mode 100644 index 0000000000..712360f0af --- /dev/null +++ b/modules/installation-guide/partials/proc_using-the-openshift-web-console-to-configure-the-checluster-custom-resource.adoc @@ -0,0 +1,49 @@ + +[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: + ____: + # ... + ____: ____ +---- +==== +. 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:installation-guide:configuring-the-che-installation.adoc[]. + +* xref:advanced-configuration-options-for-the-che-server-component.adoc[]. + diff --git a/modules/installation-guide/partials/ref_checluster-custom-resource-fields-reference.adoc b/modules/installation-guide/partials/ref_checluster-custom-resource-fields-reference.adoc index 1f37cce9d6..5260eb7197 100644 --- a/modules/installation-guide/partials/ref_checluster-custom-resource-fields-reference.adoc +++ b/modules/installation-guide/partials/ref_checluster-custom-resource-fields-reference.adoc @@ -8,12 +8,13 @@ This section describes all fields available to customize the `CheCluster` Custom Resource. * xref:a-minimal-checluster-custom-resource-example_{context}[] -* xref:checluster-custom-resource-auth-settings_{context}[] -* xref:checluster-custom-resource-database-settings_{context}[] * xref:checluster-custom-resource-server-settings_{context}[] +* xref:checluster-custom-resource-database-settings_{context}[] +* xref:checluster-custom-resource-auth-settings_{context}[] * xref:checluster-custom-resource-storage-settings_{context}[] * xref:checluster-custom-resource-k8s-settings_{context}[] -* xref:checluster-custom-resource-installation-settings_{context}[] +* xref:checluster-custom-resource-metrics-settings_{context}[] +* xref:checluster-custom-resource-status-settings_{context}[] [id="a-minimal-checluster-custom-resource-example_{context}"] .A minimal `CheCluster` Custom Resource example. @@ -24,130 +25,4 @@ include::example$checluster-custom-resource.yaml[] ---- ==== - - -[id="checluster-custom-resource-server-settings_{context}"] -.`CheCluster` Custom Resource `server` settings, related to the {prod-short} server component. -[cols="1,1,3", options="header"] -:=== -Property: Default value: Description - -`airGapContainerRegistryHostname`: omit: An optional host name or URL to an alternative container registry to pull images from. This value overrides the container registry host name defined in all default container images involved in a {prod-short} deployment. This is particularly useful to install {prod-short} in an air-gapped environment. -`airGapContainerRegistryOrganization`: omit: Optional repository name of an alternative container registry to pull images from. This value overrides the container registry organization defined in all the default container images involved in a {prod-short} deployment. This is particularly useful to install {prod-short} in an air-gapped environment. -`cheDebug`: `false`: Enables the debug mode for {prod-short} server. -`cheFlavor`: `{prod-id-short}`: Flavor of the installation. -`cheHost`: The Operator automatically sets the value.: A public host name of the installed {prod-short} server. -`cheImagePullPolicy`: `Always` for `nightly` or `latest` images, and `IfNotPresent` in other cases: Overrides the image pull policy used in {prod-short} deployment. -`cheImageTag`: omit: Overrides the tag of the container image used in {prod-short} deployment. Omit it or leave it empty to use the default image tag provided by the Operator. -`cheImage`: omit: Overrides the container image used in {prod-short} 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. -`cheLogLevel`: `INFO`: Log level for the {prod-short} server\: `INFO` or `DEBUG`. -`cheClusterRoles`: `che-namespace-editor`: Comma-separated list of ClusterRoles that will be assigned to che ServiceAccount. Che uses default `che-namespace-editor` ClusterRole to label workspace namespaces. Be aware that che-operator has to already have all permissions in these ClusterRoles to be able to grant them. -`cheWorkspaceClusterRole`: omit: Custom cluster role bound to the user for the {prod-short} workspaces. Omit or leave empty to use the default roles. -`customCheProperties`: omit: Map of additional environment variables that will be applied in the generated `{prod-id-short}` ConfigMap to be used by the {prod-short} server, in addition to the values already generated from other fields of the `CheCluster` Custom Resource (CR). If `customCheProperties` contains a property that would be normally generated in `{prod-id-short}` ConfigMap from other CR fields, then the value defined in the `customCheProperties` will be used instead. -`devfileRegistryImage`: omit: 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. -`devfileRegistryMemoryLimit`: `256Mi`: Overrides the memory limit used in the Devfile registry deployment. -`devfileRegistryMemoryRequest`: `16Mi`: Overrides the memory request used in the Devfile registry deployment. -`devfileRegistryPullPolicy`: `Always` for `nightly` or `latest` images, and `IfNotPresent` in other cases: Overrides the image pull policy used in the Devfile registry deployment. -`devfileRegistryUrl`: The Operator automatically sets the value.: Public URL of the Devfile registry that serves sample, ready-to-use devfiles. Set it if you use an external devfile registry (see the `externalDevfileRegistry` field). -`externalDevfileRegistry`: `false`: Instructs the Operator to deploy a dedicated Devfile registry server. By default a dedicated devfile registry server is started. If `externalDevfileRegistry` set to `true`, the Operator does not start a dedicated registry server automatically and you need to set the `devfileRegistryUrl` field manually. -`externalPluginRegistry`: `false`: Instructs the Operator to deploy a dedicated Plugin registry server. By default, a dedicated plug-in registry server is started. If `externalPluginRegistry` set to `true`, the Operator does not deploy a dedicated server automatically and you need to set the `pluginRegistryUrl` field manually. -`nonProxyHosts`: omit: List of hosts that will not use the configured proxy. Use `|`` as delimiter, for example `localhost|my.host.com|123.42.12.32` Only use when configuring a proxy is required (see also the `proxyURL` field). -`pluginRegistryImage`: omit: 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. -`pluginRegistryMemoryLimit`: `256Mi`: Overrides the memory limit used in the Plugin registry deployment. -`pluginRegistryMemoryRequest`: `16Mi`: Overrides the memory request used in the Plugin registry deployment. -`pluginRegistryPullPolicy`: `Always` for `nightly` or `latest` images, and `IfNotPresent` in other cases: Overrides the image pull policy used in the Plugin registry deployment. -`pluginRegistryUrl`: the Operator sets the value automatically: Public URL of the Plugin registry that serves sample ready-to-use devfiles. Set it only when using an external devfile registry (see the `externalPluginRegistry` field). -`proxyPassword`: omit: Password of the proxy server. Only use when proxy configuration is required. -`proxyPort`: omit: Port of the proxy server. Only use when configuring a proxy is required (see also the `proxyURL` field). -`proxyURL`: omit: URL (protocol+host name) of the proxy server. This drives the appropriate changes in the `JAVA_OPTS` and `https(s)_proxy` variables in the {prod-short} server and workspaces containers. Only use when configuring a proxy is required. -`proxyUser`: omit: User name of the proxy server. Only use when configuring a proxy is required (see also the `proxyURL` field). -`serverMemoryLimit`: `1Gi`: Overrides the memory limit used in the {prod-short} server deployment. -`serverMemoryRequest`: `512Mi`: Overrides the memory request used in the {prod-short} server deployment. -`tlsSupport`: `true`: Instructs the Operator to deploy {prod-short} in TLS mode. -:=== - -[id="checluster-custom-resource-database-settings_{context}"] -.`CheCluster` Custom Resource `database` configuration settings related to the database used by {prod-short} -[cols="1,1,3", options="header"] -:=== -Property: Default value: Description - -`chePostgresDb`: `dbche`: PostgreSQL database name that the {prod-short} server uses to connect to the database. -`chePostgresHostName`: the Operator sets the value automatically: PostgreSQL Database host name that the {prod-short} server uses to connect to. Defaults to `postgres`. Override this value only when using an external database. (See the field `externalDb`.) -`chePostgresPassword`: auto-generated value: PostgreSQL password that the {prod-short} server uses to connect to the database. -`chePostgresPort`: `5432`: PostgreSQL Database port that the {prod-short} server uses to connect to. Override this value only when using an external database (see field `externalDb`). -`chePostgresUser`: `pgche`: PostgreSQL user that the {prod-short} server uses to connect to the database. -`externalDb`: `false`: Instructs the Operator to deploy a dedicated database. By default, a dedicated PostgreSQL database is deployed as part of the {prod-short} installation. If set to `true`, the Operator does not deploy a dedicated database automatically, you need to provide connection details to an external database. See all the fields starting with\: `chePostgres`. -`postgresImagePullPolicy`: Always` for `nightly` or `latest` images, and `IfNotPresent` in other cases: Overrides the image pull policy used in the PostgreSQL database deployment. -`postgresImage`: omit: 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. -:=== - -[id="checluster-custom-resource-auth-settings_{context}"] -.`CheCluster` Custom Resource `auth` configuration settings related to authentication used by {prod-short} installation -[cols="1,1,3", options="header"] -:=== -Property: Default value: Description - -`externalIdentityProvider`: `false`: By default, a dedicated Identity Provider server is deployed as part of the {prod-short} installation. But if `externalIdentityProvider` is `true`, then no dedicated identity provider will be deployed by the Operator and you might need to provide details about the external identity provider you want to use. See also all the other fields starting with\: `identityProvider`. -`identityProviderAdminUserName`:`admin`: Overrides the name of the Identity Provider admin user. -`identityProviderClientId`: omit: Name of an Identity provider ({identity-provider}) `client-id` that must be used for {prod-short}. This is useful to override it ONLY if you use an external Identity Provider (see the `externalIdentityProvider` field). If omitted or left blank, it will be set to the value of the `flavor` field suffixed with `-public`. -`identityProviderImagePullPolicy`: `Always` for `nightly` or `latest` images, and `IfNotPresent` in other cases: Overrides the image pull policy used in the Identity Provider ({identity-provider}) deployment. -`identityProviderImage`: omit: Overrides the container image used in the Identity Provider ({identity-provider}) deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. -`identityProviderPassword`: omit: Overrides the password of {identity-provider} admin user. Override it only when using an external Identity Provider (see the `externalIdentityProvider` field). Omit or leave empty to set an auto-generated password. -`identityProviderPostgresPassword`: the Operator sets the value automatically: Password for The Identity Provider ({identity-provider}) to connect to the database. This is useful to override it ONLY if you use an external Identity Provider (see the `externalIdentityProvider` field). -`identityProviderRealm`: omit: Name of an Identity provider ({identity-provider}) realm. Override it only when using an external Identity Provider (see the `externalIdentityProvider` field). Omit or leave empty blank to set it to the value of the `flavor` field. -`identityProviderURL`: the Operator sets the value automatically: Instructs the Operator to deploy a dedicated Identity Provider ({identity-provider} instance). Public URL of the Identity Provider server ({identity-provider} server). Set it only when using an external Identity Provider (see the `externalIdentityProvider` field). -`oAuthClientName`: the Operator sets the value automatically: Name of the OpenShift `OAuthClient` resource used to setup identity federation on the OpenShift side. See also the `OpenShiftoAuth` field. -`oAuthSecret`: the Operator sets the value automatically: Name of the secret set in the OpenShift `OAuthClient` resource used to setup identity federation on the OpenShift side. See also the `OAuthClientName` field. -`openShiftoAuth`: `true` on OpenShift: Enables the integration of the identity provider ({identity-provider} / RHSSO) with OpenShift OAuth. This allows users to log in with their OpenShift login and have their workspaces created under personal OpenShift {orch-namespace}s. The `kubeadmin` user is not supported, and logging through does not allow access to the {prod-short} Dashboard. -`updateAdminPassword`: `false`: Forces the default `admin` {prod-short} user to update password on first login. -:=== - -[id="checluster-custom-resource-storage-settings_{context}"] -.`CheCluster` Custom Resource `storage` configuration settings related to persistent storage used by {prod-short} -[cols="1,1,3", options="header"] -:=== -Property: Default value: Description - -`postgresPVCStorageClassName`: omit: Storage class for the Persistent Volume Claim dedicated to the PostgreSQL database. Omitted or leave empty to use a default storage class. -`preCreateSubPaths`: `false`: Instructs the {prod-short} server to launch a special Pod to pre-create a subpath in the Persistent Volumes. Enable it according to the configuration of your K8S cluster. -`pvcClaimSize`: `1Gi`: Size of the persistent volume claim for workspaces. -`pvcJobsImage`: omit: Overrides the container image used to create sub-paths in the Persistent Volumes. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. See also the `preCreateSubPaths` field. -`pvcStrategy`: `common`: Available options\:`common` (all workspaces PVCs in one volume), `per-workspace` (one PVC per workspace for all declared volumes) and `unique` (one PVC per declared volume). -`workspacePVCStorageClassName`: omit: Storage class for the Persistent Volume Claims dedicated to the {prod-short} workspaces. Omit or leave empty to use a default storage class. -:=== - - -[id="checluster-custom-resource-k8s-settings_{context}"] -.`CheCluster` Custom Resource `k8s` configuration settings specific to {prod-short} installations on {platforms-name} -[cols="1,1,3", options="header"] -:=== -Property: Default value: Description - -`ingressClass`: `nginx`: Ingress class that defines which controller manages ingresses. -`ingressDomain`: omit: Global ingress domain for a K8S cluster. This field must be explicitly specified. This drives the `is kubernetes.io/ingress.class` annotation on {prod-short}-related ingresses. -`ingressStrategy`: `multi-host`: Strategy for ingress creation. This can be `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). -`securityContextFsGroup,omitempty`: `1724`: FSGroup the {prod-short} Pod and Workspace Pods containers run in. -`securityContextRunAsUser`: `1724`: ID of the user the {prod-short} Pod and Workspace Pods containers run as. -`tlsSecretName`: che-tls: Name of a secret that is used to set ingress TLS termination if TLS is enabled. If the specified secret does not exist, a self-signed certificate will be created. If the value is empty or omitted, the default ingress controller certificate will be used. See also the `tlsSupport` field. Note, when switching to the default ingress controller certificate, `self-signed-certificate` secret should be deleted manually. -:=== - -[id="checluster-custom-resource-installation-settings_{context}"] -.`CheCluster` Custom Resource `status` defines the observed state of {prod-short} installation -[cols="1,3", options="header"] -:=== -Property: Description - -`cheClusterRunning`: Status of a {prod-short} installation. Can be `Available`, `Unavailable`, or `Available, Rolling Update in Progress`. -`cheURL`: Public URL to the {prod-short} server. -`cheVersion`: Currently installed {prod-short} version. -`dbProvisioned`: Indicates whether a PostgreSQL instance has been correctly provisioned. -`devfileRegistryURL`: Public URL to the Devfile registry. -`helpLink`: A URL to where to find help related to the current Operator status. -`keycloakProvisioned`: Indicates whether an Identity Provider instance ({identity-provider} / RH SSO) has been provisioned with realm, client and user. -`keycloakURL`: Public URL to the Identity Provider server ({identity-provider} / RH SSO). -`message`: A human-readable message with details about why the Pod is in this state. -`openShiftoAuthProvisioned`: Indicates whether an Identity Provider instance ({identity-provider} / RH SSO) has been configured to integrate with the OpenShift OAuth. -`pluginRegistryURL`: Public URL to the Plugin registry. -`reason`: A brief CamelCase message with details about why the Pod is in this state. -:=== +include::example$checluster-properties.adoc[leveloffset=+1] diff --git a/modules/installation-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc b/modules/installation-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc new file mode 100644 index 0000000000..ca05ad377a --- /dev/null +++ b/modules/installation-guide/partials/snip_mounting-a-secret-or-a-configmap-into-a-container.adoc @@ -0,0 +1,57 @@ +// Module included in the following procedures: +// +// mounting-a-secret-or-a-configmap-as-an-environment-variable-into-a-container +// mounting-a-secret-or-a-configmap-as-a-file-into-a-container + + +. Create a new {platforms-name} Secret or a ConfigMap in the {platforms-name} {orch-namespace} where a {prod-short} is deployed. The labels of the object that is about to be created must match the set of labels: ++ +* `app.kubernetes.io/part-of: che.eclipse.org` +* `app.kubernetes.io/component: -` ++ +* The `` corresponds to the one following deployments: + +** `postgres` +** `keycloak` +** `devfile-registry` +** `plugin-registry` +** `{prod-deployment}` ++ +and ++ +* `` is either: ++ +** `secret` ++ +or ++ +** `configmap` + +// The following content is downstream friendly + +.Example: +==== +[source,yaml,subs="+quotes,attributes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: custom-settings + labels: + app.kubernetes.io/part-of: che.eclipse.org + app.kubernetes.io/component: {prod-deployment}-secret +... +---- +or +[source,yaml,subs="+quotes,attributes"] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: custom-settings + labels: + app.kubernetes.io/part-of: che.eclipse.org + app.kubernetes.io/component: {prod-deployment}-configmap +... +---- +==== \ No newline at end of file diff --git a/modules/overview/nav.adoc b/modules/overview/nav.adoc index 16c1a3d75c..2aa7ab5dae 100644 --- a/modules/overview/nav.adoc +++ b/modules/overview/nav.adoc @@ -1,2 +1,2 @@ * xref:introduction-to-eclipse-che.adoc[] -** xref:che-architecture.adoc[] +** xref:architecture-overview.adoc[] diff --git a/modules/overview/pages/architecture-overview.adoc b/modules/overview/pages/architecture-overview.adoc new file mode 100644 index 0000000000..aed9d3ad22 --- /dev/null +++ b/modules/overview/pages/architecture-overview.adoc @@ -0,0 +1,7 @@ +[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/che-architecture.adoc b/modules/overview/pages/che-architecture.adoc deleted file mode 100644 index 953f53eeaa..0000000000 --- a/modules/overview/pages/che-architecture.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="{prod-id-short}-architecture"] -// = {prod-short} architectural elements -:navtitle: {prod-short} architecture -:keywords: overview, che-architecture, che-architectural-elements -:page-aliases: .:che-architecture - -include::administration-guide:partial$con_che-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 1943f269e0..c4441ce6c0 100644 --- a/modules/overview/partials/assembly_introduction-to-eclipse-che.adoc +++ b/modules/overview/partials/assembly_introduction-to-eclipse-che.adoc @@ -8,18 +8,18 @@ :context: introduction-to-eclipse-che * A centralized developer environment running on {platforms-name}. -* A multicontainer workspace for each developer with the ability to replicate with a single click using {prod} factories. +* A multi-container workspace for each developer with the ability to replicate with a single click using {prod} factories. * Pre-built stacks with the ability to create custom stacks for any language or runtime. -* An enterprise integration that uses {identity-provider} for Active Directory (AD) database and Lightweight Directory Access Protocol (LDAP) related actions. +* An enterprise integration using {identity-provider} for Active Directory (AD) database and Lightweight Directory Access Protocol (LDAP) related actions. * Browser-based IDEs; integration with Che-Theia or any other web IDE, such as Jupyter. -* Support of tooling protocols, such as the Language Server Protocol or Debug Adapter Protocol. +* Support of tools protocols, such as the Language Server Protocol or Debug Adapter Protocol. * A plug-in mechanism compatible with Visual Studio Code extensions. * A software development kit (SDK) for creating custom cloud developer platforms. [id="getting-started-with-{prod-id-short}_{context}"] == Getting started with {prod-short} -* xref:what-is-{prod-id-short}_{context}[]. +* xref:what-is-{prod-id-short}_{context}[] * xref:che-architecture.adoc[] * xref:hosted-che.adoc[] * xref:installation-guide:running-che-locally.adoc[] @@ -48,11 +48,11 @@ 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:: -Join us in our link:https://github.com/eclipse/che/wiki/{prod-short}-Dev-Meetings[{prod-short} community meeting] every Monday. +Join us in the link:https://github.com/eclipse/che/wiki/{prod-short}-Dev-Meetings[{prod-short} community meeting] every Monday. Roadmap:: @@ -82,7 +82,7 @@ To achieve those core goals, {prod} provides: Workspaces are isolated from one another and are responsible for managing the lifecycle of their components. -Developers using {prod} use their containers directly in their developer workspaces. *{prod-short} workspaces are {platforms-name} pods, which allow to replicate the application runtimes (and its microservices) used in production* and provide a “dev mode” layer on top of those, adding intelligent code completion and IDE tools. +Developers using {prod} use their containers directly in their developer workspaces. *{prod-short} workspaces are {platforms-name} Pods, which allow to replicate the application runtimes (and its microservices) used in production* and provide a “developer mode” layer on top of those, adding intelligent code completion and IDE tools. === Browser-based IDEs @@ -94,7 +94,7 @@ Developers using {prod} use their containers directly in their developer workspa * *Command palette:* Do everything from your keyboard * *Task support:* Tasks from Visual Studio Code are extended and support {prod-short} commands * *Embedded preview:* Preview your application directly from the IDE, including Markdown preview -* *Customizable layout:* Adapt the layout using drag and drop +* *Customizable layout:* Adapt the layout using drag-and-drop * *And more:* Outline view, search, Git @@ -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 instead of an IDE. +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. === Extensible platform @@ -122,10 +122,10 @@ For situations in which the default IDE does not cover the use cases of the user * *Plug-ins* to add capabilities to the IDE. Che-Theia plug-ins rely on APIs compatible with Visual Studio Code. Plug-ins are isolated and provide their own dependencies packaged in containers. * *Stacks* to create pre-configured {prod-short} workspaces with a dedicated set of tools. -* *Alternative IDEs* to provide specialized tools within {prod}. Build your own, based on Eclipse Theia, or pick existing ones like Jupyter. +* *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 tooling 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. @@ -145,10 +145,6 @@ video::HbTKDlOL1eo[youtube] .Additional resources -* xref:administration-guide:che-architecture-overview.adoc[] - -* xref:administration-guide:che-workspace-controller.adoc[] - -* xref:administration-guide:che-workspaces-architecture.adoc[] +* xref:architecture-overview.adoc[] :context: {parent-context-of-introduction-to-eclipse-che} diff --git a/package.json b/package.json index 0d208af087..74b7dfa4d5 100644 --- a/package.json +++ b/package.json @@ -1,16 +1,8 @@ { - "name": "che-docs", - "description": "Documentation builder for Eclipse Che", - "license": "EPL-2.0", - "repository": "git@github.com:eclipse/che-docs.git", - "version": "1.0.0-SNAPSHOT", "dependencies": { - "@antora/cli": "^2.3.4", "@antora/site-generator-default": "^2.3.4", - "asciidoctor": "^2.2.1", "gulp": "^4.0.2", "gulp-cli": "^2.3.0", - "gulp-connect": "^5.7.0", - "http-server": "^0.12.3" + "gulp-connect": "^5.7.0" } } diff --git a/supplemental-ui/css/extra.css b/supplemental-ui/css/extra.css index 8edc743b43..a566ac0bfe 100644 --- a/supplemental-ui/css/extra.css +++ b/supplemental-ui/css/extra.css @@ -73,3 +73,7 @@ i.fa.icon-caution::before { padding: 0!important; border: none!important; } + +aside.toc.sidebar { + overflow-block: scroll; +} diff --git a/supplemental-ui/partials/header-content.hbs b/supplemental-ui/partials/header-content.hbs index e32fe8147e..3739aad4a4 100644 --- a/supplemental-ui/partials/header-content.hbs +++ b/supplemental-ui/partials/header-content.hbs @@ -8,7 +8,7 @@ - Eclipse Che Documentation + {{site.title}} - Home - Blog + Home + Blog Source Code -
- +
+ \ No newline at end of file diff --git a/tools/che-icon.png b/tools/che-icon.png new file mode 100644 index 0000000000..7bbe1cce40 Binary files /dev/null and b/tools/che-icon.png differ diff --git a/tools/checluster_docs_gen.sh b/tools/checluster_docs_gen.sh new file mode 100755 index 0000000000..d7f1fd8ec4 --- /dev/null +++ b/tools/checluster_docs_gen.sh @@ -0,0 +1,116 @@ +#!/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 +# +set -o pipefail +set -e + +CURRENT_VERSION="" +PRODUCT="" +RAW_CONTENT="" +NEWLINE=$'\n' +NEWLINEx2="$NEWLINE$NEWLINE" +TABLE_HEADER="$NEWLINE[cols=\"2,5\", options=\"header\"]$NEWLINE:=== $NEWLINE Property: Description $NEWLINE" +TABLE_FOOTER=":=== $NEWLINEx2" +PARENT_PATH=$(cd "$(dirname "${BASH_SOURCE[0]}")/.."; pwd -P) +BUFF="" +OUTPUT_PATH="$PARENT_PATH/modules/installation-guide/examples/checluster-properties.adoc" + +fetch_current_version() { + 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" + fi + echo "Detected version: $CURRENT_VERSION" >&2 +} + +fetch_product_name() { + 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 + + 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" + else + CHECLUSTER_PROPERTIES_URL="https://raw.githubusercontent.com/redhat-developer/codeready-workspaces-operator/$CURRENT_VERSION/config/crd/bases/org_v1_che_crd.yaml" + fi + + RAW_CONTENT=$(curl -sf "$CHECLUSTER_PROPERTIES_URL") + local crdVersion=$(echo "$RAW_CONTENT" | yq -r '.apiVersion') + echo "Fetching content done. CRD version: $crdVersion. Trying to parse it." >&2 +} + +parse_content() { + parse_section "server" "\`CheCluster\` Custom Resource \`server\` settings, related to the {prod-short} server component." + parse_section "database" "\`CheCluster\` Custom Resource \`database\` configuration settings related to the database used by {prod-short}." + parse_section "auth" "Custom Resource \`auth\` configuration settings related to authentication used by {prod-short}." + parse_section "storage" "\`CheCluster\` Custom Resource \`storage\` configuration settings related to persistent storage used by {prod-short}." + if [[ $PRODUCT == "che" ]]; then + parse_section "k8s" "\`CheCluster\` Custom Resource \`k8s\` configuration settings specific to {prod-short} installations on {platforms-name}." + fi + parse_section "metrics" "\`CheCluster\` Custom Resource \`metrics\` settings, related to the {prod-short} metrics collection used by {prod-short}." + parse_section "status" "\`CheCluster\` Custom Resource \`status\` defines the observed state of {prod-short} installation" + BUFF="pass:[] + +$BUFF" + echo "$BUFF" > "$OUTPUT_PATH" + echo "Processing done. Output file is $OUTPUT_PATH" >&2 +} + + +parse_section() { + local section + local sectionName=$1 + local id="[id=\"checluster-custom-resource-$sectionName-settings_{context}\"]" + local caption=$2 + local crdVersion=$(echo "$RAW_CONTENT" | yq -r '.apiVersion') + echo "Parsing section: "$sectionName + + if [[ $sectionName == "status" ]]; then + if [[ $crdVersion == "apiextensions.k8s.io/v1beta1" ]]; then + section=$(echo "$RAW_CONTENT" | yq -M '.spec.validation.openAPIV3Schema.properties.status') + else + section=$(echo "$RAW_CONTENT" | yq -M '.spec.versions[] | select(.name == "v1") | .schema.openAPIV3Schema.properties.status') + fi + else + if [[ $crdVersion == "apiextensions.k8s.io/v1beta1" ]]; then + section=$(echo "$RAW_CONTENT" | yq -M '.spec.validation.openAPIV3Schema.properties.spec.properties.'"$sectionName") + else + section=$(echo "$RAW_CONTENT" | yq -M '.spec.versions[] | select(.name == "v1") | .schema.openAPIV3Schema.properties.spec.properties.'"$sectionName") + fi + fi + + local properties=( + $(echo "$section" | yq -M '.properties | keys[]' ) + ) + + BUFF="$BUFF$id$NEWLINE" + BUFF="$BUFF.$caption$NEWLINE" + BUFF="$BUFF$TABLE_HEADER" + for PROP in "${properties[@]}" + do + PROP="${PROP//\"}" + DESCR_BUFF=$(echo "$section" | yq -M '.properties.'"$PROP"'.description') + DESCR_BUFF="${DESCR_BUFF//\"}" + DESCR_BUFF="${DESCR_BUFF//:/\\:}" + DESCR_BUFF="$(sed 's|Eclipse Che|{prod-short}|g' <<< $DESCR_BUFF)" + BUFF="$BUFF${PROP}: ${DESCR_BUFF}$NEWLINE" + done + BUFF="$BUFF$TABLE_FOOTER" +} + +fetch_current_version +fetch_product_name +fetch_conf_files_content +parse_content diff --git a/tools/count_vale_errors.sh b/tools/count_vale_errors.sh new file mode 100755 index 0000000000..cddacc6612 --- /dev/null +++ b/tools/count_vale_errors.sh @@ -0,0 +1,24 @@ +#!/bin/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 +# +set -e + +vale -v + +echo "= Breakdown of vale infringements per module" +for module in modules/* + do + printf "== %s\n" "$module" + report=".cache/vale-report-${module#modules/}.json" + vale --minAlertLevel=suggestion --output=JSON --no-exit "$module" > "$report" + printf "=== Severity\n" + jq .[][].Severity "$report" | sort | uniq -c | sort -nr + printf "=== Check\n" + jq .[][].Check "$report" | sort | uniq -c | sort -nr +done diff --git a/tools/create_architecture_diagrams.py b/tools/create_architecture_diagrams.py new file mode 100755 index 0000000000..53862106e9 --- /dev/null +++ b/tools/create_architecture_diagrams.py @@ -0,0 +1,185 @@ +#!/bin/env python +# +# 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 +# + +from diagrams import * +import diagrams +from diagrams.custom import Custom +from diagrams.k8s.controlplane import APIServer +from diagrams.k8s.rbac import User +from diagrams.onprem.database import PostgreSQL +from diagrams.onprem.network import Traefik +from diagrams.onprem.vcs import Git +from diagrams.outscale.compute import Compute +from diagrams.outscale.storage import SimpleStorageService +import os + + +def ArchitectureDiagrams(prod_short, project_context, orch_name): + script_path = os.path.dirname(os.path.realpath(__file__)) + file_path = script_path + \ + '/../modules/administration-guide/images/architecture/' + project_context + '-' + prod_icon = script_path + '/' + project_context + '-icon.png' + graph_attr = { + "bgcolor": "white", + "layout": "dot", + "overlap": "false", + # "splines": "curved" + } + + filename = file_path + 'architecture-with-che-server-engine' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + edge_attr={"constraint": "false"}, + graph_attr=graph_attr): + devfile = Git('Devfile v1') + dashboard = Custom('User dashboard', prod_icon) + che_host = Custom(prod_short + ' server', prod_icon) + with Cluster(orch_name + ' API'): + workspace = Compute('User workspace') + devfile >> dashboard >> che_host >> workspace + + filename = file_path + 'interacting-with-devworkspace' + with Diagram(filename=filename, + show=False, + direction="LR", + outformat="png", + graph_attr=graph_attr): + devfile = Git('Devfile v2') + dashboard = Custom('User dashboard', prod_icon) + with Cluster(orch_name + ' API'): + devworkspace_operator = Compute('DevWorkspace') + workspace = Compute('User workspace') + devfile >> dashboard >> devworkspace_operator >> workspace + + filename = file_path + 'deployments-interacting-with-devworkspace' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + graph_attr=graph_attr + ): + che_dashboard = Custom('User dashboard', icon_path=prod_icon) + che_gateway = Traefik('Gateway') + devfile_registries = SimpleStorageService('Devfile registries') + che_host = Custom(prod_short + ' server', icon_path=prod_icon) + git = Git('Git provider') + postgres = PostgreSQL('PostgreSQL') + plugin_registry = SimpleStorageService('Plug-in registry') + kubernetes_api = APIServer(orch_name + ' API') + user = User('User browser') + user >> che_gateway + che_gateway >> [che_dashboard, devfile_registries, che_host, + plugin_registry, kubernetes_api] + che_host >> [postgres, git] + + filename = file_path + 'gateway-interactions' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + graph_attr=graph_attr): + user = User('User') + che_gateway = Traefik('Gateway') + che_dashboard = Custom('User dashboard', icon_path=prod_icon) + devfile_registries = SimpleStorageService('Devfile registry') + che_host = Custom(prod_short + ' server', icon_path=prod_icon) + plugin_registry = SimpleStorageService('Plug-in registry') + user_workspace = Compute('User workspaces') + user >> che_gateway >> [ + che_dashboard, che_host, devfile_registries, plugin_registry, user_workspace] + + filename = file_path + 'dashboard-interactions' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + graph_attr=graph_attr): + che_dashboard = Custom('User dashboard', icon_path=prod_icon) + devfile_registry = SimpleStorageService('Devfile registries') + che_host = Custom(prod_short + ' server', icon_path=prod_icon) + plugin_registry = SimpleStorageService('Plug-in registry') + crd_workspace = APIServer(orch_name + ' API') + che_dashboard >> che_host, + che_dashboard >> [ + devfile_registry, plugin_registry] + che_dashboard >> crd_workspace + + filename = file_path + 'server-interactions' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + graph_attr=graph_attr): + che_host = Custom(prod_short + ' server', icon_path=prod_icon) + postgres = PostgreSQL('PostgreSQL') + git_provider = Git('Git provider') + crd_workspace = APIServer('API') + che_dashboard = Custom('User dashboard', icon_path=prod_icon) + che_dashboard >> che_host + che_host >> [git_provider] + che_host >> crd_workspace + che_host >> postgres + + filename = file_path + 'postgresql-interactions' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + graph_attr=graph_attr): + che_host = Custom(prod_short + ' server', icon_path=prod_icon) + postgres = PostgreSQL('PostgreSQL') + che_host >> postgres + + filename = file_path + 'devfile-registry-interactions' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + graph_attr=graph_attr): + che_dashboard = Custom('User dashboard', icon_path=prod_icon) + devfile_registry = SimpleStorageService('Devfile registries') + che_dashboard >> devfile_registry + + filename = file_path + 'plugin-registry-interactions' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + graph_attr=graph_attr): + che_dashboard = Custom('User dashboard', icon_path=prod_icon) + plugin_registry = SimpleStorageService('Plug-in registry') + che_dashboard >> plugin_registry + + filename = file_path + 'user-workspaces-interactions' + with Diagram(filename=filename, + show=False, + direction="TB", + outformat="png", + graph_attr=graph_attr): + che_gateway = Traefik('Gateway') + git = Git('Git provider') + container_registries = SimpleStorageService('Container registries') + artifact_management = SimpleStorageService('Dependency provider') + + user = User('User') + user_workspace = Compute('User workspaces') + user >> che_gateway >> user_workspace + user_workspace >> [git, container_registries, artifact_management] + + +ArchitectureDiagrams(project_context='che', + prod_short='Che', + orch_name='Kubernetes') + +ArchitectureDiagrams(project_context='crw', + prod_short='CodeReady Workspaces', + orch_name='OpenShift') diff --git a/tools/detect-unused-images.sh b/tools/detect-unused-images.sh index e733fab3b4..e550e5e91e 100755 --- a/tools/detect-unused-images.sh +++ b/tools/detect-unused-images.sh @@ -1,4 +1,12 @@ #!/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 diff --git a/tools/environment_docs_gen.sh b/tools/environment_docs_gen.sh index c5fc4a46ef..760158ad8e 100755 --- a/tools/environment_docs_gen.sh +++ b/tools/environment_docs_gen.sh @@ -13,18 +13,18 @@ CURRENT_VERSION="" RAW_CONTENT="" NEWLINE=$'\n' NEWLINEx2="$NEWLINE$NEWLINE" -TABLE_HEADER="$NEWLINE,=== $NEWLINE Environment Variable Name,Default value, Description $NEWLINE" -TABLE_FOOTER=",=== $NEWLINEx2" +# TABLE_HEADER="$NEWLINE,=== $NEWLINE Environment Variable Name,Default value, Description $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" fetch_current_version() { - echo "Trying to read current product version from $PARENT_PATH/antora-playbook.yml..." >&2 - - CURRENT_VERSION=$(grep 'prod-ver:' "$PARENT_PATH/antora-playbook.yml" | cut -d: -f2 | sed 's/ //g').x + 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-playbook.yml" >&2 + echo "Failure: Cannot read version from $PARENT_PATH/antora.yml" >&2 exit 1 fi if [[ "$CURRENT_VERSION" == *-SNAPSHOT ]]; then @@ -36,13 +36,13 @@ fetch_current_version() { fetch_conf_files_content() { echo "Fetching property files content from GitHub..." >&2 - CHE_PROPERTIES_URL="https://raw.githubusercontent.com/eclipse/che/$CURRENT_VERSION/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che/che.properties" + 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 echo "Failure: Cannot read che.properties from URL $CHE_PROPERTIES_URL" >&2 exit 1 fi - MULTIUSER_PROPERTIES_URL="https://raw.githubusercontent.com/eclipse/che/$CURRENT_VERSION/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che/multiuser.properties" + MULTIUSER_PROPERTIES_URL="https://raw.githubusercontent.com/eclipse-che/che-server/$CURRENT_VERSION/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che/multiuser.properties" RAW_CONTENT="$RAW_CONTENT $(curl -sf "$MULTIUSER_PROPERTIES_URL")" if [ $? -ne 0 ]; then echo "Failure: Cannot read multiuser.properties from URL $MULTIUSER_PROPERTIES_URL" >&2 @@ -61,12 +61,13 @@ parse_content() { TOPIC="${LINE//#}" # read topic, stripping #s TOPIC="${TOPIC/ }" # trim first space TOPICID="${TOPIC// /-}" # create topic ID - TOPICID="$(sed 's|-\{2,\}|-|g; s|[\"\/=,.<>?!;:()*]||g; s|\(.*\)|[id="\L\1"]|' <<< $TOPICID)" + TOPICID="$(sed 's|-\{2,\}|-|g; s|[\"\/=,.<>?!;:()*]||g; s|\(.*\)|[id="\1"]|;s|prod-short|prod-id-short|' <<< $TOPICID)" # 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 - BUFF="${BUFF}${TOPICID}$NEWLINE= ${TOPIC}$NEWLINEx2.${TOPIC} $TABLE_HEADER $NEWLINE" # new topic and table header - elif [[ $LINE == '#'* ]] && [[ -n $TOPIC ]]; then # line starting with single # means property description (can be multi-line) + 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 # DESCR_BUFF="$DESCR_BUFF${TRIM_LINE}" # collect all description lines into buffer elif [[ -z $LINE ]] && [[ -n $TOPIC ]]; then @@ -80,7 +81,7 @@ parse_content() { ENV=${ENV//./_} # replace dots with single underscore VALUE="${VALUE/ }" # trim first space VALUE="\`+${VALUE}+\`" # make sure asciidoc doesn't mix it up with attributes - VALUE="${VALUE/\`++\`}" # remove empty value `++` + VALUE="${VALUE/\`++\`/empty}" # remove empty value `++` DESCR_BUFF="$(sed 's|\${\([^}]*\)}|$++{\1}++|g' <<< $DESCR_BUFF)" # make sure asciidoc doesn't mix it up with attributes DESCR_BUFF="$(sed 's|\(Eclipse \)\?\bChe\b|{prod-short}|g' <<< $DESCR_BUFF)" # (Eclipse) Che -> {prod-short} @@ -91,12 +92,19 @@ parse_content() { DESCR_BUFF="$(sed -E 's|https://www.keycloak.org/docs/3.3/server_admin/topics/identity-broker/social/openshift.html|https://www.keycloak.org/docs/latest/server_admin/index.html#openshift-4|' <<< $DESCR_BUFF)" # Fix broken link DESCR_BUFF="$(sed -E 's|k8s|{orch-name}|g' <<< $DESCR_BUFF)" # k8s to {orch-name} DESCR_BUFF="$(sed -E 's| openshift| {ocp}|g' <<< $DESCR_BUFF)" # k8s to {orch-name} + DESCR_BUFF="$(sed -E 's|che-host|prod-host|g' <<< $DESCR_BUFF)" # fix missing attribute che-host + DESCR_BUFF="$(sed -E 's|\{WORKSPACE_ID|\\\{WORKSPACE_ID|g' <<< $DESCR_BUFF)" # fix missing attribute WORKSPACE_ID + DESCR_BUFF="$(sed -E 's|\{generated_8_chars|\\\{generated_8_chars|g' <<< $DESCR_BUFF)" # fix missing attribute generated_8_chars DESCR_BUFF="${DESCR_BUFF/ }" # trim first space - BUFF="$BUFF $ENV,\"$VALUE\",\"${DESCR_BUFF//\"/\'}\" $NEWLINE" # apply key value and description buffer + DESCR_BUFF="${DESCR_BUFF//::/:}" # cleanup double colons + BUFF="${BUFF}${NEWLINE}== ${ENV}${NEWLINEx2}${DESCR_BUFF}${NEWLINEx2}Default::: ${VALUE}${NEWLINEx2}'''${NEWLINEx2}" # apply key value and description buffer fi done <<< "$RAW_CONTENT" - BUFF="$BUFF$TABLE_FOOTER" # close last table + # BUFF="$BUFF$TABLE_FOOTER" # close last table + BUFF="pass:[] + +$BUFF" echo "$BUFF" > "$OUTPUT_PATH" # flush buffer into file echo "Processing done. Output file is $OUTPUT_PATH" >&2 } diff --git a/tools/get_vale_styles.sh b/tools/get_vale_styles.sh new file mode 100755 index 0000000000..4c6d26a2e2 --- /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 and display commands +set -ex + +# Get fresh Vale styles +cd .vale/styles || exit +rm -rf RedHat CheDocs +wget -qO- https://github.com/vale-at-red-hat/vale-at-red-hat/releases/latest/download/RedHat.zip | unzip - +wget -qO- https://github.com/vale-at-red-hat/chedocs/releases/latest/download/CheDocs.zip | unzip - diff --git a/tools/linkchecker.sh b/tools/linkchecker.sh deleted file mode 100755 index 7eddfa23fc..0000000000 --- a/tools/linkchecker.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env sh - -linkchecker -f linkcheckerrc http://localhost:4000 diff --git a/tools/newtopic.sh b/tools/newtopic.sh index c3b0a31ef7..5bd0e298e8 100755 --- a/tools/newtopic.sh +++ b/tools/newtopic.sh @@ -1,4 +1,13 @@ #!/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 +# + echo 'Choose the target guide:' PS3='Please select the target guide: ' options=("administration-guide" "contributor-guide" "end-user-guide" "extensions" "installation-guide" "overview") diff --git a/tools/podmanlinkchecker.sh b/tools/podmanlinkchecker.sh deleted file mode 100755 index a3fbbcbce8..0000000000 --- a/tools/podmanlinkchecker.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/usr/bin/env sh -set -ex - -echo "Run linkchecker on a running che-docs container" - -podman exec -ti \ - che-docs \ - "./tools/linkchecker.sh" \ diff --git a/tools/podmanlinkchecker.sh b/tools/podmanlinkchecker.sh new file mode 120000 index 0000000000..ca6c740ddb --- /dev/null +++ b/tools/podmanlinkchecker.sh @@ -0,0 +1 @@ +runnerhtmltest.sh \ No newline at end of file diff --git a/tools/podmanpreview.sh b/tools/podmanpreview.sh deleted file mode 100755 index 1e1f4c75b1..0000000000 --- a/tools/podmanpreview.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/usr/bin/env sh -set -ex - -podman run --rm -ti \ - --name che-docs \ - -v "$PWD:/projects:Z" -w /projects \ - --entrypoint="./tools/preview.sh" \ - -p 4000:4000 -p 35729:35729 \ - "${CHE_DOCS_IMAGE:-quay.io/eclipse/che-docs}" diff --git a/tools/podmanpreview.sh b/tools/podmanpreview.sh new file mode 120000 index 0000000000..bd316ce328 --- /dev/null +++ b/tools/podmanpreview.sh @@ -0,0 +1 @@ +runnerpreview.sh \ No newline at end of file diff --git a/tools/preview.sh b/tools/preview.sh index 0a6ff26f52..85717c51d4 100755 --- a/tools/preview.sh +++ b/tools/preview.sh @@ -1,15 +1,16 @@ #!/usr/bin/env sh -set -ex +# +# 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 +# -LIVERELOAD=true -export LIVERELOAD +# Fail on errors and display commands +set -ex -installandrungulp() { # Install gulp when not present in $PATH -echo "--modules-folder /tmp/node_modules" > /projects/.yarnrc -export HOME=/projects -export NODE_PATH=/tmp/node_modules -yarn add gulp gulp-cli gulp-connect -$NODE_PATH/gulp/bin/gulp.js -} +./tools/get_vale_styles.sh -command -v gulp || installandrungulp && gulp +LIVERELOAD=true gulp diff --git a/tools/runner.sh b/tools/runner.sh new file mode 100755 index 0000000000..98d55c39b9 --- /dev/null +++ b/tools/runner.sh @@ -0,0 +1,20 @@ +#!/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/podmanhtmltest.sh b/tools/runnerhtmltest.sh similarity index 53% rename from tools/podmanhtmltest.sh rename to tools/runnerhtmltest.sh index c29de67461..8c000494ac 100755 --- a/tools/podmanhtmltest.sh +++ b/tools/runnerhtmltest.sh @@ -6,23 +6,17 @@ # which is available at https://www.eclipse.org/legal/epl-2.0/ # # SPDX-License-Identifier: EPL-2.0 +# -set -ex - -echo "Run htmltest in a container" +# Detect available runner +. tools/runner.sh -if command -v podman -then - RUNNER=podman -elif command -v docker -then - RUNNER=docker -else - echo "podman or docker commands not available. Abandoning." - exit 1 -fi +# Fail on errors and display commands +set -ex +# Run htmltest in a container ${RUNNER} run --rm -ti \ - -v "$(pwd):/test:Z" \ - "wjdp/htmltest" \ - -c .htmltest.yml + --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 new file mode 100755 index 0000000000..47b5df94fa --- /dev/null +++ b/tools/runnerpreview.sh @@ -0,0 +1,22 @@ +#!/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 + +${RUNNER} run --rm -ti \ + --name che-docs \ + -v "$PWD:/projects:z" -w /projects \ + --entrypoint="./tools/preview.sh" \ + -p 4000:4000 -p 35729:35729 \ + "${CHE_DOCS_IMAGE:-quay.io/eclipse/che-docs}" diff --git a/tools/substitutions.sh b/tools/substitutions.sh index f6f6abfe0d..2e7f558af6 100755 --- a/tools/substitutions.sh +++ b/tools/substitutions.sh @@ -1,4 +1,12 @@ #!/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 diff --git a/tools/test-adoc.sh b/tools/test-adoc.sh index 50a73e0dec..2fdc8afd33 100755 --- a/tools/test-adoc.sh +++ b/tools/test-adoc.sh @@ -149,7 +149,7 @@ function detect_type { function print_adoc { local -r filename="$1" - # Remove both single-line and multi-line comments from the supplied file: + # Remove both single-line and multiline comments from the supplied file: perl -0pe 's{^////\s*\n.*?^////\s*\n}{}msg;s{^//.*\n}{}gm;' "$filename" } diff --git a/tools/validate_attributes_processing.sh b/tools/validate_attributes_processing.sh index ff46f34487..426f24d936 100755 --- a/tools/validate_attributes_processing.sh +++ b/tools/validate_attributes_processing.sh @@ -1,4 +1,12 @@ #!/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 diff --git a/tools/validate_language_changes.sh b/tools/validate_language_changes.sh new file mode 100755 index 0000000000..bff6979f45 --- /dev/null +++ b/tools/validate_language_changes.sh @@ -0,0 +1,22 @@ +#!/bin/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 +# +set -e + +vale -v + +BRANCH=origin/${GITHUB_BASE_REF:-master} + +FILES=$(git diff --name-only --diff-filter=AM "$BRANCH") + +echo "Files added or modified, in comparison to branch $BRANCH: +$FILES" + +# shellcheck disable=SC2086 (We want to split on spaces) +vale ${FILES} diff --git a/tools/verify_xrefs.sh b/tools/verify_xrefs.sh index 7454f112e1..e1b523fde5 100755 --- a/tools/verify_xrefs.sh +++ b/tools/verify_xrefs.sh @@ -1,4 +1,12 @@ #!/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 +# echo "Verifying xrefs." for MODULES_DIR in $@ diff --git a/yarn.lock b/yarn.lock deleted file mode 100644 index fb3e7cf984..0000000000 --- a/yarn.lock +++ /dev/null @@ -1,3690 +0,0 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. -# yarn lockfile v1 - - -"@antora/asciidoc-loader@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/asciidoc-loader/-/asciidoc-loader-2.3.4.tgz#b5c4b6447981e191cea8438226a8e76904fc1e7d" - integrity sha512-IQ0d/hnOCGZXzTYUwKAw2BlyRMI4Kg/zu7XejQ6ERIncjuUUv/+PhlzVxoJNT0r9uasJFHDlZ7l3X53Hn+MUuQ== - dependencies: - asciidoctor.js "1.5.9" - opal-runtime "1.0.11" - -"@antora/cli@^2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/cli/-/cli-2.3.4.tgz#1b2df06eb5bbbfcb5c6ae8618e18c79dc1f6758e" - integrity sha512-KItaWFEf/X4LLY2XCidjD00oUp4Ay7y9Hu26+T8dPqV+qnMwOL+MGHhYXsJz+4JaeNJu1Ofwc4onmShpwHQruA== - dependencies: - "@antora/playbook-builder" "2.3.4" - commander "~6.1" - -"@antora/content-aggregator@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/content-aggregator/-/content-aggregator-2.3.4.tgz#6b1f4258fbf2a42c79be52886edbf36c2703a877" - integrity sha512-ZwlGm/t90PUnGVo+pir71O+wC+gyXnVuhoAed+9bBLjsiGI7EGUzwUEXSZqHRSihPx5XLFj6pZinoCGX+uabcw== - dependencies: - "@antora/expand-path-helper" "~1.0" - braces "~3.0" - cache-directory "~2.0" - camelcase-keys "~6.2" - fs-extra "~8.1" - isomorphic-git "0.78.5" - js-yaml "~3.14" - matcher "~2.1" - mime-types "~2.1" - multi-progress "~2.0" - picomatch "~2.2" - through2 "~4.0" - vinyl "~2.2" - vinyl-fs "~3.0" - -"@antora/content-classifier@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/content-classifier/-/content-classifier-2.3.4.tgz#a2c59d5e971ed3ed48860bee2fd4d93b02012f97" - integrity sha512-DR4I6dLSZEFOS3T0F/hYwLf3AGY2Rb3e9j8V8ygEFzdP8OySAAZWyTjjJPF4pJZqjWtqD7s7S1f5/cCI83977Q== - dependencies: - "@antora/asciidoc-loader" "2.3.4" - vinyl "~2.2" - -"@antora/document-converter@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/document-converter/-/document-converter-2.3.4.tgz#c787ebe0f24a3bc613843b557a1b04488f48c0be" - integrity sha512-Fo2SKdX3BlNrvfQEBOi2II+YmYzdEqKQ5+lO2pzxJuNBfqN0kJJYYk30jFPR27h6QuU43U/XZgufyDt+FjfdZg== - dependencies: - "@antora/asciidoc-loader" "2.3.4" - -"@antora/expand-path-helper@~1.0": - version "1.0.0" - resolved "https://registry.yarnpkg.com/@antora/expand-path-helper/-/expand-path-helper-1.0.0.tgz#3bfd6938ab86d4709af8d869cbf3bb17b8fe8912" - integrity sha512-hg3y6M3OvRTb7jtLAnwwloYDxafbyKYttcf16kGCXvP7Wqosh7c+Ag+ltaZ7VSebpzpphO/umb/BXdpU7rxapw== - -"@antora/navigation-builder@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/navigation-builder/-/navigation-builder-2.3.4.tgz#aace46d61506ecf25de2d47f3a16f9d7debb47de" - integrity sha512-55I7p9tNTernQ/YR1+mp6RRXMV5EcU8q20Tdodt3mazdm3ObTe9E9XVAvUDFmDzRA27D0eb06jVRwLoth1gHYA== - dependencies: - "@antora/asciidoc-loader" "2.3.4" - -"@antora/page-composer@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/page-composer/-/page-composer-2.3.4.tgz#47f6438cce7d7140c3e2658d8224ef138471d256" - integrity sha512-xY0O9X87DzcoP6k/5Jx55ysy0iQIhgav3q1JbOQK/FoYQYHbiQgmVWOjJdqh5nZw57ih3yE20JROPuYqOYuUZA== - dependencies: - handlebars "~4.7" - require-from-string "~2.0" - -"@antora/playbook-builder@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/playbook-builder/-/playbook-builder-2.3.4.tgz#7f33d92a3800a3e3c78ebf17d4b0cd46644e0525" - integrity sha512-iPjBndcoZhWqpN608WOkXKUUD94b3JX38igebshiT5/NRINJbeEclpdEX/gPv8D1Z1JcrSVGURZQO1uML76dkg== - dependencies: - "@iarna/toml" "~2.2" - camelcase-keys "~6.2" - convict "~6.0" - js-yaml "~3.14" - json5 "~2.1" - -"@antora/redirect-producer@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/redirect-producer/-/redirect-producer-2.3.4.tgz#5f47337e8062d304518359fbbbcaaf75e82b656b" - integrity sha512-148amiLc+1Pod6kluAOBke8OATFWFUW3LZdTPFVfqX1lJolCp5ciOnGciy52sIIysSyVkQUjotEUhqGO9Af1EQ== - dependencies: - "@antora/asciidoc-loader" "2.3.4" - vinyl "~2.2" - -"@antora/site-generator-default@^2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/site-generator-default/-/site-generator-default-2.3.4.tgz#1b4fe3e1097ea03aa8877f98d944f26921049418" - integrity sha512-uRiFJ/nG5bxjDmFOur27ae7A1J7r+OFVocEwx+vVLRvVYfNHxYP0fI2uUrmJTci8xJ92NLH9VLHpfsHypsoq9Q== - dependencies: - "@antora/asciidoc-loader" "2.3.4" - "@antora/content-aggregator" "2.3.4" - "@antora/content-classifier" "2.3.4" - "@antora/document-converter" "2.3.4" - "@antora/navigation-builder" "2.3.4" - "@antora/page-composer" "2.3.4" - "@antora/playbook-builder" "2.3.4" - "@antora/redirect-producer" "2.3.4" - "@antora/site-mapper" "2.3.4" - "@antora/site-publisher" "2.3.4" - "@antora/ui-loader" "2.3.4" - -"@antora/site-mapper@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/site-mapper/-/site-mapper-2.3.4.tgz#ea19fc1eff09bbb49f14a3e80f829867a695356e" - integrity sha512-GVghn6ausIWZlUfbEEdDD4YB7M1mWJAUMokyha9sE5w0gyYoWwukKWQiwCwk/JhvnwXunMLhEUm6y2nrHEmlLw== - dependencies: - "@antora/content-classifier" "2.3.4" - vinyl "~2.2" - -"@antora/site-publisher@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/site-publisher/-/site-publisher-2.3.4.tgz#cb3a931f39fd6973d10172a07c730cb0ce40208f" - integrity sha512-7xI/5OdjKq5tkdGzE0ABkl/QpIcgtnof+rnIWZweQKeQtA3LWutvEHtdIeXLQt0oNZmE/kf45FwC2XCg9/ptDg== - dependencies: - "@antora/expand-path-helper" "~1.0" - fs-extra "~8.1" - gulp-vinyl-zip "~2.2" - vinyl "~2.2" - vinyl-fs "~3.0" - -"@antora/ui-loader@2.3.4": - version "2.3.4" - resolved "https://registry.yarnpkg.com/@antora/ui-loader/-/ui-loader-2.3.4.tgz#3c060c2da8752f42cf841569519396a6f4155cba" - integrity sha512-eorTmZW7zc6ZHgGLt3Vrq7mzPuobPeJnyfli50/m/DIQ91slkqjPKUYGcq4paPEz6IWoa7LT2ZwtwA5KzMyTPg== - dependencies: - "@antora/expand-path-helper" "~1.0" - bl "~4.0" - cache-directory "~2.0" - camelcase-keys "~6.2" - fs-extra "~8.1" - got "~9.6" - gulp-vinyl-zip "~2.2" - js-yaml "~3.14" - minimatch-all "~1.1" - through2 "~4.0" - vinyl "~2.2" - vinyl-fs "~3.0" - -"@asciidoctor/cli@3.4.0": - version "3.4.0" - resolved "https://registry.yarnpkg.com/@asciidoctor/cli/-/cli-3.4.0.tgz#586e9133f3367c7b3236631197f4b621890d9227" - integrity sha512-jOtxA0I6zB+6z+GGwm9+xhlmGTqCTkFPE902L6fauFlE6v7LxjhLYNxvjDVyn0zMrFLybvoSRcAnM3DcticNoQ== - dependencies: - yargs "15.3.1" - -"@asciidoctor/core@2.2.1": - version "2.2.1" - resolved "https://registry.yarnpkg.com/@asciidoctor/core/-/core-2.2.1.tgz#eac0361a85b46f2ef2a9d19d73e3875bf94715d4" - integrity sha512-wdVseZjCcBvFfWSsCGyyvJkSQJ9UmXDdTDKnL+HerM12XQq4eWtk7lniSIKO459ipqImcsrueib47EtkzzRjLw== - dependencies: - asciidoctor-opal-runtime "0.3.0" - unxhr "1.0.1" - -"@iarna/toml@~2.2": - version "2.2.5" - resolved "https://registry.yarnpkg.com/@iarna/toml/-/toml-2.2.5.tgz#b32366c89b43c6f8cefbdefac778b9c828e3ba8c" - integrity sha512-trnsAYxU3xnS1gPHPyU961coFyLkh4gAD/0zQ5mymY4yOZ+CYvsPqUbOFSw0aDM4y0tV7tiFxL/1XfXPNC6IPg== - -"@sindresorhus/is@^0.14.0": - version "0.14.0" - resolved "https://registry.yarnpkg.com/@sindresorhus/is/-/is-0.14.0.tgz#9fb3a3cf3132328151f353de4632e01e52102bea" - integrity sha512-9NET910DNaIPngYnLLPeg+Ogzqsi9uM4mSboU5y6p8S5DzMTVEsJZrawi+BoDNUVBa2DhJqQYUFvMDfgU062LQ== - -"@szmarczak/http-timer@^1.1.2": - version "1.1.2" - resolved "https://registry.yarnpkg.com/@szmarczak/http-timer/-/http-timer-1.1.2.tgz#b1665e2c461a2cd92f4c1bbf50d5454de0d4b421" - integrity sha512-XIB2XbzHTN6ieIjfIMV9hlVcfPU26s2vafYWQcZHWXHOxiaRZYEDKEwdl129Zyg50+foYV2jCgtrqSA6qNuNSA== - dependencies: - defer-to-connect "^1.0.1" - -accepts@~1.3.4: - version "1.3.7" - resolved "https://registry.yarnpkg.com/accepts/-/accepts-1.3.7.tgz#531bc726517a3b2b41f850021c6cc15eaab507cd" - integrity sha512-Il80Qs2WjYlJIBNzNkK6KYqlVMTbZLXgHx2oT0pU/fjRHyEp+PEfEPY0R3WCwAGVOtauxh1hOxNgIf5bv7dQpA== - dependencies: - mime-types "~2.1.24" - negotiator "0.6.2" - -ansi-colors@^1.0.1: - version "1.1.0" - resolved "https://registry.yarnpkg.com/ansi-colors/-/ansi-colors-1.1.0.tgz#6374b4dd5d4718ff3ce27a671a3b1cad077132a9" - integrity sha512-SFKX67auSNoVR38N3L+nvsPjOE0bybKTYbkf5tRvushrAPQ9V75huw0ZxBkKVeRU9kqH3d6HA4xTckbwZ4ixmA== - dependencies: - ansi-wrap "^0.1.0" - -ansi-colors@^2.0.5: - version "2.0.5" - resolved "https://registry.yarnpkg.com/ansi-colors/-/ansi-colors-2.0.5.tgz#5da37825fef3e75f3bda47f760d64bfd10e15e10" - integrity sha512-yAdfUZ+c2wetVNIFsNRn44THW+Lty6S5TwMpUfLA/UaGhiXbBv/F8E60/1hMLd0cnF/CDoWH8vzVaI5bAcHCjw== - -ansi-gray@^0.1.1: - version "0.1.1" - resolved "https://registry.yarnpkg.com/ansi-gray/-/ansi-gray-0.1.1.tgz#2962cf54ec9792c48510a3deb524436861ef7251" - integrity sha1-KWLPVOyXksSFEKPetSRDaGHvclE= - dependencies: - ansi-wrap "0.1.0" - -ansi-regex@^2.0.0: - version "2.1.1" - resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-2.1.1.tgz#c3b33ab5ee360d86e0e628f0468ae7ef27d654df" - integrity sha1-w7M6te42DYbg5ijwRorn7yfWVN8= - -ansi-regex@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-5.0.0.tgz#388539f55179bf39339c81af30a654d69f87cb75" - integrity sha512-bY6fj56OUQ0hU1KjFNDQuJFezqKdrAyFdIevADiqrWHwSlbmBNMHp5ak2f40Pm8JTFyM2mqxkG6ngkHO11f/lg== - -ansi-styles@^4.0.0: - version "4.3.0" - resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-4.3.0.tgz#edd803628ae71c04c85ae7a0906edad34b648937" - integrity sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg== - dependencies: - color-convert "^2.0.1" - -ansi-wrap@0.1.0, ansi-wrap@^0.1.0: - version "0.1.0" - resolved "https://registry.yarnpkg.com/ansi-wrap/-/ansi-wrap-0.1.0.tgz#a82250ddb0015e9a27ca82e82ea603bbfa45efaf" - integrity sha1-qCJQ3bABXponyoLoLqYDu/pF768= - -anymatch@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/anymatch/-/anymatch-2.0.0.tgz#bcb24b4f37934d9aa7ac17b4adaf89e7c76ef2eb" - integrity sha512-5teOsQWABXHHBFP9y3skS5P3d/WfWXpv3FUpy+LorMrNYaT9pI4oLMQX7jzQ2KklNpGpWHzdCXTDT2Y3XGlZBw== - dependencies: - micromatch "^3.1.4" - normalize-path "^2.1.1" - -append-buffer@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/append-buffer/-/append-buffer-1.0.2.tgz#d8220cf466081525efea50614f3de6514dfa58f1" - integrity sha1-2CIM9GYIFSXv6lBhTz3mUU36WPE= - dependencies: - buffer-equal "^1.0.0" - -archy@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/archy/-/archy-1.0.0.tgz#f9c8c13757cc1dd7bc379ac77b2c62a5c2868c40" - integrity sha1-+cjBN1fMHde8N5rHeyxipcKGjEA= - -argparse@^1.0.7: - version "1.0.10" - resolved "https://registry.yarnpkg.com/argparse/-/argparse-1.0.10.tgz#bcd6791ea5ae09725e17e5ad988134cd40b3d911" - integrity sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg== - dependencies: - sprintf-js "~1.0.2" - -arr-diff@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/arr-diff/-/arr-diff-4.0.0.tgz#d6461074febfec71e7e15235761a329a5dc7c520" - integrity sha1-1kYQdP6/7HHn4VI1dhoyml3HxSA= - -arr-filter@^1.1.1: - version "1.1.2" - resolved "https://registry.yarnpkg.com/arr-filter/-/arr-filter-1.1.2.tgz#43fdddd091e8ef11aa4c45d9cdc18e2dff1711ee" - integrity sha1-Q/3d0JHo7xGqTEXZzcGOLf8XEe4= - dependencies: - make-iterator "^1.0.0" - -arr-flatten@^1.0.1, arr-flatten@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/arr-flatten/-/arr-flatten-1.1.0.tgz#36048bbff4e7b47e136644316c99669ea5ae91f1" - integrity sha512-L3hKV5R/p5o81R7O02IGnwpDmkp6E982XhtbuwSe3O4qOtMMMtodicASA1Cny2U+aCXcNpml+m4dPsvsJ3jatg== - -arr-map@^2.0.0, arr-map@^2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/arr-map/-/arr-map-2.0.2.tgz#3a77345ffc1cf35e2a91825601f9e58f2e24cac4" - integrity sha1-Onc0X/wc814qkYJWAfnljy4kysQ= - dependencies: - make-iterator "^1.0.0" - -arr-union@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/arr-union/-/arr-union-3.1.0.tgz#e39b09aea9def866a8f206e288af63919bae39c4" - integrity sha1-45sJrqne+Gao8gbiiK9jkZuuOcQ= - -array-each@^1.0.0, array-each@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/array-each/-/array-each-1.0.1.tgz#a794af0c05ab1752846ee753a1f211a05ba0c44f" - integrity sha1-p5SvDAWrF1KEbudTofIRoFugxE8= - -array-initial@^1.0.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/array-initial/-/array-initial-1.1.0.tgz#2fa74b26739371c3947bd7a7adc73be334b3d795" - integrity sha1-L6dLJnOTccOUe9enrcc74zSz15U= - dependencies: - array-slice "^1.0.0" - is-number "^4.0.0" - -array-last@^1.1.1: - version "1.3.0" - resolved "https://registry.yarnpkg.com/array-last/-/array-last-1.3.0.tgz#7aa77073fec565ddab2493f5f88185f404a9d336" - integrity sha512-eOCut5rXlI6aCOS7Z7kCplKRKyiFQ6dHFBem4PwlwKeNFk2/XxTrhRh5T9PyaEWGy/NHTZWbY+nsZlNFJu9rYg== - dependencies: - is-number "^4.0.0" - -array-slice@^1.0.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/array-slice/-/array-slice-1.1.0.tgz#e368ea15f89bc7069f7ffb89aec3a6c7d4ac22d4" - integrity sha512-B1qMD3RBP7O8o0H2KbrXDyB0IccejMF15+87Lvlor12ONPRHP6gTjXMNkt/d3ZuOGbAe66hFmaCfECI24Ufp6w== - -array-sort@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/array-sort/-/array-sort-1.0.0.tgz#e4c05356453f56f53512a7d1d6123f2c54c0a88a" - integrity sha512-ihLeJkonmdiAsD7vpgN3CRcx2J2S0TiYW+IS/5zHBI7mKUq3ySvBdzzBfD236ubDBQFiiyG3SWCPc+msQ9KoYg== - dependencies: - default-compare "^1.0.0" - get-value "^2.0.6" - kind-of "^5.0.2" - -array-unique@^0.3.2: - version "0.3.2" - resolved "https://registry.yarnpkg.com/array-unique/-/array-unique-0.3.2.tgz#a894b75d4bc4f6cd679ef3244a9fd8f46ae2d428" - integrity sha1-qJS3XUvE9s1nnvMkSp/Y9Gri1Cg= - -asciidoctor-opal-runtime@0.3.0: - version "0.3.0" - resolved "https://registry.yarnpkg.com/asciidoctor-opal-runtime/-/asciidoctor-opal-runtime-0.3.0.tgz#df327a870ddd3cd5eb0e162d64ed4dcdd3fe3fee" - integrity sha512-YapVwl2qbbs6sIe1dvAlMpBzQksFVTSa2HOduOKFNhZlE9bNmn+moDgGVvjWPbzMPo/g8gItyTHfWB2u7bQxag== - dependencies: - glob "7.1.3" - unxhr "1.0.1" - -asciidoctor.js@1.5.9: - version "1.5.9" - resolved "https://registry.yarnpkg.com/asciidoctor.js/-/asciidoctor.js-1.5.9.tgz#28f8e8ee134b82627f0240e9b6a201b3d15d9524" - integrity sha512-k5JgwyV82TsiCpnYbDPReuHhzf/vRUt6NaZ+OGywkDDGeGG/CPfvN2Gd1MJ0iIZKDyuk4iJHOdY/2x1KBrWMzA== - dependencies: - opal-runtime "1.0.11" - -asciidoctor@^2.2.1: - version "2.2.1" - resolved "https://registry.yarnpkg.com/asciidoctor/-/asciidoctor-2.2.1.tgz#4e29fe7195d97f75b36c91ad8e3448191b9ab0fa" - integrity sha512-adH/pDPDZCd4eb1ku7N8WepN+O6Yl0lVQPWE/ep7+0BFkBm4P/Sx8DUqzZ+X+nG6WSZlma5Uu0gNuDgrc7etFg== - dependencies: - "@asciidoctor/cli" "3.4.0" - "@asciidoctor/core" "2.2.1" - -assign-symbols@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/assign-symbols/-/assign-symbols-1.0.0.tgz#59667f41fadd4f20ccbc2bb96b8d4f7f78ec0367" - integrity sha1-WWZ/QfrdTyDMvCu5a41Pf3jsA2c= - -async-done@^1.2.0, async-done@^1.2.2: - version "1.3.2" - resolved "https://registry.yarnpkg.com/async-done/-/async-done-1.3.2.tgz#5e15aa729962a4b07414f528a88cdf18e0b290a2" - integrity sha512-uYkTP8dw2og1tu1nmza1n1CMW0qb8gWWlwqMmLb7MhBVs4BXrFziT6HXUd+/RlRA/i4H9AkofYloUbs1fwMqlw== - dependencies: - end-of-stream "^1.1.0" - once "^1.3.2" - process-nextick-args "^2.0.0" - stream-exhaust "^1.0.1" - -async-each@^1.0.1: - version "1.0.3" - resolved "https://registry.yarnpkg.com/async-each/-/async-each-1.0.3.tgz#b727dbf87d7651602f06f4d4ac387f47d91b0cbf" - integrity sha512-z/WhQ5FPySLdvREByI2vZiTWwCnF0moMJ1hK9YQwDTHKh6I7/uSckMetoRGb5UBZPC1z0jlw+n/XCgjeH7y1AQ== - -async-lock@^1.1.0: - version "1.2.8" - resolved "https://registry.yarnpkg.com/async-lock/-/async-lock-1.2.8.tgz#7b02bdfa2de603c0713acecd11184cf97bbc7c4c" - integrity sha512-G+26B2jc0Gw0EG/WN2M6IczuGepBsfR1+DtqLnyFSH4p2C668qkOCtEkGNVEaaNAVlYwEMazy1+/jnLxltBkIQ== - -async-settle@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/async-settle/-/async-settle-1.0.0.tgz#1d0a914bb02575bec8a8f3a74e5080f72b2c0c6b" - integrity sha1-HQqRS7Aldb7IqPOnTlCA9yssDGs= - dependencies: - async-done "^1.2.2" - -async@^2.6.2: - version "2.6.3" - resolved "https://registry.yarnpkg.com/async/-/async-2.6.3.tgz#d72625e2344a3656e3a3ad4fa749fa83299d82ff" - integrity sha512-zflvls11DCy+dQWzTW2dzuilv8Z5X/pjfmZOWba6TNIVDm+2UDaJmXSOXlasHKfNBs8oo3M0aT50fDEWfKZjXg== - dependencies: - lodash "^4.17.14" - -atob@^2.1.2: - version "2.1.2" - resolved "https://registry.yarnpkg.com/atob/-/atob-2.1.2.tgz#6d9517eb9e030d2436666651e86bd9f6f13533c9" - integrity sha512-Wm6ukoaOGJi/73p/cl2GvLjTI5JM1k/O14isD73YML8StrH/7/lRFgmg8nICZgD3bZZvjwCGxtMOD3wWNAu8cg== - -bach@^1.0.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/bach/-/bach-1.2.0.tgz#4b3ce96bf27134f79a1b414a51c14e34c3bd9880" - integrity sha1-Szzpa/JxNPeaG0FKUcFONMO9mIA= - dependencies: - arr-filter "^1.1.1" - arr-flatten "^1.0.1" - arr-map "^2.0.0" - array-each "^1.0.0" - array-initial "^1.0.0" - array-last "^1.1.1" - async-done "^1.2.2" - async-settle "^1.0.0" - now-and-later "^2.0.0" - -balanced-match@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/balanced-match/-/balanced-match-1.0.0.tgz#89b4d199ab2bee49de164ea02b89ce462d71b767" - integrity sha1-ibTRmasr7kneFk6gK4nORi1xt2c= - -base64-js@0.0.2: - version "0.0.2" - resolved "https://registry.yarnpkg.com/base64-js/-/base64-js-0.0.2.tgz#024f0f72afa25b75f9c0ee73cd4f55ec1bed9784" - integrity sha1-Ak8Pcq+iW3X5wO5zzU9V7Bvtl4Q= - -base64-js@^1.3.1: - version "1.5.1" - resolved "https://registry.yarnpkg.com/base64-js/-/base64-js-1.5.1.tgz#1b1b440160a5bf7ad40b650f095963481903930a" - integrity sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA== - -base@^0.11.1: - version "0.11.2" - resolved "https://registry.yarnpkg.com/base/-/base-0.11.2.tgz#7bde5ced145b6d551a90db87f83c558b4eb48a8f" - integrity sha512-5T6P4xPgpp0YDFvSWwEZ4NoE3aM4QBQXDzmVbraCkFj8zHM+mba8SyqB5DbZWyR7mYHo6Y7BdQo3MoA4m0TeQg== - dependencies: - cache-base "^1.0.1" - class-utils "^0.3.5" - component-emitter "^1.2.1" - define-property "^1.0.0" - isobject "^3.0.1" - mixin-deep "^1.2.0" - pascalcase "^0.1.1" - -basic-auth@^1.0.3: - version "1.1.0" - resolved "https://registry.yarnpkg.com/basic-auth/-/basic-auth-1.1.0.tgz#45221ee429f7ee1e5035be3f51533f1cdfd29884" - integrity sha1-RSIe5Cn37h5QNb4/UVM/HN/SmIQ= - -batch@0.6.1: - version "0.6.1" - resolved "https://registry.yarnpkg.com/batch/-/batch-0.6.1.tgz#dc34314f4e679318093fc760272525f94bf25c16" - integrity sha1-3DQxT05nkxgJP8dgJyUl+UvyXBY= - -binary-extensions@^1.0.0: - version "1.13.1" - resolved "https://registry.yarnpkg.com/binary-extensions/-/binary-extensions-1.13.1.tgz#598afe54755b2868a5330d2aff9d4ebb53209b65" - integrity sha512-Un7MIEDdUC5gNpcGDV97op1Ywk748MpHcFTHoYs6qnj1Z3j7I53VG3nwZhKzoBZmbdRNnb6WRdFlwl7tSDuZGw== - -bindings@^1.5.0: - version "1.5.0" - resolved "https://registry.yarnpkg.com/bindings/-/bindings-1.5.0.tgz#10353c9e945334bc0511a6d90b38fbc7c9c504df" - integrity sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ== - dependencies: - file-uri-to-path "1.0.0" - -bl@~4.0: - version "4.0.3" - resolved "https://registry.yarnpkg.com/bl/-/bl-4.0.3.tgz#12d6287adc29080e22a705e5764b2a9522cdc489" - integrity sha512-fs4G6/Hu4/EE+F75J8DuN/0IpQqNjAdC7aEQv7Qt8MHGUH7Ckv2MwTEEeN9QehD0pfIDkMI1bkHYkKy7xHyKIg== - dependencies: - buffer "^5.5.0" - inherits "^2.0.4" - readable-stream "^3.4.0" - -body@^5.1.0: - version "5.1.0" - resolved "https://registry.yarnpkg.com/body/-/body-5.1.0.tgz#e4ba0ce410a46936323367609ecb4e6553125069" - integrity sha1-5LoM5BCkaTYyM2dgnstOZVMSUGk= - dependencies: - continuable-cache "^0.3.1" - error "^7.0.0" - raw-body "~1.1.0" - safe-json-parse "~1.0.1" - -bops@~0.0.6: - version "0.0.7" - resolved "https://registry.yarnpkg.com/bops/-/bops-0.0.7.tgz#b4a0a5a839a406454af0fe05a8b91a7a766a54e2" - integrity sha1-tKClqDmkBkVK8P4FqLkaenZqVOI= - dependencies: - base64-js "0.0.2" - to-utf8 "0.0.1" - -brace-expansion@^1.1.7: - version "1.1.11" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-1.1.11.tgz#3c7fcbf529d87226f3d2f52b966ff5271eb441dd" - integrity sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA== - dependencies: - balanced-match "^1.0.0" - concat-map "0.0.1" - -braces@^2.3.1, braces@^2.3.2: - version "2.3.2" - resolved "https://registry.yarnpkg.com/braces/-/braces-2.3.2.tgz#5979fd3f14cd531565e5fa2df1abfff1dfaee729" - integrity sha512-aNdbnj9P8PjdXU4ybaWLK2IF3jc/EoDYbC7AazW6to3TRsfXxscC9UXOB5iDiEQrkyIbWp2SLQda4+QAa7nc3w== - dependencies: - arr-flatten "^1.1.0" - array-unique "^0.3.2" - extend-shallow "^2.0.1" - fill-range "^4.0.0" - isobject "^3.0.1" - repeat-element "^1.1.2" - snapdragon "^0.8.1" - snapdragon-node "^2.0.1" - split-string "^3.0.2" - to-regex "^3.0.1" - -braces@~3.0: - version "3.0.2" - resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.2.tgz#3454e1a462ee8d599e236df336cd9ea4f8afe107" - integrity sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A== - dependencies: - fill-range "^7.0.1" - -buffer-crc32@~0.2.3: - version "0.2.13" - resolved "https://registry.yarnpkg.com/buffer-crc32/-/buffer-crc32-0.2.13.tgz#0d333e3f00eac50aa1454abd30ef8c2a5d9a7242" - integrity sha1-DTM+PwDqxQqhRUq9MO+MKl2ackI= - -buffer-equal@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/buffer-equal/-/buffer-equal-1.0.0.tgz#59616b498304d556abd466966b22eeda3eca5fbe" - integrity sha1-WWFrSYME1Var1GaWayLu2j7KX74= - -buffer-from@^1.0.0: - version "1.1.1" - resolved "https://registry.yarnpkg.com/buffer-from/-/buffer-from-1.1.1.tgz#32713bc028f75c02fdb710d7c7bcec1f2c6070ef" - integrity sha512-MQcXEUbCKtEo7bhqEs6560Hyd4XaovZlO/k9V3hjVUF/zwW7KBVdSK4gIt/bzwS9MbR5qob+F5jusZsb0YQK2A== - -buffer@^5.5.0: - version "5.7.1" - resolved "https://registry.yarnpkg.com/buffer/-/buffer-5.7.1.tgz#ba62e7c13133053582197160851a8f648e99eed0" - integrity sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ== - dependencies: - base64-js "^1.3.1" - ieee754 "^1.1.13" - -bytes@1: - version "1.0.0" - resolved "https://registry.yarnpkg.com/bytes/-/bytes-1.0.0.tgz#3569ede8ba34315fab99c3e92cb04c7220de1fa8" - integrity sha1-NWnt6Lo0MV+rmcPpLLBMciDeH6g= - -cache-base@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/cache-base/-/cache-base-1.0.1.tgz#0a7f46416831c8b662ee36fe4e7c59d76f666ab2" - integrity sha512-AKcdTnFSWATd5/GCPRxr2ChwIJ85CeyrEyjRHlKxQ56d4XJMGym0uAiKn0xbLOGOl3+yRpOTi484dVCEc5AUzQ== - dependencies: - collection-visit "^1.0.0" - component-emitter "^1.2.1" - get-value "^2.0.6" - has-value "^1.0.0" - isobject "^3.0.1" - set-value "^2.0.0" - to-object-path "^0.3.0" - union-value "^1.0.0" - unset-value "^1.0.0" - -cache-directory@~2.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/cache-directory/-/cache-directory-2.0.0.tgz#0d8efa1abbb6d1dd926d255ce733b4f7c5ab2892" - integrity sha512-7YKEapH+2Uikde8hySyfobXBqPKULDyHNl/lhKm7cKf/GJFdG/tU/WpLrOg2y9aUrQrWUilYqawFIiGJPS6gDA== - dependencies: - xdg-basedir "^3.0.0" - -cacheable-request@^6.0.0: - version "6.1.0" - resolved "https://registry.yarnpkg.com/cacheable-request/-/cacheable-request-6.1.0.tgz#20ffb8bd162ba4be11e9567d823db651052ca912" - integrity sha512-Oj3cAGPCqOZX7Rz64Uny2GYAZNliQSqfbePrgAQ1wKAihYmCUnraBtJtKcGR4xz7wF+LoJC+ssFZvv5BgF9Igg== - dependencies: - clone-response "^1.0.2" - get-stream "^5.1.0" - http-cache-semantics "^4.0.0" - keyv "^3.0.0" - lowercase-keys "^2.0.0" - normalize-url "^4.1.0" - responselike "^1.0.2" - -call-bind@^1.0.0: - version "1.0.2" - resolved "https://registry.yarnpkg.com/call-bind/-/call-bind-1.0.2.tgz#b1d4e89e688119c3c9a903ad30abb2f6a919be3c" - integrity sha512-7O+FbCihrB5WGbFYesctwmTKae6rOiIzmz1icreWJ+0aA7LJfuqhEso2T9ncpcFtzMQtzXf2QGGueWJGTYsqrA== - dependencies: - function-bind "^1.1.1" - get-intrinsic "^1.0.2" - -camelcase-keys@~6.2: - version "6.2.2" - resolved "https://registry.yarnpkg.com/camelcase-keys/-/camelcase-keys-6.2.2.tgz#5e755d6ba51aa223ec7d3d52f25778210f9dc3c0" - integrity sha512-YrwaA0vEKazPBkn0ipTiMpSajYDSe+KjQfrjhcBMxJt/znbvlHd8Pw/Vamaz5EB4Wfhs3SUR3Z9mwRu/P3s3Yg== - dependencies: - camelcase "^5.3.1" - map-obj "^4.0.0" - quick-lru "^4.0.1" - -camelcase@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-3.0.0.tgz#32fc4b9fcdaf845fcdf7e73bb97cac2261f0ab0a" - integrity sha1-MvxLn82vhF/N9+c7uXysImHwqwo= - -camelcase@^5.0.0, camelcase@^5.3.1: - version "5.3.1" - resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-5.3.1.tgz#e3c9b31569e106811df242f715725a1f4c494320" - integrity sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg== - -chokidar@^2.0.0: - version "2.1.8" - resolved "https://registry.yarnpkg.com/chokidar/-/chokidar-2.1.8.tgz#804b3a7b6a99358c3c5c61e71d8728f041cff917" - integrity sha512-ZmZUazfOzf0Nve7duiCKD23PFSCs4JPoYyccjUFF3aQkQadqBhfzhjkwBH2mNOG9cTBwhamM37EIsIkZw3nRgg== - dependencies: - anymatch "^2.0.0" - async-each "^1.0.1" - braces "^2.3.2" - glob-parent "^3.1.0" - inherits "^2.0.3" - is-binary-path "^1.0.0" - is-glob "^4.0.0" - normalize-path "^3.0.0" - path-is-absolute "^1.0.0" - readdirp "^2.2.1" - upath "^1.1.1" - optionalDependencies: - fsevents "^1.2.7" - -class-utils@^0.3.5: - version "0.3.6" - resolved "https://registry.yarnpkg.com/class-utils/-/class-utils-0.3.6.tgz#f93369ae8b9a7ce02fd41faad0ca83033190c463" - integrity sha512-qOhPa/Fj7s6TY8H8esGu5QNpMMQxz79h+urzrNYN6mn+9BnxlDGf5QZ+XeCDsxSjPqsSR56XOZOJmpeurnLMeg== - dependencies: - arr-union "^3.1.0" - define-property "^0.2.5" - isobject "^3.0.0" - static-extend "^0.1.1" - -clean-git-ref@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/clean-git-ref/-/clean-git-ref-2.0.1.tgz#dcc0ca093b90e527e67adb5a5e55b1af6816dcd9" - integrity sha512-bLSptAy2P0s6hU4PzuIMKmMJJSE6gLXGH1cntDu7bWJUksvuM+7ReOK61mozULErYvP6a15rnYl0zFDef+pyPw== - -cliui@^3.2.0: - version "3.2.0" - resolved "https://registry.yarnpkg.com/cliui/-/cliui-3.2.0.tgz#120601537a916d29940f934da3b48d585a39213d" - integrity sha1-EgYBU3qRbSmUD5NNo7SNWFo5IT0= - dependencies: - string-width "^1.0.1" - strip-ansi "^3.0.1" - wrap-ansi "^2.0.0" - -cliui@^6.0.0: - version "6.0.0" - resolved "https://registry.yarnpkg.com/cliui/-/cliui-6.0.0.tgz#511d702c0c4e41ca156d7d0e96021f23e13225b1" - integrity sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ== - dependencies: - string-width "^4.2.0" - strip-ansi "^6.0.0" - wrap-ansi "^6.2.0" - -clone-buffer@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/clone-buffer/-/clone-buffer-1.0.0.tgz#e3e25b207ac4e701af721e2cb5a16792cac3dc58" - integrity sha1-4+JbIHrE5wGvch4staFnksrD3Fg= - -clone-response@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/clone-response/-/clone-response-1.0.2.tgz#d1dc973920314df67fbeb94223b4ee350239e96b" - integrity sha1-0dyXOSAxTfZ/vrlCI7TuNQI56Ws= - dependencies: - mimic-response "^1.0.0" - -clone-stats@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/clone-stats/-/clone-stats-1.0.0.tgz#b3782dff8bb5474e18b9b6bf0fdfe782f8777680" - integrity sha1-s3gt/4u1R04Yuba/D9/ngvh3doA= - -clone@^2.1.1: - version "2.1.2" - resolved "https://registry.yarnpkg.com/clone/-/clone-2.1.2.tgz#1b7f4b9f591f1e8f83670401600345a02887435f" - integrity sha1-G39Ln1kfHo+DZwQBYANFoCiHQ18= - -cloneable-readable@^1.0.0: - version "1.1.3" - resolved "https://registry.yarnpkg.com/cloneable-readable/-/cloneable-readable-1.1.3.tgz#120a00cb053bfb63a222e709f9683ea2e11d8cec" - integrity sha512-2EF8zTQOxYq70Y4XKtorQupqF0m49MBz2/yf5Bj+MHjvpG3Hy7sImifnqD6UA+TKYxeSV+u6qqQPawN5UvnpKQ== - dependencies: - inherits "^2.0.1" - process-nextick-args "^2.0.0" - readable-stream "^2.3.5" - -code-point-at@^1.0.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/code-point-at/-/code-point-at-1.1.0.tgz#0d070b4d043a5bea33a2f1a40e2edb3d9a4ccf77" - integrity sha1-DQcLTQQ6W+ozovGkDi7bPZpMz3c= - -collection-map@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/collection-map/-/collection-map-1.0.0.tgz#aea0f06f8d26c780c2b75494385544b2255af18c" - integrity sha1-rqDwb40mx4DCt1SUOFVEsiVa8Yw= - dependencies: - arr-map "^2.0.2" - for-own "^1.0.0" - make-iterator "^1.0.0" - -collection-visit@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/collection-visit/-/collection-visit-1.0.0.tgz#4bc0373c164bc3291b4d368c829cf1a80a59dca0" - integrity sha1-S8A3PBZLwykbTTaMgpzxqApZ3KA= - dependencies: - map-visit "^1.0.0" - object-visit "^1.0.0" - -color-convert@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-2.0.1.tgz#72d3a68d598c9bdb3af2ad1e84f21d896abd4de3" - integrity sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ== - dependencies: - color-name "~1.1.4" - -color-name@~1.1.4: - version "1.1.4" - resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2" - integrity sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA== - -color-support@^1.1.3: - version "1.1.3" - resolved "https://registry.yarnpkg.com/color-support/-/color-support-1.1.3.tgz#93834379a1cc9a0c61f82f52f0d04322251bd5a2" - integrity sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg== - -colors@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/colors/-/colors-1.4.0.tgz#c50491479d4c1bdaed2c9ced32cf7c7dc2360f78" - integrity sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA== - -commander@~6.1: - version "6.1.0" - resolved "https://registry.yarnpkg.com/commander/-/commander-6.1.0.tgz#f8d722b78103141006b66f4c7ba1e97315ba75bc" - integrity sha512-wl7PNrYWd2y5mp1OK/LhTlv8Ff4kQJQRXXAvF+uU/TPNiVJUxZLRYGj/B0y/lPGAVcSbJqH2Za/cvHmrPMC8mA== - -component-emitter@^1.2.1: - version "1.3.0" - resolved "https://registry.yarnpkg.com/component-emitter/-/component-emitter-1.3.0.tgz#16e4070fba8ae29b679f2215853ee181ab2eabc0" - integrity sha512-Rd3se6QB+sO1TwqZjscQrurpEPIfO0/yYnSin6Q/rD3mOutHvUrCAhJub3r90uNb+SESBuE0QYoB90YdfatsRg== - -concat-map@0.0.1: - version "0.0.1" - resolved "https://registry.yarnpkg.com/concat-map/-/concat-map-0.0.1.tgz#d8a96bd77fd68df7793a73036a3ba0d5405d477b" - integrity sha1-2Klr13/Wjfd5OnMDajug1UBdR3s= - -concat-stream@^1.6.0: - version "1.6.2" - resolved "https://registry.yarnpkg.com/concat-stream/-/concat-stream-1.6.2.tgz#904bdf194cd3122fc675c77fc4ac3d4ff0fd1a34" - integrity sha512-27HBghJxjiZtIk3Ycvn/4kbJk/1uZuJFfuPEns6LaEvpvG1f0hTea8lilrouyo9mVc2GWdcEZ8OLoGmSADlrCw== - dependencies: - buffer-from "^1.0.0" - inherits "^2.0.3" - readable-stream "^2.2.2" - typedarray "^0.0.6" - -connect-livereload@^0.6.0: - version "0.6.1" - resolved "https://registry.yarnpkg.com/connect-livereload/-/connect-livereload-0.6.1.tgz#1ac0c8bb9d9cfd5b28b629987a56a9239db9baaa" - integrity sha512-3R0kMOdL7CjJpU66fzAkCe6HNtd3AavCS4m+uW4KtJjrdGPT0SQEZieAYd+cm+lJoBznNQ4lqipYWkhBMgk00g== - -connect@^3.6.6: - version "3.7.0" - resolved "https://registry.yarnpkg.com/connect/-/connect-3.7.0.tgz#5d49348910caa5e07a01800b030d0c35f20484f8" - integrity sha512-ZqRXc+tZukToSNmh5C2iWMSoV3X1YUcPbqEM4DkEG5tNQXrQUZCNVGGv3IuicnkMtPfGf3Xtp8WCXs295iQ1pQ== - dependencies: - debug "2.6.9" - finalhandler "1.1.2" - parseurl "~1.3.3" - utils-merge "1.0.1" - -continuable-cache@^0.3.1: - version "0.3.1" - resolved "https://registry.yarnpkg.com/continuable-cache/-/continuable-cache-0.3.1.tgz#bd727a7faed77e71ff3985ac93351a912733ad0f" - integrity sha1-vXJ6f67XfnH/OYWskzUakSczrQ8= - -convert-source-map@^1.5.0: - version "1.7.0" - resolved "https://registry.yarnpkg.com/convert-source-map/-/convert-source-map-1.7.0.tgz#17a2cb882d7f77d3490585e2ce6c524424a3a442" - integrity sha512-4FJkXzKXEDB1snCFZlLP4gpC3JILicCpGbzG9f9G7tGqGCzETQ2hWPrcinA9oU4wtf2biUaEH5065UnMeR33oA== - dependencies: - safe-buffer "~5.1.1" - -convict@~6.0: - version "6.0.0" - resolved "https://registry.yarnpkg.com/convict/-/convict-6.0.0.tgz#4be829f001a778d337d32ec79e9ae7f2e39df1a6" - integrity sha512-osfPkv5yjVoZqrTWBXuh/ABGpFoaJplbt0WXr0CodR4CSWt8UnzY4PSUyRz/+5BX5YUtWcToG29Kr0B6xhdIMg== - dependencies: - lodash.clonedeep "^4.5.0" - yargs-parser "^18.1.3" - -copy-descriptor@^0.1.0: - version "0.1.1" - resolved "https://registry.yarnpkg.com/copy-descriptor/-/copy-descriptor-0.1.1.tgz#676f6eb3c39997c2ee1ac3a924fd6124748f578d" - integrity sha1-Z29us8OZl8LuGsOpJP1hJHSPV40= - -copy-props@^2.0.1: - version "2.0.4" - resolved "https://registry.yarnpkg.com/copy-props/-/copy-props-2.0.4.tgz#93bb1cadfafd31da5bb8a9d4b41f471ec3a72dfe" - integrity sha512-7cjuUME+p+S3HZlbllgsn2CDwS+5eCCX16qBgNC4jgSTf49qR1VKy/Zhl400m0IQXl/bPGEVqncgUUMjrr4s8A== - dependencies: - each-props "^1.3.0" - is-plain-object "^2.0.1" - -core-util-is@~1.0.0: - version "1.0.2" - resolved "https://registry.yarnpkg.com/core-util-is/-/core-util-is-1.0.2.tgz#b5fd54220aa2bc5ab57aab7140c940754503c1a7" - integrity sha1-tf1UIgqivFq1eqtxQMlAdUUDwac= - -corser@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/corser/-/corser-2.0.1.tgz#8eda252ecaab5840dcd975ceb90d9370c819ff87" - integrity sha1-jtolLsqrWEDc2XXOuQ2TcMgZ/4c= - -crc-32@^1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/crc-32/-/crc-32-1.2.0.tgz#cb2db6e29b88508e32d9dd0ec1693e7b41a18208" - integrity sha512-1uBwHxF+Y/4yF5G48fwnKq6QsIXheor3ZLPT80yGBV1oEUwpPojlEhQbWKVw1VwcTQyMGHK1/XMmTjmlsmTTGA== - dependencies: - exit-on-epipe "~1.0.1" - printj "~1.1.0" - -d@1, d@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/d/-/d-1.0.1.tgz#8698095372d58dbee346ffd0c7093f99f8f9eb5a" - integrity sha512-m62ShEObQ39CfralilEQRjH6oAMtNCV1xJyEx5LpRYUVN+EviphDgUc/F3hnYbADmkiNs67Y+3ylmlG7Lnu+FA== - dependencies: - es5-ext "^0.10.50" - type "^1.0.1" - -debug@2.6.9, debug@^2.2.0, debug@^2.3.3: - version "2.6.9" - resolved "https://registry.yarnpkg.com/debug/-/debug-2.6.9.tgz#5d128515df134ff327e90a4c93f4e077a536341f" - integrity sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA== - dependencies: - ms "2.0.0" - -debug@^3.1.0, debug@^3.1.1: - version "3.2.7" - resolved "https://registry.yarnpkg.com/debug/-/debug-3.2.7.tgz#72580b7e9145fb39b6676f9c5e5fb100b934179a" - integrity sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ== - dependencies: - ms "^2.1.1" - -decamelize@^1.1.1, decamelize@^1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/decamelize/-/decamelize-1.2.0.tgz#f6534d15148269b20352e7bee26f501f9a191290" - integrity sha1-9lNNFRSCabIDUue+4m9QH5oZEpA= - -decode-uri-component@^0.2.0: - version "0.2.0" - resolved "https://registry.yarnpkg.com/decode-uri-component/-/decode-uri-component-0.2.0.tgz#eb3913333458775cb84cd1a1fae062106bb87545" - integrity sha1-6zkTMzRYd1y4TNGh+uBiEGu4dUU= - -decompress-response@^3.3.0: - version "3.3.0" - resolved "https://registry.yarnpkg.com/decompress-response/-/decompress-response-3.3.0.tgz#80a4dd323748384bfa248083622aedec982adff3" - integrity sha1-gKTdMjdIOEv6JICDYirt7Jgq3/M= - dependencies: - mimic-response "^1.0.0" - -decompress-response@^4.2.0: - version "4.2.1" - resolved "https://registry.yarnpkg.com/decompress-response/-/decompress-response-4.2.1.tgz#414023cc7a302da25ce2ec82d0d5238ccafd8986" - integrity sha512-jOSne2qbyE+/r8G1VU+G/82LBs2Fs4LAsTiLSHOCOMZQl2OKZ6i8i4IyHemTe+/yIXOtTcRQMzPcgyhoFlqPkw== - dependencies: - mimic-response "^2.0.0" - -default-compare@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/default-compare/-/default-compare-1.0.0.tgz#cb61131844ad84d84788fb68fd01681ca7781a2f" - integrity sha512-QWfXlM0EkAbqOCbD/6HjdwT19j7WCkMyiRhWilc4H9/5h/RzTF9gv5LYh1+CmDV5d1rki6KAWLtQale0xt20eQ== - dependencies: - kind-of "^5.0.2" - -default-resolution@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/default-resolution/-/default-resolution-2.0.0.tgz#bcb82baa72ad79b426a76732f1a81ad6df26d684" - integrity sha1-vLgrqnKtebQmp2cy8aga1t8m1oQ= - -defer-to-connect@^1.0.1: - version "1.1.3" - resolved "https://registry.yarnpkg.com/defer-to-connect/-/defer-to-connect-1.1.3.tgz#331ae050c08dcf789f8c83a7b81f0ed94f4ac591" - integrity sha512-0ISdNousHvZT2EiFlZeZAHBUvSxmKswVCEf8hW7KWgG4a8MVEu/3Vb6uWYozkjylyCxe0JBIiRB1jV45S70WVQ== - -define-properties@^1.1.3: - version "1.1.3" - resolved "https://registry.yarnpkg.com/define-properties/-/define-properties-1.1.3.tgz#cf88da6cbee26fe6db7094f61d870cbd84cee9f1" - integrity sha512-3MqfYKj2lLzdMSf8ZIZE/V+Zuy+BgD6f164e8K2w7dgnpKArBDerGYpM46IYYcjnkdPNMjPk9A6VFB8+3SKlXQ== - dependencies: - object-keys "^1.0.12" - -define-property@^0.2.5: - version "0.2.5" - resolved "https://registry.yarnpkg.com/define-property/-/define-property-0.2.5.tgz#c35b1ef918ec3c990f9a5bc57be04aacec5c8116" - integrity sha1-w1se+RjsPJkPmlvFe+BKrOxcgRY= - dependencies: - is-descriptor "^0.1.0" - -define-property@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/define-property/-/define-property-1.0.0.tgz#769ebaaf3f4a63aad3af9e8d304c9bbe79bfb0e6" - integrity sha1-dp66rz9KY6rTr56NMEybvnm/sOY= - dependencies: - is-descriptor "^1.0.0" - -define-property@^2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/define-property/-/define-property-2.0.2.tgz#d459689e8d654ba77e02a817f8710d702cb16e9d" - integrity sha512-jwK2UV4cnPpbcG7+VRARKTZPUWowwXA8bzH5NP6ud0oeAxyYPuGZUAC7hMugpCdz4BeSZl2Dl9k66CHJ/46ZYQ== - dependencies: - is-descriptor "^1.0.2" - isobject "^3.0.1" - -depd@~1.1.2: - version "1.1.2" - resolved "https://registry.yarnpkg.com/depd/-/depd-1.1.2.tgz#9bcd52e14c097763e749b274c4346ed2e560b5a9" - integrity sha1-m81S4UwJd2PnSbJ0xDRu0uVgtak= - -destroy@~1.0.4: - version "1.0.4" - resolved "https://registry.yarnpkg.com/destroy/-/destroy-1.0.4.tgz#978857442c44749e4206613e37946205826abd80" - integrity sha1-l4hXRCxEdJ5CBmE+N5RiBYJqvYA= - -detect-file@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/detect-file/-/detect-file-1.0.0.tgz#f0d66d03672a825cb1b73bdb3fe62310c8e552b7" - integrity sha1-8NZtA2cqglyxtzvbP+YjEMjlUrc= - -diff3@0.0.3: - version "0.0.3" - resolved "https://registry.yarnpkg.com/diff3/-/diff3-0.0.3.tgz#d4e5c3a4cdf4e5fe1211ab42e693fcb4321580fc" - integrity sha1-1OXDpM305f4SEatC5pP8tDIVgPw= - -duplexer3@^0.1.4: - version "0.1.4" - resolved "https://registry.yarnpkg.com/duplexer3/-/duplexer3-0.1.4.tgz#ee01dd1cac0ed3cbc7fdbea37dc0a8f1ce002ce2" - integrity sha1-7gHdHKwO08vH/b6jfcCo8c4ALOI= - -duplexify@^3.6.0: - version "3.7.1" - resolved "https://registry.yarnpkg.com/duplexify/-/duplexify-3.7.1.tgz#2a4df5317f6ccfd91f86d6fd25d8d8a103b88309" - integrity sha512-07z8uv2wMyS51kKhD1KsdXJg5WQ6t93RneqRxUHnskXVtlYYkLqM0gqStQZ3pj073g687jPCHrqNfCzawLYh5g== - dependencies: - end-of-stream "^1.0.0" - inherits "^2.0.1" - readable-stream "^2.0.0" - stream-shift "^1.0.0" - -each-props@^1.3.0: - version "1.3.2" - resolved "https://registry.yarnpkg.com/each-props/-/each-props-1.3.2.tgz#ea45a414d16dd5cfa419b1a81720d5ca06892333" - integrity sha512-vV0Hem3zAGkJAyU7JSjixeU66rwdynTAa1vofCrSA5fEln+m67Az9CcnkVD776/fsN/UjIWmBDoNRS6t6G9RfA== - dependencies: - is-plain-object "^2.0.1" - object.defaults "^1.1.0" - -ecstatic@^3.3.2: - version "3.3.2" - resolved "https://registry.yarnpkg.com/ecstatic/-/ecstatic-3.3.2.tgz#6d1dd49814d00594682c652adb66076a69d46c48" - integrity sha512-fLf9l1hnwrHI2xn9mEDT7KIi22UDqA2jaCwyCbSUJh9a1V+LEUSL/JO/6TIz/QyuBURWUHrFL5Kg2TtO1bkkog== - dependencies: - he "^1.1.1" - mime "^1.6.0" - minimist "^1.1.0" - url-join "^2.0.5" - -ee-first@1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/ee-first/-/ee-first-1.1.1.tgz#590c61156b0ae2f4f0255732a158b266bc56b21d" - integrity sha1-WQxhFWsK4vTwJVcyoViyZrxWsh0= - -emoji-regex@^8.0.0: - version "8.0.0" - resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-8.0.0.tgz#e818fd69ce5ccfcb404594f842963bf53164cc37" - integrity sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A== - -encodeurl@~1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/encodeurl/-/encodeurl-1.0.2.tgz#ad3ff4c86ec2d029322f5a02c3a9a606c95b3f59" - integrity sha1-rT/0yG7C0CkyL1oCw6mmBslbP1k= - -end-of-stream@^1.0.0, end-of-stream@^1.1.0: - version "1.4.4" - resolved "https://registry.yarnpkg.com/end-of-stream/-/end-of-stream-1.4.4.tgz#5ae64a5f45057baf3626ec14da0ca5e4b2431eb0" - integrity sha512-+uw1inIHVPQoaVuHzRyXd21icM+cnt4CzD5rW+NC1wjOUSTOs+Te7FOv7AhN7vS9x/oIyhLP5PR1H+phQAHu5Q== - dependencies: - once "^1.4.0" - -error-ex@^1.2.0: - version "1.3.2" - resolved "https://registry.yarnpkg.com/error-ex/-/error-ex-1.3.2.tgz#b4ac40648107fdcdcfae242f428bea8a14d4f1bf" - integrity sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g== - dependencies: - is-arrayish "^0.2.1" - -error@^7.0.0: - version "7.2.1" - resolved "https://registry.yarnpkg.com/error/-/error-7.2.1.tgz#eab21a4689b5f684fc83da84a0e390de82d94894" - integrity sha512-fo9HBvWnx3NGUKMvMwB/CBCMMrfEJgbDTVDEkPygA3Bdd3lM1OyCd+rbQ8BwnpF6GdVeOLDNmyL4N5Bg80ZvdA== - dependencies: - string-template "~0.2.1" - -es5-ext@^0.10.35, es5-ext@^0.10.46, es5-ext@^0.10.50: - version "0.10.53" - resolved "https://registry.yarnpkg.com/es5-ext/-/es5-ext-0.10.53.tgz#93c5a3acfdbef275220ad72644ad02ee18368de1" - integrity sha512-Xs2Stw6NiNHWypzRTY1MtaG/uJlwCk8kH81920ma8mvN8Xq1gsfhZvpkImLQArw8AHnv8MT2I45J3c0R8slE+Q== - dependencies: - es6-iterator "~2.0.3" - es6-symbol "~3.1.3" - next-tick "~1.0.0" - -es6-iterator@^2.0.1, es6-iterator@^2.0.3, es6-iterator@~2.0.3: - version "2.0.3" - resolved "https://registry.yarnpkg.com/es6-iterator/-/es6-iterator-2.0.3.tgz#a7de889141a05a94b0854403b2d0a0fbfa98f3b7" - integrity sha1-p96IkUGgWpSwhUQDstCg+/qY87c= - dependencies: - d "1" - es5-ext "^0.10.35" - es6-symbol "^3.1.1" - -es6-symbol@^3.1.1, es6-symbol@~3.1.3: - version "3.1.3" - resolved "https://registry.yarnpkg.com/es6-symbol/-/es6-symbol-3.1.3.tgz#bad5d3c1bcdac28269f4cb331e431c78ac705d18" - integrity sha512-NJ6Yn3FuDinBaBRWl/q5X/s4koRHBrgKAu+yGI6JCBeiu3qrcbJhwT2GeR/EXVfylRk8dpQVJoLEFhK+Mu31NA== - dependencies: - d "^1.0.1" - ext "^1.1.2" - -es6-weak-map@^2.0.1: - version "2.0.3" - resolved "https://registry.yarnpkg.com/es6-weak-map/-/es6-weak-map-2.0.3.tgz#b6da1f16cc2cc0d9be43e6bdbfc5e7dfcdf31d53" - integrity sha512-p5um32HOTO1kP+w7PRnB+5lQ43Z6muuMuIMffvDN8ZB4GcnjLBV6zGStpbASIMk4DCAvEaamhe2zhyCb/QXXsA== - dependencies: - d "1" - es5-ext "^0.10.46" - es6-iterator "^2.0.3" - es6-symbol "^3.1.1" - -escape-html@~1.0.3: - version "1.0.3" - resolved "https://registry.yarnpkg.com/escape-html/-/escape-html-1.0.3.tgz#0258eae4d3d0c0974de1c169188ef0051d1d1988" - integrity sha1-Aljq5NPQwJdN4cFpGI7wBR0dGYg= - -escape-string-regexp@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz#a30304e99daa32e23b2fd20f51babd07cffca344" - integrity sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w== - -esprima@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71" - integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A== - -etag@~1.8.1: - version "1.8.1" - resolved "https://registry.yarnpkg.com/etag/-/etag-1.8.1.tgz#41ae2eeb65efa62268aebfea83ac7d79299b0887" - integrity sha1-Qa4u62XvpiJorr/qg6x9eSmbCIc= - -eventemitter3@^4.0.0: - version "4.0.7" - resolved "https://registry.yarnpkg.com/eventemitter3/-/eventemitter3-4.0.7.tgz#2de9b68f6528d5644ef5c59526a1b4a07306169f" - integrity sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw== - -exit-on-epipe@~1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/exit-on-epipe/-/exit-on-epipe-1.0.1.tgz#0bdd92e87d5285d267daa8171d0eb06159689692" - integrity sha512-h2z5mrROTxce56S+pnvAV890uu7ls7f1kEvVGJbw1OlFH3/mlJ5bkXu0KRyW94v37zzHPiUd55iLn3DA7TjWpw== - -expand-brackets@^2.1.4: - version "2.1.4" - resolved "https://registry.yarnpkg.com/expand-brackets/-/expand-brackets-2.1.4.tgz#b77735e315ce30f6b6eff0f83b04151a22449622" - integrity sha1-t3c14xXOMPa27/D4OwQVGiJEliI= - dependencies: - debug "^2.3.3" - define-property "^0.2.5" - extend-shallow "^2.0.1" - posix-character-classes "^0.1.0" - regex-not "^1.0.0" - snapdragon "^0.8.1" - to-regex "^3.0.1" - -expand-tilde@^2.0.0, expand-tilde@^2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/expand-tilde/-/expand-tilde-2.0.2.tgz#97e801aa052df02454de46b02bf621642cdc8502" - integrity sha1-l+gBqgUt8CRU3kawK/YhZCzchQI= - dependencies: - homedir-polyfill "^1.0.1" - -ext@^1.1.2: - version "1.4.0" - resolved "https://registry.yarnpkg.com/ext/-/ext-1.4.0.tgz#89ae7a07158f79d35517882904324077e4379244" - integrity sha512-Key5NIsUxdqKg3vIsdw9dSuXpPCQ297y6wBjL30edxwPgt2E44WcWBZey/ZvUc6sERLTxKdyCu4gZFmUbk1Q7A== - dependencies: - type "^2.0.0" - -extend-shallow@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/extend-shallow/-/extend-shallow-2.0.1.tgz#51af7d614ad9a9f610ea1bafbb989d6b1c56890f" - integrity sha1-Ua99YUrZqfYQ6huvu5idaxxWiQ8= - dependencies: - is-extendable "^0.1.0" - -extend-shallow@^3.0.0, extend-shallow@^3.0.2: - version "3.0.2" - resolved "https://registry.yarnpkg.com/extend-shallow/-/extend-shallow-3.0.2.tgz#26a71aaf073b39fb2127172746131c2704028db8" - integrity sha1-Jqcarwc7OfshJxcnRhMcJwQCjbg= - dependencies: - assign-symbols "^1.0.0" - is-extendable "^1.0.1" - -extend@^3.0.0: - version "3.0.2" - resolved "https://registry.yarnpkg.com/extend/-/extend-3.0.2.tgz#f8b1136b4071fbd8eb140aff858b1019ec2915fa" - integrity sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g== - -extglob@^2.0.4: - version "2.0.4" - resolved "https://registry.yarnpkg.com/extglob/-/extglob-2.0.4.tgz#ad00fe4dc612a9232e8718711dc5cb5ab0285543" - integrity sha512-Nmb6QXkELsuBr24CJSkilo6UHHgbekK5UiZgfE6UHD3Eb27YC6oD+bhcT+tJ6cl8dmsgdQxnWlcry8ksBIBLpw== - dependencies: - array-unique "^0.3.2" - define-property "^1.0.0" - expand-brackets "^2.1.4" - extend-shallow "^2.0.1" - fragment-cache "^0.2.1" - regex-not "^1.0.0" - snapdragon "^0.8.1" - to-regex "^3.0.1" - -fancy-log@^1.3.2: - version "1.3.3" - resolved "https://registry.yarnpkg.com/fancy-log/-/fancy-log-1.3.3.tgz#dbc19154f558690150a23953a0adbd035be45fc7" - integrity sha512-k9oEhlyc0FrVh25qYuSELjr8oxsCoc4/LEZfg2iJJrfEk/tZL9bCoJE47gqAvI2m/AUjluCS4+3I0eTx8n3AEw== - dependencies: - ansi-gray "^0.1.1" - color-support "^1.1.3" - parse-node-version "^1.0.0" - time-stamp "^1.0.0" - -fast-levenshtein@^1.0.0: - version "1.1.4" - resolved "https://registry.yarnpkg.com/fast-levenshtein/-/fast-levenshtein-1.1.4.tgz#e6a754cc8f15e58987aa9cbd27af66fd6f4e5af9" - integrity sha1-5qdUzI8V5YmHqpy9J69m/W9OWvk= - -faye-websocket@~0.10.0: - version "0.10.0" - resolved "https://registry.yarnpkg.com/faye-websocket/-/faye-websocket-0.10.0.tgz#4e492f8d04dfb6f89003507f6edbf2d501e7c6f4" - integrity sha1-TkkvjQTftviQA1B/btvy1QHnxvQ= - dependencies: - websocket-driver ">=0.5.1" - -fd-slicer@~1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/fd-slicer/-/fd-slicer-1.1.0.tgz#25c7c89cb1f9077f8891bbe61d8f390eae256f1e" - integrity sha1-JcfInLH5B3+IkbvmHY85Dq4lbx4= - dependencies: - pend "~1.2.0" - -file-uri-to-path@1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz#553a7b8446ff6f684359c445f1e37a05dacc33dd" - integrity sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw== - -fill-range@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/fill-range/-/fill-range-4.0.0.tgz#d544811d428f98eb06a63dc402d2403c328c38f7" - integrity sha1-1USBHUKPmOsGpj3EAtJAPDKMOPc= - dependencies: - extend-shallow "^2.0.1" - is-number "^3.0.0" - repeat-string "^1.6.1" - to-regex-range "^2.1.0" - -fill-range@^7.0.1: - version "7.0.1" - resolved "https://registry.yarnpkg.com/fill-range/-/fill-range-7.0.1.tgz#1919a6a7c75fe38b2c7c77e5198535da9acdda40" - integrity sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ== - dependencies: - to-regex-range "^5.0.1" - -finalhandler@1.1.2: - version "1.1.2" - resolved "https://registry.yarnpkg.com/finalhandler/-/finalhandler-1.1.2.tgz#b7e7d000ffd11938d0fdb053506f6ebabe9f587d" - integrity sha512-aAWcW57uxVNrQZqFXjITpW3sIUQmHGG3qSb9mUah9MgMC4NeWhNOlNjXEYq3HjRAvL6arUviZGGJsBg6z0zsWA== - dependencies: - debug "2.6.9" - encodeurl "~1.0.2" - escape-html "~1.0.3" - on-finished "~2.3.0" - parseurl "~1.3.3" - statuses "~1.5.0" - unpipe "~1.0.0" - -find-up@^1.0.0: - version "1.1.2" - resolved "https://registry.yarnpkg.com/find-up/-/find-up-1.1.2.tgz#6b2e9822b1a2ce0a60ab64d610eccad53cb24d0f" - integrity sha1-ay6YIrGizgpgq2TWEOzK1TyyTQ8= - dependencies: - path-exists "^2.0.0" - pinkie-promise "^2.0.0" - -find-up@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/find-up/-/find-up-4.1.0.tgz#97afe7d6cdc0bc5928584b7c8d7b16e8a9aa5d19" - integrity sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw== - dependencies: - locate-path "^5.0.0" - path-exists "^4.0.0" - -findup-sync@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/findup-sync/-/findup-sync-2.0.0.tgz#9326b1488c22d1a6088650a86901b2d9a90a2cbc" - integrity sha1-kyaxSIwi0aYIhlCoaQGy2akKLLw= - dependencies: - detect-file "^1.0.0" - is-glob "^3.1.0" - micromatch "^3.0.4" - resolve-dir "^1.0.1" - -findup-sync@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/findup-sync/-/findup-sync-3.0.0.tgz#17b108f9ee512dfb7a5c7f3c8b27ea9e1a9c08d1" - integrity sha512-YbffarhcicEhOrm4CtrwdKBdCuz576RLdhJDsIfvNtxUuhdRet1qZcsMjqbePtAseKdAnDyM/IyXbu7PRPRLYg== - dependencies: - detect-file "^1.0.0" - is-glob "^4.0.0" - micromatch "^3.0.4" - resolve-dir "^1.0.1" - -fined@^1.0.1: - version "1.2.0" - resolved "https://registry.yarnpkg.com/fined/-/fined-1.2.0.tgz#d00beccf1aa2b475d16d423b0238b713a2c4a37b" - integrity sha512-ZYDqPLGxDkDhDZBjZBb+oD1+j0rA4E0pXY50eplAAOPg2N/gUBSSk5IM1/QhPfyVo19lJ+CvXpqfvk+b2p/8Ng== - dependencies: - expand-tilde "^2.0.2" - is-plain-object "^2.0.3" - object.defaults "^1.1.0" - object.pick "^1.2.0" - parse-filepath "^1.0.1" - -flagged-respawn@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/flagged-respawn/-/flagged-respawn-1.0.1.tgz#e7de6f1279ddd9ca9aac8a5971d618606b3aab41" - integrity sha512-lNaHNVymajmk0OJMBn8fVUAU1BtDeKIqKoVhk4xAALB57aALg6b4W0MfJ/cUE0g9YBXy5XhSlPIpYIJ7HaY/3Q== - -flush-write-stream@^1.0.2: - version "1.1.1" - resolved "https://registry.yarnpkg.com/flush-write-stream/-/flush-write-stream-1.1.1.tgz#8dd7d873a1babc207d94ead0c2e0e44276ebf2e8" - integrity sha512-3Z4XhFZ3992uIq0XOqb9AreonueSYphE6oYbpt5+3u06JWklbsPkNv3ZKkP9Bz/r+1MWCaMoSQ28P85+1Yc77w== - dependencies: - inherits "^2.0.3" - readable-stream "^2.3.6" - -follow-redirects@^1.0.0: - version "1.13.1" - resolved "https://registry.yarnpkg.com/follow-redirects/-/follow-redirects-1.13.1.tgz#5f69b813376cee4fd0474a3aba835df04ab763b7" - integrity sha512-SSG5xmZh1mkPGyKzjZP8zLjltIfpW32Y5QpdNJyjcfGxK3qo3NDDkZOZSFiGn1A6SclQxY9GzEwAHQ3dmYRWpg== - -for-in@^1.0.1, for-in@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/for-in/-/for-in-1.0.2.tgz#81068d295a8142ec0ac726c6e2200c30fb6d5e80" - integrity sha1-gQaNKVqBQuwKxybG4iAMMPttXoA= - -for-own@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/for-own/-/for-own-1.0.0.tgz#c63332f415cedc4b04dbfe70cf836494c53cb44b" - integrity sha1-xjMy9BXO3EsE2/5wz4NklMU8tEs= - dependencies: - for-in "^1.0.1" - -fragment-cache@^0.2.1: - version "0.2.1" - resolved "https://registry.yarnpkg.com/fragment-cache/-/fragment-cache-0.2.1.tgz#4290fad27f13e89be7f33799c6bc5a0abfff0d19" - integrity sha1-QpD60n8T6Jvn8zeZxrxaCr//DRk= - dependencies: - map-cache "^0.2.2" - -fresh@0.5.2: - version "0.5.2" - resolved "https://registry.yarnpkg.com/fresh/-/fresh-0.5.2.tgz#3d8cadd90d976569fa835ab1f8e4b23a105605a7" - integrity sha1-PYyt2Q2XZWn6g1qx+OSyOhBWBac= - -fs-extra@~8.1: - version "8.1.0" - resolved "https://registry.yarnpkg.com/fs-extra/-/fs-extra-8.1.0.tgz#49d43c45a88cd9677668cb7be1b46efdb8d2e1c0" - integrity sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g== - dependencies: - graceful-fs "^4.2.0" - jsonfile "^4.0.0" - universalify "^0.1.0" - -fs-mkdirp-stream@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/fs-mkdirp-stream/-/fs-mkdirp-stream-1.0.0.tgz#0b7815fc3201c6a69e14db98ce098c16935259eb" - integrity sha1-C3gV/DIBxqaeFNuYzgmMFpNSWes= - dependencies: - graceful-fs "^4.1.11" - through2 "^2.0.3" - -fs.realpath@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/fs.realpath/-/fs.realpath-1.0.0.tgz#1504ad2523158caa40db4a2787cb01411994ea4f" - integrity sha1-FQStJSMVjKpA20onh8sBQRmU6k8= - -fsevents@^1.2.7: - version "1.2.13" - resolved "https://registry.yarnpkg.com/fsevents/-/fsevents-1.2.13.tgz#f325cb0455592428bcf11b383370ef70e3bfcc38" - integrity sha512-oWb1Z6mkHIskLzEJ/XWX0srkpkTQ7vaopMQkyaEIoq0fmtFVxOthb8cCxeT+p3ynTdkk/RZwbgG4brR5BeWECw== - dependencies: - bindings "^1.5.0" - nan "^2.12.1" - -function-bind@^1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/function-bind/-/function-bind-1.1.1.tgz#a56899d3ea3c9bab874bb9773b7c5ede92f4895d" - integrity sha512-yIovAzMX49sF8Yl58fSCWJ5svSLuaibPxXQJFLmBObTuCr0Mf1KiPopGM9NiFjiYBCbfaa2Fh6breQ6ANVTI0A== - -get-caller-file@^1.0.1: - version "1.0.3" - resolved "https://registry.yarnpkg.com/get-caller-file/-/get-caller-file-1.0.3.tgz#f978fa4c90d1dfe7ff2d6beda2a515e713bdcf4a" - integrity sha512-3t6rVToeoZfYSGd8YoLFR2DJkiQrIiUrGcjvFX2mDw3bn6k2OtwHN0TNCLbBO+w8qTvimhDkv+LSscbJY1vE6w== - -get-caller-file@^2.0.1: - version "2.0.5" - resolved "https://registry.yarnpkg.com/get-caller-file/-/get-caller-file-2.0.5.tgz#4f94412a82db32f36e3b0b9741f8a97feb031f7e" - integrity sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg== - -get-intrinsic@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/get-intrinsic/-/get-intrinsic-1.0.2.tgz#6820da226e50b24894e08859469dc68361545d49" - integrity sha512-aeX0vrFm21ILl3+JpFFRNe9aUvp6VFZb2/CTbgLb8j75kOhvoNYjt9d8KA/tJG4gSo8nzEDedRl0h7vDmBYRVg== - dependencies: - function-bind "^1.1.1" - has "^1.0.3" - has-symbols "^1.0.1" - -get-stream@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/get-stream/-/get-stream-4.1.0.tgz#c1b255575f3dc21d59bfc79cd3d2b46b1c3a54b5" - integrity sha512-GMat4EJ5161kIy2HevLlr4luNjBgvmj413KaQA7jt4V8B4RDsfpHk7WQ9GVqfYyyx8OS/L66Kox+rJRNklLK7w== - dependencies: - pump "^3.0.0" - -get-stream@^5.1.0: - version "5.2.0" - resolved "https://registry.yarnpkg.com/get-stream/-/get-stream-5.2.0.tgz#4966a1795ee5ace65e706c4b7beb71257d6e22d3" - integrity sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA== - dependencies: - pump "^3.0.0" - -get-value@^2.0.3, get-value@^2.0.6: - version "2.0.6" - resolved "https://registry.yarnpkg.com/get-value/-/get-value-2.0.6.tgz#dc15ca1c672387ca76bd37ac0a395ba2042a2c28" - integrity sha1-3BXKHGcjh8p2vTesCjlbogQqLCg= - -git-apply-delta@0.0.7: - version "0.0.7" - resolved "https://registry.yarnpkg.com/git-apply-delta/-/git-apply-delta-0.0.7.tgz#fb76ae144540d79440b52b31de03e63c993c7219" - integrity sha1-+3auFEVA15RAtSsx3gPmPJk8chk= - dependencies: - bops "~0.0.6" - varint "0.0.3" - -glob-parent@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/glob-parent/-/glob-parent-3.1.0.tgz#9e6af6299d8d3bd2bd40430832bd113df906c5ae" - integrity sha1-nmr2KZ2NO9K9QEMIMr0RPfkGxa4= - dependencies: - is-glob "^3.1.0" - path-dirname "^1.0.0" - -glob-stream@^6.1.0: - version "6.1.0" - resolved "https://registry.yarnpkg.com/glob-stream/-/glob-stream-6.1.0.tgz#7045c99413b3eb94888d83ab46d0b404cc7bdde4" - integrity sha1-cEXJlBOz65SIjYOrRtC0BMx73eQ= - dependencies: - extend "^3.0.0" - glob "^7.1.1" - glob-parent "^3.1.0" - is-negated-glob "^1.0.0" - ordered-read-streams "^1.0.0" - pumpify "^1.3.5" - readable-stream "^2.1.5" - remove-trailing-separator "^1.0.1" - to-absolute-glob "^2.0.0" - unique-stream "^2.0.2" - -glob-watcher@^5.0.3: - version "5.0.5" - resolved "https://registry.yarnpkg.com/glob-watcher/-/glob-watcher-5.0.5.tgz#aa6bce648332924d9a8489be41e3e5c52d4186dc" - integrity sha512-zOZgGGEHPklZNjZQaZ9f41i7F2YwE+tS5ZHrDhbBCk3stwahn5vQxnFmBJZHoYdusR6R1bLSXeGUy/BhctwKzw== - dependencies: - anymatch "^2.0.0" - async-done "^1.2.0" - chokidar "^2.0.0" - is-negated-glob "^1.0.0" - just-debounce "^1.0.0" - normalize-path "^3.0.0" - object.defaults "^1.1.0" - -glob@6.0.4: - version "6.0.4" - resolved "https://registry.yarnpkg.com/glob/-/glob-6.0.4.tgz#0f08860f6a155127b2fadd4f9ce24b1aab6e4d22" - integrity sha1-DwiGD2oVUSey+t1PnOJLGqtuTSI= - dependencies: - inflight "^1.0.4" - inherits "2" - minimatch "2 || 3" - once "^1.3.0" - path-is-absolute "^1.0.0" - -glob@7.1.3: - version "7.1.3" - resolved "https://registry.yarnpkg.com/glob/-/glob-7.1.3.tgz#3960832d3f1574108342dafd3a67b332c0969df1" - integrity sha512-vcfuiIxogLV4DlGBHIUOwI0IbrJ8HWPc4MU7HzviGeNho/UJDfi6B5p3sHeWIQ0KGIU0Jpxi5ZHxemQfLkkAwQ== - dependencies: - fs.realpath "^1.0.0" - inflight "^1.0.4" - inherits "2" - minimatch "^3.0.4" - once "^1.3.0" - path-is-absolute "^1.0.0" - -glob@^7.1.1: - version "7.1.6" - resolved "https://registry.yarnpkg.com/glob/-/glob-7.1.6.tgz#141f33b81a7c2492e125594307480c46679278a6" - integrity sha512-LwaxwyZ72Lk7vZINtNNrywX0ZuLyStrdDtabefZKAY5ZGJhVtgdznluResxNmPitE0SAO+O26sWTHeKSI2wMBA== - dependencies: - fs.realpath "^1.0.0" - inflight "^1.0.4" - inherits "2" - minimatch "^3.0.4" - once "^1.3.0" - path-is-absolute "^1.0.0" - -global-modules@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/global-modules/-/global-modules-1.0.0.tgz#6d770f0eb523ac78164d72b5e71a8877265cc3ea" - integrity sha512-sKzpEkf11GpOFuw0Zzjzmt4B4UZwjOcG757PPvrfhxcLFbq0wpsgpOqxpxtxFiCG4DtG93M6XRVbF2oGdev7bg== - dependencies: - global-prefix "^1.0.1" - is-windows "^1.0.1" - resolve-dir "^1.0.0" - -global-prefix@^1.0.1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/global-prefix/-/global-prefix-1.0.2.tgz#dbf743c6c14992593c655568cb66ed32c0122ebe" - integrity sha1-2/dDxsFJklk8ZVVoy2btMsASLr4= - dependencies: - expand-tilde "^2.0.2" - homedir-polyfill "^1.0.1" - ini "^1.3.4" - is-windows "^1.0.1" - which "^1.2.14" - -globalyzer@^0.1.4: - version "0.1.4" - resolved "https://registry.yarnpkg.com/globalyzer/-/globalyzer-0.1.4.tgz#bc8e273afe1ac7c24eea8def5b802340c5cc534f" - integrity sha512-LeguVWaxgHN0MNbWC6YljNMzHkrCny9fzjmEUdnF1kQ7wATFD1RHFRqA1qxaX2tgxGENlcxjOflopBwj3YZiXA== - -globrex@^0.1.2: - version "0.1.2" - resolved "https://registry.yarnpkg.com/globrex/-/globrex-0.1.2.tgz#dd5d9ec826232730cd6793a5e33a9302985e6098" - integrity sha512-uHJgbwAMwNFf5mLst7IWLNg14x1CkeqglJb/K3doi4dw6q2IvAAmM/Y81kevy83wP+Sst+nutFTYOGg3d1lsxg== - -glogg@^1.0.0: - version "1.0.2" - resolved "https://registry.yarnpkg.com/glogg/-/glogg-1.0.2.tgz#2d7dd702beda22eb3bffadf880696da6d846313f" - integrity sha512-5mwUoSuBk44Y4EshyiqcH95ZntbDdTQqA3QYSrxmzj28Ai0vXBGMH1ApSANH14j2sIRtqCEyg6PfsuP7ElOEDA== - dependencies: - sparkles "^1.0.0" - -got@~9.6: - version "9.6.0" - resolved "https://registry.yarnpkg.com/got/-/got-9.6.0.tgz#edf45e7d67f99545705de1f7bbeeeb121765ed85" - integrity sha512-R7eWptXuGYxwijs0eV+v3o6+XH1IqVK8dJOEecQfTmkncw9AV4dcw/Dhxi8MdlqPthxxpZyizMzyg8RTmEsG+Q== - dependencies: - "@sindresorhus/is" "^0.14.0" - "@szmarczak/http-timer" "^1.1.2" - cacheable-request "^6.0.0" - decompress-response "^3.3.0" - duplexer3 "^0.1.4" - get-stream "^4.1.0" - lowercase-keys "^1.0.1" - mimic-response "^1.0.1" - p-cancelable "^1.0.0" - to-readable-stream "^1.0.0" - url-parse-lax "^3.0.0" - -graceful-fs@^4.0.0, graceful-fs@^4.1.11, graceful-fs@^4.1.2, graceful-fs@^4.1.6, graceful-fs@^4.2.0: - version "4.2.4" - resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.4.tgz#2256bde14d3632958c465ebc96dc467ca07a29fb" - integrity sha512-WjKPNJF79dtJAVniUlGGWHYGz2jWxT6VhN/4m1NdkbZ2nOsEF+cI1Edgql5zCRhs/VsQYRvrXctxktVXZUkixw== - -gulp-cli@^2.2.0, gulp-cli@^2.3.0: - version "2.3.0" - resolved "https://registry.yarnpkg.com/gulp-cli/-/gulp-cli-2.3.0.tgz#ec0d380e29e52aa45e47977f0d32e18fd161122f" - integrity sha512-zzGBl5fHo0EKSXsHzjspp3y5CONegCm8ErO5Qh0UzFzk2y4tMvzLWhoDokADbarfZRL2pGpRp7yt6gfJX4ph7A== - dependencies: - ansi-colors "^1.0.1" - archy "^1.0.0" - array-sort "^1.0.0" - color-support "^1.1.3" - concat-stream "^1.6.0" - copy-props "^2.0.1" - fancy-log "^1.3.2" - gulplog "^1.0.0" - interpret "^1.4.0" - isobject "^3.0.1" - liftoff "^3.1.0" - matchdep "^2.0.0" - mute-stdout "^1.0.0" - pretty-hrtime "^1.0.0" - replace-homedir "^1.0.0" - semver-greatest-satisfied-range "^1.1.0" - v8flags "^3.2.0" - yargs "^7.1.0" - -gulp-connect@^5.7.0: - version "5.7.0" - resolved "https://registry.yarnpkg.com/gulp-connect/-/gulp-connect-5.7.0.tgz#7e925f5e4c34ebfedf9f318576966e8fe8840d5a" - integrity sha512-8tRcC6wgXMLakpPw9M7GRJIhxkYdgZsXwn7n56BA2bQYGLR9NOPhMzx7js+qYDy6vhNkbApGKURjAw1FjY4pNA== - dependencies: - ansi-colors "^2.0.5" - connect "^3.6.6" - connect-livereload "^0.6.0" - fancy-log "^1.3.2" - map-stream "^0.0.7" - send "^0.16.2" - serve-index "^1.9.1" - serve-static "^1.13.2" - tiny-lr "^1.1.1" - -gulp-vinyl-zip@~2.2: - version "2.2.1" - resolved "https://registry.yarnpkg.com/gulp-vinyl-zip/-/gulp-vinyl-zip-2.2.1.tgz#24a60230afeb3b88b1efba06d31653ef7145dfd8" - integrity sha512-9lwCZUkrENzP649hVQB2r+8GgeGtVrqA2fEeVDX6aYr6+yJjdczWu0r1C6WvbZdzhXcA61MtR5MEyjR9a3D7cw== - dependencies: - queue "^4.2.1" - through "^2.3.8" - through2 "^2.0.3" - vinyl "^2.0.2" - vinyl-fs "^3.0.3" - yauzl "^2.2.1" - yazl "^2.2.1" - -gulp@^4.0.2: - version "4.0.2" - resolved "https://registry.yarnpkg.com/gulp/-/gulp-4.0.2.tgz#543651070fd0f6ab0a0650c6a3e6ff5a7cb09caa" - integrity sha512-dvEs27SCZt2ibF29xYgmnwwCYZxdxhQ/+LFWlbAW8y7jt68L/65402Lz3+CKy0Ov4rOs+NERmDq7YlZaDqUIfA== - dependencies: - glob-watcher "^5.0.3" - gulp-cli "^2.2.0" - undertaker "^1.2.1" - vinyl-fs "^3.0.0" - -gulplog@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/gulplog/-/gulplog-1.0.0.tgz#e28c4d45d05ecbbed818363ce8f9c5926229ffe5" - integrity sha1-4oxNRdBey77YGDY86PnFkmIp/+U= - dependencies: - glogg "^1.0.0" - -handlebars@~4.7: - version "4.7.6" - resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.6.tgz#d4c05c1baf90e9945f77aa68a7a219aa4a7df74e" - integrity sha512-1f2BACcBfiwAfStCKZNrUCgqNZkGsAT7UM3kkYtXuLo0KnaVfjKOyf7PRzB6++aK9STyT1Pd2ZCPe3EGOXleXA== - dependencies: - minimist "^1.2.5" - neo-async "^2.6.0" - source-map "^0.6.1" - wordwrap "^1.0.0" - optionalDependencies: - uglify-js "^3.1.4" - -has-symbols@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/has-symbols/-/has-symbols-1.0.1.tgz#9f5214758a44196c406d9bd76cebf81ec2dd31e8" - integrity sha512-PLcsoqu++dmEIZB+6totNFKq/7Do+Z0u4oT0zKOJNl3lYK6vGwwu2hjHs+68OEZbTjiUE9bgOABXbP/GvrS0Kg== - -has-value@^0.3.1: - version "0.3.1" - resolved "https://registry.yarnpkg.com/has-value/-/has-value-0.3.1.tgz#7b1f58bada62ca827ec0a2078025654845995e1f" - integrity sha1-ex9YutpiyoJ+wKIHgCVlSEWZXh8= - dependencies: - get-value "^2.0.3" - has-values "^0.1.4" - isobject "^2.0.0" - -has-value@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/has-value/-/has-value-1.0.0.tgz#18b281da585b1c5c51def24c930ed29a0be6b177" - integrity sha1-GLKB2lhbHFxR3vJMkw7SmgvmsXc= - dependencies: - get-value "^2.0.6" - has-values "^1.0.0" - isobject "^3.0.0" - -has-values@^0.1.4: - version "0.1.4" - resolved "https://registry.yarnpkg.com/has-values/-/has-values-0.1.4.tgz#6d61de95d91dfca9b9a02089ad384bff8f62b771" - integrity sha1-bWHeldkd/Km5oCCJrThL/49it3E= - -has-values@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/has-values/-/has-values-1.0.0.tgz#95b0b63fec2146619a6fe57fe75628d5a39efe4f" - integrity sha1-lbC2P+whRmGab+V/51Yo1aOe/k8= - dependencies: - is-number "^3.0.0" - kind-of "^4.0.0" - -has@^1.0.3: - version "1.0.3" - resolved "https://registry.yarnpkg.com/has/-/has-1.0.3.tgz#722d7cbfc1f6aa8241f16dd814e011e1f41e8796" - integrity sha512-f2dvO0VU6Oej7RkWJGrehjbzMAjFp5/VKPp5tTpWIV4JHHZK1/BxbFRtf/siA2SWTe09caDmVtYYzWEIbBS4zw== - dependencies: - function-bind "^1.1.1" - -he@^1.1.1: - version "1.2.0" - resolved "https://registry.yarnpkg.com/he/-/he-1.2.0.tgz#84ae65fa7eafb165fddb61566ae14baf05664f0f" - integrity sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw== - -homedir-polyfill@^1.0.1: - version "1.0.3" - resolved "https://registry.yarnpkg.com/homedir-polyfill/-/homedir-polyfill-1.0.3.tgz#743298cef4e5af3e194161fbadcc2151d3a058e8" - integrity sha512-eSmmWE5bZTK2Nou4g0AI3zZ9rswp7GRKoKXS1BLUkvPviOqs4YTN1djQIqrXy9k5gEtdLPy86JjRwsNM9tnDcA== - dependencies: - parse-passwd "^1.0.0" - -hosted-git-info@^2.1.4: - version "2.8.8" - resolved "https://registry.yarnpkg.com/hosted-git-info/-/hosted-git-info-2.8.8.tgz#7539bd4bc1e0e0a895815a2e0262420b12858488" - integrity sha512-f/wzC2QaWBs7t9IYqB4T3sR1xviIViXJRJTWBlx2Gf3g0Xi5vI7Yy4koXQ1c9OYDGHN9sBy1DQ2AB8fqZBWhUg== - -http-cache-semantics@^4.0.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/http-cache-semantics/-/http-cache-semantics-4.1.0.tgz#49e91c5cbf36c9b94bcfcd71c23d5249ec74e390" - integrity sha512-carPklcUh7ROWRK7Cv27RPtdhYhUsela/ue5/jKzjegVvXDqM2ILE9Q2BGn9JZJh1g87cp56su/FgQSzcWS8cQ== - -http-errors@~1.6.2: - version "1.6.3" - resolved "https://registry.yarnpkg.com/http-errors/-/http-errors-1.6.3.tgz#8b55680bb4be283a0b5bf4ea2e38580be1d9320d" - integrity sha1-i1VoC7S+KDoLW/TqLjhYC+HZMg0= - dependencies: - depd "~1.1.2" - inherits "2.0.3" - setprototypeof "1.1.0" - statuses ">= 1.4.0 < 2" - -http-errors@~1.7.2: - version "1.7.3" - resolved "https://registry.yarnpkg.com/http-errors/-/http-errors-1.7.3.tgz#6c619e4f9c60308c38519498c14fbb10aacebb06" - integrity sha512-ZTTX0MWrsQ2ZAhA1cejAwDLycFsd7I7nVtnkT3Ol0aqodaKW+0CTZDQ1uBv5whptCnc8e8HeRRJxRs0kmm/Qfw== - dependencies: - depd "~1.1.2" - inherits "2.0.4" - setprototypeof "1.1.1" - statuses ">= 1.5.0 < 2" - toidentifier "1.0.0" - -http-parser-js@>=0.5.1: - version "0.5.3" - resolved "https://registry.yarnpkg.com/http-parser-js/-/http-parser-js-0.5.3.tgz#01d2709c79d41698bb01d4decc5e9da4e4a033d9" - integrity sha512-t7hjvef/5HEK7RWTdUzVUhl8zkEu+LlaE0IYzdMuvbSDipxBRpOn4Uhw8ZyECEa808iVT8XCjzo6xmYt4CiLZg== - -http-proxy@^1.18.0: - version "1.18.1" - resolved "https://registry.yarnpkg.com/http-proxy/-/http-proxy-1.18.1.tgz#401541f0534884bbf95260334e72f88ee3976549" - integrity sha512-7mz/721AbnJwIVbnaSv1Cz3Am0ZLT/UBwkC92VlxhXv/k/BBQfM2fXElQNC27BVGr0uwUpplYPQM9LnaBMR5NQ== - dependencies: - eventemitter3 "^4.0.0" - follow-redirects "^1.0.0" - requires-port "^1.0.0" - -http-server@^0.12.3: - version "0.12.3" - resolved "https://registry.yarnpkg.com/http-server/-/http-server-0.12.3.tgz#ba0471d0ecc425886616cb35c4faf279140a0d37" - integrity sha512-be0dKG6pni92bRjq0kvExtj/NrrAd28/8fCXkaI/4piTwQMSDSLMhWyW0NI1V+DBI3aa1HMlQu46/HjVLfmugA== - dependencies: - basic-auth "^1.0.3" - colors "^1.4.0" - corser "^2.0.1" - ecstatic "^3.3.2" - http-proxy "^1.18.0" - minimist "^1.2.5" - opener "^1.5.1" - portfinder "^1.0.25" - secure-compare "3.0.1" - union "~0.5.0" - -ieee754@^1.1.13: - version "1.2.1" - resolved "https://registry.yarnpkg.com/ieee754/-/ieee754-1.2.1.tgz#8eb7a10a63fff25d15a57b001586d177d1b0d352" - integrity sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA== - -ignore@^5.1.4: - version "5.1.8" - resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.1.8.tgz#f150a8b50a34289b33e22f5889abd4d8016f0e57" - integrity sha512-BMpfD7PpiETpBl/A6S498BaIJ6Y/ABT93ETbby2fP00v4EbvPBXWEoaR1UBPKs3iR53pJY7EtZk5KACI57i1Uw== - -inflight@^1.0.4: - version "1.0.6" - resolved "https://registry.yarnpkg.com/inflight/-/inflight-1.0.6.tgz#49bd6331d7d02d0c09bc910a1075ba8165b56df9" - integrity sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk= - dependencies: - once "^1.3.0" - wrappy "1" - -inherits@2, inherits@2.0.4, inherits@^2.0.1, inherits@^2.0.3, inherits@^2.0.4, inherits@~2.0.0, inherits@~2.0.3: - version "2.0.4" - resolved "https://registry.yarnpkg.com/inherits/-/inherits-2.0.4.tgz#0fa2c64f932917c3433a0ded55363aae37416b7c" - integrity sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ== - -inherits@2.0.3: - version "2.0.3" - resolved "https://registry.yarnpkg.com/inherits/-/inherits-2.0.3.tgz#633c2c83e3da42a502f52466022480f4208261de" - integrity sha1-Yzwsg+PaQqUC9SRmAiSA9CCCYd4= - -ini@^1.3.4: - version "1.3.8" - resolved "https://registry.yarnpkg.com/ini/-/ini-1.3.8.tgz#a29da425b48806f34767a4efce397269af28432c" - integrity sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew== - -interpret@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/interpret/-/interpret-1.4.0.tgz#665ab8bc4da27a774a40584e812e3e0fa45b1a1e" - integrity sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA== - -invert-kv@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/invert-kv/-/invert-kv-1.0.0.tgz#104a8e4aaca6d3d8cd157a8ef8bfab2d7a3ffdb6" - integrity sha1-EEqOSqym09jNFXqO+L+rLXo//bY= - -is-absolute@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/is-absolute/-/is-absolute-1.0.0.tgz#395e1ae84b11f26ad1795e73c17378e48a301576" - integrity sha512-dOWoqflvcydARa360Gvv18DZ/gRuHKi2NU/wU5X1ZFzdYfH29nkiNZsF3mp4OJ3H4yo9Mx8A/uAGNzpzPN3yBA== - dependencies: - is-relative "^1.0.0" - is-windows "^1.0.1" - -is-accessor-descriptor@^0.1.6: - version "0.1.6" - resolved "https://registry.yarnpkg.com/is-accessor-descriptor/-/is-accessor-descriptor-0.1.6.tgz#a9e12cb3ae8d876727eeef3843f8a0897b5c98d6" - integrity sha1-qeEss66Nh2cn7u84Q/igiXtcmNY= - dependencies: - kind-of "^3.0.2" - -is-accessor-descriptor@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/is-accessor-descriptor/-/is-accessor-descriptor-1.0.0.tgz#169c2f6d3df1f992618072365c9b0ea1f6878656" - integrity sha512-m5hnHTkcVsPfqx3AKlyttIPb7J+XykHvJP2B9bZDjlhLIoEq4XoK64Vg7boZlVWYK6LUY94dYPEE7Lh0ZkZKcQ== - dependencies: - kind-of "^6.0.0" - -is-arrayish@^0.2.1: - version "0.2.1" - resolved "https://registry.yarnpkg.com/is-arrayish/-/is-arrayish-0.2.1.tgz#77c99840527aa8ecb1a8ba697b80645a7a926a9d" - integrity sha1-d8mYQFJ6qOyxqLppe4BkWnqSap0= - -is-binary-path@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/is-binary-path/-/is-binary-path-1.0.1.tgz#75f16642b480f187a711c814161fd3a4a7655898" - integrity sha1-dfFmQrSA8YenEcgUFh/TpKdlWJg= - dependencies: - binary-extensions "^1.0.0" - -is-buffer@^1.1.5: - version "1.1.6" - resolved "https://registry.yarnpkg.com/is-buffer/-/is-buffer-1.1.6.tgz#efaa2ea9daa0d7ab2ea13a97b2b8ad51fefbe8be" - integrity sha512-NcdALwpXkTm5Zvvbk7owOUSvVvBKDgKP5/ewfXEznmQFfs4ZRmanOeKBTjRVjka3QFoN6XJ+9F3USqfHqTaU5w== - -is-core-module@^2.1.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/is-core-module/-/is-core-module-2.2.0.tgz#97037ef3d52224d85163f5597b2b63d9afed981a" - integrity sha512-XRAfAdyyY5F5cOXn7hYQDqh2Xmii+DEfIcQGxK/uNwMHhIkPWO0g8msXcbzLe+MpGoR951MlqM/2iIlU4vKDdQ== - dependencies: - has "^1.0.3" - -is-data-descriptor@^0.1.4: - version "0.1.4" - resolved "https://registry.yarnpkg.com/is-data-descriptor/-/is-data-descriptor-0.1.4.tgz#0b5ee648388e2c860282e793f1856fec3f301b56" - integrity sha1-C17mSDiOLIYCgueT8YVv7D8wG1Y= - dependencies: - kind-of "^3.0.2" - -is-data-descriptor@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/is-data-descriptor/-/is-data-descriptor-1.0.0.tgz#d84876321d0e7add03990406abbbbd36ba9268c7" - integrity sha512-jbRXy1FmtAoCjQkVmIVYwuuqDFUbaOeDjmed1tOGPrsMhtJA4rD9tkgA0F1qJ3gRFRXcHYVkdeaP50Q5rE/jLQ== - dependencies: - kind-of "^6.0.0" - -is-descriptor@^0.1.0: - version "0.1.6" - resolved "https://registry.yarnpkg.com/is-descriptor/-/is-descriptor-0.1.6.tgz#366d8240dde487ca51823b1ab9f07a10a78251ca" - integrity sha512-avDYr0SB3DwO9zsMov0gKCESFYqCnE4hq/4z3TdUlukEy5t9C0YRq7HLrsN52NAcqXKaepeCD0n+B0arnVG3Hg== - dependencies: - is-accessor-descriptor "^0.1.6" - is-data-descriptor "^0.1.4" - kind-of "^5.0.0" - -is-descriptor@^1.0.0, is-descriptor@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/is-descriptor/-/is-descriptor-1.0.2.tgz#3b159746a66604b04f8c81524ba365c5f14d86ec" - integrity sha512-2eis5WqQGV7peooDyLmNEPUrps9+SXX5c9pL3xEB+4e9HnGuDa7mB7kHxHw4CbqS9k1T2hOH3miL8n8WtiYVtg== - dependencies: - is-accessor-descriptor "^1.0.0" - is-data-descriptor "^1.0.0" - kind-of "^6.0.2" - -is-extendable@^0.1.0, is-extendable@^0.1.1: - version "0.1.1" - resolved "https://registry.yarnpkg.com/is-extendable/-/is-extendable-0.1.1.tgz#62b110e289a471418e3ec36a617d472e301dfc89" - integrity sha1-YrEQ4omkcUGOPsNqYX1HLjAd/Ik= - -is-extendable@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/is-extendable/-/is-extendable-1.0.1.tgz#a7470f9e426733d81bd81e1155264e3a3507cab4" - integrity sha512-arnXMxT1hhoKo9k1LZdmlNyJdDDfy2v0fXjFlmok4+i8ul/6WlbVge9bhM74OpNPQPMGUToDtz+KXa1PneJxOA== - dependencies: - is-plain-object "^2.0.4" - -is-extglob@^2.1.0, is-extglob@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/is-extglob/-/is-extglob-2.1.1.tgz#a88c02535791f02ed37c76a1b9ea9773c833f8c2" - integrity sha1-qIwCU1eR8C7TfHahueqXc8gz+MI= - -is-fullwidth-code-point@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-1.0.0.tgz#ef9e31386f031a7f0d643af82fde50c457ef00cb" - integrity sha1-754xOG8DGn8NZDr4L95QxFfvAMs= - dependencies: - number-is-nan "^1.0.0" - -is-fullwidth-code-point@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz#f116f8064fe90b3f7844a38997c0b75051269f1d" - integrity sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg== - -is-glob@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/is-glob/-/is-glob-3.1.0.tgz#7ba5ae24217804ac70707b96922567486cc3e84a" - integrity sha1-e6WuJCF4BKxwcHuWkiVnSGzD6Eo= - dependencies: - is-extglob "^2.1.0" - -is-glob@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/is-glob/-/is-glob-4.0.1.tgz#7567dbe9f2f5e2467bc77ab83c4a29482407a5dc" - integrity sha512-5G0tKtBTFImOqDnLB2hG6Bp2qcKEFduo4tZu9MT/H6NQv/ghhy30o55ufafxJ/LdH79LLs2Kfrn85TLKyA7BUg== - dependencies: - is-extglob "^2.1.1" - -is-negated-glob@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/is-negated-glob/-/is-negated-glob-1.0.0.tgz#6910bca5da8c95e784b5751b976cf5a10fee36d2" - integrity sha1-aRC8pdqMleeEtXUbl2z1oQ/uNtI= - -is-number@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/is-number/-/is-number-3.0.0.tgz#24fd6201a4782cf50561c810276afc7d12d71195" - integrity sha1-JP1iAaR4LPUFYcgQJ2r8fRLXEZU= - dependencies: - kind-of "^3.0.2" - -is-number@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/is-number/-/is-number-4.0.0.tgz#0026e37f5454d73e356dfe6564699867c6a7f0ff" - integrity sha512-rSklcAIlf1OmFdyAqbnWTLVelsQ58uvZ66S/ZyawjWqIviTWCjg2PzVGw8WUA+nNuPTqb4wgA+NszrJ+08LlgQ== - -is-number@^7.0.0: - version "7.0.0" - resolved "https://registry.yarnpkg.com/is-number/-/is-number-7.0.0.tgz#7535345b896734d5f80c4d06c50955527a14f12b" - integrity sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng== - -is-plain-object@^2.0.1, is-plain-object@^2.0.3, is-plain-object@^2.0.4: - version "2.0.4" - resolved "https://registry.yarnpkg.com/is-plain-object/-/is-plain-object-2.0.4.tgz#2c163b3fafb1b606d9d17928f05c2a1c38e07677" - integrity sha512-h5PpgXkWitc38BBMYawTYMWJHFZJVnBquFE57xFpjB8pJFiF6gZ+bU+WyI/yqXiFR5mdLsgYNaPe8uao6Uv9Og== - dependencies: - isobject "^3.0.1" - -is-relative@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/is-relative/-/is-relative-1.0.0.tgz#a1bb6935ce8c5dba1e8b9754b9b2dcc020e2260d" - integrity sha512-Kw/ReK0iqwKeu0MITLFuj0jbPAmEiOsIwyIXvvbfa6QfmN9pkD1M+8pdk7Rl/dTKbH34/XBFMbgD4iMJhLQbGA== - dependencies: - is-unc-path "^1.0.0" - -is-unc-path@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/is-unc-path/-/is-unc-path-1.0.0.tgz#d731e8898ed090a12c352ad2eaed5095ad322c9d" - integrity sha512-mrGpVd0fs7WWLfVsStvgF6iEJnbjDFZh9/emhRDcGWTduTfNHd9CHeUwH3gYIjdbwo4On6hunkztwOaAw0yllQ== - dependencies: - unc-path-regex "^0.1.2" - -is-utf8@^0.2.0, is-utf8@^0.2.1: - version "0.2.1" - resolved "https://registry.yarnpkg.com/is-utf8/-/is-utf8-0.2.1.tgz#4b0da1442104d1b336340e80797e865cf39f7d72" - integrity sha1-Sw2hRCEE0bM2NA6AeX6GXPOffXI= - -is-valid-glob@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/is-valid-glob/-/is-valid-glob-1.0.0.tgz#29bf3eff701be2d4d315dbacc39bc39fe8f601aa" - integrity sha1-Kb8+/3Ab4tTTFdusw5vDn+j2Aao= - -is-windows@^1.0.1, is-windows@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/is-windows/-/is-windows-1.0.2.tgz#d1850eb9791ecd18e6182ce12a30f396634bb19d" - integrity sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA== - -isarray@1.0.0, isarray@~1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/isarray/-/isarray-1.0.0.tgz#bb935d48582cba168c06834957a54a3e07124f11" - integrity sha1-u5NdSFgsuhaMBoNJV6VKPgcSTxE= - -isexe@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10" - integrity sha1-6PvzdNxVb/iUehDcsFctYz8s+hA= - -isobject@^2.0.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/isobject/-/isobject-2.1.0.tgz#f065561096a3f1da2ef46272f815c840d87e0c89" - integrity sha1-8GVWEJaj8dou9GJy+BXIQNh+DIk= - dependencies: - isarray "1.0.0" - -isobject@^3.0.0, isobject@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/isobject/-/isobject-3.0.1.tgz#4e431e92b11a9731636aa1f9c8d1ccbcfdab78df" - integrity sha1-TkMekrEalzFjaqH5yNHMvP2reN8= - -isomorphic-git@0.78.5: - version "0.78.5" - resolved "https://registry.yarnpkg.com/isomorphic-git/-/isomorphic-git-0.78.5.tgz#013f8f8c280b8e0f8bb10ffa251eb87e9bb1190b" - integrity sha512-LrF5t9x7RdFeg84NsYpZo9qF1MZeb56LpBm6Jv47qMjnWMv0Il/3wPTA8I/lUYywgVbvF/e7xypHauj5auKW3w== - dependencies: - async-lock "^1.1.0" - clean-git-ref "^2.0.1" - crc-32 "^1.2.0" - diff3 "0.0.3" - git-apply-delta "0.0.7" - globalyzer "^0.1.4" - globrex "^0.1.2" - ignore "^5.1.4" - marky "^1.2.1" - minimisted "^2.0.0" - pako "^1.0.10" - pify "^4.0.1" - readable-stream "^3.4.0" - sha.js "^2.4.9" - simple-get "^3.0.2" - -js-yaml@~3.14: - version "3.14.1" - resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.14.1.tgz#dae812fdb3825fa306609a8717383c50c36a0537" - integrity sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g== - dependencies: - argparse "^1.0.7" - esprima "^4.0.0" - -json-buffer@3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/json-buffer/-/json-buffer-3.0.0.tgz#5b1f397afc75d677bde8bcfc0e47e1f9a3d9a898" - integrity sha1-Wx85evx11ne96Lz8Dkfh+aPZqJg= - -json-stable-stringify-without-jsonify@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz#9db7b59496ad3f3cfef30a75142d2d930ad72651" - integrity sha1-nbe1lJatPzz+8wp1FC0tkwrXJlE= - -json5@~2.1: - version "2.1.3" - resolved "https://registry.yarnpkg.com/json5/-/json5-2.1.3.tgz#c9b0f7fa9233bfe5807fe66fcf3a5617ed597d43" - integrity sha512-KXPvOm8K9IJKFM0bmdn8QXh7udDh1g/giieX0NLCaMnb4hEiVFqnop2ImTXCc5e0/oHz3LTqmHGtExn5hfMkOA== - dependencies: - minimist "^1.2.5" - -jsonfile@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-4.0.0.tgz#8771aae0799b64076b76640fca058f9c10e33ecb" - integrity sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss= - optionalDependencies: - graceful-fs "^4.1.6" - -just-debounce@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/just-debounce/-/just-debounce-1.0.0.tgz#87fccfaeffc0b68cd19d55f6722943f929ea35ea" - integrity sha1-h/zPrv/AtozRnVX2cilD+SnqNeo= - -keyv@^3.0.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/keyv/-/keyv-3.1.0.tgz#ecc228486f69991e49e9476485a5be1e8fc5c4d9" - integrity sha512-9ykJ/46SN/9KPM/sichzQ7OvXyGDYKGTaDlKMGCAlg2UK8KRy4jb0d8sFc+0Tt0YYnThq8X2RZgCg74RPxgcVA== - dependencies: - json-buffer "3.0.0" - -kind-of@^3.0.2, kind-of@^3.0.3, kind-of@^3.2.0: - version "3.2.2" - resolved "https://registry.yarnpkg.com/kind-of/-/kind-of-3.2.2.tgz#31ea21a734bab9bbb0f32466d893aea51e4a3c64" - integrity sha1-MeohpzS6ubuw8yRm2JOupR5KPGQ= - dependencies: - is-buffer "^1.1.5" - -kind-of@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/kind-of/-/kind-of-4.0.0.tgz#20813df3d712928b207378691a45066fae72dd57" - integrity sha1-IIE989cSkosgc3hpGkUGb65y3Vc= - dependencies: - is-buffer "^1.1.5" - -kind-of@^5.0.0, kind-of@^5.0.2: - version "5.1.0" - resolved "https://registry.yarnpkg.com/kind-of/-/kind-of-5.1.0.tgz#729c91e2d857b7a419a1f9aa65685c4c33f5845d" - integrity sha512-NGEErnH6F2vUuXDh+OlbcKW7/wOcfdRHaZ7VWtqCztfHri/++YKmP51OdWeGPuqCOba6kk2OTe5d02VmTB80Pw== - -kind-of@^6.0.0, kind-of@^6.0.2: - version "6.0.3" - resolved "https://registry.yarnpkg.com/kind-of/-/kind-of-6.0.3.tgz#07c05034a6c349fa06e24fa35aa76db4580ce4dd" - integrity sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw== - -last-run@^1.1.0: - version "1.1.1" - resolved "https://registry.yarnpkg.com/last-run/-/last-run-1.1.1.tgz#45b96942c17b1c79c772198259ba943bebf8ca5b" - integrity sha1-RblpQsF7HHnHchmCWbqUO+v4yls= - dependencies: - default-resolution "^2.0.0" - es6-weak-map "^2.0.1" - -lazystream@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/lazystream/-/lazystream-1.0.0.tgz#f6995fe0f820392f61396be89462407bb77168e4" - integrity sha1-9plf4PggOS9hOWvolGJAe7dxaOQ= - dependencies: - readable-stream "^2.0.5" - -lcid@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/lcid/-/lcid-1.0.0.tgz#308accafa0bc483a3867b4b6f2b9506251d1b835" - integrity sha1-MIrMr6C8SDo4Z7S28rlQYlHRuDU= - dependencies: - invert-kv "^1.0.0" - -lead@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/lead/-/lead-1.0.0.tgz#6f14f99a37be3a9dd784f5495690e5903466ee42" - integrity sha1-bxT5mje+Op3XhPVJVpDlkDRm7kI= - dependencies: - flush-write-stream "^1.0.2" - -liftoff@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/liftoff/-/liftoff-3.1.0.tgz#c9ba6081f908670607ee79062d700df062c52ed3" - integrity sha512-DlIPlJUkCV0Ips2zf2pJP0unEoT1kwYhiiPUGF3s/jtxTCjziNLoiVVh+jqWOWeFi6mmwQ5fNxvAUyPad4Dfog== - dependencies: - extend "^3.0.0" - findup-sync "^3.0.0" - fined "^1.0.1" - flagged-respawn "^1.0.0" - is-plain-object "^2.0.4" - object.map "^1.0.0" - rechoir "^0.6.2" - resolve "^1.1.7" - -livereload-js@^2.3.0: - version "2.4.0" - resolved "https://registry.yarnpkg.com/livereload-js/-/livereload-js-2.4.0.tgz#447c31cf1ea9ab52fc20db615c5ddf678f78009c" - integrity sha512-XPQH8Z2GDP/Hwz2PCDrh2mth4yFejwA1OZ/81Ti3LgKyhDcEjsSsqFWZojHG0va/duGd+WyosY7eXLDoOyqcPw== - -load-json-file@^1.0.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/load-json-file/-/load-json-file-1.1.0.tgz#956905708d58b4bab4c2261b04f59f31c99374c0" - integrity sha1-lWkFcI1YtLq0wiYbBPWfMcmTdMA= - dependencies: - graceful-fs "^4.1.2" - parse-json "^2.2.0" - pify "^2.0.0" - pinkie-promise "^2.0.0" - strip-bom "^2.0.0" - -locate-path@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-5.0.0.tgz#1afba396afd676a6d42504d0a67a3a7eb9f62aa0" - integrity sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g== - dependencies: - p-locate "^4.1.0" - -lodash.clonedeep@^4.5.0: - version "4.5.0" - resolved "https://registry.yarnpkg.com/lodash.clonedeep/-/lodash.clonedeep-4.5.0.tgz#e23f3f9c4f8fbdde872529c1071857a086e5ccef" - integrity sha1-4j8/nE+Pvd6HJSnBBxhXoIblzO8= - -lodash@^4.17.14: - version "4.17.20" - resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.20.tgz#b44a9b6297bcb698f1c51a3545a2b3b368d59c52" - integrity sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA== - -lowercase-keys@^1.0.0, lowercase-keys@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/lowercase-keys/-/lowercase-keys-1.0.1.tgz#6f9e30b47084d971a7c820ff15a6c5167b74c26f" - integrity sha512-G2Lj61tXDnVFFOi8VZds+SoQjtQC3dgokKdDG2mTm1tx4m50NUHBOZSBwQQHyy0V12A0JTG4icfZQH+xPyh8VA== - -lowercase-keys@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/lowercase-keys/-/lowercase-keys-2.0.0.tgz#2603e78b7b4b0006cbca2fbcc8a3202558ac9479" - integrity sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA== - -make-iterator@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/make-iterator/-/make-iterator-1.0.1.tgz#29b33f312aa8f547c4a5e490f56afcec99133ad6" - integrity sha512-pxiuXh0iVEq7VM7KMIhs5gxsfxCux2URptUQaXo4iZZJxBAzTPOLE2BumO5dbfVYq/hBJFBR/a1mFDmOx5AGmw== - dependencies: - kind-of "^6.0.2" - -map-cache@^0.2.0, map-cache@^0.2.2: - version "0.2.2" - resolved "https://registry.yarnpkg.com/map-cache/-/map-cache-0.2.2.tgz#c32abd0bd6525d9b051645bb4f26ac5dc98a0dbf" - integrity sha1-wyq9C9ZSXZsFFkW7TyasXcmKDb8= - -map-obj@^4.0.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/map-obj/-/map-obj-4.1.0.tgz#b91221b542734b9f14256c0132c897c5d7256fd5" - integrity sha512-glc9y00wgtwcDmp7GaE/0b0OnxpNJsVf3ael/An6Fe2Q51LLwN1er6sdomLRzz5h0+yMpiYLhWYF5R7HeqVd4g== - -map-stream@^0.0.7: - version "0.0.7" - resolved "https://registry.yarnpkg.com/map-stream/-/map-stream-0.0.7.tgz#8a1f07896d82b10926bd3744a2420009f88974a8" - integrity sha1-ih8HiW2CsQkmvTdEokIACfiJdKg= - -map-visit@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/map-visit/-/map-visit-1.0.0.tgz#ecdca8f13144e660f1b5bd41f12f3479d98dfb8f" - integrity sha1-7Nyo8TFE5mDxtb1B8S80edmN+48= - dependencies: - object-visit "^1.0.0" - -marky@^1.2.1: - version "1.2.1" - resolved "https://registry.yarnpkg.com/marky/-/marky-1.2.1.tgz#a3fcf82ffd357756b8b8affec9fdbf3a30dc1b02" - integrity sha512-md9k+Gxa3qLH6sUKpeC2CNkJK/Ld+bEz5X96nYwloqphQE0CKCVEKco/6jxEZixinqNdz5RFi/KaCyfbMDMAXQ== - -matchdep@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/matchdep/-/matchdep-2.0.0.tgz#c6f34834a0d8dbc3b37c27ee8bbcb27c7775582e" - integrity sha1-xvNINKDY28OzfCfui7yyfHd1WC4= - dependencies: - findup-sync "^2.0.0" - micromatch "^3.0.4" - resolve "^1.4.0" - stack-trace "0.0.10" - -matcher@~2.1: - version "2.1.0" - resolved "https://registry.yarnpkg.com/matcher/-/matcher-2.1.0.tgz#64e1041c15b993e23b786f93320a7474bf833c28" - integrity sha512-o+nZr+vtJtgPNklyeUKkkH42OsK8WAfdgaJE2FNxcjLPg+5QbeEoT6vRj8Xq/iv18JlQ9cmKsEu0b94ixWf1YQ== - dependencies: - escape-string-regexp "^2.0.0" - -micromatch@^3.0.4, micromatch@^3.1.10, micromatch@^3.1.4: - version "3.1.10" - resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-3.1.10.tgz#70859bc95c9840952f359a068a3fc49f9ecfac23" - integrity sha512-MWikgl9n9M3w+bpsY3He8L+w9eF9338xRl8IAO5viDizwSzziFEyUzo2xrrloB64ADbTf8uA8vRqqttDTOmccg== - dependencies: - arr-diff "^4.0.0" - array-unique "^0.3.2" - braces "^2.3.1" - define-property "^2.0.2" - extend-shallow "^3.0.2" - extglob "^2.0.4" - fragment-cache "^0.2.1" - kind-of "^6.0.2" - nanomatch "^1.2.9" - object.pick "^1.3.0" - regex-not "^1.0.0" - snapdragon "^0.8.1" - to-regex "^3.0.2" - -mime-db@1.45.0: - version "1.45.0" - resolved "https://registry.yarnpkg.com/mime-db/-/mime-db-1.45.0.tgz#cceeda21ccd7c3a745eba2decd55d4b73e7879ea" - integrity sha512-CkqLUxUk15hofLoLyljJSrukZi8mAtgd+yE5uO4tqRZsdsAJKv0O+rFMhVDRJgozy+yG6md5KwuXhD4ocIoP+w== - -mime-types@~2.1, mime-types@~2.1.17, mime-types@~2.1.24: - version "2.1.28" - resolved "https://registry.yarnpkg.com/mime-types/-/mime-types-2.1.28.tgz#1160c4757eab2c5363888e005273ecf79d2a0ecd" - integrity sha512-0TO2yJ5YHYr7M2zzT7gDU1tbwHxEUWBCLt0lscSNpcdAfFyJOVEpRYNS7EXVcTLNj/25QO8gulHC5JtTzSE2UQ== - dependencies: - mime-db "1.45.0" - -mime@1.4.1: - version "1.4.1" - resolved "https://registry.yarnpkg.com/mime/-/mime-1.4.1.tgz#121f9ebc49e3766f311a76e1fa1c8003c4b03aa6" - integrity sha512-KI1+qOZu5DcW6wayYHSzR/tXKCDC5Om4s1z2QJjDULzLcmf3DvzS7oluY4HCTrc+9FiKmWUgeNLg7W3uIQvxtQ== - -mime@1.6.0, mime@^1.6.0: - version "1.6.0" - resolved "https://registry.yarnpkg.com/mime/-/mime-1.6.0.tgz#32cd9e5c64553bd58d19a568af452acff04981b1" - integrity sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg== - -mimic-response@^1.0.0, mimic-response@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/mimic-response/-/mimic-response-1.0.1.tgz#4923538878eef42063cb8a3e3b0798781487ab1b" - integrity sha512-j5EctnkH7amfV/q5Hgmoal1g2QHFJRraOtmx0JpIqkxhBhI/lJSl1nMpQ45hVarwNETOoWEimndZ4QK0RHxuxQ== - -mimic-response@^2.0.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/mimic-response/-/mimic-response-2.1.0.tgz#d13763d35f613d09ec37ebb30bac0469c0ee8f43" - integrity sha512-wXqjST+SLt7R009ySCglWBCFpjUygmCIfD790/kVbiGmUgfYGuB14PiTd5DwVxSV4NcYHjzMkoj5LjQZwTQLEA== - -minimatch-all@~1.1: - version "1.1.0" - resolved "https://registry.yarnpkg.com/minimatch-all/-/minimatch-all-1.1.0.tgz#40c496a27a2e128d19bf758e76bb01a0c7145787" - integrity sha1-QMSWonouEo0Zv3WOdrsBoMcUV4c= - dependencies: - minimatch "^3.0.2" - -"minimatch@2 || 3", minimatch@^3.0.2, minimatch@^3.0.4: - version "3.0.4" - resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-3.0.4.tgz#5166e286457f03306064be5497e8dbb0c3d32083" - integrity sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA== - dependencies: - brace-expansion "^1.1.7" - -minimist@^1.1.0, minimist@^1.2.5: - version "1.2.5" - resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.5.tgz#67d66014b66a6a8aaa0c083c5fd58df4e4e97602" - integrity sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw== - -minimisted@^2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/minimisted/-/minimisted-2.0.1.tgz#d059fb905beecf0774bc3b308468699709805cb1" - integrity sha512-1oPjfuLQa2caorJUM8HV8lGgWCc0qqAO1MNv/k05G4qslmsndV/5WdNZrqCiyqiz3wohia2Ij2B7w2Dr7/IyrA== - dependencies: - minimist "^1.2.5" - -mixin-deep@^1.2.0: - version "1.3.2" - resolved "https://registry.yarnpkg.com/mixin-deep/-/mixin-deep-1.3.2.tgz#1120b43dc359a785dce65b55b82e257ccf479566" - integrity sha512-WRoDn//mXBiJ1H40rqa3vH0toePwSsGb45iInWlTySa+Uu4k3tYUSxa2v1KqAiLtvlrSzaExqS1gtk96A9zvEA== - dependencies: - for-in "^1.0.2" - is-extendable "^1.0.1" - -mkdirp@^0.5.5: - version "0.5.5" - resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-0.5.5.tgz#d91cefd62d1436ca0f41620e251288d420099def" - integrity sha512-NKmAlESf6jMGym1++R0Ra7wvhV+wFW63FaSOFPwRahvea0gMUcGUhVeAg/0BC0wiv9ih5NYPB1Wn1UEI1/L+xQ== - dependencies: - minimist "^1.2.5" - -ms@2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/ms/-/ms-2.0.0.tgz#5608aeadfc00be6c2901df5f9861788de0d597c8" - integrity sha1-VgiurfwAvmwpAd9fmGF4jeDVl8g= - -ms@2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.1.tgz#30a5864eb3ebb0a66f2ebe6d727af06a09d86e0a" - integrity sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg== - -ms@^2.1.1: - version "2.1.3" - resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2" - integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== - -multi-progress@~2.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/multi-progress/-/multi-progress-2.0.0.tgz#29ccb42cf24874b1c6384f03127ce5dff7b22f2c" - integrity sha1-Kcy0LPJIdLHGOE8DEnzl3/eyLyw= - dependencies: - progress "^1.1.8" - -mute-stdout@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/mute-stdout/-/mute-stdout-1.0.1.tgz#acb0300eb4de23a7ddeec014e3e96044b3472331" - integrity sha512-kDcwXR4PS7caBpuRYYBUz9iVixUk3anO3f5OYFiIPwK/20vCzKCHyKoulbiDY1S53zD2bxUpxN/IJ+TnXjfvxg== - -nan@^2.12.1: - version "2.14.2" - resolved "https://registry.yarnpkg.com/nan/-/nan-2.14.2.tgz#f5376400695168f4cc694ac9393d0c9585eeea19" - integrity sha512-M2ufzIiINKCuDfBSAUr1vWQ+vuVcA9kqx8JJUsbQi6yf1uGRyb7HfpdfUr5qLXf3B/t8dPvcjhKMmlfnP47EzQ== - -nanomatch@^1.2.9: - version "1.2.13" - resolved "https://registry.yarnpkg.com/nanomatch/-/nanomatch-1.2.13.tgz#b87a8aa4fc0de8fe6be88895b38983ff265bd119" - integrity sha512-fpoe2T0RbHwBTBUOftAfBPaDEi06ufaUai0mE6Yn1kacc3SnTErfb/h+X94VXzI64rKFHYImXSvdwGGCmwOqCA== - dependencies: - arr-diff "^4.0.0" - array-unique "^0.3.2" - define-property "^2.0.2" - extend-shallow "^3.0.2" - fragment-cache "^0.2.1" - is-windows "^1.0.2" - kind-of "^6.0.2" - object.pick "^1.3.0" - regex-not "^1.0.0" - snapdragon "^0.8.1" - to-regex "^3.0.1" - -negotiator@0.6.2: - version "0.6.2" - resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-0.6.2.tgz#feacf7ccf525a77ae9634436a64883ffeca346fb" - integrity sha512-hZXc7K2e+PgeI1eDBe/10Ard4ekbfrrqG8Ep+8Jmf4JID2bNg7NvCPOZN+kfF574pFQI7mum2AUqDidoKqcTOw== - -neo-async@^2.6.0: - version "2.6.2" - resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f" - integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw== - -next-tick@~1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/next-tick/-/next-tick-1.0.0.tgz#ca86d1fe8828169b0120208e3dc8424b9db8342c" - integrity sha1-yobR/ogoFpsBICCOPchCS524NCw= - -normalize-package-data@^2.3.2: - version "2.5.0" - resolved "https://registry.yarnpkg.com/normalize-package-data/-/normalize-package-data-2.5.0.tgz#e66db1838b200c1dfc233225d12cb36520e234a8" - integrity sha512-/5CMN3T0R4XTj4DcGaexo+roZSdSFW/0AOOTROrjxzCG1wrWXEsGbRKevjlIL+ZDE4sZlJr5ED4YW0yqmkK+eA== - dependencies: - hosted-git-info "^2.1.4" - resolve "^1.10.0" - semver "2 || 3 || 4 || 5" - validate-npm-package-license "^3.0.1" - -normalize-path@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/normalize-path/-/normalize-path-2.1.1.tgz#1ab28b556e198363a8c1a6f7e6fa20137fe6aed9" - integrity sha1-GrKLVW4Zg2Oowab35vogE3/mrtk= - dependencies: - remove-trailing-separator "^1.0.1" - -normalize-path@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/normalize-path/-/normalize-path-3.0.0.tgz#0dcd69ff23a1c9b11fd0978316644a0388216a65" - integrity sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA== - -normalize-url@^4.1.0: - version "4.5.0" - resolved "https://registry.yarnpkg.com/normalize-url/-/normalize-url-4.5.0.tgz#453354087e6ca96957bd8f5baf753f5982142129" - integrity sha512-2s47yzUxdexf1OhyRi4Em83iQk0aPvwTddtFz4hnSSw9dCEsLEGf6SwIO8ss/19S9iBb5sJaOuTvTGDeZI00BQ== - -now-and-later@^2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/now-and-later/-/now-and-later-2.0.1.tgz#8e579c8685764a7cc02cb680380e94f43ccb1f7c" - integrity sha512-KGvQ0cB70AQfg107Xvs/Fbu+dGmZoTRJp2TaPwcwQm3/7PteUyN2BCgk8KBMPGBUXZdVwyWS8fDCGFygBm19UQ== - dependencies: - once "^1.3.2" - -number-is-nan@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/number-is-nan/-/number-is-nan-1.0.1.tgz#097b602b53422a522c1afb8790318336941a011d" - integrity sha1-CXtgK1NCKlIsGvuHkDGDNpQaAR0= - -object-assign@^4.1.0: - version "4.1.1" - resolved "https://registry.yarnpkg.com/object-assign/-/object-assign-4.1.1.tgz#2109adc7965887cfc05cbbd442cac8bfbb360863" - integrity sha1-IQmtx5ZYh8/AXLvUQsrIv7s2CGM= - -object-copy@^0.1.0: - version "0.1.0" - resolved "https://registry.yarnpkg.com/object-copy/-/object-copy-0.1.0.tgz#7e7d858b781bd7c991a41ba975ed3812754e998c" - integrity sha1-fn2Fi3gb18mRpBupde04EnVOmYw= - dependencies: - copy-descriptor "^0.1.0" - define-property "^0.2.5" - kind-of "^3.0.3" - -object-keys@^1.0.12, object-keys@^1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/object-keys/-/object-keys-1.1.1.tgz#1c47f272df277f3b1daf061677d9c82e2322c60e" - integrity sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA== - -object-visit@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/object-visit/-/object-visit-1.0.1.tgz#f79c4493af0c5377b59fe39d395e41042dd045bb" - integrity sha1-95xEk68MU3e1n+OdOV5BBC3QRbs= - dependencies: - isobject "^3.0.0" - -object.assign@^4.0.4, object.assign@^4.1.0: - version "4.1.2" - resolved "https://registry.yarnpkg.com/object.assign/-/object.assign-4.1.2.tgz#0ed54a342eceb37b38ff76eb831a0e788cb63940" - integrity sha512-ixT2L5THXsApyiUPYKmW+2EHpXXe5Ii3M+f4e+aJFAHao5amFRW6J0OO6c/LU8Be47utCx2GL89hxGB6XSmKuQ== - dependencies: - call-bind "^1.0.0" - define-properties "^1.1.3" - has-symbols "^1.0.1" - object-keys "^1.1.1" - -object.defaults@^1.0.0, object.defaults@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/object.defaults/-/object.defaults-1.1.0.tgz#3a7f868334b407dea06da16d88d5cd29e435fecf" - integrity sha1-On+GgzS0B96gbaFtiNXNKeQ1/s8= - dependencies: - array-each "^1.0.1" - array-slice "^1.0.0" - for-own "^1.0.0" - isobject "^3.0.0" - -object.map@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/object.map/-/object.map-1.0.1.tgz#cf83e59dc8fcc0ad5f4250e1f78b3b81bd801d37" - integrity sha1-z4Plncj8wK1fQlDh94s7gb2AHTc= - dependencies: - for-own "^1.0.0" - make-iterator "^1.0.0" - -object.pick@^1.2.0, object.pick@^1.3.0: - version "1.3.0" - resolved "https://registry.yarnpkg.com/object.pick/-/object.pick-1.3.0.tgz#87a10ac4c1694bd2e1cbf53591a66141fb5dd747" - integrity sha1-h6EKxMFpS9Lhy/U1kaZhQftd10c= - dependencies: - isobject "^3.0.1" - -object.reduce@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/object.reduce/-/object.reduce-1.0.1.tgz#6fe348f2ac7fa0f95ca621226599096825bb03ad" - integrity sha1-b+NI8qx/oPlcpiEiZZkJaCW7A60= - dependencies: - for-own "^1.0.0" - make-iterator "^1.0.0" - -on-finished@~2.3.0: - version "2.3.0" - resolved "https://registry.yarnpkg.com/on-finished/-/on-finished-2.3.0.tgz#20f1336481b083cd75337992a16971aa2d906947" - integrity sha1-IPEzZIGwg811M3mSoWlxqi2QaUc= - dependencies: - ee-first "1.1.1" - -once@^1.3.0, once@^1.3.1, once@^1.3.2, once@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/once/-/once-1.4.0.tgz#583b1aa775961d4b113ac17d9c50baef9dd76bd1" - integrity sha1-WDsap3WWHUsROsF9nFC6753Xa9E= - dependencies: - wrappy "1" - -opal-runtime@1.0.11: - version "1.0.11" - resolved "https://registry.yarnpkg.com/opal-runtime/-/opal-runtime-1.0.11.tgz#81fc2a2084ae5f25d5609eada375b756a3dab036" - integrity sha512-L+6pnRvXPlDtbamBRnJAnB9mEMXmsIQ/b+0r/2xJ5/n/nxheEkLo+Pm5QNQ08LEbEN9TI6/kedhIspqRRu6tXA== - dependencies: - glob "6.0.4" - xmlhttprequest "1.8.0" - -opener@^1.5.1: - version "1.5.2" - resolved "https://registry.yarnpkg.com/opener/-/opener-1.5.2.tgz#5d37e1f35077b9dcac4301372271afdeb2a13598" - integrity sha512-ur5UIdyw5Y7yEj9wLzhqXiy6GZ3Mwx0yGI+5sMn2r0N0v3cKJvUmFH5yPP+WXh9e0xfyzyJX95D8l088DNFj7A== - -ordered-read-streams@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/ordered-read-streams/-/ordered-read-streams-1.0.1.tgz#77c0cb37c41525d64166d990ffad7ec6a0e1363e" - integrity sha1-d8DLN8QVJdZBZtmQ/61+xqDhNj4= - dependencies: - readable-stream "^2.0.1" - -os-locale@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/os-locale/-/os-locale-1.4.0.tgz#20f9f17ae29ed345e8bde583b13d2009803c14d9" - integrity sha1-IPnxeuKe00XoveWDsT0gCYA8FNk= - dependencies: - lcid "^1.0.0" - -p-cancelable@^1.0.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/p-cancelable/-/p-cancelable-1.1.0.tgz#d078d15a3af409220c886f1d9a0ca2e441ab26cc" - integrity sha512-s73XxOZ4zpt1edZYZzvhqFa6uvQc1vwUa0K0BdtIZgQMAJj9IbebH+JkgKZc9h+B05PKHLOTl4ajG1BmNrVZlw== - -p-limit@^2.2.0: - version "2.3.0" - resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-2.3.0.tgz#3dd33c647a214fdfffd835933eb086da0dc21db1" - integrity sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w== - dependencies: - p-try "^2.0.0" - -p-locate@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-4.1.0.tgz#a3428bb7088b3a60292f66919278b7c297ad4f07" - integrity sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A== - dependencies: - p-limit "^2.2.0" - -p-try@^2.0.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/p-try/-/p-try-2.2.0.tgz#cb2868540e313d61de58fafbe35ce9004d5540e6" - integrity sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ== - -pako@^1.0.10: - version "1.0.11" - resolved "https://registry.yarnpkg.com/pako/-/pako-1.0.11.tgz#6c9599d340d54dfd3946380252a35705a6b992bf" - integrity sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw== - -parse-filepath@^1.0.1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/parse-filepath/-/parse-filepath-1.0.2.tgz#a632127f53aaf3d15876f5872f3ffac763d6c891" - integrity sha1-pjISf1Oq89FYdvWHLz/6x2PWyJE= - dependencies: - is-absolute "^1.0.0" - map-cache "^0.2.0" - path-root "^0.1.1" - -parse-json@^2.2.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/parse-json/-/parse-json-2.2.0.tgz#f480f40434ef80741f8469099f8dea18f55a4dc9" - integrity sha1-9ID0BDTvgHQfhGkJn43qGPVaTck= - dependencies: - error-ex "^1.2.0" - -parse-node-version@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/parse-node-version/-/parse-node-version-1.0.1.tgz#e2b5dbede00e7fa9bc363607f53327e8b073189b" - integrity sha512-3YHlOa/JgH6Mnpr05jP9eDG254US9ek25LyIxZlDItp2iJtwyaXQb57lBYLdT3MowkUFYEV2XXNAYIPlESvJlA== - -parse-passwd@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/parse-passwd/-/parse-passwd-1.0.0.tgz#6d5b934a456993b23d37f40a382d6f1666a8e5c6" - integrity sha1-bVuTSkVpk7I9N/QKOC1vFmao5cY= - -parseurl@~1.3.2, parseurl@~1.3.3: - version "1.3.3" - resolved "https://registry.yarnpkg.com/parseurl/-/parseurl-1.3.3.tgz#9da19e7bee8d12dff0513ed5b76957793bc2e8d4" - integrity sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ== - -pascalcase@^0.1.1: - version "0.1.1" - resolved "https://registry.yarnpkg.com/pascalcase/-/pascalcase-0.1.1.tgz#b363e55e8006ca6fe21784d2db22bd15d7917f14" - integrity sha1-s2PlXoAGym/iF4TS2yK9FdeRfxQ= - -path-dirname@^1.0.0: - version "1.0.2" - resolved "https://registry.yarnpkg.com/path-dirname/-/path-dirname-1.0.2.tgz#cc33d24d525e099a5388c0336c6e32b9160609e0" - integrity sha1-zDPSTVJeCZpTiMAzbG4yuRYGCeA= - -path-exists@^2.0.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/path-exists/-/path-exists-2.1.0.tgz#0feb6c64f0fc518d9a754dd5efb62c7022761f4b" - integrity sha1-D+tsZPD8UY2adU3V77YscCJ2H0s= - dependencies: - pinkie-promise "^2.0.0" - -path-exists@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/path-exists/-/path-exists-4.0.0.tgz#513bdbe2d3b95d7762e8c1137efa195c6c61b5b3" - integrity sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w== - -path-is-absolute@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/path-is-absolute/-/path-is-absolute-1.0.1.tgz#174b9268735534ffbc7ace6bf53a5a9e1b5c5f5f" - integrity sha1-F0uSaHNVNP+8es5r9TpanhtcX18= - -path-parse@^1.0.6: - version "1.0.6" - resolved "https://registry.yarnpkg.com/path-parse/-/path-parse-1.0.6.tgz#d62dbb5679405d72c4737ec58600e9ddcf06d24c" - integrity sha512-GSmOT2EbHrINBf9SR7CDELwlJ8AENk3Qn7OikK4nFYAu3Ote2+JYNVvkpAEQm3/TLNEJFD/xZJjzyxg3KBWOzw== - -path-root-regex@^0.1.0: - version "0.1.2" - resolved "https://registry.yarnpkg.com/path-root-regex/-/path-root-regex-0.1.2.tgz#bfccdc8df5b12dc52c8b43ec38d18d72c04ba96d" - integrity sha1-v8zcjfWxLcUsi0PsONGNcsBLqW0= - -path-root@^0.1.1: - version "0.1.1" - resolved "https://registry.yarnpkg.com/path-root/-/path-root-0.1.1.tgz#9a4a6814cac1c0cd73360a95f32083c8ea4745b7" - integrity sha1-mkpoFMrBwM1zNgqV8yCDyOpHRbc= - dependencies: - path-root-regex "^0.1.0" - -path-type@^1.0.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/path-type/-/path-type-1.1.0.tgz#59c44f7ee491da704da415da5a4070ba4f8fe441" - integrity sha1-WcRPfuSR2nBNpBXaWkBwuk+P5EE= - dependencies: - graceful-fs "^4.1.2" - pify "^2.0.0" - pinkie-promise "^2.0.0" - -pend@~1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/pend/-/pend-1.2.0.tgz#7a57eb550a6783f9115331fcf4663d5c8e007a50" - integrity sha1-elfrVQpng/kRUzH89GY9XI4AelA= - -picomatch@~2.2: - version "2.2.2" - resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-2.2.2.tgz#21f333e9b6b8eaff02468f5146ea406d345f4dad" - integrity sha512-q0M/9eZHzmr0AulXyPwNfZjtwZ/RBZlbN3K3CErVrk50T2ASYI7Bye0EvekFY3IP1Nt2DHu0re+V2ZHIpMkuWg== - -pify@^2.0.0: - version "2.3.0" - resolved "https://registry.yarnpkg.com/pify/-/pify-2.3.0.tgz#ed141a6ac043a849ea588498e7dca8b15330e90c" - integrity sha1-7RQaasBDqEnqWISY59yosVMw6Qw= - -pify@^4.0.1: - version "4.0.1" - resolved "https://registry.yarnpkg.com/pify/-/pify-4.0.1.tgz#4b2cd25c50d598735c50292224fd8c6df41e3231" - integrity sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g== - -pinkie-promise@^2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/pinkie-promise/-/pinkie-promise-2.0.1.tgz#2135d6dfa7a358c069ac9b178776288228450ffa" - integrity sha1-ITXW36ejWMBprJsXh3YogihFD/o= - dependencies: - pinkie "^2.0.0" - -pinkie@^2.0.0: - version "2.0.4" - resolved "https://registry.yarnpkg.com/pinkie/-/pinkie-2.0.4.tgz#72556b80cfa0d48a974e80e77248e80ed4f7f870" - integrity sha1-clVrgM+g1IqXToDnckjoDtT3+HA= - -portfinder@^1.0.25: - version "1.0.28" - resolved "https://registry.yarnpkg.com/portfinder/-/portfinder-1.0.28.tgz#67c4622852bd5374dd1dd900f779f53462fac778" - integrity sha512-Se+2isanIcEqf2XMHjyUKskczxbPH7dQnlMjXX6+dybayyHvAf/TCgyMRlzf/B6QDhAEFOGes0pzRo3by4AbMA== - dependencies: - async "^2.6.2" - debug "^3.1.1" - mkdirp "^0.5.5" - -posix-character-classes@^0.1.0: - version "0.1.1" - resolved "https://registry.yarnpkg.com/posix-character-classes/-/posix-character-classes-0.1.1.tgz#01eac0fe3b5af71a2a6c02feabb8c1fef7e00eab" - integrity sha1-AerA/jta9xoqbAL+q7jB/vfgDqs= - -prepend-http@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/prepend-http/-/prepend-http-2.0.0.tgz#e92434bfa5ea8c19f41cdfd401d741a3c819d897" - integrity sha1-6SQ0v6XqjBn0HN/UAddBo8gZ2Jc= - -pretty-hrtime@^1.0.0: - version "1.0.3" - resolved "https://registry.yarnpkg.com/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz#b7e3ea42435a4c9b2759d99e0f201eb195802ee1" - integrity sha1-t+PqQkNaTJsnWdmeDyAesZWALuE= - -printj@~1.1.0: - version "1.1.2" - resolved "https://registry.yarnpkg.com/printj/-/printj-1.1.2.tgz#d90deb2975a8b9f600fb3a1c94e3f4c53c78a222" - integrity sha512-zA2SmoLaxZyArQTOPj5LXecR+RagfPSU5Kw1qP+jkWeNlrq+eJZyY2oS68SU1Z/7/myXM4lo9716laOFAVStCQ== - -process-nextick-args@^2.0.0, process-nextick-args@~2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/process-nextick-args/-/process-nextick-args-2.0.1.tgz#7820d9b16120cc55ca9ae7792680ae7dba6d7fe2" - integrity sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag== - -progress@^1.1.8: - version "1.1.8" - resolved "https://registry.yarnpkg.com/progress/-/progress-1.1.8.tgz#e260c78f6161cdd9b0e56cc3e0a85de17c7a57be" - integrity sha1-4mDHj2Fhzdmw5WzD4Khd4Xx6V74= - -pump@^2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/pump/-/pump-2.0.1.tgz#12399add6e4cf7526d973cbc8b5ce2e2908b3909" - integrity sha512-ruPMNRkN3MHP1cWJc9OWr+T/xDP0jhXYCLfJcBuX54hhfIBnaQmAUMfDcG4DM5UMWByBbJY69QSphm3jtDKIkA== - dependencies: - end-of-stream "^1.1.0" - once "^1.3.1" - -pump@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/pump/-/pump-3.0.0.tgz#b4a2116815bde2f4e1ea602354e8c75565107a64" - integrity sha512-LwZy+p3SFs1Pytd/jYct4wpv49HiYCqd9Rlc5ZVdk0V+8Yzv6jR5Blk3TRmPL1ft69TxP0IMZGJ+WPFU2BFhww== - dependencies: - end-of-stream "^1.1.0" - once "^1.3.1" - -pumpify@^1.3.5: - version "1.5.1" - resolved "https://registry.yarnpkg.com/pumpify/-/pumpify-1.5.1.tgz#36513be246ab27570b1a374a5ce278bfd74370ce" - integrity sha512-oClZI37HvuUJJxSKKrC17bZ9Cu0ZYhEAGPsPUy9KlMUmv9dKX2o77RUmq7f3XjIxbwyGwYzbzQ1L2Ks8sIradQ== - dependencies: - duplexify "^3.6.0" - inherits "^2.0.3" - pump "^2.0.0" - -qs@^6.4.0: - version "6.9.4" - resolved "https://registry.yarnpkg.com/qs/-/qs-6.9.4.tgz#9090b290d1f91728d3c22e54843ca44aea5ab687" - integrity sha512-A1kFqHekCTM7cz0udomYUoYNWjBebHm/5wzU/XqrBRBNWectVH0QIiN+NEcZ0Dte5hvzHwbr8+XQmguPhJ6WdQ== - -queue@^4.2.1: - version "4.5.1" - resolved "https://registry.yarnpkg.com/queue/-/queue-4.5.1.tgz#6e4290a2d7e99dc75b34494431633fe5437b0dac" - integrity sha512-AMD7w5hRXcFSb8s9u38acBZ+309u6GsiibP4/0YacJeaurRshogB7v/ZcVPxP5gD5+zIw6ixRHdutiYUJfwKHw== - dependencies: - inherits "~2.0.0" - -quick-lru@^4.0.1: - version "4.0.1" - resolved "https://registry.yarnpkg.com/quick-lru/-/quick-lru-4.0.1.tgz#5b8878f113a58217848c6482026c73e1ba57727f" - integrity sha512-ARhCpm70fzdcvNQfPoy49IaanKkTlRWF2JMzqhcJbhSFRZv7nPTvZJdcY7301IPmvW+/p0RgIWnQDLJxifsQ7g== - -range-parser@~1.2.0, range-parser@~1.2.1: - version "1.2.1" - resolved "https://registry.yarnpkg.com/range-parser/-/range-parser-1.2.1.tgz#3cf37023d199e1c24d1a55b84800c2f3e6468031" - integrity sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg== - -raw-body@~1.1.0: - version "1.1.7" - resolved "https://registry.yarnpkg.com/raw-body/-/raw-body-1.1.7.tgz#1d027c2bfa116acc6623bca8f00016572a87d425" - integrity sha1-HQJ8K/oRasxmI7yo8AAWVyqH1CU= - dependencies: - bytes "1" - string_decoder "0.10" - -read-pkg-up@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/read-pkg-up/-/read-pkg-up-1.0.1.tgz#9d63c13276c065918d57f002a57f40a1b643fb02" - integrity sha1-nWPBMnbAZZGNV/ACpX9AobZD+wI= - dependencies: - find-up "^1.0.0" - read-pkg "^1.0.0" - -read-pkg@^1.0.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/read-pkg/-/read-pkg-1.1.0.tgz#f5ffaa5ecd29cb31c0474bca7d756b6bb29e3f28" - integrity sha1-9f+qXs0pyzHAR0vKfXVra7KePyg= - dependencies: - load-json-file "^1.0.0" - normalize-package-data "^2.3.2" - path-type "^1.0.0" - -readable-stream@3, readable-stream@^3.4.0: - version "3.6.0" - resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-3.6.0.tgz#337bbda3adc0706bd3e024426a286d4b4b2c9198" - integrity sha512-BViHy7LKeTz4oNnkcLJ+lVSL6vpiFeX6/d3oSH8zCW7UxP2onchk+vTGB143xuFjHS3deTgkKoXXymXqymiIdA== - dependencies: - inherits "^2.0.3" - string_decoder "^1.1.1" - util-deprecate "^1.0.1" - -readable-stream@^2.0.0, readable-stream@^2.0.1, readable-stream@^2.0.2, readable-stream@^2.0.5, readable-stream@^2.1.5, readable-stream@^2.2.2, readable-stream@^2.3.3, readable-stream@^2.3.5, readable-stream@^2.3.6, readable-stream@~2.3.6: - version "2.3.7" - resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-2.3.7.tgz#1eca1cf711aef814c04f62252a36a62f6cb23b57" - integrity sha512-Ebho8K4jIbHAxnuxi7o42OrZgF/ZTNcsZj6nRKyUmkhLFq8CHItp/fy6hQZuZmP/n3yZ9VBUbp4zz/mX8hmYPw== - dependencies: - core-util-is "~1.0.0" - inherits "~2.0.3" - isarray "~1.0.0" - process-nextick-args "~2.0.0" - safe-buffer "~5.1.1" - string_decoder "~1.1.1" - util-deprecate "~1.0.1" - -readdirp@^2.2.1: - version "2.2.1" - resolved "https://registry.yarnpkg.com/readdirp/-/readdirp-2.2.1.tgz#0e87622a3325aa33e892285caf8b4e846529a525" - integrity sha512-1JU/8q+VgFZyxwrJ+SVIOsh+KywWGpds3NTqikiKpDMZWScmAYyKIgqkO+ARvNWJfXeXR1zxz7aHF4u4CyH6vQ== - dependencies: - graceful-fs "^4.1.11" - micromatch "^3.1.10" - readable-stream "^2.0.2" - -rechoir@^0.6.2: - version "0.6.2" - resolved "https://registry.yarnpkg.com/rechoir/-/rechoir-0.6.2.tgz#85204b54dba82d5742e28c96756ef43af50e3384" - integrity sha1-hSBLVNuoLVdC4oyWdW70OvUOM4Q= - dependencies: - resolve "^1.1.6" - -regex-not@^1.0.0, regex-not@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/regex-not/-/regex-not-1.0.2.tgz#1f4ece27e00b0b65e0247a6810e6a85d83a5752c" - integrity sha512-J6SDjUgDxQj5NusnOtdFxDwN/+HWykR8GELwctJ7mdqhcyy1xEc4SRFHUXvxTp661YaVKAjfRLZ9cCqS6tn32A== - dependencies: - extend-shallow "^3.0.2" - safe-regex "^1.1.0" - -remove-bom-buffer@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/remove-bom-buffer/-/remove-bom-buffer-3.0.0.tgz#c2bf1e377520d324f623892e33c10cac2c252b53" - integrity sha512-8v2rWhaakv18qcvNeli2mZ/TMTL2nEyAKRvzo1WtnZBl15SHyEhrCu2/xKlJyUFKHiHgfXIyuY6g2dObJJycXQ== - dependencies: - is-buffer "^1.1.5" - is-utf8 "^0.2.1" - -remove-bom-stream@^1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/remove-bom-stream/-/remove-bom-stream-1.2.0.tgz#05f1a593f16e42e1fb90ebf59de8e569525f9523" - integrity sha1-BfGlk/FuQuH7kOv1nejlaVJflSM= - dependencies: - remove-bom-buffer "^3.0.0" - safe-buffer "^5.1.0" - through2 "^2.0.3" - -remove-trailing-separator@^1.0.1, remove-trailing-separator@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/remove-trailing-separator/-/remove-trailing-separator-1.1.0.tgz#c24bce2a283adad5bc3f58e0d48249b92379d8ef" - integrity sha1-wkvOKig62tW8P1jg1IJJuSN52O8= - -repeat-element@^1.1.2: - version "1.1.3" - resolved "https://registry.yarnpkg.com/repeat-element/-/repeat-element-1.1.3.tgz#782e0d825c0c5a3bb39731f84efee6b742e6b1ce" - integrity sha512-ahGq0ZnV5m5XtZLMb+vP76kcAM5nkLqk0lpqAuojSKGgQtn4eRi4ZZGm2olo2zKFH+sMsWaqOCW1dqAnOru72g== - -repeat-string@^1.6.1: - version "1.6.1" - resolved "https://registry.yarnpkg.com/repeat-string/-/repeat-string-1.6.1.tgz#8dcae470e1c88abc2d600fff4a776286da75e637" - integrity sha1-jcrkcOHIirwtYA//Sndihtp15jc= - -replace-ext@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/replace-ext/-/replace-ext-1.0.1.tgz#2d6d996d04a15855d967443631dd5f77825b016a" - integrity sha512-yD5BHCe7quCgBph4rMQ+0KkIRKwWCrHDOX1p1Gp6HwjPM5kVoCdKGNhN7ydqqsX6lJEnQDKZ/tFMiEdQ1dvPEw== - -replace-homedir@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/replace-homedir/-/replace-homedir-1.0.0.tgz#e87f6d513b928dde808260c12be7fec6ff6e798c" - integrity sha1-6H9tUTuSjd6AgmDBK+f+xv9ueYw= - dependencies: - homedir-polyfill "^1.0.1" - is-absolute "^1.0.0" - remove-trailing-separator "^1.1.0" - -require-directory@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/require-directory/-/require-directory-2.1.1.tgz#8c64ad5fd30dab1c976e2344ffe7f792a6a6df42" - integrity sha1-jGStX9MNqxyXbiNE/+f3kqam30I= - -require-from-string@~2.0: - version "2.0.2" - resolved "https://registry.yarnpkg.com/require-from-string/-/require-from-string-2.0.2.tgz#89a7fdd938261267318eafe14f9c32e598c36909" - integrity sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw== - -require-main-filename@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/require-main-filename/-/require-main-filename-1.0.1.tgz#97f717b69d48784f5f526a6c5aa8ffdda055a4d1" - integrity sha1-l/cXtp1IeE9fUmpsWqj/3aBVpNE= - -require-main-filename@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/require-main-filename/-/require-main-filename-2.0.0.tgz#d0b329ecc7cc0f61649f62215be69af54aa8989b" - integrity sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg== - -requires-port@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/requires-port/-/requires-port-1.0.0.tgz#925d2601d39ac485e091cf0da5c6e694dc3dcaff" - integrity sha1-kl0mAdOaxIXgkc8NpcbmlNw9yv8= - -resolve-dir@^1.0.0, resolve-dir@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/resolve-dir/-/resolve-dir-1.0.1.tgz#79a40644c362be82f26effe739c9bb5382046f43" - integrity sha1-eaQGRMNivoLybv/nOcm7U4IEb0M= - dependencies: - expand-tilde "^2.0.0" - global-modules "^1.0.0" - -resolve-options@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/resolve-options/-/resolve-options-1.1.0.tgz#32bb9e39c06d67338dc9378c0d6d6074566ad131" - integrity sha1-MrueOcBtZzONyTeMDW1gdFZq0TE= - dependencies: - value-or-function "^3.0.0" - -resolve-url@^0.2.1: - version "0.2.1" - resolved "https://registry.yarnpkg.com/resolve-url/-/resolve-url-0.2.1.tgz#2c637fe77c893afd2a663fe21aa9080068e2052a" - integrity sha1-LGN/53yJOv0qZj/iGqkIAGjiBSo= - -resolve@^1.1.6, resolve@^1.1.7, resolve@^1.10.0, resolve@^1.4.0: - version "1.19.0" - resolved "https://registry.yarnpkg.com/resolve/-/resolve-1.19.0.tgz#1af5bf630409734a067cae29318aac7fa29a267c" - integrity sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg== - dependencies: - is-core-module "^2.1.0" - path-parse "^1.0.6" - -responselike@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/responselike/-/responselike-1.0.2.tgz#918720ef3b631c5642be068f15ade5a46f4ba1e7" - integrity sha1-kYcg7ztjHFZCvgaPFa3lpG9Loec= - dependencies: - lowercase-keys "^1.0.0" - -ret@~0.1.10: - version "0.1.15" - resolved "https://registry.yarnpkg.com/ret/-/ret-0.1.15.tgz#b8a4825d5bdb1fc3f6f53c2bc33f81388681c7bc" - integrity sha512-TTlYpa+OL+vMMNG24xSlQGEJ3B/RzEfUlLct7b5G/ytav+wPrplCpVMFuwzXbkecJrb6IYo1iFb0S9v37754mg== - -safe-buffer@>=5.1.0, safe-buffer@^5.0.1, safe-buffer@^5.1.0, safe-buffer@~5.2.0: - version "5.2.1" - resolved "https://registry.yarnpkg.com/safe-buffer/-/safe-buffer-5.2.1.tgz#1eaf9fa9bdb1fdd4ec75f58f9cdb4e6b7827eec6" - integrity sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ== - -safe-buffer@~5.1.0, safe-buffer@~5.1.1: - version "5.1.2" - resolved "https://registry.yarnpkg.com/safe-buffer/-/safe-buffer-5.1.2.tgz#991ec69d296e0313747d59bdfd2b745c35f8828d" - integrity sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g== - -safe-json-parse@~1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/safe-json-parse/-/safe-json-parse-1.0.1.tgz#3e76723e38dfdda13c9b1d29a1e07ffee4b30b57" - integrity sha1-PnZyPjjf3aE8mx0poeB//uSzC1c= - -safe-regex@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/safe-regex/-/safe-regex-1.1.0.tgz#40a3669f3b077d1e943d44629e157dd48023bf2e" - integrity sha1-QKNmnzsHfR6UPURinhV91IAjvy4= - dependencies: - ret "~0.1.10" - -secure-compare@3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/secure-compare/-/secure-compare-3.0.1.tgz#f1a0329b308b221fae37b9974f3d578d0ca999e3" - integrity sha1-8aAymzCLIh+uN7mXTz1XjQypmeM= - -semver-greatest-satisfied-range@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/semver-greatest-satisfied-range/-/semver-greatest-satisfied-range-1.1.0.tgz#13e8c2658ab9691cb0cd71093240280d36f77a5b" - integrity sha1-E+jCZYq5aRywzXEJMkAoDTb3els= - dependencies: - sver-compat "^1.5.0" - -"semver@2 || 3 || 4 || 5": - version "5.7.1" - resolved "https://registry.yarnpkg.com/semver/-/semver-5.7.1.tgz#a954f931aeba508d307bbf069eff0c01c96116f7" - integrity sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ== - -send@0.17.1: - version "0.17.1" - resolved "https://registry.yarnpkg.com/send/-/send-0.17.1.tgz#c1d8b059f7900f7466dd4938bdc44e11ddb376c8" - integrity sha512-BsVKsiGcQMFwT8UxypobUKyv7irCNRHk1T0G680vk88yf6LBByGcZJOTJCrTP2xVN6yI+XjPJcNuE3V4fT9sAg== - dependencies: - debug "2.6.9" - depd "~1.1.2" - destroy "~1.0.4" - encodeurl "~1.0.2" - escape-html "~1.0.3" - etag "~1.8.1" - fresh "0.5.2" - http-errors "~1.7.2" - mime "1.6.0" - ms "2.1.1" - on-finished "~2.3.0" - range-parser "~1.2.1" - statuses "~1.5.0" - -send@^0.16.2: - version "0.16.2" - resolved "https://registry.yarnpkg.com/send/-/send-0.16.2.tgz#6ecca1e0f8c156d141597559848df64730a6bbc1" - integrity sha512-E64YFPUssFHEFBvpbbjr44NCLtI1AohxQ8ZSiJjQLskAdKuriYEP6VyGEsRDH8ScozGpkaX1BGvhanqCwkcEZw== - dependencies: - debug "2.6.9" - depd "~1.1.2" - destroy "~1.0.4" - encodeurl "~1.0.2" - escape-html "~1.0.3" - etag "~1.8.1" - fresh "0.5.2" - http-errors "~1.6.2" - mime "1.4.1" - ms "2.0.0" - on-finished "~2.3.0" - range-parser "~1.2.0" - statuses "~1.4.0" - -serve-index@^1.9.1: - version "1.9.1" - resolved "https://registry.yarnpkg.com/serve-index/-/serve-index-1.9.1.tgz#d3768d69b1e7d82e5ce050fff5b453bea12a9239" - integrity sha1-03aNabHn2C5c4FD/9bRTvqEqkjk= - dependencies: - accepts "~1.3.4" - batch "0.6.1" - debug "2.6.9" - escape-html "~1.0.3" - http-errors "~1.6.2" - mime-types "~2.1.17" - parseurl "~1.3.2" - -serve-static@^1.13.2: - version "1.14.1" - resolved "https://registry.yarnpkg.com/serve-static/-/serve-static-1.14.1.tgz#666e636dc4f010f7ef29970a88a674320898b2f9" - integrity sha512-JMrvUwE54emCYWlTI+hGrGv5I8dEwmco/00EvkzIIsR7MqrHonbD9pO2MOfFnpFntl7ecpZs+3mW+XbQZu9QCg== - dependencies: - encodeurl "~1.0.2" - escape-html "~1.0.3" - parseurl "~1.3.3" - send "0.17.1" - -set-blocking@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/set-blocking/-/set-blocking-2.0.0.tgz#045f9782d011ae9a6803ddd382b24392b3d890f7" - integrity sha1-BF+XgtARrppoA93TgrJDkrPYkPc= - -set-value@^2.0.0, set-value@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/set-value/-/set-value-2.0.1.tgz#a18d40530e6f07de4228c7defe4227af8cad005b" - integrity sha512-JxHc1weCN68wRY0fhCoXpyK55m/XPHafOmK4UWD7m2CI14GMcFypt4w/0+NV5f/ZMby2F6S2wwA7fgynh9gWSw== - dependencies: - extend-shallow "^2.0.1" - is-extendable "^0.1.1" - is-plain-object "^2.0.3" - split-string "^3.0.1" - -setprototypeof@1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/setprototypeof/-/setprototypeof-1.1.0.tgz#d0bd85536887b6fe7c0d818cb962d9d91c54e656" - integrity sha512-BvE/TwpZX4FXExxOxZyRGQQv651MSwmWKZGqvmPcRIjDqWub67kTKuIMx43cZZrS/cBBzwBcNDWoFxt2XEFIpQ== - -setprototypeof@1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/setprototypeof/-/setprototypeof-1.1.1.tgz#7e95acb24aa92f5885e0abef5ba131330d4ae683" - integrity sha512-JvdAWfbXeIGaZ9cILp38HntZSFSo3mWg6xGcJJsd+d4aRMOqauag1C63dJfDw7OaMYwEbHMOxEZ1lqVRYP2OAw== - -sha.js@^2.4.9: - version "2.4.11" - resolved "https://registry.yarnpkg.com/sha.js/-/sha.js-2.4.11.tgz#37a5cf0b81ecbc6943de109ba2960d1b26584ae7" - integrity sha512-QMEp5B7cftE7APOjk5Y6xgrbWu+WkLVQwk8JNjZ8nKRciZaByEW6MubieAiToS7+dwvrjGhH8jRXz3MVd0AYqQ== - dependencies: - inherits "^2.0.1" - safe-buffer "^5.0.1" - -simple-concat@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/simple-concat/-/simple-concat-1.0.1.tgz#f46976082ba35c2263f1c8ab5edfe26c41c9552f" - integrity sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q== - -simple-get@^3.0.2: - version "3.1.0" - resolved "https://registry.yarnpkg.com/simple-get/-/simple-get-3.1.0.tgz#b45be062435e50d159540b576202ceec40b9c6b3" - integrity sha512-bCR6cP+aTdScaQCnQKbPKtJOKDp/hj9EDLJo3Nw4y1QksqaovlW/bnptB6/c1e+qmNIDHRK+oXFDdEqBT8WzUA== - dependencies: - decompress-response "^4.2.0" - once "^1.3.1" - simple-concat "^1.0.0" - -snapdragon-node@^2.0.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/snapdragon-node/-/snapdragon-node-2.1.1.tgz#6c175f86ff14bdb0724563e8f3c1b021a286853b" - integrity sha512-O27l4xaMYt/RSQ5TR3vpWCAB5Kb/czIcqUFOM/C4fYcLnbZUc1PkjTAMjof2pBWaSTwOUd6qUHcFGVGj7aIwnw== - dependencies: - define-property "^1.0.0" - isobject "^3.0.0" - snapdragon-util "^3.0.1" - -snapdragon-util@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/snapdragon-util/-/snapdragon-util-3.0.1.tgz#f956479486f2acd79700693f6f7b805e45ab56e2" - integrity sha512-mbKkMdQKsjX4BAL4bRYTj21edOf8cN7XHdYUJEe+Zn99hVEYcMvKPct1IqNe7+AZPirn8BCDOQBHQZknqmKlZQ== - dependencies: - kind-of "^3.2.0" - -snapdragon@^0.8.1: - version "0.8.2" - resolved "https://registry.yarnpkg.com/snapdragon/-/snapdragon-0.8.2.tgz#64922e7c565b0e14204ba1aa7d6964278d25182d" - integrity sha512-FtyOnWN/wCHTVXOMwvSv26d+ko5vWlIDD6zoUJ7LW8vh+ZBC8QdljveRP+crNrtBwioEUWy/4dMtbBjA4ioNlg== - dependencies: - base "^0.11.1" - debug "^2.2.0" - define-property "^0.2.5" - extend-shallow "^2.0.1" - map-cache "^0.2.2" - source-map "^0.5.6" - source-map-resolve "^0.5.0" - use "^3.1.0" - -source-map-resolve@^0.5.0: - version "0.5.3" - resolved "https://registry.yarnpkg.com/source-map-resolve/-/source-map-resolve-0.5.3.tgz#190866bece7553e1f8f267a2ee82c606b5509a1a" - integrity sha512-Htz+RnsXWk5+P2slx5Jh3Q66vhQj1Cllm0zvnaY98+NFx+Dv2CF/f5O/t8x+KaNdrdIAsruNzoh/KpialbqAnw== - dependencies: - atob "^2.1.2" - decode-uri-component "^0.2.0" - resolve-url "^0.2.1" - source-map-url "^0.4.0" - urix "^0.1.0" - -source-map-url@^0.4.0: - version "0.4.0" - resolved "https://registry.yarnpkg.com/source-map-url/-/source-map-url-0.4.0.tgz#3e935d7ddd73631b97659956d55128e87b5084a3" - integrity sha1-PpNdfd1zYxuXZZlW1VEo6HtQhKM= - -source-map@^0.5.6: - version "0.5.7" - resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.5.7.tgz#8a039d2d1021d22d1ea14c80d8ea468ba2ef3fcc" - integrity sha1-igOdLRAh0i0eoUyA2OpGi6LvP8w= - -source-map@^0.6.1: - version "0.6.1" - resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.6.1.tgz#74722af32e9614e9c287a8d0bbde48b5e2f1a263" - integrity sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g== - -sparkles@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/sparkles/-/sparkles-1.0.1.tgz#008db65edce6c50eec0c5e228e1945061dd0437c" - integrity sha512-dSO0DDYUahUt/0/pD/Is3VIm5TGJjludZ0HVymmhYF6eNA53PVLhnUk0znSYbH8IYBuJdCE+1luR22jNLMaQdw== - -spdx-correct@^3.0.0: - version "3.1.1" - resolved "https://registry.yarnpkg.com/spdx-correct/-/spdx-correct-3.1.1.tgz#dece81ac9c1e6713e5f7d1b6f17d468fa53d89a9" - integrity sha512-cOYcUWwhCuHCXi49RhFRCyJEK3iPj1Ziz9DpViV3tbZOwXD49QzIN3MpOLJNxh2qwq2lJJZaKMVw9qNi4jTC0w== - dependencies: - spdx-expression-parse "^3.0.0" - spdx-license-ids "^3.0.0" - -spdx-exceptions@^2.1.0: - version "2.3.0" - resolved "https://registry.yarnpkg.com/spdx-exceptions/-/spdx-exceptions-2.3.0.tgz#3f28ce1a77a00372683eade4a433183527a2163d" - integrity sha512-/tTrYOC7PPI1nUAgx34hUpqXuyJG+DTHJTnIULG4rDygi4xu/tfgmq1e1cIRwRzwZgo4NLySi+ricLkZkw4i5A== - -spdx-expression-parse@^3.0.0: - version "3.0.1" - resolved "https://registry.yarnpkg.com/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz#cf70f50482eefdc98e3ce0a6833e4a53ceeba679" - integrity sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q== - dependencies: - spdx-exceptions "^2.1.0" - spdx-license-ids "^3.0.0" - -spdx-license-ids@^3.0.0: - version "3.0.7" - resolved "https://registry.yarnpkg.com/spdx-license-ids/-/spdx-license-ids-3.0.7.tgz#e9c18a410e5ed7e12442a549fbd8afa767038d65" - integrity sha512-U+MTEOO0AiDzxwFvoa4JVnMV6mZlJKk2sBLt90s7G0Gd0Mlknc7kxEn3nuDPNZRta7O2uy8oLcZLVT+4sqNZHQ== - -split-string@^3.0.1, split-string@^3.0.2: - version "3.1.0" - resolved "https://registry.yarnpkg.com/split-string/-/split-string-3.1.0.tgz#7cb09dda3a86585705c64b39a6466038682e8fe2" - integrity sha512-NzNVhJDYpwceVVii8/Hu6DKfD2G+NrQHlS/V/qgv763EYudVwEcMQNxd2lh+0VrUByXN/oJkl5grOhYWvQUYiw== - dependencies: - extend-shallow "^3.0.0" - -sprintf-js@~1.0.2: - version "1.0.3" - resolved "https://registry.yarnpkg.com/sprintf-js/-/sprintf-js-1.0.3.tgz#04e6926f662895354f3dd015203633b857297e2c" - integrity sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw= - -stack-trace@0.0.10: - version "0.0.10" - resolved "https://registry.yarnpkg.com/stack-trace/-/stack-trace-0.0.10.tgz#547c70b347e8d32b4e108ea1a2a159e5fdde19c0" - integrity sha1-VHxws0fo0ytOEI6hoqFZ5f3eGcA= - -static-extend@^0.1.1: - version "0.1.2" - resolved "https://registry.yarnpkg.com/static-extend/-/static-extend-0.1.2.tgz#60809c39cbff55337226fd5e0b520f341f1fb5c6" - integrity sha1-YICcOcv/VTNyJv1eC1IPNB8ftcY= - dependencies: - define-property "^0.2.5" - object-copy "^0.1.0" - -"statuses@>= 1.4.0 < 2", "statuses@>= 1.5.0 < 2", statuses@~1.5.0: - version "1.5.0" - resolved "https://registry.yarnpkg.com/statuses/-/statuses-1.5.0.tgz#161c7dac177659fd9811f43771fa99381478628c" - integrity sha1-Fhx9rBd2Wf2YEfQ3cfqZOBR4Yow= - -statuses@~1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/statuses/-/statuses-1.4.0.tgz#bb73d446da2796106efcc1b601a253d6c46bd087" - integrity sha512-zhSCtt8v2NDrRlPQpCNtw/heZLtfUDqxBM1udqikb/Hbk52LK4nQSwr10u77iopCW5LsyHpuXS0GnEc48mLeew== - -stream-exhaust@^1.0.1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/stream-exhaust/-/stream-exhaust-1.0.2.tgz#acdac8da59ef2bc1e17a2c0ccf6c320d120e555d" - integrity sha512-b/qaq/GlBK5xaq1yrK9/zFcyRSTNxmcZwFLGSTG0mXgZl/4Z6GgiyYOXOvY7N3eEvFRAG1bkDRz5EPGSvPYQlw== - -stream-shift@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/stream-shift/-/stream-shift-1.0.1.tgz#d7088281559ab2778424279b0877da3c392d5a3d" - integrity sha512-AiisoFqQ0vbGcZgQPY1cdP2I76glaVA/RauYR4G4thNFgkTqr90yXTo4LYX60Jl+sIlPNHHdGSwo01AvbKUSVQ== - -string-template@~0.2.1: - version "0.2.1" - resolved "https://registry.yarnpkg.com/string-template/-/string-template-0.2.1.tgz#42932e598a352d01fc22ec3367d9d84eec6c9add" - integrity sha1-QpMuWYo1LQH8IuwzZ9nYTuxsmt0= - -string-width@^1.0.1, string-width@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/string-width/-/string-width-1.0.2.tgz#118bdf5b8cdc51a2a7e70d211e07e2b0b9b107d3" - integrity sha1-EYvfW4zcUaKn5w0hHgfisLmxB9M= - dependencies: - code-point-at "^1.0.0" - is-fullwidth-code-point "^1.0.0" - strip-ansi "^3.0.0" - -string-width@^4.1.0, string-width@^4.2.0: - version "4.2.0" - resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.0.tgz#952182c46cc7b2c313d1596e623992bd163b72b5" - integrity sha512-zUz5JD+tgqtuDjMhwIg5uFVV3dtqZ9yQJlZVfq4I01/K5Paj5UHj7VyrQOJvzawSVlKpObApbfD0Ed6yJc+1eg== - dependencies: - emoji-regex "^8.0.0" - is-fullwidth-code-point "^3.0.0" - strip-ansi "^6.0.0" - -string_decoder@0.10: - version "0.10.31" - resolved "https://registry.yarnpkg.com/string_decoder/-/string_decoder-0.10.31.tgz#62e203bc41766c6c28c9fc84301dab1c5310fa94" - integrity sha1-YuIDvEF2bGwoyfyEMB2rHFMQ+pQ= - -string_decoder@^1.1.1: - version "1.3.0" - resolved "https://registry.yarnpkg.com/string_decoder/-/string_decoder-1.3.0.tgz#42f114594a46cf1a8e30b0a84f56c78c3edac21e" - integrity sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA== - dependencies: - safe-buffer "~5.2.0" - -string_decoder@~1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/string_decoder/-/string_decoder-1.1.1.tgz#9cf1611ba62685d7030ae9e4ba34149c3af03fc8" - integrity sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg== - dependencies: - safe-buffer "~5.1.0" - -strip-ansi@^3.0.0, strip-ansi@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-3.0.1.tgz#6a385fb8853d952d5ff05d0e8aaf94278dc63dcf" - integrity sha1-ajhfuIU9lS1f8F0Oiq+UJ43GPc8= - dependencies: - ansi-regex "^2.0.0" - -strip-ansi@^6.0.0: - version "6.0.0" - resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.0.tgz#0b1571dd7669ccd4f3e06e14ef1eed26225ae532" - integrity sha512-AuvKTrTfQNYNIctbR1K/YGTR1756GycPsg7b9bdV9Duqur4gv6aKqHXah67Z8ImS7WEz5QVcOtlfW2rZEugt6w== - dependencies: - ansi-regex "^5.0.0" - -strip-bom@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/strip-bom/-/strip-bom-2.0.0.tgz#6219a85616520491f35788bdbf1447a99c7e6b0e" - integrity sha1-YhmoVhZSBJHzV4i9vxRHqZx+aw4= - dependencies: - is-utf8 "^0.2.0" - -sver-compat@^1.5.0: - version "1.5.0" - resolved "https://registry.yarnpkg.com/sver-compat/-/sver-compat-1.5.0.tgz#3cf87dfeb4d07b4a3f14827bc186b3fd0c645cd8" - integrity sha1-PPh9/rTQe0o/FIJ7wYaz/QxkXNg= - dependencies: - es6-iterator "^2.0.1" - es6-symbol "^3.1.1" - -through2-filter@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/through2-filter/-/through2-filter-3.0.0.tgz#700e786df2367c2c88cd8aa5be4cf9c1e7831254" - integrity sha512-jaRjI2WxN3W1V8/FMZ9HKIBXixtiqs3SQSX4/YGIiP3gL6djW48VoZq9tDqeCWs3MT8YY5wb/zli8VW8snY1CA== - dependencies: - through2 "~2.0.0" - xtend "~4.0.0" - -through2@^2.0.0, through2@^2.0.3, through2@~2.0.0: - version "2.0.5" - resolved "https://registry.yarnpkg.com/through2/-/through2-2.0.5.tgz#01c1e39eb31d07cb7d03a96a70823260b23132cd" - integrity sha512-/mrRod8xqpA+IHSLyGCQ2s8SPHiCDEeQJSep1jqLYeEUClOFG2Qsh+4FU6G9VeqpZnGW/Su8LQGc4YKni5rYSQ== - dependencies: - readable-stream "~2.3.6" - xtend "~4.0.1" - -through2@~4.0: - version "4.0.2" - resolved "https://registry.yarnpkg.com/through2/-/through2-4.0.2.tgz#a7ce3ac2a7a8b0b966c80e7c49f0484c3b239764" - integrity sha512-iOqSav00cVxEEICeD7TjLB1sueEL+81Wpzp2bY17uZjZN0pWZPuo4suZ/61VujxmqSGFfgOcNuTZ85QJwNZQpw== - dependencies: - readable-stream "3" - -through@^2.3.8: - version "2.3.8" - resolved "https://registry.yarnpkg.com/through/-/through-2.3.8.tgz#0dd4c9ffaabc357960b1b724115d7e0e86a2e1f5" - integrity sha1-DdTJ/6q8NXlgsbckEV1+Doai4fU= - -time-stamp@^1.0.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/time-stamp/-/time-stamp-1.1.0.tgz#764a5a11af50561921b133f3b44e618687e0f5c3" - integrity sha1-dkpaEa9QVhkhsTPztE5hhofg9cM= - -tiny-lr@^1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/tiny-lr/-/tiny-lr-1.1.1.tgz#9fa547412f238fedb068ee295af8b682c98b2aab" - integrity sha512-44yhA3tsaRoMOjQQ+5v5mVdqef+kH6Qze9jTpqtVufgYjYt08zyZAwNwwVBj3i1rJMnR52IxOW0LK0vBzgAkuA== - dependencies: - body "^5.1.0" - debug "^3.1.0" - faye-websocket "~0.10.0" - livereload-js "^2.3.0" - object-assign "^4.1.0" - qs "^6.4.0" - -to-absolute-glob@^2.0.0: - version "2.0.2" - resolved "https://registry.yarnpkg.com/to-absolute-glob/-/to-absolute-glob-2.0.2.tgz#1865f43d9e74b0822db9f145b78cff7d0f7c849b" - integrity sha1-GGX0PZ50sIItufFFt4z/fQ98hJs= - dependencies: - is-absolute "^1.0.0" - is-negated-glob "^1.0.0" - -to-object-path@^0.3.0: - version "0.3.0" - resolved "https://registry.yarnpkg.com/to-object-path/-/to-object-path-0.3.0.tgz#297588b7b0e7e0ac08e04e672f85c1f4999e17af" - integrity sha1-KXWIt7Dn4KwI4E5nL4XB9JmeF68= - dependencies: - kind-of "^3.0.2" - -to-readable-stream@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/to-readable-stream/-/to-readable-stream-1.0.0.tgz#ce0aa0c2f3df6adf852efb404a783e77c0475771" - integrity sha512-Iq25XBt6zD5npPhlLVXGFN3/gyR2/qODcKNNyTMd4vbm39HUaOiAM4PMq0eMVC/Tkxz+Zjdsc55g9yyz+Yq00Q== - -to-regex-range@^2.1.0: - version "2.1.1" - resolved "https://registry.yarnpkg.com/to-regex-range/-/to-regex-range-2.1.1.tgz#7c80c17b9dfebe599e27367e0d4dd5590141db38" - integrity sha1-fIDBe53+vlmeJzZ+DU3VWQFB2zg= - dependencies: - is-number "^3.0.0" - repeat-string "^1.6.1" - -to-regex-range@^5.0.1: - version "5.0.1" - resolved "https://registry.yarnpkg.com/to-regex-range/-/to-regex-range-5.0.1.tgz#1648c44aae7c8d988a326018ed72f5b4dd0392e4" - integrity sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ== - dependencies: - is-number "^7.0.0" - -to-regex@^3.0.1, to-regex@^3.0.2: - version "3.0.2" - resolved "https://registry.yarnpkg.com/to-regex/-/to-regex-3.0.2.tgz#13cfdd9b336552f30b51f33a8ae1b42a7a7599ce" - integrity sha512-FWtleNAtZ/Ki2qtqej2CXTOayOH9bHDQF+Q48VpWyDXjbYxA4Yz8iDB31zXOBUlOHHKidDbqGVrTUvQMPmBGBw== - dependencies: - define-property "^2.0.2" - extend-shallow "^3.0.2" - regex-not "^1.0.2" - safe-regex "^1.1.0" - -to-through@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/to-through/-/to-through-2.0.0.tgz#fc92adaba072647bc0b67d6b03664aa195093af6" - integrity sha1-/JKtq6ByZHvAtn1rA2ZKoZUJOvY= - dependencies: - through2 "^2.0.3" - -to-utf8@0.0.1: - version "0.0.1" - resolved "https://registry.yarnpkg.com/to-utf8/-/to-utf8-0.0.1.tgz#d17aea72ff2fba39b9e43601be7b3ff72e089852" - integrity sha1-0Xrqcv8vujm55DYBvns/9y4ImFI= - -toidentifier@1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/toidentifier/-/toidentifier-1.0.0.tgz#7e1be3470f1e77948bc43d94a3c8f4d7752ba553" - integrity sha512-yaOH/Pk/VEhBWWTlhI+qXxDFXlejDGcQipMlyxda9nthulaxLZUNcUqFxokp0vcYnvteJln5FNQDRrxj3YcbVw== - -type@^1.0.1: - version "1.2.0" - resolved "https://registry.yarnpkg.com/type/-/type-1.2.0.tgz#848dd7698dafa3e54a6c479e759c4bc3f18847a0" - integrity sha512-+5nt5AAniqsCnu2cEQQdpzCAh33kVx8n0VoFidKpB1dVVLAN/F+bgVOqOJqOnEnrhp222clB5p3vUlD+1QAnfg== - -type@^2.0.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/type/-/type-2.1.0.tgz#9bdc22c648cf8cf86dd23d32336a41cfb6475e3f" - integrity sha512-G9absDWvhAWCV2gmF1zKud3OyC61nZDwWvBL2DApaVFogI07CprggiQAOOjvp2NRjYWFzPyu7vwtDrQFq8jeSA== - -typedarray@^0.0.6: - version "0.0.6" - resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777" - integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c= - -uglify-js@^3.1.4: - version "3.12.4" - resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.12.4.tgz#93de48bb76bb3ec0fc36563f871ba46e2ee5c7ee" - integrity sha512-L5i5jg/SHkEqzN18gQMTWsZk3KelRsfD1wUVNqtq0kzqWQqcJjyL8yc1o8hJgRrWqrAl2mUFbhfznEIoi7zi2A== - -unc-path-regex@^0.1.2: - version "0.1.2" - resolved "https://registry.yarnpkg.com/unc-path-regex/-/unc-path-regex-0.1.2.tgz#e73dd3d7b0d7c5ed86fbac6b0ae7d8c6a69d50fa" - integrity sha1-5z3T17DXxe2G+6xrCufYxqadUPo= - -undertaker-registry@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/undertaker-registry/-/undertaker-registry-1.0.1.tgz#5e4bda308e4a8a2ae584f9b9a4359a499825cc50" - integrity sha1-XkvaMI5KiirlhPm5pDWaSZglzFA= - -undertaker@^1.2.1: - version "1.3.0" - resolved "https://registry.yarnpkg.com/undertaker/-/undertaker-1.3.0.tgz#363a6e541f27954d5791d6fa3c1d321666f86d18" - integrity sha512-/RXwi5m/Mu3H6IHQGww3GNt1PNXlbeCuclF2QYR14L/2CHPz3DFZkvB5hZ0N/QUkiXWCACML2jXViIQEQc2MLg== - dependencies: - arr-flatten "^1.0.1" - arr-map "^2.0.0" - bach "^1.0.0" - collection-map "^1.0.0" - es6-weak-map "^2.0.1" - fast-levenshtein "^1.0.0" - last-run "^1.1.0" - object.defaults "^1.0.0" - object.reduce "^1.0.0" - undertaker-registry "^1.0.0" - -union-value@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/union-value/-/union-value-1.0.1.tgz#0b6fe7b835aecda61c6ea4d4f02c14221e109847" - integrity sha512-tJfXmxMeWYnczCVs7XAEvIV7ieppALdyepWMkHkwciRpZraG/xwT+s2JN8+pr1+8jCRf80FFzvr+MpQeeoF4Xg== - dependencies: - arr-union "^3.1.0" - get-value "^2.0.6" - is-extendable "^0.1.1" - set-value "^2.0.1" - -union@~0.5.0: - version "0.5.0" - resolved "https://registry.yarnpkg.com/union/-/union-0.5.0.tgz#b2c11be84f60538537b846edb9ba266ba0090075" - integrity sha512-N6uOhuW6zO95P3Mel2I2zMsbsanvvtgn6jVqJv4vbVcz/JN0OkL9suomjQGmWtxJQXOCqUJvquc1sMeNz/IwlA== - dependencies: - qs "^6.4.0" - -unique-stream@^2.0.2: - version "2.3.1" - resolved "https://registry.yarnpkg.com/unique-stream/-/unique-stream-2.3.1.tgz#c65d110e9a4adf9a6c5948b28053d9a8d04cbeac" - integrity sha512-2nY4TnBE70yoxHkDli7DMazpWiP7xMdCYqU2nBRO0UB+ZpEkGsSija7MvmvnZFUeC+mrgiUfcHSr3LmRFIg4+A== - dependencies: - json-stable-stringify-without-jsonify "^1.0.1" - through2-filter "^3.0.0" - -universalify@^0.1.0: - version "0.1.2" - resolved "https://registry.yarnpkg.com/universalify/-/universalify-0.1.2.tgz#b646f69be3942dabcecc9d6639c80dc105efaa66" - integrity sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg== - -unpipe@~1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/unpipe/-/unpipe-1.0.0.tgz#b2bf4ee8514aae6165b4817829d21b2ef49904ec" - integrity sha1-sr9O6FFKrmFltIF4KdIbLvSZBOw= - -unset-value@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/unset-value/-/unset-value-1.0.0.tgz#8376873f7d2335179ffb1e6fc3a8ed0dfc8ab559" - integrity sha1-g3aHP30jNRef+x5vw6jtDfyKtVk= - dependencies: - has-value "^0.3.1" - isobject "^3.0.0" - -unxhr@1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/unxhr/-/unxhr-1.0.1.tgz#92200322d66c728993de771f9e01eeb21f41bc7b" - integrity sha512-MAhukhVHyaLGDjyDYhy8gVjWJyhTECCdNsLwlMoGFoNJ3o79fpQhtQuzmAE4IxCMDwraF4cW8ZjpAV0m9CRQbg== - -upath@^1.1.1: - version "1.2.0" - resolved "https://registry.yarnpkg.com/upath/-/upath-1.2.0.tgz#8f66dbcd55a883acdae4408af8b035a5044c1894" - integrity sha512-aZwGpamFO61g3OlfT7OQCHqhGnW43ieH9WZeP7QxN/G/jS4jfqUkZxoryvJgVPEcrl5NL/ggHsSmLMHuH64Lhg== - -urix@^0.1.0: - version "0.1.0" - resolved "https://registry.yarnpkg.com/urix/-/urix-0.1.0.tgz#da937f7a62e21fec1fd18d49b35c2935067a6c72" - integrity sha1-2pN/emLiH+wf0Y1Js1wpNQZ6bHI= - -url-join@^2.0.5: - version "2.0.5" - resolved "https://registry.yarnpkg.com/url-join/-/url-join-2.0.5.tgz#5af22f18c052a000a48d7b82c5e9c2e2feeda728" - integrity sha1-WvIvGMBSoACkjXuCxenC4v7tpyg= - -url-parse-lax@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/url-parse-lax/-/url-parse-lax-3.0.0.tgz#16b5cafc07dbe3676c1b1999177823d6503acb0c" - integrity sha1-FrXK/Afb42dsGxmZF3gj1lA6yww= - dependencies: - prepend-http "^2.0.0" - -use@^3.1.0: - version "3.1.1" - resolved "https://registry.yarnpkg.com/use/-/use-3.1.1.tgz#d50c8cac79a19fbc20f2911f56eb973f4e10070f" - integrity sha512-cwESVXlO3url9YWlFW/TA9cshCEhtu7IKJ/p5soJ/gGpj7vbvFrAY/eIioQ6Dw23KjZhYgiIo8HOs1nQ2vr/oQ== - -util-deprecate@^1.0.1, util-deprecate@~1.0.1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf" - integrity sha1-RQ1Nyfpw3nMnYvvS1KKJgUGaDM8= - -utils-merge@1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/utils-merge/-/utils-merge-1.0.1.tgz#9f95710f50a267947b2ccc124741c1028427e713" - integrity sha1-n5VxD1CiZ5R7LMwSR0HBAoQn5xM= - -v8flags@^3.2.0: - version "3.2.0" - resolved "https://registry.yarnpkg.com/v8flags/-/v8flags-3.2.0.tgz#b243e3b4dfd731fa774e7492128109a0fe66d656" - integrity sha512-mH8etigqMfiGWdeXpaaqGfs6BndypxusHHcv2qSHyZkGEznCd/qAXCWWRzeowtL54147cktFOC4P5y+kl8d8Jg== - dependencies: - homedir-polyfill "^1.0.1" - -validate-npm-package-license@^3.0.1: - version "3.0.4" - resolved "https://registry.yarnpkg.com/validate-npm-package-license/-/validate-npm-package-license-3.0.4.tgz#fc91f6b9c7ba15c857f4cb2c5defeec39d4f410a" - integrity sha512-DpKm2Ui/xN7/HQKCtpZxoRWBhZ9Z0kqtygG8XCgNQ8ZlDnxuQmWhj566j8fN4Cu3/JmbhsDo7fcAJq4s9h27Ew== - dependencies: - spdx-correct "^3.0.0" - spdx-expression-parse "^3.0.0" - -value-or-function@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/value-or-function/-/value-or-function-3.0.0.tgz#1c243a50b595c1be54a754bfece8563b9ff8d813" - integrity sha1-HCQ6ULWVwb5Up1S/7OhWO5/42BM= - -varint@0.0.3: - version "0.0.3" - resolved "https://registry.yarnpkg.com/varint/-/varint-0.0.3.tgz#b821de9b04b38b3cd22f72c18d94a9fb72ab3518" - integrity sha1-uCHemwSzizzSL3LBjZSp+3KrNRg= - -vinyl-fs@^3.0.0, vinyl-fs@^3.0.3, vinyl-fs@~3.0: - version "3.0.3" - resolved "https://registry.yarnpkg.com/vinyl-fs/-/vinyl-fs-3.0.3.tgz#c85849405f67428feabbbd5c5dbdd64f47d31bc7" - integrity sha512-vIu34EkyNyJxmP0jscNzWBSygh7VWhqun6RmqVfXePrOwi9lhvRs//dOaGOTRUQr4tx7/zd26Tk5WeSVZitgng== - dependencies: - fs-mkdirp-stream "^1.0.0" - glob-stream "^6.1.0" - graceful-fs "^4.0.0" - is-valid-glob "^1.0.0" - lazystream "^1.0.0" - lead "^1.0.0" - object.assign "^4.0.4" - pumpify "^1.3.5" - readable-stream "^2.3.3" - remove-bom-buffer "^3.0.0" - remove-bom-stream "^1.2.0" - resolve-options "^1.1.0" - through2 "^2.0.0" - to-through "^2.0.0" - value-or-function "^3.0.0" - vinyl "^2.0.0" - vinyl-sourcemap "^1.1.0" - -vinyl-sourcemap@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/vinyl-sourcemap/-/vinyl-sourcemap-1.1.0.tgz#92a800593a38703a8cdb11d8b300ad4be63b3e16" - integrity sha1-kqgAWTo4cDqM2xHYswCtS+Y7PhY= - dependencies: - append-buffer "^1.0.2" - convert-source-map "^1.5.0" - graceful-fs "^4.1.6" - normalize-path "^2.1.1" - now-and-later "^2.0.0" - remove-bom-buffer "^3.0.0" - vinyl "^2.0.0" - -vinyl@^2.0.0, vinyl@^2.0.2, vinyl@~2.2: - version "2.2.1" - resolved "https://registry.yarnpkg.com/vinyl/-/vinyl-2.2.1.tgz#23cfb8bbab5ece3803aa2c0a1eb28af7cbba1974" - integrity sha512-LII3bXRFBZLlezoG5FfZVcXflZgWP/4dCwKtxd5ky9+LOtM4CS3bIRQsmR1KMnMW07jpE8fqR2lcxPZ+8sJIcw== - dependencies: - clone "^2.1.1" - clone-buffer "^1.0.0" - clone-stats "^1.0.0" - cloneable-readable "^1.0.0" - remove-trailing-separator "^1.0.1" - replace-ext "^1.0.0" - -websocket-driver@>=0.5.1: - version "0.7.4" - resolved "https://registry.yarnpkg.com/websocket-driver/-/websocket-driver-0.7.4.tgz#89ad5295bbf64b480abcba31e4953aca706f5760" - integrity sha512-b17KeDIQVjvb0ssuSDF2cYXSg2iztliJ4B9WdsuB6J952qCPKmnVq4DyW5motImXHDC1cBT/1UezrJVsKw5zjg== - dependencies: - http-parser-js ">=0.5.1" - safe-buffer ">=5.1.0" - websocket-extensions ">=0.1.1" - -websocket-extensions@>=0.1.1: - version "0.1.4" - resolved "https://registry.yarnpkg.com/websocket-extensions/-/websocket-extensions-0.1.4.tgz#7f8473bc839dfd87608adb95d7eb075211578a42" - integrity sha512-OqedPIGOfsDlo31UNwYbCFMSaO9m9G/0faIHj5/dZFDMFqPTcx6UwqyOy3COEaEOg/9VsGIpdqn62W5KhoKSpg== - -which-module@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/which-module/-/which-module-1.0.0.tgz#bba63ca861948994ff307736089e3b96026c2a4f" - integrity sha1-u6Y8qGGUiZT/MHc2CJ47lgJsKk8= - -which-module@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/which-module/-/which-module-2.0.0.tgz#d9ef07dce77b9902b8a3a8fa4b31c3e3f7e6e87a" - integrity sha1-2e8H3Od7mQK4o6j6SzHD4/fm6Ho= - -which@^1.2.14: - version "1.3.1" - resolved "https://registry.yarnpkg.com/which/-/which-1.3.1.tgz#a45043d54f5805316da8d62f9f50918d3da70b0a" - integrity sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ== - dependencies: - isexe "^2.0.0" - -wordwrap@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb" - integrity sha1-J1hIEIkUVqQXHI0CJkQa3pDLyus= - -wrap-ansi@^2.0.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-2.1.0.tgz#d8fc3d284dd05794fe84973caecdd1cf824fdd85" - integrity sha1-2Pw9KE3QV5T+hJc8rs3Rz4JP3YU= - dependencies: - string-width "^1.0.1" - strip-ansi "^3.0.1" - -wrap-ansi@^6.2.0: - version "6.2.0" - resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-6.2.0.tgz#e9393ba07102e6c91a3b221478f0257cd2856e53" - integrity sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA== - dependencies: - ansi-styles "^4.0.0" - string-width "^4.1.0" - strip-ansi "^6.0.0" - -wrappy@1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/wrappy/-/wrappy-1.0.2.tgz#b5243d8f3ec1aa35f1364605bc0d1036e30ab69f" - integrity sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8= - -xdg-basedir@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/xdg-basedir/-/xdg-basedir-3.0.0.tgz#496b2cc109eca8dbacfe2dc72b603c17c5870ad4" - integrity sha1-SWsswQnsqNus/i3HK2A8F8WHCtQ= - -xmlhttprequest@1.8.0: - version "1.8.0" - resolved "https://registry.yarnpkg.com/xmlhttprequest/-/xmlhttprequest-1.8.0.tgz#67fe075c5c24fef39f9d65f5f7b7fe75171968fc" - integrity sha1-Z/4HXFwk/vOfnWX197f+dRcZaPw= - -xtend@~4.0.0, xtend@~4.0.1: - version "4.0.2" - resolved "https://registry.yarnpkg.com/xtend/-/xtend-4.0.2.tgz#bb72779f5fa465186b1f438f674fa347fdb5db54" - integrity sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ== - -y18n@^3.2.1: - version "3.2.2" - resolved "https://registry.yarnpkg.com/y18n/-/y18n-3.2.2.tgz#85c901bd6470ce71fc4bb723ad209b70f7f28696" - integrity sha512-uGZHXkHnhF0XeeAPgnKfPv1bgKAYyVvmNL1xlKsPYZPaIHxGti2hHqvOCQv71XMsLxu1QjergkqogUnms5D3YQ== - -y18n@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/y18n/-/y18n-4.0.1.tgz#8db2b83c31c5d75099bb890b23f3094891e247d4" - integrity sha512-wNcy4NvjMYL8gogWWYAO7ZFWFfHcbdbE57tZO8e4cbpj8tfUcwrwqSl3ad8HxpYWCdXcJUCeKKZS62Av1affwQ== - -yargs-parser@5.0.0-security.0: - version "5.0.0-security.0" - resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-5.0.0-security.0.tgz#4ff7271d25f90ac15643b86076a2ab499ec9ee24" - integrity sha512-T69y4Ps64LNesYxeYGYPvfoMTt/7y1XtfpIslUeK4um+9Hu7hlGoRtaDLvdXb7+/tfq4opVa2HRY5xGip022rQ== - dependencies: - camelcase "^3.0.0" - object.assign "^4.1.0" - -yargs-parser@^18.1.1, yargs-parser@^18.1.3: - version "18.1.3" - resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-18.1.3.tgz#be68c4975c6b2abf469236b0c870362fab09a7b0" - integrity sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ== - dependencies: - camelcase "^5.0.0" - decamelize "^1.2.0" - -yargs@15.3.1: - version "15.3.1" - resolved "https://registry.yarnpkg.com/yargs/-/yargs-15.3.1.tgz#9505b472763963e54afe60148ad27a330818e98b" - integrity sha512-92O1HWEjw27sBfgmXiixJWT5hRBp2eobqXicLtPBIDBhYB+1HpwZlXmbW2luivBJHBzki+7VyCLRtAkScbTBQA== - dependencies: - cliui "^6.0.0" - decamelize "^1.2.0" - find-up "^4.1.0" - get-caller-file "^2.0.1" - require-directory "^2.1.1" - require-main-filename "^2.0.0" - set-blocking "^2.0.0" - string-width "^4.2.0" - which-module "^2.0.0" - y18n "^4.0.0" - yargs-parser "^18.1.1" - -yargs@^7.1.0: - version "7.1.1" - resolved "https://registry.yarnpkg.com/yargs/-/yargs-7.1.1.tgz#67f0ef52e228d4ee0d6311acede8850f53464df6" - integrity sha512-huO4Fr1f9PmiJJdll5kwoS2e4GqzGSsMT3PPMpOwoVkOK8ckqAewMTZyA6LXVQWflleb/Z8oPBEvNsMft0XE+g== - dependencies: - camelcase "^3.0.0" - cliui "^3.2.0" - decamelize "^1.1.1" - get-caller-file "^1.0.1" - os-locale "^1.4.0" - read-pkg-up "^1.0.1" - require-directory "^2.1.1" - require-main-filename "^1.0.1" - set-blocking "^2.0.0" - string-width "^1.0.2" - which-module "^1.0.0" - y18n "^3.2.1" - yargs-parser "5.0.0-security.0" - -yauzl@^2.2.1: - version "2.10.0" - resolved "https://registry.yarnpkg.com/yauzl/-/yauzl-2.10.0.tgz#c7eb17c93e112cb1086fa6d8e51fb0667b79a5f9" - integrity sha1-x+sXyT4RLLEIb6bY5R+wZnt5pfk= - dependencies: - buffer-crc32 "~0.2.3" - fd-slicer "~1.1.0" - -yazl@^2.2.1: - version "2.5.1" - resolved "https://registry.yarnpkg.com/yazl/-/yazl-2.5.1.tgz#a3d65d3dd659a5b0937850e8609f22fffa2b5c35" - integrity sha512-phENi2PLiHnHb6QBVot+dJnaAZ0xosj7p3fWl+znIjBDlnMI2PsZCJZ306BPTFOaHf5qdDEI8x5qFrSOBN5vrw== - dependencies: - buffer-crc32 "~0.2.3"