eclipse-che · l0rd · Jun 18, 2021 · Aug 30, 2021
diff --git a/.gitignore b/.gitignore
@@ -37,3 +37,6 @@ linkchecker-out.html
 .local
 .yarnrc
 yarn.lock
+
+.DS_Store
+
diff --git a/modules/administration-guide/images/architecture/che-architecture-with-dw.png b/modules/administration-guide/images/architecture/che-architecture-with-dw.png
diff --git a/...administration-guide/images/architecture/workspaces-server-and-devworkspace.png b/...administration-guide/images/architecture/workspaces-server-and-devworkspace.png
diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc
@@ -1,8 +1,11 @@
 .Administration Guide
 
 * xref:che-architecture-overview.adoc[]
-** xref:che-workspace-controller.adoc[]
-** xref:che-workspaces-architecture.adoc[]
+** xref:che-architecture-overview-with-che-server.adoc[]
+*** xref:che-workspace-controller-with-che-server.adoc[]
+*** xref:che-workspaces-architecture-with-che-server.adoc[]
+** xref:che-architecture-overview-with-dw.adoc[]
+*** xref:che-workspace-controller-with-dw.adoc[]
 
 * xref:calculating-che-resource-requirements.adoc[]
 

diff --git a/modules/administration-guide/pages/che-architecture-overview-with-che-server.adoc b/modules/administration-guide/pages/che-architecture-overview-with-che-server.adoc
@@ -0,0 +1,7 @@
+[id="che-architecture-overview-with-che-server"]
+// = Che architecture with Che server as workspace engine
+:navtitle: Che server based
+:keywords: administration-guide, che-architecture-overview
+:page-aliases: .:che-architecture-overview-with-che-server, .:high-level-che-architecture-with-che-server, overview:high-level-che-architecture-with-che-server, administration-guide:high-level-che-architecture-with-che-server
+
+include::partial$con_che-architecture-overview-with-che-server.adoc[]
diff --git a/modules/administration-guide/pages/che-architecture-overview-with-dw.adoc b/modules/administration-guide/pages/che-architecture-overview-with-dw.adoc
@@ -0,0 +1,7 @@
+[id="che-architecture-overview-with-dw"]
+// = Che architecture with DevWorkspace
+:navtitle: DevWorkspace based
+:keywords: administration-guide, che-architecture-overview
+:page-aliases: .:che-architecture-overview-with-dw, .:high-level-che-architecture-with-dw, overview:high-level-che-architecture-with-dw, administration-guide:high-level-che-architecture-with-dw
+
+include::partial$con_che-architecture-overview-with-dw.adoc[]
diff --git a/modules/administration-guide/pages/che-workspace-controller-with-che-server.adoc b/modules/administration-guide/pages/che-workspace-controller-with-che-server.adoc
@@ -0,0 +1,7 @@
+[id="che-workspace-controller-with-che-server"]
+// = Che server side components
+:navtitle: Server side components
+:keywords: administration-guide, che-workspace-controller
+:page-aliases: .:che-workspace-controller-with-che-server
+
+include::partial$assembly_understanding-che-workspace-controller-with-che-server.adoc[]
diff --git a/modules/administration-guide/pages/che-workspace-controller-with-dw.adoc b/modules/administration-guide/pages/che-workspace-controller-with-dw.adoc
@@ -0,0 +1,7 @@
+[id="che-workspace-controller-with-dw"]
+// = Che workspace controller with DevWorkspace
+:navtitle: Server side components
+:keywords: administration-guide, che-workspace-controller
+:page-aliases: .:che-workspace-controller-with-dw
+
+include::partial$assembly_understanding-che-workspace-controller-with-dw.adoc[]
diff --git a/modules/administration-guide/pages/che-workspace-controller.adoc b/modules/administration-guide/pages/che-workspace-controller.adoc
diff --git a/...les/administration-guide/pages/che-workspaces-architecture-with-che-server.adoc b/...les/administration-guide/pages/che-workspaces-architecture-with-che-server.adoc
@@ -0,0 +1,7 @@
+[id="che-workspaces-architecture-with-che-server"]
+// = Che workspaces architecture
+:navtitle: Workspace side components
+:keywords: administration-guide, che-workspaces-architecture
+:page-aliases: .:che-workspaces-architecture-with-che-server
+
+include::partial$assembly_understanding-che-workspaces-architecture-with-che-server.adoc[]
diff --git a/modules/administration-guide/pages/che-workspaces-architecture.adoc b/modules/administration-guide/pages/che-workspaces-architecture.adoc
diff --git a/...derstanding-che-workspace-controller.adoc → ...workspace-controller-with-che-server.adoc b/...derstanding-che-workspace-controller.adoc → ...workspace-controller-with-che-server.adoc
@@ -9,7 +9,7 @@ This chapter describes the {prod-short} controller and the services that are a p
 
 :context: understanding-{prod-id-short}-workspace-controller
 
