camunda · conceptualshark · Aug 21, 2024 · Jul 1, 2024 · Jul 17, 2024 · Jul 17, 2024
diff --git a/docs/self-managed/about-self-managed.md b/docs/self-managed/about-self-managed.md
@@ -7,29 +7,38 @@ title: "Camunda 8 Self-Managed"
 
 Camunda 8 Self-Managed is not Camunda 7. [Find Camunda 7 documentation here](https://docs.camunda.org).
 
-However, Optimize documentation is available for both Camunda 8 and Camunda 7, including deployment instructions available [here]($optimize$/self-managed/optimize-deployment/install-and-start). Look for `Camunda 7` badges to help you understand what content is available for what product.
-
 :::
 
-As an alternative to using Camunda 8 through SaaS, you can host it yourself; we call this setup Camunda 8 Self-Managed.
+Camunda 8 Self-Managed is a self-hosted alternative to using Camunda 8 SaaS. Building process automation solutions with Camunda 8 works similarly regardless of hosting and deployment.
 
-Building process automation solutions with Camunda 8 Self-Managed is similar to working with Camunda 8 SaaS. For more information on Camunda 8 SaaS, visit [What is Camunda 8?](../components/concepts/what-is-camunda-8.md) If you are new to Camunda 8, we recommend you start your journey with [Camunda 8 SaaS-based guides](../../guides/).
+For more information on Camunda 8 SaaS, visit [What is Camunda 8?](../components/concepts/what-is-camunda-8.md) If you are new to Camunda 8, we recommend you start your journey with [Camunda 8 SaaS-based guides](../../guides/).
 
 The content in this section of the documentation includes:
 
 - Everything you need to download, configure, and work with each component of Camunda 8 Self-Managed.
 - Features specific to Camunda 8 Self-Managed.
 
-The following components are available for Camunda 8 Self-Managed:
+To get started with your Self-Managed installation, see our [installation overview](./setup/overview.md).
+
+## Architecture
+
+Camunda 8 Self-Managed consists of multiple web applications and gRPC services. The following example architecture diagram uses two [Ingress objects](./setup/guides/ingress-setup.md#combined-ingress-setup) to access these services externally: an Ingress with HTTP(S) protocol for all web applications using a single domain, and another Ingress with gRPC protocol for the Zeebe workflow engine.
+
+![Camunda 8 Self-Managed Architecture Diagram - Combined Ingress](./assets/camunda-platform-8-self-managed-architecture-diagram-combined-ingress.png)
+
+:::note
+By default, the deployment requires at least three Kubernetes Nodes to meet the Pod Anti-Affinity constraints.
+:::
+
+In this configuration, Camunda 8 Self-Managed can be accessed as follows:
+
+- Web applications: `https://camunda.example.com/[identity|operate|optimize|tasklist|modeler]`
- Web applications: `https://camunda.example.com/[identity|operate|optimize|tasklist|modeler]`
+In this configuration, Camunda 8 Self-Managed can be accessed as follows:
+- Web components: `https://camunda.example.com/[identity|operate|optimize|tasklist|modeler]`
+  - Web Modeler also exposes a WebSocket endpoint on `https://camunda.example.com/modeler-ws`. This is only used by the application itself and not supposed to be accessed by users directly.
+- Keycloak authentication: `https://camunda.example.com/auth`
+- Zeebe gateway: `grpc://zeebe.camunda.example.com`
- Web applications: `https://camunda.example.com/[identity|operate|optimize|tasklist|modeler]`
+In this configuration, Camunda 8 Self-Managed can be accessed as follows:
+- Web components: `https://camunda.example.com/[identity|operate|optimize|tasklist|modeler]`
+  - Web Modeler also exposes a WebSocket endpoint on `https://camunda.example.com/modeler-ws`. This is only used by the application itself and not supposed to be accessed by users directly.
+- Keycloak authentication: `https://camunda.example.com/auth`
+- Zeebe gateway: `grpc://zeebe.camunda.example.com`
+  - Web Modeler also exposes a WebSocket endpoint on `https://camunda.example.com/modeler-ws`. This is only used by the application itself and not supposed to be accessed by users directly.
+- Keycloak authentication: `https://camunda.example.com/auth`
+- Zeebe gateway: `grpc://zeebe.camunda.example.com`
+
+## Availability
 
-- Zeebe
-- Zeebe Gateway
-- Operate
-- Tasklist
-- Connectors
-- Optimize
-- Identity (not available in Camunda 8 SaaS)
-- Console [<span class="badge badge--enterprise-only">Enterprise only</span>](../../reference/licenses/#console)
-- Web Modeler
+Each component of Camunda 8 Self-Managed can be deployed in single or high-availability mode, which provides minimal to no service interruption. The following diagram represents deployment in high-availability mode:
 
-Camunda 8 Self-Managed users may also use [Desktop Modeler](../../components/modeler/desktop-modeler/install-the-modeler) as an addition to these components. Desktop Modeler can be used by process developers to build BPMN diagrams, DMN diagrams, or [Camunda Forms](../guides/utilizing-forms.md) for automation.
+![Camunda 8 Self-Managed Deployment Diagram](./assets/camunda-platform-8-self-managed-deployment-diagram-high-availability-mode.png)
diff --git a/...architecture-diagram-combined-ingress.png → ...architecture-diagram-combined-ingress.png b/...architecture-diagram-combined-ingress.png → ...architecture-diagram-combined-ingress.png
diff --git a/...rchitecture-diagram-separated-ingress.png → ...rchitecture-diagram-separated-ingress.png b/...rchitecture-diagram-separated-ingress.png → ...rchitecture-diagram-separated-ingress.png
diff --git a/...oyment-diagram-high-availability-mode.png → ...oyment-diagram-high-availability-mode.png b/...oyment-diagram-high-availability-mode.png → ...oyment-diagram-high-availability-mode.png
diff --git a/docs/self-managed/platform-architecture/overview.md b/docs/self-managed/platform-architecture/overview.md
diff --git a/docs/self-managed/setup/deploy/amazon/amazon-eks/eks-helm.md b/docs/self-managed/setup/deploy/amazon/amazon-eks/eks-helm.md
@@ -25,7 +25,7 @@ Multi-tenancy is disabled by default and is not covered further in this guide. I
 
 ### Architecture
 
-Note the [existing architecture](/self-managed/platform-architecture/overview.md#architecture) extended by deploying a Network Load Balancer with TLS termination within the [ingress](https://kubernetes.github.io/ingress-nginx/user-guide/tls/) below.
+Note the [existing architecture](../../../../about-self-managed.md#architecture) extended by deploying a Network Load Balancer with TLS termination within the [ingress](https://kubernetes.github.io/ingress-nginx/user-guide/tls/) below.
 
 Additionally, two components ([external-dns](https://github.com/kubernetes-sigs/external-dns) and [cert-manager](https://cert-manager.io/)) handle requesting the TLS certificate from [Let's Encrypt](https://letsencrypt.org/) and configuring Route53 to confirm domain ownership and update the DNS records to expose the Camunda 8 deployment.
 

diff --git a/docs/self-managed/setup/guides/ingress-setup.md b/docs/self-managed/setup/guides/ingress-setup.md
@@ -24,7 +24,7 @@ Camunda 8 Helm chart doesn't manage or deploy Ingress controllers, it only deplo
 
 In this setup, a single Ingress/domain is used to access Camunda 8 web applications, and another for Zeebe Gateway. By default, all web applications use `/` as a base, so we just need to set the context path, Ingress configuration, and authentication redirect URLs.
 
-![Camunda 8 Self-Managed Architecture Diagram - Combined Ingress](../../platform-architecture/assets/camunda-platform-8-self-managed-architecture-diagram-combined-ingress.png)
+![Camunda 8 Self-Managed Architecture Diagram - Combined Ingress](../../assets/camunda-platform-8-self-managed-architecture-diagram-combined-ingress.png)
 
 ```yaml
 # Chart values for the Camunda 8 Helm chart in combined Ingress setup.
@@ -109,7 +109,7 @@ Once deployed, you can access the Camunda 8 components on:
 
 In this configuration, every Camunda 8 component is assigned its own Ingress and Domain. The use of a context path is unnecessary because the default base path `/` is used for each Ingress/Domain. In this setup, you only need to provide the Ingress settings and specify the Identity authentication redirect URLs.
 
-![Camunda 8 Self-Managed Architecture Diagram - Separated Ingress](../../platform-architecture/assets/camunda-platform-8-self-managed-architecture-diagram-separated-ingress.png)
+![Camunda 8 Self-Managed Architecture Diagram - Separated Ingress](../../assets/camunda-platform-8-self-managed-architecture-diagram-separated-ingress.png)
 
 ```yaml
 # Chart values for the Camunda 8 Helm chart in combined Ingress setup.

diff --git a/docs/self-managed/setup/guides/using-existing-keycloak.md b/docs/self-managed/setup/guides/using-existing-keycloak.md
@@ -4,7 +4,7 @@ title: "Using existing Keycloak"
 description: "Learn how to use an existing Keycloak instance in Camunda 8 Self-Managed deployment."
 ---
 
-Camunda 8 Self-Managed has two different types of applications: Camunda applications (Operate, Optimize, Tasklist, etc.) and non-Camunda applications (such as Keycloak and Elasticsearch). For more details, review the [architecture](/self-managed/platform-architecture/overview.md) documentation for more information on the different types of applications.
+Camunda 8 Self-Managed has two different types of applications: Camunda applications (Operate, Optimize, Tasklist, etc.) and non-Camunda applications (such as Keycloak and Elasticsearch). For more details, review the [architecture](../../about-self-managed.md#architecture) documentation for more information on the different types of applications.
 
 This guide steps through using an existing Keycloak instance, which is part of [Camunda Identity](/self-managed/identity/what-is-identity.md). By default, [Helm chart deployment](/self-managed/setup/install.md) creates a new Keycloak instance, but it's possible to use an existing Keycloak instance either inside the same Kubernetes cluster or outside of it.
 

diff --git a/docs/self-managed/setup/guides/using-existing-opensearch.md b/docs/self-managed/setup/guides/using-existing-opensearch.md
@@ -4,7 +4,7 @@ title: "Using Amazon OpenSearch Service"
 description: "Learn how to use an Amazon OpenSearch Service instance in Camunda 8 Self-Managed deployment."
 ---
 
-Camunda 8 Self-Managed has two different types of components: Camunda components (Operate, Optimize, Tasklist, etc.) and non-Camunda dependency components (such as Keycloak and Elasticsearch). For more details, review the [architecture](/self-managed/platform-architecture/overview.md) documentation for more information on the different types of applications.
+Camunda 8 Self-Managed has two different types of components: Camunda components (Operate, Optimize, Tasklist, etc.) and non-Camunda dependency components (such as Keycloak and Elasticsearch). For more details, review the [architecture](../../about-self-managed.md#architecture) documentation for more information on the different types of applications.
 
 This guide steps through using an existing Amazon OpenSearch Service instance. By default, [Helm chart deployment](/self-managed/setup/overview.md) creates a new Elasticsearch instance, but it's possible to use Amazon OpenSearch Service instead.
 

diff --git a/docs/self-managed/setup/install.md b/docs/self-managed/setup/install.md
@@ -48,7 +48,7 @@ For example, `CAMUNDA_OPERATE_ELASTICSEARCH_URL` becomes `CAMUNDA_OPERATE_OPENSE
 Refer to the [Operate](/self-managed/operate-deployment/operate-configuration.md#settings-for-opensearch) and [Tasklist](/self-managed/tasklist-deployment/tasklist-configuration.md#elasticsearch-or-opensearch) configuration documentation for additional component configuration parameters to update.
 :::
 
-![Camunda 8 Self-Managed Architecture Diagram](../platform-architecture/assets/camunda-platform-8-self-managed-architecture-diagram-combined-ingress.png)
+![Camunda 8 Self-Managed Architecture Diagram](../assets/camunda-platform-8-self-managed-architecture-diagram-combined-ingress.png)
 
 When installing the [camunda-platform](https://artifacthub.io/packages/helm/camunda/camunda-platform) Helm chart, all components shown on the architectural diagram above are installed.
 

diff --git a/docs/self-managed/setup/overview.md b/docs/self-managed/setup/overview.md
@@ -6,7 +6,7 @@ description: "This chapter contains information for users who want to deploy and
 keywords: ["camunda download"]
 ---
 
-This chapter contains information for users who want to deploy and run Camunda 8 Self-Managed, typically in their self-controlled cloud (public or private) or even on their own hardware.
+This guide contains information for users who want to install, deploy, and upgrade Camunda 8 Self-Managed, typically in their self-controlled cloud (public or private) or on their own hardware.
 
 ## Components
 
@@ -19,22 +19,24 @@ This chapter contains information for users who want to deploy and run Camunda 8
 - Web Modeler
 - Console [<span class="badge badge--enterprise-only">Enterprise only</span>](../../../reference/licenses/#console-sm)
 
-All components except Web Modeler and Console are single Java applications.
+All components except Web Modeler and Console are single Java applications. Depending on your needs, you might not need all of the above components to successfully use Camunda 8.
 
-Depending on your needs, you might not need all the above components to successfully use Camunda 8.
+Camunda 8 Self-Managed users may also use [Desktop Modeler](../components/modeler/desktop-modeler/install-the-modeler) as an addition to these components. Desktop Modeler can be used by process developers to build BPMN diagrams, DMN diagrams, or [Camunda Forms](../../guides/utilizing-forms.md) for automation.
+
+:::note
+
+To obtain or retrieve your Camunda 8 credentials for Enterprise licenses, visit the [contact page](/contact).
+
+:::
 
 ## Supported environments
 
 For details on supported environments (e.g. Java or Elasticsearch versions), see [supported environments](/reference/supported-environments.md).
 
 ## Deployment options
 
-You have the following options to run or deploy the above components in a self-managed fashion:
-
-- **Helm/Kubernetes**: We strongly recommend using Kubernetes to run Camunda 8 in production. In addition to stock Kubernetes we also officially support variety of providers like Red Hat OpenShift and Amazon EKS. Also using Kubernetes with Minikube or KIND can be an interesting environment to run Camunda 8 locally on developer machines.
-- **Docker**: You can run the provided Docker images of the components, also in production. For your convenience, we provide a Docker Compose configuration to run Camunda 8 on developer machines. Note that the Docker Compose configuration is **not** optimized for production usage, but for local development. You can find setup instructions in the [camunda-platform](https://github.com/camunda/camunda-platform) repository.
-- **Manual**: You can run the Java applications on a local or virtual machine if it provides a supported Java Virtual Machine (JVM). This allows you to run Camunda on virtual machines or bare metal and offers a significant amount of flexibility. However, you will need to configure the details for the components to interact correctly yourself. We consider this a last resort. Note that Windows/Mac is **not** supported for production usage of Zeebe.
+- [**Helm/Kubernetes**](./install.md): We recommend using Kubernetes and Helm to deploy and run Camunda 8 Self-Managed in production. With the right configuration, Camunda 8 Self-Managed can be deployed on any Certified Kubernetes distribution (cloud or on-premise). We also officially support a variety of providers like [Red Hat OpenShift](./deploy/openshift/redhat-openshift.md) and [Amazon EKS](./deploy/amazon/amazon-eks/).
+- [**Docker**](./deploy/other/docker.md): Component [Docker images](https://hub.docker.com/u/camunda) are available for use in production. A Docker Compose configuration is also provided for local development, and is **not** optimized for production usage. You can find setup instructions in the [camunda-platform](https://github.com/camunda/camunda-platform) repository.
+- [**Manual**](./deploy/local/manual.md): The Java applications can run on a local or virtual machine if it provides a supported Java Virtual Machine (JVM). This allows you to run Camunda on virtual machines or bare metal and offers a significant amount of flexibility. However, you will need to configure the details for the components to interact correctly yourself. We consider this a last resort. Note that Windows/Mac is **not** supported for production usage of Zeebe.
 
-:::note
-For additional details on locating your Camunda 8 credentials, visit the [contact page](/contact).
-:::
+For more details on deployment, see [sizing your environment](../../components/best-practices/architecture/sizing-your-environment.md#camunda-8-self-managed).
diff --git a/optimize_sidebars.js b/optimize_sidebars.js
@@ -2132,13 +2132,6 @@ module.exports = {
 
   "Self-Managed": [
     docsLink("Camunda 8 Self-Managed", "self-managed/about-self-managed/"),
-
-    {
-      Architecture: [
-        docsLink("Overview", "self-managed/platform-architecture/overview/"),
-      ],
-    },
-
     {
       Setup: [
         docsLink("Overview", "self-managed/setup/overview/"),

diff --git a/sidebars.js b/sidebars.js
@@ -867,7 +867,6 @@ module.exports = {
   "Self-Managed": [
     "self-managed/about-self-managed",
     {
-      Architecture: ["self-managed/platform-architecture/overview"],
       Setup: [
         "self-managed/setup/overview",
         "self-managed/setup/install",