docs: normalised versions and explained releases (#4119)

* docs: normalised versions and explained releases

* added downoad links

* fix: corrected tar flag for linux

Co-authored-by: Florian Forster <florian@caos.ch>

deploy/knative/zitadel-knative-service.yaml

@@ -7,7 +7,7 @@ spec:
   template:
     metadata:
       annotations:
-        client.knative.dev/user-image: ghcr.io/zitadel/zitadel:v2.0.0-amd64
+        client.knative.dev/user-image: ghcr.io/zitadel/zitadel:stable
       creationTimestamp: null
     spec:
       containerConcurrency: 0
@@ -28,7 +28,7 @@ spec:
           value: 80
         - name: ZITADEL_EXTERNALDOMAIN
           value: zitadel.default.127.0.0.1.sslip.io
-        image: ghcr.io/zitadel/zitadel:v2.0.0-amd64
+        image: ghcr.io/zitadel/zitadel:stable
         name: user-container
         ports:
         - containerPort: 8080

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

@@ -5,7 +5,7 @@ services:
     restart: 'always'
     networks:
       - 'zitadel'
-    image: 'ghcr.io/zitadel/zitadel:v2.0.0-amd64'
+    image: 'ghcr.io/zitadel/zitadel:stable'
     command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
     environment:
       - 'ZITADEL_DATABASE_COCKROACH_HOST=db'

docs/docs/guides/deploy/knative.mdx

@@ -24,7 +24,7 @@ kubectl apply -f https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/k
 
 ```bash
 kn service create zitadel \
---image ghcr.io/zitadel/zitadel:v2.0.0-amd64 \
+--image ghcr.io/zitadel/zitadel:stable \
 --port 8080 \
 --env ZITADEL_DATABASE_COCKROACH_HOST=cockroachdb \
 --env ZITADEL_EXTERNALSECURE=false \

docs/docs/guides/deploy/linux.mdx

@@ -19,8 +19,15 @@ cockroach start-single-node --insecure --background --http-addr :9090 --listen-a
 
 ## Install ZITADEL
 
+Download the ZITADEL release according to your architecture from [Github](https://github.com/zitadel/zitadel/releases/latest) 
+
+## Unpack the archive
+move to your download location and unpack the archive
+
 ```bash
-curl -s https://api.github.com/repos/zitadel/zitadel/releases/tags/v2.0.0 | grep "browser_download_url.*zitadel_Linux_$(uname -m).tar.gz" | cut -d '"' -f 4 | xargs wget -qO - | sudo tar --extract --gzip --overwrite --directory /usr/local/bin zitadel && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadel
+#unpack and copy to /usr/local/bin
+LATEST=$(curl -i https://github.com/zitadel/zitadel/releases/latest | grep location: | cut -d '/' -f 8 | tr -d '\r'); wget -qO-  https://github.com/zitadel/zitadel/releases/download/$LATEST/zitadel_Linux_$(uname -m).tar.gz  | tar -xz zitadel && sudo mv zitadel /usr/local/bin
+
 ```
 
 ## Run ZITADEL

docs/docs/guides/deploy/loadbalancing-example/docker-compose.yaml

@@ -15,7 +15,7 @@ services:
     restart: 'always'
     networks:
       - 'zitadel'
-    image: 'ghcr.io/zitadel/zitadel:v2.0.0-amd64'
+    image: 'ghcr.io/zitadel/zitadel:stable'
     command: 'start-from-init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml --steps /example-zitadel-init-steps.yaml --masterkey "${ZITADEL_MASTERKEY}" --tlsMode external'
     depends_on:
       chown:

docs/docs/guides/deploy/macos.mdx

@@ -27,9 +27,14 @@ brew install zitadel/tap/zitadel
 
 ### Download from GitHub
 
+Download the ZITADEL release according to your architecture from [Github](https://github.com/zitadel/zitadel/releases/latest)
+
+## Unpack the archive
+move to your download location and unpack the archive
+
 ```bash
-export MY_ARCHITECTURE="arm64 or amd64 depeding on your mac"
-curl -s https://api.github.com/repos/zitadel/zitadel/releases/tags/v2.0.0 | grep "browser_download_url.*zitadel_Darwin_${MY_ARCHITECTURE}.tar.gz" | cut -d '"' -f 4 | xargs wget -qO - | sudo tar --extract --gzip --overwrite --directory /usr/local/bin zitadel && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadel
+#unpack and copy to /usr/local/bin
+LATEST=$(curl -i https://github.com/zitadel/zitadel/releases/latest | grep location: | cut -d '/' -f 8 | tr -d '\r'); wget -qO-  https://github.com/zitadel/zitadel/releases/download/$LATEST/zitadel_Darwin_$(uname -m).tar.gz  | tar -xJ zitadel && sudo mv zitadel /usr/local/bin
 ```
 
 ## Run ZITADEL

docs/docs/guides/deploy/overview.mdx

@@ -17,3 +17,12 @@ By default, it runs a highly available ZITADEL instance along with a secure and
 - ZITADEL does not need many resources, 1 CPU and 512MB memory are more than enough. (With more CPU, the password hashing might be faster)
 - A cockroachDB or [🚧 Postgresql coming soon](https://github.com/zitadel/zitadel/pull/3998) as only needed storage
 - If you want to front ZITADEL with a reverse proxy, web application firewall or content delivery network, make sure to support [HTTP/2](../manage/self-hosted/http2)
+
+
+## Releases
+
+The easiest way to use ZITADEL is to run one of our container releases
+
+- ZITADEL does provide latest and stable [container images](https://github.com/zitadel/zitadel/pkgs/container/zitadel)
+- **stable** is the current **production** release of ZITADEL.
+- **latest** is the **last created** release from our pipelines that gets updated on a high frequency.

docs/docs/guides/manage/self-hosted/configure/docker-compose.yaml

@@ -6,7 +6,7 @@ services:
     restart: 'always'
     networks:
       - 'zitadel'
-    image: 'ghcr.io/zitadel/zitadel:v2.0.0-amd64'
+    image: 'ghcr.io/zitadel/zitadel:stable'
     command: 'start-from-init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml --steps /example-zitadel-init-steps.yaml --masterkey "${ZITADEL_MASTERKEY}" --tlsMode disabled'
     depends_on:
       chown: