Restructure/reorganize content in SM introduction pages #4049
Conversation
conceptualshark
added
dx
|
👋 🤖 ✅ Looks like the changes were ported across versions, nice job! 🎉 You can read more about the versioning within our docs in our documentation guidelines. |
|
|
||
| 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/). |
There was a problem hiding this comment.
Leaving an expansion on content here for #1055 - just a quick rewrite for now.
| 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 |
There was a problem hiding this comment.
I believe these architecture diagrams are a little out of date, so I attempted to include that these were example/sample deployments, only, until they can be updated.
|  | ||
|
|
||
| :::note | ||
| By default, the deployment requires at least three Kubernetes Nodes to meet the Pod Anti-Affinity constraints. |
There was a problem hiding this comment.
The "additional considerations" section in the original architecture doc includes this:
For components with Anti-Affinity enabled, like Zeebe Broker, the Kubernetes Nodes should be equal to or greater than the number of the Pod replicas. Otherwise, some of its Pods will not be scheduled and will be in a "Pending" state.
As far as I could tell, this is the only place we talk about which (if any) components have anti-affinity enabled, or mention what to do in that case/"Pending" state pods? I don't think this diagram section is the right place for this information, even in passing, and if this is something SM users will need to know, it should be called out more directly in appropriate sections...? I can spin off a new issue to research this if this line of thought seems correct.
There was a problem hiding this comment.
I added @theburi as a reviewer to the overall PR, but I'm hoping he could shed some light on this specific topic. Is this something we can address here quickly @theburi, or should @conceptualshark create a new issue and discuss it with you separately?
There was a problem hiding this comment.
My initial thought was that this note would be too specific at this doc level. There are several constrains that needs to be taken into account and we should group them in one place, somewhere inside installation page.
There was a problem hiding this comment.
I'm going to go ahead and remove the notes from this section of the docs, which is meant to be more of an overview, and created an issue for discussion/creation of a better place for these recommendations/constraints/etc to live (#4075).
There was a problem hiding this comment.
In general, I like the direction these changes are going and my hope is the feedback that does come in isn't significantly blocking or can be addressed in iterations (for example, diagrams may be stale).
As I read through this, I'm wondering if "Ingress" is clear to users. Can you add this to the glossary? In this PR Ingress is used by itself or "Ingress objects," and I'm not sure they need to be different.
Lastly, don't get caught off guard when you backport these changes and need a redirect to remove the Architecture page. We don't do the same checks against /next/ content.
|
I'm adding @hisImminence as a review in case he wants to involve other engineers in the Self-Managed space in reviewing these changes. |
|  | ||
|
|
||
| :::note | ||
| By default, the deployment requires at least three Kubernetes Nodes to meet the Pod Anti-Affinity constraints. |
There was a problem hiding this comment.
My initial thought was that this note would be too specific at this doc level. There are several constrains that needs to be taken into account and we should group them in one place, somewhere inside installation page.
| - 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: |
There was a problem hiding this comment.
Since we are updating the page. This statement is not really correct. Not all the components are highly available. Operate is a single node only (Using Helm charts) It is possible to deploy in HA mode, but it needs manual intervention. Can we rephrase it ?
There was a problem hiding this comment.
I would argue that 'it is possible to deploy HA mode', and therefore the statement is correct :P I feel it would sound more confusing if we state its not HA or partially.
Would it be an idea to create a follow up to create a guide or make the HCs configuration more easy for customers to set up all apps in HA mode then?
There was a problem hiding this comment.
@hisImminence @theburi Do you think this diagram with a theoretical HA mode is adding anything for a technical audience? I could remove it if it's only adding to confusion, and make an issue to create the follow-up HA guide. Or, leave it for now, and make that guide to link to from here when it's done.
There was a problem hiding this comment.
I could remove it if it's only adding to confusion, and make an issue to create the follow-up HA guide
You are referring to the diagram on this page, or?
I would go with this option: I could remove it if it's only adding to confusion, and make an issue to create the follow-up HA guide.
There was a problem hiding this comment.
Specifically the high availability diagram here. I've gone ahead and removed it in this iteration, and set up this issue to look into it outside of this cleanup PR.
docs/self-managed/setup/overview.md
Outdated
| - **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/amazon-eks.md). | ||
| - [**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. |
There was a problem hiding this comment.
One thought here: would it make sense to have the Docker Compose part as a separate bullet point (would make if fmpov clearer that its not related to the docker setup), and only local!
There was a problem hiding this comment.
I pulled out docker compose in the latest push, and put it in its own mention, to keep this only a list of option for production-viable deployments.
Thanks @akeller, reviewed and besides the 2 commands I left lgtm (no blockers just thoughts)! Happy we get things movin'! |
|
@akeller I promise this isn't as large as it seems, but backporting was a bit of a mess! I'd love a final sign-off on the redirects and a sanity check on the backported links. I think it's in a good state now. |
|
|
||
| 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. | ||
| - Web applications: `https://camunda.example.com/[identity|operate|optimize|tasklist|modeler]` |
There was a problem hiding this comment.
We refer to these as Components. Web Applications is not a topology term that we use. It also does not represent them fully
There was a problem hiding this comment.
I think the usage here shouldn't capture each component fully, only represent the web interface, and should explicitly separate them out from Zeebe in terms of access.
There's a number of places where we use web app/application like this, so if it shouldn't be used at all, let me know if I should create a separate ticket to update it elsewhere.
There was a problem hiding this comment.
I could not craft a good definition of when to use components vs. web applications off the top of my head. If I had to reason out loud, it would be the following: Modeler is the component, but Web Modeler is a web application. I don't think Identity is a web application, but I don't know how I would verify that.
For internal resources, I would recommend this PMM-maintained page. You can also follow up with @karl-heinsen since I hit a dead end here.
There was a problem hiding this comment.
Would "web components" be preferable? The entirety of this section is focused on separating out the different points of access, so "Components" isn't inclusive enough as Zeebe isn't included, and we're also not referring to the entirety of the component - only the method of access. Looking for any term that is inclusive of all components with a served log-in page, and excludes those without.
| - 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` |
There was a problem hiding this comment.
I would back either "web applications" or "web components" to get this out the door.
There was a problem hiding this comment.
Web Modeller has three parts - NodeJS server that exposes web interface, REST API server and Socket server. Identity has also web interface. 'Web Component' is to restrictive and diminishes the value of our product. We typically refer to zeebe, optimize, operate as Component or C8.
Can we use 'Component' going forward?
| @@ -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. | |||
There was a problem hiding this comment.
I got into a habit of using the docs area instead of trying to walk the file structure with ../'s. Can you bring this to a team meeting so we can discuss it? No action required here (in the PR).
There was a problem hiding this comment.
@conceptualshark have a look at the link vale is complaining about. Linking to /docs/ will not respect the version drop down.
My other feedback is not blocking for this PR.
|
|
||
| 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. | ||
| - Web applications: `https://camunda.example.com/[identity|operate|optimize|tasklist|modeler]` |
There was a problem hiding this comment.
Web Modeller has three parts - NodeJS server that exposes web interface, REST API server and Socket server. Identity has also web interface. 'Web Component' is to restrictive and diminishes the value of our product. We typically refer to zeebe, optimize, operate as Component or C8.
Can we use 'Component' going forward?
|
Called out the components explicitly to remove any reference to "web" in either components or applications; carved out https://github.com/camunda/developer-experience/issues/370 to tackle the use of these terms throughout the docs. |
|
Waiting on the results of #3888 before merging to more easily incorporate those changes (terms approved by support and legal, etc) - should be within 24 hours. |
conceptualshark
dismissed
theburi’s stale review
Updated to be component-specific
|
🧹 Preview environment for this PR has been torn down. |
Description
Resolves #3235, relates to #199.
This PR separates out the consolidation and clean-up of the intro, architecture, and installation overview pages from any content additions or adjustments to other pages. The changes are currently confined to
/next, but can/will be backported + rerouted after an initial review, if needed.When should this change go live?
holdlabel or convert to draft PR)PR Checklist
/versioned_docsdirectory./docsdirectory (aka/next/).