From ae42574b276ca6fb520dc11fb00d27236e489f28 Mon Sep 17 00:00:00 2001
From: Georg Friedrich <georg@codezero.io>
Date: Fri, 26 Apr 2024 12:05:06 +1000
Subject: [PATCH] feat: add simple Compose tutorial

---
 docs/guides/compose.md       | 67 ++++++++++++++++++++++++++++++++++++
 docs/guides/vpn.mdx          |  2 +-
 docs/references/changelog.md |  2 +-
 3 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 docs/guides/compose.md

diff --git a/docs/guides/compose.md b/docs/guides/compose.md
new file mode 100644
index 0000000..a9255c9
--- /dev/null
+++ b/docs/guides/compose.md
@@ -0,0 +1,67 @@
+---
+sidebar_position: 6
+---
+
+# Codezero Compose
+
+Codezero Compose is a way to define your Consume and Serve sessions in a `codezero-compose.yaml` file which can be checked into your project repository.
+
+If you have a `codezero-compose.yaml` or `codezero-compose.yml` file in your current directory, you can start your sessions with the following command:
+
+```sh
+czctl compose start
+```
+
+## The Compose File
+
+The following `codezero-compose.yaml` file will set the primary namespace to `sample-project`, consume all services within that namespace except the `sample-project-core` service and serve a user variant of the `sample-project-core` service.
+
+```yaml
+version: "1.0"
+consume:
+  primaryNamespace: sample-project
+  rules:
+    - sample-project/*
+    - '!sample-project/sample-project-core'
+serve:
+  - namespace: sample-project
+    service: sample-project-core
+    ports:
+      - local: 3000
+        remote: 3000
+```
+
+## Templating
+
+A template directive is enclosed in `{{` and `}}` blocks.
+Your local environment variables are exposed in the `Env` template object.
+The following example shows how you can use the `USER` environment variable as a custom header value.
+
+```yaml
+version: "1.0"
+consume:
+  primaryNamespace: sample-project
+  rules:
+    - sample-project/*
+    - '!sample-project/sample-project-core'
+serve:
+  - namespace: sample-project
+    service: sample-project-core
+    ports:
+      - local: 3000
+        remote: 3000
+    condition:
+      type: 'header'
+      key: 'X-Custom-Header'
+      value: 'user-{{ .Env.USER }}'
+```
+
+In the above example, if the `USER` environment variable would be set to `joe`, any traffic to the `sample-project-core` service where the HTTP header `X-Custom-Header` is set to `user-joe` would be directed to your local machine.
+
+## Stopping all Consume and Serve sessions
+
+To stop all Consume and Serve sessions simply run the following command:
+
+```sh
+czctl reset
+```
diff --git a/docs/guides/vpn.mdx b/docs/guides/vpn.mdx
index 8fc1290..405f0d6 100644
--- a/docs/guides/vpn.mdx
+++ b/docs/guides/vpn.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Coexisting with VPNs
diff --git a/docs/references/changelog.md b/docs/references/changelog.md
index 05963a4..8eef79c 100644
--- a/docs/references/changelog.md
+++ b/docs/references/changelog.md
@@ -36,7 +36,7 @@ To update your Codezero Space Agent, follow these steps:
 
 ### Features
 
-* New command: `czctl compose start` to start consume and serve sessions based on rules in `codezero-compose.yml`.
+* New command: `czctl compose start` to start consume and serve sessions based on rules in `codezero-compose.yml`. You can read about this new feature in the [Codezero Compose](../guides/compose) guide.
 
 ## 2.1.1