Update site from docs source repo

Author: Exploding Labs Bot

superstack/bluegreen/index.html

@@ -76,7 +76,7 @@
     <div data-md-component="skip">
 
 
-        <a href="#1-adjustments-to-the-compose-file" class="md-skip">
+        <a href="#1-adjust-the-compose-file" class="md-skip">
           Skip to content
         </a>
 
@@ -444,9 +444,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 
         <li class="md-nav__item">
-  <a href="#1-adjustments-to-the-compose-file" class="md-nav__link">
+  <a href="#1-adjust-the-compose-file" class="md-nav__link">
     <span class="md-ellipsis">
-      1. Adjustments to the Compose file
+      1. Adjust the Compose file
     </span>
   </a>
 
@@ -462,12 +462,27 @@
 </li>
 
         <li class="md-nav__item">
-  <a href="#4-deploying" class="md-nav__link">
+  <a href="#3-deployingupgrading" class="md-nav__link">
     <span class="md-ellipsis">
-      4. Deploying
+      3. Deploying/Upgrading
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="3. Deploying/Upgrading">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#flip-traffic" class="md-nav__link">
+    <span class="md-ellipsis">
+      Flip traffic
     </span>
   </a>
 
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
     </ul>
@@ -525,9 +540,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 
         <li class="md-nav__item">
-  <a href="#1-adjustments-to-the-compose-file" class="md-nav__link">
+  <a href="#1-adjust-the-compose-file" class="md-nav__link">
     <span class="md-ellipsis">
-      1. Adjustments to the Compose file
+      1. Adjust the Compose file
     </span>
   </a>
 
@@ -543,12 +558,27 @@
 </li>
 
         <li class="md-nav__item">
-  <a href="#4-deploying" class="md-nav__link">
+  <a href="#3-deployingupgrading" class="md-nav__link">
     <span class="md-ellipsis">
-      4. Deploying
+      3. Deploying/Upgrading
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="3. Deploying/Upgrading">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#flip-traffic" class="md-nav__link">
+    <span class="md-ellipsis">
+      Flip traffic
     </span>
   </a>
 
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
     </ul>
@@ -576,9 +606,9 @@ <h1>Blue/Green Deployments</h1>
 deploy to the idle stack, test it, and when ready, swap roles — giving
 near-zero downtime and easy rollback.</p>
 <p><img alt="Blue/Green" src="../assets/bluegreen.png" /></p>
-<h2 id="1-adjustments-to-the-compose-file">1. Adjustments to the Compose file</h2>
-<p>Remove the exposed ports by removing the Caddy <code>ports:</code> section in
-<code>compose.yaml</code>.</p>
+<h2 id="1-adjust-the-compose-file">1. Adjust the Compose file</h2>
+<p>Remove the Caddy <code>ports:</code> section in <code>compose.yaml</code>. Instead of exposing ports
+in the stacks, a "front proxy" will expose ports and proxy to the active stack.</p>
 <p>Set <code>CADDY_SITE_ADDRESS</code> to only <code>:80</code> (leaving TLS termination to the front
 proxy):</p>
 <div class="highlight"><span class="filename">compose.yaml</span><pre><span></span><code><span class="nt">caddy</span><span class="p">:</span>
@@ -594,8 +624,8 @@ <h2 id="1-adjustments-to-the-compose-file">1. Adjustments to the Compose file</h
 <span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">user-data</span>
 </code></pre></div>
 <h2 id="2-add-a-front-proxy">2. Add a Front Proxy</h2>
-<p>The front proxy is a single container that binds <code>:80</code> and <code>:443</code> on the server
-and routes requests into either the Blue or Green stack.</p>
+<p>The <em>front proxy</em> is a single container that binds ports <code>80</code> and <code>443</code> on the
+server and routes requests into either the Blue or Green stack.</p>
 <p>On the server, create a simple <code>Caddyfile</code>:</p>
 <div class="highlight"><span class="filename">Caddyfile</span><pre><span></span><code>api.myapp.com {
   reverse_proxy blue_caddy:80
@@ -623,12 +653,23 @@ <h2 id="2-add-a-front-proxy">2. Add a Front Proxy</h2>
 <span class="w">  </span>--network<span class="w"> </span>green_default<span class="w"> </span><span class="se">\</span>
 <span class="w">  </span>caddy:2
 </code></pre></div>
-<h2 id="4-deploying">4. Deploying</h2>
-<p>Update the idle stack:</p>
-<div class="highlight"><pre><span></span><code>docker<span class="w"> </span>compose<span class="w"> </span>pull
-docker<span class="w"> </span>compose<span class="w"> </span>-p<span class="w"> </span>green<span class="w"> </span>up<span class="w"> </span>-d
+<h2 id="3-deployingupgrading">3. Deploying/Upgrading</h2>
+<p>Deploying is the same as <a href="../deploying/">before</a>, but now we're deploying the
+<em>idle stack</em>. For this example, <code>green</code> is idle so that's the one we're
+deploying.</p>
+<p>Create <code>blue</code> and <code>green</code> directories on the server and deploy <code>compose.yaml</code>
+into the idle stack's directory:</p>
+<div class="highlight"><pre><span></span><code>scp<span class="w"> </span>compose.yaml<span class="w"> </span>youruser@yourserver:green/compose.yaml
+</code></pre></div>
+<p>Shell into the server and bring up the idle stack:</p>
+<div class="highlight"><pre><span></span><code><span class="nb">cd</span><span class="w"> </span>green
+docker<span class="w"> </span>compose<span class="w"> </span>pull
+docker<span class="w"> </span>compose<span class="w"> </span>up<span class="w"> </span>-d
 </code></pre></div>
-<p>Edit the front proxy's config to flip traffic:</p>
+<p>Docker will use the directory name <code>green</code> as the project name, creating
+different containers, volumes and networks than the <code>blue</code> stack.</p>
+<h3 id="flip-traffic">Flip traffic</h3>
+<p>Point traffic to the <code>green</code> stack, and make <code>blue</code> idle:</p>
 <div class="highlight"><span class="filename">Caddyfile</span><pre><span></span><code>api.myapp.com {
   reverse_proxy green_caddy:80
 }
@@ -637,11 +678,11 @@ <h2 id="4-deploying">4. Deploying</h2>
   reverse_proxy blue_caddy:80
 }
 </code></pre></div>