-include::partial$con_che-workspace-controller.adoc[leveloffset=+1]
+include::partial$con_che-workspace-controller-with-che-server.adoc[leveloffset=+1]
 
 include::partial$con_che-server.adoc[leveloffset=+1]
 

diff --git a/...ion-guide/partials/assembly_understanding-che-workspace-controller-with-dw.adoc b/...ion-guide/partials/assembly_understanding-che-workspace-controller-with-dw.adoc
@@ -0,0 +1,26 @@
+
+
+:parent-context-of-understanding-che-workspace-controller-with-dw: {context}
+
+[id="understanding-{prod-id-short}-workspace-controller_{context}-with-dw"]
+= Understanding {prod-short} server-side components with the DevWorkspace Operator
+
+:context: understanding-{prod-id-short}-workspace-controller-with-dw
+
+include::partial$con_che-with-dw-warning.adoc[leveloffset=+1]
+
+include::partial$con_che-workspace-controller-with-dw.adoc[leveloffset=+1]
+
+include::partial$con_devworkspace-operator.adoc[leveloffset=+1]
+
+include::partial$con_che-server-with-dw.adoc[leveloffset=+1]
+
+include::partial$con_che-user-dashboard-with-dw.adoc[leveloffset=+1]
+
+include::partial$con_che-devfile-registry-with-dw.adoc[leveloffset=+1]
+
+include::partial$con_che-plug-in-registry-with-dw.adoc[leveloffset=+1]
+
+include::partial$con_che-postgresql-with-dw.adoc[leveloffset=+1]
+
+:context: {parent-context-of-understanding-che-workspace-controller-with-dw}
diff --git a/...standing-che-workspaces-architecture.adoc → ...kspaces-architecture-with-che-server.adoc b/...standing-che-workspaces-architecture.adoc → ...kspaces-architecture-with-che-server.adoc
@@ -9,7 +9,7 @@
 
 This chapter describes the architecture and components of {prod-short}.
 
-include::partial$con_che-workspaces-architecture.adoc[leveloffset=+1]
+include::partial$con_che-workspaces-architecture-with-che-server.adoc[leveloffset=+1]
 
 
 include::partial$assembly_che-workspace-components.adoc[leveloffset=+1]

