docs: setup with service account docs (#4877)

* docs: add service account setup for kubernetes

* docs: add service account setup for macos, linux and compose

* docs: change image tag in compose

* docs: move default user part of kubernetes

docs/docs/guides/deploy/compose.mdx

@@ -4,12 +4,15 @@ title: Docker Compose
 
 import CodeBlock from '@theme/CodeBlock';
 import DockerComposeSource from '!!raw-loader!./docker-compose.yaml'
+import DockerComposeSaSource from '!!raw-loader!./docker-compose-sa.yaml'
 import Disclaimer from './_disclaimer.mdx'
 import DefaultUser from './_defaultuser.mdx'
 import Next from './_next.mdx'
 
 The setup is tested against Docker version 20.10.17 and Docker Compose version v2.2.3
 
+## Docker compose
+
 By executing the commands below, you will download the following file:
 
 <details><summary>docker-compose.yaml</summary>
@@ -28,5 +31,27 @@ docker compose up --detach
 
 ## VideoGuide
 <iframe width="100%" height="315" src="https://www.youtube.com/embed/-02FaoN9Fko" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+## Docker compose with service account
+
+By executing the commands below, you will download the following file:
+
+<details><summary>docker-compose-sa.yaml</summary>
+    <CodeBlock language="yaml">{DockerComposeSaSource}</CodeBlock>
+</details>
+
+```bash
+# Download the docker compose example configuration.
+wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/deploy/docker-compose-sa.yaml -O docker-compose.yaml
+
+# Run the database and application containers.
+docker compose up --detach
+
+# then you can move your machine key
+mv ./machinekey/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json
+```
+
+This key can be used to provision resources with for example [Terraform](../manage/terraform/basics.md).
+
 <Next components={props.components} />
 <Disclaimer components={props.components} />

docs/docs/guides/deploy/docker-compose-sa.yaml

@@ -0,0 +1,42 @@
+version: '3.8'
+
+services:
+  zitadel:
+    restart: 'always'
+    networks:
+      - 'zitadel'
+    image: 'ghcr.io/zitadel/zitadel:stable'
+    command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
+    environment:
+      - 'ZITADEL_DATABASE_COCKROACH_HOST=crdb'
+      - 'ZITADEL_EXTERNALSECURE=false'
+      - 'ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/machinekey/zitadel-admin-sa.json'
+      - 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa'
+      - 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin'
+      - 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1'
+    depends_on:
+      crdb:
+        condition: 'service_healthy'
+    ports:
+      - '8080:8080'
+    volumes:
+      - ./machinekey:/machinekey
+
+  crdb:
+    restart: 'always'
+    networks:
+      - 'zitadel'
+    image: 'cockroachdb/cockroach:v22.1.3'
+    command: 'start-single-node --insecure'
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health?ready=1"]
+      interval: '10s'
+      timeout: '30s'
+      retries: 5
+      start_period: '20s'
+    ports:
+      - '9090:8080'
+      - '26257:26257'
+
+networks:
+  zitadel:

docs/docs/guides/deploy/kubernetes.mdx

@@ -19,7 +19,9 @@ helm repo add cockroachdb https://charts.cockroachdb.com/
 helm repo add zitadel https://charts.zitadel.com
 ```
 
-### Install an insecure cockroachdb and zitadel release that works with localhost
+### Install zitadel
+
+#### Install an insecure cockroachdb and zitadel release that works with localhost
 
 ```bash
 # CockroachDB
@@ -34,15 +36,44 @@ helm install my-zitadel zitadel/zitadel \
   --set zitadel.configmapConfig.ExternalSecure=false \
   --set zitadel.configmapConfig.TLS.Enabled=false \
   --set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \
-  --set replicaCount=1
+  --set replicaCount=1 \
+  --set cockroachdb.single-node=true \
+  --set cockroachdb.statefulset.replicas=1
 ```
 
+<DefaultUser components={props.components} />
+
+#### Install an insecure zitadel release that works with localhost with a service account
+
+!!!Caution!!! With this setup you only get a service account with a key and no admin account where you can login directly into ZITADEL.
+
+```bash
+helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \
+  --set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \
+  --set zitadel.configmapConfig.ExternalSecure=false \
+  --set zitadel.configmapConfig.TLS.Enabled=false \
+  --set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \
+  --set replicaCount=1 \
+  --set cockroachdb.single-node=true \
+  --set cockroachdb.statefulset.replicas=1 \
+  --set zitadel.configmapConfig.FirstInstance.MachineKeyPath="/machinekey/zitadel-admin-sa.json" \
+  --set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Username="zitadel-admin-sa" \
+  --set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Name="Admin" \
+  --set zitadel.configmapConfig.FirstInstance.Org.Machine.MachineKey.Type=1
+```
+
+When helm is done, you get a command to retrieve your machine key, which is saved as a kubernetes secret, for example:
+```bash
+kubectl -n zitadel get secret zitadel-admin-sa -o jsonpath='{ .data.zitadel-admin-sa\.json }' | base64 -D
+```
+
+This key can be used to provision resources with for example [Terraform](../manage/terraform/basics.md).
+
 ### Forward the ZITADEL service port to your local machine
 
 ```bash
 kubectl port-forward svc/my-zitadel 8080:8080
 ```
 
-<DefaultUser components={props.components} />
 <Next components={props.components} />
 <Disclaimer components={props.components} />

docs/docs/guides/deploy/linux.mdx

@@ -41,5 +41,16 @@ ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeeds
 ## VideoGuide
 <iframe width="100%" height="315" src="https://www.youtube.com/embed/YVLua-q7dbs" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
+### Setup ZITADEL with a service account
+
+```bash
+ZITADEL_EXTERNALSECURE=false ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
+
+# then you can move your machine key
+mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json
+```
+
+This key can be used to provision resources with for example [Terraform](../manage/terraform/basics.md).
+
 <Next components={props.components} />
 <Disclaimer components={props.components} />

docs/docs/guides/deploy/macos.mdx

@@ -48,6 +48,16 @@ ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeeds
 ## VideoGuide
 <iframe width="100%" height="315" src="https://www.youtube.com/embed/Ob-kBzmezeg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
+### Setup ZITADEL with a service account
+
+```bash
+ZITADEL_EXTERNALSECURE=false ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
+
+# then you can move your machine key
+mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json
+```
+
+This key can be used to provision resources with for example [Terraform](../manage/terraform/basics.md).
 
 <Next components={props.components} />
 <Disclaimer components={props.components} />