Adjust docs

Author: bcb

docs/bluegreen.md

@@ -2,12 +2,12 @@ Blue/Green deployment runs two stacks side-by-side: one live, one idle. You
 deploy to the idle stack, test it, and when ready, swap roles — giving
 near-zero downtime and easy rollback.
 
-![Blue/Green](../assets/bluegreen.png)
+![Blue/Green](assets/bluegreen.png)
 
-## 1. Adjustments to the Compose file
+## 1. Adjust the Compose file
 
-Remove the exposed ports by removing the Caddy `ports:` section in
-`compose.yaml`.
+Remove the Caddy `ports:` section in `compose.yaml`. Instead of exposing ports
+in the stacks, a "front proxy" will expose ports and proxy to the active stack.
 
 Set `CADDY_SITE_ADDRESS` to only `:80` (leaving TLS termination to the front
 proxy):
@@ -31,8 +31,8 @@ volumes:
 
 ## 2. Add a Front Proxy
 
-The front proxy is a single container that binds `:80` and `:443` on the server
-and routes requests into either the Blue or Green stack.
+The _front proxy_ is a single container that binds ports `80` and `443` on the
+server and routes requests into either the Blue or Green stack.
 
 On the server, create a simple `Caddyfile`:
 
@@ -73,16 +73,33 @@ docker run -d \
   caddy:2
 ```
 
-## 4. Deploying
+## 3. Deploying/Upgrading
 
-Update the idle stack:
+Deploying is the same as [before](deploying.md), but now we're deploying the
+_idle stack_. For this example, `green` is idle so that's the one we're
+deploying.
+
+Create `blue` and `green` directories on the server and deploy `compose.yaml`
+into the idle stack's directory:
 
 ```sh
+scp compose.yaml youruser@yourserver:green/compose.yaml
+```
+
+Shell into the server and bring up the idle stack:
+
+```sh
+cd green
 docker compose pull
-docker compose -p green up -d
+docker compose up -d
 ```
 
-Edit the front proxy's config to flip traffic:
+Docker will use the directory name `green` as the project name, creating
+different containers, volumes and networks than the `blue` stack.
+
+### Flip traffic
+
+Point traffic to the `green` stack, and make `blue` idle:
 
 ```caddyfile title="Caddyfile"
 api.myapp.com {
@@ -94,12 +111,12 @@ next.myapp.com {
 }
 ```
 
-Restart Caddy:
+Reload the front proxy's config:
 
 ```sh
 docker exec front-proxy caddy reload
 ```
 
 Cutover is instant. Green is now live, and Blue is the idle stack.
 
-And rollback is simple: flip the `Caddyfile` back and `caddy reload`.
+And rollback is simple: flip the `Caddyfile` back and `caddy reload` again.

docs/deploying.md

@@ -16,12 +16,12 @@ Container Registry account), for example:
 caddy:
   build:
     context: ./caddy
-  image: ghcr.io/youruser/yourapp-caddy
+  image: ghcr.io/youruser/yourapp-caddy:0.1.0
 
 postgres:
   build:
     context: ./postgres
-  image: ghcr.io/youruser/yourapp-postgres
+  image: ghcr.io/youruser/yourapp-postgres:0.1.0
 ```
 
 ## 🛠️ 2. Build and Push your Images
@@ -35,30 +35,26 @@ docker compose push
 
 ## 📦 3. Deploy the Compose File
 
-Copy `compose.yaml` to your server:
+Copy `compose.yaml` to the server:
 
 ```sh
 scp compose.yaml youruser@yourserver:
 ```
 
 ## 🚀 4. Launch your Stack
 
-SSH into your server and bring up the stack.
+SSH into your server and bring up the stack:
 
-For production, avoid using `.env` files. Instead, set secrets directly:
-
-```sh title=".env"
-JWT_SECRET=your-secret \
-CADDY_PORT=80 \
-PG_USER=admin \
-PG_PASS=supersecret \
-POSTGREST_AUTHENTICATOR_PASS=supersecret \
+```sh
+docker compose pull
 docker compose up -d
 ```
 
-> 💡 Avoid leaking secrets by disabling shell history.
+Docker compose needs secrets, so you have a few options:
 
-Alternatively, use environment injection in your CI/CD.
+1. Write secrets to a `.env` file in plain-text (be sure to `chmod 600 .env`).
+1. Set env vars in the docker compose command
+1. Alternatively, use environment injection in your CI/CD.
 
 ---
 

docs/gettingstarted.md

@@ -64,9 +64,7 @@ This `.env` file is used to configure:
 - **Ports** – Adjust the exposed ports (specifically, Caddy's) depending on
   environment or application (you may bring up multiple).
 
-> ⚠️ The .env file is for development only. Never store real secrets in version
-> control or production. Use CI/CD environment variables or a secrets manager
-> instead.
+> ⚠️ Never store secrets in version control.
 
 ## 3. Start the Stack