diff --git a/...dministration-guide/partials/con_che-architecture-overview-with-che-server.adoc b/...dministration-guide/partials/con_che-architecture-overview-with-che-server.adoc
@@ -0,0 +1,17 @@
+[id="{prod-id-short}-architecture-overview-with-che-server_{context}"]
+= {prod-short} architecture with the {prod-id-short}-server
+
+Although {prod} is transitioning to xref:administration-guide:che-architecture-overview-with-dw.adoc[an architecture based on the DevWorksapce Operator], the default architecture is still based on the {prod-id-short}-server. The {prod-id-short}-server is a Java web service that exposes an HTTP REST API to manage {prod-short} workspaces and users. When {prod} is configured to use the {prod-id-short}-server its components are:
+
+* A central workspace controller: an always-running service that manages user workspaces through the {orch-name} API.
+* User workspaces: container-based IDEs that the controller stops when the user stops coding.
+
+.High-level {prod-short} architecture
+image::administration-guide:architecture/{project-context}-high-level.png[]
+
+When {prod-short} is installed on a {platforms-name} cluster, the workspace controller is the only component that is deployed. A {prod-short} workspace is created immediately after a user requests it.
+
+.Additional resources
+
+* xref:administration-guide:che-workspace-controller-with-che-server.adoc[]
+* xref:administration-guide:che-workspaces-architecture-with-che-server.adoc[]
diff --git a/modules/administration-guide/partials/con_che-architecture-overview-with-dw.adoc b/modules/administration-guide/partials/con_che-architecture-overview-with-dw.adoc
@@ -0,0 +1,28 @@
+
+[id="{prod-id-short}-architecture-overview-with-dw_{context}"]
+= {prod-short} architecture with the DevWorkspace
+
+include::partial$con_che-with-dw-warning.adoc[]
+
+This section describes the DevWorkspace based architecture of {prod}. {prod} default workspace engine is still the {prod-id-short}-server but from v.7.28.0 of {prod-short} an administrator can configure an alternative workspace engine: the https://github.com/devfile/devworkspace-operator[DevWorkspace {orch-name} Operator]. 
+
+The DevWorkspace based architecture will eventually become the default. Until then an administrator has to explicitly configure {prod-short} to use the DevWorkspace following the instructions in xref:installation-guide:enabling-dev-workspace-engine.adoc[this article].
+
+When {prod} is configured to use the new engine, {prod-short} workspaces are valid {orch-name} objects. They are managed through the {orch-name} API and secured through https://kubernetes.io/docs/reference/access-authn-authz/rbac/[{orch-name} role-based access control (RBAC)].
+
+{prod} components, with the DevWorkspace Operator enabled, are:
+
+* **DevWorkspace Operator**: the DevWorkspace Custom Resource Definition and the associated controller that extend {orch-name} and provide DevWorkpaces native support.
+* **{prod-short} server components**: always-running services on top of the DevWorkspace Operator for multi-tenancy and easier workspaces management.
+* **User workspaces**: container-based IDEs that the server stops when the user stops coding.
+
+.High-level {prod-short} architecture
+image::administration-guide:architecture/{project-context}-architecture-with-dw.png[]
+
+When {prod-short} is installed on a {orch-name} cluster, the DevWorkspace Operator and the {prod} server components are deployed.
+
+{prod-short} workspaces are deployed and stopped at user request. {prod-short} workspaces are automatically stopped after 30 minutes (configurable) of inactivity.
+
+.Additional resources
+
+* xref:administration-guide:che-workspace-controller-with-dw.adoc[]
diff --git a/modules/administration-guide/partials/con_che-architecture-overview.adoc b/modules/administration-guide/partials/con_che-architecture-overview.adoc
@@ -1,17 +1,15 @@
 [id="{prod-id-short}-architecture-overview_{context}"]
 = {prod-short} architecture overview
 
-{prod} components are:
+We are currently replacing {prod-short} existing workspace engine, the {prod-id-short}-server, with a new one, the https://github.com/devfile/devworkspace-operator[DevWorkspace Operator]. The former is a Java web service that exposes an HTTP REST API to manage {prod-short} workspaces and users. The latter is an {orch-name} Operator that extends the {orch-name} API so that {prod-short} workspaces can be managed as first class {prod-short} objects.
 
-* A central workspace controller: an always-running service that manages user workspaces through the {orch-name} API.
-* User workspaces: container-based IDEs that the controller stops when the user stops coding.
+{prod-short} default workspace engine is still the {prod-id-short}-server but from v.7.28.0 of {prod-short} an administrator can configure it to use the DevWorkspace Operator following the instructions in xref:installation-guide:enabling-dev-workspace-engine.adoc[this article].
 
-.High-level {prod-short} architecture
-image::administration-guide:architecture/{project-context}-high-level.png[]
+include::partial$con_che-with-dw-warning.adoc[]
 
-When {prod-short} is installed on a {platforms-name} cluster, the workspace controller is the only component that is deployed. A {prod-short} workspace is created immediately after a user requests it.
+The following sections describe the different architectures of {prod-short} configured with the DevWorkspace Operator or the {prod-id-short}-server. 
 
 .Additional resources
 
-* xref:administration-guide:che-workspace-controller.adoc[]
-* xref:administration-guide:che-workspaces-architecture.adoc[]
+* xref:administration-guide:che-architecture-overview-with-che-server.adoc[]
+* xref:administration-guide:che-architecture-overview-with-dw.adoc[]
diff --git a/modules/administration-guide/partials/con_che-devfile-registry-with-dw.adoc b/modules/administration-guide/partials/con_che-devfile-registry-with-dw.adoc
@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// {prod-id-short}-workspace-controller-with-dw
+
+[id="{prod-id-short}-devfile-registry-with-dw_{context}"]
+= {prod-short} Devfile registry (in the DevWorkspace context)
+
+The {prod-short} devfile registry is a service that provides a list of {prod-short} samples to create ready-to-use workspaces. This list of samples is used in the *Dashboard* -> *Create Workspace* window. The devfile registry runs in a container and can be deployed wherever the user dashboard can connect. The devfiles included in the registry use the v2.1 of the https://docs.devfile.io/devfile/2.1.0/user-guide/index.html[Devfile specification].
+
+[cols=2*]
+|===
+ifeval::["{project-context}" == "che"]
+| Source code
+| link:{url-devfile-registry-repo}[{prod-short} Devfile registry]
+endif::[]
+
+| Container image
+| `{che-devfile-registry-container-image}`
+|===
+
+ifeval::["{project-context}" == "che"]
+.Additional resources
+
+* xref:building-and-running-a-custom-registry-image.adoc[]
+endif::[]
diff --git a/modules/administration-guide/partials/con_che-devfile-registry.adoc b/modules/administration-guide/partials/con_che-devfile-registry.adoc
@@ -1,14 +1,11 @@
 // Module included in the following assemblies:
 //
-// {prod-id-short}-workspace-controller
+// {prod-id-short}-workspace-controller-with-che-server
 
 [id="{prod-id-short}-devfile-registry_{context}"]
 = {prod-short} Devfile registry
 
-The {prod-short} devfile registry is a service that provides a list of {prod-short} stacks to create ready-to-use workspaces. This list of stacks is used in the  *Dashboard* -> *Create Workspace* window. The devfile registry runs in a container and can be deployed wherever the user dashboard can connect.
-
-// TODO: add link to "Customizing devfile registry"
-For more information about devfile registry customization, see the Customizing devfile registry section.
+The {prod-short} devfile registry is a service that provides a list of {prod-short} samples to create ready-to-use workspaces. This list of samples is used in the *Dashboard* -> *Create Workspace* window. The devfile registry runs in a container and can be deployed wherever the user dashboard can connect.
 
 [cols=2*]
 |===
@@ -20,3 +17,9 @@ endif::[]
 | Container image
 | `{che-devfile-registry-container-image}`
 |===
+
+ifeval::["{project-context}" == "che"]
+.Additional resources
+
+* xref:building-and-running-a-custom-registry-image.adoc[]
+endif::[]
diff --git a/modules/administration-guide/partials/con_che-plug-in-registry-with-dw.adoc b/modules/administration-guide/partials/con_che-plug-in-registry-with-dw.adoc
@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// {prod-id-short}-workspace-controller-with-dw
+
+[id="{prod-id-short}-plug-in-registry-with-dw_{context}"]
+= {prod-short} plug-in registry (in the DevWorkspace context)
+
+The {prod-short} plug-in registry is a service that provides the list editors and editors' extensions for {prod-short} workspaces. Those editors and their extensions are specified as fragment of a https://docs.devfile.io/[v2 Devfile] and can be referenced from the files ``.che/che-editor.yaml`` and ``.che/che-theia-plugins.yaml`` at the root of a git repository or from a v2 Devfile ``che-editor.yaml`` and ``che-theia-plugins.yaml`` attributes. The plugin registry runs in a container and can be deployed wherever {prod-short} server connects.
+
+[cols=2*]
+|===
+ifeval::["{project-context}" == "che"]
+| Source code
+| link:{url-plug-in-registry-repo}[{prod-short} plug-in registry]
+endif::[]
+
+| Container image
+| `{che-plugin-registry-container-image}`
+|===
+
+ifeval::["{project-context}" == "che"]
+.Additional resources
+
+* xref:building-and-running-a-custom-registry-image.adoc[]
+endif::[]
diff --git a/modules/administration-guide/partials/con_che-plug-in-registry.adoc b/modules/administration-guide/partials/con_che-plug-in-registry.adoc
@@ -1,11 +1,11 @@
 // Module included in the following assemblies:
 //
-// {prod-id-short}-workspace-controller
+// {prod-id-short}-workspace-controller-with-che-server
 
 [id="{prod-id-short}-plug-in-registry_{context}"]
 = {prod-short} plug-in registry
 
-The {prod-short} plug-in registry is a service that provides the list of plug-ins and editors for the {prod-short} workspaces. A devfile only references a plug-in that is published in a {prod-short} plug-in registry. It runs in a container and can be deployed wherever {prod-short} server connects.
+The {prod-short} plug-in registry is a service that provides the list of plug-ins and editors for {prod-short} workspaces. A devfile only references a plug-in that is published in a {prod-short} plug-in registry. It runs in a container and can be deployed wherever {prod-short} server connects.
 
 [cols=2*]
 |===

diff --git a/modules/administration-guide/partials/con_che-postgresql-with-dw.adoc b/modules/administration-guide/partials/con_che-postgresql-with-dw.adoc
@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// {prod-id-short}-workspace-controller-with-dw
+
+[id="{prod-id-short}-postgresql_{context}"]
+= {prod-short} and PostgreSQL (in the DevWorkspace context)
+
+The PostgreSQL database is a {prod-short} prerequisite. The {prod-short} administrator can choose to connect {prod-short} to an existing PostgreSQL instance or let the {prod-short} deployment start a new dedicated PostgreSQL instance.
+
+The {prod-id-short}-server uses the database to persist user configurations (workspaces metadata, Git credentials).
+
+[cols=2*]
+|===
+ifeval::["{project-context}" == "che"]
+| Source code
+| link:{link-postgres-dockerfile-location}[{prod-short} Postgres]
+endif::[]
+
+| Container image
+| `{postgresql-image-url}`
+|===
diff --git a/modules/administration-guide/partials/con_che-postgresql.adoc b/modules/administration-guide/partials/con_che-postgresql.adoc
@@ -1,13 +1,13 @@
 // Module included in the following assemblies:
 //
-// {prod-id-short}-workspace-controller
+// {prod-id-short}-workspace-controller-with-che-server
 
 [id="{prod-id-short}-postgresql_{context}"]
 = {prod-short} and PostgreSQL
 
 The PostgreSQL database is a prerequisite to configure {prod-short} in multiuser mode. The {prod-short} administrator can choose to connect {prod-short} to an existing PostgreSQL instance or let the {prod-short} deployment start a new dedicated PostgreSQL instance.
 
-The {prod-short} server uses the database to persist user configurations (workspaces metadata, Git credentials). {identity-provider} uses the database as its back end to persist user information.
+The {prod-id-short}-server uses the database to persist user configurations (workspaces metadata, Git credentials). {identity-provider} uses the database as its back end to persist user information.
 
 [cols=2*]
 |===

diff --git a/modules/administration-guide/partials/con_che-server-with-dw.adoc b/modules/administration-guide/partials/con_che-server-with-dw.adoc
@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// {prod-id-short}-workspace-controller-with-dw
+
+
+[id="{prod-id-short}-server-with-dw_{context}"]
+= {prod-short} server (in the DevWorkspace context)
+
+The {prod-id-short}-server is the central service of {prod-short} server-side components. It is a Java web service that exposes an HTTP REST API to simplify the usage of the DevWorkspace API in a multi-tenant context.
+
+[cols=2*]
+|===
+ifeval::["{project-context}" == "che"]
+| Source code
+| link:https://github.com/eclipse-che/che-server[{prod} server repository] 
+endif::[]
+
+| Container image
+| `quay.io/eclipse/che-server`
+
+|===
+
+.Additional resources
+
+* xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[]
diff --git a/modules/administration-guide/partials/con_che-server.adoc b/modules/administration-guide/partials/con_che-server.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// {prod-id-short}-workspace-controller
+// {prod-id-short}-workspace-controller-che-server
 
 
 [id="{prod-id-short}-server_{context}"]
@@ -16,7 +16,7 @@ ifeval::["{project-context}" == "che"]
 endif::[]
 
 | Container image
-| `eclipse/che-server`
+| `quay.io/eclipse/che-server`
 
 |===
 

diff --git a/modules/administration-guide/partials/con_che-user-dashboard-with-dw.adoc b/modules/administration-guide/partials/con_che-user-dashboard-with-dw.adoc
@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// {prod-id-short}-workspace-controller-with-dw
+
+[id="{prod-id-short}-user-dashboard-with-dw_{context}"]
+= {prod-short} user dashboard (in the DevWorkspace context)
+
+The user dashboard is the landing page of {prod}. It is a React application. {prod-short} users create, start, and manage {prod-short} workspaces from their browsers through the user dashboard.
+
+[cols=2*]
+|===
+ifeval::["{project-context}" == "che"]
+| Source code
+| link:https://github.com/eclipse-che/che-dashboard[{prod-short} Dashboard]
+endif::[]
+
+| Container image
+| `quay.io/eclipse/che-dashboard`
+|===