-<p>Restart Caddy:</p>
+<p>Reload the front proxy's config:</p>
 <div class="highlight"><pre><span></span><code>docker<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>front-proxy<span class="w"> </span>caddy<span class="w"> </span>reload
 </code></pre></div>
 <p>Cutover is instant. Green is now live, and Blue is the idle stack.</p>
-<p>And rollback is simple: flip the <code>Caddyfile</code> back and <code>caddy reload</code>.</p>
+<p>And rollback is simple: flip the <code>Caddyfile</code> back and <code>caddy reload</code> again.</p>
 
 
 

superstack/deploying/index.html

@@ -606,36 +606,33 @@ <h2 id="1-prepare-your-images">✅ 1. Prepare your Images</h2>
 <div class="highlight"><span class="filename">compose.yaml</span><pre><span></span><code><span class="nt">caddy</span><span class="p">:</span>
 <span class="w">  </span><span class="nt">build</span><span class="p">:</span>
 <span class="w">    </span><span class="nt">context</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">./caddy</span>
-<span class="w">  </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ghcr.io/youruser/yourapp-caddy</span>
+<span class="w">  </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ghcr.io/youruser/yourapp-caddy:0.1.0</span>
 
 <span class="nt">postgres</span><span class="p">:</span>
 <span class="w">  </span><span class="nt">build</span><span class="p">:</span>
 <span class="w">    </span><span class="nt">context</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">./postgres</span>
-<span class="w">  </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ghcr.io/youruser/yourapp-postgres</span>
+<span class="w">  </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ghcr.io/youruser/yourapp-postgres:0.1.0</span>
 </code></pre></div>
 <h2 id="2-build-and-push-your-images">🛠️ 2. Build and Push your Images</h2>
 <p>Build your images locally and push to your registry:</p>
 <div class="highlight"><pre><span></span><code>docker<span class="w"> </span>compose<span class="w"> </span>build
 docker<span class="w"> </span>compose<span class="w"> </span>push
 </code></pre></div>
 <h2 id="3-deploy-the-compose-file">📦 3. Deploy the Compose File</h2>
-<p>Copy <code>compose.yaml</code> to your server:</p>
+<p>Copy <code>compose.yaml</code> to the server:</p>
 <div class="highlight"><pre><span></span><code>scp<span class="w"> </span>compose.yaml<span class="w"> </span>youruser@yourserver:
 </code></pre></div>
 <h2 id="4-launch-your-stack">🚀 4. Launch your Stack</h2>
-<p>SSH into your server and bring up the stack.</p>
-<p>For production, avoid using <code>.env</code> files. Instead, set secrets directly:</p>
-<div class="highlight"><span class="filename">.env</span><pre><span></span><code><span class="nv">JWT_SECRET</span><span class="o">=</span>your-secret<span class="w"> </span><span class="se">\</span>
-<span class="nv">CADDY_PORT</span><span class="o">=</span><span class="m">80</span><span class="w"> </span><span class="se">\</span>
-<span class="nv">PG_USER</span><span class="o">=</span>admin<span class="w"> </span><span class="se">\</span>
-<span class="nv">PG_PASS</span><span class="o">=</span>supersecret<span class="w"> </span><span class="se">\</span>
-<span class="nv">POSTGREST_AUTHENTICATOR_PASS</span><span class="o">=</span>supersecret<span class="w"> </span><span class="se">\</span>
+<p>SSH into your server and bring up the stack:</p>
+<div class="highlight"><pre><span></span><code>docker<span class="w"> </span>compose<span class="w"> </span>pull
 docker<span class="w"> </span>compose<span class="w"> </span>up<span class="w"> </span>-d
 </code></pre></div>
-<blockquote>
-<p>💡 Avoid leaking secrets by disabling shell history.</p>
-</blockquote>
-<p>Alternatively, use environment injection in your CI/CD.</p>
+<p>Docker compose needs secrets, so you have a few options:</p>
+<ol>
+<li>Write secrets to a <code>.env</code> file in plain-text (be sure to <code>chmod 600 .env</code>).</li>
+<li>Set env vars in the docker compose command</li>
+<li>Alternatively, use environment injection in your CI/CD.</li>
+</ol>
 <hr />
 <p>That’s it — your backend is live.</p>
 <p>If this is the first time bringing up your stack, the migrations will run

superstack/gettingstarted/index.html

@@ -705,9 +705,7 @@ <h2 id="2-configure-environment-variables">2. Configure Environment Variables</h
   environment or application (you may bring up multiple).</li>
 </ul>
 <blockquote>
-<p>⚠️ 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.</p>
+<p>⚠️ Never store secrets in version control.</p>
 </blockquote>
 <h2 id="3-start-the-stack">3. Start the Stack</h2>
 <div class="highlight"><pre><span></span><code>docker<span class="w"> </span>compose<span class="w"> </span>up<span class="w"> </span>-d