From e0bd780f69f550451dfb5a0f2df09b1e6ff792aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Thu, 24 Oct 2019 17:29:18 +0200 Subject: [PATCH 1/2] Remove Che 6 docs. --- src/main/404.adoc | 1 - src/main/_data/sidebars/che_6_docs.yml | 296 -------- src/main/_data/sidebars/che_7_docs.yml | 4 +- src/main/_data/sidebars/che_docs_home.yml | 19 - src/main/_data/topnav.yml | 6 - src/main/_includes/sidebar.html | 4 +- src/main/index.adoc | 16 - src/main/pages/che-6/dev_essentials/dto.adoc | 446 ------------ .../pages/che-6/dev_essentials/guice.adoc | 149 ---- .../handling-projects-in-plugins.adoc | 164 ----- .../pages/che-6/dev_essentials/json-rpc.adoc | 93 --- .../pages/che-6/developer-guide/actions.adoc | 460 ------------- .../che-6/developer-guide/assemblies.adoc | 214 ------ .../che-6/developer-guide/build-reqs.adoc | 67 -- .../che-in-che-quickstart.adoc | 83 --- .../pages/che-6/developer-guide/cors.adoc | 45 -- .../developer-guide/custom-installers.adoc | 195 ------ src/main/pages/che-6/developer-guide/dao.adoc | 29 - .../che-6/developer-guide/databases.adoc | 185 ----- .../pages/che-6/developer-guide/editor.adoc | 10 - .../developer-guide/framework-overview.adoc | 22 - .../che-6/developer-guide/framework.adoc | 10 - .../developer-guide/ide-extensions-gwt.adoc | 212 ------ .../developer-guide/language-servers.adoc | 134 ---- .../pages/che-6/developer-guide/logging.adoc | 111 --- .../pages/che-6/developer-guide/parts.adoc | 264 ------- .../che-6/developer-guide/project-types.adoc | 371 ---------- .../che-6/developer-guide/properties.adoc | 92 --- .../pages/che-6/developer-guide/registry.adoc | 10 - .../pages/che-6/developer-guide/rest-api.adoc | 18 - .../server-side-extensions.adoc | 12 - .../pages/che-6/developer-guide/themes.adoc | 10 - .../developer-guide/workspace-agent.adoc | 81 --- .../pages/che-6/overview/infra-support.adoc | 75 -- .../pages/che-6/overview/introduction.adoc | 141 ---- .../pages/che-6/overview/quick-start.adoc | 92 --- .../che-6/overview/single-multi-user.adoc | 45 -- .../chedir-getting-started.adoc | 50 -- .../chedir-installation.adoc | 79 --- .../chedir-project-setup.adoc | 34 - .../che-6/portable-workspaces/chedir-ssh.adoc | 21 - .../chedir-up-and-down.adoc | 47 -- .../che-6/portable-workspaces/chefile.adoc | 174 ----- .../creating-factories.adoc | 178 ----- .../factories-getting-started.adoc | 71 -- .../che-6/portable-workspaces/factories.adoc | 35 - .../factories_json_reference.adoc | 297 -------- .../che-6/portable-workspaces/why-chedir.adoc | 16 - .../pages/che-6/setup-docker/docker-cli.adoc | 430 ------------ .../che-6/setup-docker/docker-config.adoc | 644 ------------------ .../che-6/setup-docker/docker-multi-user.adoc | 72 -- .../setup-docker/docker-single-user.adoc | 431 ------------ .../kubernetes-admin-guide.adoc | 18 - .../setup-kubernetes/kubernetes-config.adoc | 40 -- .../kubernetes-multi-user.adoc | 167 ----- .../kubernetes-or-openshift-admin-guide.adoc | 486 ------------- .../kubernetes-single-user.adoc | 118 ---- .../openshift-admin-guide.adoc | 88 --- .../setup-openshift/openshift-config.adoc | 243 ------- .../setup-openshift/openshift-multi-user.adoc | 72 -- .../openshift-single-user.adoc | 144 ---- .../using-ocp-to-deploy-che.adoc | 15 - .../pages/che-6/spi/spi-implementation.adoc | 366 ---------- src/main/pages/che-6/spi/spi_overview.adoc | 43 -- src/main/pages/che-6/tags/assembly.adoc | 12 - src/main/pages/che-6/tags/chedir.adoc | 12 - src/main/pages/che-6/tags/debugger.adoc | 12 - src/main/pages/che-6/tags/dev-docs.adoc | 12 - src/main/pages/che-6/tags/docker.adoc | 12 - src/main/pages/che-6/tags/extensions.adoc | 14 - src/main/pages/che-6/tags/factories.adoc | 12 - .../pages/che-6/tags/getting-started.adoc | 12 - src/main/pages/che-6/tags/installation.adoc | 12 - src/main/pages/che-6/tags/keycloak.adoc | 12 - src/main/pages/che-6/tags/kubernetes.adoc | 12 - src/main/pages/che-6/tags/ldap.adoc | 12 - src/main/pages/che-6/tags/networking.adoc | 12 - src/main/pages/che-6/tags/openshift.adoc | 12 - src/main/pages/che-6/tags/organizations.adoc | 12 - src/main/pages/che-6/tags/plugins.adoc | 12 - src/main/pages/che-6/tags/runtime.adoc | 12 - .../pages/che-6/tags/troubleshooting.adoc | 12 - src/main/pages/che-6/tags/workspace.adoc | 12 - .../che-6/user-guide/commands-ide-macro.adoc | 231 ------- .../creating-starting-workspaces.adoc | 116 ---- src/main/pages/che-6/user-guide/debug.adoc | 294 -------- .../user-guide/dependency-management.adoc | 27 - .../user-guide/editor_code_assistance.adoc | 92 --- .../pages/che-6/user-guide/ide-projects.adoc | 35 - .../che-6/user-guide/version-control.adoc | 332 --------- .../che-6/user-management/authentication.adoc | 219 ------ .../che-6/user-management/organizations.adoc | 203 ------ .../che-6/user-management/permissions.adoc | 273 -------- .../user-management/resource-management.adoc | 142 ---- .../user-management/user-management.adoc | 111 --- .../che-6/workspace-admin/env-variables.adoc | 27 - .../che-6/workspace-admin/environments.adoc | 10 - .../che-6/workspace-admin/installers.adoc | 80 --- .../pages/che-6/workspace-admin/projects.adoc | 91 --- .../pages/che-6/workspace-admin/recipes.adoc | 265 ------- .../che-6/workspace-admin/secure-servers.adoc | 48 -- .../pages/che-6/workspace-admin/servers.adoc | 110 --- .../pages/che-6/workspace-admin/stacks.adoc | 87 --- .../pages/che-6/workspace-admin/volumes.adoc | 60 -- .../workspace-admin/what-are-workspaces.adoc | 63 -- .../workspace-admin/workspace-data-model.adoc | 96 --- .../workspace-admin/workspace-rest-api.adoc | 10 - .../workspaces-troubleshooting.adoc | 69 -- .../assembly_introduction-to-eclipse-che.adoc | 4 +- 109 files changed, 7 insertions(+), 11883 deletions(-) delete mode 100644 src/main/_data/sidebars/che_6_docs.yml delete mode 100644 src/main/_data/sidebars/che_docs_home.yml delete mode 100644 src/main/index.adoc delete mode 100644 src/main/pages/che-6/dev_essentials/dto.adoc delete mode 100644 src/main/pages/che-6/dev_essentials/guice.adoc delete mode 100644 src/main/pages/che-6/dev_essentials/handling-projects-in-plugins.adoc delete mode 100644 src/main/pages/che-6/dev_essentials/json-rpc.adoc delete mode 100644 src/main/pages/che-6/developer-guide/actions.adoc delete mode 100644 src/main/pages/che-6/developer-guide/assemblies.adoc delete mode 100644 src/main/pages/che-6/developer-guide/build-reqs.adoc delete mode 100644 src/main/pages/che-6/developer-guide/che-in-che-quickstart.adoc delete mode 100644 src/main/pages/che-6/developer-guide/cors.adoc delete mode 100644 src/main/pages/che-6/developer-guide/custom-installers.adoc delete mode 100644 src/main/pages/che-6/developer-guide/dao.adoc delete mode 100644 src/main/pages/che-6/developer-guide/databases.adoc delete mode 100644 src/main/pages/che-6/developer-guide/editor.adoc delete mode 100644 src/main/pages/che-6/developer-guide/framework-overview.adoc delete mode 100644 src/main/pages/che-6/developer-guide/framework.adoc delete mode 100644 src/main/pages/che-6/developer-guide/ide-extensions-gwt.adoc delete mode 100644 src/main/pages/che-6/developer-guide/language-servers.adoc delete mode 100644 src/main/pages/che-6/developer-guide/logging.adoc delete mode 100644 src/main/pages/che-6/developer-guide/parts.adoc delete mode 100644 src/main/pages/che-6/developer-guide/project-types.adoc delete mode 100644 src/main/pages/che-6/developer-guide/properties.adoc delete mode 100644 src/main/pages/che-6/developer-guide/registry.adoc delete mode 100644 src/main/pages/che-6/developer-guide/rest-api.adoc delete mode 100644 src/main/pages/che-6/developer-guide/server-side-extensions.adoc delete mode 100644 src/main/pages/che-6/developer-guide/themes.adoc delete mode 100644 src/main/pages/che-6/developer-guide/workspace-agent.adoc delete mode 100644 src/main/pages/che-6/overview/infra-support.adoc delete mode 100644 src/main/pages/che-6/overview/introduction.adoc delete mode 100644 src/main/pages/che-6/overview/quick-start.adoc delete mode 100644 src/main/pages/che-6/overview/single-multi-user.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/chedir-getting-started.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/chedir-installation.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/chedir-project-setup.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/chedir-ssh.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/chedir-up-and-down.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/chefile.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/creating-factories.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/factories-getting-started.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/factories.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/factories_json_reference.adoc delete mode 100644 src/main/pages/che-6/portable-workspaces/why-chedir.adoc delete mode 100644 src/main/pages/che-6/setup-docker/docker-cli.adoc delete mode 100644 src/main/pages/che-6/setup-docker/docker-config.adoc delete mode 100644 src/main/pages/che-6/setup-docker/docker-multi-user.adoc delete mode 100644 src/main/pages/che-6/setup-docker/docker-single-user.adoc delete mode 100644 src/main/pages/che-6/setup-kubernetes/kubernetes-admin-guide.adoc delete mode 100644 src/main/pages/che-6/setup-kubernetes/kubernetes-config.adoc delete mode 100644 src/main/pages/che-6/setup-kubernetes/kubernetes-multi-user.adoc delete mode 100644 src/main/pages/che-6/setup-kubernetes/kubernetes-or-openshift-admin-guide.adoc delete mode 100644 src/main/pages/che-6/setup-kubernetes/kubernetes-single-user.adoc delete mode 100644 src/main/pages/che-6/setup-openshift/openshift-admin-guide.adoc delete mode 100644 src/main/pages/che-6/setup-openshift/openshift-config.adoc delete mode 100644 src/main/pages/che-6/setup-openshift/openshift-multi-user.adoc delete mode 100644 src/main/pages/che-6/setup-openshift/openshift-single-user.adoc delete mode 100644 src/main/pages/che-6/setup-openshift/using-ocp-to-deploy-che.adoc delete mode 100644 src/main/pages/che-6/spi/spi-implementation.adoc delete mode 100644 src/main/pages/che-6/spi/spi_overview.adoc delete mode 100644 src/main/pages/che-6/tags/assembly.adoc delete mode 100644 src/main/pages/che-6/tags/chedir.adoc delete mode 100644 src/main/pages/che-6/tags/debugger.adoc delete mode 100644 src/main/pages/che-6/tags/dev-docs.adoc delete mode 100644 src/main/pages/che-6/tags/docker.adoc delete mode 100644 src/main/pages/che-6/tags/extensions.adoc delete mode 100644 src/main/pages/che-6/tags/factories.adoc delete mode 100644 src/main/pages/che-6/tags/getting-started.adoc delete mode 100644 src/main/pages/che-6/tags/installation.adoc delete mode 100644 src/main/pages/che-6/tags/keycloak.adoc delete mode 100644 src/main/pages/che-6/tags/kubernetes.adoc delete mode 100644 src/main/pages/che-6/tags/ldap.adoc delete mode 100644 src/main/pages/che-6/tags/networking.adoc delete mode 100644 src/main/pages/che-6/tags/openshift.adoc delete mode 100644 src/main/pages/che-6/tags/organizations.adoc delete mode 100644 src/main/pages/che-6/tags/plugins.adoc delete mode 100644 src/main/pages/che-6/tags/runtime.adoc delete mode 100644 src/main/pages/che-6/tags/troubleshooting.adoc delete mode 100644 src/main/pages/che-6/tags/workspace.adoc delete mode 100644 src/main/pages/che-6/user-guide/commands-ide-macro.adoc delete mode 100644 src/main/pages/che-6/user-guide/creating-starting-workspaces.adoc delete mode 100644 src/main/pages/che-6/user-guide/debug.adoc delete mode 100644 src/main/pages/che-6/user-guide/dependency-management.adoc delete mode 100644 src/main/pages/che-6/user-guide/editor_code_assistance.adoc delete mode 100644 src/main/pages/che-6/user-guide/ide-projects.adoc delete mode 100644 src/main/pages/che-6/user-guide/version-control.adoc delete mode 100644 src/main/pages/che-6/user-management/authentication.adoc delete mode 100644 src/main/pages/che-6/user-management/organizations.adoc delete mode 100644 src/main/pages/che-6/user-management/permissions.adoc delete mode 100644 src/main/pages/che-6/user-management/resource-management.adoc delete mode 100644 src/main/pages/che-6/user-management/user-management.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/env-variables.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/environments.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/installers.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/projects.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/recipes.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/secure-servers.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/servers.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/stacks.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/volumes.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/what-are-workspaces.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/workspace-data-model.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/workspace-rest-api.adoc delete mode 100644 src/main/pages/che-6/workspace-admin/workspaces-troubleshooting.adoc diff --git a/src/main/404.adoc b/src/main/404.adoc index 045055b769..81b646e704 100644 --- a/src/main/404.adoc +++ b/src/main/404.adoc @@ -1,7 +1,6 @@ --- title: "Page Not Found" search: exclude -sidebar: mydoc_sidebar --- Apologies. The page you were trying to view does not exist. If you believe this is a mistake, please, file an link:https://github.com/eclipse/che/issues[issue]. diff --git a/src/main/_data/sidebars/che_6_docs.yml b/src/main/_data/sidebars/che_6_docs.yml deleted file mode 100644 index 3f0f836a25..0000000000 --- a/src/main/_data/sidebars/che_6_docs.yml +++ /dev/null @@ -1,296 +0,0 @@ -# This is your sidebar TOC. The sidebar code loops through sections here and provides the appropriate formatting. - -entries: -- title: Documentation Topics - product: Eclipse Che - version: 6 - folders: - - - title: - output: pdf - type: frontmatter - folderitems: - - title: - url: che-6/titlepage.html - output: pdf - type: frontmatter - - title: - url: che-6/tocpage.html - output: pdf - type: frontmatter - - - - title: Overview - output: web, pdf - folderitems: - - - title: Introduction - url: che-6/index.html - output: web, pdf - - title: Getting Started - url: che-6/quick-start.html - output: web, pdf - - title: Single and Multi-User Flavors - url: che-6/single-multi-user.html - output: web, pdf - - title: Supported Infrastructures - url: che-6/infra-support.html - output: web, pdf - - - title: Che on Docker - output: web, pdf - folderitems: - - title: Docker - Single User - url: che-6/docker-single-user.html - output: web, pdf - - title: Docker - Multi User - url: che-6/docker-multi-user.html - output: web, pdf - - title: Docker - Configuration - url: che-6/docker-config.html - output: web, pdf - - title: Docker - CLI Reference - url: che-6/docker-cli.html - output: web, pdf - - - title: Che on Kubernetes - output: web, pdf - folderitems: - - title: Kubernetes - Single User - url: che-6/kubernetes-single-user.html - output: web, pdf - - title: Kubernetes - Multi User - url: che-6/kubernetes-multi-user.html - output: web, pdf - - title: Kubernetes - Configuration - url: che-6/kubernetes-config.html - output: web, pdf - - title: Kubernetes - Admin Guide - url: che-6/kubernetes-admin-guide.html - output: web, pdf - - - title: Che on OpenShift - output: web, pdf - folderitems: - - title: OpenShift - Single User - url: che-6/openshift-single-user.html - output: web, pdf - - title: OpenShift - Multi User - url: che-6/openshift-multi-user.html - output: web, pdf - - title: OpenShift - Configuration - url: che-6/openshift-config.html - output: web, pdf - - title: OpenShift - Admin Guide - url: che-6/openshift-admin-guide.html - output: web, pdf - - - title: User Management - output: web, pdf - folderitems: - - title: Authentication and Authorization - url: che-6/user-management.html - output: web, pdf - - title: Security Model - url: che-6/authentication.html - output: web, pdf - - title: Permissions - url: che-6/permissions.html - output: web, pdf - - title: Organizations in UD - url: che-6/organizations.html - output: web, pdf - - title: Resource Management - url: che-6/resource-management.html - output: web, pdf - - - title: User Guides - output: web, pdf - folderitems: - - title: Creating and starting Workspaces - url: che-6/creating-starting-workspaces.html - output: web, pdf - - title: Projects - url: che-6/ide-projects.html - output: web, pdf - - title: Editor and Code-Assistance - url: che-6/editor-code-assistance.html - output: web, pdf - - title: Dependency Management - url: che-6/dependency-management.html - output: web, pdf - - title: Commands and IDE Macros - url: che-6/commands-ide-macro.html - output: web, pdf - - title: Version Control - url: che-6/version-control.html - output: web, pdf - - title: Debug - url: che-6/debug.html - output: web, pdf - -# Workspaces, data model, creating workspaces and troubleshooting - - - title: Workspace Administration - output: web, pdf - folderitems: - - title: Workspace Overview - url: che-6/what-are-workspaces.html - output: web, pdf - - title: Workspace - Stacks - url: che-6/stacks.html - output: web, pdf - - title: Workspace - Recipes - url: che-6/recipes.html - output: web, pdf - - title: Workspace - Servers - url: che-6/servers.html - output: web, pdf - - title: Workspace - Installers - url: che-6/installers.html - output: web, pdf - - title: Workspace - Volumes Mount - url: che-6/volumes.html - output: web, pdf - - title: Workspace - Environment Variables - url: che-6/env-variables.html - output: web, pdf - - title: Workspace - Projects - url: che-6/projects.html - output: web, pdf - - title: Workspace - Troubleshooting - url: che-6/workspaces-troubleshooting.html - output: web, pdf - - title: Workspace Data Model - url: che-6/workspace-data-model.html - output: web, pdf - - - title: Portable Workspaces - output: web, pdf - folderitems: - - title: Chedir - Getting Started - url: che-6/chedir-getting-started.html - output: web, pdf - - title: Chedir - Why Chedir? - url: che-6/why-chedir.html - output: web, pdf - - title: Chedir - Installation - url: che-6/chedir-installation.html - output: web, pdf - - title: Chedir - Project Setup - url: che-6/chedir-project-setup.html - output: web, pdf - - title: Chedir - Up and Down - url: che-6/chedir-up-and-down.html - output: web, pdf - - title: Chedir - Chefile - url: che-6/chefile.html - output: web, pdf - - title: Chedir - SSH - url: che-6/chedir-ssh.html - output: web, pdf - - title: Factory - Getting Started - url: che-6/factories-getting-started.html - output: web, pdf - - title: Factory - Creating - url: che-6/creating-factories.html - output: web, pdf - - title: Factory - JSON Reference - url: che-6/factories_json_reference.html - output: web, pdf - - - title: Developer Guides - output: web - folderitems: - - title: Overview - url: che-6/framework-overview.html - output: web, pdf - - title: SDK - REST API - url: che-6/rest-api.html - output: web, pdf - - title: SDK - Your First Plugin - url: che-6/che-in-che-quickstart.html - output: web, pdf - - title: SDK - Building Che - url: che-6/build-reqs.html - output: web, pdf - - title: SDK - Assemblies - url: che-6/assemblies.html - output: web, pdf - - title: SDK - Logging - url: che-6/logging.html - output: web, pdf - - title: SDK - GWT IDE Extensions - url: che-6/ide-extensions-gwt.html - output: web - - title: SDK - Server Side Extensions - url: che-6/server-side-extensions.html - output: web - - title: SDK - Installers - url: che-6/custom-installers.html - output: web - - title: SDK - Project Types - url: che-6/project-types.html - output: web - - title: SDK - Language Support - url: che-6/language-servers.html - output: web - - title: IDE UI: Parts - url: che-6/parts.html - output: web - - title: IDE UI: Actions - url: che-6/actions.html - output: web - # - title: IDE UI: Editor - # url: che-6/editor.html - # output: web - # - title: IDE UI: Themes - # url: che-6/themes.html - # output: web - - - title: Dev Essentials - output: web - folderitems: - - title: Dependency Injection - url: che-6/guice.html - output: web - - title: Transport: DTO - url: che-6/dto.html - output: web - - title: Communication: JSON-RPC - url: che-6/json-rpc.html - output: web - - title: Handling Projects in Plugins - url: che-6/handling-projects-in-plugins.html - output: web - - title: Persistence, DAO - url: che-6/dao.html - output: web, pdf - - title: Properties - url: che-6/properties.html - output: web, pdf - - title: Infrastructure and SPI - output: web - folderitems: - - title: Overview - url: che-6/spi_overview.html - output: web - - title: Implementation Notes - url: che-6/spi-implementation.html - output: web - -# - title: Plugin Authoring -# output: web -# folderitems: -# - title: Overview And Quick Start -# url: che-6/developer.html -# output: web -# - title: Assemblies -# url: che-6/che-assemblies.html -# output: web -# - title: Modules -# url: che-6/che-modules.html -# output: web -# - title: REST APIs -# url: che-6/rest-apis.html -# output: web diff --git a/src/main/_data/sidebars/che_7_docs.yml b/src/main/_data/sidebars/che_7_docs.yml index 9c728ee6e6..412e7c25e7 100644 --- a/src/main/_data/sidebars/che_7_docs.yml +++ b/src/main/_data/sidebars/che_7_docs.yml @@ -2,8 +2,8 @@ entries: - title: Overview - product: Eclipse Che - version: 7 + #product: Eclipse Che + #version: 7 folders: - title: Introduction to Che url: che-7/introduction-to-eclipse-che diff --git a/src/main/_data/sidebars/che_docs_home.yml b/src/main/_data/sidebars/che_docs_home.yml deleted file mode 100644 index f96f789adb..0000000000 --- a/src/main/_data/sidebars/che_docs_home.yml +++ /dev/null @@ -1,19 +0,0 @@ -entries: -- title: Eclipse Che versions - product: - version: - folders: - - - title: Che 6 documentation - output: web - folderitems: - - title: Overview - url: che-6 - output: web - - - title: Che 7 documentation - output: web - folderitems: - - title: Overview - url: che-7 - output: web diff --git a/src/main/_data/topnav.yml b/src/main/_data/topnav.yml index 51af735b68..837cfacc1d 100644 --- a/src/main/_data/topnav.yml +++ b/src/main/_data/topnav.yml @@ -12,12 +12,6 @@ topnav: topnav_dropdowns: - title: Topnav dropdowns folders: - - title: Che Version - folderitems: - - title: Che 6 - url: che-6 - - title: Che 7 - url: che-7 - title: Get Support folderitems: - title: Known Bugs diff --git a/src/main/_includes/sidebar.html b/src/main/_includes/sidebar.html index 049ae4754f..15da2c6fb0 100644 --- a/src/main/_includes/sidebar.html +++ b/src/main/_includes/sidebar.html @@ -52,9 +52,9 @@ {% endfor %} {% endfor %} -

+ diff --git a/src/main/index.adoc b/src/main/index.adoc deleted file mode 100644 index 667634477e..0000000000 --- a/src/main/index.adoc +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Eclipse Che Documentation -keywords: landing, index, introduction, overview, home -sidebar: che_docs_home -#sidebar: none -toc: false -permalink: index.html -folder: -summary: Eclipse Che is a developer workspace server and cloud IDE ---- - -[id="documentation-versions"] -== Documentation versions - -* link:{{site.baseurl}}che-6[Che 6 documentation] -* link:{{site.baseurl}}che-7[Che 7 documentation] diff --git a/src/main/pages/che-6/dev_essentials/dto.adoc b/src/main/pages/che-6/dev_essentials/dto.adoc deleted file mode 100644 index 9217e3411a..0000000000 --- a/src/main/pages/che-6/dev_essentials/dto.adoc +++ /dev/null @@ -1,446 +0,0 @@ ---- -title: "DTO" -keywords: framework, plugin, extension, dto -tags: [extensions, dev-docs] -sidebar: che_6_docs -permalink: che-6/dto.html -redirect_from: dto.html -folder: che-6/dev_essentials ---- - - -A data transfer object (DTO) is an object to exchange data with the client and server. DTOs are responsible for serializing (and deserializing) themselves into JSON. You can prepare custom DTOs for your extensions and plugins. You define a DTO interface and then our DTO utilities will generate implementations that can be included in your extension. - -[id="interfaces"] -== Interfaces - -Every DTO requires interfaces that must contain get-methods. Mark these interfaces with the `org.eclipse.che.dto.shared.DTO` annotation. Possible names for getter-methods are: - ----- -get... -is... ----- - -For example: - -[source,java] ----- -package com.codenvy.test.dto; - -import org.eclipse.che.dto.shared.DTO; - -@DTO -public interface Item { - String getStatus(); - void setStatus(String status); - boolean isHidden(); - void setHidden(boolean hidden); -} ----- - -[id="pom"] -== POM - -Update the `` section of a `pom.xml` to include the DTO. - -1. `maven-compiler-plugin` - helps to run compilation of project in two steps. -2. `che-core-api-dto-maven-plugin` - generates DTO implementations. -3. `build-helper-maven-plugin` - adds generated files to project’s sources. - -`che-core-api-dto-maven-plugin` has the following configuration parameters (all required): - -`dtoPackages`: names of packages which contains DTO interfaces. - -`outputDirectory`: name of directory to store generated files. Usually just set one property, e.g. `dto-generator-out-directory` and reuse it in configurations of plugins. - -`genClassName`: sets the name of an enclosing class where generated classes are placed. - -`impl`: either `server` or `client` to define which kind of DTO to generate. - -`dependencies` - each maven plugin has its own classloader. Plugin cannot see dependencies or build output of current project. So it’s necessary to add current project as dependency for `che-core-api-dto-maven-plugin`. If DTOs from current project use DTOs from another project, then need add dependency to that project too. - -The following `pom.xml` snippet demonstrates how you can generate server-side DTOs: - ----- -... - - ${project.build.directory}/generated-sources/dto/ - -... - - - - maven-compiler-plugin - - - pre-compile - generate-sources - - compile - - - - - - org.eclipse.che.core - che-core-api-dto-maven-plugin - ${che.core.version} - - - process-sources - - generate - - - - - - com.codenvy.test.dto - - ${dto-generator-out-directory} - com.codenvy.test.server.dto.DtoServerImpls - server - - - - ${project.groupId} - ${project.artifactId} - ${project.version} - - - - - - org.codehaus.mojo - build-helper-maven-plugin - - - add-resource - process-sources - - add-resource - - - - - ${dto-generator-out-directory}/META-INF - META-INF - - - - - - add-source - process-sources - - add-source - - - - ${dto-generator-out-directory} - - - - - - - -... ----- - -The following `pom.xml` snippet demonstrates how you can generate both types of DTOs (client and server): - ----- -... - - ${project.build.directory}/generated-sources/dto/ - -... - - - - maven-compiler-plugin - - - pre-compile - generate-sources - - compile - - - - - - org.eclipse.che.core - che-core-api-dto-maven-plugin - ${che.core.version} - - - process-sources - - generate - - - - com.codenvy.test.dto - - ${dto-generator-out-directory} - com.codenvy.test.client.dto.DtoClientImpls - client - - - - process-sources - - generate - - - - com.codenvy.test.dto - - ${dto-generator-out-directory} - com.codenvy.test.server.dto.DtoServerImpls - server - - - - - - ${project.groupId} - ${project.artifactId} - ${project.version} - - - - - - org.codehaus.mojo - build-helper-maven-plugin - - - add-resource - process-sources - - add-resource - - - - - ${dto-generator-out-directory}/META-INF - META-INF - - - - - - add-source - process-sources - - add-source - - - - ${dto-generator-out-directory} - - - - - - - - ... - - ${generated.sources.directory} - - - -... ----- - -Make sure that the directory with generated client-side DTOs is included in classpath resources. - -[id="generate"] -== Generate - -In order to generate DTOs, you build your project with maven: - ----- -mvn clean install ----- - -[id="use-server-side"] -== Use: Server-Side - -[source,java] ----- -// server-side DTO -import org.eclipse.che.dto.server.DtoFactory; -... - -// create instance and set fields -MyJob job = DtoFactory.getInstance().createDto(MyJob.class); -job.setStatus("success"); -job.setExitCode(0); - -// serialize to JSON -String json = DtoFactory.getInstance().toJson(job); - -// deserialize from JSON -MyJob job2 = DtoFactory.getInstance().createDtoFromJson(json, MyJob.class); ----- - -You can also use the static method `DtoFactory.newDto(MyJob.class)` that is a shortcut for `DtoFactory.getInstance().createDto(MyJob.class)`. See: https://github.com/eclipse/che/blob/master/core/che-core-api-dto/src/main/java/org/eclipse/che/dto/server/DtoFactory.java[DtoFactory] for server side. - -[id="use-client-side"] -== Use: Client-Side - -[source,java] ----- -// client-side DTO -import org.eclipse.che.ide.dto.DtoFactory; -@Singleton -public class MyPresenter { - @Inject - public MyPresenter(DtoFactory dtoFactory) { - // create instance and set fields - MyJob job = dtoFactory.createDto(MyJob.class); - job.setStatus("success"); - job.setExitCode(0); - - // serialize to JSON - String json = dtoFactory.toJson(job); - - // deserialize from JSON - MyJob job2 = dtoFactory.createDtoFromJson(json, MyJob.class); - } -} ----- - -See: client side https://github.com/eclipse/che/blob/master/ide/commons-gwt/src/main/java/org/eclipse/che/ide/dto/DtoFactory.java[DtoFactory]. - -[id="method-chaining"] -== Method Chaining - -In addition to the standard getter and setter methods, our generator also adds a method `withXXX(T value)`. This is seimilar to a setter method, but also returns `this`. You can use this to do chaining. Instead of: - -[source,java] ----- -MyJob job = DtoFactory.getInstance().createDto(MyJob.class); -job.setStatus("success"); -job.setExitCode(0); ----- - -use: - -[source,java] ----- -MyJob job = -DtoFactory.getInstance().createDto(MyJob.class).withStatus("success").withExitCode(0); ----- - -Generator always add such methods in generated implementation for your DTO interfaces, but you still should add them to you interfaces so that they are externally accessible: - -[source,java] ----- -package com.codenvy.test.dto; -import org.eclipse.che.dto.shared.DTO; -@DTO -public interface MyJob { - String getStatus(); - void setStatus(String status); - int getExitCode(); - void setExitCode(int code); - String getError(); - void setError(String error); - // for chaining - MyJob withStatus(String status); - MyJob withExitCode(int code); - MyJob withError(String error); -} ----- - -[id="delegate-dto-methods"] -== Delegate DTO Methods - -In some case we may need more then just getters and setters in DTO, but there is no common mechanism to generate such implementation for DTO interface. In this case `org.eclipse.che.dto.shared.DelegateTo` annotation may help. DTO interface bellow contains getters, setters and with methods and one more complex method for getting full name of user. - -[source,java] ----- -@DTO -public interface User { - String getFirstName(); - void setFirstName(String firstName); - User withFirstName(String firstName); - String getLastName(); - void setLastName(String lastName); - User withLastName(String lastName); - @DelegateTo(client = @DelegateRule(type = Util.class, method = "fullName"), - server = @DelegateRule(type = Util.class, method = "fullName")) - String getFullName(); -} ----- - -For method `getFullName` add annotation `DelegateTo`. Annotations may contains different delegate rules for client and server code. - -`DelegateTo` annotation: - -[cols=",",options="header",] -|=== -|Parameter |Description -|`client` |Rules for client code generator -|`server` |Rules for server code generator -|=== - -`DelegateRule` annotation - -[cols=",",options="header",] -|=== -|Parameter |Description -|`type` |Class that contains method to delegate method call -|`method` |Name of method -|=== - -[source,java] ----- -public class Util { - public static String fullName(User user) { - return user.getFirstName() + " " + user.getLastName(); - } -} ----- - -Fragment of generated code for method `getFullName()`: - -[source,java] ----- -public String getFullName() { - return Util.fullName(this); -} ----- - -Requirements for methods to delegate DTO methods calls: - -1. Method must be public and static. -2. Method must accept DTO interface as first parameter, if DTO method contains other parameters then the delegate method must accept the whole set of DTO method parameters starting from the second position. - -For example: - -[source,java] ----- -@DelegateTo(client = @DelegateRule(type = Util.class, method = "fullName"), - server = @DelegateRule(type = Util.class, method = "fullName")) -String getFullNameWithPrefix(String prefix); ----- - -Delegate method: - -[source,java] ----- -public static String fullName(User user, String prefix) { - return prefix + " " + user.getFirstName() + " " + user.getLastName(); -} ----- diff --git a/src/main/pages/che-6/dev_essentials/guice.adoc b/src/main/pages/che-6/dev_essentials/guice.adoc deleted file mode 100644 index b7fe6f82a1..0000000000 --- a/src/main/pages/che-6/dev_essentials/guice.adoc +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: "Dependency Injection" -keywords: framework, plugin, extension, DI, dependency injection -tags: [extensions, dev-docs] -sidebar: che_6_docs -permalink: che-6/guice.html -redirect_from: guice.html -folder: che-6/dev_essentials ---- - - -In this section, we briefly introduce the usage of dependency injection in Che, on the client and on the server side. If you are already familiar with Guice and Gin, you might want to skip this part. - -Che uses dependency injection to wire the different components, in order to create objects as well as register and retrieve extensions. Therefore, dependency injection is technically the core mechanism of communicating with the framework and connecting custom extensions. This includes accessing framework services and objects (e.g. a file type or a link:%7B%7B%20base%20%7D%7D%7B%7Bsite.links%5B%22assemblies-sdk-code-editors%22%5D%7D%7D[file type registry]) and providing custom objects to the framework. - -Che uses the existing dependency injection framework https://github.com/google/guice[Guice] on the server-side and the GWT version of Guice, https://github.com/google-code-export/google-gin[Gin], on the client-side. - -In general, there are two use cases for dependency injection: consuming objects and providing objects. - -image::devel/di.png[] - -Please note that when extending Che, DI consumer and provider can be either in your custom extension or within the Che framework. As an example, if you want to provide a new wizard to be used in the IDE, you will create an object provider, which provides the wizard. Che implements an object consumer, which picks up the wizard class and uses it. In turn, if you want to access a service provided by Che, your extension will be the object consumer. - -The main goal of using dependency injection is to decouple object provider and object consumer. Both parties just need to know about the object they consume/provide. The object is identified by its type (typically a Java interface) and optionally an additional key. In the following, we first describe how to consume objects (in Guice and Gin) and subsequently, how to provide objects. - -[id="consuming-objects"] -== Consuming Objects - -Required objects can be injected in any class that is instantiated by the framework. If a custom component requires objects, e.g. a service, it can be injected as a parameter. This can be done in the constructor or in methods of a class. If the parameter is required for a class to operate, we recommend using the constructor for injection. To get parameters injected in a method or constructor, it is marked with the annotation `@Inject` (see code example below). By adding the annotation, all parameters of a constructor/method will be resolved by the framework and passed in through the initialization of the class. - -The dependency injection framework needs to know how to identify the correct object to be used as a parameter. There are two essential ways of specifying the parameters as a consumer * First, if you just specify a parameter of a certain type (in the example `SomeService`), the framework will search for an object of that type. This will only work, if there is exactly one object of this type in the context, which is typically true for services. - -* Second, if there can be several objects of the required type and you want a specific object out of those, you can additionally specify a key using the annotation `@Named`. - -In the following example, for the second parameter, the framework will look for an object which is of type `MyClass` has been explicitly registered with the key `MyID`. Please link:#providing-objects[see the following] section how to provide objects to be consumed that way. - -[source,java] ----- -public class MyClass { - - private MyOtherClass myOtherClass; - - @Inject - public MyClass(final SomeService someService, - final @Named("MyID") MyClass myClass) { - someService.someMethod(myClass); - this.other = new MyOtherClass(myClass); - } - - // do somehting with myOtherClass; -} ----- - -Please note, that dependency injection is only available for objects which are instantiated by the dependency injection framework. In the example above, the class `MyOtherClass` is instantiated using plain Java, therefore it is not possible to use `@Inject` in its constructor. - -[id="providing-objects"] -== Providing Objects - -Implementing an object provider serves two purposes when writing an extension: * First, you can consume the objects that you provide from within other custom classes. - -* Second, the provided classes can be consumed by the Che framework. - -As an example, if you provide a wizard class, it will be integrated by the Che IDE. Therefore, dependency injection is a core extension mechanism of Che. - -To provide custom objects, you implement a module class. It is responsible to create the objects to be injected as well as register them using the type and optionally a key. Depending on the general structure of your extension, you could add as many modules as you like, however, most extensions use only one module for the client (Gin) and one for the server part (Guice). - -The following code example shows a simple Guice module. All Guice modules inherit from AbstractModule and are marked with the annotation `@DynaModule`, which registers the module itself to be executed by Guice. The mandatory method `#configure` is responsible for the registration of objects. We will not go into detail about all the different options of Guice/Gin, but focus on relevant use cases in Che. In the following code example, we register a custom object (`CustomObject`), which implements an existing Che type (`ExistingCheType`). The Che type defines an extension point for Che, e.g. a wizard. - -[source,java] ----- -public class CustomObject implements ExistingCheType { - // ... -} ----- - -Now, we register our custom object using the type and therefore make it available for the Che framework. To register and to retrieve the object, the type `ExistingCheType` is used as an identifier. In the example, there can be an arbitrary number of objects implementing `ExistingCheType`, so Che will retrieve a set of objects. To register the object, we create a new `Set Binder` for the type `ExistingCheType`. Then, we add a binding and register the custom object. The `CustomObject` will be instantiated by the framework using dependency injection. Therefore, the `@Inject` annotation can be used in the constructor of `CustomObject`. - -[source,java] ----- -import org.eclipse.che.inject.DynaModule; -import com.google.inject.AbstractModule; -import com.google.inject.multibindings.Multibinder; - -@DynaModule -public class MyGuiceModule extends AbstractModule { - - @Override - protected void configure() { - Multibinder.newSetBinder(binder(), ExistingCheType.class) - .addBinding() - .to(CustomObject.class); - } -} ----- - -Gin modules inherit from `AbstractGinModule` and use the `@ExtensionGinModule` annotation. Gin has a different https://code.google.com/p/google-gin/wiki/GinTutorial[binding mechanism than Guice], however, for the typical use case, the code would look the same: - -[source,java] ----- -import org.eclipse.che.ide.api.extension.ExtensionGinModule; -import com.google.gwt.inject.client.AbstractGinModule; -import com.google.gwt.inject.client.multibindings.GinMultibinder; - -@ExtensionGinModule -public class MyGinModule extends AbstractGinModule { - - @Override - protected void configure() { - GinMultibinder.newSetBinder(binder(), ExistingCheType.class) - .addBinding() - .to(CustomObject.class); - } -} ----- - -As an alternative to the registration above, objects can also be registered using methods marked with the `@Provides` annotation. The following example provides a simple object, which only needs to be instantiated once (`@Singleton`). In this example, the registration additionally contains a key specified by the `@Named` annotation. Please note that in this case, the `CustomObject` is created manually, so no dependency injection can be used within it. The following method is placed in your custom Gin/Guice module. - -[source,java] ----- -@Provides -@Singleton -@Named("MyID") -protected FileType provideMyClass() { - return new MyClass(); -} ----- - -The examples of dependency injection cover all basic use cases to understand the following extension tutorial. If you want to learn more about the different types of Guice bindings, please refer https://github.com/google/guice/wiki/Bindings[to this page]. - -[id="extension-classes"] -== Extension Classes - -Besides the extensibility using dependency injections, many custom extensions need to call some Che services or registries on start-up. Therefore, most extensions contain a central class called `Extension`. To register those classes, Che provides the custom annotation `@Extension`, which also allows to define a title for the extension. A common example for a class which gets instantiated by Che and which requires parameters is the `Extension` class. - -Extension classes will automatically be picked-up by Che on start-up and all methods will be executed using dependency injection. In the following example, the extension class connects `SomeParameter` to `SomeService`. - -[source,java] ----- -@Extension(title = "My Extension") -public class MyExtension { - - @Inject - private void myInitialization( - final SomeService someService, - final SomeParameter someParameter) { - someService.doSth(someParameter); - } -} ----- diff --git a/src/main/pages/che-6/dev_essentials/handling-projects-in-plugins.adoc b/src/main/pages/che-6/dev_essentials/handling-projects-in-plugins.adoc deleted file mode 100644 index 7676167d42..0000000000 --- a/src/main/pages/che-6/dev_essentials/handling-projects-in-plugins.adoc +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: "Handling Projects in Server and Client Side Plugins" -keywords: framework, plugin, extension, project import, file system -tags: [extensions, dev-docs] -sidebar: che_6_docs -permalink: che-6/handling-projects-in-plugins.html -redirect_from: handling-projects-in-plugins.html -folder: che-6/dev_essentials ---- - - -[id="overview"] -== Overview - -In Che there is a bunch of project operations that can be performed via REST, JSON-RPC or programmatically (on server side). Most valuable will be covered by this chapter. - -[id="project-import"] -== Project import - -In is possible to import a project using several ways, Che supports project import via REST, JSON-RPC and ProjectManager, those will be described further with examples. - -[id="using-rest-to-import-a-project"] -=== Using REST to import a project - -Most popular way of project import for clients is using corresponding REST service https://github.com/eclipse/che/blob/master/wsagent/che-core-api-project/src/main/java/org/eclipse/che/api/project/server/ProjectService.java[`org.eclipse.che.api.project.server.ProjectService`]. It has quite extensive API, so please check the service to have complete understanding of it’s capabilities. In Eclipse Che IDE there is already implemented https://github.com/eclipse/che/blob/master/ide/che-core-ide-app/src/main/java/org/eclipse/che/ide/project/ProjectServiceClient.java[`org.eclipse.che.ide.project.ProjectServiceClient`] that we can use in order to communicate with project service. Most basic use case is: - -[source,java] ----- -Path path = Path.valueOf("/DemoProject"); - -String location = "location"; -String storage = "git"; -Map parameters = new HashMap() { - { - put("branch", "master"); - put("commitId", "123456"); - put("keepVcs", "true"); - put("fetch", "12345"); - put("keepDir", "/src"); - } - } - -SourceStorageDto sourceStorage = dtoFactory.createDto(SourceStorageDto.class); -sourceStorage.setLocation(location); -sourceStorage.setStorage(git); -sourceStorage.setParameters(); - -projectServiceClient.importProject(path, sourceStorage) - .then((ignored)->{}); ----- - -Where: - -*`path`* - project path in workspace file system - -*`sourceStorage`* - source storage metadata container - -*`location`* - project location in a storage (can be URL, or any other storage dependent location descriptor) - -*`storage`* - storage identifier, in our example it is "git" - -*`parameters`* - storage related parameters - -Example can be found https://github.com/eclipse/che/blob/master/ide/che-core-ide-app/src/main/java/org/eclipse/che/ide/resources/impl/ResourceManager.java#L497[here] - -[id="using-json-rpc-to-import-a-project"] -=== Using JSON-RPC to import a project - -Another approach is to use JSON-RPC calls instead of REST, that may be more convenient for JSON-RPC based clients. JSON-RPC service is represented by a range of JSON-RPC method handlers that are all configured within https://github.com/eclipse/che/blob/master/wsagent/che-core-api-project/src/main/java/org/eclipse/che/api/project/server/ProjectJsonRpcServiceConfigurator.java[`org.eclipse.che.api.project.server.ProjectJsonRpcServiceConfigurator`] class and utilize JSON-RPC protocol Eclipse Che implementation. In order to import a project we must call `"project/import"` method, that has https://github.com/eclipse/che/blob/master/wsagent/che-core-api-project-shared/src/main/java/org/eclipse/che/api/project/shared/dto/service/ImportRequestDto.java[`org.eclipse.che.api.project.shared.dto.service.ImportRequestDto`] as request params and https://github.com/eclipse/che/blob/master/wsagent/che-core-api-project-shared/src/main/java/org/eclipse/che/api/project/shared/dto/service/ImportResponseDto.java[`org.eclipse.che.api.project.shared.dto.service.ImportResponseDto`] as a result. Inside those DTOs you will need to configure https://github.com/eclipse/che/blob/master/core/che-core-api-model/src/main/java/org/eclipse/che/api/core/model/workspace/config/SourceStorage.java[`org.eclipse.che.api.core.model.workspace.config.SourceStorage`] in order to start import procedure and will receive https://github.com/eclipse/che/blob/master/core/che-core-api-model/src/main/java/org/eclipse/che/api/core/model/workspace/config/ProjectConfig.java[`org.eclipse.che.api.core.model.workspace.config.ProjectConfig`] after import is finished. Most basic example is: - -[source,java] ----- - -String projectWsPath = "/DemoProject" - -String method = "project/import"; -String endpointId = "ws-agent"; - -String location = "location"; -String storage = "git"; -Map parameters = new HashMap() { - { - put("branch", "master"); - put("commitId", "123456"); - put("keepVcs", "true"); - put("fetch", "12345"); - put("keepDir", "/src"); - } - } - -SourceStorageDto sourceStorage = dtoFactory.createDto(SourceStorageDto.class); -sourceStorage.setLocation(location); -sourceStorage.setStorage(git); -sourceStorage.setParameters(); - - -ImportRequestDto params = dtoFactory.createDto(ImportRequestDto.class); -params.setWsPath(projectWsPath); -params.setSourceStorage(sourceStorage); - -Class resultClass = ImportResponseDto.class; - - requestTransmitter - .newRequest() - .endpointId(endpointId) - .methodName(method) - .paramsAsDto(params) - .sendAndReceiveResultAsDto(resultClass) - .onSuccess((importResponse) -> {}) - .onFailure((jsonRpcError) -> {}); ----- - -Where: - -*`method`* - JSON-RPC compliant method name that we want to call on server side, in our case it is `"project/import"` - -*`endpointId`* - identifier of endpoint where we want to call our method, in our case it is `"ws-agent"` - -*`projectWsPath`* - project path in workspace file system - -*`resultClass`* - class of resulting dto - -*`importResponse`* - import response DTO that contains business logic objects, in our case it contains imported project configuration - -[id="using-projectmanager-to-import-a-project"] -=== Using ProjectManager to import a project - -On server side we can use https://github.com/eclipse/che/blob/master/wsagent/che-core-api-project/src/main/java/org/eclipse/che/api/project/server/ProjectManager.java[`org.eclipse.che.api.project.server.ProjectManager`] in order to perform project import operations. Most basic use case: - -[source,java] ----- -BiConsumer consumer = (s1, s2) -> {}; - -boolean rewrite = false; - -String projectWsPath = "/DemoProject" - -String location = "location"; -String storage = "git"; -Map parameters = new HashMap() { - { - put("branch", "master"); - put("commitId", "123456"); - put("keepVcs", "true"); - put("fetch", "12345"); - put("keepDir", "/src"); - } - } - -SourceStorageDto sourceStorage = DtoFactory.newInstance().createDto(SourceStorageDto.class); -sourceStorage.setLocation(location); -sourceStorage.setStorage(git); -sourceStorage.setParameters(); - -projectManager.doImport(projectWsPath, sourceStorage, rewrite, consumer); ----- - -Where: - -*`consumer`* - binary consumer that may accept project import progression reports as string lines and pass it further, e.g. it is used to track project import progression on clients - -*`rewrite`* - boolean parameter to indicate if an old project can be rewritten by new one during import - -Example can be found https://github.com/eclipse/che/blob/master/wsagent/che-core-api-project/src/main/java/org/eclipse/che/api/project/server/impl/SynchronizingProjectManager.java#L227[here] diff --git a/src/main/pages/che-6/dev_essentials/json-rpc.adoc b/src/main/pages/che-6/dev_essentials/json-rpc.adoc deleted file mode 100644 index d21b33fb17..0000000000 --- a/src/main/pages/che-6/dev_essentials/json-rpc.adoc +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "Communication: JSON-RPC" -keywords: framework, plugin, extension, json rpc, communication, events, subscribe -tags: [extensions, dev-docs] -sidebar: che_6_docs -permalink: che-6/json-rpc.html -redirect_from: json-rpc.html -folder: che-6/dev_essentials ---- - - -[id="overview"] -== Overview - -In CHE we use http://www.jsonrpc.org/specification[JSON-RPC] for asynchronous communication between clients and servers. JSON-RPC is asymmetric by nature so in order to be able to information independently we use duplex approach where both sides (clients and servers) can act both as a JSON-RPC server and as JSON-RPC client. To make it clear, clients (e.g. IDE) can send JSON-RPC requests (acting as JSON-RPC client) and receive requests (acting as JSON-RPC server) and servers (e.g. workspace master or workspace agent) can do the same. - -[id="send-a-json-rpc-request"] -== Send a JSON-RPC request - -To send request you can use https://github.com/eclipse/che/blob/master/core/che-core-api-core/src/main/java/org/eclipse/che/api/core/jsonrpc/commons/RequestTransmitter.java[`org.eclipse.che.api.core.jsonrpc.commons.RequestTransmitter`], the most basic use case (actual for both client and server sides) looks quite simple: - -[source,java] ----- -transmitter - .newRequest() - .endpointId(endpointId) - .methodName(method) - .paramsAsDto(dto) - .sendAndReceiveResultAsDto(dtoClass) - .onSuccess((result) -> {}) - .onFailure((jsonRpcError) -> {}); ----- - -*endpointId* - in common sense can be an arbitrary *`String`* identifier that allows to distinguish endpoints. Please note that for server sides these endpoints are statically defined as constants: `"ws-agent"` for workspace agent and `"ws-master"` for workspace master for example, while for clients it is a dynamic identifier because clients are dynamic by their nature. - -*method* - method name corresponds to it’s definition in JSON-RPC protocol specification. In Che we use the following naming convention: method name in most cases consists of two parts separated be slash - scope and action. For example `project/create` where `project` is the scope and `create` is the action. - -*dto* - value of parameters passed (in our example it is a https://en.wikipedia.org/wiki/Data_transfer_object[DTO]), please note that though JSON-RPC protocol specification requires parameters either as json objects or arrays, you can use single primitives here as well and they will be automatically converted to a singleton array. - -*dtoClass* - class of a result that will be contained within the response to our request - -*result* - result of our request (in our example it is of class *dtoClass*) - -*jsonRpcError* - error object that contains information about the error if any happened, its structure corresponds to error defined in JSON-RPC protocol specification - -Source code example of using of the transmitter can be found here: https://github.com/eclipse/che/blob/master/wsagent/che-core-api-debug/src/main/java/org/eclipse/che/api/debugger/server/DebuggerJsonRpcMessenger.java#L76 - -[id="receive-a-json-rpc-request"] -== Receive a JSON-RPC request - -To receive a request you can use https://github.com/eclipse/che/blob/master/core/che-core-api-core/src/main/java/org/eclipse/che/api/core/jsonrpc/commons/RequestHandlerConfigurator.java[`org.eclipse.che.api.core.jsonrpc.commons.RequestHandlerConfigurator`], the use case (actual for both sides): - -[source,java] ----- -configurator - .newConfiguration() - .methodName(method) - .paramsAsDto(paramsDtoClass) - .resultAsDto(resultDtoClass) - .withFunction((endpointId, paramsDto) -> resultDto); ----- - -*method* - the name of JSON-RPC method that is to be handled by this configuration - -*paramsDtoClass* - class of parameters that are passed in a JSON-RPC request (in our example it is a DTO) - -*resultDtoClass* - class of result that is passed in a JSON-RPC response (in our example it is DTO) - -*endpointId* - the identifier of an endpoint that sends the request that is handled by this configuration - -*paramsDto* - the value of parameters passed - -*resultDto* - the value of result passed - -Source code example of using of the transmitter can be found here: https://github.com/eclipse/che/blob/master/wsagent/che-core-api-debug/src/main/java/org/eclipse/che/api/debugger/server/DebuggerJsonRpcMessenger.java#L117 - -[id="client-endpoint-identification"] -== Client endpoint identification - -In order to receive a cross sessional identifier clients (e.g. IDE) can use a https://github.com/eclipse/che/blob/master/core/che-core-api-core/src/main/java/org/eclipse/che/api/core/websocket/impl/WebsocketIdService.java[`org.eclipse.che.api.core.websocket.impl.WebsocketIdService`], otherwise client identifier will not be persisted between websocket sessions. The most common use case (client specific): - -[source,java] ----- -requestTransmitter - .newRequest() - .endpointId("ws-master") - .methodName("websocketIdService/getId") - .noParams() - .sendAndReceiveResultAsString() - .onSuccess(appContext::setApplicationWebsocketId); ----- - -Source code example of using websocket identification service can be found here: https://github.com/eclipse/che/blob/master/ide/che-core-ide-app/src/main/java/org/eclipse/che/ide/jsonrpc/WsMasterJsonRpcInitializer.java#L134 diff --git a/src/main/pages/che-6/developer-guide/actions.adoc b/src/main/pages/che-6/developer-guide/actions.adoc deleted file mode 100644 index 44b18f8aaa..0000000000 --- a/src/main/pages/che-6/developer-guide/actions.adoc +++ /dev/null @@ -1,460 +0,0 @@ ---- -title: "IDE UI: Actions" -keywords: framework, UI, actions -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/actions.html -redirect_from: actions.html -folder: che-6/developer-guide ---- - - -Actions allow you to add custom behavior to the Che IDE. They can be placed in menus, toolbars or context menus. An Action is a Java class, which implements the behavior to be executed. Additionally, it defines a text to be shown, a tooltip and an icon. In the following section, we describe the implementation of Actions more in detail. To make Actions available in the Che IDE, they need to be registered and placed into ActionGroups. Thereby, you specify the location (e.g. a menu or toolbar), where the actions is shown. The registration of actions is described in the subsequent section link:#registering-actions[Registering Actions]. - -[id="authoring-actions"] -== Authoring Actions - -Simple `Actions` directly inherit from `org.eclipse.che.ide.api.action.Action`. In the constructor, we use the super class to configure our action with the following parameters: - -* *text* (String): The name of the action shown in the UI, in our case defined by concrete Actions (sub classes). -* Optional: *description* (String): The description of the action shown in the UI, in our case defined by concrete Actions (sub classes). - -In the example action below, the constructor also gets the `NotificationManager` injected, which is used to display a "Hello World" message. A custom `Action` need to implement the `#actionPerformed` method, which is called when it is invoked. Actions can be associated with a variety of triggers within the system such as buttons, menu item selections, or user input (see following section). - -[source,java] ----- -@Singleton -public class HelloWorldAction extends Action { - - private NotificationManager notificationManager; - - @Inject - public HelloWorldAction(NotificationManager notificationManager) { - super("Say Hello World", "Say Hello World Action"); - this.notificationManager = notificationManager; - } - - @Override - public void actionPerformed(ActionEvent e) { - this.notificationManager.notify("Hello World", StatusNotification.Status.SUCCESS, StatusNotification.DisplayMode.FLOAT_MODE); - } -} ----- - -Additionally, you can optionally define an icon for an Action. This is done by calling an alternative constructor including the following two parameters: - -* *imageResource*: An icon for the action shown in the UI, in our case defined by concrete Actions, we pass in null, as we alternatively use svgResource. -* *svgResource* (SVGResource): An Icon for the the action shown in the UI, in our case defined by concrete Actions (sub classes). - -The following code example defines another "Hello World" action including a corresponding icon: - -[source,java] ----- -@Singleton -public class HelloWorldActionWithIcon extends Action { - - private NotificationManager notificationManager; - - @Inject - public HelloWorldActionWithIcon( - NotificationManager notificationManager) { - super("Say Hello World", "Say Hello World Action", null, SampleActionsResources.INSTANCE.icon()); - this.notifpricationManager = notificationManager; - } - - /... -} ----- - -[id="registering-actions"] -== Registering Actions - -Once we have implemented a custom action, we must register it. This is done in the custom `Extension` class , which is used for other extensions, too (see link:guice.html[Dependency Injection Basics]). - -As a first step, we register the `HelloWorldAction` itself at the `ActionManager`. Thereby, Che is aware of the action to be executed. Along with the registration, an action must be associated with a unique ID, which allows to reference the `Action`. - -Second, to define a place in the IDE where the Action is visible to the user, we place the Action in an existing `ActionGroup`. Actions are organized into groups, which, in turn, can contain other groups. A group of actions can form a toolbar or a menu. Subgroups of the group can form submenus of the menu. You can directly place an `Action` into an existing group. Alternatively, you can crea]te a custom group containing your action and add this group into Che. In the following example, a custom group is created (`SampleGroup`), the `HelloWorldAction` is added to it and the Group is placed in the main menu of Che. Additionally, the `HelloWorldActionWithIcon` is directly placed into the main menu. - -Please see the following section on more details about existing action locations (i.e. groups) in Che and how to specify the order of actions within those groups. - -[source,java] ----- -@Extension(title = "Sample Actions Extension", version = "1.0.0") -public class SampleActionsExtensions { - @Inject - public SampleActionsExtensions(HelloWorldAction helloWorldAction, ActionManager actionManager) { - - actionManager.registerAction("helloWorldAction", helloWorldAction); - actionManager.registerAction("helloWorldActionWithIcon", helloWorldActionWithIcon); - /... - - DefaultActionGroup sampleGroup = new DefaultActionGroup("Sample actions", true, actionManager); - - sampleGroup.add(helloWorldAction); - - // add sample group after help menu entry - DefaultActionGroup mainMenu = (DefaultActionGroup)actionManager.getAction(GROUP_MAIN_MENU); - mainMenu.add(sampleGroup); - - // add the sample group to the beginning of the toolbar as well - DefaultActionGroup toolbar = (DefaultActionGroup)actionManager.getAction(IdeActions.GROUP_MAIN_TOOLBAR); - toolbar.add(helloWorldActionWithIcon); - /... - } -} ----- - -[id="action-locations"] -== Action Locations - -In this section, we describe more in detail, how actions can be placed at specific locations within Che and how the order within toolbars and menus can be specified. Both, the location and the order is specified along with the registration of an action. - -Every action and action group in Che has a unique identifier. This allows to reference existing groups and actions when registering a new element and thereby specify its location. In the example registration in the previous section, we have used the ID of the Che main menu to place our custom action group and action in it. All existing identifiers for existing che action groups can be found in https://github.com/eclipse/che/blob/master/ide/che-core-ide-api/src/main/java/org/eclipse/che/ide/api/action/IdeActions.java[org.eclipse.che.ide.api.action.IdeActions]. Additionally, you can find an example in a https://github.com/che-samples/che-ide-server-extension/blob/master/plugins/plugin-serverservice/plugin-serverservice-ide/src/main/java/org/eclipse/che/sample/ide/action/MyAction.java[sample extension]. - -In addition to placing actions in groups, you can define a relative order for actions and groups within their parent container. Therefore, a constraint needs to be specified when adding an element to a group. The constraint defines an anchor (ID of an existing element) and a relation to it (`BEFORE` or `AFTER`). Alternatively, you can use `Constraints.FIRST` and `Constraints.LAST` (default) to add an element at the beginning or at the end, respectively. - -The following code example shows the registration of the group containing `HelloWorldAction` after the existing help menu, as well as the action itself at the beginning of the main toolbar. - -[source,java] ----- -DefaultActionGroup sampleGroup = new DefaultActionGroup("Sample actions", true, actionManager); -sampleGroup.add(helloWorldAction); - -// add sample group after help menu entry -DefaultActionGroup mainMenu = (DefaultActionGroup)actionManager.getAction(GROUP_MAIN_MENU); -mainMenu.add(sampleGroup, new Constraints(AFTER, GROUP_HELP)); - -// add the sample group to the beginning of the toolbar as well -DefaultActionGroup toolbar = (DefaultActionGroup)actionManager.getAction(IdeActions.GROUP_MAIN_TOOLBAR); -toolbar.add(helloWorldActionWithIcon, Constraints.FIRST); ----- - -[id="visibility-and-enablement"] -== Visibility and Enablement - -By default, actions will always be visible to the user and enabled. However, certain actions shall only be visible or enabled based on the current state of Che. The implementation of an action is responsible for managing its visibility and enabled state. - -Therefore, you need to implement the method `Action.update()` in a custom action. The method is periodically called by the IDE for updating the state. The object of type `ActionEvent` passed to this method carries the information about the current context for the action, e.g. the current perspective of the current selection. Additional information about the current state of the IDE can be retrieved form the service `AppContext`. See an example link:#projectperspective-specific-actions-json-example[here] - -The `ActionEvent` allows access to the specific presentation which needs to be updated. As every action can be included in multiple groups and appear in multiple places within the IDE user interface, the visibility and enabled state can not centrally be controlled for an action. For every place where the action appears, a new Presentation is created on which the visibility and enabled state is set alternatively. Please note, that the `ActionEvent` instance is also passed to the `actionPerformed()` method, when the action is executed. - -The following example shows the `OnProjectHelloWorldAction`, which is placed in the main menu of Che. It controls its visibility based on the state and is only visible if a project is selected in the navigator. - -_che/samples/sample-plugin-actions/che-sample-plugin-actions-ide/src/main/java/org/eclipse/che/plugin/sampleactions/ide/action/OnProjectHelloWorldAction.java_ - -[source,java] ----- -public class OnProjectHelloWorldAction extends Action { - - private AppContext appContext; - private final NotificationManager notificationManager; - - /** - * Constructor. - * @param appContext - * the application context - * @param notificationManager - * the notification manager - */ - @Inject - public OnProjectHelloWorldAction( - final AppContext appContext, - final NotificationManager notificationManager) { - super("Project specific Hello World", "We have a project"); - this.appContext = appContext; - this.notificationManager = notificationManager; - } - - @Override - public void actionPerformed(ActionEvent e) { - this.notificationManager.notify( - "Hello World in the context of a project", - StatusNotification.Status.SUCCESS, - StatusNotification.DisplayMode.FLOAT_MODE); - } - - @Override - public void update(ActionEvent e) { - e.getPresentation().setEnabledAndVisible(appContext.getRootProject() != null); - } -} ----- - -[id="reusable-actions"] -== Reusable Actions - -For common operations such as creating files, Che provides reusable default actions. Custom implementations can inherit from those and thereby only need to specify their specifics, while reusing most of the default behavior. In this section, we provide an overview of the most common reusable actions in Che. - -[id="create-file-actions"] -== Create File Actions - -Che provides a template implementation for actions to create new resources (i.e. files). When using the template, you only need to specify the name of the action as well as the file extension to be created (as shown in the following code example). - -[source,java] ----- -org.eclipse.che.plugin.myextension.ide.action.CreateMyFileAction -public class CreateMyFileAction extends AbstractNewResourceAction { - - @Inject - public CreateMyFileAction(MyResources myResources) { - super("Create my File", "Create a new file ", myResources.icon()); - } - - @Override - protected String getExtension() { - return "my"; - } -} ----- - -[id="projectperspective-specific-actions"] -== Project/Perspective-specific Actions - -In this part of the tutorial, as part of the this JSON example we describe how to add project- and perspective-specific actions, meaning actions that are only available for a specific project type and within specific perspectives. As we want to define several actions of this type, we will create a template implementation and then inherit from it for the implementation of several actions. - -These example actions will be placed in the context menu on the specific JSON project type defined before. The following diagram shows all components of a project type registration. The classes highlighted in dark grey are to be implemented for the extension. - -First, our actions must determine whether they are available based on the current app context, in our case, based on the current project type. As we want to add several project specific actions, it makes sense to extract this behavior into an abstract class, in our case `MyAbstractProjectSpecificAction`. By inheriting from this abstract base class, we can now easily add project specific actions implementing the actual behavior to be executed. - -As described before, to make an action available in Che, it needs to be registered at the `ActionManager`. This is done in an `Extension`. - -image::devel/my_plugin.png[] - -In the following example, we first define the perspective- and project specific template action. Then, we define a simple action for the JSON example and register it in the context menu of the JSON project type. The action itself will trigger a simple notification once executed. However, the action could be adapted to execute any kind of behavior. - -To make our abstract template action perspective-specific, we inherit from a reusable action implementation `AbstractPerspectiveAction` provided by Che. Compared to the basic `Action` its constructor allows the definition of a list of perspectives, in which the action is visible, referenced by ID. Null or empty list means the action is enabled everywhere. In the example, the project perspective, only. - -The constructor also gets the `AppContext` injected, which is used in the following to control the project-specific visibility of the action (see description below). - -[source,java] ----- -org.eclipse.che.plug.plugin.jsonexample.ide.action.JsonExampleProjectAction -public abstract class JsonExampleProjectAction extends AbstractPerspectiveAction { - - private AppContext appContext; - - public JsonExampleProjectAction(AppContext appContext, - @NotNull String text, - @NotNull String description, - @Nullable SVGResource svgResource) { - - super(Collections.singletonList(ProjectPerspective.PROJECT_PERSPECTIVE_ID), - text, - description, - null, - svgResource); - this.appContext = appContext; - } - - @Override - public void updateInPerspective(@NotNull ActionEvent event) { - CurrentProject currentProject = appContext.getCurrentProject(); - event.getPresentation().setEnabledAndVisible( - isJsonExampleProjectType(currentProject)); - } - - private static boolean isJsonExampleProjectType(CurrentProject currentProject) { - if (currentProject == null) { - return false; - } - return Constants.JSON_EXAMPLE_PROJECT_TYPE_ID.equals( - currentProject.getProjectConfig().getType()); - } - -} ----- - -The `#updateInPerspective` method is responsible for updating the enablement and the visibility of the action. In this example, we only want to show the action, if the current project is a JSON project. Therefore, we retrieve the current project from the `AppContext`, check whether there is a current project and if so, whether it has the expected project type. Calling `event.getPresentation().setEnabledAndVisible(true/false)` will set the enablement and the visibility accordingly. - -After defining a project specific action, we can now define an arbitrary number of concrete implementations to add custom behavior. The example below inherits from our `JsonExampleProjectAction` and uses the super constructor to configure the specificity of the action. Further, the constructor gets the `NotificationManager` injected, which is used in the implementation of the action below. The method `#actionPerformed` will be called once the user has clicked on an action. - -In the example, we trigger a simple notification. However, this simple behavior could be replaced with any custom operation. - -[source,java] ----- -org.eclipse.che.plug.plugin.jsonexample.ide.action.HelloAction -@Singleton -public class HelloWorldAction extends JsonExampleProjectAction { - - private NotificationManager notificationManager; - - @Inject - public HelloWorldAction(AppContext appContext, - NotificationManager notificationManager) { - super(appContext, - "Say Hello World", - "Say Hello World Action", - null); - this.notificationManager = notificationManager; - } - - - @Override - public void actionPerformed(ActionEvent e) { - this.notificationManager.notify( - "Hello World", - StatusNotification.Status.SUCCESS, - StatusNotification.DisplayMode.FLOAT_MODE - ); - } -} ----- - -Once we have implemented a custom action, we must register it. This is done in the custom extension class `JsonExampleExtension`, which has been used for other extensions before (see link:guice.html[Dependency Injection Basics]). - -To keep all JSON example related actions together, we define a new `ActionGroup` called "JSON Example". The second parameter defines that the group is displayed as a popup. After registering the new group at the `ActionManager`, we add our custom `HelloWorldAction` to it. - -To define a place in the IDE where the Action is visible to the user, we further place the Action in an existing `ActionGroup`, in our case, the context menu of a project. - -[source,java] ----- -org.eclipse.che.plugin.jsonexample.ide.JsonExampleExtension -@Extension(title = "JSON Example Extension", version = "0.0.1") -public class JsonExampleExtension { - @Inject - public JsonExampleExtension( - ActionManager actionManager, - HelloWorldAction helloWorldAction, - JsonExampleResources jsonExampleResources, - IconRegistry iconRegistry) { - - actionManager.registerAction("helloWorldAction", helloWorldAction); - - DefaultActionGroup jsonGroup = new DefaultActionGroup("JSON Example", - true, actionManager); - actionManager.registerAction("jsonExample", jsonGroup); - jsonGroup.add(helloWorldAction); - - DefaultActionGroup mainContextMenuGroup = (DefaultActionGroup) actionManager.getAction("resourceOperation"); - mainContextMenuGroup.add(jsonGroup); - - } -} ----- - -Finally, we can open the context menu on our custom project type and trigger the example action. - -[id="further-example-actions"] -== Further Example Actions - -In this section, we provide a collection of existing example actions to demonstrate the variety of possible locations and behavior to be executed. - -The following example creates a `RedirectToDashboardWorkspacesAction` which is the behavior that redirects the IDE back into the user dashboard application. - -_https://github.com/eclipse/che/blob/master/core/ide/che-core-ide-app/src/main/java/org/eclipse/che/ide/actions/RedirectToDashboardWorkspacesAction.java_ - -[source,java] ----- -package org.eclipse.che.ide.actions; - -import com.google.gwt.user.client.Window; -import com.google.inject.Inject; - -import org.eclipse.che.ide.CoreLocalizationConstant; -import org.eclipse.che.ide.api.action.Action; -import org.eclipse.che.ide.api.action.ActionEvent; - -public class RedirectToDashboardWorkspacesAction extends Action { - - private static final String REDIRECT_URL = "/dashboard/#/workspaces"; - - @Inject - public RedirectToDashboardWorkspacesAction(CoreLocalizationConstant localization) { - super(localization.actionRedirectToDashboardWorkspacesTitle(), - localization.actionRedirectToDashboardWorkspacesDescription(), - null, - null); - } - - @Override - public void actionPerformed(ActionEvent e) { - Window.open(REDIRECT_URL, "_blank", ""); - } -} ----- - -The following example executes a server call to retrieve and display the number of lines of code from all JSON files within a project: - -[source,java] ----- -/** - * Action for counting lines of code of all JSON files within the current project. - * Line counting is implemented by consuming a RESTful service. - */ -@Singleton -public class CountLinesAction extends JsonExampleProjectAction { - - private final AppContext appContext; - private final StringMapUnmarshaller unmarshaller; - private final AsyncRequestFactory asyncRequestFactory; - private final NotificationManager notificationManager; - - /** - * Constructor - * - * @param appContext - * the IDE application context - * @param resources - * the JSON Example resources that contain the action icon - * @param asyncRequestFactory - * asynchronous request factory for creating the server request - * @param notificationManager - * the notification manager used to display the lines of code per file - */ - @Inject - public CountLinesAction(AppContext appContext, - JsonExampleResources resources, - AsyncRequestFactory asyncRequestFactory, - NotificationManager notificationManager) { - - super(appContext, - "Count JSON Lines of Code", - "Counts lines of code for all JSON Files in the project", - resources.icon()); - - this.appContext = appContext; - this.asyncRequestFactory = asyncRequestFactory; - this.notificationManager = notificationManager; - this.unmarshaller = new StringMapUnmarshaller(); - } - - @Override - public void actionPerformed(ActionEvent e) { - - String url = this.appContext.getDevMachine().getWsAgentBaseUrl() + "/json-example/" + this.appContext.getWorkspaceId() + -this.appContext.getCurrentProject().getRootProject().getPath(); - - asyncRequestFactory.createGetRequest(url, false).send( - new AsyncRequestCallback>(unmarshaller) { - - @Override - protected void onSuccess(Map linesPerFile) { - for (Map.Entry entry : linesPerFile.entrySet()) { - String fileName = entry.getKey(); - String loc = entry.getValue(); - notificationManager.notify("File " + fileName + " has " + loc + " lines.", StatusNotification.Status.SUCCESS, StatusNotification.DisplayMode.FLOAT_MODE); - } - } - - @Override - protected void onFailure(Throwable exception) { - notificationManager.notify(exception.getMessage(), StatusNotification.Status.FAIL, StatusNotification.DisplayMode.FLOAT_MODE); - } - }); - } -} ----- - -The following example shows how Che registers all of the actions for the https://github.com/eclipse/che/blob/master/plugins/plugin-git/che-plugin-git-ext-git/src/main/java/org/eclipse/che/ide/ext/git/client/GitExtension.java[Git menu]. - -[source,java] ----- -DefaultActionGroup git = new DefaultActionGroup(GIT_GROUP_MAIN_MENU, true, actionManager); -actionManager.registerAction("git", git); -mainMenu.add(git, new Constraints(BEFORE, GROUP_HELP)); - -DefaultActionGroup commandGroup = new DefaultActionGroup(COMMAND_GROUP_MAIN_MENU, false, actionManager); -actionManager.registerAction("gitCommandGroup", commandGroup); -git.add(commandGroup); -git.addSeparator(); ----- diff --git a/src/main/pages/che-6/developer-guide/assemblies.adoc b/src/main/pages/che-6/developer-guide/assemblies.adoc deleted file mode 100644 index 4103ca00e2..0000000000 --- a/src/main/pages/che-6/developer-guide/assemblies.adoc +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Che Assemblies -sidebar: che_6_docs -keywords: dev docs -tags: [extensions, assembly] -permalink: che-6/assemblies.html -redirect_from: assemblies.html -folder: che-6/developer-guide ---- - - -[id="understanding-che-assemblies"] -== Understanding Che Assemblies? - -An assembly is a Maven module that produces a build artifact. In case of https://github.com/eclipse/che/tree/master/assembly[Eclipse Che], this is either a `.war` with `jars` in it, or a Tomcat assembly, which is a Tomcat web server with custom configuration and artifacts, copied to `webapps`. The following are Eclipse Che assemblies: - -[width="100%",cols="61%,39%",options="header",] -|=== -|Che Assembly |What Is Included -|`assembly-ide-war` |GWT plugins that will be compiled into a new browser IDE as JavaScript -|`assembly-wsagent-war` |Java plugins that will run within a workspace agent, deployed as `.war` artifact with numerous jars in it -|`assembly-wsagent-server` |Packages workspace agent into a Tomcat that is then launched in a machine -|`assembly-wsmaster-war` |Java plugins that will run within Che core server - master -|`assembly-main` |Packages all Che modules (including those listed above) into a final Tomcat bundle -|=== - -[id="assembly-ide-war"] -== assembly-ide-war - -A successful build of this module produces an `ide.war` file, which is then deployed with Tomcat (produced by `assembly-main`) as a `ROOT.war` that contains dependencies packages as JAR files. It also contains the `_app` directory with JavaScript, CSS, and other resources that are loaded into the `IDE.html` file when the IDE is initialized. - -This module inherits https://github.com/eclipse/che/blob/da18cd1867210f87a6071ed65930fb47fb8bb775/ide/che-ide-gwt-app/pom.xml[`che-ide-gwt-app`] that it its turn has https://github.com/eclipse/che/blob/5a6d3910b268feb3c4e67c2ff9aa5640410bf777/ide/che-ide-full/pom.xml[`che-ide-full`] in dependencies. So, `che-ide-full` is where all of the client side plugin dependencies are declared. - -However, if you build a custom assembly and your plugin provides client side changes, it is root pom.xml of *assembly-ide-war* that dependencies should be added to. See: link:ide-extensions-gwt.html[IDE Extensions]. - -This is the module that is most often extended with custom plugins. - -[id="assembly-wsagent-war"] -== assembly-wsagent-war - -The build artifact of this module contains all server-side plugins components packaged as JAR files. Root `pom.xml` contains dependencies to all plugins that get deployed with the workspace agent, and this is where dependencies to custom plugins should be added. Once built, `assembly-wsagent-war` is copied to `webapps` of ws-agent Tomcat as `ROOT.war`. This is the module that is most often extended with custom plugins. - -[id="assembly-wsagent-server"] -== assembly-wsagent-server - -This module packages `ROOT.war` into Tomcat’s `webapps` and adds configuration files. This Tomcat is packaged as a `tar.gz` archive that is then placed into main Tomcat produced by the `assembly-main` build. - -[id="assembly-wsmaster-war"] -== assembly-wsmaster-war - -The core of Che platform as a workspace server that includes link:rest-api.html[workspace API], user profile and settings, link:spi-implementation.html[implementation of runtime infrastructure]. Usually used as a dependency in custom assemblies, however, it is possible to extend it, for example, by providing support of a new infrastructure. - -[id="assembly-main"] -== assembly-main - -This is the main assembly that packages all Che components into a Tomcat server. These components include wsmaster as `api.war`, User Dashboard as `dashboard.war`, documentation - `docs.war` and Swagger UI - `swagger.war`, agents like terminal and ws-agent (those are packaged into `lib` directory in the root of the resulting archive where Che master picks them up and serves, thus making them downloadable for link:installers.html[installers]). - -[id="custom-assemblies"] -== Custom Assemblies - -You may build your own custom assembly of Che. To do so, there is no need to clone or copy the entire Che source code. All artifacts can be used as dependencies. Also, unlike assemblies in Che source code, custom assemblies can use minimal artifacts for server and client side. - -See an https://github.com/che-samples/che-ide-server-extension[example] of a custom Che assembly that brings in two plug-ins - server- and client-side. You may clone this repository and use it as a basis for your custom Che assembly. - -Note that this example uses core artifacts as dependencies both for https://github.com/che-samples/che-ide-server-extension/blob/master/assembly/assembly-ide-war/pom.xml#L31-L35[client]: - -[source,xml] ----- - - org.eclipse.che.core - che-ide-core - gwt-lib - ----- - -and https://github.com/che-samples/che-ide-server-extension/blob/master/assembly/assembly-wsagent-war/pom.xml#L22-L26[server side]: - -[source,xml] ----- - - org.eclipse.che.core - che-wsagent-core - war - ----- - -Core artifacts contain a bare minimum set of platform components and plugins to be able to create and start a workspace, create or import a project, open and edit files in the editor. - -You may use full artifacts that include all standard Che plugins: - -Client side: - -[source,xml] ----- - - org.eclipse.che.core - che-ide-full - gwt-lib - ----- - -You may include a full IDE artifact and exclude a particular plugin: - -[source,xml] ----- - - - org.eclipse.che.core - che-ide-full - - - che-plugin-product-info - org.eclipse.che.plugin - - - - - - - - org.eclipse.che.core - che-core-gwt-maven-plugin - ${project.version} - - - - process-excludes - - - - - - ----- - -Server side: - -[source,xml] ----- - - - org.eclipse.che - assembly-wsagent-war - war - ----- - -These two `pom.xml` files are entrypoints to adding custom plugins. This assembly includes two plugins, which are declared in: - -* https://github.com/che-samples/che-ide-server-extension/blob/master/pom.xml#L54-L64[root `pom.xml`] - artifact version defaults to project version. These dependencies need to be declared to follow dependency convergence rules in Che (i.e. all dependencies have to be declared either in Che `maven-depmgt-pom` or in a root pom of an assembly). `maven-depmgt-pom` parent brings a set of enforcer plug-ins, such as formatting, dependency management, source validation, and others. -+ -[source,xml] ----- - - org.eclipse.che.sample - plugin-serverservice-server - ${project.version} - ----- - -* https://github.com/che-samples/che-ide-server-extension/blob/master/assembly/assembly-ide-war/pom.xml#L36-L40[assembly-ide-war pom]: -+ -[source,xml] ----- - - org.eclipse.che.sample - plugin-serverservice-ide - gwt-lib - ----- -+ -This way, your client-side plug-in is included in `ide.war`. We use https://maven.apache.org/plugins/maven-war-plugin/overlays.html[Maven’s overlays feature] to package custom plug-ins into the resulting artifact. - -* https://github.com/che-samples/che-ide-server-extension/blob/master/assembly/assembly-wsagent-war/pom.xml#L27-L30[assembly-wsmaster-war pom]: -+ -[source,xml] ----- - - org.eclipse.che.sample - plugin-serverservice-server - ----- - -Your custom plug-in packaged as a JAR file is automatically added to the inherited `wsagent` artifact if both are declared as dependencies in `pom.xml`. As a result, the final `.war` artifact will contain a custom JAR file. - -[id="updating-assemblies"] -== Updating assemblies - -In the `pom.xml` file, update both: - -[source,xml] ----- - - maven-depmgt-pom - org.eclipse.che.depmgt - 6.0.0-M4 - ----- - -and - -[source,xml] ----- - - 6.0.0-M4 - ----- - -Keep the versions consistent to avoid build failures and incompatibilities. It is also recommended to keep versions of own artifacts aligned with a parent version. - -[id="next-steps"] -== Next steps - -Now that you have got some knowledge about Che assemblies and own cloned a sample assembly, take a closer look at Eclipse Che link:ide-extensions-gwt.html[client] and link:server-side-extensions.html[server-side] plug-ins. diff --git a/src/main/pages/che-6/developer-guide/build-reqs.adoc b/src/main/pages/che-6/developer-guide/build-reqs.adoc deleted file mode 100644 index 40d68064c4..0000000000 --- a/src/main/pages/che-6/developer-guide/build-reqs.adoc +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Build Requirements" -keywords: java. maven, node, npm -tags: [dev-docs] -sidebar: che_6_docs -permalink: che-6/build-reqs.html -redirect_from: build-reqs.html -folder: che-6/developer-guide ---- - - -[id="build-command"] -== Build Command - -`mvn clean install` - -Execute this command in the root of your custom assembly or Che repo. To make your build faster, you may use the following arguments: - -`-Dskip-enforce -DskipTests -Dskip-validate-sources -Dfindbugs.skip -DskipIntegrationTests=true -Dmdep.analyze.skip=true` - -If you prepare a PR to upstream Che, make sure build is a success with just `mvn clean install` with all the tests and enforcers. If you have enough CPU, you may also add `-Dgwt.compiler.localWorkers=4` so that 4 CPU cores will be used during GWT compilation. - -[id="pre-reqs"] -== Pre-Reqs - -* JDK 1.8.0_130+ -* Maven 3.3.5+ -* Go 1.8+ - -By default, Che is built with docker profile, which means Dashboard is built in a Docker container. You may use a different profile though - `mvn clean install -Pnative` - in that case the following Node.JS version needs to be available: - -* Node.JS 5.4+ - -If your link:assemblies.html[custom assembly] does not bring any changes to Dashboard, https://github.com/eclipse/che/tree/master/agents[Golang agents] and link:what-are-workspaces.html#bootstrapper[bootstrapper], you just need JDK 1.8.0_130+ installed. - -At least 2 CPUs and 8GB RAM (recommended) is required. - -[id="build-in-docker"] -== Build in Docker - -You can use a https://github.com/eclipse/che/blob/master/dockerfiles/dev/Dockerfile[dev Docker image]: - -`docker run -ti -v ~/.m2:/home/user/.m2 -v /path/to/che/assembly:/che eclipse/che-dev:nightly sh -c "mvn clean install"` - -We recommend mounting Maven repo (`-v ~/.m2:/home/user/.m2`) to persist dependencies and make subsequent builds faster. - -[id="build-in-che"] -== Build in Che - -See: link:che-in-che-quickstart.html[Che in Che quickstart] - -[id="enforcers"] -== Enforcers - -There are a few Maven enforcers brought by a parent pom. - -*License* - -All source file should have expected license. If your build fails because of a missing license, you may run `mvn license:format` - -*Dependency Convergence* - -Your custom dependencies need to be declared to follow dependency convergence rules in Che (i.e. all dependencies have to be declared either in Che `maven-depmgt-pom` or in a root pom of an assembly). - -*Formatting* - -See: https://github.com/eclipse/che/wiki/Development-Workflow#code-style[Code Style] diff --git a/src/main/pages/che-6/developer-guide/che-in-che-quickstart.adoc b/src/main/pages/che-6/developer-guide/che-in-che-quickstart.adoc deleted file mode 100644 index 4da5afd5a6..0000000000 --- a/src/main/pages/che-6/developer-guide/che-in-che-quickstart.adoc +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Develop Your First Plugin Usign Che -sidebar: che_6_docs -keywords: dev docs, developer docs, plugins, extensions -tags: [extensions, dev-docs, assembly] -permalink: che-6/che-in-che-quickstart.html -redirect_from: che-in-che-quickstart.html -folder: che-6/developer-guide ---- - -Before you dive into information on how you can link:framework-overview.html[extend Che framework] and build your own Che link:assemblies.html[assembly], let’s install and debug your first Che plugin using Che itself. - -[id="run-eclipse-che"] -== Run Eclipse Che - -* Installing it on Docker: link:docker-single-user.html[Single-user] or link:docker-multi-user.html[Multi-user] -* Installing it on OpenShift: link:openshift-single-user.html[Single-user] or link:openshift-multi-user.html[Multi-user] - -[id="create-workspace-and-sample-extension"] -== Create Workspace and Sample Extension - -Search for a stack by keyword `che` and choose `che-ide-server-extension` as a sample project. This extension is both IDE and server side extension. It will bring a new menu item, an action to the IDE and a notification returned from a simple REST service. - -image::devel/create_extension.png[] - -[id="build-a-deploy-your-extension"] -== Build a Deploy Your Extension - -When the project shows up in project explorer, you will find 2 main Maven modules: `assembly` (See: link:assemblies.html[Assemblies]) and plugins (containing plugins themselves). - -Execute `Traefik Start`, `Tomcat8-IDE Start`, `Deploy IDE` and `Deploy Workspace Agent` commands: - -image::devel/commands.png[] - -* Tomcat8-IDE Start - the name speaks for itself. The command starts a Tomcat 8 server -* Traefik Start - we need some smart redirects inside a workspace. By design, the IDE tries to reach workspace master at the same host:port it is running. Since we will access the 2nd IDE instance on the same host, but a different port (it’s a random port from the ephemeral port range that Docker uses to publish exposed ports) -* Deploy IDE - build ide-war module and its dependencies and packages `war` artifact and copies ide.war from `assembly-ide-war` target dir over to Tomcat’s webapp -* Deploy Workspace Agent does the same with the agent war artifact - -The last two commands have identical preview URLs pointing to `host:port` Tomcat 8 with two extensions is bound to. You will notice `?wsagent-ref-prefix=dev-` appended to the URL. This param is an instruction for the IDE to connect to your custom workspace agent, not the default one (this is where Traefik magic happens). Click this preview URL, and when you are in the 2nd instance of IDE, call context menu in the project explorer (right click) to find *MyAction*. Click it to see a notification with `Hello CheeAllPowerfull` message: - -image::devel/sample_action.png[] - -[id="develop-and-debug-client-side"] -== Develop and Debug Client Side - -Get back to an original IDE instance and execute `GWT SDM` command which will run http://www.gwtproject.org/articles/superdevmode.html[GWT Super Dev Mode]. You can find more info about Super Dev Mode in Che at link:ide-extensions-gwt.html#debugging-with-super-devmode[this page]. When the compilation is completed, hit the preview URL which will display a page with further instructions. You’ll have to drag 2 bookmarks to your browser’s bookmarks bar. Having done that, change menu item title in `MyAction.java`: - -[source,java] ----- - super("My New Action", "My Action Description"); ----- - -Return to the 2nd IDE instance, click *Dev Mode On* button and hit *Compile*. Re-compilation should take ~15 seconds. Once done, call context menu in the project explorer again to see your changes. - -You can also debug your client code in the browser. In the 2nd IDE instance with your custom plugin, open `Chrome dev console > Sources > Ctrl + P > MyAction.java`. Set a breakpoint in this class and call `My New Action` in the context menu. - -image::devel/debug_chrome.png[] - -[id="develop-and-debug-server-side"] -== Develop and Debug Server Side - -Let’s change response from our REST service in `MyService.java`: - -[source,java] ----- -public String sayHello(@PathParam("name") String name) { - return "Howdy, " + name + "!"; -} ----- - -Select this submodule in project explorer (`plugin-serverservice-server`) and run `Build` and `Workspace Agent Hot Deploy` commands one by one that will package your extension into jar artifact and swap it (by copying) in Tomcat’s `webapps/ROOT/WEB-INF/lib/` that Tomcat hot deploys it. Now return to your 2nd IDE instance, call My New Action and get an updated response from server side. - -It’s time to *debug* this REST service. By default, we have started Tomcat in a debug mode (`jpda run`) on port 9000 which we will use to attach Che debugger. - -Open `MyService.java` and set a breakpoint on line 31 (where response is returned). Go to *Run > Edit Debug Configurations > Java > Connect to process on a workspace machine > port 9000*. Save this configuration and click Debug. You will also see this configuration at *Run > Debug*. - -Return to the 2nd IDE instance and call My New Action. You will get stuck and see a loader. In the main IDE instance you will see a debugger panel: - -image::devel/debugger.png[] - -In Variable window, click `Change variable` icon and replace the value with anything you like. Hit Resume (F9) and get back to your 2nd IDE instance to see the updated response from the REST service. - diff --git a/src/main/pages/che-6/developer-guide/cors.adoc b/src/main/pages/che-6/developer-guide/cors.adoc deleted file mode 100644 index 873812e47e..0000000000 --- a/src/main/pages/che-6/developer-guide/cors.adoc +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Che CORS filters -sidebar: che_6_docs -keywords: dev docs -tags: [cors] -permalink: che-6/cors.html -redirect_from: cors.html -folder: che-6/developer-guide ---- - - - -Note: Che 6.15 CORS configuration is not compatible with Che 6.16 instances, due to CORS requirementes in Tomcat 8.5.35. - -If you are running into an issue related (e.g. IDE is not properly working, and there are CORS related errors in the browser console) -Make sure to use the correct deployments with updated configuration from 6.16 -Also, do not use localhost as che-host, as it is not supported by browsers. - -== CORS filters in Che - -CORS filters are present in Che to allow requests with origins, that can be different from the origin that the client is loaded on (For example, GWT IDE executing requests from browser to WS Agent, with origin belonging to WS Master domain). - -The default configuration for CORS goes as follows: - -WS Master: - -"cors.support.credentials" - "false" -"cors.allowed.origins" - "*" - -WS Agent: - -"cors.support.credentials" - true -"cors.allowed.origins" - - -== Overriding default CORS configuration - -Here is the full list of environment variables that can be usedfor overriding of default configuration for CORS on WS Master and WS Agent: - -* `CHE_CORS_ENABLED` = Enabling CORS Filter on WS Master. On by default -* `CHE_CORS_ALLOWED_ORIGINS` = List of allowed origins in requests to WS Master. Default is "*". -* `CHE_CORS_ALLOW_CREDENTIALS` = Allowing requests with credentials to WS Master. Default is "false". - -* `CHE_WSAGENT_CORS_ENABLED` = Enabling CORS Filter on WS Agent. -* `CHE_WSAGENT_CORS_ALLOWED__ORIGINS` = List of allowed origins in requests to WS Agent. If not set, or set to "null", value will be evaluated from CHE_API variable at runtime. -* `CHE_WSAGENT_CORS_ALLOW__CREDENTIALS` = Allowing requests with credentials to WS Agent. Default is "true". diff --git a/src/main/pages/che-6/developer-guide/custom-installers.adoc b/src/main/pages/che-6/developer-guide/custom-installers.adoc deleted file mode 100644 index 5f7e363532..0000000000 --- a/src/main/pages/che-6/developer-guide/custom-installers.adoc +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: "Installers" -keywords: framework, overview, master, server, che server, framework -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/custom-installers.html -redirect_from: custom-installers.html -folder: che-6/developer-guide ---- - -Now that you have made yourself familiar with link:installers.html[Installer] concept and usage, let’s take a closer look at implementing custom ones. - -Let’s take a closer look of a custom installer named `Curl`: - -The installer can be split into description in json format and shell script. - -The description has the following format: - -[source,json] ----- -{ - "id": "org.eclipse.che.curl", - "version": "1.0.0", - "name": "Curl", - "description": "Embedded Curl", - "dependencies": [], - "properties": {}, - "servers": {} -} ----- - -As you can see it has the following fields: - -* id - unique value that identifier an installer; -* version - version of the installer; -* name - readable name of the installer; -* description - description of the installer; -* dependencies - declare dependencies to other installers; -* properties - key:value map, where installer is able to store custom specific fields; -* servers - list of servers which will be started by the installer. - -The second item in resources is an installer script. It’s a shell script that will do all required system changes: - -Here is an example of script that installs `Curl` inside a machine: - -[source,shell] ----- -is_current_user_root() { - test "$(id -u)" = 0 -} - -is_current_user_sudoer() { - sudo -n true > /dev/null 2>&1 -} - -set_sudo_command() { - if is_current_user_sudoer && ! is_current_user_root; then SUDO="sudo -E"; else unset SUDO; fi -} - -set_sudo_command -unset PACKAGES - -CURL_INSTALLED=false -command -v curl >/dev/null 2>&1 && CURL_INSTALLED=true - -# no curl, install it -if [ ${CURL_INSTALLED} = false ]; then - PACKAGES=${PACKAGES}" curl"; - CURL_INSTALLED=true -else - echo "Curl is already installed" - exit 0 -fi - -command -v yum >/dev/null 2>&1 && YUM_INSTALLED=true -command -v apt-get >/dev/null 2>&1 && APT_GET_INSTALLED=true -command -v dnf >/dev/null 2>&1 && DNF_INSTALLED=true -command -v zypper >/dev/null 2>&1 && ZYPPER_INSTALLED=true - - -if [ ${YUM_INSTALLED} = false ]; then - ${SUDO} yum install ${PACKAGES}; - -elif [ ${APT_GET_INSTALLED} = false ]; then - ${SUDO} apt-get update; - ${SUDO} apt-get -y install ${PACKAGES}; - -elif [ ${DNF_INSTALLED} = false ]; then - ${SUDO} dnf -y install ${PACKAGES}; - -elif [ ${ZYPPER_INSTALLED} = false ]; then - ${SUDO} zypper install -y ${PACKAGES}; - -else - >&2 echo "Any of Yum, Apt-get, Dnf, Zypper package manager is not available" - exit 1 -fi - -echo "Curl is installed successfully" ----- - -And here is another installer which launches a web server and depends on another installer. Here is content of description json file: - -[source,json] ----- -{ - "id": "org.eclipse.che.tomcat", - "version": "8.5.24", - "name": "Tomcat", - "description": "Embedded tomcat server", - "dependencies": ["org.eclipse.che.curl"], - "properties": {}, - "servers": { - "tomcat": { - "port": "8090/tcp", - "protocol": "http", - "path" : "/" - } - } -} ----- - -This installer needs curl to download tomcat binaries, so it is declared in `dependencies` field. If an installer depends on other installers, then all required installers will be launched automatically even if a user has not configured it. All installers which are defined as `dependencies` will be launched before launching the dependent one. - -Bootstrapper that launches installers tries to connect to all declared servers. No user input is required. Start of a workspace fails if any of servers are not accessible on defined ports during configured timeout. - -Installers servers may conflict, for example, two installers start servers on the same port. Then, infrastructure may want to be able reconfigure servers in its own way. So installer must expect environment variable with port for server launching or launch server on a default port if it is absent. - -The environment variable name has the following format `CHE_SERVER_{NORMALISED_SERVER_NAME}_PORT`. Where `NORMALISED_SERVER_NAME` is a server name in the upper case where all characters which are not Latin letters or digits replaced with `_` symbol. - -Here is an installer script that downloads Tomcat binaries with `Curl`, configures to use free port and launches it. - -[source,bash] ----- -TOMCAT_VERSION=8.5.24 -TOMCAT_BINARIES_URL=http://apache.volia.net/tomcat/tomcat-8/v8.5.24/bin/apache-tomcat-$TOMCAT_VERSION.tar.gz - -TARGET_FOLDER=~/tomcat -mkdir -p $TARGET_FOLDER - -echo "Downloading Tomcat $TOMCAT_VERSION into $TARGET_FOLDER" -curl $TOMCAT_BINARIES_URL | tar xzf - -C ${TARGET_FOLDER} -TOMCAT_FOLDER=$TARGET_FOLDER/apache-tomcat-$TOMCAT_VERSION - -echo "Tomcat $TOMCAT_VERSION is downloaded and unpacked into $TOMCAT_FOLDER" - -DEFAULT_TOMCAT_SERVER_PORT=8090 -TOMCAT_SERVER_PORT=${CHE_SERVER_TOMCAT_PORT:-${DEFAULT_TOMCAT_SERVER_PORT}} - -// configure Tomcat -sed -i "s/port=\"8080\"/port=\"${TOMCAT_SERVER_PORT}\"/g" $TOMCAT_FOLDER/conf/server.xml - -echo "Tomcat $TOMCAT_VERSION is configured to use $TOMCAT_SERVER_PORT port" - -$TOMCAT_FOLDER/bin/catalina.sh run ----- - -An installer can be included into Che assembly or added to particular Che Server via REST API. - -To include an installer into Che assembly, two files are required in Che Server resources: installer description in json format and its script. The files must be named in the following way: `{INSTALLER_ID}.json` for description file and `{INSTALLER_ID}.script.sh` for script file. These files should be placed into `/installers/{INSTALLER_VERSION}` folder. - -Here is an example of maven module structure: - -image::extensibility/installers/curl-installer-module.png[] - -The it is needed to add the corresponding maven module to Workspace Master War archive - -[source,xml] ----- - - - che-assembly-parent - org.eclipse.che - 6.0.X - - assembly-wsmaster-war - war - Che IDE :: Compiling WS Master WAR - - - org.eclipse.che - installer-tomcat - - - org.eclipse.che - installer-tomcat - - - ----- - -Also as it was mentioned an installer can be added via REST API or using Swagger: - -image::extensibility/installers/add-installer-swagger.png[] - diff --git a/src/main/pages/che-6/developer-guide/dao.adoc b/src/main/pages/che-6/developer-guide/dao.adoc deleted file mode 100644 index b1d4681219..0000000000 --- a/src/main/pages/che-6/developer-guide/dao.adoc +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: "DAO" -keywords: framework, overview, master, server, dao, database -tags: [dev-docs] -sidebar: che_6_docs -permalink: che-6/dao.html -redirect_from: dao.html -folder: che-6/developer-guide ---- - - -Data access object (DAO) is an object that provides an interface of persisting objects of some domain in some storage. It provides an API of storing data objects into a database without exposing any details about which database is used or, in general, any specific details about an actual way of persisting data. Eclipse Che persists the following objects: - -* Users, user profile and preferences -* Accounts -* link:what-are-workspaces.html[Workspaces] -* link:factories-getting-started.html[Factories] -* link:stacks.html[Stacks] -* link:permissions.html[Permissions] -* link:installers.html[Installers] -* link:organizations.html[Organizations and members] - -Examples of DAO in Che: - -* https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-user/src/main/java/org/eclipse/che/api/user/server/spi/UserDao.java[User DAO] and an example of its implementation https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-user/src/main/java/org/eclipse/che/api/user/server/jpa/JpaUserDao.java[JpaUserDao] -* https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/spi/WorkspaceDao.java[Workspace DAO] and an example of its implementation https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/jpa/JpaWorkspaceDao.java[JpaWorkspaceDao] -* https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-factory/src/main/java/org/eclipse/che/api/factory/server/spi/FactoryDao.java[Factory DAO] and an example of its implementation https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-factory/src/main/java/org/eclipse/che/api/factory/server/jpa/JpaFactoryDao.java[JpaFactoryDao] - -Eclipse Che uses http://www.h2database.com/html/main.html[H2] for single-user builds and PostgreSQL database in a multi-user flavor. diff --git a/src/main/pages/che-6/developer-guide/databases.adoc b/src/main/pages/che-6/developer-guide/databases.adoc deleted file mode 100644 index 2be37b5ce9..0000000000 --- a/src/main/pages/che-6/developer-guide/databases.adoc +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: "Databases" -keywords: database, -tags: [dev-docs] -sidebar: che_6_docs -permalink: che-6/database.html -redirect_from: database.html -folder: che-6/developer-guide ---- -[id="currently-supported-dbs"] -== Currently Supported Databases -As of version 6.11, Eclipse Che currently supports following databases: - -* H2 (version 1.4.196) -* PostgreSQL (version 9.6) - -H2 database is used by default in Single-User Che, whereas postgresql is used for Multi-User installation. -Both of these have been tested with Selenium Integration tests, as well as TCK integration tests. - -There is also experimental support of the MySQL DB - currently only TCK test are confirmed to be working without any major issues, but the whole product wasn't checked yet. - -It is possible to connect own DB to datasource, and have TCK tests run on it, to ensure that DB can be used with Che's JPA code. - -[id="datasource-components"] -== Datasource components -*JDBC Pool configuration* -Depending on Database used by Che, `JNDIDataSourceFactory` implementation will provide all the required JDBC pool connection configuration. -These properties can be overriden with Che configuration Environment Variables: - -[width="100%",options="header",] -|=== -|Che Environment Variable |JDBC Pool configuration property -|CHE_JDBC_USERNAME |username -|CHE_JDBC_PASSWORD |password -|CHE_JDBC_URL |url -|CHE_JDBC_DRIVER\__CLASS__NAME |driverClassName -|CHE_JDBC_MAX__TOTAL |maxTotal -|CHE_JDBC_MAX__IDLE |maxIdle -|CHE_JDBC_MAX\__WAIT__MILLIS| maxWaitMillis -|=== - -(More about JDBC configuration properties at https://tomcat.apache.org/tomcat-8.5-doc/jndi-datasource-examples-howto.html) - -*ExceptionHandler* -Database may sometimes produce different SQL exception, depending on the vendor. -As in Java code, and TCK it is expected, a custom ExceptionHandler implementaion may be created, that will allow to rethrow more common exception. -For example, in H2 and PostgreSQL, an exception may occur, when data couldn't be updated/stored due to unique constrain violation. -But as it will a vendor specific exception with different code, there are Custom `H2ExceptionHandler`/`PostgreSqlExceptionHandler` that will catch it, and throw instead a `DuplicateKeyException`, which is used across the codebase. - -Exception handler has to be defined in persistence XML. - -[id="test-compatibility-kit"] -== Test Compatibility Kit (TCK) -Test Compatibility kit is a set of integration tests that covers uses of essential DAO components, that are being run against real database. - -List of Che modules that have TCK tests: - -* che-core-api-user -* che-core-api-account -* che-core-api-installer -* che-core-api-ssh -* che-core-api-workspace -* che-core-api-workspace-activity -* infrastructure-kubernetes -* che-multiuser-machine-authentication (Multi-User Che) -* che-multiuser-api-organization (Multi-User Che) -* che-multiuser-api-permission (Multi-User Che) -* che-multiuser-api-resource (Multi-User Che) -* che-multiuser-permission-workspace (Multi-User Che) - -Tests in these modules are executed on H2 Database during the build. -Also, each module packages tests into separate artifacts with `tests` classifier, which are meant to be used for their re-usage in other TCK tests running modules. - -As an example of that, there are `postgresql-tck` and `che-multiuser-postgresql-tck` modules for running TCK tests on Postgres DB. - -[id="cascade-removal-tests"] -== JPA Cascade Removal Tests - -In Eclipse Che database schema, some objects have foreign keys reference on other objects. -Example: Account and workspaces, Permissions and Workspaces. To be able to correctly -remove such objects and avoid referential integrity problems Eclipse Che are using events mechanism. -For example, method in AccountManager that removes account sends a CascadeEvent, and Workspace DAO has a CascadeEventSubscriber that would listen to that event -and remove workspace at that time. In case if removal of workspace failed the whole transaction would be rolled back, because AccountManager method had a `@Transactional` annotation. - -All that functionality is covered by "Cascade Removal Tests", that are located in `cascade-removal` and `che-multiuser-cascade-removal` modules. - -[id="flyway-migration"] -== Flyway migration - -Flyway framework is used to facilitate database schema initialization, as well as perform migrations. -It is configured to pick up scripts and apply them in order, according to versioning. -Some key configuration values are defined in che.properties: - - ----- -db.schema.flyway.baseline.enabled=true # -db.schema.flyway.baseline.version=5.0.0.8.1 # -db.schema.flyway.scripts.prefix= # -db.schema.flyway.scripts.suffix=.sql # -db.schema.flyway.scripts.version_separator=__ # -db.schema.flyway.scripts.locations=classpath:che-schema # ----- - -Che DB Schema artifacts have - -Taking a look at the sample structure: - ----- -che-schema/ - 5.0.0-M1/ - 1__init.sql - 5.0.0-M2 - 1__rename_tables.sql - 2__insert_predefined_data.sql - postgresql/ - 2__insert_predefined_data.sql -subproject-schema/ - 5.0.0-M1/ - 0.1__before_init_main.sql - 1.1__init_subproject.sql - 5.0.0-M2 - 2.1__create_additional_tables.sql ----- - -Location directory -The main root directory for scripts (in this example, `che-schema` and `subproject-schema` is used as location names for Flyway. -There can be multiple locations (artifacts) with scripts, and Flyway can be configured with property to search for such locations in classpath - -db.schema.flyway.scripts.locations=classpath:che-schema,classpath:subproject-schema - -* Version directory* - -There are version directories under the `che-schema` like 5.0.0 or 5.0.0-M1 these directories contain -scripts for specific versions -SQL scripts will be placed under project version directories line 1.init.sql or 1.rename_fields.sql -The naming of scripts is pretty simple: the first digit in the name is a script version in a project versions (it's `1` in `1__init.sql`) -then description of changes (if necessary) init in 1__init.sql and then the file extension .sql in 1__init.sql - -Note, that in this example, as well as in current Che schema, scripts numbers start from 1, but it is possible to use 0. -This can be useful when script has to be run before the first script in superschema. - -*Vendor specific script* - -There is a directory in 5.0.0-M2 called `postresql` if current database provider is posgresql then -the script from 5.0.0-M1/posgresql/2.add_workspace_constraint.sql will be used instead of 5.0.0-M1/2.add_workspace_constraint.sql, so basically if the same script name is provided in provider-specific directory then this script will be used instead - -So, the order of applying scripts be as following -[width="100%",options="header",] -|=== -|db version |script name |location |picked vendor specific -|5.0.0.1.0.1 |0.1__before_init_main.sql |subproject-schema |no -|5.0.0.1.1 |1__init.sql |che-schema |no -|5.0.0.1.1.1 |1.1__init_subproject.sql |subproject-schema |no -|5.0.0.2.1 |1__rename_tables.sql |che-schema |no -|5.0.0.2.2 |2__insert_predefined_data.sql |che-schema |yes -|5.0.0.2.2.1 |2.1__create_new_tables.sql |subproject-schema |no -|=== - -[id="pg-trgm"] -== pg_trgm -Postgres Trigram extension is used for more optimised search of similar string https://www.postgresql.org/docs/9.6/static/pgtrgm.html - -in Che it is used for a faster search for similar email and names, and enabled with a vendor specific migration script: -``` -CREATE EXTENSION IF NOT EXISTS pg_trgm; -CREATE INDEX index_user_lower_email ON usr USING GIN (LOWER(email) gin_trgm_ops); -CREATE INDEX index_user_lower_name ON usr USING GIN (LOWER(name) gin_trgm_ops); -``` - -[id="contributor-guidelines"] -== Contributor guidelines -*Creating a module to run TCK on a custom DB* - -In order to run TCK for a custom database, a maven module should be created with following components: - -- configured `docker-maven-plugin` to run an image with database; -- a Guice module that extends `TckModule` which will be responsible for establishing connection with DataSource, binding all required implementations of JPA entities and repositories; -- a file in src/test/resources/META-INF/services named `org.eclipse.che.commons.test.tck.TckModule`. In it, there must be defined a name of the mentioned TckModule implementaion; -- include all dependency artifacts with TCK tests (see list of Che modules above); -- include artifact with DB Driver; -- include artifact with Che SQL schema. Note, that your database may not be fully compatible with existing Che SQL schema, so you might gonna have to create a separate maven module to add additional vendor specific scripts ( See "Flyway Migration" for the information on how to add such scripts); -- add persistence.xml file or use PersistTestModuleBuilder helper class to create one programmatically in `TckModule` implementation; - -Note, that to contribute the module to Eclipse repository, one must create an Eclipse CQ for Database, its drivers and other possible dependencies. -As these artifacts are used only for building and testing purposes, the type of CQ will be "works with". See https://www.eclipse.org/projects/handbook/#ip-third-party-workswith \ No newline at end of file diff --git a/src/main/pages/che-6/developer-guide/editor.adoc b/src/main/pages/che-6/developer-guide/editor.adoc deleted file mode 100644 index 7736e46911..0000000000 --- a/src/main/pages/che-6/developer-guide/editor.adoc +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "IDE UI: Editor" -keywords: framework, UI, themes, editor, syntax coloring -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/editor.html -redirect_from: editor.html -folder: che-6/developer-guide ---- - diff --git a/src/main/pages/che-6/developer-guide/framework-overview.adoc b/src/main/pages/che-6/developer-guide/framework-overview.adoc deleted file mode 100644 index a3fdd7fd19..0000000000 --- a/src/main/pages/che-6/developer-guide/framework-overview.adoc +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "Extending Che" -keywords: framework, overview, plugin, extension, language support, language server -tags: [extensions, assembly] -sidebar: che_6_docs -permalink: che-6/framework-overview.html -redirect_from: framework-overview.html -folder: che-6/developer-guide ---- - - -[id="introduction"] -== Introduction - -Eclipse Che is a platform that can be extended by: - -* adding client side plugins that bring new menus, panels and other UI components, link:ide-extensions-gwt.html[authored in GWT] -* adding link:server-side-extensions.html[server side components and agents] that get deployed to a workspace machines -* adding support of link:spi_overview.html[new infrastructure] -* enable language tooling via link:language-servers.html[Language Servers] - -On top of that Eclipse Che can be integrated into other platforms since it exposes link:rest-api.html[REST APIs] for all server side components which makes it possible to create on demand workspaces serving needs of CI, support, issue tracking and other systems. diff --git a/src/main/pages/che-6/developer-guide/framework.adoc b/src/main/pages/che-6/developer-guide/framework.adoc deleted file mode 100644 index 0c6a00d698..0000000000 --- a/src/main/pages/che-6/developer-guide/framework.adoc +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Eclipse Che Framework" -keywords: framework, overview, master, server, che server, framework -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/framework.html -redirect_from: framework.html -folder: che-6/developer-guide ---- - diff --git a/src/main/pages/che-6/developer-guide/ide-extensions-gwt.adoc b/src/main/pages/che-6/developer-guide/ide-extensions-gwt.adoc deleted file mode 100644 index 67cb2d48fb..0000000000 --- a/src/main/pages/che-6/developer-guide/ide-extensions-gwt.adoc +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: "IDE Extensions: GWT" -keywords: framework, extensions, gwt, client side -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/ide-extensions-gwt.html -redirect_from: ide-extensions-gwt.html -folder: che-6/developer-guide ---- - - -[id="ide-extension-structure"] -== IDE Extension Structure - -Let’s take a closer look at how an IDE extension should be structured: - ----- -ide -├─ src // sources folder -│ └─ main -│ ├─ java -│ │ └─ org.eclipse.che.plugin.menu.ide -│ │ ├─ ... -│ │ ├─ inject -│ │ │ └─ SampleMenuGinModule.java // GIN module -│ │ └─ SampleMenuExtension.java // IDE extension class -│ ├─ resources -│ │ └─ org.eclipse.che.ide.ext.demo.client -│ └─ module.gwt.xml // template for generating GWT module [1] -├─ target // build output -│ └─ classes -│ ├─ META-INF -│ │ └─ gwt -│ │ └─ mainModule // contains GWT module name [2] -│ └─ org.eclipse.che.plugin.menu -│ ├─ ... -│ └─ SampleMenuExtension.gwt.xml // generated GWT module [3] -└─ pom.xml ----- - -Links: https://tbroyer.github.io/gwt-maven-plugin/generate-module-mojo.html[1] https://tbroyer.github.io/gwt-maven-plugin/generate-module-metadata-mojo.html[2] https://tbroyer.github.io/gwt-maven-plugin/generate-module-mojo.html[3] - -[id="pom.xml"] -== pom.xml - -There are several important parts in the pom.xml of the Che IDE plugin: - -* Packaging of the Maven project is `gwt-lib` which triggers https://tbroyer.github.io/gwt-maven-plugin/lifecycles.html#GWT_Library:_gwt-lib[`gwt-lib`] Maven lifecycle that will build a https://tbroyer.github.io/gwt-maven-plugin/artifact-handlers.html#GWT_Library:_gwt-lib[GWT library]: -+ -[source,xml] ----- -gwt-lib ----- -* Dependency on the Che IDE API library that provides a https://docs.google.com/spreadsheets/d/1ijapDnl1G7svy7sIKgTntyTuVsnd9nFcH0-357C0MxE/edit#gid=0[set of APIs] for extending Che IDE: -+ -[source,xml] ----- - - org.eclipse.che.core - che-core-ide-api - ----- -* Name of the GWT module is defined in the configuration of `gwt-maven-plugin`: -+ -[source,xml] ----- - - net.ltgt.gwt.maven - gwt-maven-plugin - true - - org.eclipse.che.plugin.menu.SampleMenuExtension - - ----- -+ -For details on the generating GWT module, read the `gwt:generate-module` https://tbroyer.github.io/gwt-maven-plugin/generate-module-mojo.html[mojo description]. GWT library is a JAR that contains compiled classes, project’s (re-)sources, GWT module descriptor (`*.gwt.xml`) and possibly other GWT-specific files. - -[id="gwt.xml"] -== gwt.xml - -Project’s `*.gwt.xml` file is generated within the `gwt-lib` Maven lifecycle and contains: - -* the declarations for the default source folders: -+ -[source,xml] ----- - - - ----- -* `` directives for the project’s _direct_ dependencies which were packaged as a `gwt-lib`. - -_Optional_ template may be provided in `src/main/module.gwt.xml` for generating project’s `*.gwt.xml` file. - -The most common cases when you may require a template: - -* need to override the default source folders, like https://github.com/eclipse/che/blob/f15fbf1cb1248d18acc3ee6fdc41766946ea4a3b/plugins/plugin-java/che-plugin-java-ext-lang-client/src/main/module.gwt.xml#L18[here]; -* need to add `` directive for a GWT lib that isn’t packaged as a `gwt-lib` artifact (doesn’t contain GWT-specific meta information). - -[id="consuming-shared-libs"] -== Consuming Shared Libs - -The shared libraries don’t require any GWT-specific files or configuration in pom.xml to be consumed by a GWT library. - -To use shared code in a GWT library: - -* declare a dependency on the "normal" artifact (JAR with compiled classes); -* declare a dependency on the "sources" artifact (with `sources`). - -See an example https://github.com/eclipse/che/blob/19f5fd1f5ae8f165b7306e71cb0d58c2082fafab/plugins/plugin-python/che-plugin-python-lang-ide/pom.xml#L49-L57[here]. - -[id="ide-extension-class"] -== IDE extension class - -Che IDE plugin has an entry point - Java class annotated with an https://github.com/eclipse/che/blob/master/ide/che-core-ide-api/src/main/java/org/eclipse/che/ide/api/extension/Extension.java[`@org.eclipse.che.ide.api.extension.Extension`] annotation. Plugin entry point is called immediately after initializing the core part of the Che IDE. - -Here’s an entry point of the plugin that will add a new top level menu group using link:actions.html[IDE actions]: - -[source,java] ----- -package org.eclipse.che.plugin.menu.ide; - -import static org.eclipse.che.ide.api.action.IdeActions.GROUP_HELP; -import static org.eclipse.che.ide.api.action.IdeActions.GROUP_MAIN_MENU; -import static org.eclipse.che.ide.api.constraints.Anchor.AFTER; - -import com.google.inject.Inject; -import org.eclipse.che.ide.api.action.ActionManager; -import org.eclipse.che.ide.api.action.DefaultActionGroup; -import org.eclipse.che.ide.api.constraints.Constraints; -import org.eclipse.che.ide.api.extension.Extension; -import org.eclipse.che.plugin.menu.ide.action.SampleAction; - -@Extension(title = "Sample Menu") -public class SampleMenuExtension { - - private static final String SAMPLE_GROUP_MAIN_MENU = "Sample"; - - @Inject - private void prepareActions(SampleAction sampleAction, ActionManager actionManager) { - - DefaultActionGroup mainMenu = (DefaultActionGroup) actionManager.getAction(GROUP_MAIN_MENU); - - DefaultActionGroup sampleGroup = - new DefaultActionGroup(SAMPLE_GROUP_MAIN_MENU, true, actionManager); - actionManager.registerAction("sampleGroup", sampleGroup); - mainMenu.add(sampleGroup, new Constraints(AFTER, GROUP_HELP)); - - actionManager.registerAction("sayHello", sampleAction); - sampleGroup.add(sampleAction, Constraints.FIRST); - } -} ----- - -[id="dependency-injection"] -== Dependency Injection - -Che IDE use https://code.google.com/archive/p/google-gin/[Google GIN] for dependency injection. Che IDE plugin can provide a GIN module. In order to be picked-up by IDE, plugin’s GIN module should be annotated with an https://github.com/eclipse/che/blob/master/ide/che-core-ide-api/src/main/java/org/eclipse/che/ide/api/extension/ExtensionGinModule.java[`@org.eclipse.che.ide.api.extension.ExtensionGinModule`] annotation. - -Here’s a GIN module of the plugin: - -[source,java] ----- -package org.eclipse.che.plugin.menu.ide.inject; - -import com.google.gwt.inject.client.AbstractGinModule; -import org.eclipse.che.ide.api.extension.ExtensionGinModule; - -@ExtensionGinModule -public class SampleMenuGinModule extends AbstractGinModule { - - @Override - protected void configure() {} -} ----- - -In this example an extension GIN module isn’t really necessary since the plugin does not really need to put anything in a container. Read more about link:guice.html[dependency injection] and take a look at https://github.com/eclipse/che/blob/master/plugins/plugin-csharp/che-plugin-csharp-lang-ide/src/main/java/org/eclipse/che/plugin/csharp/ide/inject/CSharpGinModule.java[example Gin modules]. - -[id="extension-points"] -== Extension Points - -You can provide or customize existing link:actions.html[actions], link:parts.html[parts], link:themes.html[themes] and link:editor.html[editor]. This example has registered a new action. - -[id="debugging-with-super-devmode"] -== Debugging With Super DevMode - -There are two options available to launch GWT Super DevMode, depending on the state of the Che sources: whether it’s built or not since a lot of sources are generated during the Maven build. - -* Case 1: Che sources have been already built. Use the following command: - -`mvn gwt:codeserver -pl :che-ide-gwt-app -am -Dmaven.main.skip -Dmaven.resources.skip -Dche.dto.skip -Dskip-enforce -Dskip-validate-sources` - -* Case 2: Che sources haven’t been built, e.g. freshly cloned or after executing `mvn clean` or you just don’t need to build the whole project. Use the following command: - -`mvn gwt:codeserver -pl :che-ide-gwt-app -am -Dskip-enforce -Dskip-validate-sources` - -The second one requires _more time_ to launch GWT CodeServer since it executes `process-classes` build phase for each maven module. Thus, using the first command is preferable. - -*Note*, both commands have to be performed in the root folder of the Che project. - -Once codeserver is started, open the prompted URL, drag bookmarks on your bookmarks bar. Note that you may face the error saying there are no GWT modules on the page. It happens because the IDE is opened in an iframe. Just, cut `dashboard/#/ide/` from the URL. To debug client side code, follow instructions from link:che-in-che-quickstart.html#develop-and-debug-client-side[quickstart]. - -[id="run-in-che"] -== Run in Che - -Once your extension is ready, you can build, run and debug it in link:che-in-che-quickstart.html[Che itself]. Just use an existing sample and add a custom plugin with its dependencies. - -[id="add-to-a-custom-assembly"] -== Add to a Custom Assembly - -You can build your custom link:assemblies.html[Che assembly] outside Che and/or use any IDE to develop extensions. Once done, run `mvn clean install` in the root of the assembly to get a Tomcat bundle that is ready to be run either in link:docker-config.html#development-mode[Docker] or deployed to link:openshift-config.html#development-mode[OpenShift]. diff --git a/src/main/pages/che-6/developer-guide/language-servers.adoc b/src/main/pages/che-6/developer-guide/language-servers.adoc deleted file mode 100644 index a454c57679..0000000000 --- a/src/main/pages/che-6/developer-guide/language-servers.adoc +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: "Language Support" -keywords: framework, language servers, code assistant, language support, code completion, error marking -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/language-servers.html -redirect_from: language-servers.html -folder: che-6/developer-guide ---- - - -[id="overview"] -== Overview - -The Language Server Protocol is used between a tool (the client) and a language intelligence provider (the server) to integrate features like auto complete, goto definition, find references, etc. - -You can learn more about the language server specification on the https://github.com/Microsoft/language-server-protocol[LSP GitHub page]. - -Currently Eclipse Che implements the https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md[3.x protocol version]. - -Note that, Eclipse Che also implements the snippet syntax used in VSCode. It is not versioned in the LSP specification, but the supported syntax is described https://github.com/Microsoft/vscode/blob/0ebd01213a65231f0af8187acaf264243629e4dc/src/vs/editor/contrib/snippet/browser/snippet.md[here]. - -[id="adding-support-for-new-languages"] -== Adding Support for New Languages - -There are two approaches to add a new language server: - -* via installer and launcher: this way a language server runs in the machine where the respective installer has been enabled -* adding link:#ls-sidecars[language server as a sidecar] in workspace configuration - multi-machine recipe + server with required attributes - -[id="general-concept"] -== General Concept - -Language server integration is divided into 2 steps: an install followed by a separately triggered start. Language servers aren’t started when the agent starts. Instead they are started in a second step which can be triggered at any time. This is done to reduce resource consumption and reduce workspace startup time. - -1. The language server agent is launched when the workspace starts - its job is to install all dependencies and prepare the `bash` launcher file that will be used to start the language server. -2. The https://github.com/eclipse/che/blob/master/wsagent/che-core-api-languageserver/src/main/java/org/eclipse/che/api/languageserver/launcher/LanguageServerLauncher.java[launcher] is triggered and starts the language server. We suggest triggering the launcher when the user begins interacting with file types related to the language server. Once launched, the language server is registered with specific file types (covered in more detail below). - -[id="adding-a-language-server-installer"] -== Adding a Language Server Installer - -Follow the documentation on how to link:custom-installers.html[add new installer]. - -Examples of existed language server agents you can learn from: - -* https://github.com/eclipse/che/tree/master/agents/ls-json[JSON] -* https://github.com/eclipse/che/tree/master/agents/ls-php[PHP] -* https://github.com/eclipse/che/tree/master/agents/ls-python[Python] -* https://github.com/eclipse/che/tree/master/agents/ls-csharp[C#] -* https://github.com/eclipse/che/tree/master/agents/ls-typescript[TypeScript] - -[id="adding-a-language-server-config"] -== Adding a Language Server Config - -In order to start/initialize a language server for the desired language, you need to implement https://github.com/eclipse/che/blob/master/wsagent/che-core-api-languageserver/src/main/java/org/eclipse/che/api/languageserver/LanguageServerConfig.java[LanguageServerConfig interface] which pretty much defines what needs to be accomplished to start a 'local' language server. - -Here is how a typical LanguageServerConfig looks like: https://github.com/eclipse/che/blob/master/plugins/plugin-clangd/che-plugin-clangd-lang-server/src/main/java/org/eclipse/plugin/clangd/languageserver/ClangDLanguageServerConfig.java[Clangd]. - -Things to pay attention to: - -* *REGEX* defines regexp for desired files. It can be a path, all fines with certain extension or particular file names etc. -* *launchScript* is usually created by an installer script and contains command(s) to launch a language server in a stdio mode -* *LANGUAGE_ID* is defined in a guice module. See: https://github.com/eclipse/che/blob/master/plugins/plugin-clangd/che-plugin-clangd-lang-server/src/main/java/org/eclipse/plugin/clangd/inject/ClangModule.java[ClangdModule] -* add binding in https://github.com/eclipse/che/blob/master/plugins/plugin-clangd/che-plugin-clangd-lang-server/src/main/java/org/eclipse/plugin/clangd/inject/ClangModule.java#L37[guice module] - -Installers are packaged into wsmaster, so you will need to add required dependencies there. LanguageServerConfigs are usually part of plugins packages with a workspace agent. - -[id="ls-sidecars"] -== LS-Sidecars - -While the above approach works well for custom assemblies, i.e. you actually need to rebuild Che with a custom plugin that registers a new installer and a language server launcher, there is a mechanism to launch Language Servers in parallel containers/sidecars. This is what you need to do to add a new language server to your workspace as a sidecar. - -* Build a Docker image in which language server is started in `ENTRYPOINT` or `CMD`. Note that some language servers support `tcp` arguments in their start syntax. Make sure that the language server acts like a server, rather than attempts to bind to a socket. The best way to check it is to run the image: `docker run -ti ${image}`. If the container starts, everything is fine, and if it exits immediately, you need to fix it. - -We recommend running language servers in `stdio` mode and use sockat as a proxy. Here’s an example of a Dockerfile that builds an image with TyperScript language server: - ----- -# inherit an image with node.js and npm - runtime requirements for TypeScript LS -FROM eclipse/node - -# install socat -RUN sudo apt-get install socat -y && \ - sudo npm install -g typescript@2.5.3 typescript-language-server@0.1.4 - -# run socat that listens on port 4417 with exec command that starts LS -CMD socat TCP4-LISTEN:4417,reuseaddr,fork EXEC:"typescript-language-server --stdio" ----- - -* Create a stack with a link:creating-starting-workspaces.html[custom recipe]: Create Workspace > Add Stack: - -[source,yaml] ----- -services: - typescript-ls-machine: - image: ls/image - mem_limit: 1073741824 - dev-machine: - image: eclipse/ubuntu_jdk8 - mem_limit: 2147483648 - depends_on: - - typescript-ls-machine ----- - -* In User Dashboard, go to *Workspaces > Your Workspace > Config*, and add a server for typescript-ls-machine in `servers:[]` - -[source,json] ----- -"servers": { - "ls": { - "attributes": { - "id": "go-ls", - "internal": "true", - "type": "ls", - "languageRegexes": "[ {\"languageId\":\"golang\", \"regex\":\".*\\\\.go$\"}]", - }, - "protocol": "tcp", - "port": "4417" - } -} ----- - -* *ls* - server name - can be any string -* *attributes.id* - can be any unique identifier -* *attributes.internal* - `true`. Mandatory! Used to get an internal link to server -* *attributes.type* - `ls`. Mandatory. Used by the IDE client to identify a server as a language server -* *languageRegexes.languageId* - language identifier, either one of those supported in https://microsoft.github.io/language-server-protocol/specification#textdocumentitem[LSP specification] or own. -* *languageRegexes.regex* - regexp expression to match either extension or file name + extension, or whatever match you need (for example, path, say, initialize language server only for config/config.xml files). Pay attention to regexp syntax since errors are not validated by server, and bad regexp will result in the client ignoring your files. -* In User Dashboard, go to Workspaces > Your Workspace > Volumes, add a volume for *each machine*. The two volumes have to share the same name (for example, `projects`) and path `/projects` so that they actually share one volume. This way a language server container has access to workspace project types. - -image::extensibility/lang_servers/volumes_ls.png[] - -* Start a workspace. Open a file with one of the extensions bound to a language ID. Che client will attempt to connect to language server over tcp socket. This data is retrieved from workspace runtime. Language server process should be available at the port declared in the server. You can either use Socat or launch a language server in tcp mode if it supports it. It is your Docker image’s responsibility to launch the language server. Adding `ENTRYPOINT` or `CMD` instruction should work well. - -See: https://gist.githubusercontent.com/eivantsov/4e86b4d51cf23fbd8fd68410170f06e3/raw/e9c1edc600d0ff82e15d2d68d2ac5c6304a981b9/go-workspace.json[Sample configuration] of a workspace featuring 2 machines, one of which is a language server machine. diff --git a/src/main/pages/che-6/developer-guide/logging.adoc b/src/main/pages/che-6/developer-guide/logging.adoc deleted file mode 100644 index 0f34bf5cb5..0000000000 --- a/src/main/pages/che-6/developer-guide/logging.adoc +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Che logging -sidebar: che_6_docs -keywords: dev docs -tags: [extensions, assembly, logging, log, logs] -permalink: che-6/logging.html -redirect_from: logging.html -folder: che-6/developer-guide ---- - - -[id="logging-in-che"] -== Logging in Che - -By default ws-master and ws-agent are configured to use logback as default logging backend. Their configuration produces plaintext logs to output of Che assembly and stores it to files. There are several options on how to customize logs producing in Che. Che is bundled with 2 variants of logger format and location settings `json` and `plaintext`. + -JSON setting produces logs in JSON stream format and doesn’t store them in any files. + -Plaintext setting produces logs in the format of plain text and stores it in directory Che logs dir. + -To switch these encodings set environment variable `CHE_LOGS_APPENDERS_IMPL` to `json` or `plaintext`. Value `plaintext` is default setting. - -To add a custom implementation of logger producing create link:assemblies.html[custom assembly], set environment variable `CHE_LOGS_APPENDERS_IMPL=myimpl` and add files `logback-file-myimpl-appenders.xml` and `tomcat-file-myimpl-appenders.xml` to `tomcat/conf` folder. + -An example of these files which adds storing logs in JSON format in files: + -logback-file-json-appenders.xml - -[source,xml] ----- - - - - ${che.logs.dir}/logs/catalina.log.json - - info - - - ${che.logs.dir}/archive/%d{yyyy/MM/dd}/catalina.log.json - ${max.retention.days} - - - identity_id - req_id - - - - - - - ----- - -tomcat-file-json-appenders.xml - -[source,xml] ----- - - - - ${che.logs.dir}/logs/catalina.log.json - - info - - - ${che.logs.dir}/archive/%d{yyyy/MM/dd}/catalina.log.json - ${max.retention.days} - - - identity_id - req_id - - - - - - - ----- - -Other `logback-logstash-encoder` appenders can be added as well. See https://github.com/logstash/logstash-logback-encoder#usage. + -Note that to change logging settings for workspace environment variable should be set in workspaces and assembly of ws-agent should be extended in addition to the same actions for Che master. + -On the other hand, customizing of ws-agent logs is uncommon practise, so it can be avoided. - -Also, there are two ways to extend chosen configuration. 1. Put your configuration in `${che.local.conf.dir}/logback/logback-additional-appenders.xml` or `${catalina.home}/conf/logback-additional-appenders.xml` file 2. Provide environment variable in such form - ----- -CHE_LOGGER_CONFIG=logger1=logger1_level,logger2=logger2_level ----- - -for example - ----- -CHE_LOGGER_CONFIG=org.eclipse.che=DEBUG,org.eclipse.che.api.installer.server.impl.LocalInstallerRegistry=OFF ----- - -Che Server also has an option to view and edit logger configuration during runtime through following REST services: - -[cols=",,",options="header",] -|=== -|GET | `logger/ -` | get list of all loggers -|GET | `logger/{name}` | get info about particular logger -|POST | `logger/{name}` | update logger configuration -|PUT | `logger/{name}` | create logger configuration -|=== - -For example, sending PUT request with following configuration - -``` -{ - "name" : "org.eclipse.che.api.workspace.activity" - "level" : "DEBUG" -} -``` - -will add logger level configuration that will set DEBUG level for loggers in `org.eclipse.che.api.workspace.activity` package diff --git a/src/main/pages/che-6/developer-guide/parts.adoc b/src/main/pages/che-6/developer-guide/parts.adoc deleted file mode 100644 index ae55a4066d..0000000000 --- a/src/main/pages/che-6/developer-guide/parts.adoc +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: "IDE UI: Parts" -keywords: framework, UI, parts -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/parts.html -redirect_from: parts.html -folder: che-6/developer-guide ---- - - -Parts represent the content of the Che workbench, i.e. views and editors within the IDE. Che already provides various parts such as the project explorer, the output console, the build result view, file outline and the code editor. In this part of the tutorial, we describe how to implement a custom view and embed it into the Che IDE. Furthermore, we demonstrate how to open and hide views. - -Sample plugins: https://github.com/che-samples/che-plugin-menu[IDE] and https://github.com/che-samples/che-ide-server-extension[IDE-Server Side]. - -[id="create-a-custom-part"] -== Create a custom Part - -Creating a part in Che consists of two four components, which are marked in grey in the diagram below. In this section, we provide a general overview, in the following sections, we describe the concrete implementation more in detail. - -The central component is the implementation of the view itself (`MyViewImpl`). It will create all the UI widgets, which are shown within a part. `MyViewImpl` inherits from `BaseView`, a base implementation of common functionality for all views provided by Che. If the view needs to be accessed by other components, e.g. to set a selection, public methods should be extracted to an interface (`MyView`). To allow other components to get an instance of `MyView`, the interface is bound to the implementation within `MyGinModule`. See the section link:guice.html[Dependency Injection Basics] for more details about this. As mentioned before, the view implementation is responsible for the content of a view. The integration into the Che IDE, including configuring the tab (title, icon, etc.) is done by a part presenter (`MyPartPresenter`), which inherits from `BasePresenter`. Part presenter are called by Che or a custom action to interact with a part, e.g. to open it or to fill it with content. The part presenter forwards relevant calls to the implementation of a view (encapsulated by the interface). - -image::devel/parts.png[] - -In the following sections, we describe the implementation of the mentioned components more in detail. As an example, we create a part displaying "Hello World" and define an action to open it. - -[id="implementing-a-view"] -== Implementing a View - -In this section, we describe the implementation of a simple "Hello World" view. The implementation is shown in the following listing. All views in Che inherit from `org.eclipse.che.ide.api.parts.base.BaseView`, which implements basic features for views embedded into the Che IDE. The super constructor requires the `PartStackUIResources` which we get injected as a parameter. Views in Che are implemented using GWT. Therefore, we can use any GWT widgets or framework capabilities to actually implement the views. In the following example, we simply create a label and set its text. To implement more complex views and use other GWT features, such as describing the UI using XML, please refer to the http://www.gwtproject.org/[GWT project page]. - -In the last line of the example, we call the method `#setContenWidget` of the base class to specifiy the root widget to be shown in the view. In our case, this is the `Label`, if you create a more complex layout of widgets, this would be the root container of the view. - -[source,java] ----- -package org.eclipse.che.plugin.parts.ide.helloworldview; - -import com.google.gwt.usder.client.ui.Label; -import com.google.inject.Inject; -import com.google.inject.Singleton; -import org.eclipse.che.ide.api.parts.PartStackUIResources; -import org.eclipse.che.ide.api.parts.base.BaseView; - -public class HelloWorldViewImpl extends BaseView implements HelloWorldView { - - @Inject - public HelloWorldViewImpl(PartStackUIResources resources){ - super(resources); - Label label = new Label("Hello World"); - setContentWidget(label); - } - -} ----- - -As mentioned in the introduction of this section, an explicit interface should defined, when implementing a view, encapsulating all interaction with other components (see following listing). Therefore, the interface contains all methods, which shall be accessible by other components. In the following example, the interface defines a method `#setVisible` to allow controlling the visibility of the view. This method is already implemented by `BaseView` so we do not need to implement it in `HelloWorldViewImpl`. If you need to provide any other methods for a view, e.g. to pass in some input parameters to be shown, you should extend the view interface accordingly. - -Following the GWT pattern, the view interface also defines an `ActionDelegate`. This interface can be implemented by components, which want to listen to events triggered with the view, e.g. a button click. Our `HelloWorldView`is currently not triggering any actions, so the interface is empty. - -[source,java] ----- -package org.eclipse.che.plugin.parts.ide.helloworldview; - -import org.eclipse.che.ide.api.mvp.View; -import org.eclipse.che.ide.api.parts.base.BaseActionDelegate; - -public interface HelloWorldView extends View { - - - void setVisible(boolean visible); - - interface ActionDelegate extends BaseActionDelegate { - - } -} ----- - -Finally, we have to make our view available for other components, using dependency injection. This is done in `MyGinModule`, which can contain other bindings, too. Please see the section link:guice.html[Dependency Injection Basics] for more details about this binding. - -[source,java] ----- -package org.eclipse.che.plugin.parts.ide.inject; - -import com.google.gwt.inject.client.AbstractGinModule; -import org.eclipse.che.ide.api.extension.ExtensionGinModule; -import org.eclipse.che.plugin.parts.ide.helloworldview.HelloWorldView; -import org.eclipse.che.plugin.parts.ide.helloworldview.HelloWorldViewImpl; - -@ExtensionGinModule -public class MyGinModule extends AbstractGinModule { - - @Override - protected void configure() { - bind(HelloWorldView.class).to(HelloWorldViewImpl.class); - } - -} ----- - -[id="implementing-a-part-presenter"] -== Implementing a Part Presenter - -To connect the view implementation to the Che workbench, we need to implement a part presenter. It defines, how a view is embedded into Che (e.g. a title and an icon). Furthermore, it handles all interactions with the view. This goes in both directions. As a first example, if you want to hide a view, you will call the presenter. As a second example, if you click a button within a view, which should trigger something in Che, the presenter will receive this event and trigger the specified action. - -The following listing shows the `HelloWorldPresenter` for the previous example view. It retrieves the `HelloWorld`view using dependency injection in its constructor. The following methods define, how the view is presented as a tab in Che: a title, an icon and a tooltip. The method `#setVisible` delegates to the view itself. The method `#go` is called, when a view is opened. As a parameter, it receives a callback, which expects a view implementation to be set. With this call, the view implementation is wired to the Che workbench. - -[source,java] ----- -package org.eclipse.che.plugin.parts.ide.helloworldview; -import com.google.gwt.user.client.ui.AcceptsOneWidget; -import com.google.gwt.user.client.ui.IsWidget; -import com.google.inject.Inject; -import org.eclipse.che.ide.api.parts.base.BasePresenter; -import org.eclipse.che.plugin.parts.ide.SamplePartsResources; -import org.vectomatic.dom.svg.ui.SVGResource; - -/** - * Presenter for the sample Hello World View. - */ -@Singelton -public class HelloWorldPresenter extends BasePresenter { - - private HelloWorldView view; - - @Inject - public HelloWorldPresenter(HelloWorldView view){ - this.view = view; - } - - @Override - public String getTitle() { - return "Hello World View"; - } - - @Override - public SVGResource getTitleImage() { - return (SamplePartsResources.INSTANCE.icon()); - } - - @Override - public String getTitleToolTip() { - return "Hello World Tooltip"; - } - - @Override - public IsWidget getView() { - return view; - } - - @Override - public void setVisible(boolean visible) { - view.setVisible(visible); - } - - @Override - public void go(AcceptsOneWidget container) { - container.setWidget(view); - } -} ----- - -[id="interacting-from-within-a-view"] -== Interacting from within a view - -To trigger any behavior from with views, the `ActionDelegate` is used as a receiver of events following the GWT MVP pattern. Therefore, you extend the interface by the required methods, in the following listing a method `#onButtonClicked`. - -[source,java] ----- -/** Required for delegating functions in view. */ -public interface ActionDelegate extends BaseActionDelegate { - /** Performs some actions in response to a user's clicking on Button */ - void onButtonClicked(); -} ----- - -The `ActionDelegate` interface has to be implemented and provided to the view. For a part, the part presenter is a good component to do both, especially, if the relevant operations to be triggered are related to the Che workbench or to Che services. Therefore, the part presenter implements the interface `MyView.ActionDelegate`, implements the defined method and sets itself as a delegate (see listing below). - -[source,java] ----- -@Singelton -public class MyPartPresenter extends BasePresenter implements MyView.ActionDelegate { - - private MyView view; - - @Inject - public MyPartPresenter(MyView view){ - this.view = view; - view.setDelegate(this); - } - - public void onButtonClicked(){ - //Do sth. - } ----- - -Finally, the action delegate can be called from within the view implementation, as shown below. - -[source,java] ----- -public class MyViewImpl extends BaseView implements MyView { - -/... - -public void onButtonClicked(ClickEvent event) { - delegate.onButtonClicked(); -} ----- - -[id="opening-parts"] -== Opening Parts - -To open parts, the service `WorkspaceAgent` is used. It provides a method `#openPart` which accepts two parameters: - -* The part presenter of the part to be opened -* The location, where the part is to be opened - -The following locations are supported by Che: - -* `EDITING`: area just above the editor, like a file tab -* `NAVIGATION`: area on the left to project explorer -* `TOOLING`: area to the right of the editor -* `INFORMATION`: area under the editor, 'console' area - -After a pat has been opened, it must be activated to ensure that it gets visible and receives the focus. This is done using `WorkspaceAgent#setActivePart`. The following code example shows an action, which opens the "Hello World" part defined before. Please see the section link:actions.html[Actions] for more details about the implementation of actions. - -[source,java] ----- -package org.eclipse.che.plugin.parts.ide.helloworldview; - -import com.google.inject.Inject; -import com.google.inject.Singleton; -import org.eclipse.che.ide.api.action.Action; -import org.eclipse.che.ide.api.action.ActionEvent; -import org.eclipse.che.ide.api.parts.PartStackType; -import org.eclipse.che.ide.api.parts.WorkspaceAgent; - -/** - * Action for showing a the Hello World View. - */ -@Singleton -public class HelloWorldViewAction extends Action { - - private WorkspaceAgent workspaceAgent; - private HelloWorldPresenter helloWorldPresenter; - - /** - * Constructor. - * - */ - @Inject - public HelloWorldViewAction(WorkspaceAgent workspaceAgent, HelloWorldPresenter helloWorldPresenter) { - super("Show Hello World View"); - this.workspaceAgent = workspaceAgent; - this.helloWorldPresenter = helloWorldPresenter; - } - - - @Override - public void actionPerformed(ActionEvent e) { - workspaceAgent.openPart(helloWorldPresenter, PartStackType.INFORMATION); - workspaceAgent.setActivePart(helloWorldPresenter); - } -} ----- diff --git a/src/main/pages/che-6/developer-guide/project-types.adoc b/src/main/pages/che-6/developer-guide/project-types.adoc deleted file mode 100644 index 20cca016d1..0000000000 --- a/src/main/pages/che-6/developer-guide/project-types.adoc +++ /dev/null @@ -1,371 +0,0 @@ ---- -title: "Project Types" -keywords: framework, overview, framework, project, project type, API -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/project-types.html -redirect_from: project-types.html -folder: che-6/developer-guide ---- - - -Project types allow you to provide custom project behavior for a certain language. Additionally, they allow you to specify specific project templates, which can be instantiated and already contain language specific content. Further, they allow the user to specify language specific properties for a project, e.g. compiler settings or dependencies. Finally, specific actions, e.g. in the context menu, can be associated with a project type. - -In this part of the tutorial, we describe how to define a custom project type, how to provide a custom creation wizard, and how to add project-specific actions. - -Sample assembly with https://github.com/che-samples/che-plugin-json[plugin JSON]. There’s also https://github.com/che-samples/che-plugin-wizard[another sample plugin] that registers a custom project type and adds it to project creation wizard. - -[id="custom-project-type"] -== Custom Project Type - -In this part of the tutorial, we describe how to define a new custom project type including a project initialization (e.g. to add default content). The following diagram shows all components of a project type registration. The classes highlighted in dark grey are to be implemented for the extension. - -image::devel/ProjectType.png[] - -The custom `ProjectTypeDef` implementation defines the actual project type. Therefore, it defines an ID, a name and some configuration options. As the ID is referenced from other classes, it is retrieved from a shared constant class `MyConstants`. - -A custom `ProjectCreateHandler` is responsible for creating a new project of the custom type. As an example, it can create some default files on project creation. `ProjectCreateHandler` is a subtype of ProjectHandler, other sub types, e.g. `PostImportProjectHandler` and `ProjectInitHandler` provide further hooks to configure projects. - -Both, the custom `ProjectTypeDef` as well as the custom `ProjectCreateHandler` are bound by a `GuiceModule` to make them available for the Che Framework. Please note that all these components are part of a server plugin. Necessary adaptations within the IDE, e.g. the extension of the "New" menu are done automatically by Che. - -As an example, we will describe in the following how to add a simple project type for managing JSON files, although in a real use case JSON files are usually embedded into other projects (e.g. a JavaScript project). We will also add a default initialization to the project type, which already creates a new JSON file in any created project. - -As a first step, we implement a custom subclass of `ProjectTypeDef` (see code example below). Its constructor calls the default super constructor to define the ID and the name for the custom project type. - -Further, it uses the remaining three boolean parameters to specify: - -`primary=true`:: The project can be a top-level project, meaning that it can be created on the root level of a workspace. -`mixin=false`:: The project cannot be embedded into other projects (as sub-projects). - -After specifying the project, we add a constant and a variable definition to the project type. Constants can not be changed once they are defined and therefore contain static information about the project type. In our example, we add the information that the project language is JSON. The first parameter specifies a key, the second a description of the constant, and the third the corresponding value. - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-server/src/main/java/it/pkg/projecttype/JsonExampleProjectType.java[JsonExampleProjectType.java]: - -[source,java] ----- -public class JsonExampleProjectType extends ProjectTypeDef { - - @Inject - public JsonExampleProjectType() { - super(JSON_EXAMPLE_PROJECT_TYPE_ID, "JSON Example", true, false); - addConstantDefinition(LANGUAGE, LANGUAGE, JSON_EXAMPLE_PROJECT_TYPE_ID); - addVariableDefinition("json-schema-ref", "Referenced base schema", /*required*/ true); - } -} ----- - -Variables can be changed, e.g. to store values that the user enters on project creation. In the example, we define a custom variable to store a reference to a JSON schema. We will allow the user to set this variable in a custom project wizard in the corresponding part of this tutorial. You can define your own variables to store project specific properties. All String constants of the following code example are defined in a shared constant class, which is listed below. - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-shared/src/main/java/it/pkg/shared/Constants.java[Constants.java]: - -[source,java] ----- -public final class Constants { - - /** - * Language attribute name. - */ - public static final String LANGUAGE = "language"; - - /** - * Language attribute value. - */ - public static final String JSON_EXAMPLE_LANG = "json"; - - /** - * JSON Example Project Type ID. - */ - public static final String JSON_EXAMPLE_PROJECT_TYPE_ID = "json-example"; - - /** - * JSON Example Category. - */ - public static final String JSON_EXAMPLE_CATEGORY = "JSON Example"; - - /** - * JSON Schema reference attribute name. - */ - public static final String JSON_EXAMPLE_SCHEMA_REF_ATTRIBUTE = "json-schem-ref"; - - private Constants() { - - } -} ----- - -To make our new project type available in Che, we need to register it using Guice. The following example code registers the `JsonExampleProjectType` from above as a `ProjectTypeDef`. Che will automatically pick up all bound `ProjectTypeDefs`. Please see our link:guice.html[Dependency Injection Basics] section for a general introduction of this mechanism. - -[source,java] ----- -org.eclipse.che.plugin.jsonexample.inject.JsonExampleGuiceModule -@DynaModule -public class JsonExampleGuiceModule extends AbstractModule { - - @Override - protected void configure() { - Multibinder projectTypeDefMultibinder = newSetBinder(binder(), - ProjectTypeDef.class); - projectTypeDefMultibinder.addBinding().to(JsonExampleProjectType.class); - } -} ----- - -By defining the new project type, Che will add a new entry in the "New" menu of the IDE and allow us to create a new and empty project: - -image::devel/wizard.png[] - -Typical project types often need to be initialized with some default content, e.g. some files. This can be done by implementing a `CreateProjectHandler` (subtype of `ProjectHandler`). In the method `#onProjectCreate`, you can access the base folder, as well as the attributes and options of the project. - -In the following example, we will create the following files: a "person.json" file with some default content that will be stored in a folder named "myJsonFiles" as well as a "package.json" file, which we’ll need later on. The method `#getProjectType` needs to provide the project type ID to allow Che to map the `ProjectHandler` to the correct type. - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-server/src/main/java/it/pkg/inject/JsonExampleGuiceModule.java[JsonExampleGuiceModule.java]: - -[source,java] ----- -public class JsonExampleCreateProjectHandler implements CreateProjectHandler { - - private static final String FILE_NAME = "package.json"; - - @Override - public void onCreateProject(FolderEntry baseFolder, - Map attributes, - Map options) throws /.../ - { - InputStream packageJson = null; - InputStream personJson = null; - try { - FolderEntry myJsonFiles = baseFolder.createFolder("myJsonFiles"); - packageJson = getClass().getClassLoader() - .getResourceAsStream("files/default_package"); - personJson = getClass().getClassLoader() - .getResourceAsStream("files/default_person"); - baseFolder.createFile(FILE_NAME, packageJson); - myJsonFiles.createFile("person.json", personJson); - } finally { - Closeables.closeQuietly(packageJson); - Closeables.closeQuietly(personJson); - } - } - - @Override - public String getProjectType() { - return Constants.JSON_EXAMPLE_PROJECT_TYPE_ID; - } -} ----- - -Finally, the ProjectHandler needs to be bound using Guice just as the project type was bound before: - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-server/src/main/java/it/pkg/inject/JsonExampleGuiceModule.java[JsonExampleGuiceModule.java]: - -[source,java] ----- -/... -Multibinder projectHandlerMultibinder = newSetBinder(binder(), - ProjectHandler.class); -projectHandlerMultibinder.addBinding().to(JsonExampleCreateProjectHandler.class); -/... ----- - -Once the ProjectHandler has been added and executed, the example project will already contain the files in the IDE. - -[id="project-creation-wizard"] -== Project Creation Wizard - -Project creation wizards are executed once the user creates a new project. They allow you to enter general properties (such as a name and a description), but also project-specific properties (e.g. a compiler option, a project dependency, etc.). Without providing a specific project creation wizard, Che already allows you to enter the general properties available for all projects as shown in the following screenshot for the JSON example project type we have defined in the previous section of the tutorial. - -In this section, we will describe how to extend the default project creation wizard with a new page allowing it to enter an additional property. As part of the JSON example, we will allow the user to enter the URL of a JSON Schema. We will later use the schema to validate JSON files on the server. Therefore, we will add a new page to the JSON project creation wizard allowing to enter the schema url property: - -image::devel/schema.png[] - -This page serves as a simple example, it can be adapted for any other project specific property. - -The following diagram shows all components for the extension of the project wizard. The classes highlighted in dark grey are to be implemented for the project wizards extension. - -image::devel/ProjectType-JsonExample.png[] - -Before we look at the detailed implementations, we will first give an overview of all participating components. As a first step, we need to implement a `ProjectWizardRegistrar`. It holds a set of `AbstractWizardPages`. These pages are added to the default wizard and displayed during project creation. Our implementation of a `ProjectWizardRegistrar` is in `JsonExampleProjectWizardRegistrar` and contributes one wizard page (see its method `#getWizardPages`) which will contain exactly one field for entering a JSON schema URL. - -The page itself is implemented in `SchemaUrlWizardPage`. To actually display a UI, it configures a GWT view defined in `SchemaUrlPageViewImpl` and its corresponding `SchemaUrlPageViewImpl.ui.xml`. Furthermore, the wizard page will create and configure a handler for URL changes called `SchemaUrlChangedDelegate`. - -Now all required classes are set up and the actual runtime behavior can be performed. Whenever the user performs a change in the textbox for the schema URL, GWT will trigger the method `#onSchemaUrlChanged` in `SchemaUrlPageViewImpl` since it is annotated as a handler for changes on this textbox. The method will then notify the `SchemaUrlChangedDelegate`. The `SchemaUrlChangedDelegate` will in turn write the changed URL into a `ProjectConfigDto` owned by the `SchemaUrlWizardPage`. - -Finally, to wire everything up with Gin, all we need to do is to define a module to register our class `JsonExampleProjectWizardRegistrar` as an implementation of `ProjectWizardRegistrar`: - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-ide/src/main/java/it/pkg/ide/inject/JsonExampleModule.java[JsonExampleModule.java]: - -[source,java] ----- -@ExtensionGinModule -public class JsonExampleModule extends AbstractGinModule { - - @Override - protected void configure() { - GinMultibinder - .newSetBinder(binder(), ProjectWizardRegistrar.class) - .addBinding() - .to(JsonExampleProjectWizardRegistrar.class); - } - //... -} ----- - -Now let us look at the implementation of all required classes in more detail. - -The `JsonExampleProjectWizardRegistrar` is responsible for setting up the `SchemaUrlWizardPage` as one of its wizard pages. To do this, it requests a provider for a `SchemaUrlWizardPage` injected in its constructor. The provider is just a wrapper around the actual wizard page which is required by the Che framework. In the method `#getWizardPages` we can then just return a list of providers for wizard pages containing only the injected provider. - -In addition to setting up the wizard page we need to declare the project type and category for which the project wizard is responsible for. - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-ide/src/main/java/it/pkg/ide/project/JsonExampleProjectWizardRegistrar.java[JsonExampleProjectWizardRegistrar.java]: - -[source,java] ----- -public class JsonExampleProjectWizardRegistrar implements ProjectWizardRegistrar { - private final List>> wizardPages; - - @Inject - public JsonExampleProjectWizardRegistrar( - Provider wizardPage) { - wizardPages = new ArrayList<>(); - wizardPages.add(provider); - } - - @NotNull - public String getProjectTypeId() { - return Constants.JSON_EXAMPLE_PROJECT_TYPE_ID; - } - - @NotNull - public String getCategory() { - return JSON_EXAMPLE_CATEGORY; - } - - @NotNull - public List>> getWizardPages() { - return wizardPages; - } -} ----- - -The `SchemaUrlWizardPage` class defines the actual wizard page for entering a schema URL. In the constructor it requires the injection of a view for displaying the UI of the page called `SchemaUrlPageViewImpl`. In the method `#go`, which is called when the page is about to be displayed, it will set this view as the only widget on the page and pass a new `SchemaUrlChangedDelegate` to the view. The view will later use this delegate to trigger changes on the page’s `ProjectConfigDto` whenever something is entered into the schema URL text box on the view. - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-ide/src/main/java/it/pkg/ide/project/SchemaUrlWizardPage.java[SchemaUrlWizardPage.java]: - -[source,java] ----- -public class SchemaUrlWizardPage extends AbstractWizardPage { - - private final SchemaUrlChangedDelegate view; - - @Inject - public SchemaUrlWizardPage(SchemaUrlPageViewImpl view) { - this.view = view; - } - - @Override - public void go(AcceptsOneWidget container) { - container.setWidget(view); - view.setDelegate(new SchemaUrlChangedDelegate (this.dataObject)); - } - -} ----- - -The `SchemaUrlChangedDelegate` receives a `ProjectConfigDto` in its constructor which holds all the values that are defined during project creation including the schema URL. Whenever its `#schemaUrlChanged` method is fired, it will write the new value into the `ProjectConfigDto`. - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-ide/src/main/java/it/pkg/ide/project/SchemaUrlChangedDelegate.java[SchemaUrlChangedDelegate.java]: - -[source,java] ----- -public class SchemaUrlChangedDelegate { - - private ProjectConfigDto dataObject; - - public SchemaUrlChangedDelegate(ProjectConfigDto dataObject) { - this.dataObject = dataObject; - } - - public void schemaUrlChanged(String value) { - dataObject.getAttributes().put("json-schema-ref", - Collections.singletonList(value)); - } -} ----- - -`SchemaUrlPageView` is just a marker interface required by the framework to declare that our `SchemaUrlPageViewImpl` is an implementation of a view with a `SchemaUrlChangedDelegate`. - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-ide/src/main/java/it/pkg/ide/project/SchemaUrlPageView.java[SchemaUrlPageView.java]: - -[source,java] ----- -public interface SchemaUrlPageView extends View {} ----- - -`SchemaUrlPageViewImpl` is the class which will actually create the UI with a TextBox for entering the schema URL. It is a GWT Composite with its contents defined in `SchemaUrlPageViewImpl.ui.xml`. To receive all changes of the schema URL in the UI it declares a method `#onSchemaUrlChanged` with an annotation @UiHandler("schemaUrl"). This annotation defines the method that is to be called whenever the text in the schemaUrl text box as defined in `SchemaUrlPageViewImpl.ui.xml` is changed. The method will just forward any call to the `SchemaUrlChangedDelegate` which was configured earlier by the `SchemaUrlWizardPage`. In its constructor the view gets a `JsonExamplePageViewUiBinder` injected which is used to create and bind the UI defined in `SchemaUrlPageViewImpl.ui.xml`. This requires you to define `JsonExamplePageViewUiBinder` as a marker interface extending `UiBinder`. - -More about declarative UIs with GWT UI binder can be found on the http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html[GWT homepage]. - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-ide/src/main/java/it/pkg/ide/project/SchemaUrlPageViewImpl.java[SchemaUrlPageViewImpl.java]: - -[source,java] ----- -class SchemaUrlPageViewImpl extends Composite implements SchemaUrlPageView { - - interface JsonExamplePageViewUiBinder extends UiBinder { - } - - @UiField - TextBox schemaUrl; - - private SchemaUrlChangedDelegate delegate; - - @Inject - public SchemaUrlPageViewImpl(JsonExamplePageViewUiBinder uiBinder) { - initWidget(uiBinder.createAndBindUi(this)); - } - - /** {@inheritDoc} */ - @Override - public void setDelegate(SchemaUrlChangedDelegate delegate) { - this.delegate = delegate; - } - - @UiHandler("schemaUrl") - void onSchemaUrlChanged(KeyUpEvent event) { - delegate.schemaUrlChanged(schemaUrl.getValue()); - } -} ----- - -https://github.com/che-samples/che-plugin-json/blob/master/plugins/plugin-myjson/plugin-myjson-ide/src/main/java/it/pkg/ide/project/SchemaUrlPageViewImpl.java[SchemaUrlPageViewImpl.ui.xml]: - -[source,xml] ----- -SchemaUrlPageViewImpl.ui.xml - - - - - - - - - - - wo - - ----- - -By adapting the `SchemaUrlPageViewImpl.ui.xml`, you can customize the layout of the final wizard page. - -[id="project-specific-actions"] -== Project-specific Actions - -Actions allow you to add custom behavior to the Che IDE. They can be placed in menus, toolbars or context menus. Some actions shall only be available on a specific project type. In the JSON example, we place two actions in the context menu of the defined project type. The screenshot shows a project-specific `HelloWorldAction`, as well as another project specific action. - -image::devel/json-example.png[] diff --git a/src/main/pages/che-6/developer-guide/properties.adoc b/src/main/pages/che-6/developer-guide/properties.adoc deleted file mode 100644 index afdccdaee2..0000000000 --- a/src/main/pages/che-6/developer-guide/properties.adoc +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Properties in Extensions" -keywords: framework, UI, properties -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/properties.html -redirect_from: properties.html -folder: che-6/developer-guide ---- - - -[id="referencing-properties-in-extensions"] -== Referencing Properties in Extensions - -You can reference properties in Che extensions that you author. Configuration parameters may be injected with a constructor or directly in the fields. The parameter of the field must be annotated with `@javax.inject.Named`. The value of the annotation is the name of the property. For example, if the configuration property is: `data_file:/home/user/storage` then in your extension code: - -[source,java] ----- -public class MyClass { - ... - @Inject - public MyClass(@Named("data_file") File storage) { - ... - } -} ----- - -or - -[source,java] ----- -public class MyClass { - @Inject - @Named("data_file") - private File storage; - ... -} ----- - -All system properties and environment variables may be injected into your extensions with prefixes `sys.` and `env.`, respectively. So, for example, environment variable `HOME` name must be `env.HOME`. Here is an example of how to inject the value of system property `java.io.tmpdir` and value of environment variable `HOME`. - -[source,java] ----- -public class MyClass { - @Inject - public MyClass(@Named("sys.java.io.tmpdir") File tmp, @Named("env.HOME") File home) { - ... - } -} ----- - -Any value can be converted into a `java.lang.String` Java type. You can also directly convert properties to the following Java types: * `boolean` * `byte` * `short` * `int` * `long` * `float` * `double` * `java.net.URI` * `java.net.URL` * `java.io.File` * `String[]` (value is a comma separated string) - -[id="property-aliases"] -== Property Aliases - -Sometimes a developer may need to change property name but support old names as well for the sake of backward compatibility. If this is the case, there is https://github.com/eclipse/che/blob/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che_aliases.properties[aliases file] where you can map new property name to old ones: - ----- -current_name=old_name, very_old_name ----- - -A few gotchas: - -* current_name = current_value -* if `old_name` property exists it will be bound to the old_value, so `current_name = old_value` and `very_old_name = old_value` -* if `very_old_name` property exists it will be bound to `very_old_value`, so `current_name = very_old_value` and `old_name = very_old_value` - -*IMPORTANT*: it is prohibited to use a different name for the same property on the same level. From the example above, you can use environment property `CHE_CURRENT_NAME` and `CHE_OLD_NAME`. However, you can use it on a different level, for instance, environment property and system property. - -[id="properties-and-environment-variables"] -== Properties and Environment Variables - -Naming conventions: - -* dots in properties separate components (in case of env vars it is a *single* underscore) -* underscores in properties separate words in a single component item (in case of env vars it is a *double underscore*) - -Example: - ----- -che.component1.sub_component_2_mb -> CHE_COMPONENT1_SUB__COMPONENT__2__MB - -where MB is unit of measurement in case when property is a number ----- - -Environment variables have a *higher priority* over properties, so if both are set, value of an environment variable will be used. Property can only be overridden, if it starts with `che.` - -[id="workspace-extension-properties"] -== Workspace Extension Properties - -Each workspace is a separate runtime, and has at least one development agent that runs as a miniaturized Che server within the workspace. That agent has its own properties that can be configured as well. If you are authoring custom workspace extensions that are deployed within Che’s agent in the workspace, you can customize. diff --git a/src/main/pages/che-6/developer-guide/registry.adoc b/src/main/pages/che-6/developer-guide/registry.adoc deleted file mode 100644 index bd87d1899a..0000000000 --- a/src/main/pages/che-6/developer-guide/registry.adoc +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Registry" -keywords: framework, overview, master, server, registry -tags: [dev-docs] -sidebar: che_6_docs -permalink: che-6/registry.html -redirect_from: registry.html -folder: che-6/developer-guide ---- - diff --git a/src/main/pages/che-6/developer-guide/rest-api.adoc b/src/main/pages/che-6/developer-guide/rest-api.adoc deleted file mode 100644 index 7c69346d65..0000000000 --- a/src/main/pages/che-6/developer-guide/rest-api.adoc +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: "REST API" -keywords: framework, overview, master, server, REST API -tags: [extensions, dev-docs, assembly] -sidebar: che_6_docs -permalink: che-6/rest-api.html -redirect_from: rest-api.html -folder: che-6/developer-guide ---- - - -Eclipse Che server side components - both for master and workspace agents - are exposed as REST services which makes it easy to integrate Che in other platforms or use custom clients to create and run workspaces, import and update projects, update/delete workspaces and associated objects etc. - -You can make yourself familiar with available APIs in Swagger UI page - all methods have swagger annotations. Che master APIs are available at at `${CHE_HOST}/swagger/`. If you use multi-user Che flavor, you will need link:authentication.html[authentication token]. - -Probably, https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/WorkspaceService.java[workspace API] is the most interesting one to take a closer look. Workspace API lets you remotely interact with Che master to create developer environments - create, update and delete workspaces, start workspaces by creating and deleting runtime, add, update and delete workspace environments, associate commands with a workspace. - -Workspace agent APIs focus on link:project-types.html[project types], link:projects.html[projects] and things related to projects, like link:version-control.html[Git]. To see the list of available workspace REST APIs, follow instructions in link:authentication.html[authentication docs]. With https://github.com/eclipse/che/blob/master/wsagent/che-core-api-project/src/main/java/org/eclipse/che/api/project/server/ProjectService.java[Project API] you can programmatically create/import projects in a workspace, update configuration, get file content using custom plugins or 3rd-party clients. diff --git a/src/main/pages/che-6/developer-guide/server-side-extensions.adoc b/src/main/pages/che-6/developer-guide/server-side-extensions.adoc deleted file mode 100644 index 8ee4471b48..0000000000 --- a/src/main/pages/che-6/developer-guide/server-side-extensions.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Server Side Extensions" -keywords: framework, overview, master, server, che server, framework -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/server-side-extensions.html -redirect_from: server-side-extensions.html -folder: che-6/developer-guide ---- - - -TODO diff --git a/src/main/pages/che-6/developer-guide/themes.adoc b/src/main/pages/che-6/developer-guide/themes.adoc deleted file mode 100644 index bf709111dc..0000000000 --- a/src/main/pages/che-6/developer-guide/themes.adoc +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "IDE UI: Themes" -keywords: framework, UI, themes, styles, customize -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/themes.html -redirect_from: themes.html -folder: che-6/developer-guide ---- - diff --git a/src/main/pages/che-6/developer-guide/workspace-agent.adoc b/src/main/pages/che-6/developer-guide/workspace-agent.adoc deleted file mode 100644 index 916429f34e..0000000000 --- a/src/main/pages/che-6/developer-guide/workspace-agent.adoc +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Workspace Agent" -keywords: framework, agent, workspace -tags: [extensions, assembly, dev-docs] -sidebar: che_6_docs -permalink: che-6/workspace-agent.html -redirect_from: workspace-agent.html -folder: che-6/developer-guide ---- - -== Enabling debugging on Workspace Agent - -. Configure your WS Agent Tomcat JPDA launching parameters with the following Workspace environment variables: -+ -`WSAGENT_DEBUG`:: Set to `true` to enable JPDA mode for Workspace Agent Tomcat. The default is `false`. -`WSAGENT_DEBUG_PORT`:: Configure the JPDA port. The default is `4403`. -`WSAGENT_DEBUG_SUSPEND`:: Set to `y` to enable JPDA suspend mode. The default is `n`. -+ -image::wsagent/wsagent-debug-env.png[] - -. Get a host and a port for connecting to Workspace Agent Tomcat. - -=== Connecting to Workspace Agent Tomcat with a debugger - -You will need a host and port for the debugger. The process of acquiring it differs depending on the Che infrastructure: - -==== Connecting a debugger on Docker - -* Before starting a workspace, define a link:servers.html[Server] for your JPDA port. -+ -image::wsagent/wsagent-debug-server.png[] - -* You will need to use a port on your host that is mapped to a port in the container. It can be found in *Workspace Servers* of a running workspace: -+ -image::wsagent/wsagent-debug-docker.png[] - -==== Connecting a debugger on Kubernetes or OpenShift - -To connect with a debugger from outside of the cluster, use _port forwarding_ to forward a port from your workspace pod to the port on your localhost. - -*For Kubernetes:* - -Use the following command to find the name and namespace of your workspace pod: - ----- -$ kubectl get pods --all-namespaces ----- - ----- -$ kubectl port-forward :--namespace= ----- - -In the command above, replace: - -* `` with the port of your configured JPDA Tomcat -* `` with the port on your host that you will connect to with your debugger -* `` with the name of the workspace pod -* `` with the namespace of the workspace pod - -*For Openshift:* - -Use the following commands to get name of your pod: - ----- -$ oc login -$ oc get pods ----- - -For a pod that belongs to a different namespace (if Che is configured to create an OpenShift project per workspace), use `oc use ` to switch to that project and run `oc get pods` again. - ----- -$ oc port-forward : ----- - -In the command above, replace: - -* `` with the port of your configured JPDA Tomcat -* `` with the port on your host that you will connect to with your debugger -* `` with the name of the workspace pod - -Connect to your debugger using `localhost` as the host and your local port, which is forwarded to the workspace pod. diff --git a/src/main/pages/che-6/overview/infra-support.adoc b/src/main/pages/che-6/overview/infra-support.adoc deleted file mode 100644 index ad73425150..0000000000 --- a/src/main/pages/che-6/overview/infra-support.adoc +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Infrastructures supported in Eclipse Che" -keywords: docker, oepsnhift -tags: [infrastructure, installation, docker, openshift] -sidebar: che_6_docs -permalink: che-6/infra-support.html -redirect_from: infra-support.html -folder: che-6/overview ---- - -[id="introduction"] -== Introduction - -Eclipse Che runs on several infrastructures and container engines: - -* Docker -* OpenShift: *https://www.openshift.com/container-platform/index.html[OpenShift Container Platform (OCP)]*, *https://www.openshift.com/features/index.html[OpenShift Online (OSO)]*, *https://access.redhat.com/products/openshift-dedicated-red-hat/[OpenShift Dedicated (OCD)]*, *https://www.openshift.org/minishift/[MiniShift]* -* Kubernetes - -[id="available-features-for-different-infrastructures"] -=== Available features for different infrastructures - -[%autowidth] -|=== -| Feature | *Docker* | *OpenShift* | *Kubernetes* -|root access | yes | yes (See: link:openshift-config.html#enable-ssh-and-sudo[Configuration]) | yes -|https | no | yes (See: link:openshift-config.html#https-mode[Configuration]) | yes -|scalability | no | yes (See: link:openshift-config.html#scalability[Configuration]) | yes -|privileged containers | yes | yes (configurable in https://docs.openshift.com/container-platform/3.6/admin_guide/manage_scc.html#grant-access-to-the-privileged-scc[OpenShift]) | yes -|health checks | no | yes | yes -|persistent preview URLs | no | yes | yes -|installers | yes | yes (some installers may require link:openshift-config.html#enable-ssh-and-sudo[sudo access]) | yes -|file system permissions | not limited | limited to directories owned by root link:openshift-config.html#filesystem-permissions[group] | not limited -|=== - -[id="docker-versus-openshift-for-running-che"] -== Docker versus OpenShift for running Che - -Che on Docker is not scalable because you cannot add more nodes to run workspaces.Even if you have a node with lots of resources, you can face problems with many containers residing on one node. A potential problem is that the instance can be unresponsive when it has a large number of running containers with heavy processes running in them. This affects the workspace master and all running workspaces. - -The follow features are available on both Docker and OpenShift: - -*Root Access:* You can have root access in workspace containers, which allows you to run system services and to install software at runtime. - -*Privileged Containers:* You can run workspace containers in a link:docker-config.html#privileged-mode[privileged mode]. - - -The following features are only available on OpenShift: - -*HTTPS support:* - -HAProxy runs in an OpenShift cluster and creates secure routes. - -*Scalability:* - -You can add nodes depending on the demand to run workspaces. OpenShift schedules workspaces to available nodes. - -*Health Checks:* - -OpenShift restarts failed deployments and offers health checks for pods. This can significantly minimize the effect of infrastructure outages. - -*Persistent Preview URLs:* - -You can access applications and processes in Che workspaces. Che creates services and routes that are persistent URLs. - -*Additional Resources* - -link:docker-single-user[Install Single-User Che on Docker] - -link:docker-multi-user[Install Multi-User Che on Docker] - -link:openshift-single-user[Deploy Single User Che to OpenShift] - -link:openshift-single-user.html[Deploy Multi-User Che to OpenShift] - diff --git a/src/main/pages/che-6/overview/introduction.adoc b/src/main/pages/che-6/overview/introduction.adoc deleted file mode 100644 index a2fb8dfe4f..0000000000 --- a/src/main/pages/che-6/overview/introduction.adoc +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Introduction to Eclipse Che -keywords: overview -tags: [overview, getting-started] -sidebar: che_6_docs -permalink: che-6/index.html -folder: che-6/overview -summary: Eclipse Che is a developer workspace server and cloud IDE ---- - -[id="introduction"] -== Introduction - -Eclipse Che provides: - -* Workspaces that include runtimes and IDEs -* RESTful workspace server -* A browser-based IDE -* Plugins for languages, framework, and tools -* An SDK for creating plugins and assemblies - -[id="getting-started"] -== Getting Started - -You can get started with Che by: - -* link:quick-start.html[Quick start guide] -* Installing it on Docker: link:docker-single-user.html[Single-user] or link:docker-multi-user.html[Multi-user] -* Installing it on OpenShift: link:openshift-single-user.html[Single-user] or link:openshift-multi-user.html[Multi-user] -* https://che.openshift.io[Creating a hosted SaaS account] (at che.openshift.io) - -[id="single-and-multi-user-flavors"] -== Single and Multi-User Flavors - -Eclipse Che is available in two different modes: - -* *Single-user*: perfectly suited for personal desktop environment. -* *Multi-user*: secure and best for organization and developer teams. - -Learn more about single and multi-user flavors on the following link:single-multi-user.html[page]. - -Considering the `multi-user` mode as an advanced setup of Eclipe Che, the quick starts are covering only the `single-user` mode. If you are interested by the `multi-user`, please read the following pages: - -* link:docker-multi-user.html[Multi-user configuration on Docker] -* link:openshift-multi-user.html[Multi-user configuration on OpenShift] - -[id="docker-and-openshift-support"] -== Docker and OpenShift Support - -Eclipse Che runs on different kind of infrastructure and container engine: - -* link:infra-support.html[Docker] -* link:infra-support.html[OpenShift] -* Kubernetes (soon) - -Learn more about the different infrastructure supported by Eclipse Che on the following link:infra-support.html[page]. - -[id="workspace-model"] -== Workspace Model - -image::intro/intro-che-workspace.png[] - -Che defines the workspace to be the project code files and all of their dependencies necessary to edit, build, run, and debug them. In our world, we treat the IDE and the development runtime as a dependency of the workspace. These items are embedded and included with the workspace, whereever it may run. This compares to classic workspace definitions which may include the project code, but require the developer to bind their IDE and use their laptop localhost to provide a runtime. - -Each workspace is isolated from one another and is responsible for managing the lifecycle of the components that are contained within it. - -image::intro/intro-workspace-runtimes.png[] - -A workspace contains one or more runtimes. The default runtime within our workspaces are Docker containers, but these runtimes can be replaced with other types of "machines" that offer different characteristics. We, for example, provide an SSH machine type and will soon provide localhost machines. The advantage of Docker as the runtime type allows users to define the contents of their runtime using Dockerfiles, for which we can then dynamically construct workspace runtimes without the user having to learn a lot of complex Docker syntax. - -image::intro/intro-project-mounted.png[] - -A workspace can have 0..n projects, with each project mapping to 0..1 remote version control repositories such as git, subversion, or mercurial. Projects are mounted into the workspace, so that they are available both inside of the workspace and also available on long term storage. Each project has a "type", such as "maven", which when selected will activate a series of plugins that alter the behavior of the workspace to accommodate that project type. Projects can have different types and they can also have remodules which are sub-portions of a project that have their own typing and behaviors. - -Each workspace has its own private browser IDE hosted within it. The browser IDE provided by Che is packaged as JavaScript and CSS, but our IDE could be replaced with other IDEs. Since each workspace has its own server runtimes, each workspace can have a customized IDE with different plugins packaged within it. - -image::intro/intro-SSH-connect.png[] - -By default, each workspace also configures its own SSH server. This allows remote clients and desktop IDEs to SSH mount into the workspace. By SSH mounting, you can let IDEs like IntelliJ or Eclipse work with the projects and runtimes contained within Che. - -Workspaces are hosted in the Che server, which is a lightweight runtime for managing workspaces. A single Che server can manage large volumes of workspaces, which themselves may or may not be running on the same host. Since Che workspace runtimes have their own runtimes, each workspace can be running on the same host or another host, managed by a docker daemon. The Che server is also a Docker container by default, which itself could be operated by compose or Swarm. - -image::intro/intro-share-workspace.png[] - -Since the workspaces are servers that have their own runtimes, they are collaborative and shareable. This allows multiple users to access the same workspace at the same time. Each workspace has its own unique URL which allows multi-user access. We currently support multiple users within a single workspace on a last-write-wins policy. Before the end of 2016, we’ll have multi-cursor editing using an operational transform. - -Each workspace is defined with a JSON data model that contains the definition of its projects, its runtimes, its IDE, and other necessary information that allows a Che server to create replicas. This allows workspaces to move from one location to another, such as from one Che server to another Che server. You will never have the "but it runs on that computer" issue again. Workspaces can also have their internal state snapshot and saved in a registry, so replicas can be created from the original template, or from images that contain modifications made after a user started working with the workspace. - -Both the Che server and each workspace have their own embedded RESTful APIs. Everything that is done by the user dashboard Web application and the browser IDE is done over RESTful APIs. You can access these APIs using swagger as Swagger configurations are provided within each service. The API set within the server and each workspace dynamically changes based upon the plugins that have been deployed by the admin or the user. - -[id="users"] -== Users - -Che has three types of users: - -* *Developers*. Che can be installed and used as a local IDE for any kind of programming language or framework, such as Java and JavaScript. While Che runs as a server, it can be run on a desktop, server, or within an embedded device. You can use Che with our embedded browser IDE or your existing IDE which is allowed to SSH into the Che workspaces. -* *Product Owners*. Che provides APIs hosted within its workspace server to manage environments, workspaces, projects, templates, stacks, and intellisense for developer activities such as editing, syntax analysis, compiling, packaging, and debugging. You can use Che to host on-demand workspaces accessed by the Che IDE or a client that your product team authors. For example, SAP uses the Che workspace server to embed its development tools for SAP Hana. -* *Plugin Providers*. Che provides a SDK to create and package plugins that modify the browser IDE, workspaces, or the Che server. ISVs and tool providers can add new project types, programming languages, tooling extensions, or applications. Che plugins can be authored for the client-side IDE or the server-side. - -[id="logical-architecture"] -== Logical Architecture - -image::intro/intro-che-architecture.png[] - -Che is a workspace server that runs on top of an application server like Tomcat. When the Che server is launched, the IDE is loaded as a Web application accessible via a browser at `http://localhost:8080/`. The browser downloads the IDE as a single page web app from the Che server. The Web application provides UI components such as wizards, panels, editors, menus, toolbars, and dialog boxes. - -As a user interacts with the Web application, they will create workspaces, projects, environments, machines, and other artifacts necessary to code and debug a project. The IDE communicates with Che over RESTful APIs that manage and interact with a Workspace Master. - -The Che server controls the lifecycle of workspaces. Workspaces are isolated spaces where developers can work. Che injects various services into each workspace, including the projects, source code, Che plug-ins, SSH daemon, and language services such as Eclipse JDT.LS Intellisense to provide refactoring for Java language projects. The workspace also contains a synchronizer which, depending upon whether the workspace is running locally or remotely, is responsible for synchronizing project files from within the machine with Che long term storage. - -[id="extensibility"] -== Extensibility - -Che provides an SDK for authoring new extensions, packaging extensions into plug-ins, and grouping plug-ins into an assembly. An assembly can either be executed stand alone as a new server, or, it can be installed onto desktops as an application using included installers. - -There are a number of aspects that can be modified within Che. - -[width="100%",cols="50%,50%",options="header",] -|=== -| Type | Description -| IDE Extension | Modify the look-and-feel, panels, editors, wizards, menus, toolbars, and pop-up boxes of the client. IDE extensions are authored in Java and transpiled into a JavaScript Web application that is hosted on the Che server as a WAR file. -| Che Server Extension (aka, Workspace Master) | Add or modify the core APIs that run within the Che server for managing workspaces, environments and machines. Workspace extensions are authored in Java and packaged as JAR files. -| Workspace Extension (aka, Workspace Agent) | Create or modify project-specific extensions that run within a workspace machine and have local access to project files. Define machine behaviors, code templates, command instructions, scaffolding commands, and intellisense. The Che Java extension is authored as a workspace agent extension, deployed into the machine, and runs Eclipse JDT.LS services to do local intellisense operations against the remote workspace. -|=== - -Each extension type is packaged separately because they are deployed differently into the assembly. IDE extensions are transpiled using GWT to generate a cross-browser JavaScript. This application is packaged as a WAR file and hosted on the Che server. - -Workspace master extensions are deployed as services within the Che server. Once deployed, they activate new management services that can control users, identity and workspaces. - -Workspace agent extensions are compiled with Che core libraries and also deployed within an embedded Che server that runs inside of each workspace machine. The Che server is injected into machines created and controlled by the central workspace master Che server. This embedded server hosts your workspace agent extensions and provides a communication bridge between the services hosted within Che and the machines that are hosting the project. - -[id="machines"] -== Machines - -When you develop with a desktop IDE, the workspace uses localhost as the execution environment for processes like build, run and debug. In a cloud IDE, localhost is not available, so the workspace server must generate the environments that it needs. These environments must be isolated from one another and scalable. We generate containers that contain the software needed for each environment. Each workspace is given at least one environment, but users may create additional environments for each workspace if they want. Each container can have different software installed. Che installs different software into the machine based upon the project type. For example, a Java project will have the JDK, Git, and Maven installed. When a user is working within their Workspace, this container is booted by Che and the source code of the project is mounted within it. Developer actions like auto-complete and `mvn clean install` are processes that are executed within the container. Users can provide their own Dockerfiles or Composefile that Che will build into images and extension developers can register Dockerfile templates associated with a project type. This allows Che to manage a potentially infinite number of environments while still giving users customization flexibility. - -[id="whats-included"] -== What’s Included - -Che ships with a large number of plugins for many programming languages, build systems, source code tools, and infrastructure including Java, Maven, Ant, Git, JavaScript, and Angular.JS. The community is developing their own and many are merged into the main Che repository. Che can be installed on any operating system that supports Docker 1.8+, OpenShift or Java 1.8 – desktop, server or cloud and has been tested on Linux, MacOS and Windows. It is originally licensed as EPL 1.0, and starting from version 6.9.0 and higher - as EPL 2.0. - diff --git a/src/main/pages/che-6/overview/quick-start.adoc b/src/main/pages/che-6/overview/quick-start.adoc deleted file mode 100644 index 0626fa088c..0000000000 --- a/src/main/pages/che-6/overview/quick-start.adoc +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Quick-Start" -keywords: docker, installation, minishift, openshift -tags: [installation, docker] -sidebar: che_6_docs -permalink: che-6/quick-start.html -folder: che-6/overview ---- - -Eclipse Che is a developer workspace server and cloud IDE. You install, run, and manage Eclipse Che with with different container orchestration engines such as Docker or OpenShift. - -Eclipse Che is available in two modes: - -* *Single-user*: This is suited for personal desktop environments. -* *Multi-user*: This is an advanced setup for Che and is for organizations and developer teams. - -See link:single-multi-user.html[Single and Multi-User Che] to learn more. The quick starts are for single-user mode. - -[id="docker"] -== Running single-user Che on Docker - -.Prerequisites - -* Latest Docker version installed (Docker 17+). -* On macOS, create an IP alias. In a terminal, run: -+ ----- -# ifconfig lo0 alias $IP ----- -+ -Where `$IP` is found either in *Preferences > Advanced > Docker subnet*, or run -+ ----- -$ docker run --rm --net host eclipse/che-ip:{{site.latest_6_x_version}} ----- - -.Procedure - -To run Che in single-user mode, run the command below. Note that `/local/path` in the command below needs to be changed and can be any path on your local machine where you want to store Che data and projects. - ----- -$ docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v /local/path:/data eclipse/che:{{site.latest_6_x_version}} start ----- - -Once Che has started, it can be accessed at `localhost:8080`. - -.Next steps - -link:creating-starting-workspaces.html[Create and start your first workspace], import a link:ide-projects.html[project], and link:commands-ide-macro.html[build and run] your project. - -.Additional resources - -* link:docker-single-user.html[Single-user on Docker] -* link:docker-multi-user.html[Multi-user on Docker] -* link:docker-config.html[Configuration on Docker] -* link:docker-cli.html[Che CLI for Docker] - -[id="openshift"] -== Running single-user Che on OpenShift - -.Prerequisities - -* Use the latest version of https://docs.openshift.org/latest/minishift/getting-started/index.html[MiniShift]. See https://github.com/minishift/minishift-addons/tree/master/add-ons/che[MiniShift add-on for Che]. - -To run Che in single-user mode on Minishift, use: - ----- -$ git clone https://github.com/minishift/minishift-addons -$ minishift addons install /add-ons/che -$ minishift addons enable che -$ minishift addons apply \ - --addon-env CHE_DOCKER_IMAGE=eclipse/che-server:{{site.latest_6_x_version}} \ - --addon-env OPENSHIFT_TOKEN=$(oc whoami -t) \ - che ----- - -.Next steps - -link:creating-starting-workspaces.html[Create and start your first workspace], import a link:ide-projects.html[project], and link:commands-ide-macro.html[build and run] your project. - -.Additional resources - -* link:openshift-single-user.html[Single-user on OpenShift] -* link:openshift-multi-user.html[Multi-user on OpenShift] -* link:openshift-config.html[Configuration on OpenShift] - -See the following resources for more information on the Openshift variants supported by Che: - -* https://www.openshift.com/container-platform/index.html[OpenShift Container Platform (OCP)]: OpenShift on-premise, which you can install in your Data Center. -* https://www.openshift.com/features/index.html[OpenShift Online (OSO)]: On-Demand OpenShift hosted on public cloud and managed by Red Hat. -* https://access.redhat.com/products/openshift-dedicated-red-hat/[OpenShift Dedicated (OCD)]: Enterprise public cloud with your own OpenShift cluster managed by Red Hat. -* https://www.openshift.org/minishift/[MiniShift]: OpenShift running on your local environment. diff --git a/src/main/pages/che-6/overview/single-multi-user.adoc b/src/main/pages/che-6/overview/single-multi-user.adoc deleted file mode 100644 index 40934884ca..0000000000 --- a/src/main/pages/che-6/overview/single-multi-user.adoc +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "Single and Multi-User Che" -keywords: single-user, Eclipse Che -tags: [installation, getting-started] -sidebar: che_6_docs -permalink: che-6/single-multi-user.html -redirect_from: single-multi-user.html -folder: che-6/overview - ---- - -Eclipse Che is available in two different modes: single-user and multi-user. - -**Single-user Che** - -To use Che on your local machine or to evaluate the platform, start with single-user Che. The advantages of using single-user Che are: - -* The command line interface pulls fewer images. -* The user dashboard is quickly available because no login is required. - -Single-user Che does not provide multi-tenancy nor permissions for entities such as workspaces. Che server and workspaces are not secure with single-user Che. - -.Additional Resources - -* To run Che in single-user mode using Docker, see link:docker-single-user.html[Single-user on Docker]. - -* To run Che in single-user mode using OpenShift, see link:openshift-single-user.html[Single-user on OpenShift]. - -**Multi-user Che** - -Multi-user Che provides multi-tenancy. Che uses http://www.keycloak.org[Keycloak] to register, manage, and authenticate users. Keycloak tokens provide security for user accounts and workspaces. The Permissions API regulates access to different entities such as workspaces, stacks, recipes, and organizations. User information is stored in a persistent PostgreSQL database, which supports migrations. - -The advantages of using multi-user Che are: - -* The fully functional web IDE supports precise access controls. -* The standalone Keycloak server supports user federation and identity providers. - -By default, Che deploys in single-user mode for Docker and OpenShift. You can use special flags to enable multi-user functionality. - -.Additional Resources - -* To run Che in multi-user mode using Docker, see link:docker-multi-user.html[Multi-user on Docker]. - -* To run Che in multi-user mode using OpenShift, see link:openshift-multi-user.html[Multi-user on OpenShift]. - diff --git a/src/main/pages/che-6/portable-workspaces/chedir-getting-started.adoc b/src/main/pages/che-6/portable-workspaces/chedir-getting-started.adoc deleted file mode 100644 index 9110567273..0000000000 --- a/src/main/pages/che-6/portable-workspaces/chedir-getting-started.adoc +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Getting Started" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/chedir-getting-started.html -redirect_from: chedir-getting-started.html -folder: che-6/portable-workspaces ---- - - -*Chedir is a Docker only feature and will not work on OpenShift/K8S!* - -The Chedir getting started guide will walk you through your first Chedir project, and show the basic features Chedir has to offer. - -If you are curious what benefits Chedir has to offer, you should also read the link:why-chedir.html[Why Chedir] page. - -Before diving into your first workspace, please check how to use the latest version of Chedir, which is also part of the link:docker-cli.html[Eclipse Che CLI]. And since Docker is required for everything related to Che, make sure that is installed as well. - ----- -# Clone a source code repo that you want to convert into a workspace -git clone https://github.com/che-samples/web-java-spring-petclinic -cd web-java-spring-petclinic - -# Convert it into a workspace running in a private Che server -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/chedir - eclipse/che: dir up - -# Note: Currently requires no other Che servers to be running simultaneously -# New version coming will allow many directories mounted into a single server ----- - -After running the above commands, you will have a project inside of a workspace inside of a running Che server. The workspace has its own runtime, powered by an Ubuntu Docker image. The project is mounted from the local directory into the workspace and is given full git capabilities. - -You can either open the IDE in your browser to work on the project immediately. The Web IDE has a terminal for accessing the Docker image powering the workspace. You can SSH into the workspace by pressing the `SSH` button in the IDE to get connectivity details. You can then make modifications, set the project type in the IDE, use language intellisense, or run a debugger. When you are done making modifications, you can use the IDE to commit and push changes with git, or continue to do those on your command line. You can then stop the workspace and unlink it with the following command: - ----- -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/chedir - eclipse/che: dir down ----- - -Now imagine every repository that you work on being this easy to convert into a debuggable workspace that includes its own pre-configured IDE. Chedir is all you need to convert repositories into workspaces with their own private runtimes, dependencies, networking and synchronized folders. - -The rest of this guide will walk you through setting up a more complete project, covering more features of Chedir. - -You have just created your first developer workspace with Chedir. Read on to learn more about link:chedir-project-setup.html[project setup]. diff --git a/src/main/pages/che-6/portable-workspaces/chedir-installation.adoc b/src/main/pages/che-6/portable-workspaces/chedir-installation.adoc deleted file mode 100644 index a0c60ef2ef..0000000000 --- a/src/main/pages/che-6/portable-workspaces/chedir-installation.adoc +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "Chedir Installation" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/chedir-installation.html -redirect_from: chedir-installation.html -folder: che-6/portable-workspaces ---- - - -Installing Chedir is extremely easy. Just link:docker-cli.html[get the Che CLI] and you have everything you need to run Chedir on any operating system. Docker and Git Bash (installed by Docker) are required for the Che CLI. - -[id="backwards-compatibility"] -== Backwards Compatibility - -Chedir requires Eclipse Che 4.7+. Chefiles are not supported to run on older versions of Che. - -[id="upgrading"] -== Upgrading - -You will automatically get newer versions of Chedir when you upgrade Eclipse Che. You can upgrade Eclipse Che with the CLI by `docker run -it --rm eclipse/che: upgrade`. If you want to use a particular version of Chedir you can set `CHE_VERSION` as an environment variable and Chedir will use that particular version. You can run multiple versions of Chedir at the same time. - -[id="from-source"] -== From Source - -Chedir is provided as a Docker container which you can run instead of using the CLI. The CLI captures your environmental information and invokes the container with the appropriate syntax. - ----- -# Mac / Linux -docker run -v /var/run/docker.sock:/var/run/docker.sock \ - -v "$PWD":"$PWD" --rm eclipse/che-dir \ - $PWD - -# Windows -# Replace $PWD to be the absolute path to the current directory. -# Use case-sensitive format with forward slashes: /c/Users/some_path/ ----- - -[id="build-chedir-docker-container"] -== Build Chedir Docker Container - -You can build Chedir Docker Container by using the following commands: - ----- -git clone http://github.com/eclipse/che -cd che/dockerfiles/dir -./build.sh ----- - -[id="uninstallation"] -== Uninstallation - -You can remove Chedir by deleting the Chedir docker image from your system. - ----- -docker rmi -f eclipse/che-dir ----- - -*_Remove Che_* - -If you’d also like to remove the Che CLI and Che: - ----- -# Remove the Che container -docker rmi -f eclipse/che-server - -# Remove your workspaces and the CLI - -# Linux / Mac -rm -rf $CHE_DATA_FOLDER -rm -rf /usr/local/bin/che - - -# Windows -rmdir /s %CHE_DATA_FOLDER% -del che.bat -del che.sh\ ----- diff --git a/src/main/pages/che-6/portable-workspaces/chedir-project-setup.adoc b/src/main/pages/che-6/portable-workspaces/chedir-project-setup.adoc deleted file mode 100644 index 815c8493dd..0000000000 --- a/src/main/pages/che-6/portable-workspaces/chedir-project-setup.adoc +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Chedir Project Setup" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/chedir-project-setup.html -redirect_from: chedir-project-setup.html -folder: che-6/portable-workspaces ---- - - -he first step in configuring a Che workspace from your directory is to create a Chefile. The purpose of the Chefile is to: 1. Mark the root directory that contains the source code to be mounted into your workspace. This directory will be used to create a single project in the workspace running in the Che server. The project will be mounted into `/projects` in the workspace. Many of the configuration options in Chedir are relative to this root directory. - -1. Describe the way the Che server and workspace will be configured and the resources they need to run your project, as well as what workspace stack to use and how it should be accessed. - -Chedir has a built-in command for initializing a directory for usage with Chedir: `docker run -it --rm -v :/chedir eclipse/che: dir init`. For the purpose of this getting started guide, please follow along in your terminal: - ----- -mkdir chedir_start -cd chedir_start - -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/chedir - eclipse/che: dir init ----- - -This will place a Chefile in your current directory. You can take a look at the Chefile if you want, it is filled with comments and examples. You can also run Chedir `init` command in a pre-existing directory that already has source code to set up Chedir for an existing project. - -The Chefile is meant to be committed to version control with your project, if you use version control. This way, every person working with that project can benefit from Chedir without any upfront work. - -*NEXT STEPS* - -link:chedir-up-and-down.html[Cycle your workspace up and down] in a custom Che server. diff --git a/src/main/pages/che-6/portable-workspaces/chedir-ssh.adoc b/src/main/pages/che-6/portable-workspaces/chedir-ssh.adoc deleted file mode 100644 index e63430c044..0000000000 --- a/src/main/pages/che-6/portable-workspaces/chedir-ssh.adoc +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: "SSH" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/chedir-ssh.html -redirect_from: chedir-ssh.html -folder: che-6/portable-workspaces ---- - - -You can use Chedir to SSH into the newly created workspace, whether it is local or remote. It does not matter what operating system that you are using, this technique also supports Microsoft Windows without having to install putty! - ----- -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/chedir - eclipse/che: dir ssh ----- - -The command has local context of the Che server and workspace that is associated with the Chefile in the current directory. Chedir looks up the appropriate context and then initiates an SSH connection. diff --git a/src/main/pages/che-6/portable-workspaces/chedir-up-and-down.adoc b/src/main/pages/che-6/portable-workspaces/chedir-up-and-down.adoc deleted file mode 100644 index ab445bdae3..0000000000 --- a/src/main/pages/che-6/portable-workspaces/chedir-up-and-down.adoc +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Chedir Up and Down" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/chedir-up-and-down.html -redirect_from: chedir-up-and-down.html -folder: che-6/portable-workspaces ---- - - -In the first version of Chedir, each Chedir directory maps to a single Che server containing a single workspace. That workspace can have multiple projects and source repositories that are part of it. - -You can boot both a Che server and a workspace (with its embedded runtimes) with a single command: - ----- -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/chedir - eclipse/che: dir up ----- - -This command will boot a Che server according to the properties in the Chefile. If necessary, the right Che launcher and Che server Docker images will be downloaded and cached. After the server has booted, Chedir will create a workspace and start its runtime, also as a set of Docker containers. - -If there is an existing Che server running with the configuration specified, Chedir will discontinue and recommend that you create a different configuration to avoid conflicts. - -When the process of creation has completed, you will be presented with two URLs: - -1: Che server URL - a URL that will open the dashboard to manage the Che instance + -2: Workspace URL - a URL that will open the browser IDE with the workspace configured - -The workspace is a fully functional runtime environment. You can work within the workspace, SSH into it, and also work on code. Any code changes will be synchronized with the local directory. You can also perform git operations such as add, commit, and push from within the IDE. - -Run Chedir `down` command on the host machine. Chedir will stop the workspace runtime, stop the Che server, and return to the host. The workspace and its project will be preserved. You can run Chedir `up` to reactivate it. This command is the equivalent of running `docker run -it --rm eclipse/che: stop` with the CLI. - -To stop the Che server and remove the workspace, you can destroy it. - ----- -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/chedir - eclipse/che: dir destroy ----- - -*NEXT STEPS* - -link:chefile.html[Author a custom Chefile] to tailor how the workspace is created and adapted to your project. diff --git a/src/main/pages/che-6/portable-workspaces/chefile.adoc b/src/main/pages/che-6/portable-workspaces/chefile.adoc deleted file mode 100644 index c6e90ea242..0000000000 --- a/src/main/pages/che-6/portable-workspaces/chefile.adoc +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: "Chefile" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/chefile.html -redirect_from: chefile.html -folder: che-6/portable-workspaces ---- - - -[id="getting-started"] -== Getting Started - -You can create a Chefile and place it into the root of your repository. The Chefile contains the configuration that will be used to setup the Che server and Che workspace. - ----- -# Usage -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/chedir - eclipse/che: dir - -# Commands: - -- init : Initialize the :/chedir volume mount and add a default Chefile file if there is none -- up : Boot Eclipse Che with workspace on folder -- down : Stop Eclipse Che and any workspaces -- ssh : Connect to the running workspace by using ssh -- status : Display if an instance of Eclipse Che is running or not for the specified folder ----- - -[id="chefile-syntax"] -== Chefile syntax - ----- -# This file can be generated by using `dir init` command -# Defines public IP for Che (ip should be IP of docker host) -che.server.ip = localhost - -# Defines port on which your private Che server will listen. -che.server.port = 8080 - -# Configure how Che boots with environment variables. -# Chefile supports the full Che configuration list of che.env -che.server.properties['CHE_VERSION']='nightly' -che.server.properties['CHE_PROPERTY_http__proxy']='http://localhost:1234' - -# Defines name of the workspace -workspace.name = “happy” - -# Define the Docker image to use to power the workspace's runtime -# This must conform to recipe requirements -workspace.runtime.docker.image="eclipse/alpine_jdk8" - -# You can - instead - define the runtime using a Dockerfile in a git repo -workspace.runtime.docker.location= "http://gist...../my-dockerfile" - -# Or you could define the runtime using inline Dockerfile content -workspace.runtime.docker.dockerfile=` -FROM ... -RUN ... -ENV ... -` - -# Or, you can define a multi-contianer runtime using compose -workspace.runtime.docker.composefile=` -version: 2 -` - -# Defines memory allocated to the workspace's runtime -workspace.ram = 2048 - -# Commands are processes that users execute in the IDE. -# Commands will appear in the drop down on the tool bar. -workspace.commands[0].name = "my-first-command" -workspace.commands[0].type = "mvn" -workspace.commands[0].commandLine = "mvn clean install -f ${current.project.path}" -workspace.commands[0].attributes.previewUrl = "http://${server.port.80}/${current.project.relpath}" - -# If you omit the command type, it will default to a custom command (bash). -workspace.commands[1].name = "my-second-command" -workspace.commands[1].commandLine = "echo hello world" - -# A command that will be executed after the workspace is loaded. -# Reference the name of a command defined above. -workspace.postload.actions[0].name="my-second-command" - -# Or, by defining inline bash script within the post action. -workspace.postload.actions[1].script=`echo 'this is a post-loading command' \ - && while true; do \ - echo $(date); sleep 1; \ - done` - -# A project has type, name, and mapped to a source repository. -# This project is mapped to the directory where Chefile is saved. -workspace.projects[0].type="blank" - -# You can have multiple projects sourced from git or subversion repos -workspace.projects[1].name = "florent" -workspace.projects[1].source.type = "git" -workspace.projects[1].source.location = "https://github.com/che-samples/web-java-spring-petclinic" -workspace.projects[1].type = "maven" ----- - -[id="sample-chefile"] -== Sample Chefile - -We maintain a https://github.com/eclipse/che/blob/master/Chefile[Chefile in the root of the Eclipse Che repository]. It is used to build and run Che using Eclipse Che! - ----- - -# Runtime image to use for booting and compiling Eclipse Che -# workspace.runtime.docker.image="florentbenoit/che-in-che" - -# Commands to display in the IDE -workspace.commands[0].name="build" -workspace.commands[0].commandLine="mvn clean install -f /projects/che/assembly/assembly-main" - - -workspace.commands[1].name="run" -workspace.commands[1].commandLine='export CHE_VERSION="nightly" && export CHE_BIN_PATH=$(ls -d /projects/che/assembly/assembly-main/target/eclipse-che-*/eclipse-che-*); sudo docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock' -workspace.commands[1].commandLine=workspace.commands[1].commandLine+" --env CHE_LOCAL_BINARY=${CHE_BIN_PATH/'/projects/che'/$(sudo docker inspect --format '{{"{{"}} range .Mounts }}{{"{{"}} if eq .Destination \"/projects/che\" }}{{"{{"}} .Source }}{{"{{"}} end }}{{"{{"}} end }}' $(hostname))}" -workspace.commands[1].commandLine=workspace.commands[1].commandLine+' --env CHE_PORT=54321 --env CHE_SERVER_CONTAINER_NAME="che-in-che-server" eclipse/che-launcher:nightly start' -workspace.commands[1].attributes={ - "previewUrl": "http://localhost:54321" -} - -workspace.commands[2].name="stop" -workspace.commands[2].commandLine='sudo docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock --env CHE_SERVER_CONTAINER_NAME="che-in-che-server" eclipse/che-launcher stop' - -workspace.commands[3].name="kill" -workspace.commands[3].commandLine="sudo docker rm -f che-in-che-server" - -# Name of the workspace -workspace.name="che" - -# Memory for this workspace -workspace.ram=3092 - -# Configure project properties -workspace.projects[0].type = "maven" ----- - -[id="add-typescript-to-chefile"] -== Add Typescript to Chefile - -Chefile is authored as Typescript. While it looks like a simple `name=value` property file, it’s actually written entirely in Typescript using `variable=assignment` syntax. This means that you can add in valid TypeScript for variable assignments, operators, and constructs. - -This is essential for development team leads and developer operations teams so that they can dynamically generate the Chefile configuration as part of their continuous development processes. While complicated, this is also a valid Chefile: - -[source,javascript] ----- -var date = new Date(); -let es6Date = new Date(); - -let myMap = new Map(); -myMap.set("my-name", my-custom-workspace); -myMap.set("my-ram", 2048); - -console.log('first date is', date); -console.log('another date is', es6Date); - -console.log("map is", myMap); - -workspace.name=getWorkspaceName(); -workspace.ram=myMap.get("my-ram"); - -console.log('first command of workspace is', workspace.commands[0].commandLine); - -function getWorkspaceName() { - return myMap.get("my-name"); -} ----- diff --git a/src/main/pages/che-6/portable-workspaces/creating-factories.adoc b/src/main/pages/che-6/portable-workspaces/creating-factories.adoc deleted file mode 100644 index 609b0f35ea..0000000000 --- a/src/main/pages/che-6/portable-workspaces/creating-factories.adoc +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: "Creating Factories" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/creating-factories.html -redirect_from: creating-factories.html -folder: che-6/portable-workspaces ---- - - -[id="create-a-factory-in-the-dashboard"] -== Creating a factory in the dashboard - -You can create a factory based on an existing workspace. You can also create factories based on a template or by pasting in a `.factory.json` file and then generating a factory URL using the Che CLI or API. To learn more about the JSON structure and options, see link:factories_json_reference.html[Factory JSON reference]. - -A factory created from the dashboard is persisted on Che and retained when upgrading to a newer version. - -To create a factory on the dashboard: - -. In the IDE, click *Dashboard* > *Factories* > *Create Factory*. - -Sample factory: https://che.openshift.io/f?id=factorymtyoro1y0qt8tq2j[https://che.openshift.io/f?id=factorymtyoro1y0qt8tq2j]. - - -[id="create-a-factory-in-the-ide"] -== Creating a factory in the IDE - -Creating a factory in the IDE in a running workspace generates a factory to replicate that workspace including the runtime and project settings. - -A factory created from the dashboard is persisted on Che and retained when upgrading to a newer version. - -To create a factory in the IDE: - -. In the IDE, click *Workspace* > *Create Factory*. - -Sample factory: https://che.openshift.io/f?id=factorymtyoro1y0qt8tq2j[https://che.openshift.io/f?id=factorymtyoro1y0qt8tq2j]. - - -[id="create-a-factory-based-on-a-repo"] -== Creating a factory based on a repository - -URL factories work with GitHub and GitLab repositories. By using URL factories, the project referenced by the URL is automatically imported. - -To create a factory based on a repository: - -. Specify the repository URL. Ensure that you store the configuration in the repository. - -Sample factories: - -* http://che.openshift.io/f?url=https://github.com/eclipse/che - -* http://che.openshift.io/f?url=https://github.com/eclipse/che/tree/language-server - -* http://che.openshift.io/f?url=https://gitlab.com/benoitf/simple-project - -The factory URL can include a branch or a subdirectory. Following are examples of optional parameters: - -* `?url=https://github.com/eclipse/che` Che is imported with the `master` branch. - -* `?url=https://github.com/eclipse/che/tree/5.0.0` Che is imported by using the `5.0.0` branch. - -* `?url=https://github.com/eclipse/che/tree/5.0.0/dashboard` subdirectory `dashboard/` is imported by using the `5.0.0` branch. - - -[id="customizing-url-factories"] -=== Customizing URL factories - -The following are two ways to customize the runtime and configuration: - -Customizing only the runtime:: Providing a `.factory.json` file inside the repository signals to Che URL factory to configure the project and runtime according to this configuration file. When a `.factory.json` file is stored inside the repository, any `Dockerfile` content is ignored because the workspace runtime configuration is defined inside the JSON file. - -Customizing the `Dockerfile`:: (This only works on Docker infrastructure. On recent Che versions, support of this feature may be reduced or dropped.) Providing a `.factory.dockerfile` inside the repository signals to the URL factory to use this `Dockerfile` for the workspace agent runtime. By default, imported projects are set to a `blank` project type. You can also set the project type in the `.factory.json` file or in the workspace definition that the factory inherits from. - - -[id="configuring-factory-policies"] -== Configuring factory policies - -Policies are a way to send instructions to the automation engine about the number of workspaces to create and their meta data such as lifespan and resource allocation. - - -[id="setting-factories-limitations"] -=== Setting factory limitations - -Referer:: Checks the hostname of the acceptor and only allows the factory to execute if there is a match. - -Since and Until:: Defines the time window in which the factory can be activated. For example, instructors who want to create an exercise that can only be accessed for two hours should set these properties. - - -[id="setting-factories-multiplicity"] -=== Setting factory multiplicity - -Multiplicity defines the number of workspaces that can be created from the factory. - -Multiple workspaces (`perClick`):: Every click of the factory URL generates a different workspace, each with its own identifier, name, and resources. - -Single workspace (`perUser`):: Exactly one workspace is generated for each unique user that clicks on the factory URL. Existing workspaces are reopened. - -To learn how to configure factory policies, see the link:factories_json_reference.html[JSON reference]. - - -[id="customizing-the-ide"] -== Customizing the IDE - -You can instruct the factory to invoke a series of IDE actions based on events in the lifecycle of the workspace. - - -[id="lifecycle-events"] -== Lifecycle Events - -The lifecycle of the workspace is defined by the following events: - -* `onAppLoaded`: Triggered when the IDE is loaded. -* `onProjectsLoaded`: Triggered when the workspace and all projects have been activated. -* `onAppClosed`: Triggered when the IDE is closed. - -Each event type has a set of actions that can be triggered. There is no ordering of actions executed when you provide a list; Che asynchronously invokes multiple actions if appropriate. - - -[id="factory-actions"] -== Factory actions - -The following is a list of all possible actions that can be configured with your factory. - -Run Command:: -Specify the name of the command to invoke after the IDE is loaded. + -_Associated Event_: `onProjectsLoaded` - -Open File:: -Open project files in the editor. Optionally, define the line to be highlighted. + -_Associated Event_: `onProjectsLoaded` - -Open a Welcome Page:: -Customize content of a welcome panel displayed when the workspace is loaded. + -_Associated Event_: `onAppLoaded` - -Warn on Uncommitted Changes:: -Opens a warning pop-up window when the user closes the browser tab with a project that has uncommitted changes. + -_Associated Event_: `onAppClosed` - -To learn how to configure factory actions, see the link:factories_json_reference.html#ide-customization[Factory JSON reference]. - - -[id="find-and-replace"] -== Finding and replacing variables - -Factories make it possible to replace variables or placeholders in the source code -- used to avoid exposing sensitive information (passwords, URLs, account names, API keys) -- with real values. To find and replace a value, you can use the `run` command during an `onProjectsLoaded` event. You can use `sed`, `awk`, or other tools available in your workspace environment. - -For a sample of how to configure finding and replacing a value, see the link:factories_json_reference.html#action-find-and-replace[Factory JSON reference] section. Alternatively, you can add IDE actions in the *Factory* tab, on the user *Dashboard*. - -Use https://www.gnu.org/software/sed/manual/html_node/Regular-Expressions.html[regular expressions] in `sed`, both in find-replace and file-file type patterns. - - -[id="pull-request-workflow"] -== Pull request workflow - -Factories can be configured with a dedicated pull request workflow. The PR workflow handles local and remote branching, forking, and issuing the pull request. Pull requests generated from within Che have another factory placed into the comments of the pull requests that a PR reviewer can use to quickly start the workspace. - -When enabled, the pull request workflow adds a contribution panel to the IDE. - -image::git/pr_panel.png[] - - -[id="repository-badging"] -== Repository badging - -If you have projects in GitHub or GitLab, you can help your contributors to get started by providing them ready-to-code developer workspaces. Create a factory and add the following badge on your repositories `readme.md`: - -[source,markdown] ----- -[![Developer Workspace](https://che.openshift.io/factory/resources/factory-contribute.svg)](your-factory-url) ----- - - -[id="creating-factories-next-steps"] -== Next steps - -* Read about customizing factories with the link:factories_json_reference.html[Factory JSON reference]. diff --git a/src/main/pages/che-6/portable-workspaces/factories-getting-started.adoc b/src/main/pages/che-6/portable-workspaces/factories-getting-started.adoc deleted file mode 100644 index 1968f09ce6..0000000000 --- a/src/main/pages/che-6/portable-workspaces/factories-getting-started.adoc +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Getting started with factories" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/factories-getting-started.html -redirect_from: factories-getting-started.html -folder: che-6/portable-workspaces ---- - -A factory is a template containing configuration to automate the generation of a new workspace using a factory identifier added to the IDE URL. Factories can be used to create replicas of existing workspaces or to automate the provisioning of statically or dynamically defined workspaces. - - -[id="trying-a-factory"] -== Trying a factory - -Clone a public workspace on `che.openshift.io` by clicking https://che.openshift.io/f?id=factorymtyoro1y0qt8tq2j[try a factory]. - - -[id="using-factories"] -== Using factories - -Factories can be invoked from a factory URL built in multiple ways. You can replace the `localhost:8080` domain with the hostname of any Che installation. - -Using factories on `che.openshift.io` requires the user to be authenticated. Users who are not authenticated see a login screen after they click on the factory URL. Users without an account can create one using the same dialog. - - -[id="invoking-factories-using-their-unique-hashcodes"] -== Invoking factories using their unique hashcodes - -[cols="1,5"] -|=== -|Format | `/f?id={hashcode}` + - `/factory?id={hashcode}` -|Sample | https://localhost:8080/f?id=factorymtyoro1y0qt8tq2j -|=== - - -[id="invoking-a-named-factory"] -== Invoking a named factory - -[cols="1,5"] -|=== -|Format | `/f?user={username}&name={factoryname}` + - `/factory?user={username}&name={factoryname}` -|Sample | https://localhost:8080/f?user=che&name=starwars + - https://localhost:8080/factory?user=che&name=starwars -|=== - - -[id="invoking-a-factory-for-a-specific-git-repository"] -== Invoking a factory for a specific git repository - -[cols="1,5"] -|=== -|Format | `/f?url={git URL}` -|Sample | http://localhost:8080/f?url=https://github.com/eclipse/che + - http://localhost:8080/f?url=https://github.com/eclipse/che/tree/language-server + - http://localhost:8080/f?url=https://gitlab.com/benoitf/simple-project -|=== - -Once a factory is executed, it either loads an existing workspace or generates a new one, depending on the factory configuration. The name of the workspace is determined by the factory configuration, and its name becomes a part of the URL used to access the factory. The format is: `{hostname}/{username}/{workspace}`. - - -[id="next-steps"] -== Next steps - -You have just created your first developer workspace using factories. Read on to learn more about: - -* How to link:creating-factories.html[create factories] -* Customizing factories with the link:factories_json_reference.html[factory JSON reference] diff --git a/src/main/pages/che-6/portable-workspaces/factories.adoc b/src/main/pages/che-6/portable-workspaces/factories.adoc deleted file mode 100644 index 79c6c9c44b..0000000000 --- a/src/main/pages/che-6/portable-workspaces/factories.adoc +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "What Are Factories?" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/factories.html -redirect_from: factories.html -folder: che-6/portable-workspaces ---- - - -[id="intro"] -== Intro - -A factory is a concept that automates the generation or loading of a workspace using URLs. - -Factories make it possible to execute many of the automation capabilities contained within a Chefile, but in a purely remote syntax. Factories are URLs that you give to others, that when executed by other developers, will generate new workspaces in those acceptors’ accounts with cloned projects and ready-to-go commands. Factories are wrapped with policies so that the Factory owner can control when, how, and who is able to make use of the Factory without the acceptors’ having to pre-configure any software on their computer. - -You can create Chefiles for a local directory from an existing Factory. Or, you can have Che automatically generate a Factory for a source repository that has a Chefile in the root of the repository. Think of factory as a way for you to allow remote users to execute Chedir up against a repository without those users having to install anything first. - -[id="create-factory-from-chefile"] -== Create Factory From Chefile - -You can create a factory to load within Codenvy from an existing Chefile. In the directory that has your Chefile execute: - ----- -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/chedir - eclipse/che: dir factory ----- - -This will output a factory object that can be imported into any Che installation. Once imported, you will have a URL that can be shared with others allowing for remote execution of the Chedir up capability. - -Note: Che is also searching for .Chefile name (hidden file on Linux/MacOs) in addition to Chefile. diff --git a/src/main/pages/che-6/portable-workspaces/factories_json_reference.adoc b/src/main/pages/che-6/portable-workspaces/factories_json_reference.adoc deleted file mode 100644 index 015a76f8a1..0000000000 --- a/src/main/pages/che-6/portable-workspaces/factories_json_reference.adoc +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: "Factories JSON Reference" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/factories_json_reference.html -redirect_from: factories_json_reference.html -folder: che-6/portable-workspaces ---- - -A factory configuration is a JSON snippet either stored within Che or as a `.factory.json` file. You can create factories within the IDE using the Che URL syntax, within the dashboard, or on the command line with the API and CLI. - -[source,json] ----- -factory : { - "v" : 4.0, <1> - "workspace" : {}, <2> - "policies" : {}, <3> - "ide" : {}, <4> - "creator" : {}, <5> -} ----- -<1> Version of the configuration format. -<2> Identical to `workspace:{}` object for Eclipse Che. -<3> (Optional) Restrictions that limit behaviors. -<4> (Optional) Trigger IDE UI actions tied to workspace events. -<5> (Optional) Identifying information of author. - -The `factory.workspace` is identical to the `workspace:{}` object for Eclipse Che and contains the structure of the workspace. To learn more about the workspace JSON object, see link:workspace-data-model.html[Workspace Data Model]. - -You can export Che workspaces and then reuse the workspace definition within a factory. Che workspaces are composed of the following: - -* 0..n projects -* 0..n environments that contain machines to run the code -* 0..n commands to execute against the code and machines -* a type - -The `factory.policies`, `factory.ide`, and `factory.creator` objects are unique to factories. They provide meta information to the automation engine that alter the presentation of the factory URL or the behavior of the provisioning. - -[id="mixins"] -== Mixins - -A mixin adds additional behaviors to a project as a set of new project type attributes. Mixins are reusable across any project type. To define the mixins to add to a project, specify an array of strings, with each string containing the identifier for the mixin. For example, `"mixins" : [ "pullrequest" ]`. - -[width="100%",cols="50%,50%",options="header",] -|=== -|Mixin ID |Description -|`pullrequest` -|Enables pull request workflow where Che handles local and remote branching, forking, and pull request issuance. Pull requests generated from within Che have another factory placed into the comments of pull requests that a PR reviewer can consume. Adds contribution panel to the IDE. If this mixin is set, it uses attribute values for `project.attributes.local_branch` and `project.attributes.contribute_to_branch` -|=== - -* The `pullrequest` mixin requires additional configuration from the `attributes` object of the project. If present, {{ site.product_mini_name }} will use the project attributes as defined in the factory. If not provided, {{ site.product_mini_name }} will set defaults for the attributes. - -* Learn more about other link:TODO: link to project API docs[mixins] - -[id="pull-request-mixin-attributes"] -== Pull Request mixin attributes - -Project attributes alter the behavior of the IDE or workspace. - -Different Eclipse Che plug-ins can add their own attributes to affect the behavior of the IDE or workspace. Attribute configuration is always optional and if not provided within a factory definition, the IDE or workspace sets it. - - -[width="100%",cols="50%,50%",options="header",] -|=== -|Attribute |Description -|`local_branch` |Used in conjunction with the `pullrequest` mixin. If provided, the local branch for the project is set with this value. If not provided, the local branch is set with the value of `project.source.parameters.branch` (the name of the branch from the remote). If both `local_branch` and `project.source.parameters.branch` are not provided, the local branch is set to the name of the checked out branch. -|`contribute_to_branch` |Name of the branch that a pull request will be contributed to. The value of `project.source.parameters.branch` is default. It is the name of the branch that this project was cloned from. -|=== - -Following is a snippet that demonstrates full configuration of the `contribution` mixin. - -[source,json] ----- -factory.workspace.project : { - "mixins" : [ "pullrequest" ], - - "attributes" : { - "local_branch" : [ "timing" ], - "contribute_to_branch" : [ "master" ] - }, - - "source" : { - "type" : "git", - "location" : "https://github.com/codenvy/che.git", - "parameters" : { - "keepVcs" : "true" - } - } -} ----- - -[id="policies"] -== Policies - -Following is an example of a factory policy. - -[source,json] ----- -factory.policies : { - "referer" : STRING, <1> - "since" : EPOCHTIME, <2> - "until" : EPOCHTIME, <3> - "create" : [perClick | perUser] <4> -} ----- -<1> Works only for clients from a referrer. -<2> Factory works only after this date. -<3> Factory works only before this date. -<4> Create one workpace per click, user, or account. - -[id="factories_json_reference-limitations"] -== Limitations - -You can use `since : EPOCHTIME`, `until : EPOCHTIME`, and `referer` as a way to prevent the factory from executing under certain conditions. `since` and `until` represent a valid time window that allows the factory to activate. The `referrer` checks the hostname of the acceptor and only allows the factory to execute if there is a match. - -[id="factories_json_reference-multiplicity"] -== Multiplicity - -Using `create : perClick` causes every click of the factory URL to generate a new workspace, each with its own identifier, name, and resources. Using `create : perUser` causes only one workspace to be generated for each unique user that clicks on the factory URL. If the workspace has previously been generated, the existing workspace is reopened. - -[id="factories_json_reference-ide-customization"] -== Customizing the IDE - -[source,json] ----- -factory.ide.{event} : { <1> - "actions" : [{}] <2> -} - -factory.ide.{event}.actions : [{ - "id" : String, <3> - properties : {} <4> -}] ----- -<1> event = `onAppLoaded`, `onProjectsLoaded`, `onAppClosed`. -<2> List of IDE actions to be executed when the event is triggered. -<3> Action for the IDE to perform when the event is triggered. -<4> Properties to customize action behavior. - -You can instruct the factory to invoke a series of IDE actions based on events in the lifecycle of the workspace. - -`onAppLoaded`:: - Triggered when the IDE is loaded. -`onProjectsLoaded`:: - Triggered when the workspace and all projects have been activated or imported. -`onAppClosed`:: - Triggered when the IDE is closed. - -Following is an example that associates a variety of actions with all of the events. - -[source,json] ----- -"ide" : { - "onProjectsLoaded" : { <1> - "actions" : [{ - "id" : "openFile", <2> - "properties" : { <3> - "file" : "/my-project/pom.xml" - } - }, - { - "id" : "runCommand", <4> - "properties" : { - "name" : "MCI" <5> - } - } - ]}, - "onAppLoaded": { - "actions": [ - { - "properties:{ - "greetingTitle": "Getting Started", <6> - "greetingContentUrl": "http://example.com/README.html" <7> - }, - "id": "openWelcomePage" - } - ] - }, - "onAppClosed" : { <8> - "actions" : [{ - "id" : "warnOnClose" <9> - }] - } -} ----- -<1> Actions triggered when a project is opened. -<2> Opens a file in the editor. Can add multiple. -<3> The file to be opened (include project name). -<4> Launch command after the IDE opens. -<5> Command name. -<6> Title of a *Welcome* tab. -<7> HTML file to be loaded into a tab. -<8> Actions to be triggered when the IDE is closed. -<9> Show warning when closing a browser tab. - -Each event type has a set of actions that can be triggered. There is no ordering of actions executed when you provide a list; {{ site.product_mini_name }} will asynchronously invoke multiple actions if appropriate. Some actions can be configured in how they perform and will have an associated `properties : {}` object. - -*onProjectsLoaded Event* - -[width="100%",cols="34%,33%,33%",options="header",] -|=== -|Action |Properties? |Description -|`runCommand` |Yes |Specify the name of the command to invoke after the IDE is loaded. Specify the commands in the `factory.workspace.commands : []` array. -|`openFile` |Yes |Open project files as a tab in the editor. -|=== - -*onAppLoaded Event* - -[width="100%",cols="34%,33%,33%",options="header",] -|=== -|Action |Properties? |Description -|`openWelcomePage` |Yes |Customize the content of the welcome panel when the workspace is loaded. Note that browsers block http resources that are loaded into https pages. -|=== - -*onAppClosed Event* - -[width="100%",cols="34%,33%,33%",options="header",] -|=== -|Action |Properties? |Description -|`warnOnClose` |No |Opens a warning pop-up window when the user closes the browser tab with a project that has uncommitted changes. Requires `project.parameters.keepVcs` to be `true`. -|=== - -[id="action-open-file"] -== Action: Open File - -This action opens a file as a tab in the editor. You can provide this action multiple times to have multiple files open. The file property is a relative reference to a file in the project source tree. The `file` parameter is the relative path within the workspace to the file that should be opened by the editor. The `line` parameter is optional and can be used to move the editor cursor to a specific line when the file is opened. Projects are located in the `/projects/` directory of a workspace. - -[source,json] ----- -{ - "id" : "openFile", - "properties" : { - "file" : "/my-project/pom.xml", - "line" : "50" - } -} ----- - -[id="action-find-and-replace"] -== Action: Find and Replace - -In projects created from a factory, Che can find and replace values in the source code after it is imported into the project tree. This lets you parameterize your source code. Find and replace can be run as a *Run Command* during `onProjectsLoaded` event. You can use `sed`, `awk`, or any other tools that are available in your workspace environment. - -To define a command for your workspace in `factory.workspace.workspaceConfig.commands`: - ----- -{ - "commandLine": "sed -i 's/***/userId984hfy6/g' /projects/console-java-simple/README.md", - "name": "replace", - "attributes": { - "goal": "Common", - "previewUrl": "" - }, - "type": "custom" -} ----- - -In the preceding example, a named command `replace` is created. The command replaces each occurrence of `***` with the string `userId984hfy6` in the `README.md` file of the project. - -Then register this command to the execution list linked to the `onProjectsLoaded` event. In this example, the `replace` command is executed after the project is imported into a workspace. - ----- -"ide": { - "onProjectsLoaded": { - "actions": [ - { - "properties": { - "name": "replace" - }, - "id": "runCommand" - } - ] - } - } ----- - -Use https://www.gnu.org/software/sed/manual/html_node/Regular-Expressions.html[regular expressions] in `sed`, both in find-replace and file-file type patterns. - -[id="creator"] -== Creator - -This object has meta information that you can embed within the factory. These attributes do not affect the automation behavior or the behavior of the generated workspace. - -[source,json] ----- -factory.creator : { - "name" : STRING, <1> - "email" : STRING, <2> - "created" : EPOCHTIME, <3> - "userId" : STRING <4> -} ----- -<1> The name of the author of this configuration file. -<2> The author's email address. -<3> This value is set by the system. -<4> This value is set by the system. diff --git a/src/main/pages/che-6/portable-workspaces/why-chedir.adoc b/src/main/pages/che-6/portable-workspaces/why-chedir.adoc deleted file mode 100644 index 3b04303258..0000000000 --- a/src/main/pages/che-6/portable-workspaces/why-chedir.adoc +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Why Chedir?" -keywords: chedir, factories -tags: [chedir, factories] -sidebar: che_6_docs -permalink: che-6/why-chedir.html -redirect_from: why-chedir.html -folder: che-6/portable-workspaces ---- - - -Chedir provides easy to configure, reproducible and portable developer workspaces built on top of Docker and controlled by a single consistent workflow to help maximize the productivity and flexibility of you and your team. - -To achieve its magic, Chedir uses Eclipse Che and Docker. Workspaces are provisioned inside of a Che server that is running locally or remotely. The workspace will have its own private runtime that is also based upon Docker or Docker Compose. Your source code is then synchronized from the current directory into the hosted workspace. You can then use provisioning tools such as shell scripts, Chef, or Puppet to define the software that is inside the workspace available to edit, build, run and debug your code. - -Chedir is (positively) influenced by Vagrant. Where Vagrant treats a single VM as a broad abstraction as an "environment", Chedir applies a similar abstraction to a developer workspace, which is inclusive of multiple internal environments, the source code for projects mapped from repositories, and the tools + commands necessary to build and debug a project. After provisioning, users can connect their local IDE or use the embedded cloud IDE of Eclipse Che. diff --git a/src/main/pages/che-6/setup-docker/docker-cli.adoc b/src/main/pages/che-6/setup-docker/docker-cli.adoc deleted file mode 100644 index 4bd436b797..0000000000 --- a/src/main/pages/che-6/setup-docker/docker-cli.adoc +++ /dev/null @@ -1,430 +0,0 @@ ---- -title: "CLI Reference" -keywords: docker, configuration, CLI, cli -tags: [installation, docker] -sidebar: che_6_docs -permalink: che-6/docker-cli.html -redirect_from: docker-cli.html -folder: che-6/setup-docker ---- - -[id="cli-syntax-and-commands"] -== CLI syntax and commands - -The CLI is a Docker-formatted container image that comes with a collection of commands to configure, interact with, and start Che. The CLI also contains commands, such as `sync` and `ssh`, for end users to interact with workspaces. - -Command: ----- -$ docker run -it --rm eclipse/che-cli: [COMMAND] ----- - -Following is the mandatory `docker` command parameter for the CLI image: - ----- --v :/data ----- - -The user, instance, and log data are saved here. - -The following tables lists the optional `docker` command parameters that you can use with the CLI image. - -[cols="2*", options="header"] -|=== -|Optional Docker parameter -|Description -|`-e CHE_HOST=` -|IP address or hostname where Che serves its users - -|`-e CHE_PORT=` -|Port on which Che binds itself - -|`-e CHE_CONTAINER=` -|Prefix name for the Che container - -|`-v :/data/instance` -|The instance, user, log data is saved here - -|`-v :/data/backup` -|Backup files are saved here - -|`-v :/repo` -|Che git repository - uses local binaries and manifests - -|`-v :/assembly` -|Che assembly - uses local binaries - -|`-v :/sync` -|Where `remote ws` files are copied with the `sync` command - -|`-v :/unison` -|Where unison profile for optimizing the `sync` command resides - -|`-v :/chedir` -|Source repository to convert into workspace with the `Chedir` utility -|=== - - -The following table lists the commands that you can use with the Docker CLI image. - -[cols="2*", options="header"] -|=== -|Command -|Description -|`action ` -|Start action on Che instance - -|`backup` -|Backs up Che configuration and data to the `/data/backup` volume mount - -|`config` -|Generates a Che configuration from variables; run on any `start` or `restart` command - -|`destroy` -|Stops services, and deletes che instance data - -|`dir ` -|Use `Chedir` and `Chefile` in the directory mounted to `:/chedir` - -|`download` -|Pulls Docker images for the current Che version - -|`help` -|Displays information about Che and the CLI - -|`info` -|Displays system state and debugging information - -|`init` -|Initializes a directory with a Che install - -|`offline` -|Saves Che container images into TAR files for offline installation - -|`restart` -|Restarts the Che services - -|`restore` -|Restores Che configuration and data from the `/data/backup` mount - -|`rmi` -|Removes the container images for ``, forcing a re-pull - -|`ssh <__workspace-name__> [_machine-name_]` -|SSH to a workspace if SSH agent is enabled - -|`start` -|Starts the Che services - -|`stop` -|Stops the Che services - -|`sync <__workspace-name__>` -|Synchronizes workspace with local directory mounted to `:/sync` - -|`test <__test-name__>` -|Starts test on the Che instance - -|`upgrade` -|Upgrades Che from one version to another with migrations and backups - -|`version` -|Installed version and upgrade paths -|=== - -The following table lists the global command options that you can use with the Docker CLI image. - -[cols="2*", options="header"] -|=== -|Command option -|Description -|`--fast` -|Skips networking, version, nightly, and preflight checks - -|`--offline` -|Runs CLI in offline mode, loading images from the disk - -|`--debug` -|Enable debugging of the Che server - -|`--trace` -|Activates trace output for debugging the CLI -|=== - -The CLI has the following three primary phases: - -* The initialization phase is executed by the `init` command. It installs version-specific files into the directory mounted to `/data/`. This includes the universal configuration file named `che.env`, a version identifier, and a location where configuration files are saved. The configuration is executed by the `config` command. The `config` command takes the `che.env` configuration file and the OS of your host system as input and generates an OS-specific set of configuration files in the `data/instance` directory." - -* The configuration phase runs an initialization if a directory is not found. Every execution of the `config` command overwrites the files in the `/data/instance/` directory with the latest configuration. This ensures that if an administrator modifies any configuration file, the instance’s configuration files are updated consistently. The CLI generates a large number of configuration files specific to running Che. The configuration files are sourced from the Puppet templates that are stored in the GitHub repository under `/dockerfiles/init/`. - -* The start phase is executed by the `start` command. It uses a configuration-generated `docker-compose-container.yml` file to launch Eclipse Che. The start phase always executes a `config` command, so any files that were edited in the `/data/instance/` directory are overwritten with the generated configuration from the CLI. - -The CLI hides most error conditions from the standard output. Internal stack traces and error output are redirected to the `cli.log` file, which is saved in the host directory where `:/data` is mounted. - -You can override any value in the `che.env` file for a single execution by passing the `-e NAME=VALUE` argument on the command line. The CLI detects the values on the command line and ignores those imported from the `che.env` file. - -Following are some selected commands and their uses. - -`action`:: -The `action` command executes some actions on the Eclipse Che instance or on a workspace running inside Che. To list all workspaces on Che, use the `action list-workspaces` command. To execute a command on a workspace, use the `action execute-command ` command; here, the `` parameter is interpreted by the shell. - - -`backup`:: -The `backup` command creates TAR files from the `instance/` directory and places them in the `/backup/` directory. These files are restoration-ready. - -`config`:: -The `config` command generates a Che instance configuration that is placed in the `instance/` directory. It uses Puppet to generate Docker Compose configuration files to run Che and its associated server. Che server configuration is generated as a `che.properties` file that is mounted in the Che server when it boots. This command is executed on every `start` or `restart`. -+ -If you are using a `eclipse/che:` image and it does not match the version in the `instance/che.ver` file, the configuration aborts to prevent you from running a configuration for a different version. -+ -It respects the `--no-force`, `--pull`, `--force`, and `--offline` command options. - -`destroy`:: -The `destroy` command deletes the `che.env` file and the `/docs/` and `instance/` directories, including user workspaces, projects, data, and user database. To skip the confirmation warning message, pass the `--quiet` argument in the command. To delete the `cli.log` file, pass the `--cli` argument. By default, the `cli-log` file is retained for traceability. - -`dir`:: -The `dir` command boots a new Eclipse Che instance with a workspace for the `:/chedir` directory defined as volume mount in the parameter. -+ -For example, if you give `$HOME/my-project` as a parameter, a new Che instance is created using `$HOME/my-project` as a project in the IDE. Inside the IDE, the `/projects/` directory contains a `my-project/` directory with your host directory. Any changes inside the IDE are reflected in your host directory. Updating a file on your local computer updates the content of the file inside the IDE. -+ --- -[horizontal] -`init`:: Initializes the directory specified and adds a default `Chefile` if there is none. -`up`:: Boots Eclipse Che with workspace on directory. -`down`:: Stops Eclipse Che and any workspaces. -`ssh`:: Connects to the running workspace by using the `ssh` command. -`status`:: Displays if an instance of Eclipse Che is running or not for the specified directory. --- - -`download`:: -The `download` command is used to download container images stored in your image repository. This command downloads images that are used by the CLI as utilities, for Che to do initialization and configuration, and for the runtime images that Che needs when it starts. This command respects the `--offline`, `--pull`, `--force`, and `--no-force` (default) command options. It is invoked by the `che init`, `che config`, or `che start` commands. -+ -The `download` command is invoked by the `che init` command before initialization to download images for the version specified by `eclipse/che:`. -+ -To override the Docker-formatted container images used by the CLI, set the following environment variables: -+ -* `IMAGE_INIT` to override the default `eclipse/che-init:` Docker-formatted container image. -* `IMAGE_CHE` to override the default `eclipse/che-server:` Docker-formatted container image. -+ -For example, if you want to use a given tag in your own Docker account for both images, add the following parameters to the `docker` command: -+ ----- --e IMAGE_INIT=myDockerAccount/che-init:givenTag -e IMAGE_CHE=myDockerAccount/che-server:givenTag ----- - -`info`:: -The `info` command displays system state and debugging information. The `--network` command option runs a test to take the `CHE_HOST` variable value to test network connectivity by simulating the *browser > Che* and *Che > workspace* connectivity. The `--bundle` command option generates a support diagnostic bundle in a TAR file, which includes the output of certain commands and the execution logs. - -`init`:: -The `init` command initializes an empty directory with a Che configuration and instance directory. The user data and runtime configuration are stored in the empty directory. You must provide a `:/data` volume mount for Che to create the `instance/` and `backup/` sub-directories of ``. After initialization, a `che.env` file is placed in the root directory of the path that you mounted to `/data/`. -+ --- -Overriding the location of the `instance/` directory:: Mount an additional local directory to the `/data/instance/` directory. -Overriding the location of where backups are stored:: Mount an additional local directory to the `/data/backup/` directory. --- -+ -The following variables can be set in your local environment shell before running. These variables are respected during initialization: -+ -[width="100%",cols="44%,56%",options="header",] -|=== -|Variable |Description -|`CHE_HOST` |The IP address or DNS name of the Che service. We use `eclipse/che-ip` to attempt discovery if not set. -|`CHE_PORT` |The port the Che server will run on and expose in its container for your clients to connect to. -|=== -+ -Che depends on container images. The images are used to: -+ -* Provide cross-platform utilities within the CLI. For example, to perform a `curl` operation, you use a small container image to perform this function. This is done as a precautionary measure because many operating systems do not have `curl` installed. -+ -* Find the master version and upgrade manifest, which is saved within the CLI container image in the `/version/` sub-directory. -+ -* Perform initialization and configuration of Che as done with the `eclipse/che-init` command. This image contains templates to be installed on your computer used by the CLI to configure Che for your specific OS. -+ -You can control how Che downloads these images with command-line options. All image downloads are performed using the `docker pull` command. -+ -[width="100%",cols="32%,68%",options="header",] -|=== -|Mode |Description -|`--no-force` |The default behavior. Downloads an image if not found locally. A local check of the image inspects if an image of a matching name is present in your local registry and then skips pulling the image if it is found. This mode does not check DockerHub for a newer version of the same image. -|`--pull` |Always perform a `docker pull` command when an image is requested. If there is a newer version of the same tagged image at DockerHub, it pulls it, or uses the one in the local cache. This slows the execution but keeps your images up-to-date. -|`--force` |Performs a forced removal of the local image using the `docker rmi` command and then pulls it again from DockerHub. Use this to clean your local cache and to ensure that all images are new. -|`--offline` |Loads tar-archived container images from the `backup/` directory during the pre-boot mode of the CLI. Used if you are performing an installation or start while disconnected from the Internet. -|=== -+ -You can reinstall Che on a directory that is already initialized and preserve your `che.env` values by passing the `--reinit` flag. - -`offline`:: -The `offline` command saves all the container images that Che requires in `/backup/*.tar` files. Each image is saved as its own file. If the `backup/` directory is available on a machine that is disconnected from the Internet and you start Che with the `--offline` command option, the CLI pre-boot sequence loads all the container images in the `backup/` directory. -+ -The `--list` option lists all the core images and optional stack images that can be downloaded. The core system images and the CLI are always saved if an existing TAR file is not found. The `--image:` command option downloads a single-stack image and can be used multiple times on the command line. You can use the `--all-stacks` option or the `--no-stacks` option to download all or none of the optional stack images. - -`restart`:: -The `restart` command performs a `stop` action followed by a `start` action, respecting the `--pull`, `--force`, `--offline`, `--skip:config`, `--skip:preflight`, and `--skip:postflight` command options. - -`restore`:: -The `restore` command restores the `/instance` directory to its previous state. The start-stop-restart cycle ensures that the proper Docker images are available or downloaded if not found. -+ -[IMPORTANT] -==== -Use this command with caution because it deletes the existing `instance/` directory. As a precautionary measure, set these values to different directories when performing a restore action. -==== - -`rmi`:: -The `rmi` command deletes the container images that Che has downloaded for this version from the local registry. - -`ssh`:: -The `ssh` command connects the current terminal where the command is started to the terminal of a machine of the workspace. If no machine is specified in the command, it connects to the default development machine. The syntax is: -+ ----- - ssh [machine-name] ----- -+ -The SSH connection only works with a configured workspace SSH key. A default SSH key is automatically generated when a workspace is created. - -`sync`:: -The `sync` command synchronizes contents of a workspace with a local directory mounted to `:/sync`. The syntax is: -+ ----- --v :/sync eclipse/che sync ----- -+ -To display a log of the underlying unison tool, use the `--unison-verbose` flag. - -`start`:: -The `start` command starts Che and its services using the `docker-compose` command. In the absence of valid configuration, it performs an `init` command. Every `start` and `restart` command runs the `config` command to generate a new configuration set using the latest configuration files placed into the `instance/` directory. The starting sequence also tests if any ports required by Che are currently being used by other services and to verify access to key APIs. -+ --- -Skipping the generation of configuration:: Use the `--skip:config` option. -Skipping checks:: Use the `--skip:preflight` and `--skip:postflight` options. -Automatically printing server logs during the boot:: Use the `--follow` option. To interrupt the output, press *Ctrl+c*, or use the shell commands to interrupt the output. --- - -`stop`:: -The default stop is a graceful stop where each workspace is stopped and confirmed shut down before stopping system services. If workspaces are configured to snap on stop, all snaps are completed before the system service shutdown begins. You can ignore workspace stop behavior and shut down only system services using the `–force` flag. - -`test`:: -The `test` command performs tests on your local instance of Che. For example, to check the ability to create a workspace, start the workspace by using a custom workspace runtime, and then use it. For a list of all tests available, use the `test` command. - -`upgrade`:: -The `upgrade` command manages the sequence of upgrading Che from one version to another. For a list of available versions that you can upgrade to, run the `che version` command. -+ -The Che upgrade is done by using a `eclipse/che:` image that is newer than the version you currently have installed. For example, if you have `` installed and you want to upgrade to ``: -+ -. To get the new version of Che: -+ ----- -$ docker pull eclipse/che: ----- -+ -You now have two `eclipse/che` images (one for each version). -+ -. Use the new image to upgrade the old installation: -+ ----- -$ docker run eclipse/che: upgrade ----- -+ -The `upgrade` command has numerous checks to prevent you from upgrading Che if the new image and the old version are not compatible. For the upgrade procedure to proceed, the CLI image must be newer than the value of `instance/che.ver`. -+ -Following is a list of actions that the upgrade process performs in the background: - -.. Performs a version compatibility check. - -.. Downloads new Docker images that are needed to run the new version of Che. - -.. Stops Che if it is currently running and triggers a maintenance window. - -.. Backs up your installation. - -.. Initializes the new version. - -.. Starts Che. - -For a list of available versions that you can upgrade to, run the `che version` command. - -The `--skip-backup` option allows you to skip the https://github.com/codenvy/che-docs/blob/master/src/main/_docs/setup/setup-cli.md#backup[backup] operation during the update. Skipping the backup operation speeds up the upgrade because the https://github.com/codenvy/che-docs/blob/master/src/main/_docs/setup/setup-cli.md#backup[backup operation] can be time consuming if the `/instance` directory contains many user worksapces and projects making it a large directory. - -`version`:: -The `version` command provides information on the current version and the available versions that are hosted in Che repositories. The `che upgrade` command enforces upgrade sequences and prevents you from upgrading one version to another version where data migrations cannot be guaranteed. - - -[id="cli-development"] -== Developing and testing the CLI - -You can customize the CLI using a variety of techniques. This section discusses how engineers develop and test the CLI on their local machines. - -[id="structure"] -== Structure of the Che CLI - -The Che CLI is constructed of multiple Docker images within the Che source repository. - ----- -/dockerfiles/base <1> -/dockerfiles/cli <2> -/dockerfiles/init <3> ----- -<1> Common functions and commands -<2> CLI entrypoint, overrides, and version information -<3> Manifests used to configure Che on a host installation - -The Che CLI is written in Bash. The `cli` image depends upon both the `base` image and the `init` image. In the source repository, the `build.sh` script builds these Docker images either one at a time or collectively as a group. - -Rebuilding images every time you want to test a small change to Bash script can be tedious. To avoid rebuilding the images every time and for every change to a Bash script, mount the contents during the image execution. You cannot mount the `entrypoint.sh` file, but you can mount the following: - -* To mount the contents of the `base` image: -+ ----- --v /dockerfiles/scripts/base/scripts:/base/scripts ----- - -* To mount the contents of the `init` image: -+ ----- --v :/repo ----- - -If you run the Che CLI in this configuration, any changes made to the Bash files or templates in those repositories are used without having to first rebuild the CLI image. - -[id="custom-cli"] -== Customizing the Che CLI - -The Che CLI was designed to be overridden to allow different CLIs to be created from the same base structure. The CLI is created with the following minimal assets: - ----- -/dockerfiles/cli/build.sh <1> -/dockerfiles/cli/Dockerfile <2> -/dockerfiles/cli/scripts <3> -/dockerfiles/cli/scripts/entrypoint.sh <4> -/dockerfiles/cli/scripts/cli.sh <5> -/dockerfiles/cli/version <6> ----- -<1> Local file to build the image -<2> Image definition, must FROM `eclipse/che-base:nightly` -<3> Contains additional commands in the form of `cmd_.sh` -<4> The entrypoint of the CLI container, with the `usage()` method -<5> Defines CLI-specific product names and variables -<6> Contains version-specific data that the CLI requires - -You can add additional commands to the Che CLI beyond the base set of commands that are provided by adding a file of the name `cmd_.sh` into the `scripts/` directory. - -The `version/` directory contains information about the latest version and a sub-directory for each version that is available for installation. Each version sub-directory has version-specific data that the CLI depends on to create a manifest of container images that must be downloaded to support the product that is going to be run. When a release of the Che CLI is generated, the CI systems automatically update the `version/` directory with the version-specific information contained in the release. - -[id="puppet-templates"] -== Puppet templates - -The Che CLI uses Puppet to generate OS-specific configuration files based on environment variables set by the user either with the `-e ` option on the command line, or by modifying their `che.env` file. - -A Puppet configuration utility parses files contained in the `/dockerfiles/init/modules/` and `/dockerfiles/init/manifests/` directories to take the templates contained in the `/init/` directory, matches them with user-specific variables, and generates an instance-specific configuration in the `instance/` directory. Puppet has logic constructs that allow us to generate different kinds of constructs with logic based on the values provided by the end users. - -This Puppet-based approach allows to simplify the outputs for end users and limit the locations where end users need to configure various parts of the system. An example of this is that we generate two `docker-compose.yml` files from a single Puppet template. The `docker-compose.yml` and `docker-compose-container.yml` files are located in the user’s `instance/` directory. - -`docker-compose.yml`:: A configuration file that allows a user to run Docker Compose for Che on their host. They can run the `docker-compose up` command in that directory. - -`docker-compose-container.yml`:: A configuration file for running Docker Compose from within a container, which is what the CLI does. - -The syntax of Docker Compose changes in each of these scenarios as the files being referenced from within the compose syntax are different. There is a single template for Docker Compose in the `init` image. It is then applied in two configurations using Puppet. - -[id="cli-tests"] -== CLI tests - -There are existing https://github.com/sstephenson/bats[bats] tests for the Che CLI, which run automatically with each execution of the `build.sh` script located in the `dockerfiles/cli/` directory. To skip them, pass the `--skip-tests` argument when running the build script. To only run the tests, execute the `test.sh` script located in the same directory. The tests utilize the `eclipse/che-bats` docker image, which is built from the `Dockerfile` placed in the `dockerfiles/bats/` directory. - diff --git a/src/main/pages/che-6/setup-docker/docker-config.adoc b/src/main/pages/che-6/setup-docker/docker-config.adoc deleted file mode 100644 index 071460cde0..0000000000 --- a/src/main/pages/che-6/setup-docker/docker-config.adoc +++ /dev/null @@ -1,644 +0,0 @@ ---- -title: "Configuring Che on Docker" -keywords: docker, configuration -tags: [installation, docker] -sidebar: che_6_docs -permalink: che-6/docker-config.html -redirect_from: docker-config.html -folder: che-6/setup-docker ---- - -The Che on Docker configuration is handled by modifying the https://github.com/eclipse/che/blob/master/dockerfiles/init/manifests/che.env[`che.env`] file that is placed in the root directory of a host directory mounted to `:/data`. This configuration file is generated during the `che init` phase. If you rerun the `che init` command in an already initialized directory, the process will abort unless you pass the `--force`, `--pull`, or `--reinit` options. - -You can also pass an environment variable directly in the `docker run` syntax: `-e CHE_ENV_NAME=value`. - -Each variable is documented with an explanation and usually commented out. If you need to set a variable, uncomment it and configure it with your value. You can then run the `che config` command to apply this configuration to your system. The `che start` command also reapplies the latest configuration. - -You can run the `che init` command to install a new configuration into an empty directory. This command uses the `che/init:` Docker container to deliver a version-specific set of Puppet templates into the directory. - -If you run the `che config` command, Che runs Puppet to transform your Puppet templates into a Che instance configuration. It places the results either into the `/che/instance` directory if you mounted that, or into an `instance` subdirectory of the path you mounted to `/che`. Each time you start Che, the `che config` command is run to ensure that the instance configuration files are properly generated and consistent with the configuration you have specified in the `che.env` file. - -Administration teams that want to manage versions of your Che configuration should save the `che.env` file. This is the only file that should be saved with version control. It is not necessary to save any other files. To upgrade, use the `che upgrade` command and replace these files with templates that are specific to the version that is being upgraded. The `che.env` file remains the same between versions and you can generate instance configurations from that. - -The following is the version-control sequence: - -. Run the `che init` command to get an initial configuration for a particular version. -. Edit the `che.env` file with your environment-specific configuration. -. Save the `che.env` file to version control. -. Setup a new directory and copy the `che.env` file from version control into the directory you will mount to `:/data`. -. Run the `che config` or the `che start` command. - -[id="running-che-in-single-port-mode"] -== Running Che in single-port mode - -By default, Che lets Docker publish exposed ports in a random manner. Docker chooses available ports from the ephemeral port range to expose workspace link:servers.html[servers]. This requires the opening of the ephemeral port range (and the Keycloak `5050` port for multi-user Che) to the world. - -To run Che in single-port mode, add `-e CHE_SINGLE_PORT=true` to the run syntax. In this case, a Traefik container will be used to route traffic through a single port. - -=== Using wildcard DNS - -In single-port mode, Che builds URLs of workspace services using the following pattern: `serviceName-machineName-ws-ID.IP.wildcardDNSProvider`. For example, with an external IP of `193.12.34.56`, the URL of a workspace agent will be `wsagent-http-dev-machine-workspace0bcgkgkvsqi31b4u.193.12.34.56.nip.io`. - -* By default, http://nip.io/[nip.io] is used. This is an external wildcard DNS provider. The nip.io service must be available for networking in single-port Che to work correctly. - -* You can use a different wildcard DNS provider with the `CHE_SINGLEPORT_WILDCARD__DOMAIN_HOST` environment variable. - -* To exclude the external IP from the URL (`serviceName-machineName-ws-ID.wildcardDNSProvider`, for example to use a wildcard SSL certificate), specify `CHE_SINGLEPORT_WILDCARD_DOMAIN_IPLESS=true` with a custom wildcard DNS (example: `CHE_SINGLEPORT_WILDCARD_DOMAIN_HOST=domain.tld`). You must have a matching DNS entry for `*.domain.tld`. In multi-user mode, Keycloak will be provided at `keycloak.domain.tld`. - -[id="configuring-keycloak-in-multi-user-mode"] -=== Configuring Keycloak in multi-user mode - -Ensure that `webOrigins` and `redirectUris` in Keycloak client settings (`che-public` client) reference your `CHE_DOCKER_IP_EXTERNAL` value, that is the IP that external users will use to log in. Keycloak administration console in multi-user Che is available at `http://keycloak.$IP.$wildcardDNSProvider:$chePort/auth/`. Here, `$IP` is either your `docker0` IP or the `CHE_DOCKER_IP_EXTERNAL` value. - -[id="accessing-logs-and-user-data"] -== Accessing logs and user data - -When Che initializes itself, it stores logs, user data, database data, and instance-specific configuration in the directory mounted to `:/data/instance` or an `instance` subdirectory of what you mounted to `:/data`. - -Che containers save their logs in the same location: - ----- -/instance/logs/che/2016 <1> -/instance/logs/che/che-machine-logs <2> ----- -<1> Server logs -<2> Workspace logs - -There may be cases of logs encoding settings when Che master logs are not stored in the location above. - -User data is stored in: - ----- -/instance/data/che <1> ----- -<1> Project backups (synchronized projects from remote workspaces) - -Instance configuration is generated by Che and is updated by the internal configuration utilities. Do not modify these generated configuration files. Store them at: - ----- -/instance/che.ver.do_not_modify <1> -/instance/docker-compose-container.yml <2> -/instance/docker-compose.yml <3> -/instance/config <4> ----- -<1> Version of che installed -<2> Docker compose to launch Che from within a container -<3> Docker compose to launch Che from the host without container -<4> Configuration files for Che, which are volume mounted into containers - -[id="jdbc-configuration"] -== Configuring JDBC - -Eclipse Che uses the http://www.h2database.com/html/main.html[H2] database for single-user builds and PostgreSQL database in multi-user mode. - -Depending on the used database, the JDBC Connection pool is initialized with respective default values. These values can be overridden in the `che.env` file. - -Example of configuration for using the H2 database (default for single-user Che): - ----- -CHE_JDBC_USERNAME= -CHE_JDBC_PASSWORD= -CHE_JDBC_DATABASE=jdbc:h2:che -CHE_JDBC_URL=jdbc:postgresql://postgres:5432/dbche -CHE_JDBC_DRIVER__CLASS__NAME=org.h2.Driver -CHE_JDBC_MAX__TOTAL=8 -CHE_JDBC_MAX__IDLE=2 -CHE_JDBC_MAX__WAIT__MILLIS=-1 ----- - -Example of configuration for using the PostgreSQL database (default for multi-user Che): - ----- -CHE_JDBC_USERNAME=pgche -CHE_JDBC_PASSWORD=pgchepassword -CHE_JDBC_DATABASE=dbche -CHE_JDBC_URL=jdbc:postgresql://postgres:5432/dbche -CHE_JDBC_DRIVER__CLASS__NAME=org.postgresql.Driver -CHE_JDBC_MAX__TOTAL=20 -CHE_JDBC_MAX__IDLE=10 -CHE_JDBC_MAX__WAIT__MILLIS=-1 ----- - -[id="oauth"] -== Configuring OAuth - -You can configure using Google, GitHub, Microsoft, or BitBucket OAuth for Git operations. See: link:version-control.html#github-oauth[Version Control]. - -[id="stacks-and-samples"] -== Creating stacks and samples - -link:stacks.html[Stacks] define the recipes used to create workspace runtimes. They appear in the stack library of the dashboard. You can create your own stacks. - -The `CHE_PREDEFINED_STACKS_RELOAD__ON__START` variable (set to `false` by default) defines the stack loading policy. When set to `false`, stacks are loaded from a JSON file only once during database initialization. When set to `true`, the JSON file is sourced every time the Che server starts. - -Code samples allow you to define sample projects that are cloned into a workspace if the user chooses it when creating a new project. You can add your own code samples. In your `${LOCAL_DATA_DIR}/instance/data/templates` directory, create a JSON file with your custom samples. It will be sourced each time the Che server starts. For an example of a default Che `samples.json` file, see https://github.com/eclipse/che/blob/master/ide/che-core-ide-templates/src/main/resources/samples.json[samples.json]. - -[id="workspace-limits"] -== Placing workspace limits - -You can place limits on how users interact with the system to control the overall system resource usage. You can define the number of workspaces created, RAM consumed, idle timeout, and a variety of other parameters. - -You can also set limits on Docker’s allocation of CPU to workspaces, which may be necessary if you have a very dense workspace population where users are competing for limited physical resources. - -Workspace idle timeout can be configured in the `che.env` file so that the inactive workspaces are stopped automatically over this length of time in milliseconds. By default, this value is set to `3600000` (1 hour). If set to `0`, workspaces will not stop automatically. Currently, keyboard and mouse interactions in the IDE and HTTP requests to the `ws-agent` count as activity. - -[id="setting-the-java-opts-environment-variable"] -== Setting the JAVA_OPTS environment variable - -There can be several Java processes running in a workspace machine. Some Java agents are special purpose agents started in a machine to provide core and additional IDE functionalities. These are workspace agents and a link:dependency-management.html[Maven plugin] that are both started in the JVM. You can run your own Java programs and use build tools like Maven. A set of the following environment variables can help optimize RAM consumption: - -=== User-defined environment variables - -You can provide your own link:env-variables.html[environment variables] per workspace machine. - -`pass:[JAVA_OPTS]`:: -machine-wide java opts - -`pass:[MAVEN_OPTS]`:: -machine-wide maven opts - -`pass:[CHE_WORKSPACE_WSAGENT__JAVA__OPTIONS]`:: -java opts to adjust java opts of ws-agent - -`pass:[CHE_WORKSPACE_MAVEN__SERVER__JAVA__OPTIONS]`:: -java opts to adjust java opts of the maven server - -Che administrators (anyone with access to the `che.env` file or the Che server environment directly) can override the following user-defined environment variables: - -`pass:[CHE_WORKSPACE_JAVA__OPTIONS]`:: -Overrides the default value of JAVA_OPTS of all workspaces - -`pass:[CHE_WORKSPACE_MAVEN__OPTIONS]`:: -Overrides the default value of MAVEN_OPTS of all workspaces - -`pass:[CHE_WORKSPACE_WSAGENT__JAVA__OPTIONS]`:: -Overrides the default value of JAVA_OPTS of all ws-agents - -`pass:[CHE_WORKSPACE_MAVEN__SERVER__JAVA__OPTIONS]`:: -Overrides the default value of JAVA_OPTS of all maven servers - -For default values of the environment variables, see the https://github.com/eclipse/che/blob/master/dockerfiles/init/manifests/che.env#L127-L141[che.env] file. - -[id="hostname"] -== Hostname - -Hostname is the IP address or DNS name where the Che endpoint provides service to the users. - -* When run on a local system, the value of the hostname is auto-detected as the IP address of your Docker daemon. - -* On many systems, especially those from cloud hosting providers like DigitalOcean, you may have to explicitly set this to the external IP address or DNS entry provided by the provider. - -You can edit this value in the `che.env` file and restart Che, or you can pass it during initialization. - ----- -$ docker run -e CHE_HOST= eclipse/che: start ----- - -[id="networking"] -== Networking - -Eclipse Che makes connections between three entities: the browser, the Che server running in a Docker container, and a workspace running in a Docker container. - -To distribute these components on different nodes, hosts, or IP addresses, add additional configuration parameters to bridge the different networks. - -The Che server and your Che workspaces are within containers governed by the Docker daemon. You must ensure that these components have bridges to communicate with the daemon. - -Your browser, the Che server, and the Che workspace being on the same node ensures that the `localhost` configuration works correctly. - -=== WebSockets - -Che relies on WebSockets to stream content between workspaces and the browser. There are many networks and firewalls that block portions of the WebSocket communication. If there are any initial configuration issues, this is a likely cause of the problem. - -=== Topology - -The Che server runs in its own Docker-formatted container, `Che Docker Container`. Each workspace has an embedded runtime that can be a set of additional Docker containers, `Docker Container(n)`. All containers are managed by a common Docker daemon, `docker-ip`, making them siblings of each other. This includes the Che server and its workspaces. Each workspace runtime environment has a set of containers that is a sibling to the Che server and is not a child. - -=== Connectivity - -The browser client initiates communication with the Che server by connecting to `che-ip`. This IP address must be accessible by your browser clients. Internally, Che runs on Tomcat that is bound to port `8080`. This port can be altered by setting the `CHE_PORT` variable during start or in the `che.env` file. - -When a user creates a workspace, the Che server connects to the Docker daemon at `docker-ip` and uses the daemon to launch a new set of containers that power the workspace. These workspace containers have a Docker-configured IP address, `workspace-container-ip`. The `workspace-container-ip` is not usually reachable by your browser host. `docker-ip` is used to establish the connections between the browser and workspace containers. - -The Che server provides workspace containers with the following environment variables: - -`CHE_API_INTERNAL`:: -* Points to the internal API endpoint that is accessible across other machines within the workspace. -* Its value is taken from the Che server `CHE_INFRA_DOCKER_MASTER__API__ENDPOINT` variable that can be initialized either by the CLI or the default value defined in the `che.properties` file. - -`CHE_API_EXTERNAL`:: -* Points to the external API endpoint that is used by the browser clients. -* Its value is taken from the Che server `CHE_API` variable. -* Its default value is defined in the `che.properties` file. - -`CHE_API`:: -* Points to the same value as `CHE_API_INTERNAL` for backward compatibility. - -[NOTE] -==== -The `CHE_API` environment variable will be deprecated in a future release. -==== - -When Che is booting or starting a workspace, Che goes through a progression algorithm to establish the protocol, IP address, and port to establish communication. You can override certain parameters in Che’s configuration to overcome issues with the Docker daemon, workspaces, or browsers being on different networks. - -=== Browser -> Che server - -The `${CHE_HOST}:${SERVER_PORT}/wsmaster/api` variable is the default. However, requests are sent to the IP or hostname in your browser address bar. You can also use the value of `che.api`. - -=== Che server -> Docker daemon progression - -Use the value of the `che.infra.docker.daemon_url` variable. You can also use one of the following values: - -* The value of the `DOCKER_HOST` system variable - -* The Unix socket over `unix:///var/run/docker.sock` - -* The default `docker0` IP address - `172.17.42.1` - -=== Che Server -> Workspace Connection - -Use the value of the `che.docker.ip` variable. Or, use the address of the docker0 bridge network, if available. - -=== Browser -> Workspace Connection - -Use the value of the `che.docker.ip.external` variable. Or, use the `che.docker.ip` value, or the value provided by the `ws container inspect` command. - -=== Workspace Agent -> Che Server - -If set, use the value of the `pass:[CHE_INFRA_DOCKER_MASTER__API__ENDPOINT]` variable. The default value is `http://che-host:${SERVER_PORT}/api`; here, `che-host` is the IP of docker0 (Linux) or the VM IP (macOS and Windows). - -When Che is configured with firewalls, routers, networks, and hosts, the default values detected, as a known behavior, establish faulty connections. To run a test that makes connections between simulated components reflect the networking setup of Che as it is configured, execute the `docker run eclipse/che info --network` command. It is acceptable that all connections may not pass for Che to be properly configured. For example, on a Windows machine, this output may exist indicating that `localhost` is not an acceptable domain for communication but the IP address `10.0.75.2` is. - ----- -INFO: --------------------------------------- -INFO: -------- CONNECTIVITY TEST -------- -INFO: --------------------------------------- -INFO: Browser => Workspace Agent (localhost): Connection failed -INFO: Browser => Workspace Agent (10.0.75.2): Connection succeeded -INFO: Server => Workspace Agent (External IP): Connection failed -INFO: Server => Workspace Agent (Internal IP): Connection succeeded ----- - -You can also perform additional tests against an already-running Che server. Use the `docker ps` and `docker inspect` commands to get the container name and IP address of your Che server. Then, you can run additional tests: - -* Browser => Workspace Agent (External IP): -+ ----- -$ curl http://:/wsagent/ext/ ----- -+ -* Server => Workspace Agent (External IP): -+ ----- -docker exec -ti curl http://:/wsagent/ext/ ----- -+ -* Server => Workspace Agent (Internal IP): -+ ----- -docker exec -ti curl http://:4401/wsagent/ext/ ----- - -=== DNS resolution - -Che and its workspaces, by default, inherit DNS resolver servers from the host. You can override these resolvers by setting the `CHE_DNS_RESOLVERS` variable in the `che.env` file and restarting Che. DNS resolvers allow programs and services that are deployed within a user workspace to perform DNS lookups with public or internal resolver servers. In some environments, custom resolution of DNS entries (usually to an internal DNS provider) is required to enable the Che server and the workspace runtimes to have lookup ability for internal services. - -To update your `che.env` file with a comma-separated list of resolvers: - ----- -CHE_DNS_RESOLVERS=10.10.10.10,8.8.8.8 ----- - -[id="single-port-routing"] -== Single-port routing - -Single-port routing is currently not supported in Che 6. - -[id="private-images"] -== Private images - -When users create a workspace in Eclipse Che, they must select a container image to power the workspace. Che provides stacks that reference images hosted at the public DockerHub that do not require any authenticated access to pull. You can provide your own images that are stored in a local private registry or at Docker Hub. The images may be publicly or privately visible, even if they are a part of a private registry. - -If the stack images that Che wants to pull require authenticated access to any registry then you must configure registry authentication. - -In the `che.env` file: - ----- -CHE_DOCKER_REGISTRY_AUTH_REGISTRY1_URL=url1 -CHE_DOCKER_REGISTRY_AUTH_REGISTRY1_USERNAME=username1 -CHE_DOCKER_REGISTRY_AUTH_REGISTRY1_PASSWORD=password1 - -CHE_DOCKER_REGISTRY_AWS_REGISTRY1_ID=id1 -CHE_DOCKER_REGISTRY_AWS_REGISTRY1_REGION=region1 -CHE_DOCKER_REGISTRY_AWS_REGISTRY1_ACCESS__KEY__ID=key_id1 -CHE_DOCKER_REGISTRY_AWS_REGISTRY1_SECRET__ACCESS__KEY=secret1 ----- - -There are different configurations for AWS EC2 and the Docker registry. Using the numerical indicator in the environment variable, you can define as many different registries as you want. To add several registries, copy the set of properties and append `REGISTRY[n]` for each variable. - -=== Pulling private images in stacks - -After you have configured private registry access, any Che stack that has `FROM /` that requires authenticated access will use the credentials provided in the `che.env` file to access the registry. - ----- -# Syntax -FROM /: - -# Example: -FROM my.registry.url:9000/image:latest ----- - -To read more about registries, see https://docs.docker.com/registry/[Docker documentation]. - -[id="privileged-mode"] -== Enabling privileged mode - -Docker privileged mode allows a container to have root-level access to the host from within the container. This enables containers to do more than they normally can but also presents security risks. You can enable your workspaces to have privileged mode, giving your users root-level access to the host where Che is running (in addition to root access of their workspaces). Privileged mode is necessary if you want to enable certain features such as Docker in Docker. - -By default, Che workspaces powered by a Docker container are not configured with Docker privileged mode. There are many security risks associated with activating this feature. Review the various issues mentioned in the blogs posted online. - -To update the `che.env` file: - ----- -CHE_DOCKER_PRIVILEGED=true ----- - -[id="mirroring-dockerhub"] -== Mirroring DockerHub - -If you run a private registry internal to your company, you can https://docs.docker.com/registry/recipes/mirror/[optionally mirror DockerHub]. Your private registry will download and cache any images that your users reference from the public DockerHub. You must https://docs.docker.com/registry/recipes/mirror[configure your Docker daemon to make use of mirroring]. - -[id="using-docker-in-workspaces"] -== Using Docker in workspaces - -To allow your users to work with projects that have their own container images and Docker build capabilities inside of their workspaces, you must configure the workspaces to work with Docker. Following are the three options to configure the workspaces: - -* Activate Docker privileged mode where your user workspaces have access to the host. Update your `che.env` to allow all Che workspace machines and containers to have privileged rights: -+ ----- -CHE_DOCKER_PRIVILEGED=true; ----- - -* Configure Che workspaces to mount the host Docker daemon socket file. Update your `che.env` to allow all Che workspaces to mount their host daemon when starting: -+ ----- -CHE_WORKSPACE_VOLUME=/var/run/docker.sock:/var/run/docker.sock; ----- - -* Configure the Docker daemon to listen to the TCP socket and specify the `DOCKER_HOST` environment variable in the workspace machine. Each host environment will have different network topology and configuration. The following is an example. -+ -To configure your Docker daemon to listen on TCP: -+ -. Add the following to your Docker configuration file (on Ubuntu, the file is located at `/etc/default/docker`. For location of the Docker configuration file for your OS, see the https://docs.docker.com/engine/reference/commandline/dockerd/[Docker documentation]). Listen using the default unix socket on a specific IP address on the host. This varies depending on your host OS. -+ ----- -# dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375 ----- -+ -Verify that the Docker API is responding at: `http://$IP:2375/containers/json`. -+ -. Export the `DOCKER_HOST` variable in your workspace. You can do this in the terminal or make it permanent by adding `ENV DOCKER_HOST=tcp://$IP:2375` to a workspace recipe; here, `$IP` is the IP address of the Docker daemon machine. -+ -On a workspace machine: -+ ----- -$ docker -H tcp://$IP:2375 ps ----- -+ -or: -+ ----- -$ export DOCKER_HOST="tcp://$IP:2375" -$ docker ps ----- - -These three options allow user workspaces to perform `docker` commands from within their workspace to create and work with containers that will be outside the workspace. This means that your users' workspaces are now equivalent to their personal computers where they would normally perform the `docker build` and `docker run` commands. - -You must ensure that your user workspaces are powered from a stack that has Docker installed inside of it. Che's default Docker recipe images do not have Docker installed, but you can build your own image. - -// [TODO: link to custom stack authoring]. - - -[id="development-mode"] -== Debugging in development mode - -You can debug the Che binaries that are running within the Che server. You can debug either the binaries that are included within the `eclipse/che-server` image that you download from DockerHub or you can mount a local Che Git repository to debug binaries built in a local assembly. By using local binaries, Che developers can perform a rapid edit-build-run cycle without having to rebuild Che’s Docker images. - -To activate development mode, pass the `--debug` argument to any command on the CLI. - -To activate development mode with embedded binaries: - ----- -$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data \ - eclipse/che: [COMMAND] --debug ----- - -You can replace the binaries in your local image with local binaries by mounting the Che Git repository to `:/repo` in your `docker run` command. - ----- -$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data \ - -v :/repo \ - eclipse/che: [COMMAND] --debug ----- - -Optionally, you can use your local binaries in production mode by mounting `:/repo` without passing the `--debug` argument. Files from two locations from your Che source repository will be used instead of those in the image: - -* During the `che config` phase, the source repository’s `/dockerfiles/init/modules` and `/dockerfiles/init/manifests` will be used instead of the ones that are included in the `eclipse/che-init` container. - -* During the `che start` phase, a local assembly from `assembly/assembly-main/target/` is mounted into the `eclipse/che-server` runtime container. You must run the `mvn clean install` on the `assembly/assembly-main/` directory prior to activating development mode. - -Mounting `:/repo` will also make use of your repository’s Puppet manifests and other files (replacing those that are stored within the `eclipse/che-server` base image). To only mount a new set of assemblies and ignore the other items in a repository, mount `:/assembly` to a directory that is the base of a binary. Mounting a `.tgz` file is not supported as yet. - -[subs=+quotes] ----- -$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock \ - -v ____:/data \ - -v ____:/assembly \ - eclipse/che:____ _[COMMAND]_ ----- - -To activate JPDA suspend mode for debugging Che server initialization, add the following in the `che.env` file: - ----- -CHE_DEBUG_SUSPEND=true ----- - -To change the Che debug port, add the following in the `che.env` file: - ----- -CHE_DEBUG_PORT=8000 ----- - -[id="production-mode"] -== Building images in production mode - -To build your own `INIT` and `SERVER` images to have custom configuration and binaries, take the following steps: - -. Clone the https://github.com/eclipse/che[Che repository]. - -. Copy the `dockerfiles` directory to the root of your custom assembly. - -. Configure your Che server: - -.. To have no custom configuration in your custom Che server, build the Che server image by executing the following command: -+ ----- -$ dockerfiles/build.sh ----- -+ -.. Tag the resulted image as needed. - -.. To customize the configuration for your custom Che server and to allow users to override these custom configuration, in the `che.env` file, build your own `INIT` image with a custom https://github.com/eclipse/che/blob/master/dockerfiles/init/manifests/che.env[`che.env`] file. - -. Start the custom binaries. -+ ----- -$ docker run -ti -v '/var/run/docker.sock:/var/run/docker.sock \ - -v /local/data/path:/data \ - -e "IMAGE_CHE=your/che-server" \ - -e "IMAGE_INIT=your/init-image" eclipse/che::{{site.latest_6_x_version}} start' ----- - -You have built `IMAGE_CHE` in `dockerfiles/che` and `IMAGE_INIT` is the one from `dockerfiles/init`. - -[id="docker-unix-socket-mounting-vs-tcp-mode"] -== Docker Unix socket mounting vs TCP mode - -The `-v /var/run/docker.sock:/var/run/docker.sock` command is used for mounting a Unix socket, so that when a process inside the container communicates with the Docker daemon, the process is redirected to the same socket on the host system. - -However, peculiarities of file systems and permissions may make it impossible to invoke Docker processes from inside a container. If this happens, the Che startup scripts will print an error about being unable to reach the Docker daemon with guidance on how to resolve the issue. - -An alternative solution is to run the Docker daemon in TCP mode on the host and export the `DOCKER_HOST` environment variable in the container. You can make the Docker daemon listen on both Unix sockets and TCP. On the host running the Docker daemon, run the following commands: - -. Set this environment variable and restart the Docker daemon. -+ ----- -DOCKER_OPTS=" -H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock" ----- -+ -. Verify that the Docker API is responding at the following address: `http://localhost:2375/info`. - -. Run the Che container with the `DOCKER_HOST` environment variable set to the IP address of the `docker0` or the `eth0` network interface. If `docker0` is running on 1.1.1.1, run the following command: -+ ----- -$ docker run -ti -e DOCKER_HOST=tcp://1.1.1.1:2375 \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v ~/Documents/che-data1:/data eclipse/che:{{site.latest_6_x_version}} start ----- -+ -. Alternatively, you can save this environment variable in the `che.env` file and restart Che. - -[id="proxiesfirewallsports"] -== Installing Che behind a proxy - -To install and operate Che behind a proxy, take the following steps: - -. Configure each physical node’s Docker daemon with proxy access. - -. Optionally, to restrict the users' Internet access, override the workspace proxy settings for them. - -. Before starting Che, configure the https://docs.docker.com/engine/admin/systemd/#/http-proxy[Docker daemon for proxy access]. When installing Che while having Docker for Windows or Docker for macOS installed on your desktop, these utilities have a GUI in their settings that let you set the proxy settings directly. - -. Ensure that your `HTTP_PROXY` and `HTTPS_PROXY` that you set in the Docker daemon have a protocol and port number. Ensure that you provide a fully qualified proxy location. - -If you configure `HTTP_PROXY` or `HTTPS_PROXY` in your Docker daemon, Che adds `localhost,127.0.0.1,CHE_HOST` to your `NO_PROXY` value; here, `CHE_HOST` is the DNS or IP address. We recommend that you add the short and long form DNS entry to your Docker’s `NO_PROXY` setting if it is not already set. - -The following is an example of adding some values to the `che.env` file that contain some proxy overrides. You can optionally modify these with overrides. - ----- -CHE_HTTP_PROXY= -CHE_HTTPS_PROXY= -CHE_NO_PROXY=localhost,127.0.0.1, -CHE_HTTP_PROXY_FOR_WORKSPACES= -CHE_HTTPS_PROXY_FOR_WORKSPACES= -CHE_NO_PROXY_FOR_WORKSPACES=localhost,127.0.0.1, ----- - -The last three entries are injected into workspaces created by your users. This gives your users access to the Internet from within their workspaces. You can comment out these entries to disable access. If that access is turned off, the default templates with source code fail to be created in workspaces as those projects are cloned from GitHub. Your workspaces are still functional and only template cloning is prevented. - -On Linux, a firewall may block inbound connections from within Docker containers to your localhost network. As a result, the workspace agent is unable to ping the Che server. You can check for a firewall and configure it to allow ther required connections. - -Firewalls typically cause traffic problems when starting a new workspace. There are certain network configurations where we direct networking traffic between workspaces and Che through external IP addresses that can flow through routers or firewalls. If ports or protocols are blocked, certain functions will be unavailable. - -[id="running-che-behind-firewall"] -== Running Che behind a firewall - -Check whether required ports are open and, if necessary, configure the firewall to keep the ports open. - -[id="configuring-firewall-on-linux"] -=== Configuring firewall on Linux - -. Check if a firewall is running: -+ ----- -# systemctl status firewalld ----- -+ -. Check the list of open ports, and verify that ports `8080/tcp` and `32768-65535/tcp` are open: -+ ----- -# firewall-cmd --list-ports ----- -+ -. Optionally, open ports on your local firewall. For example: -+ ----- -# firewall-cmd --permanent --add-port=8080/tcp ----- -+ -Use this command to open other ports, too. - -[id="configuring-firewall-on-macos"] -=== Configuring firewall on macOS - -. Verify that ports `8080/tcp` and `32768`--`65535/tcp` are open: -+ ----- -$ nmap -Pn -p T:8080,T:32768-65535 localhost ----- -+ -. If a port is closed, open it by editing the `/etc/pf.conf` file. For example, to open port `8080` for TCP for all interfaces, add the following line to the file: -+ ----- -pass in proto tcp from any port to any port 8080 ----- -. Test the settings: -+ ----- -# pfctl -vnf /etc/pf.conf ----- -+ -Restart the firewall: *System Preferences > Security & Privacy > Firewall > Turn Off Firewall*. - -[id="configuring-firewall-on-windows"] -== Configuring firewall on Windows - -There are many third-party firewall services. Different versions of Windows also have different firewall configurations. The built-in Windows firewall can be configured in the *Control Panel* under *System and Security*: - -. In the left pane, right-click *Inbound Rules*, and then click *New Rule* in the action pane. - -. In the *Rule Type* dialog box, select *Port*, and click *Next*. - -. In the *Protocol and Ports* dialog box, select *TCP*. - -. Select specific local ports, enter the port number to be opened, and click *Next*. - -. In the *Action* dialog box, select *Allow the Connection*, and click *Next*. - -. In the *Name* dialog box, type a name and description for this rule, and click *Finish*. - -[id="limiting-che-ports"] -== Limiting Che ports - -Eclipse Che uses Docker to power its workspaces. Docker uses the https://en.wikipedia.org/wiki/Ephemeral_port[ephemeral port range] when exposing ports for services running in the container. So when a Tomcat server is started on port `8080` inside a Che workspace, Docker automatically selects an available port from the ephemeral range at runtime to map to that Tomcat instance. - -Docker will select its ports from anywhere in the ephemeral range. To reduce the size of the ephemeral range to improve security you can do so. Note that each Che workspace will use at least two ports and, additionally, ports are required for the services that the user adds to their workspace. - -Limiting the ephemeral range can only be done at the host level. To read more about it and some of the risks in doing so, see the http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html[Ephemeral Port Range]. - -To change the ephemeral range: - -* On Linux, see http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Linux[changing ephemeral ports on Linux]. - -* On Windows, see http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Windows[changing epemeral ports on Windows]. diff --git a/src/main/pages/che-6/setup-docker/docker-multi-user.adoc b/src/main/pages/che-6/setup-docker/docker-multi-user.adoc deleted file mode 100644 index 1cafe54e08..0000000000 --- a/src/main/pages/che-6/setup-docker/docker-multi-user.adoc +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "Multi-user: Installation on Docker" -keywords: openshift, installation -tags: [installation, docker] -sidebar: che_6_docs -permalink: che-6/docker-multi-user.html -redirect_from: docker-multi-user.html -folder: che-6/setup-docker ---- - -[id="system-requirements"] -== System requirements - -* Minimum 4GB of RAM (for the three Che containers and one 2GB workspace) -* 2 CPUs -* Ports `8080`, `5050`, and the https://en.wikipedia.org/wiki/Ephemeral_port[ephemeral port] range publicly available for inbound connections (`32768-65535`) - -[id="known-issues"] -== Known issues - -Currently, when running Che multi-user on Windows, PostgreSQL has issues with file permissions that prevents the database from starting. As a workaround, mount a local storage path that is not a Windows file system mount point: - -`-v /chedata/:/data` - -It is not recommended to run Che multi-user on Windows for production use. - -[id="run-syntax"] -== Running Che multi-user - -Following is the command to run Che multi-user: ----- -docker run -it -e CHE_MULTIUSER=true -e CHE_HOST=${EXTERNAL_IP} -v /var/run/docker.sock:/var/run/docker.sock -v ~/.che-multiuser:/data eclipse/che:{{site.latest_6_x_version}} start ----- - -Here: - -* `~/.che-multiuser` is any local path. Che data and configuration is stored at this location. - -* `${EXTERNAL_IP}` should be a public IP accessible to all users who will access the Che instance. If you are running Che locally and will access it from within the same network, you may omit the `CHE_HOST` environment variable from the command. In this case, Che CLI will attempt to auto-detect your server IP. - -[NOTE] -==== -Auto-detection may produce erroneous results, especially in case of a complex network setup. If you run Che as a cloud server that is accessible by external users, we recommend explicitly providing an external IP for the `CHE_HOST` variable. -==== - -You must access Che multi-user using the hostname/IP specified in the `CHE_HOST` variable or manually add redirect URIs and Web Origins to the link:user-management.html#che-and-keycloak[Keycloak client]. - -[id="the-che-multiuser-variable"] -== The CHE_MULTIUSER variable - -The `CHE_MULTIUSER` variable when set to `true`, instructs the Che CLI to generate a special `Docker Compose` file that will be executed to produce the configuration and run the following: - -* Keycloak container with pre-configured realm and clients -* PostgreSQL container that will store Keycloak and Che data -* Che server container with a special build of multi-user Che assembly - -[id="deployment-diagram"] -== Deployment diagram - -Che multi-user on Docker does not differ much from a link:openshift-multi-user.html#deployment-diagram[multi-user deployment on OpenShift] in terms of architecture and communication between services. Following are some of the differences between Che multi-user on Docker and multi-user deployment on OpenShift: - -* Containers instead of pods. -* Volume mounts instead of PVCs. -* To pre-build Keycloak and Postgres images, configuration is mounted into containers. -* Port `5050` must be publicly available (OpenShift uses routes and services). -* Che CLI pre-configures and populates values for environment variables like `CHE_HOST`, that is then used in Keycloak configuration files. - -[id="whats-next"] -== What is next? - -When you have a running Che multi-user instance, the next step is to link:user-management.html[create a user, setup GitHub OAuth, and log in]. - diff --git a/src/main/pages/che-6/setup-docker/docker-single-user.adoc b/src/main/pages/che-6/setup-docker/docker-single-user.adoc deleted file mode 100644 index b503a0facd..0000000000 --- a/src/main/pages/che-6/setup-docker/docker-single-user.adoc +++ /dev/null @@ -1,431 +0,0 @@ ---- -title: "Single-User: Installation on Docker" -keywords: docker, installation -tags: [installation, docker] -sidebar: che_6_docs -permalink: che-6/docker-single-user.html -redirect_from: docker-single-user.html -folder: che-6/setup-docker ---- - -This section walks you through the single-user installation of Che on Docker. - -*Prerequisites* - -* Use Docker version 17 or higher. Older versions are untested but may work (1.13 or higher). To install the latest Docker version, see https://docs.docker.com/install/. -+ ----- -wget -qO- https://get.docker.com/ | sh ----- -+ -* Operating Systems: Linux, macOS, Windows. -+ -[IMPORTANT] -==== -macOS users must create an IP alias using the `sudo ifconfig lo0 alias $IP` command. Here, `$IP` is the IP that you can obtain from Docker for the Mac application from *Preferences* -> *Advanced* -> *Docker subnet* or by running the following command: - ----- -docker run --rm --net host eclipse/che-ip:{{site.latest_6_x_version}} ----- -==== -+ -* Minimum one CPU, 2GB of RAM, 3GB disk space. - -The default port required to run Che is `8080`. When Che starts, it performs a check to verify that the port is available. Pass the `-e CHE_PORT=` argument in the Docker portion of the start command to change the port that you want Che to start on. - -Ports used by Che must be open and must not be blocked by firewalls or other applications already using the same ports. - -In this context, we recognize two types of ports: - -* Internal ports: These are ports within a local network, such as when Che is installed on the user's local desktop or laptop. - -* External ports: These are ports outside a local network, such as when using a remote Che server on a cloud host provider. - -All ports are TCP unless otherwise noted. - -[width="100%",cols="34%,33%,33%",options="header",] -|=== -|Port |Service |Notes -|8080 |Tomcat Port |Che server default port. -|8000 |Server Debug Port |Users developing Che extensions and custom assemblies use this debug port to connect a remote debugger to the Che server. -|32768-65535 |Docker and Che Agents |Users who launch servers in their workspace bind to ephemeral ports in this range. This range can be limited. -|=== - -[id="known-issues"] -== Known issues - -To view the https://github.com/eclipse/che/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Akind%2Fbug[known issues], search GitHub issues for Che having the *kind/bug* label. - -Following are the two known issues in which features work on Docker 1.13 and higher but do not work on Docker 1.12: - -* SELinux: https://github.com/eclipse/che/issues/4747 -* `pass:[CHE_DOCKER_ALWAYS__PULL__IMAGE]`: https://github.com/eclipse/che/issues/5503 - -Fedora and RHEL or CentOS users may encounter issues with SElinux. To fix the issue, disable SElinux using the `setenforce 0` command. If using the latest Docker version and disabling SElinux does not fix the issue, file a ticket on the https://github.com/eclipse/che/issues[issues] page. - -[id="quick-start"] -== Quickstart - -To start Che, run the following command where `` is a local directory: - ----- -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v :/data eclipse/che:{{site.latest_6_x_version}} start ----- - -The following is an example of the output: - ----- -$ docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v ~/Documents/che-data1:/data eclipse/che:{{site.latest_6_x_version}} start -INFO: (che cli): {{site.latest_6_x_version}} - using docker 17.10.0-ce / native -INFO: (che config): Generating che configuration... -INFO: (che config): Customizing docker-compose for running in a container -INFO: (che start): Preflight checks - mem (1.5 GiB): [OK] - disk (100 MB): [OK] - port 8080 (http): [AVAILABLE] - conn (browser => ws): [OK] - conn (server => ws): [OK] - -INFO: (che start): Starting containers... -INFO: (che start): Services booting... -INFO: (che start): Server logs at "docker logs -f che" -INFO: (che start): Booted and reachable -INFO: (che start): Ver: {{site.latest_6_x_version}} -INFO: (che start): Use: http://172.19.20.180:8080 -INFO: (che start): API: http://172.19.20.180:8080/swagger ----- - -[NOTE] -==== -You can run the `docker run -it eclipse/che:{{site.latest_6_x_version}} start` command, which will fail by default. But, it will print options on how to proceed. -==== - -`eclipse/che` is a Docker image that manages the other Docker images and supporting utilities that Che uses during its configuration or operational phases. It is recommended to install Che using the `eclipse/che` image. To run the `che-server` image directly, see link:#run-without-cli[Run Che-Server directly]. - -[id="versions"] -== Versions - -Each version of Che is available as a Docker image tagged with a label that matches the version, such as `eclipse/che:6.0.0`. For a list of the available versions, browse https://hub.docker.com/r/eclipse/che/tags/[Docker Hub]. - -The following table lists the _redirection_ labels that reference special versions of Che: - -[cols=",",options="header",] -|=== -|Variable |Description -|`nightly` |The nightly build. -|=== - -The software referenced by these labels can change over time. Because Docker will cache images locally, the `eclipse/che:` image that you are running locally may not be current with the one cached on Docker Hub. Additionally, the `eclipse/che:` image that you are running references a manifest of Docker images that Che depends upon, which can also change if you are using these special redirection tags. - -If you use a CLI version that mismatches with the one that was installed, you will encounter an error. - -To avoid issues caused by using the `nightly` redirections, ensure that you adhere to the following: - -. Use the `docker pull eclipse/che:{{site.latest_6_x_version}}` command to ensure that you have the most recent Docker version. -. When using the CLI, commands that use other Docker images have an optional `--pull` and `--force` command line option https://hub.docker.com/r/eclipse/che/[that instructs the CLI to check Docker Hub] for a newer version and pull it. Using these flags slows down performance, but it ensures that your local cache is up-to-date. - -If you run Che using a tagged version that is not a redirection label, such as `6.0.0`, you will not encounter the caching issues because the installed software is tagged and specific to the particular version and does not change over time. - -[id="volume-mounts"] -== Configuring Che using volume mounts - -Use volume mounts to configure certain parts of Che. The presence or absence of certain volume mounts triggers certain behaviors in the system. For example, you can mount a Che source git repository with `:/repo` to use the Che source code instead of the binaries and the configuration that is shipped with the Docker images. - -At a minimum, you must mount a local path to `:/data`. Che installs its configuration, user data, version, and log information at this location. Che creates a `cli.log` file in this location to debug unexpected behavior while running the system. You can also create a `che.env` file in this directory. This file contains all the administrative configurations that you can set or override in a single location. - -You can also use volume mounts to override the location of where the user or backup data is stored. By default, these directories are created as sub-directories of the location that you mount to `:/data`. However, if you do not want the `instance/` and `backup/` directories to be sub-directories, you can set them individually with separate overrides. - ----- -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -v :/data/instance - -v :/data/backup - eclipse/che: [COMMAND] ----- - -[width="100%",cols="34%,33%,33%",options="header",] -|=== -|Local Location |Container Location |Usage -|`/var/run/docker.sock` |`/var/run/docker.sock` |This is how Che gets access to the Docker daemon. This instructs the container to use your local Docker daemon when Che wants to create its own containers. -|`//lib` |`/data/lib` |Inside the container, a copy of important libraries that your workspaces will need are made and are placed into the `lib/` directory. When Che creates a workspace container, that container uses your local Docker daemon and the Che workspace looks for these libraries in your local `lib/` directory. This helps in getting the files from inside the container out on your local host. -|`//workspaces` |`/data/workspaces` |The location of your workspace and project files. -|`//storage`   |`/data/storage`   |The location where Che stores the meta information that describes the various workspaces, projects, and user preferences.   -|=== - -[id="hosting"] -== Hosting Che - -To host Che on a cloud service like DigitalOcean, AWS, or Scaleways, the `CHE_HOST` variable must be set to the public IP address of the server or its DNS. - -You can automatically set the `CHE_HOST` variable by running the internal utility `docker run --net=host eclipse/che-ip:{{site.latest_6_x_version}}` command. This utility is usually accurate on desktops, but it usually fails on hosted servers. You can explicitly set this value to the IP address of your server: - ----- -docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock - -v :/data - -e CHE_HOST= - eclipse/che: [COMMAND] ----- - -[id="run-on-different-port"] -== Running Che on different ports - -Either set the `CHE_PORT=$your_port` variable in the link:docker-config.html#saving-configuration-in-version-control[che.env] file or pass it as an environment variable in your `docker run` syntax: `-e CHE_PORT=$your_port`. - -[id="run-as-user"] -== Running Che as different users - -On Linux or macOS, you can run the Eclipse Che container with different user identities. By default, you run the Che container as the `root` user. You can pass the `--user uid:gid` or the `-e CHE_USER=uid:gid` argument as a `docker run` parameter before the `eclipse/che` Docker image. The CLI starts the `eclipse/che-server` image with the same `uid:gid` combination and mounts the `/etc/group` and `etc/passwd` files. When Che is run as a custom user, all files written from within the Che server to the host (such as `che.env` or `cli.log` files) are written to the disk with the custom user as the owner of the files. This feature is not available on Windows. - -[id="offline-installation"] -== Installing Che when offline - -Che supports offline (disconnected from the Internet) installation and operation. This is helpful for restricted environments, regulated datacenters, or offshore installations. The offline installation downloads the CLI, core system images, and any stack images while you are within a network DMZ with Docker Hub access. You can then move those files to a secure environment and start Che. - -. Save Che images. -+ -While connected to the Internet, download Che Docker images: -+ ----- -docker run eclipse/che: offline ----- -+ -The CLI downloads images and saves them to the `/backup/*.tar` file with each image saved as its own file. You can save these files at a different location by mounting a local directory to the `:/data/backup` directory. The version tag of the CLI Docker image is used to determine the versions of dependent images that must be downloaded. Approximately, 1 GB of data is saved. -+ -The default execution does not download any optional stack images that are needed to launch workspaces of a particular type. There are many stacks for different programming languages and some of them are over 1 GB in size. -+ -For a list of available stack images, run the `eclipse/che offline --list` command. -+ -To download a specific stack, run the `eclipse/che offline --image:` command. You can use the `--image` flag repeatedly on a single command line. -+ -. Start Che in offline mode. -+ -Place the TAR files in a directory in the offline computer. If the files are placed in a directory named `/tmp/offline/`, run Che in offline mode using the following command: -+ ----- -# Load the CLI -docker load < /tmp/offline/eclipse_che:.tar - -# Start Che in offline mode -docker run -v /tmp/offline:/data/backup eclipse/che: start --offline ----- -+ -The `--offline` parameter instructs the Che CLI to load all the TAR files located in the directory mounted to the `/data/backup/` directory. These images are then used instead of routing to the Internet to check for Docker Hub. The preboot sequence takes place before any CLI functions use the Docker daemon. The `eclipse/che start`, `eclipse/che download`, and `eclipse/che init` commands support the `--offline` parameter, which triggers this preboot sequence. - -[id="upgrade"] -== Upgrading Che - -You can upgrade Che by downloading a `eclipse/che-cli:` image that is newer than the version that you currently have installed. For a list of available versions that you can upgrade to, run the `eclipse/che-cli version` command . - -*Example* - -To upgrade to 6.0.1 from 6.0.0: - -. Get the new version of Che: `docker pull eclipse/che-cli:6.0.0`. -+ -You now have two `eclipse/che-cli` images (one for each version). -+ -. Use the new image to upgrade the old installation: `docker run eclipse/che-cli:6.0.1 upgrade`. -+ -The upgrade command has numerous checks to prevent you from upgrading Che if the new image and the old one are not compatible. For the upgrade procedure to advance, the CLI image must be newer than the one in the `/instance/che.ver` file. - -The upgrade command performs the following steps in the background: - -. Performs a version compatibility check. - -. Downloads the new Docker images that are needed to run the new version of Che. - -. If it is running, stops Che . - -. Triggers a maintenance window. - -. Backs up your installation. - -. Initializes the new version. - -. Starts Che. - -[IMPORTANT] -==== -To save the stacks packaged into the new binaries in the database, set the `CHE_PREDEFINED_STACKS_RELOAD__ON__START` variable to `true`. -==== - - -[id="backup"] -== Backing up your Che installation - -* To create a copy of relevant configuration information, user data, projects, and workspaces, run the `che backup` command. The `che backup` command does not save workspace snaphots. -* To recover Che from a particular backup snapshot, run the `che restore` command. The backup is saved as a TAR file that you can keep in your records. You can then use the `che restore` command to recover your user data and configuration. - -[id="configuration"] -== Configuration - -Che CLI supports configuring the port, hostname, OAuth, Docker, Git, and resolving networking issues. For details, see link:docker-config.html[Che configuration on Docker]. - -[id="run-without-cli"] -== Running Che without the CLI - -You can run the Che server directly by launching a Docker image. This approach bypasses the CLI that has additional utilities to simplify administration and operation. The `eclipse/che-server` Docker image is appropriate for running Che within clusters, orchestrators, or by third-party tools with automation. - -To run Che directly by launching a Docker image, take the following steps: - -. Run the latest released version of Che 6.x: {{site.latest_6_x_version}}. -. Replace `` with any host directory. Che places the backup files (configurable properties, workspaces, lib, storage) in this directory. -+ ----- -docker run -p 8080:8080 \ - --name che \ - --rm \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data \ - eclipse/che-server:{{site.latest_6_x_version}} ----- - -The following is a selection of commands: - -* To run the nightly version of Che, replace `eclipse/che-server:{{site.latest_6_x_version}}` with `eclipse/che-server:nightly`. - -* To run a specific tagged version of Che, replace `eclipse/che-server:{{site.latest_6_x_version}}` with `eclipse/che-server:<_version_>`. - -* To stop the container running Che, use the `docker stop che` command. - -* To restart the container running Che and restart the Che server, use the `docker restart che` command. - -* To upgrade to a newer version, use the following commands in order: -+ ----- -docker pull eclipse/che-server:{{site.latest_6_x_version}} -docker restart che ----- - -The *Server startup in ##### ms* message confirms that Che has started. After starting, Che is available at `localhost:8080` or at a remote IP if you started Che remotely. - -*Running Che on SELinux* - -If SELinux is enabled, run the following command instead of the preceding one: - ----- -# Run the latest released version of Che -docker run -p 8080:8080 \ - --name che \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data:Z \ - --security-opt label:disable \ - eclipse/che-server:{{site.latest_6_x_version}} ----- - -*Running Che on ports* - -Tomcat inside the container will bind itself to port `8080` by default. You must map this port to be exposed in your container using the `-p 8080:8080` parameter. If you want to change the port to which your browsers connect, change the first value, such as `-p 9000:8080`. This routes requests from port `9000` to the internal Tomcat bound to port `8080`. To change the internal port that Tomcat is bound to, you must update the port binding and set the `CHE_PORT` variable to the new value. - -[source,text] ----- -docker run -p 9000:9500 \ - --name che \ - -e CHE_PORT=9500 \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data \ - eclipse/che-server:{{site.latest_6_x_version}} ----- - -*Configuring properties* - -The most important configuration properties are defined as environment variables that you can pass to the container. For example, to have Che listen on port `9000`: - ----- -docker run -p:9000:9000 \ - --name che \ - -e CHE_SERVER_ACTION=stop \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data \ - eclipse/che-server:{{site.latest_6_x_version}} ----- - -The following table contains a list of variables that can be set. - -[width="100%",cols="34%,33%,33%",options="header",] -|=== -|Variable |Description |Default Values -|`CHE_SERVER_ACTION` |The command to send to Tomcat. It can be `run`, `start` , `stop`. |`run` -|`CHE_ASSEMBLY` |The path to a Che assembly that is on your host to be used instead of the assembly packaged within the `che-server` image. If you set this variable, you must also volume mount the same directory to `/home/user/che` |`/home/user/che` -|`CHE_IN_VM` |Set to `true` if this container is running inside a VM providing Docker such as boot2docker, Docker for Mac, or Docker for Windows. This is auto-detected in most situations, but it is not always perfect. |auto-detection -|`CHE_LOG_LEVEL` |Logging level of output for Che server. Can be `debug` or `info`. |`info` -|`CHE_HOST` |IP address/hostname that the Che server will bind to. Used by browsers to contact workspaces. You must set this IP address if you want to bind the Che server to an external IP address that is not the same as Docker’s. |The IP address set to the Docker host. This covers 99% of situations, but on rare occassions this IP address is not discovered and you must provide it. -|`CHE_DEBUG_SERVER` |If `true`, it will launch the Che server with JPDA activated so that a Java debugger can attach to the Che server for debugging plugins, extensions, and core libraries. |`false` -|`CHE_DEBUG_SERVER_PORT` |The port that the JPDA debugger will listen. |`8000` -|`CHE_DEBUG_SERVER_SUSPEND` |If `true`, then activates the `JPDA_SUSPEND` flag for Tomcat running the Che server. Used for advanced internal debugging of extensions. |`false` -|`CHE_PORT` |The port that the Che server will bind itself to within the Che container. |`8080` -|=== - -For a list of environment variables, see https://github.com/eclipse/che/blob/master/dockerfiles/init/manifests/che.env[che.env]. - -You can create a file with the environment variables that you want to pass to the `che-server` image: - ----- -docker run -p:8080:8080 \ - --name che \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data \ - --env-file /home/user/che.env \ - eclipse/che-server:{{site.latest_6_x_version}} ----- - -*Running Che on a public IP address* - -To connect the remote browser clients to the Che server (as opposed to the local browser clients) and override the defaults that are detected, set the `CHE_IP` variable to the Docker host IP address that will have requests forwarded to the `che-server` container. - -Run an auto-detection algorithm within the `che-server` container to determine this IP. - -* Docker is running on the `boot2docker` tool, this is usually the `eth1` interface. -* You are running Docker for Windows or Docker for macOS, this is usually the `eth0` interface. -* You are running Docker natively on Linux, this is the `docker0` interface. - -To allow access of the remote clients to this container when your host that is running Docker has its IP 10.0.75.4: - ----- -docker run -p:8080:8080 \ - --name che \ - -e CHE_HOST=10.0.75.4 \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data \ - eclipse/che-server:{{site.latest_6_x_version}} ----- - -*Running Che as a daemon* - -Pass the `--restart always` parameter to the `docker` command syntax to have the Docker daemon restart the container on any exit event, including when your host is initially booting. You can also run Che in the background with the `-d` option. - ----- -docker run -p:8080:8080 \ - --name che \ - --restart always \ - -e CHE_HOST=10.0.75.4 \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v :/data \ - eclipse/che-server:{{site.latest_6_x_version}} ----- - -*Running Che with Docker Compose* - -[source,yaml] ----- -che: - image: eclipse/che-server:{{site.latest_6_x_version}} - port: 8080:8080 - restart: always - volumes: - - /var/run/docker.sock:/var/run/docker.sock - - :/data - container_name: che ----- - -. Save this in a file named `Composefile`. - -. Run this with Docker Compose using the `docker-compose -f Composefile -d --env-file=che.env` command. -+ -The `Environment` file must contain the following required environment variable: -+ ----- -# $IP is a public IP of your server -CHE_HOST=$IP ----- - diff --git a/src/main/pages/che-6/setup-kubernetes/kubernetes-admin-guide.adoc b/src/main/pages/che-6/setup-kubernetes/kubernetes-admin-guide.adoc deleted file mode 100644 index 0f13d71c8d..0000000000 --- a/src/main/pages/che-6/setup-kubernetes/kubernetes-admin-guide.adoc +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: "Che on Kubernetes: Admin Guide" -keywords: kubernetes, configuration, admin guide -tags: [installation, kubernetes] -sidebar: che_6_docs -permalink: che-6/kubernetes-admin-guide.html -redirect_from: kubernetes-admin-guide.html -folder: setup-kubernetes ---- - -:admin-context: Kubernetes -:ctl-command: kubectl -:k8s-namespace: Kubernetes Namespace -:docs-registry-link: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ -:che-data-volume-link: https://github.com/eclipse/che/blob/master/deploy/kubernetes/helm/che/templates/deployment.yaml#L57 -:cluster-nodes-link: https://kubernetes.io/docs/concepts/architecture/nodes/#management - -include::../../../pages/che-6/setup-kubernetes/kubernetes-or-openshift-admin-guide.adoc[] diff --git a/src/main/pages/che-6/setup-kubernetes/kubernetes-config.adoc b/src/main/pages/che-6/setup-kubernetes/kubernetes-config.adoc deleted file mode 100644 index 06acb43743..0000000000 --- a/src/main/pages/che-6/setup-kubernetes/kubernetes-config.adoc +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Configuring Kubernetes" -keywords: kubernetes, configuration -tags: [installation, kubernetes] -sidebar: che_6_docs -permalink: che-6/kubernetes-config.html -redirect_from: kubernetes-config.html -folder: che-6/setup-kubernetes ---- - -You can configure the behavior of the Che server by passing environment variables to the Che deployment. - -There are multiple ways to edit the Che deployment to add new or edit existing environment variables: - -* To open the Che deployment YAML file in text editor, use: -+ ----- -kubectl edit dc/che ----- -+ -* To manually edit the Che deployment, in the Kubernetes web console, click *Deployments* -> *Che* -> *Edit*. -* To update the Che deployment with new environment variables or to modify the values of existing ones, use: -+ ----- -$ kubectl set env dc/che = = ----- - -[id="configurable-che-properties"] -== Configurable Che properties - -You can find the deployment environment variables or configuration map in the YAML files. For a complete list of all the properties that are configurable for the Che server, see link:https://github.com/eclipse/che/tree/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che[Che properties]. - -To manually convert properties into environment variables, follow the instructions on the link:properties.html#properties-and-environment-variables[properties page]. - -For more information about critical configuration options, see the link:kubernetes-admin-guide.html[Kubernetes Administration guide]. - -[id="specifying-the-default-unrecoverable-events"] -== Specifying the default unrecoverable events - -By default, if the `Failed Mount`, `Failed Scheduling`, or `Failed to pull image` Kubernetes or OpenShift events occur during a startup, the workspace is immediately terminated before timeout. To change or disable (using a blank value) the default unrecoverable events, use the following environment variable: `CHE_INFRA_KUBERNETES_WORKSPACE_UNRECOVERABLE_EVENTS`. diff --git a/src/main/pages/che-6/setup-kubernetes/kubernetes-multi-user.adoc b/src/main/pages/che-6/setup-kubernetes/kubernetes-multi-user.adoc deleted file mode 100644 index 0005059bf4..0000000000 --- a/src/main/pages/che-6/setup-kubernetes/kubernetes-multi-user.adoc +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: "Deploying multi-user Che to Kubernetes" -keywords: kubernetes, installation, pvc, deployment -tags: [installation, kubernetes] -sidebar: che_6_docs -permalink: che-6/kubernetes-multi-user.html -redirect_from: kubernetes-multi-user.html -folder: setup-kubernetes ---- - -This section walks you through multi-user deployment of Che on Kubernetes. - -*Prerequisites* - -* A Kubernetes cluster with at least 4 GB RAM and RBAC: -** For Minikube 0.26.0 and higher, use the following command: -+ ----- -minikube start --cpus 2 --memory 4096 --extra-config=apiserver.authorization-mode=RBAC ----- -+ -** For Minikube 0.25.2 and lower, use the following command: -+ ----- -minikube start --cpus 2 --memory 4096 --extra-config=apiserver.Authorization.Mode=RBAC ----- -+ -* To deploy role binding, use the following command: -+ ----- -kubectl create clusterrolebinding add-on-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default ----- -+ -* Install the https://github.com/kubernetes/helm/blob/master/docs/install.md[Helm] CLI. HELM is the package manager for Kubernetes. -* Set your default Kubernetes context (this is required to use Helm). In Minikube, this is set automatically. Otherwise, modify the `KUBECONFIG` environment variable and run the following coammnd: -+ ----- -kubectl config use-context ----- -+ -* Install tiller, the Helm server, on your cluster. -.. Create a https://github.com/kubernetes/helm/blob/master/docs/rbac.md[tiller serviceAccount]. -+ ----- -kubectl create serviceaccount tiller --namespace kube-system ----- -+ -.. Bind it to the `cluster-admin` role. -+ ----- -kubectl apply -f ./tiller-rbac.yaml ----- -+ -.. Install `tiller`. -+ ----- -helm init --service-account tiller --wait ----- -+ -* Ensure that you have an NGINX-based Ingress controller. This is the default Ingress controller on Minikube. To start it, use the `minikube addons enable ingress` command. -* DNS discovery should be enabled. It is enabled by default in Minikube. - -[id="cluster-ip"] -== Obtaining the cluster IP - -To obtain the cluster IP: - -* To run your cluster on Minikube, type `minikube ip` on the command line. -* If your cluster is in the cloud, obtain the hostname or IP address from your cloud provider. - -In production, you must specify a hostname. For details, see the issue details at https://github.com/eclipse/che/issues/8694[Add an ability to use host-based routing instead of path-based for k8s infras]. To use a host-based configuration when you do not have a hostname, use services such as nip.io or xip.io. - -To specify a hostname, pass it as the value of the `ingressDomain` parameter in the deployment syntax in the following section. - -To use the IP address, for example, when your corporate policy prevents you from using nip.io, set `isHostBased` to `false`. - -[id="deploy-syntax"] -== Deployment syntax - -The context of the commands below is `che/deploy/kubernetes/helm/che`. - -[id="to-deploy-with-dedicated-keycloak-as-authentication-server"] -=== Deploying with dedicated Keycloak as authentication server - -To deploy multi-user with dedicated Keycloak as authentication server: - -. Make sure Helm dependencies are up-to-date: -+ ----- -helm dependency update ----- - -. Use one of the following two methods to override the default values: - -** Change the `values.yaml` file. On the command line, run the following command: -+ ----- -helm upgrade --install --namespace -f ./values/multi-user.yaml ./ ----- -+ -** Or, override default values during installation, using the `--set` flag: -+ ----- -helm upgrade --install --namespace -f ./values/multi-user.yaml --set global.ingressDomain= --set cheImage= ./ ----- - -Once the deployment finishes, you can access Che on the following locations: - -* Master: `https://che-.domain` -* Keycloak: `https://keycloak-.domain` -* Workspaces servers: `https://server-host.domain` - -[id="to-deploy-without-keycloak-in-multi-user-mode"] -=== Deploying without Keycloak in multi-user mode - -. Make sure Helm dependencies are up-to-date: -+ ----- -helm dependency update ----- - -. Supply the custom OpenID Connect provider using the following flags (for details, see https://github.com/eclipse/che-docs/blob/b2310017b1a75901cbec3b9c665d7ffa1cb23177/src/main/pages/setup-openshift/openshift-config.md[openshift-config.md]): -+ ----- -helm upgrade --install --namespace -f ./values/multi-user.yaml --set global.ingressDomain=,cheImage=,global.cheDedicatedKeycloak=false,customOidcProvider=,cheKeycloakClientId=,customOidcUsernameClaim= ./ ----- -+ -Here: - -* `cheKeycloakClientId` is your authentication server client ID. -* `customOidcUsernameClaim` is optional. Use if your authentication server does not support `preferred_username` claim in the JWT token (check this by accessing the `oidc-url/.well-known/openid-configuration` response). This parameter defines that the claim should be used to determine user name instead. - -[id="default-host"] -== Default Host - -All Ingress specifications are created without a host attribute (defaults to `*`) and with path-based routing to all components. The multi-user configuration is enabled. - ----- -helm upgrade --install --namespace -f ./values/default-host.yaml --set global.ingressDomain= ./ ----- - -* Master: `+https:///+` -* Keycloak: `+https:///auth/+` -* Workspaces servers: `+https:///+` - -[id="tls"] -== TLS certification - -Cert-manager, the Kubernetes certificate management controller, is used to issue *LetsEncrypt* certificates. To avoid rate-limit issues, use a single hostname for all Ingress controllers and path-based routing for all components. Multi-user configuration is enabled. - ----- -helm install --name stable/cert-manager -helm upgrade --install --namespace -f ./values/tls.yaml --set global.ingressDomain= ./ ----- - -* Master: `+https:///+` -* Keycloak: `+https:///auth/+` -* Workspaces servers: `+https:///+` - -[id="delete-che-deployment"] -== Deleting Che deployment - -To delete a deployment, run the following command: - ----- -helm delete ----- diff --git a/src/main/pages/che-6/setup-kubernetes/kubernetes-or-openshift-admin-guide.adoc b/src/main/pages/che-6/setup-kubernetes/kubernetes-or-openshift-admin-guide.adoc deleted file mode 100644 index e383048585..0000000000 --- a/src/main/pages/che-6/setup-kubernetes/kubernetes-or-openshift-admin-guide.adoc +++ /dev/null @@ -1,486 +0,0 @@ -// This content (file) is included in: -// -// * setup-kubernetes/kubernetes-admin-guide.adoc -// * setup-openshift/openshift-admin-guide.adoc -// -// The 'admin-context' variable (set in the parent files) -// is used to determine K8s or OpenShift use. - -// ifeval::[{admin-context} == "OpenShift"] -// :ctl-command: oc -// :k8s-namespace: OpenShift Project -// endif::[] -// -// ifeval::[{admin-context} == "Kubernetes"] -// :ctl-command: kubectl -// :k8s-namespace: Kubernetes Namespace -// endif::[] - -hen the deployment YAML files run, -[id="ram-prerequisites"] -== RAM prerequisites - -[id="single-user-prerequisites"] -=== Single-user prerequisites - -3 GB of RAM is required for single-user Che on {admin-context}. - -Single-user Che uses RAM in this distribution: - -* Che server pod uses up to 1 GB of RAM. The initial request for RAM is 256 MB. The Che server pod rarely uses more than 800 MB RAM. -* Workspaces use 2 GB of RAM. - -[id="multi-user-prerequisites"] -=== Multi-user prerequisites - -You must have at least 5 GB of RAM to run multi-user Che. The Keycloak authorization server and PostgreSQL database require the extra RAM. Multi-user Che uses RAM in this distribution: - -* Che server: approximately 750 MB -* Keycloak: approximately 1 GB -* PostgreSQL: approximately 515 MB -* Workspaces: 2 GB of RAM per workspace. The total workspace RAM depends on the size of the workspace runtime(s) and the number of concurrent workspace pods. - -=== Setting default workspace RAM limits - -The default workspace RAM limit and the RAM allocation request can be configured by passing the `pass:[CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB]` and `pass:[CHE_WORKSPACE_DEFAULT__MEMORY__REQUEST__MB]` parameters to a Che deployment. - -For example, use the following configuration to limit the amount of RAM used by workspaces to 2048 MB and to request the allocation of 1024 MB of RAM: - -[subs="+attributes"] ----- -$ {ctl-command} set env dc/che CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB=2048 \ - CHE_WORKSPACE_DEFAULT__MEMORY__REQUEST__MB=1024 ----- - -[NOTE] -==== -* The user can override the default values when creating a workspace. -* A RAM request greater than the RAM limit is ignored. -==== - -[id="requirements-for-resource-allocation-and-quotas"] -== Requirements for resource allocation and quotas - -Workspace pods are created in the account of the user who deploys Che. The user needs enough quota for RAM, CPU, and storage to create the pods. - -[id="setting-up-the-project-workspace"] -== Setting up the project workspace - -Workspace objects are created differently depending on the configuration. Eclipse Che currently supports two different configurations: - -* Single {admin-context} project - -* Multi {admin-context} project - -[id="setting-up-a-single-openshift-project"] -=== Setting up a single {admin-context} project - -To setup a single {admin-context} project: - -. Define the service account used to create workspace objects with the `CHE_OPENSHIFT_SERVICEACCOUNTNAME` variable. -. To ensure this service account is visible to the Che server, put the service and the Che server in the same namespace. -. Give the service account permissions to create and edit {admin-context} resources. -. If the developer needs to create an object outside of the service accounts bound namespace, give the service account cluster-admin rights by running this command: -+ -[subs="+attributes"] ----- -$ {ctl-command} adm policy add-cluster-role-to-user self-provisioner system:serviceaccount:eclipse-che:che ----- - -In the command above, `eclipse-che` is the Che namespace. - -[id="setting-up-a-multi-openshift-project"] -=== Setting up a multi {admin-context} project - -. To create workspace objects in different namespaces for each user, set the `NULL_CHE_INFRA_OPENSHIFT_PROJECT` variable to `NULL`. - -. To create resources on behalf of the currently logged-in user, use the user’s {admin-context} tokens. - -[id="how-the-che-server-uses-PVCs-and-PVs-for-storage"] -== How the Che server uses PVCs and PVs for storage - -Che server, Keycloak and PostgreSQL pods, and workspace pods use Persistent Volume Claims (PVCs), which are bound to the physical Persistent Volumes (PVs) with https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes[ReadWriteOnce access mode]. When the deployment YAML files run, they define the Che PVCs. You can configure link:#storage-strategies-for-che-workspaces[workspace PVC] access mode and claim size with Che deployment environment variables. - -[IMPORTANT] -==== -The following two conditions prevent the user from running multiple workspaces: - -* Che uses the `common` Persistent Volume Claim (PVC) strategy -* Persistent volumes (PVs) use `ReadWriteOnce` (RWO) access mode - -To work around this limitation, use one of the following measures: - -* Set `ReadWriteMany` (RWX) access mode for PVs -* Use the `unique` PVC strategy -* Use the `per-workspace` strategy -==== - -[id="storage-requirements-for-che-infrastructure"] -=== Storage requirements for Che infrastructure - -* Che server: 1 GB to store logs and initial workspace stacks. -* Keycloak: 2 PVCs, 1 GB each to store logs and Keycloak data. -* PostgreSQL: 1 GB PVC to store database. - -[id="storage-strategies-for-che-workspaces"] -=== Storage strategies for Che workspaces - -The workspace PVC strategy is configurable: - -[width="100%",cols="25%,25%,25%,25%",options="header",] -|=== -|strategy |details |pros |cons -|*unique (default)* | One PVC per workspace volume or user-defined PVC |Storage isolation |An undefined number of PVs is required -|*common* | One PVC for all workspaces in one {k8s-namespace} - -Sub-paths pre-created |Easy to manage and control storage |Workspaces must be in a separate {k8s-namespace} if PV does not support ReadWriteMany (RWX) access mode -|*per-workspace* | One PVC for one workspace - -Sub-paths pre-created |Easy to manage and control storage |Workspace containers must all be in one pod if PV does not support ReadWriteMany (RWX) access mode -|=== - -[id="unique-pvc-strategy"] -=== Unique PVC strategy - -[id="how-the-unique-pvc-strategy-works"] -==== How the unique PVC strategy works - -Every Che Volume of workspace gets its own PVC, which means workspace PVCs are created when a workspace starts for the first time. Workspace PVCs are deleted when a corresponding workspace is deleted. - -User-defined PVCs are created with few modifications: - -- they are provisioned with genarated names to garantee that it is not conflicting with other PVCs in namespace; - -- subpaths of mount volumes that reference user-defined PVCs are prefixed with `{workspace id}/{PVC name}`. -It is done to have the same data structure on PV on different PVC strategies; - -[id="enabling-a-unique-strategy"] -==== Enabling a unique strategy - -If you have already deployed Che with another strategy, set the `CHE_INFRA_KUBERNETES_PVC_STRATEGY` variable to `unique` in `dc/che`. -Note that existing workspaces data won't be migrated and they will use new unique PVC per Che Volume without cleaning up existing PVCs. - -If applying the `che-server-template.yaml` configuration, pass `-p CHE_INFRA_KUBERNETES_PVC_STRATEGY=unique` to the `{ctl-command} new-app` command. - -[id="common-pvc-strategy"] -=== Common PVC Strategy - -[id="how-the-common-pvc-strategy-works"] -==== How the common PVC strategy works - -All workspaces (within one {k8s-namespace}) use the same PVC to store data declared in their volumes (projects and workspace logs by default and whatever additional link:volumes.html[volumes] that a user can define.) - -User-defined PVCs are ignored and volumes that reference PVCs are replaced with volume that references common PVC. -The corresponding containers volume mounts are relinked to common volume and subpaths are prefixed with `'{workspaceId}/{originalPVCName}'`. - -User-defined PVC name is used as Che Volume name. It means that if Machine is configured to use Che Volume with the same name as user-defined -PVC has then they will use the same shared folder in common PVC. - -A PV that is bound to PVC `che-claim-workspace` will have the following structure: - ----- -pv0001 - workspaceid1 - workspaceid2 - workspaceidn - che-logs projects ... ----- - -Volumes can be anything that a user defines as volumes for workspace machines. The volume name is equal to the directory name in `${PV}/${ws-id}`. - -When a workspace is deleted, a corresponding subdirectory (`${ws-id}`) is deleted in the PV directory. - -[id="enabling-the-common-strategy"] -==== Enabling the common strategy - -If you have already deployed Che with another strategy, set the `CHE_INFRA_KUBERNETES_PVC_STRATEGY` variable to `common` in `dc/che`. -Note that existing workspaces data won't be migrated and they will use common PVC without cleaning up existing PVCs. - -If applying the `che-server-template.yaml` configuration, pass `-p CHE_INFRA_KUBERNETES_PVC_STRATEGY=common` to the `{ctl-command} new-app` command. - -ifeval::[{admin-context} == "Kubernetes"] -[NOTE] -==== -. For pre 1.6 Kubernetes, you need to set the `pass:[CHE_INFRA_KUBERNETES_PVC_PRECREATE__SUBPATHS]` variable to `true`. - -. For Kubernetes older than 1.6, setting this variable to `true` is not a requirement. -==== -endif::[] - -[id="restrictions-on-using-common-pvc-strategy"] -==== Restrictions on using the common PVC strategy - -When the `common` strategy is used and a workspace PVC access mode is ReadWriteOnce (RWO), only one {admin-context} node can simultaneously use the PVC. If there are several nodes, you can use the `common` strategy, but the workspace PVC access mode is ReadWriteMany (RWM). Multiple nodes can use this PVC simultaneously. - -To change the access mode for workspace PVCs, pass the `CHE_INFRA_KUBERNETES_PVC_ACCESS_MODE=ReadWriteMany` environment variable to Che deployment either when initially deploying Che or through the Che deployment update. - -Another restriction is that only pods in the same namespace can use the same PVC. The `CHE_INFRA_KUBERNETES_PROJECT` environment variable should not be empty. It should be either the Che server namespace where objects can be created with the Che service account (SA) or a dedicated namespace where a token or a user name and password need to be used. - -[id="per-workspace-pvc-strategy"] -=== Per workspace PVC strategy - -[id="how-the-per-workspace-pvc-strategy-works"] -==== How the per-workspace PVC strategy works - -The `per-workspace` strategy works similarly to the `common` PVC strategy. The only difference is that all workspace volumes (but not all workspaces) use the same PVC to store data (projects and workspace logs by default and any additional link:volumes.html[volumes] that a user can define). - -[id="enabling-a-per-workspace-strategy"] -==== Enabling a per-workspace strategy - -If you have already deployed Che with another strategy, set the `CHE_INFRA_KUBERNETES_PVC_STRATEGY` variable to `per-workspace` in `dc/che`. -Note that existing workspaces data won't be migrated and they will use common PVC per workspace without cleaning up existing PVCs. - -If applying the `che-server-template.yaml` configuration, pass `-p CHE_INFRA_KUBERNETES_PVC_STRATEGY=per-workspace` to the `{ctl-command} new-app` command. - - -[id="updating-your-che-deployment"] -== Updating your Che deployment - -To update a Che deployment: - -. Change the image tag: -+ -You can change the image tag in one of the following ways: - -* On the command line, edit the image tag by running: -+ -[subs="+attributes"] ----- -$ {ctl-command} edit dc/che ----- -+ -* In the {admin-context} web console, edit the `image:tag` line in the YAML file in *Deployments* -* Using the Docker service: -+ -[subs="+attributes,+macros"] ----- -$ {ctl-command} set image dc/che che=eclipse/che-server:$pass:[{VERSION}] --source=docker ----- - -. Update Keycloak and PostgreSQL deployments (optional): - -* Run the `eclipse/che-keycloak` command. -* Run the `eclipse/che-postgres` command. -+ -You can get the list of available versions at https://github.com/eclipse/che/tags[Che GitHub page]. - -. Change the pull policy (optional): -+ -To change the pull policy, do one of the following: - -* Add `--set cheImagePullPolicy=IfNotPresent` to the link:openshift-multi-user.html[Che deployment]. -* Manually edit `dc/che` after deployment. - -The default pull policy is `Always`. The default tag is `nightly`. This tag sets the image pull policy to `Always` and triggers a new deployment with a newer image, if available. - -[id="scalability"] -== Scalability - -To run more workspaces, {cluster-nodes-link}[add more nodes to your {admin-context} cluster]. An error message is returned when the system is out of resources. - -[id="gdpr"] -== GDPR - -To delete data or request the administrator to delete data, run this command with the user or administrator token: - ----- -$ curl -X DELETE http://che-server/api/user/{id} ----- - - -[id="debug-mode"] -== Debug mode - -To run Che Server in debug mode, set the following environment variable in the Che deployment to `true` (default is `false`): - -`CHE_DEBUG_SERVER=true` - -[id="kubernetes-or-openshift-admin-guide-private-docker-registries"] -== Private Docker registries - -See {docs-registry-link}[{admin-context} documentation]. - -[id="che-server-logs"] -== Che server logs - -Logs are persisted in a PV .The PVC `che-data-volume` is {che-data-volume-link}[created] and bound to a PV after Che deploys to {admin-context}. - -To retrieve logs, do one of the following: - -* Run the `{ctl-command} get log dc/che` command. -* Run the `{ctl-command} describe pvc che-data-claim` command to find the PV. Next, run the `{ctl-command} describe pv $pvName` command with the PV to get a local path with the logs directory. Be careful with permissions for that directory, since once changed, Che server will not be able to write to a file. -* In the {admin-context} web console, select *Pods > che-pod > Logs*. - -It is also possible to configure Che master not to store logs, but produce JSON encoded logs to output instead. It may be used to collect logs by systems such as Logstash. To configure JSON logging instead of plain text environment variable `CHE_LOGS_APPENDERS_IMPL` should have value `json`. See more at link:logging.html[logging docs]. - -[id="workspace-logs"] -== Workspace logs - -Workspace logs are stored in an PV bound to `che-claim-workspace` PVC. Workspace logs include logs from workspace agent, link:what-are-workspaces.html#bootstrapper[bootstrapper] and other agents if applicable. - -[id="che-master-states"] -== Che master states - -The Che master has three possible states: - -* `RUNNING` -* `PREPARING_TO_SHUTDOWN` -* `READY_TO_SHUTDOWN` - -The `PREPARING_TO_SHUTDOWN` state means that no new workspace startups are allowed. This situation can cause two different results: - -* If your infrastructure does not support workspace recovery, all running workspaces are forcibly stopped. - -* If your infrastructure does support workspace recovery, any workspaces that are currently starting or stopping is allowed to finish that process. Running workspaces do not stop. - -For those that did not stop, automatic fallback to the shutdown with full workspaces stopping will be performed. - -If you want a full shutdown with workspaces stopped, you can request this by using the `shutdown=true` parameter. When preparation process is finished, the `READY_TO_SHUTDOWN` state is set which allows to stop current Che master instance. - -[id="kubernetes-or-openshift-admin-guide-che-workspace-termination-grace-period"] -== Che workspace termination grace period - -The default grace termination period of {admin-context} workspace pods is `0`. This setting terminates pods almost instantly and significantly decreases the time required for stopping a workspace. - -To increase the grace termination period, use the following environment variable: `pass:[CHE_INFRA_KUBERNETES_POD_TERMINATION__GRACE__PERIOD__SEC]`. - -[IMPORTANT] -==== -If the `terminationGracePeriodSeconds` variable is explicitly set in the {admin-context} recipe, the `pass:[CHE_INFRA_KUBERNETES_POD_TERMINATION__GRACE__PERIOD__SEC]` environment variable does not override the recipe. -==== - - -[id="kubernetes-or-openshift-admin-guide-che-workspace-stop-on-pods-removing"] -== Auto-stopping a workspace when its pods are removed - -Che Server includes a job that automatically stops workspace runtimes if their pods have been terminated. Pods are terminated when, for example, users remove them from the {admin-context} console, administrators terminate them to prevent misuse, or an infrastructure node crashes. - -The job is disabled by default to avoid problems in configurations where Che Server cannot interact with the Kubernetes API without user intervention. - -The job cannot function with the following Che Server configuration: - -* Che Server communicates with the Kubernetes API using a token from the OAuth provider. - -The job can function with the following Che Server configurations: - -* Workspaces objects are created in the same namespace where Che Server is located. -* The *cluster-admin* service account token is mounted to the Che Server pod. - -To enable the job, set the `pass:[CHE_INFRA_KUBERNETES_RUNTIMES__CONSISTENCY__CHECK__PERIOD__MIN]` environment variable to contain a value greater than `0`. The value is the time period in minutes between checks for runtimes without pods. - - -[id="updating-che-without-stopping-active-workspaces"] -== Updating Che without stopping active workspaces - -The differences between a Recreate update and a Rolling update: - -[options="header,autowidth"] -|=== -| Recreate update |Rolling update -| Che downtime |No Che downtime -| - |New deployment starts in parallel and traffic is hot-switched -|=== - -[id="performing-a-recreate-update"] -=== Performing a recreate update - -To perform a recreate update: - -* Ensure that the new master version is fully API compatible with the old workspace agent version. -* Set the deployment update strategy to Recreate -* Make POST request to the `/api/system/stop` api to start WS master suspend. This means that all new attempts to start workspaces will be refused, and all current starts and stops will be finished. Note that this method requires system admin credentials. -* Make periodical `GET` requests to the `/api/system/state` API, until it returns the `READY_TO_SHUTDOWN` state. Also, you can check for "System is ready to shutdown" in the server logs. -* Perform new deploy. - -[id="performing-a-rolling-update"] -=== Performing a rolling update - -To perform a rolling update: - -* Ensure that the new master is fully API compatible with the old ws agent versions, as well as database compatibility. It is impossible to use database migrations on this update mode. -* Set the deployment update strategy set to Rolling. -* Ensure `terminationGracePeriodSeconds` deployment parameter has enough value (see details below). -* Press *Deploy* button or execute `{ctl-command} rollout latest che` from cli client. - -[id="known-issues"] -==== Known issues - -* Workspaces may fallback to the stopped state when they are started five to thirty seconds before the network traffic are switched to the new pod. This happens when the bootstrappers use the Che server route URL for notifying the Che Server that bootstrapping is done. Since traffic is already switched to the new Che server, the old Che server cannot get the bootstrapper's report and fails to start after the waiting timeout is reached. If the old Che server is killed before this timeout, the workspaces can be stuck in the `STARTING` state. The `terminationGracePeriodSeconds` parameter must define enough time to cover the workspace start timeout, which is eight minutes plus some additional time. Typically, setting `terminationGracePeriodSeconds` to 540 sec is enough to cover all timeouts. -* Users may experience problems with websocket reconnections or missed events published by WebSocket connection when a workspace is `STARTED` but dashboard displays that it is `STARTING`. In this case, you need to reload the page to restore connections and the actual workspace states. - -[id="update-with-db-migrations-or-api-incompatibility"] -=== Updating with database migrations or API incompatibility - -If new version of Che server contains some DB migrations, but there is still API compatibility between old and new version, recreate update type may be used, without stopping running workspaces. - -API incompatible versions should be updated with full workspaces stop. It means that `/api/system/stop?shutdown=true` must be called prior to update. - -[id="deleting-deployments"] -== Deleting deployments - -The fastest way to completely delete Che and its infrastructure components is to delete the project and namespace. - -To delete Che and components: - -[subs="+attributes"] ----- -$ {ctl-command} delete namespace che ----- - -You can use selectors to delete particular deployments and associated objects. - -To remove all Che server related objects: - -[subs="+attributes"] ----- -$ {ctl-command} delete all -l=app=che ----- - -To remove all Keycloak related objects: - -[subs="+attributes"] ----- -$ {ctl-command} delete all -l=app=keycloak ----- - -To remove all PostgreSQL-related objects: - -[subs="+attributes"] ----- -$ {ctl-command} delete all -l=app=postgres ----- - -PVCs, service accounts and role bindings should be deleted separately because `{ctl-command} delete all` does not delete them. - -To delete Che server PVC, ServiceAccount and RoleBinding: - -[subs="+attributes"] ----- -$ {ctl-command} delete sa -l=app=che -$ {ctl-command} delete rolebinding -l=app=che ----- - -To delete Keycloak and PostgreSQL PVCs: - -[subs="+attributes"] ----- -$ {ctl-command} delete pvc -l=app=keycloak -$ {ctl-command} delete pvc -l=app=postgres ----- - -== Monitoring Che Master Server - -Master server emits metrics in Prometheus format by default on port `8087` of the Che server host -(this can be customized by the `che.metrics.port` -link:properties.html#properties-and-environment-variables[configuration property]). - -You can configure your own Prometheus deployment to scrape the metrics (as per convention, the -metrics are published on the `:8087/metrics` endpoint). - -The Che's Helm chart can optionally install Prometheus and Grafana servers preconfigured to collect -the metrics of the Che server. When you set the `global.metricsEnabled` value to `true` when -installing Che's Helm chart, Prometheus and Grafana servers are automatically deployed. -The servers are accessible on `prometheus-.domain` or `grafana-.domain` -domains respectively. The Grafana server is preconfigured with a sample dashboard showing the memory -usage of the Che server. You can log in to the Grafana server using the predefined username `admin` -with the default password `admin`. diff --git a/src/main/pages/che-6/setup-kubernetes/kubernetes-single-user.adoc b/src/main/pages/che-6/setup-kubernetes/kubernetes-single-user.adoc deleted file mode 100644 index 8c0ef93814..0000000000 --- a/src/main/pages/che-6/setup-kubernetes/kubernetes-single-user.adoc +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: "Deploying single-user Che to Kubernetes" -keywords: kubernetes, installation, pvc, deployment -tags: [installation, kubernetes] -sidebar: che_6_docs -permalink: che-6/kubernetes-single-user.html -redirect_from: kubernetes-single-user.html -folder: che-6/setup-kubernetes ---- - -This section walks you through single-user deployment of Che on Kubernetes. - -*Prerequisites* - -* A Kubernetes cluster with at least 4 GB RAM and RBAC: -** For Minikube 0.26.0 and higher, use the following command: -+ ----- -minikube start --cpus 2 --memory 4096 --extra-config=apiserver.authorization-mode=RBAC ----- -+ -** For Minikube 0.25.2 and lower, use the following command: -+ ----- -minikube start --cpus 2 --memory 4096 --extra-config=apiserver.Authorization.Mode=RBAC ----- -+ -* To deploy role binding, use the following command: -+ ----- -kubectl create clusterrolebinding add-on-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default ----- -+ -* Install the https://github.com/kubernetes/helm/blob/master/docs/install.md[Helm] CLI. HELM is the package manager for Kubernetes. -* Set your default Kubernetes context (this is required to use Helm). In Minikube, this is set automatically. Otherwise, modify the `KUBECONFIG` environment variable and run the following coammnd: -+ ----- -kubectl config use-context ----- -+ -* Install tiller, the Helm server, on your cluster. -.. Create a https://github.com/kubernetes/helm/blob/master/docs/rbac.md[tiller serviceAccount]. -+ ----- -kubectl create serviceaccount tiller --namespace kube-system ----- -+ -.. Bind it to the `cluster-admin` role. -+ ----- -kubectl apply -f ./tiller-rbac.yaml ----- -+ -.. Install `tiller`. -+ ----- -helm init --service-account tiller --wait ----- -+ -* Ensure that you have an Ingress controller enabled. To start it on Minikube, use the `minikube addons enable ingress` command. -* DNS discovery should be enabled. It is enabled by default in Minikube. - -[id="cluster-ip"] -== Obtaining the cluster IP - -To obtain the cluster IP: - -* To run your cluster on Minikube, type `minikube ip` on the command line. -* If your cluster is in the cloud, obtain the hostname or IP address from your cloud provider. - -In production, you must specify a hostname. For details, see the issue details at https://github.com/eclipse/che/issues/8694[Add an ability to use host-based routing instead of path-based for k8s infras]. To use a host-based configuration when you do not have a hostname, use services such as nip.io or xip.io. - -To specify a hostname, pass it as the value of the `ingressDomain` parameter in the deployment syntax in the following section. - -To use the IP address, for example, when your corporate policy prevents you from using nip.io, set `isHostBased` to `false`. - -[id="deploy-syntax"] -== Deployment syntax - -The context of the commands below is `che/deploy/kubernetes/helm/che`. - -[id="deploy-che"] -=== Deploying Che - -To deploy single-user Che: - -. Make sure Helm dependencies are up-to-date: -+ ----- -helm dependency update ----- - -. Use following two methods to override the default values: -+ -** Change the `values.yaml` file. On the command line, run the following command: -+ ----- -helm upgrade --install --namespace ./ ----- -+ -** Or, override default values during installation, using the `--set` flag: -+ ----- -helm upgrade --install --namespace --set global.ingressDomain= --set cheImage= ./ ----- - -Once the deployment finishes, you can access Che on the following locations: - -* Master: `https://che-.domain` -* Workspaces servers: `https://server-host.domain` - -== Deleting Che deployment - -To delete a deployment, run the following command: - ----- -helm delete ----- diff --git a/src/main/pages/che-6/setup-openshift/openshift-admin-guide.adoc b/src/main/pages/che-6/setup-openshift/openshift-admin-guide.adoc deleted file mode 100644 index cd29824e67..0000000000 --- a/src/main/pages/che-6/setup-openshift/openshift-admin-guide.adoc +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Che on OpenShift: Admin Guide" -keywords: openshift, configuration, admin guide -tags: [installation, kubernetes] -sidebar: che_6_docs -permalink: che-6/openshift-admin-guide.html -redirect_from: openshift-admin-guide.html -folder: setup-openshift ---- - -:admin-context: OpenShift -:ctl-command: oc -:k8s-namespace: OpenShift Project -:docs-registry-link: https://docs.okd.io/latest/architecture/infrastructure_components/image_registry.html -:che-data-volume-link: https://github.com/eclipse/che/blob/master/deploy/openshift/templates/pvc/che-server-pvc.yaml#L14 -:cluster-nodes-link: https://docs.okd.io/latest/admin_guide/manage_nodes.html - -include::../setup-kubernetes/kubernetes-or-openshift-admin-guide.adoc[] - - -[id="create-workspace-objects-in-personal-namespaces"] -== Creating workspace objects in personal namespaces - -You can register the OpenShift server as an identity provider when Che is installed in multi-user mode. This allows you to create workspace objects in the OpenShift namespace of the user that is logged in Che through Keycloak. - -To create a workspace object in the namespace of the user that is logged into Che: - -* link:#openshift-identity-provider-registration[Register], inside Keycloak, an OpenShift identity provider that points to the OpenShift console of the cluster. -* link:#che-configuration[Configure] Che to use the Keycloak identity provider to retrieve the OpenShift tokens of the Che users. - -Every workspace action such as start or stop creates an OpenShift resource in the OpenShift user account. A notification message displays which allows you to link the Keycloak account to your OpenShift user account. - -But for non-interactive workspace actions, such as workspace stop on idling or Che server shutdown, the dedicated OpenShift account configured for the Kubernetes infrastructure is used. See link:#setting-up-the-project-workspace[Setting up the project workspace] for more information. - -To easily install Che on OpenShift with this feature enabled, see link:openshift-multi-user.html#creating-workspace-resources-in-personal-openshift-accounts-on-minishift[this section for Minishift] and link:openshift-multi-user.html#creating-workspace-resources-in-personal-openshift-accounts[this one for OCP] - -[id="openshift-identity-provider-registration"] -== OpenShift identity provider registration - -[NOTE] -==== -Cluster-wide administrator rights are required to add an OAuth client. -==== - -To add the OpenShift identity provider: - -. Use the following settings in the link:user-management.html#auth-and-user-management[Keycloak administration console]: -+ -image::keycloak/openshift_identity_provider.png[] -The `Base URL` is the URL of the OpenShift console. -+ -. Add a default read-token role. -+ -image::git/kc_roles.png[] -+ -. Declare the identity provider as an OAuth client inside OpenShift with the following commands: -+ ----- -$ oc create -f <(echo ' -apiVersion: v1 -kind: OAuthClient -metadata: - name: kc-client -secret: "" -redirectURIs: - - "" -grantMethod: prompt -') ----- - -See https://www.keycloak.org/docs/3.3/server_admin/topics/identity-broker/social/openshift.html[Keycloak documentation] for more information on the Keycloak OpenShift identity provider. - -[id="configuring-che"] -== Configuring Che - -To configure Che deployment: - -* Set the `CHE_INFRA_OPENSHIFT_PROJECT` variable to `NULL` to ensure a new distinct OpenShift namespace is created for every workspace that is started. -* Set the `pass:[CHE_INFRA_OPENSHIFT_OAUTH__IDENTITY__PROVIDER]` variable to the alias of the OpenShift identity provider specified in step 1 of its link:#openshift-identity-provider-registration[registration in Keycloak]. The default value is `openshift-v3`. - -[id="providing-the-openshift-certificate-to-keycloak"] -== Providing the OpenShift certificate to Keycloak - -If the certificate used by the OpenShift console is self-signed or is not trusted, then by default the Keycloak will not be able to contact the OpenShift console to retrieve linked tokens. - -Keycloak cannot contact the OpenShift console to retrieve linked tokens when the certificate used by the OpenShift console is self-signed or is not trusted. - -When the certificate is self-signed or is not trusted, use the `OPENSHIFT_IDENTITY_PROVIDER_CERTIFICATE` variable to pass the OpenShift console certificate to the Keycloak deployment. This will enable the Keycloak server to add the certificate to the list of trusted certificates. The environment variable refers to a secret that contains the certificate. diff --git a/src/main/pages/che-6/setup-openshift/openshift-config.adoc b/src/main/pages/che-6/setup-openshift/openshift-config.adoc deleted file mode 100644 index 3ab3817ff5..0000000000 --- a/src/main/pages/che-6/setup-openshift/openshift-config.adoc +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: "Configuration: OpenShift" -keywords: openshift, configuration -tags: [installation, openshift] -sidebar: che_6_docs -permalink: che-6/openshift-config.html -redirect_from: openshift-config.html -folder: che-6/setup-openshift ---- - -[id="admin-guide"] -== Admin Guide - -See: link:openshift-admin-guide.html[OpenShift Admin Guide] to general information that works both for OS and K8S. - -[id="configure-che-server"] -== Configure Che Server - -Che server is configured by updating environment variables passed to Che deployment. You can configure Che Server when initially deploying Che (See: link:openshift-single-user.html[Installation Single User], link:openshift-multi-user.html[Multi-User]) or afterwards, by modifying Che deployment. - -There are multiple ways to modify Che deployment to add new or modify existing environment variables. You can either: - -* *Option 1: Update Che deployment yaml.* To update Che deployment yaml and update in nano editor (VIM is used by default), run this command: `$ OC_EDITOR="nano" oc edit dc/che` -* *Option 2: Update manually in OpenShift web console.* To update manually in OpenShift web console > deployments > Che > Environment -* *Option 3: Modify environment variables.* To update Che deployment with new environment variables or modify existing variables, run this command: `$ oc set env dc/che KEY=VALUE KEY1=VALUE1` - -[id="what-can-be-configured"] -== What Can Be Configured? - -You can find deployment env or config map in yaml files. - -Here is a https://github.com/eclipse/che/tree/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che[complete] list of all properties that are configurable for Che server. - -You can manually convert properties into envs, just make sure to follow link:properties.html#properties-and-environment-variables[instructions on properties page] - -[id="https-mode"] -== HTTPS Mode - -To enable https for server and workspace routes, follow instructions in link:openshift-single-user.html[setup docs single user] and link:openshift-multi-user.html[multi-user]. - -To migrate an existing Che deployment to https, do the following: - -1. Update Che deployment with `PROTOCOL=https, WS_PROTOCOL=wss, TLS=true` -2. Manually edit or recreate routes for Che and Keycloak `oc apply -f https` -3. Once done, go to `https://keycloak-${NAMESPACE}.${ROUTING_SUFFIX}`, log in to admin console. Default credentials are `admin:admin`. Go to Clients, `che-public` client and edit *Valid Redirect URIs* and *Web Origins* URLs so that they use *https* protocol. You do not need to do that if you initially deploy Che with https support. - -[id="https-mode---self-signed-certs"] -== HTTPS Mode - Self-Signed Certs - -If you enable HTTPS mode for multi-user Che on an OpenShift installation that does not have certificates signed by a public authority, it won’t be possible to start workspaces or even login. - -There is a lot of communication between Che server and workspace agents, Che server and Keycloak. Therefore, self signed certs should be added to Java trust store of Che server and Keycloak (only for a multi user Che deployment) pods, as well as workspace images. While there is automation for Che server and Keycloak, certs should be manually added to workspace images, since adding a root certificate requires sudo privileges which an arbitrary OpenShift user may not have. - -* Export certificate: - -This has to be the certificate that your OpenShift *router* uses since OpenShift Web Console may use a different cert or even use a different (sub)domain. If you are not certain where to find the cert, you may export it: - -image::workspaces/chrome_cert.png[] - -Choose the top certificate hierarchy and export a single certificate. - -* Create a secret with certificate: - ----- -CERTIFICATE=$(cat /path/to/openshift/ca.crt) -oc new-app -f deploy/openshift/templates/multi/openshift-certificate-secret.yaml -p CERTIFICATE="${CERTIFICATE}" ----- - -There is another way to create a secret with a certificate using the `oc` (or `kubectl`) client: - -[subs="+quotes"] ----- - oc create secret generic self-signed-certificate --from-file=__ both.pem - -# Backup the old config -oc export secret router-certs > ~/old-router-certs-secret.yaml - -# Replace the router certificate -oc secrets new router-certs tls.crt=both.pem tls.key=privkey.pem -o json --type='kubernetes.io/tls' --confirm | oc replace -f - - -# Rollout the latest DC for the router -oc rollout latest router ----- - -You may also find the following docs/blog posts helpful: - -* https://docs.openshift.org/latest/install_config/redeploying_certificates.html#redeploying-custom-registry-or-router-certificates[OpenShift Docs] -* https://blog.openshift.com/lets-encrypt-acme-v2-api/[OpenShift Blog] - -After a router restarts, all secure routes in the cluster should be trusted, and you can deploy Che in https mode: link:openshift-single-user.html#https-mode[single user] or link:openshift-multi-user.html#openshift-container-platform[multi-user] or update your http Che installation. - -[id="private-docker-registries"] -== Private Docker Registries - -Refer to https://docs.openshift.com/container-platform/3.7/security/registries.html[OpenShift documentation] - -[id="enable-ssh-and-sudo"] -== Enable ssh and sudo - -By default, pods are run with an arbitrary user that has a randomly generated UID (the range is defined in OpenShift config file). This security constrain has several consequences for Eclipse Che users: - -* installers for language servers will fail since most of them require `sudo` -* no way to run any sudo commands in a running workspace - -It is possible to allow root access which in its turn allows running system services and change file/directory link:#filesystem-permissions[permissions]. You can change this behavior. See https://docs.openshift.com/container-platform/3.6/admin_guide/manage_scc.html#enable-images-to-run-with-user-in-the-dockerfile[OpenShift Documentation for details]. - -You may also configure some services to bind to ports below `1024`, say, apache2. Here’s an example of enabling it for https://github.com/eclipse/che-dockerfiles/blob/master/recipes/php/Dockerfile#L49[Apache2] in a PHP image. - -*How to Get a Shell in a Pod?* - -Since OpenShift routes do not support ssh protocol, once cannot run sshd (or equivalent) in a pod and ssh into it. However, OpenShift itself provides a few alternatives (only for users who can authenticate as a user that has deployed Che): - -* `oc rsh ${POD_NAME}` (you can get running pods with `oc`). Note that this is a remote shell, not an ssh connection -* in an OpenShift *web console, projects > ws-namespace > pods > pod details > Terminal*. - -Once Che server is able to create OpenShift objects on behalf of a current user, rsh will be available for all users. You may follow GitHub https://github.com/eclipse/che/issues/8178[issue] to get updates. - -[id="filesystem-permissions"] -== Filesystem Permissions - -As said above, pods in OpenShift are started with an arbitrary user with a dynamic UID that is generated for each namespace individually. As a result, a user in an OpenShift pod does not have write permissions for files and directories unless root group (UID - `0`) has write permissions for those (an arbitrary user in OpenShift belongs to root group). All Che ready to go stacks are optimized to run well on OpenShift. See an example from a https://github.com/eclipse/che-dockerfiles/blob/master/recipes/stack-base/centos/Dockerfile#L45-L48[base image]. What happens there is that a root group has write permissions for `/projects` (where workspace projects are located), a user home directory and some other dirs. - -[id="multi-user-using-own-keycloak-and-psql"] -== Multi-User: Using Own Keycloak and PSQL - -Out of the box Che is deployed together with Keycloak and Postgres pods, and all three services are properly configured to be able to communicate. However, it does not matter for Che what Keycloak server and Postgres DB to use, as long as those have compatible versions and meet certain requirements. - -Follow instructions on deploying multi-user link:openshift-multi-user.html[Che without Keycloak or Postgres or both]. - -*_Che Server and Keycloak_* - -Keycloak server URL is retrieved from the `pass:[CHE_KEYCLOAK_AUTH__SERVER__URL]` environment variable. A new installation of Che will use its own Keycloak server running in a Docker container pre-configured to communicate with Che server. Realm and client are mandatory environment variables. By default Keycloak environment variables are: - ----- -CHE_KEYCLOAK_AUTH__SERVER__URL=http://${KC_ROUTE}:5050/auth -CHE_KEYCLOAK_REALM=che -CHE_KEYCLOAK_CLIENT__ID=che-public ----- - -You can use your own Keycloak server. Create a new realm and a public client. A few things to keep in mind: - -* It must be a public client -* `redirectUris` should be `${CHE_SERVER_ROUTE}/*`. If no or incorrect `redirectUris` are provided or the one used is not in the list of `redirectUris`, Keycloak will display an error saying that redirect_uri param is invalid. -* `webOrigins` should be either`${CHE_SERVER_ROUTE}` or `*`. If no or incorrect `webOrigins` are provided, Keycloak script won’t be injected into a page because of CORS error. - -*_Using an alternate OIDC provider instead of Keycloak_* - -Instead using a Keycloak server, Che now provides a limited support for alternate authentication servers compatible with the http://openid.net/specs/openid-connect-core-1_0.html[OpenId Connect specification]. - -Some limitations restrict the alternate OIDC providers that can be used with Eclipse Che. Supported providers should: - -* implement access tokens as JWT tokens including at least the following claims: -** `exp`: the expiration time (https://tools.ietf.org/html/rfc7519#section-4.1.4) -** `sub`: the subject (https://tools.ietf.org/html/rfc7519#section-4.1.2) -* allow redirect Urls with wildcards at the end -* provide an endpoint that returns the http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[OpenID Provider Configuration information]. According to the specification, this endpoint should end with sub-path `/.well-known/openid-configuration`. - -When using an alternate OIDC provider, the following Keycloak environment variables should be set to `NULL`: - ----- -CHE_KEYCLOAK_AUTH__SERVER__URL=NULL -CHE_KEYCLOAK_REALM=NULL ----- - -Instead, you should set the folowing environement variables: - ----- -CHE_KEYCLOAK_CLIENT__ID= -CHE_KEYCLOAK_OIDC__PROVIDER= ----- - -If the optional http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest[`nonce` OpenId request parameter] is not supported, the following environment variable should be added: - ----- -CHE_KEYCLOAK_USE__NONCE=FALSE ----- - -By default, the OIDC authentication in Che requires using redirect URLs with wildcards. For alternate OIDC providers that only support a list of fixed redirect URLs, use the following environment variable to switch to fixed redirect URL mode: - ----- -CHE_KEYCLOAK_USE__FIXED__REDIRECT__URLS=TRUE ----- - -In this case, the two redirect URLs that should be registered in the OIDC provider configuration are: ----- -${CHE_SERVER_ROUTE}/api/keycloak/oidcCallbackIde.html -${CHE_SERVER_ROUTE}/api/keycloak/oidcCallbackDashboard.html ----- - - -*_Che Server and PostgreSQL_* - -Che server uses the below defaults to connect to PostgreSQL to store info related to users, user preferences and workspaces: - ----- -CHE_JDBC_USERNAME=pgche -CHE_JDBC_PASSWORD=pgchepassword -CHE_JDBC_DATABASE=dbche -CHE_JDBC_URL=jdbc:postgresql://postgres:5432/dbche -CHE_JDBC_DRIVER__CLASS__NAME=org.postgresql.Driver -CHE_JDBC_MAX__TOTAL=20 -CHE_JDBC_MAX__IDLE=10 -CHE_JDBC_MAX__WAIT__MILLIS=-1 ----- - -Che currently uses version 9.6. - -*_Keycloak and PostgreSQL_* - -Database URL, port, database name, user and password are defined as environment variables in Keycloak pod. Defaults are: - ----- -POSTGRES_PORT_5432_TCP_ADDR=postgres -POSTGRES_PORT_5432_TCP_PORT=5432 -POSTGRES_DATABASE=keycloak -POSTGRES_USER=keycloak -POSTGRES_PASSWORD=keycloak ----- - -[id="development-mode"] -== Development Mode - -After you have built your link:assemblies.html[custom assembly], execute `build.sh` https://github.com/eclipse/che/tree/master/dockerfiles/che[script]. You can then tag it, either push to MiniShift or a public Docker registry, and reference in your Che deployment as `CHE_IMAGE_REPO` and `CHE_IMAGE_TAG`. Alternatively, you may make sure the image is available locally and change pull policy to `IfNotPresent` in che deployment. - -[id="che-workspace-termination-grace-period"] -== Che Workspace Termination Grace Period - -Info about changing workspace termination grace period can be found in the following link:kubernetes-config.html#che-workspace-termination-grace-period[section] of the Che Kubernetes config document. diff --git a/src/main/pages/che-6/setup-openshift/openshift-multi-user.adoc b/src/main/pages/che-6/setup-openshift/openshift-multi-user.adoc deleted file mode 100644 index a244c7cf56..0000000000 --- a/src/main/pages/che-6/setup-openshift/openshift-multi-user.adoc +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "Multi-User: Deploying to OpenShift" -keywords: openshift, installation, ocp, multi-user, multi user, keycloak, postgres, deployment -tags: [installation, openshift] -sidebar: che_6_docs -permalink: che-6/openshift-multi-user.html -redirect_from: openshift-multi-user.html -folder: che-6/setup-openshift ---- - - -[id="deploying-che-on-supported-openshift-flavors-and-versions"] -== Deploying Che on supported OpenShift flavors and versions - -Multi-user Eclipse Che can be deployed to OpenShift Container Platform 3.6 and later, OpenShift Dedicated, and OpenShift Online Pro. - -The deployment script creates three DeploymentConfigs for Che, PostgreSQL, and Keycloak. PVCs, services, and routes (Che and Keycloak only) are also created by the deployment script. - - -[id="deployment-diagram"] -== Deployment diagram - -image::diagrams/ocp_multi_user.png[] - -ifeval::["{project-context}" == "che"] -[id="using-minishift-to-deploy-che"] -== Using Minishift to Deploy Che - -Due to the size of a multi-user Eclipse Che installation, Minishift is not recommended as the base for this configuration. If you have to use Minishift, start it with at least 4GB of memory by including the `--memory=4096` parameter, and https://docs.openshift.org/latest/minishift/getting-started/updating.html[update Minishift] to the latest version. - ----- -$ curl -fsSL https://raw.githubusercontent.com/eclipse/che/master/deploy/openshift/deploy_che.sh -o deploy_che.sh -$ ./deploy_che.sh --multiuser ----- -The script will download deployment templates, check your current oc session and context. Run `./deploy_che.sh --help` to get a list of all deployment options. -endif::[] - - -[id="using-openshift-container-platform-to-deploy-che"] -== Using OpenShift Container Platform to deploy Che - -ifeval::["{project-context}" == "che"] -:pwd: pages/che-6/setup-openshift/ -endif::[] - -include::using-ocp-to-deploy-{project-context}.adoc[] - - -[id="using-openshift-dedicated-to-deploy-che"] -== Using OpenShift Dedicated to deploy Che - -The instructions to deploy Che to OpenShift Dedicated are identical to those for link:#using-openshift-container-platform-to-deploy-che[OpenShift Container Platform]. - - -[id="using-openshift-online-pro-to-deploy-che"] -== Using OpenShift Online Pro to deploy Che - -The instructions to deploy Che to OpenShift Online Pro are identical to those for link:#using-openshift-container-platform-to-deploy-che[OpenShift Container Platform]. - - -[id="openshift-multi-user-what-is-next"] -== What is next? - -Now that you have a running Che multi-user instance, link:user-management.html[create a user, set up OAuth, and log in]. - - -ifeval::["{project-context}" == "che"] -[id="additional-resources"] -== Additional Resources - -* Kubernetes link:kubernetes-admin-guide.html[Admininstration Guide] -endif::[] diff --git a/src/main/pages/che-6/setup-openshift/openshift-single-user.adoc b/src/main/pages/che-6/setup-openshift/openshift-single-user.adoc deleted file mode 100644 index 4dae56fb99..0000000000 --- a/src/main/pages/che-6/setup-openshift/openshift-single-user.adoc +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: "Single-User: Deploy to OpenShift" -keywords: openshift, installation, pvc, https, deployment -tags: [installation, openshift] -sidebar: che_6_docs -permalink: che-6/openshift-single-user.html -redirect_from: openshift-single-user.html -folder: che-6/setup-openshift ---- - -[id="supported-openshift-flavors-and-versions"] -== Supported OpenShift Flavors and Versions - -Single User Eclipse Che can be deployed to Minishift, OCP, OSD and OSO v3.6+. - -[id="pre-requisites"] -== Pre-Requisites - -OpenShift oc client installed locally - -[id="admin-guide"] -== Admin Guide - -See: link:kubernetes-admin-guide.html[Kubernetes Admin Guide] - -[id="deployment-diagram"] -== Deployment Diagram - -There are a few essential Kubernetes and OpenShift objects that are created when Che is deployed to OpenShift. When a workspace is started additional objects are created. See the diagram below: - -image::diagrams/ocp_single_user.png[] - -This diagram depicts the default link:openshift-config.html#volumes[PVC strategy] (PVC per workspace). - -[id="minishift-addon"] -== Minishift Addon - -Before starting https://docs.openshift.org/latest/minishift/getting-started/installing.html[install Minishift] or https://docs.openshift.org/latest/minishift/getting-started/updating.html[update your Minishift] to ensure you’re on the most up-to-date version. - -*Minishift Addon* - -The best way of deploying Che to Minishift is using an add-on via the https://docs.openshift.org/latest/minishift/command-ref/minishift_addons_apply.html[`minishift add-ons apply`] command which is outlined in the following paragraphs. - -*Install add-On* - -Starting with minishift v1.23.0 Che addon is pre-installed. To start Che we need to `enable` the addon and `apply` it: - ----- -$ minishift addons enable che && minishift addons apply che ----- - -*Deploy a local Che server image* - -To deploy a local che-server image (e.g. `eclipse/che-server:local`) based on Che v5: - ----- -$ minishift addons apply --addon-env CHE_DOCKER_IMAGE=eclipse/che-server:local che ----- - -If the local image is based on Che v6: - ----- -$ minishift addons apply \ - --addon-env CHE_DOCKER_IMAGE=eclipse/che-server:local \ - che ----- - -*Addon Variables* - -To customize the deployment of the Che server, the following variables can be applied to the execution: - -[width="100%",cols="15%,39%,46%",options="header",] -|=== -|Name |Description |Default Value -|`NAMESPACE` |The OpenShift project where Che service will be deployed |`che-mini` -|`CHE_DOCKER_IMAGE` |The docker image to be used for che. |`eclipse/che-server:latest` -|`GITHUB_CLIENT_ID` |GitHub client ID to be used in Che workspaces |`changeme` -|`GITHUB_CLIENT_SECRET` |GitHub client secred to be used in Che workspaces |`changeme` -|=== - -Variables can be specified by adding `--addon-env ` when the addon is being invoked (either by `minishift start` or `minishift addons apply`). - -*Remove add-on* - -To remove all created template and che project: - ----- -minishift addons remove che ----- - -*Uninstall add-on* - -To uninstall the addon from the addon list: - -`minishift addons uninstall che` - - -[id="minishift-script"] -== MiniShift: Deployment Script - -Alternatively, you may download deployment script and run deployment manually instead of using MiniShift addons: - ----- -curl -fsSL https://raw.githubusercontent.com/eclipse/che/master/deploy/openshift/deploy_che.sh -o deploy_che.sh -./deploy_che.sh ----- - -The script will download deployment templates, check your current oc session and context. Run `./deploy_che.sh --help` to get a list of all deployment options. - -You can use the same script to deploy to a local Origin/OKD cluster (oc cluster up) - -[id="https-mode"] -== HTTPS Mode - -IMPORTANT! Find instructions on adding self signed certs at link:openshift-config.html#https-mode---self-signed-certs[OpenShift Configuration page]. - ----- -./deploy_che.sh -s ----- - -[id="openshift-container-platform"] -== OpenShift Container Platform - -Same instructions as in link:#minishift-script[MiniShift]. - -[id="openshift-dedicated"] -== OpenShift Dedicated - -Instructions to deploy Che to OSD are identical to those for link:#openshift-container-platform[OpenShift Container Platform] - -[id="openshift-online"] -== OpenShift Online - -Instructions to deploy Che to OSO Pro are identical to those for link:#openshift-container-platform[OpenShift Container Platform] - -[id="deployment-options-and-configuration"] -== Deployment Options and Configuration - -See: link:openshift-config.html[OpenShift Deployment Config] and link:kubernetes-admin-guide.html[Admin Guide] - -[id="whats-next"] -== What’s Next - -Create and link:creating-starting-workspaces.html[start your first workspace], link:version-control.html[import a project]. diff --git a/src/main/pages/che-6/setup-openshift/using-ocp-to-deploy-che.adoc b/src/main/pages/che-6/setup-openshift/using-ocp-to-deploy-che.adoc deleted file mode 100644 index 120177314a..0000000000 --- a/src/main/pages/che-6/setup-openshift/using-ocp-to-deploy-che.adoc +++ /dev/null @@ -1,15 +0,0 @@ -*HTTP Setup* - ----- -$ curl -fsSL https://raw.githubusercontent.com/eclipse/che/master/deploy/openshift/deploy_che.sh -o deploy_che.sh -$ ./deploy_che.sh --multiuser ----- - -*HTTPS Setup* - -IMPORTANT! Find instructions on adding self-signed certificates at the link:openshift-config.html#https-mode---self-signed-certs[OpenShift Configuration page]. - ----- -$ curl -fsSL https://raw.githubusercontent.com/eclipse/che/master/deploy/openshift/deploy_che.sh -o deploy_che.sh -$ ./deploy_che.sh --multiuser -s ----- diff --git a/src/main/pages/che-6/spi/spi-implementation.adoc b/src/main/pages/che-6/spi/spi-implementation.adoc deleted file mode 100644 index b49dc666da..0000000000 --- a/src/main/pages/che-6/spi/spi-implementation.adoc +++ /dev/null @@ -1,366 +0,0 @@ ---- -title: SPI: Implementation -sidebar: che_6_docs -keywords: dev docs -permalink: che-6/spi-implementation.html -redirect_from: spi-implementation.html -folder: che-6/spi ---- - -Now that you have made yourself familiar with link:spi_overview.html[SPI motivation and concept], let’s take a closer look at its components and implementation notes. - -[id="components"] -== Components - -[id="environment"] -=== Environment - -* https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/spi/environment/InternalEnvironment.java#L32[InternalEnvironment] holds internal representations of environment configuration. -* https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/spi/environment/InternalEnvironmentFactory.java#L45[InternalEnvironmentFactory] creates a valid `InternalEnvironment` based on the specified workspace configuration and recipe. This component is independent of Infrastructure - -[id="infrastructure"] -=== Infrastructure - -* https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/spi/RuntimeInfrastructure.java[RuntimeInfrastructure] is a starting point that has two obligations: -** provides meta information about infrastructure like name and types of supported recipes; -** provides an interface for creation of `RuntimeContext`. -* https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/spi/RuntimeContext.java[RuntimeContext] holds information that can be used by `InternalRuntime`. -* https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/spi/InternalRuntime.java[InternalRuntime] describes particular runtime and provides an interface for interacting with it like starting, stopping. - -Environment components are decoupled from Infrastructure components to make it easier to support the same environments type by different infrastructures. - -The following diagram shows the components interaction while a workspace start. - -image::spi/start-sequence-diagram.png[] - -[id="exceptions"] -== Exceptions - -There are three types of exceptions which can be thrown by Infrastructure components: - -* `ValidationException` should be thrown when an error occurs because of wrong data provided by user (e.g. recipe); -* `InternalInfrastructureException` should be thrown when an unexpected error occurs and a user has no ways of fixing it, so Che Server administrator should take a look at it; -* `InfrastructureException` should be thrown in all other cases. - -[id="events"] -== Events - -Infrastructure should inform Workspace API about progress of starting/stopping a workspace with publishing of events. Events are link:dto.html[DTOs objects] and can be created with `DtoFactory`. Server implementations are provided by https://github.com/eclipse/che/tree/master/wsmaster/che-core-api-workspace[workspace-api] module. Infrastructure should publish them by `EventService`. Information about particular events and when they should be thrown are listed below. - -[id="internalenvironmentfactory"] -== InternalEnvironmentFactory - -The first thing that should be decided is which environments will be supported by a new infrastructure, and which recipes this environment supports. Che has four recipes out of the box which can be used: `dockerfile`, `dockerimage`, `compose`, `openshift`. If a developer wants to support own recipe type the corresponding `InternalEnvironmentFactory` should be bound with a `MapBinder` with unique String key that contains recipe type, like: - -[source,java] ----- - MapBinder.newMapBinder(binder(), String.class, InternalEnvironmentFactory.class); - .addBinding("myRecipe").to(SubclassOfInternalEnvironmentFactory.class); ----- - -Once supported environments are taken care of, the next step is implementing own `RuntimeInfrastructure, RuntimeContext, InternalRuntime` which are strongly connected. - -[id="runtimeinfrastructure"] -== RuntimeInfrastructure - -So, `RuntimeInfrastructure` should create `RuntimeContext` according to the specified `InternalEnvironment`. Before context creation, `RuntimeInfrastructure` may somehow need to customize `InternalEnvironment`, like modifying original recipes objects according to machines configuration (e.g. exposing ports required for configured servers, or setting memory limit according to machine configuration). This step is called *Runtime Context preparing*. - -[id="runtimecontext"] -== RuntimeContext - -*Implementation of RuntimeContext* should provide two methods: - -* `#getOutputChannel` method that returns an output channel for a particular runtime. The output channel is a WebSocket endpoint where runtime output can be received by clients. Infrastructure can set up own endpoint or use an existing one. -+ -Existing master websocket endpoint is configured with `che.websocket.endpoint` property. Out of the box, there is `installer/log` request handler that will publish received event via EventService and two link:json-rpc.html[JSON RPC] messengers which transmit https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace-shared/src/main/java/org/eclipse/che/api/workspace/shared/dto/event/InstallerLogEvent.java[InstallerLogEvent] and https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace-shared/src/main/java/org/eclipse/che/api/workspace/shared/dto/event/MachineLogEvent.java[MachineLogEvent] via WebSocket to `machine/log` and `installer/log` methods. So, received installers logs will be automatically propagated to subscribed clients. If an infrastructure wants to propagate machine logs it’s enough to propagate `MachineLogEvent` via `EventService`. -+ -Setting up a new endpoint can be useful to remove load from master since there can be a lot of output produced by runtime. -* `#getRuntime` method that returns a runtime. - -[id="internalruntime"] -== InternalRuntime - -The main piece of work should be done while implementing of start and stop of `InternalRuntime` (`#internalStart` and `#internalStop` methods). After runtime start, it should be fully ready to be used by clients. Start of runtime includes two major actions: *machines start* and *launching agents*. - -Starting of machines is an exceptionally infrastructure specific process. There is only one declared thing that is related to machine life cycle: Infrastructure may publish https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace-shared/src/main/java/org/eclipse/che/api/workspace/shared/dto/event/MachineStatusEvent.java#L25[machine statuses events]. There are four possible values for machine status: - -* *_STARTING_* - machine is starting; -* *_RUNNING_* - machine is running, note that it says nothing about servers statuses and machine can be not ready for using by clients; -* *_STOPPED_* - machine is not running; -* *_FAILED_* - machine failed to start or crashed while running. - -[id="installers"] -== Installers - -As to launching of agents, Che offers an out-of-the-box feature that automates this process. So, it can be done with installers which in fact are shell scripts that should be executed to install some software and dependencies, and launch it if needed. A *bootstrapper* can be used to execute installers scripts. - -*Bootstrapper* is a binary file which can execute installers scripts and wait until the corresponding servers are accessible. To launch machine with agents via a bootstrapper, extend `AbstractBootstrapper` and implement `#doBootstrapAsync` method with the following steps: - -* Provide binary file of bootstrapper into a machine. Bootstrapper binaries are hosted by Che Server and can be downloaded by the following link `http://${CHE_HOST}:${CHE_PORT}/agent-binaries/linux_amd64/bootstrapper/bootstrapper`. Or it can be provided in any another way if infrastructure is able put something into machine (exec, mount etc). -* The second step is providing a config file for a bootstrapper (inject it into machine in a way that an infrastructure allows). It must contain an ordered list of https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-installer-shared/src/main/java/org/eclipse/che/api/installer/shared/model/Installer.java[installers] configs in a json format. Installers will be launched in the specified order and it is needed for resolving dependencies between installers. Note that https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-workspace/src/main/java/org/eclipse/che/api/workspace/server/spi/environment/InternalMachineConfig.java#L76[InternalMachineConfig#getInstallers] methods returns already ordered installers list. -* Finally, launching bootstrapper with the corresponding parameters. Bootstrapper requires the following parameters to be specified as start arguments: -** *_machine-name_* - machine name where this particular bootstrapper is running. -** *_runtime-id_* - runtime identifier in format 'workspace:environment:owner'. -** *_push-endpoint_* - a WebSocket endpoint where to push statuses. -** *_push-logs-endpoint_* - a WebSocket endpoint where to push logs. -+ -The following parameters are optional and there is default behavior when they are missing: -** *_-installer-timeout_* - time(in seconds) given for one installer to complete its installation. If installation is not finished in time it will be interrupted. Default value 120 seconds (3 minutes); -** *_server-check-period_* - time(in seconds) between servers availability checks. Once servers for an installer are available, checks are stopped. The default value is 3 seconds; -** *_file_* - configuration file path. Default value - `config.json`; -** *_logs-endpoint-reconnect-period_* - time(in seconds) between attempts to reconnect to push-logs-endpoint. Bootstrapper tries to reconnect to push-logs-endpoint when previously established connection lost. Default value - 10 seconds. - -Skeletal implementation of `AbstractBootstrapper` should look like the following sample: - -[source,java] ----- -package org.eclipse.che.workspace.infrastructure.dummy.bootstrapper; - -import ...; - -public class MyBootstrapper extends AbstractBootstrapper { - private static final Gson GSON = new GsonBuilder().disableHtmlEscaping().create(); - - private final String machineName; - private final RuntimeIdentity runtimeIdentity; - private final List installers; - private final int serverCheckPeriodSeconds; - private final int installerTimeoutSeconds; - private final String installerWebsocketEndpoint; - private final String outputWebsocketEndpoint; - - public MyBootstrapper( - @Assisted String machineName, - @Assisted RuntimeIdentity runtimeIdentity, - @Assisted List installers, - EventService eventService, - @Named("che.websocket.endpoint") String cheWebsocketEndpoint, - @Named("che.infra.dummy.output_endpoint") String myOutputEndpoint, - @Named("che.infra.dummy.bootstrapper.timeout_min") int bootstrappingTimeoutMinutes, - @Named("che.infra.dummy.bootstrapper.installer_timeout_sec") int installerTimeoutSeconds, - @Named("che.infra.dummy.bootstrapper.server_check_period_sec") int serverCheckPeriodSeconds) { - super(machineName, runtimeIdentity, bootstrappingTimeoutMinutes, myOutputEndpoint, - cheWebsocketEndpoint, eventService); - this.machineName = machineName; - this.runtimeIdentity = runtimeIdentity; - this.installers = installers; - this.serverCheckPeriodSeconds = serverCheckPeriodSeconds; - this.installerTimeoutSeconds = installerTimeoutSeconds; - this.installerWebsocketEndpoint = cheWebsocketEndpoint; - this.outputWebsocketEndpoint = myOutputEndpoint; - } - - @Override - protected void doBootstrapAsync(String installerWebsocketEndpoint, String outputWebsocketEndpoint) - throws InfrastructureException { - // inject bootstrapper binaries - - // make it executable - - String configJson = GSON.toJson(installers); - // inject config.json file - - // launch bootstrapper with the corresponding - // configuration parameters - // - // ./bootstrapper -machine-name $machineName - // -runtime-id + String.format("%s:%s:%s", - // runtimeIdentity.getWorkspaceId(), - // runtimeIdentity.getEnvName(), - // runtimeIdentity.getOwner() - // -push-endpoint $installerWebsocketEndpoint - // -push-logs-endpoint $outputWebsocketEndpoint - // -server-check-period $serverCheckPeriodSeconds - // -installer-timeout $installerTimeoutSeconds - // -file $pathToConfigFileHere - } -} ----- - -When it is implemented `InternalRuntime` can easily use it in the following way: - -[source,java] ----- -public class MyInternalRuntime extends InternalRuntime { - - private void doBootstrap(String machineName, InternalMachineConfig machineConfig) - throws InfrastructureException, InterruptedException { - MyBootstrapper myBootstrapper = - myBootstrapperFactory.create( - machineName, getContext().getIdentity(), machineConfig.getInstallers()); - - myBootstrapper.bootstrap(); - } -} ----- - -[id="servers"] -== Servers - -See: link:#servers[Servers] - -Machine configuration contains servers configuration that will be launched inside it. Servers can be embedded into a machine or launched by installers. If an application has more than one endpoint (like http and websocket, or the same protocol by different paths) it can declare different servers. There are two kinds of servers: - -* Internal servers which are available only for other machines of a workspace; -* Public server which are available for all clients. - -Public servers should be protected with authentication since they are publicly accessible. Internal servers don’t require any authentication since they must be accessible only for other machines. So, servers configs have the following format: - -[source,java] ----- -/** Configuration of server that can be started inside of machine. */ -public interface ServerConfig { - /** - * Port used by server. It may contain protocol(tcp or udp) after '/' symbol. If protocol is - * missing tcp will be used by default. - * Example: '8080/tcp', '8080/udp', '8080'. - */ - String getPort(); - - /** - * Protocol for configuring preview url of this server. - * Example: 'http', 'https', 'tcp', 'udp', 'ws', 'wss'. - */ - String getProtocol(); - - /** Path used by server. */ - @Nullable - String getPath(); - - /** Attributes of the server */ - Map getAttributes(); -} ----- - -There is an attribute of which has name `internal` and boolean value which indicates whether server should be internal or public. If the attribute is missing or its value differs from "true" than server is treated as public. Infrastructure is responsible for propagated ports of servers in different ways depending on whether or not the server is internal. Port is a machine port which will be used by a server and should be propagated by infrastructure for the clients. The way of propagating of machine port is infrastructure specific. To interact with servers Che clients use servers provided by an Infrastructure. So, the server object has the following format: - -[source,java] ----- -public interface Server { - /** Returns URL exposing the server */ - String getUrl(); - - /** Returns the status */ - ServerStatus getStatus(); - - /** Returns attributes of the server with some metadata */ - Map getAttributes(); -} ----- - -Attributes from server configs should be propagated to servers. - -The server URL should be evaluated by Infrastructure with `protocol` and `path` from server config, while `host name` and `port` values depending on the way in which machines ports are propagated by an infrastructure. Note that server URL can be rewritten with `URLRewriter` by abstract `InternalRuntime`, so clients will get modified URL. It is used when Che machines supposed to be accessible via reverse Proxy. - -As to server statuses they are provided by Infrastructure. There are three possible values for them: - -* RUNNING is returned when server is up and running; -* STOPPED is returned when server is not running; -* UNKNOWN there is no information about server status. - -Checking of servers statuses can be performed in infrastructure specific way. Or Workspace API provides out of box server checkers which can be used by Infrastructure. Now there are servers checks only for most critical servers for Che clients: wsagent, terminal, exec. It can be used by Runtime while starting and waiting until servers are available in the following way: - -[source,java] ----- -import org.eclipse.che.api.workspace.server.hc.ServersChecker; -import org.eclipse.che.api.workspace.server.hc.ServersCheckerFactory; - -private class MyInternalRuntime { - ... - - private void doWaitServersRunning(String machineName, InternalMachineConfiug machineConfig) - throws InfrastructureException, InterruptedException { - ServersChecker readinessChecker = serverCheckerFactory.create(getContext().getIdentity(), - machineName, machine.getServers()); - readinessChecker.startAsync((serverRef) -> { - // update server state to RUNNING - sendRunningServerEvent(machineName, serverRef); - }); - readinessChecker.await(); - } -} ----- - -In addition there are server probes which may be scheduled to continuously checks server liveness. Here is an example of how to do this: - -[source,java] ----- -import org.eclipse.che.api.workspace.server.hc.probe.ProbeResult; -import org.eclipse.che.api.workspace.server.hc.probe.ProbeResult.ProbeStatus; -import org.eclipse.che.api.workspace.server.hc.probe.ProbeScheduler; -import org.eclipse.che.api.workspace.server.hc.probe.WorkspaceProbesFactory; - -private class MyInternalRuntime { - private final ProbeScheduler probeScheduler; - private final WorkspaceProbesFactory probesFactory; - ... - private void doScheduleServersLivenessProbes(String machineName) throws InfrastructureException { - RuntimeIdentity identity = getContext().getIdentity(); - probeScheduler.schedule( - probesFactory.getProbes(identity.getWorkspaceId(), machineName, /*resolved machine servers should be here instead of empty map*/ emptyMap()), - new ServerLivenessHandler()); - } - - private class ServerLivenessHandler implements Consumer { - @Override - public void accept(ProbeResult probeResult) { - String machineName = probeResult.getMachineName(); - String serverName = probeResult.getServerName(); - ProbeStatus probeStatus = probeResult.getStatus(); - Server server = /*assign server which has name serverName to which probe is related instead of null*/ null; - ServerStatus oldServerStatus = server.getStatus(); - ServerStatus serverStatus; - - if (probeStatus == ProbeStatus.FAILED && oldServerStatus == ServerStatus.RUNNING) { - serverStatus = ServerStatus.STOPPED; - } else if (probeStatus == ProbeStatus.PASSED && (oldServerStatus != ServerStatus.RUNNING)) { - serverStatus = ServerStatus.RUNNING; - } else { - return; - } - - // set new status serverStatus into machine with name machineName - - // send event about changing server status - } -} ----- - -[id="volumes"] -== Volumes - -A link:#volumes[volume] is a persistent storage that can be used for sharing data between machines of a workspace or for saving data persistently. Volumes field in a machine configuration is a map where key is volume name and value is volume itself. For now, volume object has only one field `path`. It’s an absolute path where volume should be mounted in the machine. - -[source,json] ----- -{ - "myMachine": { - ... - "volumes": { - "maven_repo": { - "path": "/home/user/.m2/repository" - } - } - } -} ----- - -Note that if a volume with the same name is used in different machines then the same volume should be shared between machines. - -Infrastructure must implement supporting of volumes in its own way. - -[id="workspace-start-interruption"] -== Workspace Start Interruption - -Workspace API allows users to stop workspaces that are *_STARTING_*, but whether they will interrupt the launch of the workspace or not, depends on the implementation of the infrastructure. So `InternalRuntime` should expect that `internalStop` method may be called when `internalStart` hasn’t finished its work yet. Then `InternalRuntime` may interrupt runtime start or throw an exception if stopping of a workspace with a *_STARTING_* status is not supported by an infrastructure. - -[id="runtimes-recovering"] -== Runtimes Recovering - -Workspace API allows Infrastructure to pick up running runtime while getting it from context. It allows recovering running runtime when workspace master crashed, or restart/reconfigure/update workspace master without workspaces stopping. - -[id="skeletal-implementation"] -== Skeletal Implementation - -The full skeletal implementation is located in the following https://github.com/codenvy/che-infra-sample[repository]. - diff --git a/src/main/pages/che-6/spi/spi_overview.adoc b/src/main/pages/che-6/spi/spi_overview.adoc deleted file mode 100644 index e9fcb91a36..0000000000 --- a/src/main/pages/che-6/spi/spi_overview.adoc +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: SPI: Overview -sidebar: che_6_docs -keywords: dev docs -permalink: che-6/spi_overview.html -redirect_from: spi_overview.html -folder: che-6/spi ---- - - -[id="abstraction"] -== Abstraction - -Che Workspace Runtime composed by set of running Machines can be deployed on top of any Infrastructure. Runtime is able to provide one or more Machines. - -As defined in a link:what-are-workspaces.html[workspace model], a machine is termed as some set of hardware and|or software resources working under control of Operation System. Examples of such Infrastructure including: - -* Running Physical Computers -* Virtual machines -* Linux Containers - -Che Workspace Runtime *Service Provider Interface* (SPI) is a clean abstraction to allow pluggable Environment and Runtime Infrastructure. - -It defines two kinds of contracts to be implemented in order to: - -* describe Workspace Environment binding logical configuration of Machines along with implementation of a specific Recipe -* let particular Runtime Infrastructure start and stop resources associated with Workspace Runtime, such as Docker Containers, Kubernetes Pods, volumes etc. -* allow listening to infrastructure specific events, machines start/stop sequences, servers health checking thanks to asynchronous link:json-rpc.html[JSON-RPC messaging]. - -Strictly speaking, there are 2 kinds of SPI: one for Environment analyzing and transformation and another for applying effective environment and starting Workspace Runtime. - -The reason of decoupling `InternalEnvironment` from Runtime Infrastructure SPI is that some types of Recipes can be understandable/supported for more than one Infrastructure. - -[id="motivation"] -== Motivation - -SPI is one of the main features of Che 6. - -There are several reasons to implement it, main of which include: - -* Big demand of using infractructures other than Docker, such as: OpenShift, Kubernetes, local machine which was too hard on Docker oriented implementation. -* Needs to have more flexibility with deploying different tools on different machines, not to be "dev-machine oriented". -* A client has to be better informed during Workspace starting, stopping and running including receiving detailed infrastructure specific events. diff --git a/src/main/pages/che-6/tags/assembly.adoc b/src/main/pages/che-6/tags/assembly.adoc deleted file mode 100644 index 1d50872580..0000000000 --- a/src/main/pages/che-6/tags/assembly.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Che Assembly pages" -tagName: assembly -search: exclude -permalink: che-6/tag_assembly.html -redirect_from: tag_assembly.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/chedir.adoc b/src/main/pages/che-6/tags/chedir.adoc deleted file mode 100644 index 57688aa8b6..0000000000 --- a/src/main/pages/che-6/tags/chedir.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Chedir pages" -tagName: chedir -search: exclude -permalink: che-6/tag_chedir.html -redirect_from: tag_chedir.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/debugger.adoc b/src/main/pages/che-6/tags/debugger.adoc deleted file mode 100644 index 3ee6cd965f..0000000000 --- a/src/main/pages/che-6/tags/debugger.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Debugger pages" -tagName: debugger -search: exclude -permalink: che-6/tag_debugger.html -redirect_from: tag_debugger.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/dev-docs.adoc b/src/main/pages/che-6/tags/dev-docs.adoc deleted file mode 100644 index 0f78903e12..0000000000 --- a/src/main/pages/che-6/tags/dev-docs.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Dev Docs pages" -tagName: dev-docs -search: exclude -permalink: che-6/tag_dev-docs.html -redirect_from: tag_dev-docs.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/docker.adoc b/src/main/pages/che-6/tags/docker.adoc deleted file mode 100644 index 24d1af305c..0000000000 --- a/src/main/pages/che-6/tags/docker.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Docker pages" -tagName: docker -search: exclude -permalink: che-6/tag_docker.html -redirect_from: tag_docker.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/extensions.adoc b/src/main/pages/che-6/tags/extensions.adoc deleted file mode 100644 index 9445174463..0000000000 --- a/src/main/pages/che-6/tags/extensions.adoc +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Extensions pages" -tagName: extensions -search: exclude -permalink: che-6/tag_extensions.html -redirect_from: tag_extensions.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ - - diff --git a/src/main/pages/che-6/tags/factories.adoc b/src/main/pages/che-6/tags/factories.adoc deleted file mode 100644 index 4c676c305c..0000000000 --- a/src/main/pages/che-6/tags/factories.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Factories pages" -tagName: factories -search: exclude -permalink: che-6/tag_factories.html -redirect_from: tag_factories.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/getting-started.adoc b/src/main/pages/che-6/tags/getting-started.adoc deleted file mode 100644 index 34f7524f41..0000000000 --- a/src/main/pages/che-6/tags/getting-started.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Getting Started pages" -tagName: getting-started -search: exclude -permalink: che-6/tag_getting-started.html -redirect_from: tag_getting-started.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/installation.adoc b/src/main/pages/che-6/tags/installation.adoc deleted file mode 100644 index e37977157f..0000000000 --- a/src/main/pages/che-6/tags/installation.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Installation pages" -tagName: installation -search: exclude -permalink: che-6/tag_installation.html -redirect_from: tag_installation.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/keycloak.adoc b/src/main/pages/che-6/tags/keycloak.adoc deleted file mode 100644 index 6e22042a35..0000000000 --- a/src/main/pages/che-6/tags/keycloak.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Keycloak Pages" -tagName: keycloak -search: exclude -permalink: che-6/tag_keycloak.html -redirect_from: tag_keycloak.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/kubernetes.adoc b/src/main/pages/che-6/tags/kubernetes.adoc deleted file mode 100644 index 31e2294773..0000000000 --- a/src/main/pages/che-6/tags/kubernetes.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Kubernetes pages" -tagName: kubernetes -search: exclude -permalink: che-6/tag_kubernetes.html -redirect_from: tag_kubernetes.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/ldap.adoc b/src/main/pages/che-6/tags/ldap.adoc deleted file mode 100644 index 1a660a58bd..0000000000 --- a/src/main/pages/che-6/tags/ldap.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "LDAP Pages" -tagName: ldap -search: exclude -permalink: che-6/tag_ldap.html -redirect_from: tag_ldap.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/networking.adoc b/src/main/pages/che-6/tags/networking.adoc deleted file mode 100644 index f5facc8ee6..0000000000 --- a/src/main/pages/che-6/tags/networking.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Networking pages" -tagName: networking -search: exclude -permalink: che-6/tag_networking.html -redirect_from: tag_networking.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/openshift.adoc b/src/main/pages/che-6/tags/openshift.adoc deleted file mode 100644 index 8ae6e2b463..0000000000 --- a/src/main/pages/che-6/tags/openshift.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "OpenShift pages" -tagName: openshift -search: exclude -permalink: che-6/tag_openshift.html -redirect_from: tag_openshift.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/organizations.adoc b/src/main/pages/che-6/tags/organizations.adoc deleted file mode 100644 index 1a730f651f..0000000000 --- a/src/main/pages/che-6/tags/organizations.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Organizations pages" -tagName: organizations -search: exclude -permalink: che-6/tag_organizations.html -redirect_from: tag_organizations.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/plugins.adoc b/src/main/pages/che-6/tags/plugins.adoc deleted file mode 100644 index 6d10fc3e88..0000000000 --- a/src/main/pages/che-6/tags/plugins.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Plugins pages" -tagName: plugins -search: exclude -permalink: che-6/tag_plugins.html -redirect_from: tag_plugins.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/runtime.adoc b/src/main/pages/che-6/tags/runtime.adoc deleted file mode 100644 index 160b554b64..0000000000 --- a/src/main/pages/che-6/tags/runtime.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Runtime pages" -tagName: runtime -search: exclude -permalink: che-6/tag_runtime.html -redirect_from: tag_runtime.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/troubleshooting.adoc b/src/main/pages/che-6/tags/troubleshooting.adoc deleted file mode 100644 index b41b37ed3a..0000000000 --- a/src/main/pages/che-6/tags/troubleshooting.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Troubleshooting pages" -tagName: troubleshooting -search: exclude -permalink: che-6/tag_troubleshooting.html -redirect_from: tag_troubleshooting.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/tags/workspace.adoc b/src/main/pages/che-6/tags/workspace.adoc deleted file mode 100644 index 09a26c303a..0000000000 --- a/src/main/pages/che-6/tags/workspace.adoc +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Workspace pages" -tagName: workspace -search: exclude -permalink: che-6/tag_workspace.html -redirect_from: tag_workspace.html -sidebar: che_6_docs ---- - -++++ -{% include taglogic.html %} -++++ diff --git a/src/main/pages/che-6/user-guide/commands-ide-macro.adoc b/src/main/pages/che-6/user-guide/commands-ide-macro.adoc deleted file mode 100644 index cf1773196b..0000000000 --- a/src/main/pages/che-6/user-guide/commands-ide-macro.adoc +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "Commands and IDE Macros" -keywords: workspace, runtime, commands, build, run, macro, preview, url -tags: [workspace, runtime] -sidebar: che_6_docs -permalink: che-6/commands-ide-macro.html -redirect_from: commands-ide-macro.html -folder: che-6/user-guide ---- - -A command is: - -* A set of instructions that is injected into the workspace machine for execution - -* A goal to organize commands for your workflow - -* A context to scope the command to particular projects - -* A preview URL to expose the URL of a running server - -Commands are saved in the configuration storage of your workspace and are part of any workspace export operation. - -[id="command-goals"] -== Command goals - -A developer executes a command to achieve a particular step in the development workflow. Che provides the ability to organize commands per goal: - -* _Build_: Commands that build the projects in a workspace. - -* _Test_: Commands related to test execution. - -* _Run_: Commands that run projects in a workspace. - -* _Debug_: Commands used to start a debugging session. - -* _Deploy_: Commands that are used to deploy projects in a workspace on specific servers or services. - -* _Common_: Commands used for general purpose. - -[id="command-context"] -== Command context - -The context of a command defines the projects that the command can be used with. For example: a `maven build` command is relevant only if the project uses Maven. - -[id="managing-commands"] -== Managing commands - -Workspace commands are available in the *Commands Explorer* view. This view is accessible from the left pane. The commands are organized in this view by goal. - -image::commands/command-explorer.png[] - -To create new commands, use the `+` icon next to a goal. Alternatively, you can select a command from the tree to edit, duplicate, or delete it. - -image::commands/command-editor.png[] - -The command editor is a distinct tab in the existing editor pane. Double-click the tab to use the full-screen edit mode. The editor can be split vertically or horizontally to display multiple editors at once. - -* *Name*: A unique command name in your workspace. The name is not restricted to CamelCase. - -* *Intructions*: To learn more about instructions and macros, see the link:[Macros] section. - -* *Goal*: Use the dropdown list to change the goal of the command. - -* *Context*: By default, the command is available with all the workspace projects. You can scope the command to be available only for selected projects. - -* *Preview*: To learn more about servers, see the link:servers.html[Servers] section. - -Che provides macros that can be used within a command or preview URL to reference workspace objects. To learn more, see the link:#macros[Macros] section. - -[id="macros-list"] -== Macros list - -When editing a command, you can access all the macros that can be used in the command’s instructions or in the preview URL. To display a complete list of macros, click on the `Macros` link. - -image::commands/command-macros-list.png[] - -[id="auto-completing-macros"] -== Auto-completing macros - -You can auto-complete all macros used in the editor. To activate the auto-complete feature, press *Ctrl+Space*. This displays a menu listing all the possible macros based on what is typed. - - -image::commands/command-macros-autocompletion.png[] - -[id="using-commands"] -== Using commands - -You can use commands from the following widgets: - -* *Command Palette* - -* Command toolbar - -* Contextual menu in the *Project Explorer* view - -[id="using-the-command-palette"] -=== Using the Command Palette - -Use the *Shift+F10* keys to open the *Command Palette*. Use the arrow keys to navigate through the list of commands. Use *Enter* to execute a selected command. - -image::commands/command-palette.png[] - -[id="command-toolbar"] -=== Using the command toolbar - -Using the command toolbar, you can execute the most common `Run` and `Debug` goals. The toolbar provides access to all the executed commands and previews. - -image::commands/command-toolbar.png[] - -==== Using the Run and Debug buttons - -To trigger commands directly from the *Run* and *Debug* buttons, you must define the commands for the `Run` and `Debug` goals. - -You are asked to choose the default command associated with a button when you use this button for the first time and this button has multiple commands defined for a goal. Consecutive clicks of this button trigger the previously selected command. - -To select a command to execute from a goal, click and hold the button. This command becomes the default command associated with the button. - -==== Using the command controller - -Use the command controller to view the state of the workspace and the last command that was executed. You can see the time span since a command was started and decide if it should be stopped or relaunched. - -To view the list of all the previously executed commands when multiple commands are executed, click on the widget. - -image::commands/command-toolbar-expanded.png[] - -To clean the list, remove the process of the command from the list of processes. - -image::commands/command-clean-toolbar.png[] - -==== Using the Preview button - -For commands used to start servers, define the preview URL to access the running server. To learn more, see the link:servers.html#preview-urls[Preview URLs] section. - -The *Preview* button provides quick access to all of fthe servers that are running in the machines of the workspace. - -[id="authoring-command-instructions"] -== Authoring command instructions - -A command may contain a single instruction or a succession of commands. For example: - ----- -cd /projects/spring <1> -mvn clean install ----- -<1> Each command starts on a new line - ----- -cd /projects/spring; mvn clean install <1> ----- -<1> A succession of several commands where `;` stands for a new line ----- -cd /projects/spring && mvn clean install <1> ----- -<1> A succession of several commands where execution of a subsequent command depends on the execution of the preceeding one. If the `/projects/spring` directory is absent, the `mvn clean install` command is not executed. - - -To check for conditions, use loops and other `bash` syntax: - ----- -mvn -f ${current.project.path} clean install <1> - if [[ $? -eq 0 ]]; then - cp /projects/kitchensink/target/*.war /home/user/wildfly-10.0.0.Beta2/standalone/deployments/ROOT.war - echo "BUILD ARTIFACT SUCCESSFULLY DEPLOYED..." -else - echo "FAILED TO DEPLOY NEW ARTIFACT DUE TO BUILD FAILURE..." -fi ----- -<1> Copy build artifact only if build is successful. - -[id="macros"] -== Macros - -Che provides macros that can be used within a command or preview URL to reference workspace objects. Macros are translated into real values only when used in the IDE. - -[NOTE] -==== -You cannot use macros in commands that are launched from the server side. -==== - -The following table lists the macros and their descriptions. - -[width="100%",cols="50%,50%",options="header",] -|=== -|Macro |Details -|`${current.project.path}` |Absolute path to the project or module currently selected in the *Project Explorer* tree. -|`${current.project.eldest.parent.path}` |Absolute path to a project root (for example, in the Maven-multi-module project). -|`${current.class.fqn}` |The fully qualified `package.class` name of the Java class currently active in the editor panel. -|`${current.project.relpath}` |The path to the currently selected project relative to `/projects`. Effectively removes the `/projects` path from any project reference. -|`${editor.current.file.name}` |Currently selected file in the editor. -|`${editor.current.file.basename}` |Currently selected file in the editor without extension. -|`${editor.current.file.path}` |Absolute path to the selected file in the editor. -|`${editor.current.file.relpath}` |Path relative to the `/projects` directory to the selected file in editor. -|`${editor.current.project.name}` |Project name of the file currently selected in the editor. -|`${editor.current.project.type}` |Project type of the file currently selected in the editor. -|`${explorer.current.file.name}` |Currently selected file in the project tree. -|`${explorer.current.file.basename}` |Currently selected file in the project tree without extension. -|`${explorer.current.file.path}` |Absolute path to the selected file in the project tree. -|`${explorer.current.file.relpath}` |Path relative to the `/projects` directory in the project tree. -|`${explorer.current.project.name}` |Project name of the file currently selected in the explorer. -|`${java.main.class}` |Path to the main class. -|`${machine.dev.hostname}` |Current machine host name. -|`${project.java.classpath}` |Project classpath. -|`${project.java.output.dir}` |Path to the Java project output directory. -|`${project.java.sourcepath}` |Path to the Java project source directory. -|`${explorer.current.project.type}` |Project type of the file currently selected in the explorer. -|`${server.}` |Returns protocol, hostname, and port of an internal server. `` is defined by the same internal port of the internal service that you have exposed in your workspace recipe. + -|=== - -* Returns the hostname and port of a service or application you launch inside a machine. - -* The hostname resolves to the hostname or the IP address of the workspace machine. This name varies depending on where Docker is running and whether it is embedded within a VM. - -* The port returns the Docker ephemeral port that you can give to your external clients to connect to your internal service. Docker uses ephemeral port mapping to expose a range of ports that your clients may use to connect to your internal service. This port mapping is dynamic. In case of OpenShift, a route is returned. -|=== -|Macro |Details -|`${workspace.name}` |Returns the name of the workspace. -| `${workspace.namespace}` |Workspace namespace (defaults to `che` in single-user Che). -|=== - -[id="environment-variables"] -== Environment variables - -The workspace machine has a set of system environment variables that have been exported. They are reachable from your command scripts using the `bash` syntax. - ----- -export <1> - -$TOMCAT_HOME/bin/catalina.sh run <2> ----- -<1> List of all the available machine system environment variables. -<2> Reference an environment variable, where `$TOMCAT_HOME` points to the `/home/user/tomcat8` directory. diff --git a/src/main/pages/che-6/user-guide/creating-starting-workspaces.adoc b/src/main/pages/che-6/user-guide/creating-starting-workspaces.adoc deleted file mode 100644 index 9a24b0eb24..0000000000 --- a/src/main/pages/che-6/user-guide/creating-starting-workspaces.adoc +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: "Managing workspaces" -keywords: workspace, runtime, recipe, docker, yaml, Dockerfile, docker, kubernetes, container, pod -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/creating-starting-workspaces.html -redirect_from: creating-starting-workspaces.html -folder: che-6/user-guide ---- - - -[id="creating-workspaces"] -== Creating workspaces - -Use the link:stacks.html[stacks] in the *Dashboard* to create a workspace. Images and configuration in these stacks are certified both for Docker and OpenShift. These stacks are used in daily functional testing. - -=== Creating a workspace from stacks in the dashboard - -To create a workspace from stacks in the *Dashboard*, take the following steps: - -. In the *Dashboard*, in the left panel, click *Stacks*. - -. Click the *Duplicate stack* icon for the stack that you want to create a clone of. A page titled after the selected stack opens. - -. Edit the fields that you want to edit. - -. Click *Save*. - -image::workspaces/ready_to_go_stacks.gif[] - -=== Duplicating an existing stack - -Create a stack and then use the resulting stack to create a workspace. - -To create a copy of an existing stack, take the following steps: - -. In the *Dashboard*, in the left panel, click *Stacks*. - -. Click the *Duplicate stack* icon for the stack that you want to clone. - -. Edit the *Name* field. - -. In the *Machines* field, edit the *Source* field. - -. Click *Save*. The *Stack is successfully updated* message confirms that the stack is updated. - -. In the *Dashboard*, click *Workspaces* > *Add Workspace*. - -. In the *SELECT STACK* section, scroll through the list to locate the stack that you created in the preceding steps. - -. Click *Create* to create the workspace based on this stack. - -image::workspaces/duplicate_stack.gif[] - -=== Creating a custom stack from a custom recipe - -Author a custom link:recipes.html[recipe] and then create a stack. Use the resulting stack to create a workspace. - -To create a custom stack from a custom recipe, take the following steps: - -. In the *Dashboard*, click *Workspaces* > *Add Workspace*. - -. From the *SELECT STACK* field, select the required stack. - -. Click *Add Stack*. - -. In the *Create Stack* dialog box, click *Yes* to confirm that you want to create the stack from a recipe. - -. In the *Build stack from recipe* window, type the recipe name from which you want to build this stack (example: `FROM: eclipse/new-stack`). - -. Click *OK*. - -. In the *Name* field, type a name for the stack. - -. In the *Runtimes* > *Machines* > *Recipe* section, click *Show* to ensure that the stack is being created using the recipe that you set in the preceding steps (*eclipse/new-stack*, in this case). - -. Click *Save*. - -image::workspaces/custom_recipe_stack.gif[] - -[id="starting-workspaces"] -== Starting workspaces - -You can start a workspace in one of the following ways: - -* The workspace starts automatically after it is created in the user's *Dashboard*. - -* In the user's *Dashboard*, use the *Run* or *Open* buttons in the *Workspace Details* view. - -* Click a workspace name from the *Recent Workspaces* displayed in the left panel. - -* Use the REST API. For more information about the REST API, see link:rest-api.html[REST API]. - -The workspace may take time to start depending on factors like network conditions, container image availability, and configured installers attempting to install additional tools and software in the runtime. Track the progress of the workspace start operation in the *Workspace Start* tab. The tabs for each machine in the workspace environment stream logs from the installers (terminal, `exec` agent, `ws` agent, and language servers if any). - -[id="managing-a-workspace"] -== Managing a workspace - -After a workspace is created or started, you can modify it by adding projects, installers, environment variables, and volumes. - -[IMPORTANT] -==== -To edit a raw workspace configuration, back up the working configuration to avoid breaking your workspace. -==== - -Change the configuration of a running workspace and saving it restarts the workspace. To learn more about workspace configuration, see: - -* link:projects.html[Creating projects in workspaces] - -* link:installers.html[Installers] - -* link:env-variables.html[Environment variables] - -* link:volumes.html[Volumes] - -image::workspaces/ws_details.gif[] diff --git a/src/main/pages/che-6/user-guide/debug.adoc b/src/main/pages/che-6/user-guide/debug.adoc deleted file mode 100644 index b33e5f165b..0000000000 --- a/src/main/pages/che-6/user-guide/debug.adoc +++ /dev/null @@ -1,294 +0,0 @@ ---- -title: "Debug" -keywords: workspace, runtime, project, projects, debugger, debug, debug jar, breakpoint, suspend -tags: [workspace, runtime, debugger] -sidebar: che_6_docs -permalink: che-6/debug.html -redirect_from: debug.html -folder: che-6/user-guide ---- - - -Che currently supports debuggers for: - -* link:#java[Java] -* link:#gdb[C/C++] (via GDB) -* link:#php[PHP] (via Zend debugger, zDebug and Z-Ray) -* link:#nodejs[Node.js] (via GDB) - -[id="java"] -== Java - -Java debugger is deployed with the workspace agent, i.e. runs in the workspace. It can connect to local processes (those running in a workspace) or remote ones. - -Breakpoints are set with a single click on a line number in the editor. You can set breakpoints before attaching a debugger: - -image::debug/breakpoint.png[] - -In a Debug Dialog (*Run > Edit Debug Configurations…*), choose if you want to attach to a process in a local workspace or a remote machine. If localhost is chosen, a drop down menu will show all ports that are exposed in a container. You may either choose an existing port or provide your own. - -image::debug/debug-configurations.png[] - -*Java Console Apps* - -To debug console apps, pass debug arguments to JVM: - ----- -mvn clean install && java -jar -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y ${current.project.path}/target/*.jar ----- - -*Java Web Apps* - -To debug a web application, you need to start a web server in a debug mode. Debug arguments may vary depending on the web server in use. For example, to start Tomcat in a debug mode, run: st - -[source,text] ----- -$TOMCAT_HOME/bin/catalina.sh jpda run ----- - -You can add debug commands to CMD widget to permanently save them with the workspace config. - -Java debugger supports the following features: - -* step into -* step over -* run to cursor -* evaluate expression -* watch expression -* conditional breakpoints -* change variable value/expression -* suspend current or all threads - -image::debug/debug.gif[] - -[id="gdb"] -== GDB - -GDB can be used to debug *C/C++* and *Node.js* projects. In Docker 1.13+, a container requires certain capabilities for gdb and gdbserver to start. In `che.env` uncomment the following line and restart Che: - ----- -CHE_DOCKER_SECURITYOPT=seccomp:unconfined ----- - -[id="debugging-local-binary"] -== Debugging Local Binary - -Compile your app with `-g` argument, go to `Run > Edit Debug Configurations > GDB`. Create a new configuration, check `Debug local binary` box. By default, binary path is `${current.project.path/a.out}`. When the debugger attaches, this macro is translated into an absolute path to a currently selected project. `a.out` is the default binary name. If you have compiled binary with a different name, change it: - -image::debug/debug.png[] - -Set a breakpoint in code, go to `Run > Debug > YourDebugConfiguration`. Once a debugger attaches, there’s a notification in the top right corner. A debugger panel will open. - -[id="remote-debugging-with-gdb-server"] -== Remote Debugging with GDB server - -Similar to Java debugger, one needs to start a process that a debugger will connect to. In case of GDB, this is `gdbserver` which is installed in C/CPP runtime by default. - -To *run* gdbserver, execute the following: - -`gdbserver :$port /path/to/binary/file` where `$port` is a random port that you will then connect to. It is important to provide an absolute path to a binary file if you run gdbserver in a command. - -It is important to make sure that the binary has been compiled with `-g` argument, i.e. with attached sources. - -When gdbserver starts, it produces some output with info on process ID and port it’s listening on. When a remote client connects to gdbserver, there will be a message with IP address of a remote connection. - -To *stop* gdbserver, terminate the command in Consoles panel (if the server has been started as a command). If gdbserver has been started in a terminal, Ctrl+C does not kill it. Open another terminal into a machine, and run: - -`kill $(ps ax | grep "[g]dbserver" | awk {'print $1;}')` - -This commands grabs gdbserver PID and kills the process. - -*Connect to GDB server* - -Go to `Run > Edit Debug Configurations` and enter host (localhost if gdbserver has been started in the same workspace environment), port and path to the binary file being debugged. By default, binary name is `a.out`. If you have compiled your binary with `-o` argument, you need to provide own custom binary name in a debug configuration. - -Save your configuration, choose it at `Run > Debug > ` and attach the debugger, having previously set breakpoints in source files. - -*Connection Timeouts* - -Latency or poor connectivity may cause issues with remote debugging. A local GDB may fail to receive a timely response from the remote server. To fix it, set a default timeout for a local GDB. In the terminal, run: - ----- -echo "set remotetimeout 10" > ~/.gdbinit ----- - -You may set a bigger timeout, say, 20 seconds, if there are serious connectivity issues with a remote GDB server. - -It is also possible to add this command as a Dockerfile instruction for a custom recipe: - ----- -FROM eclipse/cpp_gcc -RUN echo "set remotetimeout 10" > /home/user/.gdbinit ----- - -[id="php"] -== PHP - -The PHP and Zend stacks come with the Zend Debugger module installed and configured. Debugging both PHP CLI scripts and PHP web apps is supported. - -The debugging workflow involves the following steps: - -1. Launch the Zend Debugger Client to start listening for new debug sessions. -2. Optionally set breakpoints in the PHP editor. -3. Trigger a debug session from the CLI script or the web app. -4. Use the Web IDE tooling to do the actual debugging. - -image::debug/php-debugging.gif[] - -[id="starting-the-zend-debugger-client"] -== Starting the Zend Debugger Client - -\{\{site.product_formal_name}} has the Zend Debugger Client integrated in the Web IDE. For launching the Zend Debugger Client: - -1. Go to `Run > Edit Debug Configurations` from the main menu. -2. Create new `PHP` configuration. -3. Change any settings if necessary. The defaults are usually OK. -4. Click the `Debug` button. - -image::debug/php-debug-configuration.png[] - -The successful launch of the Zend Debugger Client is noted with a notification message. From this moment on the Zend Debugger Client listens for new debug sessions initiated by the Zend Debugger module of the PHP engine. - -The Debug Configuration window allows the following configuration for the Zend Debugger Client: - -* `Break at first line`. Determines whether to break the execution at the very first line, hit by the PHP interpreter. Enabled by default. It is useful to easily find the app’s entry point. You may want to switch this option off if you defined your own breakpoint and you are not interesting at breaking the execution at the first line. -* `Client host/IP`. The host/IP on which to bind the server socket for listening for new debug sessions. The default host is `localhost`. Changing it should be only necessary if the PHP engine is running in a different workspace machine or outside of the \{\{site.product_mini_name}} workspace at all. -* `Debug port`. The port on which to bind the server socket for listening for new debug sessions. The default port is `10137`. It should be rarely necessary to change it. -* `Use SSL encryption`. Whether to use SSL encryption for the debugging communication between the PHP engine and the Zend Debugger Client. Disabled by default. - -[id="debugging-php-cli-scripts"] -== Debugging PHP CLI Scripts - -PHP CLI scripts can be debugged by setting the `QUERY_STRING` environment variable when executing the PHP script. For example, to debug the `hello.php` script you should execute the following command in the Terminal: - -[source,sh] ----- -QUERY_STRING="start_debug=1&debug_host=localhost&debug_port=10137" php hello.php ----- - -Let’s dissect the value of the `QUERY_STRING`: - -* `start_debug=1` says the PHP engine that we want to trigger a debug session for this execution. -* `debug_host=localhost` says that the Zend Debugger Client runs on localhost (on the same host where the PHP engine runs). -* `debug_port=10137` says that the Zend Debugger Client listens on port 10137. - -For convenience the PHP and Zend stacks have the `debug php script` command. It will run the PHP script, which is currently opened in the editor, with the required `QUERY_STRING` preprended to the launch command. It is a handy way for easily debugging CLI script without the need to remember the exact `QUERY_STRING` variable. - -[id="debugging-php-web-apps"] -== Debugging PHP Web Apps - -Debugging web apps is done in a similar way. The value of the `QUERY_STRING` used for debugging CLI scripts must be added as a query string to the URL of the debugged web page. This can be done either manually or by using a browser toolbar/extension that does it automatically. Such browser extensions also make it easier to debug POST requests. - -*Using Query Params in URL* - -The `?start_debug=1&debug_host=localhost&debug_port=10137` query string must be added to the URL. For example, to debug the `http://localhost:32810/web-php-simple/index.php` web page you should request the following URL in the browser: - ----- -http://localhost:32810/web-php-simple/index.php?start_debug=1&debug_host=localhost&debug_port=10137 ----- - -[id="using-zdebug-extension-for-chrome"] -== Using zDebug Extension for Chrome - -The https://chrome.google.com/webstore/detail/zdebug/gknbnafalimbhgkmichoadhmkaoingil[zDebug] extension can be used for easier triggering of debug sessions from the Chrome browser. The https://chrome.google.com/webstore/detail/zend-debugger-extension/aonajadpeeaijblinaeohfdmbgdpibba[Zend Debugger Extension] is another extension that does the same job. - -It is important to configure the Chrome extension properly before using it for debugging PHP apps running in a \{\{site.product_mini_name}} workspace: - -1. Set `Debug Host` to `localhost` or `127.0.0.1`. -2. Set `Debug Port` to `10137`. -3. Set `Debug Local Copy` to `No`. - -Note that it is not the browser that opens the debug session to the Zend Debugger Client. This is done by the PHP engine that runs in the \{\{site.product_mini_name}} workspace. The browser just tells the PHP engine to do so. So the above settings are for the PHP engine (the Zend Debugger module in particular). Thus the `Debug Host` must be set to `localhost` and not the public host of the docker container running the \{\{site.product_mini_name}} workspace. - -In the end the zDebug settings should look like this: - -image::debug/zdebug-settings.png[] - -Now you are ready to trigger the debug session: - -1. Open the web page to debug. -2. Click on the zDebug toolbar button. -3. Click on `This Page`. - -[id="using-the-zend-debugger-toolbar-for-firefox"] -== Using the Zend Debugger Toolbar for Firefox - -The https://addons.mozilla.org/firefox/addon/zend-debugger-toolbar/[Zend Debugger Toolbar for Firefox] can be used for easier triggering of debug sessions from the Firefox browser. - -After installing it, go to `Extra Stuff > Setttings` to configure the toolbar: - -1. Disable the `Debug Local Copy` option. -2. Switch the `Client/IDE Settings` to `Manual Settings`. -3. Set `Debug Port` to `10137`. -4. Set `IP Address` to `127.0.0.1`. - -In the end the toolbar settings should look like this: - -image::debug/zend-debugger-firefox-settings.png[] - -Now you are ready to trigger the debug session: - -1. Open the web page to debug. -2. Click on the `Debug` toolbar button. - -[id="using-z-ray"] -== Using Z-Ray - -http://www.zend.com/en/products/server/z-ray[Z-Ray] is a productivity tool, part of http://www.zend.com/en/products/zend_server[Zend Server], that is available in the Zend stack. Z-Ray requires no installation or configuraton. It is injected into the response coming from your PHP app and shown right in the browser you are using for development. - -Among other features, it also has the capability to trigger a debug session: - -1. Click on the "bug" button. -2. Click on `Debug current page`. - -image::debug/z-ray-debug.png[] - -That’s all! - -[id="nodejs"] -== NodeJS - -The Node.js ready-to-go link:stacks.html[stack] comes with a Node.js debugger module installed and configured. The Dockerfile is located in the https://github.com/eclipse/che-dockerfiles/blob/master/recipes/node/Dockerfile[eclipse/che-dockerfiles] repository. - -The debugging workflow is: - -1. Launch the Node.js debugger client to start a debug session -2. Create/Run command to generate a preview URL -3. Click the preview URL to interact with the app -4. Use the debugger panel to perform debug functions - -You can set breakpoints in the editor at any time by clicking on the line number. - -*Starting Node.js Debugger Client* - -\{\{site.product_formal_name}} has the Node.js client integrated in the web IDE. to launch the debugger client: - -1. Go to `Run > Edit Debug Configurations` from the main menu -2. Create a new `NODEJS` configuration -3. Change any settings if necessary. The defaults are usually OK -4. Click the `Debug` button -5. The debugger will break at first line of code - -image::debug/debug-nodejs-config.png[] - -*Creating a Command with Preview URL* - -\{\{site.product_formal_name}}’s workspaces have machine(s) that are docker container(s). Docker container’s exposed ports are given an ephemeral port. The preview url provides an easy way convert an internal port to it’s external ephemeral port counter part. - -1. Add a command `Run > Edit Commands` -2. Give the command a name like "View Preview URL" -3. Add a fictitious command `echo` for required command line -4. Provide the preview URL for your app such as `http://${server.port.}/` - -[id="using-node.js-debugger"] -== Using Node.js Debugger - -1. Start the debugger `Run > debug > ` -2. Click the continue button until server is running -3. Add breakpoints if needed -4. Run the preview URL command (see above) -5. Click the preview URL to open web app in another tab -6. Go back to IDE tab -7. Use the Web IDE tooling to do the actual debugging - -image::debug/nodejs-debugger-walkthru.gif[] diff --git a/src/main/pages/che-6/user-guide/dependency-management.adoc b/src/main/pages/che-6/user-guide/dependency-management.adoc deleted file mode 100644 index f7ef4ed044..0000000000 --- a/src/main/pages/che-6/user-guide/dependency-management.adoc +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Dependency Management" -keywords: workspace, runtime, project, projects, dependency management, maven, gradle -tags: [workspace, runtime] -sidebar: che_6_docs -permalink: che-6/dependency-management.html -redirect_from: dependency-management.html -folder: che-6/user-guide ---- - - -[id="maven"] -== Maven - -Maven is natively supported by JDT.LS. - -You can forcefully update dependencies for a Maven project by selecting *Maven > Reimport* from the context menu. - -[id="gradle"] -== Gradle - -Gradle is natively supported by JDT.LS. - -[id="npm"] -== NPM - -There is no plugin for Che that would automatically run `npm install` for JavaScript projects. As a workaround, you can create a link:commands-ide-macro.html[custom command] to install dependencies. diff --git a/src/main/pages/che-6/user-guide/editor_code_assistance.adoc b/src/main/pages/che-6/user-guide/editor_code_assistance.adoc deleted file mode 100644 index 386d52de8c..0000000000 --- a/src/main/pages/che-6/user-guide/editor_code_assistance.adoc +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Editor and Code Assistance" -keywords: workspace, runtime, project, editor, code-completion, code completion, code assistance, intellisense -tags: [workspace, runtime] -sidebar: che_6_docs -permalink: che-6/editor-code-assistance.html -redirect_from: editor-code-assistance.html -folder: che-6/user-guide ---- - - -[id="orion-editor"] -== Orion editor - -=== Use with Che -Eclipse Che uses the Orion editor and integrate it with the language servers, Git, debugger, and other services that run on the server and client side. Che allows the use of custom or user-provided editors. See link:editor.html[Editor] for more information. - -[id="syntax-highlighting"] -=== Syntax highlighting with Orion - -By default, the Orion editor provides syntax highlighting. Che overrides styles for some file types and uses existing styles for other file types. When the opened file does not have syntax highlighting, this means that Orion does not recognize this file type. You can define your own syntax highlighting for custom file types or override existing styles. See: link:editor.html[Editor] for more information. - -[id="code-assistant"] -=== Code assistant - -The Orion editor provides code assistance for JavaScript. - -Code assistance for other languages is provided by link:language-servers.html[Language Servers]. Eclipse Che supports code assistance for Java, C#, PHP, Python, TypeScript, YAML and JSON. There are plans to add language servers for Golang. - -[id="configuring-editor-settings"] -=== Configuring editor settings - -* To configure editor settings in the Che IDE, go to *Profile > Preferences > IDE > Editor*. Preferences can change key bindings, tabbing rules, language tools, whitespace, and ruler preferences. - -* To switch to vi-style or Emacs-style keybindings, go to *Profile > Preferences*. - -* To configure the error and warning preferences for the Java compiler, go to *Profile > Preferences > Java Compiler > Errors/Warnings*. - -[NOTE] -==== -If settings are not applied, refresh your settings. -==== - -[id="splitting-the-editor-into-multiple-panes"] -=== Splitting the editor into multiple panes - -You can split the editor into multiple panes. This allows easier navigation to edit across different files or parts of the same file at the same time. - -* To split the editor into multiple panes, right-click in the editor and select either *Split Vertical* or *Split Horizontal* on the drop-down menu. - -[id="splitting-the-consoles-into-multiple-panes"] -=== Splitting the consoles into multiple panes - -You can split the consoles into multiple panes. This allows easier navigation when trying to see different console outputs at the same time. - -* To split the consoles into multiple panes, select *Split Vertical* or *Split Horizontal* from the drop down at the top right of the console area. - -* To put the new console in a newly created pane, select the open area below the tabs. - -[id="fullsreen-mode-for-panes"] -=== Fullscreen mode for panes - -The editor tabs and console outputs can be displayed in the fullscreen. - -[id="displaying-the-editor-in-fullscreen"] -=== Displaying the editor in fullscreen - -To display the editor in fullscreen mode, double-click on one of the editors tabs. All other panes collapse when you do this. - -To exit fullscreen mode, double-click again on the tab. - -[id="fullscreen-for-consoles"] -=== Fullscreen for consoles - -To display the console outputs and processes tabs in fullscreen mode: -* Double-click on one of the terminals or outputs tab to maximize it. All other panes collapse when you do this. - -* Select the quick pane option displayed in the top right corner of the pane. - -To exit fullscreen mode, double-click again on the tab. - -[id="previewing-html-files"] -=== Previewing HTML files - -To preview an HTML file, right-click in the project explorer and select *Preview* from the popup menu. - -[id="previewing-images"] -=== Previewing images - -* To preview images, double-click in the project explorer. The image opens in the editor area. - -* To open the image in the dedicated browser tab, right-click the image in the project explorer and select *Preview* from the popup menu. diff --git a/src/main/pages/che-6/user-guide/ide-projects.adoc b/src/main/pages/che-6/user-guide/ide-projects.adoc deleted file mode 100644 index dbab23b02d..0000000000 --- a/src/main/pages/che-6/user-guide/ide-projects.adoc +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Importing projects" -keywords: workspace, runtime, project, projects -tags: [workspace, runtime] -sidebar: che_6_docs -permalink: che-6/ide-projects.html -redirect_from: ide-projects.html -folder: che-6/user-guide ---- - - -[id="default-location-of-projects"] -== Default location of projects - -When a workspace machine with a workspace agent starts, the IDE makes calls to the Project API to fetch the workspace projects. By default, projects are located in the `/projects` directory in a machine container or pod. You can not configure this location because other IDE components depend on it. - -Projects are displayed in the project tree in the left panel. To view the projects on the terminal, use the `ls -la /projects` command. When a workspace is stopped, its machines are terminated. The `/projects` directory is mounted on the host file system (either data volume or PVC). When a new container or pod is started, your workspace projects are always there. - -image::ide/project_tree.png[] - -[id="file-watchers"] -== File watchers - -Changes to project source files do not originate from the IDE editor only. File watchers listen to changes on the file system. Resources that you create, edit, or delete on your file system using the terminal or REST API propagate to the project tree and the editor. When importing projects, file watchers are disabled to avoid flooding events. - -[id="importing-projects-in-the-ide"] -== Importing projects in the IDE - -The following are two ways to import a project in the IDE: - -* Add a project to the link:projects.html[workspace configuration] in the *Dashboard*. After the workspace configuration is saved, and the workspace is being opened, the IDE obtains the workspace configuration. Projects associated with the workspace configuration are automatically imported. If these projects are present in a file system, the IDE skips this step. - -* Import a project into a running workspace using the *Workspace* > *Import project* menu option. To import a private project, link:version-control.html[set up the SSH keys]. - -image::ide/import_project.png[] diff --git a/src/main/pages/che-6/user-guide/version-control.adoc b/src/main/pages/che-6/user-guide/version-control.adoc deleted file mode 100644 index d5b003004d..0000000000 --- a/src/main/pages/che-6/user-guide/version-control.adoc +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: "Using version control" -keywords: workspace, runtime, project, projects, git, subversion, version control, clone, pull, push, ssh key, ssh keys, github, oauth, gitlab, bitbucket -tags: -sidebar: che_6_docs -permalink: che-6/version-control.html -redirect_from: version-control.html -folder: che-6/user-guide ---- - -Eclipse Che natively supports the Git version control system (VCS), which is provided by the link:https://www.eclipse.org/jgit/[JGit library]. Versioning functionality is available in the IDE and in the terminal. - -ifeval::["{project-context}" == "che"] -An link:#svn[Subversion (SVN) plug-in] also exists, but it is not part of the default Che assembly. -endif::[] - -The following sections describe how to connect and authenticate users to a remote Git repository. Any operations that involve authentication on the remote repository need to be done via the IDE interface unless authentication is configured separately for the workspace machine (terminal, commands). - -Private repositories require a secure SSH connection. In order to connect to Git repositories over SSH, an SSH key pair needs to be generated. SSH keys are saved in user preferences, so the same key can be used in all workspaces. - -NOTE: HTTPS Git URLs can only be used to push changes when OAuth authentication is enabled. See link:user-management.html#enabling-authentication-with-social-accounts-and-brokering[Enabling authentication with social accounts and brokering]. - -[id="generating-and-uploading-ssh-keys"] -== Generating and uploading SSH keys - -SSH keys can be generated in the Che user interface. - -. Go to *Profile > Preferences > SSH > VCS*, and click the btn:[Generate Key] button. - -. When prompted to provide the host name for your repository, use the bare host name (do not include `www` or `https`) as in the example below. - -. Save the resulting key to your Git-hosting provider account. - -IMPORTANT: The host name is an actual host name of a VCS provider. Examples: `github.com`, `bitbucket.org`. - -=== Using existing SSH keys - -You can upload an existing public key instead of creating a new SSH key. When uploading a key, add the host name (using no `www` or `https` - as in the example below). Note that the *Public key > View* button is not be available when using this option because the public file should be generated already. - -image::git/ssh_keys.gif[] - -The following examples are specific to GitHub and GitLab, but a similar procedure can be used with all Git or SVN repository providers that use SSH authentication. See documentation provided by other providers for additional assistance. - -[IMPORTANT] -==== - -The default type of SSH key does not work in Che. The `git pull` command fails on authorization. To work around the issue, you need a different type of an SSH key. - -To convert an existing SSH key to the `PEM` format, run the following command and substitute `__` for the path to your key file. - -[subs="+quotes"] ----- -$ ssh-keygen -p -f __ -m PEM ----- - -Or, to generate a *new* `PEM` SSH key instead of the default `RFC 4716/SSH2 key`, omit the `-p` flag. Substitute `__` for the path to the new file. - -[subs="+quotes"] ----- -$ ssh-keygen -f __ -m PEM ----- - -==== - -.GitHub example -[example] -==== -When not using GitHub OAuth, you can manually upload a key. To add the associated public key to a repository or account on *github.com*: - -. Click your user icon (top right). -. Go to *Settings > SSH and GPG keys* and click the *New SSH key* button. -. Enter a title and paste the public key copied from Che to the *Key* text field. - -image::git/ssh_github.png[] -==== - -.GitLab example -[example] -==== -To add the associated public key to a Git repository or account on *gitlab.com*: - -. Click your user icon (top right). -. Go to *Settings > SSH Keys*. -. Enter a title and paste the public key copied from Che to the *Key* text field. - -image::git/ssh_gitlab.png[] -==== - - -[id="configuring-github-oauth"] -== Configuring GitHub OAuth - -OAuth for Github allows users to import projects using SSH addresses (`git@`), push to repositories, and use the *Pull Request* panel. To enable automatic SSH key upload to GitHub for users: - -. On *github.com*, click your user icon (top right). -. Go to *Settings* > *Developer settings* > *OAuth Apps*. -. Click the btn:[Register a new application] button. -. In the *Application name* field, enter, for example, `Eclipse Che`. -. In the *Homepage URL* field, enter `pass:q[http://__${CHE_HOST}__:__${CHE_PORT}__]`. -. In the *Authorization callback URL* field, enter `pass:q[http://__${CHE_HOST}__:__${CHE_PORT}__/api/oauth/callback]`. -+ -image::git/github_oauth.png[] - -ifeval::["{project-context}" == "che"] -. On Docker, set the following to environment variables in the `che.env` file (see link:docker-config.html[Docker configuration]). -endif::[] -. On OpenShift, update the deployment configuration (see link:openshift-config.html[OpenShift configuration]). -+ -[subs=+quotes] ----- -CHE_OAUTH_GITHUB_CLIENTID=____ -CHE_OAUTH_GITHUB_CLIENTSECRET=____ -CHE_OAUTH_GITHUB_AUTHURI=https://github.com/login/oauth/authorize -CHE_OAUTH_GITHUB_TOKENURI=https://github.com/login/oauth/access_token -CHE_OAUTH_GITHUB_REDIRECTURIS=http://__${CHE_HOST}__:__${CHE_PORT}__/api/oauth/callback ----- - -[NOTE] -==== -* Substitute all occurrences of `_${CHE_HOST}_` and `_${CHE_PORT}_` with the URL and port of your Che installation. - -* Substitute `__` and `__` with your GitHub client ID and secret. - -ifeval::["{project-context}" == "che"] -* This configuration only applies to single-user deployments of Che. See: link:user-management.html#enabling-authentication-with-social-accounts-and-brokering[Enabling authentication with social accounts and brokering]. -endif::[] -==== - -Once OAuth is configured, SSH keys are generated and uploaded automatically to GitHub by a user in the IDE in *Profile* > *Preferences* > *SSH* > *VCS* by clicking the _Octocat_ icon. You can connect to your GitHub account and choose repositories to clone, rather than having to manually type (or paste) GitHub project URLs. - -[id="configuring-github-oauth-for-openshift-infrastructure"] -== Configuring GitHub OAuth for OpenShift infrastructure - -.Prerequisites - -* A deployed instance of Eclipse Che - -.Procedure - -OAuth for GitHub allows users to import projects using the SSH addresses (`git@`), push to repositories, and use the *Pull Request* panel. The steps listed in this section are performed by an administrative user. - -Note that these steps are applicable when a user has Che 6 deployed in the multi-user mode. - -To enable automatic SSH key upload to GitHub for users, take the following steps: - -. In the *Overview* tab, click the __ to open it. - -. Click the Keycloak link to open the *Red Hat Single Sign-On* window. - -. Expand the *Configure* tab and then click *Identity Providers*. - -. In the *Add provider* drop-down list, click *GitHub*. The *Add identity provider* window is displayed. - -. In the *Add identity provider* window: - -.. The *Redirect URI* field, depending on your Eclipse Che installation, type the Authorization callback URL. - -.. Copy the client ID and the client secret from GitHub and paste them in the *Client ID* and the *Client Secret* fields, respectively. - -.. In the *Homepage URL* and the *Authorization callback URL* field, depending on your Eclipse Che installation, type the two URLS. - -.. In the *Default Scopes* field, type `repo, user, write:publick_key`. - -.. Set *Store Tokens* and *Stored Tokens Readable* to *ON*. - -.. Click *Save*. -+ -The *Success! The github provider has been created.* message indicates success. And, the GitHub provider is added to the *Identity Providers* window. -+ -image::git/github-provider-added.png[] -+ -Perform the following steps to set role mapping for non-administrative users. -+ -. Expand the *Manage* tab and then click *Users*. - -. Click the *Role Mappings* tab. - -. Click the *Client Roles* drop-down menu and click *broker*. - -. In the *Available Roles* list, click *read-token*. - -. Click *Add selected*. - -. In the *Effective Roles* list, click *read-token*. - -The GitHub OAuth is now set for the user. - -[id="gitlab-oauth"] -== Configuring GitLab OAuth - -OAuth integration with GitLab is not supported. Although GitLab supports OAuth for clone operations, pushes are not supported. A feature request to add support exists in the GitLab issue management system: link:https://gitlab.com/gitlab-org/gitlab-ce/issues/18106[Allow runners to push via their CI token]. - - -[id="built-in-pull-request-panel"] -== Submitting pull requests using the built-in Pull Request panel - -Eclipse Che provides a *Pull Request* panel to simplify the creation of pull requests for GitHub, BitBucket, and Microsoft VSTS (with Git) repositories. - -image::git/pr_panel.png[] - - -[id="saving-committer-name-and-email"] -== Saving committer name and email - -Committer name and email are set in *Profile > Preferences > Git > Committer*. Once set, every commit will include this information. - - -[id="git-workspace-clients"] -== Interacting with Git from a workspace - -After importing a repository, you can perform the most common Git operations using interactive menus or as terminal commands. - -NOTE: Terminal Git commands require their own authentication setup. This means that keys generated in the IDE work only when Git is used through the IDE menus. Git installed in a terminal is a different Git system. You can generate keys in `~/.ssh` there as well. - -image::git/git.gif[] - -Use keyboard shortcuts to access the most frequently used Git functionality faster: - -|=== -| Commit | kbd:[Alt+C] -| Push to remote | kbd:[Alt+Shift+C] -| Pull from remote | kbd:[Alt+P] -| Work with branches | kbd:[Ctrl+B] -| Compare current changes with the latest repository version | kbd:[Ctrl+Alt+D] -|=== - - -[id="git-in-project-tree-and-editor"] -== Git status highlighting in the project tree and editor - -Files in project explorer and editor tabs can be colored according to their Git status: - -image::git/project-explorer-editor-tabs-git-colors.png[] - -* Green: new files that are staged in index -* Blue: files that contain changes -* Yellow: files that are not staged in index - -The editor displays change markers according to file edits: - -image::git/editor-git-change-markers.png[] - -* Yellow marker: modified line(s) -* Green marker: new line(s) -* White triangle: removed line(s) - - -[id="git-operations"] -== Performing Git operations - -=== Commiting - -Commit your changes by navigating to *Git > Commit...* in the main menu, or use the kbd:[Alt+C] shortcut. - -image::git/git-commit-tree-view.png[] - -. Select files that will be added to index and committed. All files in the selected package or folder in the project explorer are checked by default. - -. Type your commit message. Optionally, you can select *Amend previous commit* to modify the previous commit (for more details, see link:https://git-scm.com/docs/git-commit#git-commit---amend[Git commit documentation]). - -. To push your commit to a remote repository by checking the *Push committed changes to* check-box and select a remote branch. - -. Click btn:[Commit] to proceed (the btn:[Commit] button is active when at least one file is selected and a commit message is present, or *Amend previous commit* is checked). - -Behavior for files in the list view is the same as in the *Compare* window (see link:#reviewing-changed-files[Reviewing changed files] section). Double-clicking a file opens diff window with it. - -=== Pushing and pulling - -Push your commits by navigating to *Git > Remotes... > Push* in the main menu, or use the kbd:[Alt+Shift+C] shortcut. - -image::git/git-push.png[] - -. Choose the remote repository. - -. Choose the local and remote branch. - -. Optionally, you can force select *Force push*. - -Get changes from a remote repository by navigating to *Git > Remotes... > Pull* in the main menu, or use the kbd:[Alt+P] shortcut. - -image::git/git-pull.png[] - -You can use *Rebase instead of merge* to keep your local commits on top (for more information, see https://git-scm.com/docs/git-pull#git-pull--r[Git pull documentation]). - -=== Managing branches - -Manage your git branches by navigating to *Git > Branches...* in the main menu, or use the kbd:[Ctrl+B] shortcut. - -image::git/git-branches-window.png[] - -You can filter the branches view by choosing to see only local or remote branches. - - -[id="reviewing-changed-files"] -== Reviewing changed files - -The *Git Compare* window is used to show files that have changed. - -To compare the current state of code to the latest local commit, navigate to *Git > Compare > Select-to-what* in the main menu, or use the kbd:[Ctrl+Alt+D] shortcut. Another way is to select an object in the project tree and choose *Git > Select-to-what* from the context menu of an item. - -.Listing changed files - -The *Git Compare* window shows changed files in the selected object in the project explorer. To see all changes, select a project folder. If only one file has changed, a diff window is shown instead of the compare window. - -image::git/git-compare-tree-view.png[] - -By default, affected files are listed as a tree. - -The *Expand all directories* and *Collapse all directories* options help to get a better view. The btn:[View as list] button switches the view of changed files to a list, where each file is shown with its full path. To return to the tree view, click btn:[Group by directories]. - -image::git/git-compare-list-view.png[] - -.Viewing diffs - -To view a diff for a file, select the file and click *Compare*, or double-click the file name. - -You can review changes between two states of code. To view the diff, go to *Git > Compare > Select-to-what* in main menu. If more than one file has changed, a list of the changed files is opened first. To select a file to compare, double-click it, or select a file, and then click *Compare*. Another way to open a diff is to select a file in the *Projects Explorer* and choose *Git > Select-to-what* from its context menu or directly from the context menu in the editor. - -image::git/git-diff-widget.png[] - -Your changes are shown on the left, and the file being compared to is on the right. The left pane can be used for editing and fixing your changes. - -To review multiple files, you can navigate between them using the btn:[Previous] (or kbd:[Alt+.]) and btn:[Next] (or kbd:[Alt+,]) buttons. The number of files for review is displayed in the title of the diff window. - -The btn:[Refresh] button updates the difference links between the two panes. - -ifeval::["{project-context}" == "che"] -[id="svn"] -== Subversion (SVN) - -The SVN plug-in is not included in the default Che build. You can build your own link:https://github.com/eclipse/che-plugin-svn[Che assembly with this plugin]. -endif::[] diff --git a/src/main/pages/che-6/user-management/authentication.adoc b/src/main/pages/che-6/user-management/authentication.adoc deleted file mode 100644 index 327110307c..0000000000 --- a/src/main/pages/che-6/user-management/authentication.adoc +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: "Che Authentication" -keywords: user management, permissions, authentication -tags: [keycloak] -sidebar: che_6_docs -permalink: che-6/authentication.html -redirect_from: authentication.html -folder: che-6/user-management ---- - - -[id="authentication-on-che-master"] -== Authentication on Che Master - -[id="openid"] -=== OpenId - -OpenId authentication on Che master, implies presence of an external OpenId provider and has 2 main steps: - -1. Authenticate the user through the JWT token he brought or redirect him to login; -+ -(Authentication tokens should be send in a `Authorization` header. Also, in limited cases when it’s not possible to use `Authorization` header, token can be send in `token` query parameter. An example of such exceptional case can be: OAuth authentification initialization, IDE shows javadoc in iframe where authentication must be initialized.) -2. Compose internal "subject" object which represents the current user inside of the Che master code. - -At the time of writing the only supported/tested OpenId provider is Keycloak, so all examples/links will refer to this implementation. - -The flow starts from the 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`, `client_id` etc returned. in JSON format. - -Service class is *org.eclipse.che.multiuser.keycloak.server.KeycloakSettings*, and it is bound only in multi-user version of Che, so by its presence it is possible to detect if authentication enabled in current deployment or not. - -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" -} ----- - -Also, this service allows to download JS client library to interact with provider. Service URL is `:/api/keycloak/settings` for retrieving settings JSON and `:/api/keycloak/OIDCKeycloak.js` for JS adapter library. - -Next step is redirection of user to the appropriate provider’s login page with all the necessary params like client_id, return redirection path etc. This can be basically done with any client library (JS or Java etc). - -After user logged in on provider’s side and client side code obtained and passed the JWT token, validation of it and creation of subject begins. - -Verification of tokens signature occurs in the two main filters chain: - -* *org.eclipse.che.multiuser.keycloak.server.KeycloakAuthenticationFilter* class. Token is extracted from `Authorization` header or `token` query param and tried to being parsed using public key retrieved from provider. In case of expired/invalid/malformed token, 403 error is sent to user. As noted above, usage of query parameter should be minimised as much as possible, since support of it may be limited/dropped at some point. - -If validation was successful, token is passed to the - -* *org.eclipse.che.multiuser.keycloak.server.KeycloakEnvironmentInitalizationFilter* filter in the parsed form. This filter simply extracts data from JWT token claims, creates user in the local DB if it is not yet present, and constructs subject object and sets it into per-request `EnvironmentContext` object which is statically accessible everywhere. - -If the request was made using machine token only (e.g. from ws agent) then it is only one auth filter in the chain: - -* *org.eclipse.che.multiuser.machine.authentication.server.MachineLoginFilter* - finds userId given token belongs to, than retrieves user instance and sets principal to the session. - -Master-to-master requests are performed using *org.eclipse.che.multiuser.keycloak.server.KeycloakHttpJsonRequestFactory* which signs every request with the current subject token obtained from EnvironmentContext. - -[id="user-profile"] -==== User Profile - -Since keycloak may store user specific information (first/last name, phone number, job title etc), there is special implementation of the ProfileDao which can provide this data to consumers inside Che. Implementation is read-only, so no create/update operations are possible. Class is *org.eclipse.che.multiuser.keycloak.server.dao.KeycloakProfileDao*. - -[id="obtaining-token-from-keycloak"] -==== Obtaining Token From Keycloak - -For the clients which cannot run JS or other type clients (like CLI or selenium tests), auth token may be requested directly from Keycloak. The simplest way to obtain Keycloak auth token, is to perform request to the token endpoint with username and password credentials. This request can be schematically described as following cURL request: - ----- -curl - --data "grant_type=password&client_id=&username=&password=" - http://:5050/auth/realms//protocol/openid-connect/token ----- - -Since the two main Che clients (IDE and Dashboard) utilizes native Keycloak js library, they’re using a customized Keycloak login page and somewhat more complicated authentication mechanism using `grant_type=authorization_code`. It’s a two step authentication: first step is login and obtaining authorization code, and second step is obtaining token using this code. - -Example of correct token response: - -[source,json] ----- -{ - "access_token":"eyJhb...", - "expires_in":300, - "refresh_expires_in":1800, - "refresh_token":"Nj0C...", - "token_type":"bearer", - "not-before-policy":0, - "session_state":"14de1b98-8065-43e1-9536-43e7472250c9" -} ----- - -[id="other-authentication-implementations"] -=== Other authentication implementations - -If you want to adapt authentication implementation other than Keycloak, the following steps must be done: - -* Write own or refactor existing info service which will provide list of configured provider endpoints to the clients; -* Write single or chain of filters to validate tokens, create user in Che DB and compose the Subject object; -* If the new auth provider supports OpenId protocol, OIDC JS client available at settings endpoint can be used as well since it is maximally decoupled of specific implementations. -* If the selected provider stores some additional data about user (first/last name, job title etc), it is a good idea to write an provider-specific ProfileDao implementation which will provide such kind of information. - -[id="oauth"] -=== OAuth - -OAuth authentication part has 2 main flows - internal and external based on Keycloak brokering mechanism. So, there are 2 main OAuth API implementations - *org.eclipse.che.security.oauth.EmbeddedOAuthAPI* and *org.eclipse.che.multiuser.keycloak.server.oauth2.DelegatedOAuthAPI*. - -They can be switched using `che.oauth.service_mode=` configuration property. - -Also, there is support of OAuth1 protocol can be found at *org.eclipse.che.security.oauth1* package. - -The main REST endpoint in tha OAuth API is *org.eclipse.che.security.oauth.OAuthAuthenticationService*, which contains `authenticate` method to start OAuth authentication flow, `callback` method to process callbacks from provider, `token` to retrieve current user’s oauth token, etc. - -Those methods refer to the currently activated embedded/delegated OAuthAPI which is doing all the undercover stuff (finds appropriate authenticator, initializes the login process, user forwarding etc). - -[id="authentication-on-che-agents"] -== Authentication on Che Agents - -Machines may contain services that must be protected with authentication, e.g. agents like workspace agent and terminal. For this purpose, machine authentication mechanism should be used. Machine tokens were introduced to avoid passing the Keycloak tokens to the machine side (which can be potentially insecure). Another reason is that Keycloak tokens may have relatively small lifetime and require periodical renewal/refresh which is hard to manage and keep in sync with same user session tokens on clients etc. - -As agents cannot be queried using Keycloak token, there is only Machine Token option. Machine token can be also passed in header or query parameter. - -[id="machine-jwt-token"] -=== Machine JWT Token - -Machine token is https://jwt.io/[JWT] that contains the following information in its claim: - -* *uid* - id of user who owns this token -* *uname* - name of user who owns this token -* *wsid* - id of a workspace which can be queried with this token - -Each user is provided with unique personal token for each workspace. - -The structure of token and the signature are different to Keycloak and have the following view: - -[source,json] ----- -# Header -{ - "alg": "RS512", - "kind": "machine_token" -} -# Payload -{ - "wsid": "workspacekrh99xjenek3h571", - "uid": "b07e3a58-ed50-4a6e-be17-fcf49ff8b242", - "uname": "john", - "jti": "06c73349-2242-45f8-a94c-722e081bb6fd" -} -# Signature -{ - "value": "RSASHA512(base64UrlEncode(header) + . + base64UrlEncode(payload))" -} ----- - -The algorithm that is used for signing machine tokens is `SHA-512` and it’s not configurable for now. Also, there is no public service that distributes the public part of the key pair with which the token was signed. But in each machine, there must be environment variables that contains key value. So, agents can verify machine JWT token using the following environment variables: - -* `pass:[CHE_MACHINE_AUTH_SIGNATURE__ALGORITHM]` - contains information about the algorithm which the token was signed -* `pass:[CHE_MACHINE_AUTH_SIGNATURE__PUBLIC__KEY]` - contains public key value encoded in Base64 - -It’s all that is needed for verifying machine token inside of machine. To make sure that specified token is related to current workspace, it is needed to fetch `wsid` from JWT token claims and compare it with `CHE_WORKSPACE_ID` environment variable. - -Also, if agents need to query Che Master they can use machine token provided in `CHE_MACHINE_TOKEN` environment, actually it is token of user who starts a workspace. - -[id="authentication-schema"] -=== Authentication schema - -The way how Che master interacts with agents with enabled authentication mechanism is the following: - -image::diagrams/machine_auth_flow.png[] - -Machine token verification on agents is done by the following components: - -* *org.eclipse.che.multiuser.machine.authentication.agent.MachineLoginFilter* - doing basically the same as the appropriate filter on a master, the only thing that is different it’s a way how agent obtains the public signature part. The public key for the signature check is placed in a machine environment, with algorithm description. -* *auth.auth.go* - the entry point for all request that is proceeding on go agents side, the logic of token verification is similar with MachineLoginFilter. - -[id="obtaining-machine-token"] -=== Obtaining Machine Token - -A machine token is provided for users in runtime object. It can be fetched by using get workspace by key (id or namespace/name) method which path equals to `/api/workspace/`. The machine token will be placed in `runtime.machineToken` field. - -[id="using-swagger-or-rest-clients"] -== Using Swagger or REST Clients - -User’s Keycloak token is used to execute queries to secured API on his behalf through REST clients. A valid token must be attached as request header or query parameter - `?token=$token`. Che Swagger can be accessed from `http://che_host:8080/swagger`. A user must be signed-in through Keycloak so that access token is included in request headers. - -By default, swagger loads `swagger.json` from Che master. - -To work with WS Agent, a URL to its `swagger.json` should be provided. It can be retrieved from link:workspace-data-model.html#runtime[Workspace Runtime], by getting URL to link:servers.html[WS Agent server] endpoint and adding `api/docs/swagger.json` to it. Also, to authenticate on WS Agent API, user must include Machine Token, which can be found in Workspace Runtime as well. - -To use Swagger for a workspace agent, user must do following steps: - -* get workspace object with runtimes fetched (using `/api/workspace/` service) -* get WS agent API endpoint URL, and add a path to its `swagger.json` (e.g. `http://:/api/docs/swagger.json` for Docker or `http:///api/docs/swagger.json` for OpenShift ). Put it in the upper bar `URL` field: - -[source,json] ----- -"wsagent/http": { - "url": "http://172.19.20.180:32777/api", - "attributes": {}, - "status": "RUNNING" -} ----- - -* get machine token from `runtime.machineToken` field, and put it in the upper bar `token` field - ----- -"machineToken": "eyJhbGciOiJSUzUxMiIsImtpbmQiOiJtYWNoaW5lX3Rva2VuIn0.eyJ3c2lkIjoid29ya3NwYWNlMzEiLCJ1aWQiOiJ1c2VyMTMiLCJ1bmFtZSI6InRlc3RVc2VyIiwianRpIjoiOTAwYTUwNWYtYWY4ZS00MWQxLWFhYzktMTFkOGI5OTA5Y2QxIn0.UwU7NDzqnHxTr4vu8UqjZ7-cjIfQBY4gP70Nqxkwfx8EsPfZMpoHGPt8bfqLWVWkpp3OacQVaswAOMOG9Uc9FtLnQWnup_6vvyMo6gchZ1lTZFJMVHIw9RnSJAGFl98adWe3NqE_DdM02PyHb23MoHqE_xd8z3eFhngyaMImhc4", ----- - -* click Explore to load Swagger for WS Agent - -image::devel/swagger.png[] diff --git a/src/main/pages/che-6/user-management/organizations.adoc b/src/main/pages/che-6/user-management/organizations.adoc deleted file mode 100644 index b2f3bd4ea6..0000000000 --- a/src/main/pages/che-6/user-management/organizations.adoc +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: "Organizations" -keywords: organizations, user management, permissions -tags: [organizations] -sidebar: che_6_docs -permalink: che-6/organizations.html -redirect_from: organizations.html -folder: che-6/user-management ---- - - -[id="organizations-in-eclipse-che"] -== Organizations in Eclipse Che - -Organizations allow administrators to group Eclipse Che users and allocate resources. The system administrator controls and allocates resources and permissions within the administrator dashboard. - -[id="roles-in-an-organization"] -=== Roles in an organization - -A user can have the following roles in an organization: - -Members:: Create workspaces, manage their own workspaces, and use any workspaces they have permissions for. -Administrators:: Manage the organization, members, resources, and sub-organization, and can edit settings. -System Administrators:: Create root organizations, manages resources, members and sub-organizations. System administrators have more permissions than the administrators and members. - -[id="root-organizations-and-sub-organizations"] -=== Root organizations and sub-organizations - -The top-level organizations are called root organizations. Multiple root organizations can be created. Any organization can have zero to a set number of sub-organizations. Only the system administrator can create root organizations and manage the resources of the root organization. - -[id="creating-an-organization"] -=== Creating an organization - -Only the system administrator can create root organizations. An administrator can create sub-organizations. - -To create an organization: - -. Click the menu in the left sidebar. A new page displays all the organizations in your system. - -. Click on the upper-left button to create a new organization. - -[id="displaying-the-list-of-organizations"] -=== Displaying the list of organizations - -The *Organization* page displays a list of all the organizations. The list contains the following information for each organization: number of members, total RAM, available RAM, and number of sub-organizations. - -[id="adding-members-to-organizations"] -=== Adding members to organizations - -To add members to an organization: - -. Click the *Add* button to add a member. A new pop-up window displays. You can change the role of a member or remove them from the organization at any time. - -. Enter the new member name. - -[NOTE] -==== -Users with the green checkmark beside their name already have an Eclipse Che account and can be added to the organization. Users without a checkmark do not have an account and cannot be added into the organization. -==== - -[id="workspaces-in-organizations"] -=== Workspaces in organizations - -A workspace is created inside of an organization and uses the resources of the organization. The workspace creator chooses the organization on the *Workspace Creation* page. - -[id="setting-email-notifications"] -=== Setting email notifications - -To send notifications from the Che server when a user joins or leaves an organization, you can do either of the following: - -* Configure the SMTP server in the `che.env` file. - -* For OpenShift, add environment variables to the deployment. - -Che does not have a built-in SMTP server by default. You may use any mail server. - -For example, to send a notification email to your Gmail account, set the following environment variables: - ----- -CHE_MAIL_PORT=465 -CHE_MAIL_HOST=smtp.gmail.com -CHE_MAIL_SMTP_STARTTLS_ENABLE=true -CHE_MAIL_SMTP_AUTH=true -CHE_MAIL_SMTP_AUTH_USERNAME=no-reply@gmail.com -CHE_MAIL_SMTP_AUTH_PASSWORD=password ----- - -[id="creating-sub-organizations"] -=== Creating sub-organizations - -To create a sub-organization: - -* On the *Organization Details* page, select the *Sub-Organizations* tab. - -* Click the *Add Sub-Organization* button. - -The steps to create a sub-organization are the same as that for creating an organization. Use them to create the organization. - -[id="adding-members-to-sub-organizations"] -=== Adding members to sub-organizations - -You can only add members of the parent organization as members of the sub-organization. - -[id="organization-and-sub-organization-administration"] -=== Organization and sub-organization administration - -The settings of the organization are visible to all members of the organization. Only the Eclipse Che system administrator can modify the settings. - -[id="renaming-an-organization-or-sub-organization"] -=== Renaming an organization or sub-organization - -[NOTE] -==== -Only an Eclipse Che system administrator and administrator of the organization can rename an organization or sub-organization. -==== - -To rename an organization: - -. Click the *Name* field to edit the name of the organization. The save mode appears. - -. Click the *Save* button to update the name. - -The name of the organization or sub-organization must follow these rules: - -* Only alphanumeric characters and a single dash (-) can be used. - -* Spaces cannot be used. - -* Each organization name must be unique within the Eclipse Che installation. - -* Each sub-organization name must be unique within an organization. - -[id="leaving-an-organization-or-sub-organization"] -=== Leaving an organization or sub-organization - -To leave an organization, members need to contact the administrator of the organization or the system administrator of Eclipse Che. - -[id="deleting-an-organization-or-sub-organization"] -=== Deleting an organization or sub-organization - -[IMPORTANT] -==== -* Only system administrators or administrators of the organization can delete an organization or sub-organization. -* This action cannot be reverted, and all workspaces created under the organization will be deleted. -* All members of the organization will receive an email notification to inform them about the deletion of the organization. -==== - -To delete an organization or a sub-organization: - -* Click the *Delete* button. - -[id="allocating-resources-for-organizations"] -=== Allocating resources for organizations - -Workspaces use the resources of the organization that are allocated by the system administrator. The resources for sub-organizations are taken from the parent organization. Administrators control the portion of resources, of the parent organization, that are available to the sub-organization. - -[id="managing-limits"] -=== Managing limits - -[NOTE] -==== -Managing limits is restricted to the Eclipse Che system administrator and administrator of the organization. -==== - -The system configuration defines the default limits. The administrator of the organization manages only the limits of its sub-organizations. No resource limits apply to the organization by default. The following are the limits defined by the system administrator: - -* *Workspace Cap*: The maximum number of workspaces that can exist in the organization. -* *Running Workspace Cap*: The maximum number of workspaces that can run simultaneously in the organization. + -* *Workspace RAM Cap*: The maximum amount of RAM that a workspace can use in GB. - - -[id="updating-organization-and-sub-organization-member-roles"] -=== Updating organization and sub-organization member roles - -[NOTE] -==== -Updating the members of an organization or sub-organization is restricted to the Eclipse Che system administrator and administrator of the organization. -==== - -To edit the role of an organization member: - -. Click the *Edit* button in the *Actions* column. Update the role of the selected member in the pop-up window. - -. Click *Save* to confirm the update. - -[id="removing-organization-and-sub-organization-members"] -=== Removing members from an organization and sub-organization - -[NOTE] -==== -Removing the members of an organization or sub-organization is restricted to the Eclipse Che system administrator and administrator of the organization. -==== - -To remove a member: - -. Click the *Delete* button in the *Actions* column. In the confirmation pop-up window, confirm the deletion. - -To remove multiple members: - -. Select the check boxes to select multiple members from the organization. - -. Click the *Delete* button that appears in the header of the table. The members that are removed from the organization will receive an email notification. - diff --git a/src/main/pages/che-6/user-management/permissions.adoc b/src/main/pages/che-6/user-management/permissions.adoc deleted file mode 100644 index b5d08ee654..0000000000 --- a/src/main/pages/che-6/user-management/permissions.adoc +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: "Permissions" -keywords: organizations, user management, permissions -tags: [organizations] -sidebar: che_6_docs -permalink: che-6/permissions.html -redirect_from: permissions.html -folder: che-6/user-management ---- - - -[id="permissions-overview"] -== Overview - -Permissions are used to control the actions of users and establish a security model. You can control resources managed by Che and allow certain actions by assigning permissions to users. - -Permissions can be applied to the following: - -* Workspace -* Organization -* Stack -* System - -[id="workspace-permissions"] -== Workspace permissions - -The user who creates a workspace is the workspace owner. The workspace owner has the following permissions by default: `read`, `use`, `run`, `configure`, `setPermissions`, and `delete`. Workspace owners invite users into the workspace and control workspace permissions for each user. - -The following permissions are associated with workspaces: - -[cols=",",options="header",] -|=== -|Permission |Description -|read |Allows reading the workspace configuration. -|use |Allows using a workspace and interacting with it. -|run |Allows starting and stopping a workspace. -|configure |Allows defining and changing the workspace configuration. -|setPermissions |Allows updating the workspace permissions for other users. -|delete |Allows deleting the workspace. -|=== - -[id="organization-permissions"] -== Organization permissions - -An organization is a named set of users. - -The following permissions are applicable to organizations: - -[width="100%",cols="30%,70%",options="header",] -|=== -|Permission |Description -|update |Allows editing of the organization settings and information. -|delete |Allows deleting an organization. -|manageSuborganizations |Allows creating and managing sub-organizations. -|manageResources |Allows redistribution of an organization’s resources and defining the resource limits. -|manageWorkspaces |Allows creating and managing all the organization’s workspaces. -|setPermissions |Allows adding and removing users and updating their permissions. -|=== - -[id="system-permissions"] -== System permissions - -System permissions control aspects of the whole Che installation. - -The following permissions are applicable to the organization: - -[cols=",",options="header",] -|=== -|Permission |Description -|manageSystem |Allows control of the system, workspaces, and organizations. -|setPermissions |Allows updating the permissions for users on the system. -|manageUsers |Allows creating and managing users. -|monitorSystem |Allows for accessing endpoints used for monitoring the state of the server. -|=== - -All system permissions will be granted to the administration user configured with the pass:[`CHE_SYSTEM_ADMIN__NAME`] property (the default is `admin`). -This happens at Che Server start. If the user is not present in the Che user database, it happens after the user's login. - -[id="manage-system-permission"] -== manageSystem permission - -Users with the `manageSystem` permission have access to the following services: - -[cols=",,",options="header",] -|=== -|Path | HTTP Method | Description -|`/resource/free/` |GET | Get free resource limits -|`/resource/free/{accountId}` |GET | Get free resource limits for given account -|`/resource/free/{accountId}` |POST | Edit free resource limit for given account -|`/resource/free/{accountId}` |DELETE | Remove free resource limit for 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 Che Server -|`/logger/{name}` |GET | Get configurations of logger by its name in Che Server -|`/logger/{name}`|PUT | Create logging in Che Server -|`/logger/{name}` |POST | Edit logging in Che Server -|`/resource/{accountId}/details` |GET | Get detailed information about resources for given account -|`/system/stop` |POST | Shutdown all system services, prepare Che to stop -|`/stacks` |All methods | All Stack service methods -|=== - -[id="monitor-system-permissions"] -== monitorSystem permission - -Users with the `monitorSystem` permission have access to the following services: - -[cols=",,",options="header",] -|=== -|Path | HTTP Method | Description -|`/activity` |GET | Get workspaces in certain state for a certain amount of time -|=== - -[id="super-privileged-mode"] -== Super-privileged mode - -The `manageSystem` permission can be extended to provide a super-privileged mode. This allows the user to perform advanced actions on any resources managed by the system. You can read and stop any workspaces with the `manageSystem` permission and assign permissions to users as needed. - -The super-privileged mode is disabled by default. You can change to super-privileged mode by configuring the pass:[`CHE_SYSTEM_SUPER__PRIVILEGED__MODE`] variable to `true` in the `che.env` file. - -List of services that are enabled for users with `manageSystems` permissions and with super-privileged mode on: - -[cols=",,",options="header",] -|=== -|Path | HTTP Method | Description -|`/workspace/namespace/{namespace:.*}` |GET |Get all workspaces for given namespace. -|`/workspace/{id}` |DELETE |Stop workspace -|`/workspace/{key:.*}` |GET | Get workspace by key -|`/organization/resource/{suborganizationId}/cap` |GET |Get resource cap for given organization -|`/organization/resource/{suborganizationId}/cap` |POST |Set resource cap for given organization -|`/organization/{parent}/organizations` |GET | Get child organizations -|`/organization` |GET | Get user's organizations -|=== - -[id="stack-permissions"] -== Stack permissions - -A stack is a runtime configuration for a workspace. See link:stacks.html[stack definition] for more information on stacks. - -The following permissions are applicable to stacks: - -[cols=",",options="header",] -|=== -|Permission |Description -|search |Allows searching of the stacks. -|read |Allows reading of the stack configuration. -|update |Allows updating of the stack configuration. -|delete |Allows deleting of the stack. -|setPermissions |Allows managing permissions for the stack. -|=== - -[id="permissions-api"] -== Permissions API - -All permissions can be managed using the provided REST API. The APIs are documented using Swagger at `[{host}/swagger/#!/permissions]`. - -[id="list-permissions"] -== Listing permissions - -To list the permissions that apply to a specific resources, run this command: ----- -$ GET /permissions ----- - -The `domain` values are: - -[cols="",options="header",] -|=== -|Domain -|`system` -|`organization` -|`workspace` -|`stack` -|=== - -[NOTE] -==== -`domain` is optional. In this case, the API returns all possible permissions for all domains. -==== - -[id="list-permissions-for-specific-user"] -== Listing permissions for a user - -To list the permissions that apply to a user, run this command: - ----- -$ GET /permissions/{domain} ----- - -The `domain` values are: - -[cols="",options="header",] -|=== -|Domain -|`system` -|`organization` -|`workspace` -|`stack` -|=== - - -[id="list-permissions-for-all-users"] -== Listing permissions for all users - -[NOTE] -==== -You must have sufficient permissions to see this information. -==== - -To list the permissions that apply to all users, run this command: - ----- -GET /permissions/{domain}/all ----- - -The `domain` values are: - -[cols="", options="header",] -|=== -|Domain -|`system` -|`organization` -|`workspace` -|`stack` -|=== - - -[id="assign-permissions"] -== Assigning permissions - -To assign permissions to a resource, run this command: - -`POST /permissions` - -The `domain` values are: - -[cols="",options="header",] -|=== -|Domain -|`system` -|`organization` -|`workspace` -|`stack` -|=== - -The following is a message `body` that requests permissions for a user with a `userID` to a workspace with a `workspaceID`: - -[source,json] ----- -{ - "actions": [ - "read", - "use", - "run", - "configure", - "setPermissions" - ], - "userId": "userID", - "domainId": "workspace", - "instanceId": "workspaceID" -} ----- - -The `instanceId` parameter corresponds to the ID of the resource that retrieves the permission for all users. The `userId` parameter corresponds to the ID of the user that has been granted certain permissions. - -[id="sharing-permissions"] -== Sharing permissions - -A user with `setPermissions` privileges can share a workspace and grant `read`, `use`, `run`, `configure`, or `setPermissions` privileges to other users. - -To share workspace permissions: - -* Select a workspace in the user dashboard, navigate to the *Share* tab and enter emails of users. Use commas or space as separators if there are multiple emails. diff --git a/src/main/pages/che-6/user-management/resource-management.adoc b/src/main/pages/che-6/user-management/resource-management.adoc deleted file mode 100644 index a7dbe9b4c1..0000000000 --- a/src/main/pages/che-6/user-management/resource-management.adoc +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "Resource Management" -keywords: organizations, user management, permissions, resource management, RAM allocation -tags: [ldap, keycloak] -sidebar: che_6_docs -permalink: che-6/resource-management.html -redirect_from: resource-management.html -folder: che-6/user-management ---- - - -[id="resource-management-overview"] -== Overview - -The Resource API manages the resources that are utilized by Che users. The Che administrators set the limits on the amount of resources available for each resource type and each user. - -There are two kinds of accounts used in Che: - -* _personal_ - This account belongs to a user. Only one user can utilize resources provided to the account. -* _organizational_ - This account belongs to an link:organizations.html[organization]. This type of account allows each member of the organization to use resources. Resources are distributed between an organization and sub-organizations. - -Resource usage mostly refers to resources used by workspaces and runtimes in the development flow. - -Multi-user Che supports the following types of resources: - -* *RAM* - Amount of RAM which can be used by running workspaces at the same time. -* *Timeout* - Period of time that is used to control idling of user workspaces. -* *Runtime* - Number of workspaces that users can run at the same time. -* *Workspace* - Number of workspaces that users can have at the same time. - -[id="resource-api"] -== Resource API - -*Total resources* - -`GET resource/${accountId}:` Gets the list of total resources an account can use; - -*Used resources* - -`GET resource/{accountId}/used:` Gets the resources used by an account; - -*Available resources* - -`GET resource/${accountId}/available:` Gets the resources that are available and not used by an account. If no resources are used, the available resources equal total resources. If resources are used, the available resources equals total resources minus used resources. - -*Resource details* - -`GET resource/{accountId}/details:` Gets detailed information about the resources available for an account. The detailed information includes: resource providers, resource-usage start time, and resource-usage end time. - -For more information about the response objects and required parameters, see the Swagger page at `${che-host}/swagger/#/resource`. - -[id="distributing-resources"] -== Distributing resources - -The following are ways to distribute resources to an account: - -* Che administrator specifies default free resources limit for account by configuration. - -* Che administrator overrides the default free resources limit for account by resource-free API. - -[id="configuring-workspaces-and-resources"] -== Configuring workspaces and resources - -The Che administrator can limit how workspaces are created and the resources that these workspaces consume. Detailed information about each property can be found in the https://github.com/eclipse/che/blob/master/dockerfiles/init/manifests/che.env#L538[`che.env`] file. - -See link:docker-config.html[Docker] and link:openshift-config.html[OpenShift] configuration documentation for more information. - -[width="100%",cols="33%,8%,6%,53%",options="header",] -|=== -|Property name |Default Value |Unit |Description -|`CHE_LIMITS_USER_WORKSPACES_COUNT` |-1 |item |maximum number of workspaces that the Che user can create -|`CHE_LIMITS_USER_WORKSPACES_RUN_COUNT` |-1 |item |maximum number of simultaneously running workspaces for a Che user -|`CHE_LIMITS_USER_WORKSPACES_RAM` |-1 |memory |maximum amount of RAM that workspaces use -|`CHE_LIMITS_ORGANIZATION_WORKSPACES_COUNT` |-1 |item |maximum number of workspaces that members of an organization can create -|`CHE_LIMITS_ORGANIZATION_WORKSPACES_RUN_COUNT` |-1 |item |maximum number of workspaces that members of an organization can simultaneously run -|`CHE_LIMITS_ORGANIZATION_WORKSPACES_RAM` |-1 |memory |maximum amount of RAM that workspaces from all organizations can simultaneously use -|`CHE_LIMITS_WORKSPACE_IDLE_TIMEOUT` |-1 |millisecond |maxium number of workspaces that can stay inactive before they are idled -|`CHE_LIMITS_WORKSPACE_ENV_RAM` |16gb |memory |maximum amount of RAM that workspace environment can use simultaneously -|=== - -[id="unit-formats"] -== Unit formats - -The unit has the following formats: - -* `-1`: An unlimited value. Any operation, aggregation, and deduction of resources will return `-1`. - -* `memory`: A plain or fixed-point integer measured in bytes. - -+ -Memory uses one of the following suffixes: -+ -[cols=",",options="header",] -|=== -|Suffix name |Description -|`k` / `kb` / `kib` |kilo bytes `1k` = `1024b` -|`m` / `mb` / `mib` |mega bytes `1m` = `1024k` -|`g` / `gb` / `gib` |giga bytes `1g` = `1024m` -|`t` / `tb` / `tib` |terra bytes `1t` = `1024g` -|`p` / `pb` / `pib` |peta bytes `1p` = `1024t` -|=== - -* `item` - An integer describing the number of objects. -* `millisecond` - An integer describing the time frame in milliseconds. - -[id="resource-free-api"] -== Resource-free API - -The Resource-free API manages the free resources that are provided by the system configuration. You can override resources for an account. - -*Free Resources* - -`GET resource/free:` Gets the resources that are available. - -`GET resource/free/{accountId}:` Gets the resources that are available for this account. - -*Set Free Resources* - -`POST resource/free:` Sets the maximum amount of resources available for the user organization account. This number overrides the Сhe configuration. It will be used in all further operations with resources. - -*Remove Free Resources* - -`DELETE resource/free/{accountId}:` Deletes the number of resources available for the user and organization account. The system configuration defines the amount of resources available. - -For more information on response objects and required parameters, see the Swagger page at `{che-host}/swagger/#/resource-free`. - -[id="organization-resource-api"] -== Organization Resource API - -*Distributed Organization Resources* - -`GET organization/resource/{organizationId}:` Gets the resources that the parent organization provides to the sub-organization. - -*Sub-Organization Resources Cap* - -`GET organization/resource/{suborganizationId}/cap:` Gets the maximum amount of resources that are available for a sub-organization; By default, sub-organizations can use all the resources of the parent organization. - -*Set Sub-Organization Resources Cap* - -`POST organization/resource/{suborganizationId}/cap:` Sets the maximum amount of resources for a sub-organization. This limits the usage of shared resources by the sub-organization. - -See the Swagger page at `{che-host}/swagger/#/organization-resource` for more detailed specification of response objects and required parameters. diff --git a/src/main/pages/che-6/user-management/user-management.adoc b/src/main/pages/che-6/user-management/user-management.adoc deleted file mode 100644 index d62566558f..0000000000 --- a/src/main/pages/che-6/user-management/user-management.adoc +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Managing users" -keywords: organizations, user management, permissions -tags: [ldap, keycloak] -sidebar: che_6_docs -permalink: che-6/user-management.html -redirect_from: user-management.html -folder: che-6/user-management ---- - - -[id="authorization-and-user-management"] -== Authorization and user management - -Eclipse Che uses http://www.Keycloak.org[Keycloak] to create, import, manage, delete, and authenticate users. Keycloak uses built-in authentication mechanisms and user storage. It can use third-party identity management systems to create and authenticate users. Eclipse Che requires a Keycloak token when you request access to Che resources. - -Local users and imported federation users must have an email address in their profile. - -The default Keycloak credentials are `admin:admin`. You can use the `admin:admin` credentials when logging into Che for the first time. It has system privileges. - -To find your Keycloak URL: - -If Che is deployed on OpenShift: - -* Go to the OpenShift web console and navigate to the *Keycloak* namespace. - -ifeval::["{project-context}" == "che"] -If Che is running on Docker: - -* Go to `$CHE_HOST:5050/auth`. -endif::[] - -[id="configuring-che-to-work-with-keycloak"] -== Configuring Che to work with Keycloak - -The deployment script ensures that Keycloak is properly configured when Che is deployed on OpenShift or installed on Docker. When the `che-public` client is created, the following fields are populated: - -* *Valid Redirect URIs*: Use this URL to access Che. -* *Web Origins* - -The following are common errors when configuring Che to work with Keycloak: - -*Invalid `redirectURI` error*: occurs when you access Che at `myhost`, which is an alias, and your original `CHE_HOST` is `1.1.1.1`. If this error occurs, go to the Keycloak administration console and ensure that the valid redirect URIs are configured. - -*CORS error*: occurs when you have an invalid web origin - -[id="configuring-keycloak-tokens"] -== Configuring Keycloak tokens - -A user token expires after 30 minutes by default. - -You can change the following Keycloak token settings: - -image::keycloak/keycloak_realm.png[] - -[id="setting-up-user-federation"] -== Setting up user federation - -Keycloak federates external user databases and supports LDAP and Active Directory. You can test the connection and authenticate users before choosing a storage provider. - -See the http://www.keycloak.org/docs/3.2/server_admin/topics/user-federation.html[User storage federation] page in Keycloak documentation to learn how to add a provider. - -See the http://www.keycloak.org/docs/3.2/server_admin/topics/user-federation/ldap.html[LDAP and Active Directory] page in Keycloak documentation to specify multiple LDAP servers. - -[id="enabling-authentication-with-social-accounts-and-brokering"] -== Enabling authentication with social accounts and brokering - -Keycloak provides built-in support for GitHub, OpenShift, and most common social networks such as Facebook and Twitter. See Instructions to http://www.keycloak.org/docs/3.2/server_admin/topics/identity-broker/social/github.html[enable Login with GitHub]. - -You can also enable the SSH key and upload it to the Che users’ GitHub accounts. - -To enable this feature when you register a GitHub identity provider: - -. Set scope to `repo,user,write:public_key`. - -. Set store tokens and stored tokens readable to *ON*. - -image::git/kc_provider.png[] - -. Add a default read-token role. - -image::git/kc_roles.png[] - -This is the default `delegated` OAuth service mode for multi-user Che. You can configure the OAuth service mode with the property `che.oauth.service_mode`. - -To use Che's OAuth Authenticator, set `che.oauth.service_mode` to `embedded` and use link:version-control.html#github-oauth[Instructions for single-user mode]. - -See link:ide_projects.html#importing-projects-in-the-ide[SSH key management] for more information. - -[id="using-protocol-based-providers"] -== Using protocol-based providers - -Keycloak supports http://www.Keycloak.org/docs/3.2/server_admin/topics/identity-broker/saml.html[SAML v2.0] and http://www.Keycloak.org/docs/3.2/server_admin/topics/identity-broker/oidc.html[OpenID Connect v1.0] protocols. You can connect your identity provider systems if they support these protocols. - -[id="managing-users"] -== Managing users - -You can add, delete, and edit users in the user interface. See: http://www.Keycloak.org/docs/3.2/server_admin/topics/users.html[Keycloak User Management] for more information. - -[id="smtp-configurationemail-notifications"] -== Configuring SMTP and email notifications - -Eclipse Che does not provide any pre-configured MTP servers. - -To enable SMTP servers in Keycloak: - -. Go to `che realm settings > Email`. - -. Specify the host, port, username, and password. - -Eclipse Che uses the default theme for email templates for registration, email confirmation, password recovery, and failed login. diff --git a/src/main/pages/che-6/workspace-admin/env-variables.adoc b/src/main/pages/che-6/workspace-admin/env-variables.adoc deleted file mode 100644 index 731eb8121d..0000000000 --- a/src/main/pages/che-6/workspace-admin/env-variables.adoc +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Environment variables" -keywords: workspace, runtime, recipe, docker, stack, environment variables, env, envs -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/env-variables.html -redirect_from: env-variables.html -folder: che-6/workspace-admin ---- - - -Environment variables are defined per machine. Depending on the infrastructure, they are added either to the container or the Kubernetes pod definition. You can add, edit, and remove environment variables either in the *User Dashboard* or directly in the workspace machine configuration. - -The following is an example of an environment variable: - -[source,json] ----- -"env": { - "key": "value" - } ----- - -You can use environment variables in applications running in a workspace, in link:commands-ide-macro.html[commands], and in the terminal. The Che server also adds some environment variables that a user does not control, although they are available to use. For example, they can be used as an API endpoint or workspace ID. - -The following shows how to add a new environment variable: - -image::workspaces/env_variable.png[] diff --git a/src/main/pages/che-6/workspace-admin/environments.adoc b/src/main/pages/che-6/workspace-admin/environments.adoc deleted file mode 100644 index 3fc0d77a30..0000000000 --- a/src/main/pages/che-6/workspace-admin/environments.adoc +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Workspace Environments" -keywords: workspace, runtime, recipe, docker, yaml, Dockerfile, docker, kubernetes, container, pod, environment -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/environments.html -redirect_from: environments.html -folder: che-6/workspace-admin ---- - diff --git a/src/main/pages/che-6/workspace-admin/installers.adoc b/src/main/pages/che-6/workspace-admin/installers.adoc deleted file mode 100644 index 566fce2897..0000000000 --- a/src/main/pages/che-6/workspace-admin/installers.adoc +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Installers" -keywords: workspace, runtime, recipe, docker, stack, installers, agents -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/installers.html -redirect_from: installers.html -folder: che-6/workspace-admin ---- - - -[id="what-are-installers"] -== What are installers? - -Installers are scripts that are added into machines in a runtime. Once running, installers: - -. Prepare the environment and download dependencies for a particular software or tool. -. Install chosen software and dependencies. -. Launch software and tools with particular arguments and modes that provide extra functionality for a workspace. - -Installers are typically language servers and tools that provide features such as SSH access to a workspace machine. You can find a complete list of available installers in the *Workspace details > Installers* tab. - -The following is an example of installers: - ----- -"installers": [ - "org.eclipse.che.exec", - "org.eclipse.che.terminal", - "org.eclipse.che.ws-agent", - "org.eclipse.che.ssh" - ] ----- - -[id="how-installers-work"] -== How installers work - -Installers are saved in a configuration file that a link:what-are-workspaces.html#bootstrapper[bootstrapper] uses to execute jobs. An installer script works exactly the same way as other shell scripts in Linux. The Che server checks if the launched process is running. - -Some installers activate special agents, such as the workspace, terminal, and execution agents. If a workspace agent fails to start, the workspace is treated as if it has been started but the IDE is not usable. If the execution agent fails, the *commands* widget is unavailable. - - -[id="what-happens-when-enabling-and-disabling-installers"] -== What happens when enabling and disabling installers - -You can enable or disable installers per machine by using the *User Dashboard* or by updating the workspace machine configuration. When an installer is enabled, the bootstrapper executes an installer script after the workspace has started. - -The following shows installers that are enabled and disabled: - -image::workspaces/installers.png[] - -[id="troubleshooting-installer-failures"] -== Troubleshooting installer failures - -=== Permission denied failure - -Installers run as if a user in the container has `sudoers` privileges. If the user does not have the privileges, the installer fails with `permission denied` issues. - -This problem can occur with OpenShift when a pod is run by a user with no permissions to use `sudo` or to access or modify resources on the file system. - -In most cases, this problem can be solved by rebuilding the base image so that it already has all of the dependencies for particular agents that an installer activates. - -=== Permission to files and directories failures - -Another possible issue can be with permissions to files and directories. For example, an installer may need to write to the https://github.com/eclipse/che-dockerfiles/blob/master/recipes/stack-base/centos/Dockerfile#L45-L57[user home directory]. - -[id="installer-registry-and-rest-api"] -== Installer registry and REST API - -Che installers are stored in the Installer Registry. They can be viewed and edited through the Installer Registry REST API: - -[cols=",,",options="header",] -|=== -|Path | HTTP Method | Description -|`/installer` |GET | Get installers -|`/installer/{id}/version` |GET | Get versions of installers by given id -|`/installer/orders` |GET | Get installers, ordered by their dependencies -|`/installer/` |POST | Add installer to the registry -|`/installer/{key}` |PUT | Update installer in the registry -|`/installer/{key}` |DELETE | Remove installer from the registry -|=== diff --git a/src/main/pages/che-6/workspace-admin/projects.adoc b/src/main/pages/che-6/workspace-admin/projects.adoc deleted file mode 100644 index d28ebcef5c..0000000000 --- a/src/main/pages/che-6/workspace-admin/projects.adoc +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "Projects" -keywords: workspace, runtime, project, projects -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/projects.html -redirect_from: projects.html -folder: che-6/workspace-admin ---- - -[id="creating-projects-in-workspaces"] -== Creating projects in workspaces - -Projects are always associated with a workspace and saved in a workspace configuration. - -The following is an example of the project YAML file: - -[source,json] ----- -"projects": [ - { - "description": "A basic example using Spring servlets. The app returns values entered into a submit form.", - "source": { - "location": "https://github.com/che-samples/web-java-spring.git", - "type": "git", - "parameters": {} - }, - "links": [], - "mixins": [], - "problems": [], - "name": "web-java-spring", - "type": "maven", - "path": "/web-java-spring", - "attributes": {} - } - ] ----- - -Once a project is saved into a workspace configuration, the IDE checks if the project exists on a file system. Use the `source.location` URL to import projects that do yet exist on the file system. This happens during the IDE initialization stage. - -You can add the following projects: - -* Git projects -* remotely hosted archives -* GitHub projects -* example projects provided by Eclipse Che - -Project import tools can be found on the *User Dashboard* when you are creating a new workspace or editing an existing workspace in the IDE. Project import tools can also be found in the *Workspace* menu. - -The following shows example projects: - -image::workspaces/projects.png[] - - -[id="defining-project-types"] -== Defining project types - -Plug-in developers can define their own project types. Since project types trigger certain behaviors within the IDE, the construction of the projects is important to understand. - -* A project type is defined as one primary type and zero or more mixin types. -+ --- -** A primary project type is one where the project is editable, buildable, and runnable. -** A mixin project type defines additional restrictions and behaviors of the project, but it cannot be a primary project type by itself. --- -+ -The collection of primary and mixin types for a single project defines the aggregate set of attributes that will be stored as meta data within the project. - -* Project types describe different aspects of a project, such as: -** the types of source files inside -** the structure of the explorer tree -** the way in which a command is executed -** associated workflows -** which plug-ins must be installed - -* A project defines a set of attributes. The attributes of a project can be mandatory or optional. Attributes that are optional can be dynamically set at runtime or during configuration. - -* Sub-projects may have different project types than their parents. Modules may physically exist within the tree structure of the parent. For example, subdirectories exist within the tree structure of the parent. Also, modules may physically exist outside the tree structure of the parent, such as when the parent is a soft link to the module project. - -[id="creating-a-sub-projects"] -== Creating a sub-project - -A sub-project is a portion of a project that can have sets of commands run against it where the sub-directory is treated as the root working directory. Sub-projects make it possible to organize a single repository into multiple, independently buildable, and runnable units. - -To create a module, right-click on a directory in the IDE explorer tree and select *Convert to Project*. You can then execute commands directly against this sub-project. - - -[id="navigating-the-project-tree"] -== Navigating the project tree - -You can step into or out of the project tree. When you step into a directory, that directory is set as the project tree root and the explorer refreshes the view. All commands are then executed against this directory root. diff --git a/src/main/pages/che-6/workspace-admin/recipes.adoc b/src/main/pages/che-6/workspace-admin/recipes.adoc deleted file mode 100644 index f45347ed43..0000000000 --- a/src/main/pages/che-6/workspace-admin/recipes.adoc +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: "Recipes" -keywords: workspace, runtime, recipe, docker, stack -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/recipes.html -redirect_from: recipes.html -folder: che-6/workspace-admin ---- - - -[id="supported-recipe-formats"] -== Supported Recipe Formats - -Depending on the infrastructure, Che supports the following default recipe formats: - -[cols=",,,,",options="header",] -|=== -|*Infrastructure* |*Docker-formatted container image* |*Dockerfile* |*Composefile* |*Kubernetes YAML* -|*Docker* |Supported |Supported |Supported |Not supported -|*OpenShift* |Supported |Not supported |Not supported |Supported -|=== - -[id="docker-formatted-container-image-requirements-and-limitations"] -== Docker-formatted container image requirements and limitations - -The Docker-formatted container image recipe pulls an image from a Docker registry or uses the local image. The recipe then runs the image and creates a pod that references this image in the container specification. The following are Docker-formatted container image requirements and limitations for a workspace machine: - -. Use a non-terminating `CMD` or `ENTRYPOINT`. For a custom image, use, for example, `tail -f /dev/null` as one of the main processes. -. For OpenShift only: -+ -** Do not use any processes and operations with `sudo` in `CMD`. See link:openshift-config.html#enable-ssh-and-sudo[Enable SSH and `sudo`] for more information. -** Use https://github.com/eclipse/che-dockerfiles/tree/master/recipes/stack-base[Che base stacks]. You can also build your own image, but inherit from one of the base stacks. - -[id="dockerfile-definition-and-limitations"] -== Dockerfile definition and limitations - -A Dockerfile is a set of instructions that Docker performs to build an image. After you provide a Dockerfile for your workspace machine, Che initiates a Docker build and runs the resulting image. The following are the limitations: - -. The `COPY` and `ADD` instructions fail because there is no context in `docker build`. -. To avoid long build times with long Dockerfiles, build your image locally, push it to DockerHub, and then use the pushed image as a Docker-formatted container image recipe type. The start timeout for a workspace is five minutes. - -[id="running-multi-container-workspaces-using-compose-files"] -== Running multi-container workspaces using Compose files - -You can run multi-container workspaces using Compose files on Docker. The following syntax is not supported: `Local "build.context" and "build.dockerfile"`. - -Because Che workspaces can be distributed, you cannot have host-local build and Dockerfile contexts. You can remotely host these aspects in a Git repository. Che sources the Compose file from the remote system and uses it as the build context. - -You can run into a failure when the Dockerfile or build context requires you to `ADD` or `COPY` other files into the image. The local Che workspace generator cannot access these remote files. - -[id="accessing-remote-files"] -=== Accessing remote files - -To ensure the local Che workspace generator can access remote files, take these steps: - -. Pre-package the build context or Dockerfile into an image. - -. Push that image into a registry. - -. Reference the pre-built image in your Compose file. - -The following is an example of a remote context that works: - -[source,yaml] ----- -build: - ## remote context will work - context: https://github.com/eclipse/che-dockerfiles.git#master:recipes/stack-base/ubuntu - - ## local context will not work - context: ./my/local/filesystem ----- - -[id="using-private-repositories"] -=== Using private repositories - -To use private repositories in a remote build context: - -. Set up the SSH keys on your host machine. - -. Add the remote repository hostname or IP to the list of known hosts. - -The following is an example of a YAML file using a private repository: - -[source,yaml] ----- -## The following will use master branch and build in recipes/stack-base/ubuntu folder -build: - context: git@github.com:eclipse/che-dockerfiles.git#master:recipes/stack-base/ubuntu ----- - -[id="configuring-privileged-access"] -=== Configuring privileged access - -The `privileged` Compose option does not support securing the underlying host system. - -To configure the Che server to give all containers privileged access, set the `CHE_PROPERTY_machine_docker_privilege__mode` variable to `true`. - -[IMPORTANT] -==== -Setting the `CHE_PROPERTY_machine_docker_privilege_mode` variable to `true` makes the host system vulnerable and gives all containers access to the host system. -==== - -=== Special considerations when using Compose files - -*Build images* - -When a Compose file includes both build instructions and a build image, the build instructions override the build image, if it exists. - -*Container names* - -The `container_name` is skipped during execution. Instead, Che generates container names based on its own internal patterns. Avoid naming conflicts. Many developers can be running the same Compose file on the same Che workspace node at the same time. - -The following is an example of a YAML file using a container name: - -[source,yaml] ----- -container_name: my_container ----- - -*Volumes* - -To define volumes for workspace machines, see link:volumes.html[Volumes]. Volume instructions in a Compose file are not supported. - -*Networks* - -Che does not support Compose networks. The use of aliases is supported by the `links` command. - -The following is an example of a YAML file using networks: - -[source,yaml] ----- -## Not supported -networks: - internal: - aliases: ['my.alias’] -## Not supported -networks: - internal: - driver: bridge ----- - -*Hostname* - -Hostname is not supported. The machine’s name is used for the hostname. You can use `links` aliases syntax to add additional hostnames to a machine. - -*Binding ports* - -Binding ports to the host system is not supported to ensure that containers do not use already assigned host ports. Users can work around this limitation by adding link:servers.html[servers] to machines. - -*Environment file* - -The `env_file` Compose option is not supported. Environment variables can be manually entered in the Compose file or machine configuration. See link:env-variables.html[Environment variables] for more information. - -[id="kubernetes-yaml-limitations-and-restrictions"] -== Kubernetes YAML limitations and restrictions - -When a workspace is starting, Che creates various Kubernetes resources to support the IDE and development tools. Workspaces primarily consist of a https://kubernetes.io/docs/concepts/workloads/controllers/deployment/[Deployment] which runs a https://kubernetes.io/docs/concepts/workloads/pods/pod/[Kubernetes pod]. The following are limitatons and restrictions: - -. Che allows users specify Pods, Deployments, ConfigMaps, and Services in recipes - - If a Pod is specified, it will be wrapped in a simple Deployment when running the workspace -. Other object kinds will be ignored (PVC and route) or a workspace fails to start with an exception from Kubernetes. -. Che performs some minimal validation of Kubernetes YAML, but invalid yaml in a recipe can cause workspaces to fail to run (e.g. referring to a non-existent configmap) -. You cannot use volumes in the container and pod definition. See link:volumes.html[Volumes] for information about persisting and sharing data between pods. - -The following is an example of a custom recipe with two containers, a simple config map, one deployment, and a service that is bound to port 8081: - -[source,yaml] ----- -kind: List -items: - - - apiVersion: apps/v1 - kind: Deployment - metadata: - name: my-deployment - spec: - replicas: 1 - selector: - matchLabels: - my-workspace-pod: dev - template: - metadata: - name: dev-pod - labels: - my-workspace-pod: dev - spec: - containers: - - - image: eclipse/ubuntu_jdk8:latest - name: main - ports: - - - containerPort: 8081 - protocol: TCP - env: - - - name: MY_ENV_VAR - valueFrom: - configMapKeyRef: - name: my-configmap - key: my-key - - - image: eclipse/ubuntu_jdk8:latest - name: main1 - - - apiVersion: v1 - kind: ConfigMap - metadata: - name: my-configmap - data: - my-key: my-value - - - kind: Service - apiVersion: v1 - metadata: - name: my-service - spec: - selector: - name: app - ports: - - protocol: TCP - port: 8081 - targetPort: 8081 ----- - -As a bare minimum, a Kubernetes YAML recipe must contain at least one Pod or Deployment, in which the main dev machine is run. - -You can also specify multiple containers within the workspace pod. Che treats those containers as workspace machines. These containers can have machine names defined in annotations. `PodName/Container Name` is the default naming pattern for a machine. - -The following is an example of using annotations: - -[source,yaml] ----- -kind: List -items: -- - apiVersion: v1 - kind: Pod - metadata: - name: any123123 - annotations: - org.eclipse.che.container.main.machine_name: myMachine - org.eclipse.che.container.main1.machine_name: myMachine1 - spec: - containers: - - - image: rhche/spring-boot:latest - name: main - ports: - - - containerPort: 8080 - protocol: TCP - resources: {} - - - - image: rhche/spring-boot:latest - name: main1 - ports: - - - containerPort: 8080 - protocol: TCP - resources: {} ----- diff --git a/src/main/pages/che-6/workspace-admin/secure-servers.adoc b/src/main/pages/che-6/workspace-admin/secure-servers.adoc deleted file mode 100644 index e031eec165..0000000000 --- a/src/main/pages/che-6/workspace-admin/secure-servers.adoc +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Secure Servers" -keywords: workspace, runtime, recipe, kubernetes, openshift, stack, servers, server, secure server -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/secure-servers.html -redirect_from: secure-servers.html -folder: che-6/workspace-admin ---- - -Now that you have made yourself familiar with link:servers.html#secure-server[secure servers] concept, let’s take a closer look at enabling this functionality and implementation details. - -[id="how-to-enable-secure-servers-functionality"] -== How to enable secure servers functionality? - -This functionality is in *beta* phase now and it is disabled by default. It is needed to set `pass:[CHE_SERVER_SECURE__EXPOSER=jwtproxy]` environment variable of Che Server to enable secure servers with JwtProxy as proxy backend. Note that it is supported by Kubernetes and OpenShift infrastructures but not Docker. - -[id="how-to-access-to-secure-server"] -== How to access to secure server - -To request secure server it is needed to provide machine token. Machine token may be fetched from workspace runtime. - -There are three possible ways to specify token in the request to secure server, ways are ordered in priority of search: - -* specify token in `access_token` cookie. This option can be configured and is disabled by default. -* specify token in `Authorization` request header. Note that `Bearer` prefix should be specified as token type; -* specify it in `token` query parameter. This way is not recommended to be used since token will be present in URL. But there can be limited cases when it’s not possible to use `Authorization` header or cookies. An example of such exceptional case can be: OAuth authentification initialization. - -[id="cookies-authentication"] -== Cookies Authentication - -Authentication with cookies increases the probability of CSRF attack and because of that it is disabled by default for servers. Authentication with cookies may be enabled via `cookiesAuthEnabled` server configuration attribute. CSRF is not actual if server doesn’t have any methods that processes modifying GET, POST requests and accepts html form supported content types. Otherwise server should implements additional protection from CSRF attack by itself if cookies authentication is needed. - -Authentication with cookies is the most useful for a server which is a web application. It solves to issues for it: - -* a client initialization issues - no needs to specify token explicitly after storing an token in cookies otherwise token must be specified in URL as query parameter which is not good from security perspective; -* a client doesn’t need to specify token explicitly during calls to its server. - -An example of such web application is Theia IDE that loads main page from secure server with token specified in cookie and the same token is used for further communication between Theia Client Side and Server Side. - -[id="jwtproxy"] -== JwtProxy - -Now https://github.com/eclipse/che-jwtproxy[JwtProxy] is the only supported backend for secure servers. It proxies all requests to secure servers an verify incoming requests. - -To make cookies authentication easier JwtProxy has authentication endpoint that may be used for automatically putting machine token into cookies. The following diagram shows how it works - -image::diagrams/servers-cookies-auth.svg[] diff --git a/src/main/pages/che-6/workspace-admin/servers.adoc b/src/main/pages/che-6/workspace-admin/servers.adoc deleted file mode 100644 index ae0f7f3814..0000000000 --- a/src/main/pages/che-6/workspace-admin/servers.adoc +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Servers" -keywords: workspace, runtime, recipe, docker, stack, servers, server, port, preview, preview url -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/servers.html -redirect_from: servers.html -folder: che-6/workspace-admin ---- - - -[id="what-are-servers"] -== What are servers? - -A server defines the protocol port of a process that runs in a machine. It has a name, path, and attributes. The path defines the base path of the service that is used by the server. Attributes are optional and can be used to tune the server or for identification. You can add a server when you need to access a process in your workspace machine. - -To add a server, use the *User Dashboard* or edit the workspace machine configuration YAML file. - -The following is an example of the YAML file: - -[source,json] ----- -"node": { - "port": "3000", - "protocol": "http", - "path": "/", - "attributes": {} -} ----- - -The following is an example of the *User Dashboard*: - -image::workspaces/servers_dashboard.png[] - -[NOTE] -==== -If your workspace is running, saving a new server restarts the workspace. -==== - -[id="preview-urls"] -== Preview URLs - -Adding the server with port 3000 does not mean you can use this port to access a server. Each server is assigned a URL when a workspace is running. - -* On Docker, port 3000 is published to a random port from the ephemeral port range from 32768 to 65535. The server URLs change every time you start a workspace. -* On OpenShift, a route bound to a service is created. Routes are persistent URLs. - -[id="getting-preview-urls"] -== Getting preview URLs - -In this example, you added a server with port 3000 and started a workspace. The following are ways to get the server's preview URL: - -* Use a link:commands-ide-macro.html[macro] command. -* In the IDE, Click the `+` icon in the bottom panel under the editor. - -image::workspaces/servers.png[] -* In the *User Dashboard*, click *Workspaces > YourWorkspace > Servers*. - -You can also see internal server URLs. Internal servers launch when the workspace container or pod is available. - -[id="exposing-internal-servers"] -== Exposing internal servers - -To access a port internally within a workspace, expose it internally, but do not make it publicly accessible. For example, a database server is exposed only for the web application and because of security concerns, it should not be accessible publicly. The database server is exposed as internal. - -To expose a server as internal, add the corresponding attribute into the server configuration YAML file: - -[source,json] ----- -"db": { - "port": "3200", - "protocol": "tcp", - "attributes": { - "internal": "true" - } -} ----- - -The application is able to fetch the database URL from the workspace runtime and access the database. The database URL is not accessible publicly from the browser. - -[id="exposing-secure-servers"] -== Exposing secure servers - -Secure servers are exposed publicly but access is restricted only for users who have permissions to the workspace. The authentication proxy is set up as the exposed server and the machine token is required to request it. - -To expose a server as secure, add the corresponding attributes into the server configuration YAML file: - -[source,json] ----- -"tooling": { - "port": "4921", - "protocol": "http", - "attributes": { - "secure": "true", - "unsecuredPaths": "/liveness", - "cookiesAuthEnabled": "true" - } -} ----- - -The following describes the attributes: - -`secure`:: Indicates whether the server is exposed as secure. The default value is `false`. -`unsecuredPaths`:: Configures the secure servers. It contains a comma-separated list of URLs that are considered non-secure on the given server and can be accessible without a token. It may be needed when the server provides any public APIs. The API endpoint for health checks is an example. -`cookiesAuthEnabled`:: Indicates whether cookies should be searched for a token. By default, it is disabled. You can enable this attribute if you are sure that servers cannot be attacked by Cross-Site Request Forgery (CSRF) or have special protection from it. - -[NOTE] -==== -This is in the beta phase and disabled by default. See link:secure-servers.html#how-to-make-secure-servers-working[Secure servers] for information on how to enable secure servers. -==== diff --git a/src/main/pages/che-6/workspace-admin/stacks.adoc b/src/main/pages/che-6/workspace-admin/stacks.adoc deleted file mode 100644 index 14ef4bf218..0000000000 --- a/src/main/pages/che-6/workspace-admin/stacks.adoc +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Stacks" -keywords: workspace, runtime, recipe, docker, stack -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/stacks.html -redirect_from: stacks.html -folder: che-6/workspace-admin ---- - - - -[id="stack-overview"] -== Stack overview - -A stack is a link:workspace-data-model.html[workspace configuration] template. Stacks are used to create workspaces in the *User Dashboard*. The stack includes meta-information such as scope, tags, components, description, name, and identification. You can filter stacks by machine type and scope. The type is either single machine or multi machine. You can also search for a stack by keyword. Stacks are displayed in the *User Dashboard* on the *Create a workspace* page. - -See the link:creating-starting-workspaces.html[Creating and starting workspaces user guide] for more information. - -[id="importing-community-supported-stacks-and-applications"] -== Importing community supported stacks and applications - -Che includes some stacks and sample applications that are pre-configured and tested. Stacks that are contributed by the Che community are not tested. Community stacks are located in the https://github.com/che-samples/community-stacks[community stacks GitHub repository]. - -Each directory has `${technology}-stack.json` and `${technology}-samples.json`. - -To import a stack, follow these steps: - -. Copy the content of the JSON files. -. Go to `${CHE_HOST}/swagger/#!/stack/createStack`. -. Paste the content of the JSON file to the *body* field. -. Click the *Try it out* button. - -You can choose a different name or ID when there is a conflict with the stack ID or name. - -For a multi-user setup, you can make your stack available for a particular user or all users in the system. See link:#stack-sharing-and-system-stacks[stack sharing] for more information. - -To import sample applications, move `*-stacks.json` files to: - -* `${LOCAL_STORAGE}/instance/data/templates` for Docker infrastructure. -* `${mount-path-of-che-data-volume}/templates` for OpenShift and Kubernetes infrastructure. You need administrator privileges to get the host path and to access the host directory. Also, the new JSON files have the same permissions as the original `samples.json` file. - -You can find Dockerfiles for all stacks in the https://github.com/eclipse/che-dockerfiles[Che Dockerfiles repository]. - -[id="sharing-stacks-and-system-stacks"] -== Sharing stacks and system stacks - -You can share stacks with selected users or with all users in the system if you have system privileges. You share stacks by making REST calls. - -To share stacks with users: - -* Log in as administrator -* Go to `/swagger/#!/stack/searchStacks` to get a list of all stacks. You may filter search by tags. -* Find your stack by name and get its ID. -* The next API to use is: `/swagger/#!/permissions` -* Find the below POST method: - -image::workspaces/stack_permissions.png[] - -* Use the following JSON file and replace `${STACK_ID}` with an actual ID: - -[source,json] ----- -{ -"userId": "*", - "domainId": "stack", - "instanceId": "${STACK_ID}", - "actions": [ - "read", - "search" - ] -} ----- - -If you get 204, all the users in the system see the stack. To share a stack with a particular user, get the user's ID and use it instead of `*` in the JSON file. - -The administrator can remove pre-configured stacks and replace them with custom stacks. The administrator can also remove permissions from stacks. You can create stacks either in the user dashboard or by using any REST client. You can use Swagger (`$CHE_HOST:$CHE_PORT/swagger`) to bundle with Che. - -[id="loading-stacks"] -== Loading stacks - -Stacks are loaded from a JSON file that is packaged into resources of a special component that is deployed with the workspace master. This JSON file is not exposed to users. You can perform stack management using REST APIs in the *User Dashboard*. - -When a user first starts Che, stacks are loaded from a JSON file only when the database is initialized. This is the default policy that can be changed. To keep getting stack updates with the new Che stacks, set `CHE_PREDEFINED_STACKS_RELOADONSTART=true` in `che.env`. When set to `true`, `stacks.json` is used to update Che database each time the Che server starts. This means Che gets all the stacks in `stacks.json` and uploads the stacks to a database. This allows you to keep existing custom stacks and get stack updates from new Che releases. New and edited stacks that have fixes in the stack definition are merged in with the other stacks. - -Name conflicts are possible. A name conflict happens when a new Che version provides a stack with a name that already exists in the database. - diff --git a/src/main/pages/che-6/workspace-admin/volumes.adoc b/src/main/pages/che-6/workspace-admin/volumes.adoc deleted file mode 100644 index f611854002..0000000000 --- a/src/main/pages/che-6/workspace-admin/volumes.adoc +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Volumes" -keywords: workspace, runtime, recipe, docker, stack, volume, volumes -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/volumes.html -redirect_from: volumes.html -folder: che-6/workspace-admin ---- - - -[id="default-volumes_for_workspace_containers"] -== Default volumes for workspace containers - -By default, workspace containers start with a default volume and have a minimum of one PVC that is located in the `/projects` directory. - -Workspace projects are physically located in the `/projects` directory. When a workspace stops, the machines are destroyed, but the volumes persist. - -[id="Adding-volumes"] -== Adding volumes - -In order for your data to persist for a local Maven repository, the `node_modules/` directory, Ruby gems, or the `authorized_keys` file for SSH connections, your workspace will need additional volumes. Each machine can add as many volumes as the underlying infrastructure can support. OpenShift may impose a limit on the number of volumes. - -You can add volumes either by using the *User Dashboard* or by updating the machine configuration. The following is an example of the configuration file: - -[source,json] ----- -"volumes": { - "myvolume": { - "path": "/absolute/path/in/workspace" - } -} ----- - - -To avoid failures when updating the workspace configuration using REST APIs: - -* Use an absolute path. -* The name and path cannot contain special characters, including dashes (`-`) or underscores (`_`). - -[NOTE] -==== -To allow machines to share the same volume, create a volume for each machine with an identical name. -==== - -[id="configuring-workspaces"] -== Configuring workspaces - -To configure workspaces on the OpenShift and Kubernetes infrastructure as ephemeral, set the `persistVolumes` attribute to `false` in the workspace configuration. - -The following is an example of the configuration file: - -[source,json] ----- -"attributes": { - "persistVolumes": "false" -} ----- - -In this case, regardless of the link:openshift-admin-guide.html#che-workspaces-storage[PVC strategy], all volumes would be created as https://kubernetes.io/docs/concepts/storage/volumes/#emptydir[`emptyDir`] for the given workspace. When a workspace pod is removed for any reason, the data in the `emptyDir` volume is deleted forever. diff --git a/src/main/pages/che-6/workspace-admin/what-are-workspaces.adoc b/src/main/pages/che-6/workspace-admin/what-are-workspaces.adoc deleted file mode 100644 index 9283259818..0000000000 --- a/src/main/pages/che-6/workspace-admin/what-are-workspaces.adoc +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Administering workspaces" -keywords: workspace, runtime, recipe, docker, yaml, Dockerfile, docker, kubernetes, container, pod -tags: [workspace, runtime, docker, kubernetes] -sidebar: che_6_docs -permalink: che-6/what-are-workspaces.html -redirect_from: what-are-workspaces.html -folder: che-6/workspace-admin ---- - -IMPORTANT: Che 6 workspace configuration format is no longer supported in the latest Che 7 release. Please, follow the -link:{site-baseurl}che-7/converting-a-che-6-workspace-to-a-che-7-devfile["Converting a Che 6 workspace to a Che 7 devfile"] documentation in order to update the definition of the workspace and benefit from the latest capabilities. - -[id="workspace"] -== Workspace - -A workspace is usually termed as a local directory with projects and meta-information that the integrated development environment (IDE) uses to configure projects. In Eclipse Che, a workspace is the developer environment. The developer environment contains Docker containers, Kubernetes pods, and a virtual machine or localhost. Environment variables and storage volumes are part of the workspace. The developer environment also contains projects, project commands, and resource allocation attributes. - -[id="what-are-workspaces-environment"] -== Environment - -The workspace runtime environment is a set of machines where each machine is defined by a recipe. The environment is healthy when all the machines successfully start and the installers execute jobs. The environment is defined by a recipe that can have different types. The environment and infrastructure validate a recipe. - -[id="machine"] -== Machine - -The runtime environment has a minimum of one machine that can be a Docker-formatted container or a Kubernetes pod. You can create multi-machine environments with as many machines as your project infrastructure requires. Each machine has a configuration and start policy. Machine crashes and start failures are signs of an unhealthy environment. Machines communicate by using the internal network, `service:port`. - -[id="recipe"] -== Recipe - -A workspace environment is defined by a recipe. The recipe can be one of the following: - -* single container image -* Dockerfile -* Docker Compose file -* Kubernetes list of objects with multiple pods and services - -[id="bootstrapper"] -== Bootstrapper - -The bootstrapper starts the installer script after the first process is executed in the machine following the `CMD` or `ENTRYPOINT`. The role of the bootstrapper is to start the installer scripts with a set of parameters and a configuration file. The bootstrapper is a small binary compiled from Go code. - -[id="installer"] -== Installer - -The purpose of the installer is to install software and services, start servers, and activate agents. The workspace agent, executive agent, and terminal servers are important to the IDE and workspace. The language servers, SSH installer, and other servers bring new functionality to a workspace. The bootstrapper executes installer scripts that prepare the environment and checks for dependencies. See an https://github.com/eclipse/che/blob/che6/agents/ls-csharp/src/main/resources/installers/1.0.1/org.eclipse.che.ls.csharp.script.sh[example of an installer script] that prepares the environment and installs the C# language server. - -[id="volume"] -== Volume - -A volume is a fixed amount of storage that is used to persist workspace data. Workspace projects are automatically mounted into a host file system by default. A user can define extra volumes for each machine in the environment. Docker volumes, Kubernetes persistent volumes (PVs), and persistent volumes claims (PVCs) are examples of volumes. - -[id="what-are-workspaces-environment-variables"] -== Environment variables - -The environment variables are propagated into each individual machine. Depending on the infrastructure, environment variables are propagated to Docker containers or Kubernetes pods. - -[id="what-are-workspaces-what-is-next"] -== What is next? - -* link:creating-starting-workspaces.html[Create and start your first workspace]. -* Learn how to define link:volumes.html[volumes] and link:env-variables.html[environment variables]. diff --git a/src/main/pages/che-6/workspace-admin/workspace-data-model.adoc b/src/main/pages/che-6/workspace-admin/workspace-data-model.adoc deleted file mode 100644 index c76bf89a12..0000000000 --- a/src/main/pages/che-6/workspace-admin/workspace-data-model.adoc +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "Workspace Data Model" -keywords: workspace, runtime, recipe, docker, yaml, Dockerfile, docker, kubernetes, container, pod -tags: [workspace, runtime, docker, kubernetes, dev-docs] -sidebar: che_6_docs -permalink: che-6/workspace-data-model.html -redirect_from: workspace-data-model.html -folder: che-6/workspace-admin ---- - - -The following table lists the data types and their description. - -[width="100%",cols="50%,50%",options="header",] -|=== -|Data Types |Description -|environments: Map -|Workspace environment variables. A workspace can have multiple environment variables. - -|defaultEnv: STRING -|A workspace must have a default environment. - -|projects: [] -|Projects associated with a workspace. - -|commands: [] -|Commands associated with a workspace. - -|name: STRING -|Workspace name that has to be unique in a namespace. - -|links: [] -|- -|=== - -[id="workspace-data-modelenvironment"] -== Environment recipes - -image::workspaces/ws_data_model.png[] - -For link:recipes.html[recipe] types of `dockerfile`, `compose`, or `openshift`, content, not location, is specified. - -[source,json] ----- -"recipe": { - "type": "compose", - "content": "services:\n db:\n image: eclipse/mysql\n environment:\n MYSQL_ROOT_PASSWORD: password\n MYSQL_DATABASE: petclinic\n MYSQL_USER: petclinic\n MYSQL_PASSWORD: password\n mem_limit: 1073741824\n dev-machine:\n image: eclipse/ubuntu_jdk8\n mem_limit: 2147483648\n depends_on:\n - db", - "contentType": "application/x-yaml" -} ----- - -[id="workspace-data-model-projects"] -== Projects - -image::workspaces/ws_projects.png[] - -The project object structure has the `source.location` and `source.type` parameters. There are two importer types: `git` and `zip`. New location types can be provided by custom plugins, such as `svn`. - -Incorrectly configured projects or projects missing sources are marked with error codes and messages explaining the error. In the example above, the project does not have errors and mixins. - -A mixin adds additional behaviors to the project, the IDE panels, and menus. Mixins are reusable across any project type. To define the mixins to add to a project, specify an array of strings, with each string containing the identifier for the mixin. - -[width="100%",cols="50%,50%",options="header",] -|=== -|Mixin ID |Description -|`git` |Initiates the project with a Git repository. Adds Git-menu functionality to the IDE. To add a mixin to the project, create a new project and then initialize a Git repository. -|`pullrequest` |Enables pull-request workflow where a server handles the local and remote branching, forking, and pull-request issuance. Pull requests generated from within the server have another Factory placed into the comments of pull requests that a PR reviewer can consume. Adds contribution panel to the IDE. Set this mixin to use attribute values for `project.attributes.local_branch` and `project.attributes.contribute_to_branch`. -|=== - -The `pullrequest` mixin requires additional configuration from the `attributes` object of the project. - -The `project` object can include `source.parameters`, which is a map that can contain additional parameters. Example: related to project importer. - -[width="100%",cols="50%,50%",options="header",] -|=== -|Parameter name |Description -|`skipFirstLevel` |Used for projects with type `zip`. When value is 'true', the first directory inside ZIP will be omitted. -|=== - -[id="commands"] -== Commands - -Commands can be both tied to a workspace and an individual project. In the example below, a command is saved to workspace configuration. - -image::workspaces/ws_commands.png[] - -The followling image shows ways to save commands in the project configuration. - -image::workspaces/project_commands.png[] - -[id="runtime"] -== Runtime - -A runtime object is created when a workspace is in a running state. Runtime returns server URLs, internal or external, depending on the server configuration. Interested clients, like the *User Dashboard* and the IDE, use these URLs. - -image::workspaces/runtime.png[] diff --git a/src/main/pages/che-6/workspace-admin/workspace-rest-api.adoc b/src/main/pages/che-6/workspace-admin/workspace-rest-api.adoc deleted file mode 100644 index 0e5acdc830..0000000000 --- a/src/main/pages/che-6/workspace-admin/workspace-rest-api.adoc +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Workspace REST API" -keywords: workspace, runtime, recipe, docker, yaml, Dockerfile, docker, kubernetes, container, pod -tags: [workspace, runtime, docker, kubernetes, dev-docs] -sidebar: che_6_docs -permalink: che-6/workspaces-rest-api.html -redirect_from: workspaces-rest-api.html -folder: che-6/workspace-admin ---- - diff --git a/src/main/pages/che-6/workspace-admin/workspaces-troubleshooting.adoc b/src/main/pages/che-6/workspace-admin/workspaces-troubleshooting.adoc deleted file mode 100644 index 79d4f78efd..0000000000 --- a/src/main/pages/che-6/workspace-admin/workspaces-troubleshooting.adoc +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Troubleshooting failures in starting the workspace" -keywords: workspace, runtime, recipe, docker, yaml, Dockerfile, docker, kubernetes, container, pod -tags: [workspace, runtime, docker, kubernetes, troubleshooting] -sidebar: che_6_docs -permalink: che-6/workspaces-troubleshooting.html -redirect_from: workspaces-troubleshooting.html -folder: che-6/workspace-admin ---- - - -Failures to start a workspace may be caused by the following factors: - -* Incorrect environment recipe -* Restrictive network settings - -[id="bad-recipes"] -== Incorrect environment recipes - -When a workspace is starting, an environment link:recipes.html[recipe] is sent to Docker or to the OpenShift API. The Che server then listens to events provided by the given infrastructure. The Che server expects a running Docker container or an OpenShift pod. The server fails to start an environment and consequently the starting of the workspace fails if the infrastructure is unable to create and start a container or a pod from the provided recipe. - -A recipe can be incorrect due to the following reasons: - -* The Docker build fails with the provided `Dockerfile`. This can be because of a broken `Dockerfile` or because of Che. If the Docker build in Che link:recipes.html#dockerfile[does not support context], consider editing the Docker recipe locally to ensure that it is a valid `Dockerfile`. Add or copy resources into an image locally on your machine, push the image to a registry, such as DockerHub, and use the resulting images in the recipe. - -* Che does not support certain link:recipes.html#composefile[Docker Compose syntax]. Ensure that the `Composefile` is supported by Che. - -* Installing packages in your `Dockerfile` instructions can take time. This may be influenced by network settings. - -=== Viewing logs from a failed workspace start - -No link:installers.html[installer] logs are shown when a workspace fails to start because its container or pod are not launched. In most cases, only logs from infrastructure and image pull and build are shown. Analyse these logs to find the problem. The Che server also produces logs that are helpful in debugging the problem. - -[id="network-conditions"] -== Restrictive network settings - -The Che server and agents, which run in a workspace container or pod, and the user’s browser communicate with each other. Firewall, filtered ports, and other network restrictions may cause trouble when starting a workspace. - -A workspace is considered to be in a `RUNNING` state after the Che server verifies that the workspace agent is up. The workspace agent also tries to reach the Che server. All this happens in separate containers or pods, and the user’s browser is not yet involved. The `workspace started by user $userName` message in the Che server logs indicates the following: - -* The workspace container or pod is up. -* The workspace agent has successfully started. -* The Che server can reach it. - -=== Troubleshooting network setting when workspace agent cannot be reached - -An error message saying that the IDE cannot be initialized indicates that the client (browser) cannot reach the workspace agent. This is caused by the Che server using an internal IP address to reach the workspace agent, while you are accessing the workspace from a machine that is located on a different network. To confirm this, open the browser developer console and check failed requests. The failed requests are to `project` and `project-type` API. - -To access a workspace from a different network than the one on which the Che server is running, enable access to the ephemeral port range on the Che server network. - -[id="bootstrapping-failures"] -== Failure in bootstrapping - -When a workspace starts, the Che server creates and starts a container or a pod or a set of containers and pods as per the environment recipe. After the container or pod is running, a bootstrapping process begins - the bootstrapper binary is downloaded and launched. If the server logs show bootstrapping failures, or you do not see any output in the *Machine* tab of the *Workspaces* view, the reason is that bootstrapper is not downloaded. The following are possible the reasons for the bootstrapper download failure: - -* Network conditions (for example, firewall restrictions). - -* Incorrect bootstrapper binary URL that the Che server uses (often reproduced when deploying to OpenShift and missing necessary environment variables). - -To work around the problem, download the bootstrapper binary manually. On OpenShift, access the pod on the command line (shell or the terminal in the web console) and run the following commands: - ----- -$ cd /tmp/bootstrapper -$ ls -la <1> -$ curl ${CHE_URL}/agent-binaries/linux_amd64/bootstrapper/bootstrapper ----- -<1> to check for the existence of the bootstrapper binary - -To prevent the `curl` command from failing, unblock port `80` on your network. On OpenShift with `https` routes, unblock port `443`. diff --git a/src/main/pages/che-7/overview/assembly_introduction-to-eclipse-che.adoc b/src/main/pages/che-7/overview/assembly_introduction-to-eclipse-che.adoc index d7c544fc4f..f36f46e810 100644 --- a/src/main/pages/che-7/overview/assembly_introduction-to-eclipse-che.adoc +++ b/src/main/pages/che-7/overview/assembly_introduction-to-eclipse-che.adoc @@ -4,7 +4,9 @@ keywords: tags: [Che] sidebar: che_7_docs permalink: che-7/introduction-to-eclipse-che/ -redirect_from: che-7/index.html +redirect_from: + - che-7/index.html + - index.html folder: che-7/overview summary: --- From 66694b7a7620641a321092b742ad0847a11dc64d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Thu, 24 Oct 2019 18:15:28 +0200 Subject: [PATCH 2/2] Fix sidebar issues. --- src/main/_data/sidebars/rn_sidebar.yml | 13 ------------- src/main/css/customstyles.css | 2 +- src/main/js/customscripts.js | 2 +- 3 files changed, 2 insertions(+), 15 deletions(-) delete mode 100644 src/main/_data/sidebars/rn_sidebar.yml diff --git a/src/main/_data/sidebars/rn_sidebar.yml b/src/main/_data/sidebars/rn_sidebar.yml deleted file mode 100644 index 92dd70aa24..0000000000 --- a/src/main/_data/sidebars/rn_sidebar.yml +++ /dev/null @@ -1,13 +0,0 @@ -# This is your sidebar TOC. The sidebar code loops through sections here and provides the appropriate formatting. - -entries: -- title: - levels: one - folders: - - - title: Release Notes - output: web - folderitems: - - title: 6.0.0 - url: /release-6.0.0.html - output: web diff --git a/src/main/css/customstyles.css b/src/main/css/customstyles.css index 621494577b..3dd3862058 100644 --- a/src/main/css/customstyles.css +++ b/src/main/css/customstyles.css @@ -416,7 +416,7 @@ a.accordion-toggle, a.accordion-collapsed { .nav { /* padding: 4px;*/ padding:0px; - margin: 0px; + margin: 0 0 15px 0; } .nav > li { diff --git a/src/main/js/customscripts.js b/src/main/js/customscripts.js index 27701a35d6..0574ca0fa8 100644 --- a/src/main/js/customscripts.js +++ b/src/main/js/customscripts.js @@ -7,7 +7,7 @@ $( document ).ready(function() { // position as your scroll. if you have a lot of nav items, this height may not work for you. var h = $(window).height(); //console.log (h); - if (h > 800) { + if (h > 1500) { $( "#mysidebar" ).attr("class", "nav affix"); } // activate tooltips. although this is a bootstrap js function, it must be activated this way in your theme.