As a user I have a hard time to quickly start with C8 SM

[Zelldon]

Details (Problem)

I recently played around with C8 SM (as preparation for a Game day) and I simply installed the chart with all defaults.

Instead of using port-forwarding and doing everything local I wanted to be more realistic and deploy an application in K8 as well. I had a really hard time to find out what I have to do such my application can talk with Zeebe (meaning configure the right OAUTH stuff with Identity, etc.)

I was missing a simple quick start guide for this, and was wondering whether we don't have such thing? I haven't seen anything in the docs.

What I found were some blog entries from @nloding (which is great btw) but they didn't get far enough, for example:

• https://camunda.com/blog/2023/10/camunda-self-managed-for-absolute-beginners/
• https://camunda.com/blog/2024/01/camunda-self-managed-absolute-beginners-part-2-ingress-tls-ssl/

As user I had expected they might cover this, but this just ends with Add Identity and Optimize, configure the ingress, and test the authentication with zbctl

As this is actually the default anyway I don't think it is the best to place it into a blog. I would expect an get started guide for such in our documentation.

Even the current guide https://docs.camunda.io/docs/self-managed/setup/guides/installing-payment-app-example/ just links to a guide which explains everything with port-forwarding. I don't think that we expect to use such thing to be used in production.

Proposal

We place a quick get started or (go to production guide) that includes just install helm charts, do x,y,z and be happy.

For example, I wrote the following down here (these were the steps to achieve this):

Example guide:

Installation:

releaseName=c8-sm
helm install $releaseName camunda/camunda-platform

Will include:

• Identity, Keycloak, Postgres
• Tasklist, Operate, Optimize, Elasticsearch
• Zeebe Broker, Zeebe Gateway

Application deployment For example, we can use our starter deployment, that we use for our cloud benchmarks:

1. Port-forward to keycloak kubectl port-forward svc/$releaseName-keycloak 18080:80
2. Port-forward to identity kubectl port-forward svc/c8-sm-identity 8080:80
3. Access http://localhost:8080/applications
4. Check pre-configured Zeebe application - get the clientId and client secret
5. Configure either the starter via environment variables or the secret as we do in our benchmarks (I recommend this)

The secret can look like this:

apiVersion: v1
kind: Secret
metadata:
  name: cloud-credentials
type: Opaque
stringData:
  clientId: zeebe # Copied from Identity
  clientSecret: xxxxxxxxxx # Copied from Identity
  # the prefix depends on your chart $releaseName; internally the application can resolve this name
  zeebeAddress: c8-sm-zeebe-gateway:26500 
  # the prefix depends on your chart $releaseName; make sure to use the service name
  authServer: http://c8-sm-keycloak/auth/realms/camunda-platform/protocol/openid-connect/token 

Our starter deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: starter
  labels:
    app: starter
spec:
  selector:
    matchLabels:
      app: starter
  replicas: 1
  template:
    metadata:
      labels:
        app: starter
        metrics: gmp
    spec:
      containers:
        - name: starter
          image: gcr.io/zeebe-io/starter:SNAPSHOT
          imagePullPolicy: Always
          env:
            - name: JDK_JAVA_OPTIONS
              value: >-
                -Dapp.starter.rate=5
                -Dapp.tls=false
                -Dzeebe.client.requestTimeout=62000
                -XX:+HeapDumpOnOutOfMemoryError
            - name: LOG_LEVEL
              value: "info"
            - name: ZEEBE_ADDRESS
              valueFrom:
                secretKeyRef:
                  name: cloud-credentials
                  key: zeebeAddress
            - name: ZEEBE_CLIENT_ID
              valueFrom:
                secretKeyRef:
                  name: cloud-credentials
                  key: clientId
            - name: ZEEBE_CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: cloud-credentials
                  key: clientSecret
            - name: ZEEBE_AUTHORIZATION_SERVER_URL
              valueFrom:
                secretKeyRef:
                  name: cloud-credentials
                  key: authServer
            - name: ZEEBE_TOKEN_SCOPE
              value: "camunda-identity"
            - name: ZEEBE_TOKEN_AUDIENCE
              value: "zeebe-api"

          resources:
            limits:
              cpu: 250m
              memory: 256Mi
            requests:
              cpu: 250m
              memory: 256Mi

If you now port forward to Operate kubectl port-forward svc/c8-sm-operate 8081:80 you will see new instances being created.

Maybe we can reuse this.

[Zelldon]

Looks like I followed the wrong link https://github.com/camunda-community-hub/camunda-8-examples/tree/main/payment-example-process-application

Instead of https://github.com/camunda-community-hub/camunda-8-examples/blob/main/payment-example-process-application/kube/README.md

Can we make this more accessible and visible (observable). WDYT @akeller ?

[akeller]

We have an E2E for MT + SM (which I don't think you are looking for) as well as getting started guide content in the works for different installation paths.

I don't think that we expect to use such thing to be used in production.

Getting started guides shouldn't be used in production, but they shouldn't necessarily block seeing features. We are having an internal discussion about this now - what is in scope for getting started vs. after. I want to draw a clear distinction between getting started vs. production build outs until it's super easy to do both quickly. This is not a topic that can just be fixed with docs.

However, based on your feedback, it looks like there are things we can take immediate action on.

@conceptualshark is our DRI of SM docs, and I want to make sure this is on your radar. Can you start to take a look at this feedback and see if there are any quick wins as you continue your onboarding? I will continue to pull you in to topics as they evolve or need your input.

FYI @maxdanilov, who is also part of this internal discussion. Super timely, as we just had a meeting today!

[akeller]

Related to https://camunda.slack.com/archives/C077J92G8LX