Adjust advanced doc

Author: bcb

docs/advanced.md

@@ -1,52 +1,46 @@
-A new `proxy` service is added to direct traffic.
+The standard SuperStack replaces the stack in place.
 
-```
-proxy/
-  compose.yaml
-app/
-  ...
-```
+- There's some downtime while upgrading.
+- You can't test one app while another is live (blue/green)
+- Once an app is upgrade, you can't rollback.
 
-## 1. Update Application
+Once your app is ready for production, consider adding a traffic-switcher in
+front of your app.
 
-Remove the exposed ports, and connect to the proxy's network:
+How it works:
 
-```yaml title="app/compose.yaml" hl_lines="6-13,15-17"
-services:
-  caddy:
-    build:
-      context: ./caddy
-    environment:
-      CADDY_SITE_ADDRESS: ":80"
-    networks:
-      default:
-      # This alias allows the proxy to target this container, while still
-      # allowing Docker to manage the container name
-      proxy_default:
-        aliases:
-          - ${COMPOSE_PROJECT_NAME}_caddy
+- We stop exposing ports in the `app` project.
+- A new `proxy` project is added, with ports open.
+- It's purpose is to direct traffic to the right application.
+- Apps are deployed completely separate to the live one.
+
+This way, environments are _ephemeral, immutable and idempotent_.
+
+The directory structure looks like:
 
-networks:
-  proxy_default:
-    external: true
+```
+proxy/
+  compose.yaml
+app/
+  a/
+    compose.yaml
+    .env
+  b/
+    compose.yaml
+    .env
 ```
 
-**app/compose.override.yaml**
+## 1. Create a new project
 
-```yaml
-# Development overrides
+From the root of the repository, create a new `proxy` project:
 
-services:
-  caddy:
-    volumes:
-      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
+```sh
+mkdir proxy
 ```
 
-## 1. Add a traffic-switcher proxy service
-
-**proxy/compose.yaml**
+Add a compose file:
 
-```yaml
+```yaml title="proxy/compose.yaml"
 services:
   caddy:
     build:
@@ -61,12 +55,10 @@ services:
 
 volumes:
   caddy_data:
-    name: caddy-data
+    name: caddy-data # The proxy manages TLS, so give it a persistent volume for certificates
 ```
 
-**proxy/compose.override.yaml**
-
-```yaml
+```yaml title="proxy/compose.override.yaml"
 # Development overrides
 
 services:
@@ -77,32 +69,48 @@ services:
       CADDY_SITE_ADDRESS: :80
 ```
 
-**proxy/caddy/Caddyfile**
-
-```yaml
+```yaml title="proxy/caddy/Caddyfile"
 {$CADDY_SITE_ADDRESS}
 
 reverse_proxy app_caddy:80
 ```
 
-## Deploying
+## 2. Update the Application
 
-The proxy is deployed manually, and app infra files are created in a new
-directory every time.
+Remove the app's exposed ports, and connect to the proxy's network:
 
+```yaml title="app/compose.yaml" hl_lines="6-13,15-17"
+services:
+  caddy:
+    build:
+      context: ./caddy
+    environment:
+      CADDY_SITE_ADDRESS: ":80"
+    networks:
+      default:
+      # This alias allows the proxy to target this container, while still
+      # allowing Docker to manage the container name
+      proxy_default:
+        aliases:
+          - ${COMPOSE_PROJECT_NAME}_caddy
+
+networks:
+  proxy_default:
+    external: true
 ```
-proxy/
-  compose.yaml
-app/
-  a/
-    compose.yaml
-    .env
-  b/
-    compose.yaml
-    .env
+
+```yaml title="app/compose.override.yaml"
+# Development overrides
+
+services:
+  caddy:
+    volumes:
+      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
 ```
 
-the Proxy (Manual Step)
+## Deploy the Proxy
+
+The proxy is only deployed once.
 
 On the server, create a proxy directory:
 
@@ -116,16 +124,9 @@ Back on local, copy your Compose file to the server:
 scp proxy/compose.yaml app-backend:proxy/
 ```
 
-> Optionally, you might point a second hostname to an idle stack for testing.
+> You might also point a second hostname to an idle stack for testing.
 
-The proxy manages TLS, so give it a persistent volume for certificates:
-
-```sh
-docker volume create caddy_data
-```
-
-Start the proxy, attaching it to both networks – this requires both stacks to
-be up first, so the networks exist:
+## Deploy the app
 
 ```sh
 docker compose up -d
@@ -141,9 +142,7 @@ docker compose exec caddy curl -X PATCH -d '"newapp_caddy:80"' \
 
 ## Github Actions Workflow
 
-**.github/workflows/ci.yaml**
-
-```yaml
+```yaml title=".github/workflows/ci.yaml"
 name: Deploy
 
 on:

docs/deploy.md

@@ -31,17 +31,17 @@ Copy your `compose.yaml` to the remote host:
 scp compose.yaml youruser@yourserver:
 ```
 
-### 3. Set Secrets
+## 3. Set Secrets
 
 Your app will need credentials such as database passwords or API keys. Choose
 one of these approaches:
 
 1. **`.env` file** — simply place a `.env` file alongside your `compose.yaml`.
    Be sure to `chmod 600 .env`.
-2. **Environment variables** — pass them directly to the command line.
+2. **Environment variables** — pass secrets directly to the command line.
 3. **CI/CD injection** — good for automated pipelines.
 
-## 🚀 Launch the App
+## 🚀 3. Launch the App
 
 Start the application on the server:
 
@@ -56,7 +56,5 @@ Your backend is now live. 🚀
 
 ## 🧭 Next Steps
 
-This setup replaces the stack in place.
-
 If you want zero-downtime deployments, rollback support, or blue-green testing,
-continue reading to [Advanced Deployments](advanced.md).
+continue to [Advanced Deployments](advanced.md).