Upgrade docker-compose.yml to use postgres 16, add upgrade instructions

docker/README.md

@@ -86,6 +86,31 @@ For example, in NGINX you can use the `$scheme` variable like so:
 proxy_set_header X-Forwarded-Proto $scheme;
 ```
 
+## Upgrading Database
+
+When you upgrade the database version in `docker-compose.yml` (for example,
+from `postgres:12` to `postgres:16`), you will also need to upgrade your postgres
+data directory. One way to do this is using the
+[pgautoupgrade](https://hub.docker.com/r/pgautoupgrade/pgautoupgrade) container.
+
+Steps:
+
+* As the very first step, **take a full backup of your database**.
+* Stop the `db` and `web` containers: `docker compose stop`
+* Look up the name of the postgres data volume name using `docker volume ls`
+* Run `pgautoupgrade` like so:
+
+```
+docker run --rm --name pgauto -it \
+   --mount type=volume,source=<pg-volume-name-here>,target=/var/lib/postgresql/data \
+   -e POSTGRES_PASSWORD=password \
+   -e PGAUTO_ONESHOT=yes \
+   pgautoupgrade/pgautoupgrade:16-bookworm
+```
+
+* Update the `docker-compose.yml` file to use the `postgres:16` image
+* Start containers: `docker compose up`
+
 ## Pre-built Images
 
 Pre-built Docker images, built from the Dockerfile in this directory, are available

docker/docker-compose.yml

@@ -1,10 +1,9 @@
-version: "3"
 volumes:
     db-data:
 
 services:
   db:
-    image: postgres:12
+    image: postgres:16
     volumes:
       - db-data:/var/lib/postgresql/data
     environment:

templates/docs/self_hosted_docker.html-fragment

@@ -85,6 +85,29 @@ reverse proxy:</p>
 <div class="highlight"><pre><span></span><code>proxy_set_header X-Forwarded-Proto $scheme;
 </code></pre></div>
 
+<h2>Upgrading Database</h2>
+<p>When you upgrade the database version in <code>docker-compose.yml</code> (for example,
+from <code>postgres:12</code> to <code>postgres:16</code>), you will also need to upgrade your postgres
+data directory. One way to do this is using the
+<a href="https://hub.docker.com/r/pgautoupgrade/pgautoupgrade">pgautoupgrade</a> container.</p>
+<p>Steps:</p>
+<ul>
+<li>As the very first step, <strong>take a full backup of your database</strong>.</li>
+<li>Stop the <code>db</code> and <code>web</code> containers: <code>docker compose stop</code></li>
+<li>Look up the name of the postgres data volume name using <code>docker volume ls</code></li>
+<li>Run <code>pgautoupgrade</code> like so:</li>
+</ul>
+<div class="highlight"><pre><span></span><code><span class="n">docker</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="o">--</span><span class="n">rm</span><span class="w"> </span><span class="o">--</span><span class="n">name</span><span class="w"> </span><span class="n">pgauto</span><span class="w"> </span><span class="o">-</span><span class="n">it</span><span class="w"> </span>\
+<span class="w">   </span><span class="o">--</span><span class="n">mount</span><span class="w"> </span><span class="n">type</span><span class="o">=</span><span class="n">volume</span><span class="p">,</span><span class="n">source</span><span class="o">=&lt;</span><span class="n">pg</span><span class="o">-</span><span class="n">volume</span><span class="o">-</span><span class="n">name</span><span class="o">-</span><span class="n">here</span><span class="o">&gt;</span><span class="p">,</span><span class="n">target</span><span class="o">=/</span><span class="k">var</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">postgresql</span><span class="o">/</span><span class="n">data</span><span class="w"> </span>\
+<span class="w">   </span><span class="o">-</span><span class="n">e</span><span class="w"> </span><span class="n">POSTGRES_PASSWORD</span><span class="o">=</span><span class="n">password</span><span class="w"> </span>\
+<span class="w">   </span><span class="o">-</span><span class="n">e</span><span class="w"> </span><span class="n">PGAUTO_ONESHOT</span><span class="o">=</span><span class="n">yes</span><span class="w"> </span>\
+<span class="w">   </span><span class="n">pgautoupgrade</span><span class="o">/</span><span class="n">pgautoupgrade</span><span class="p">:</span><span class="mi">16</span><span class="o">-</span><span class="n">bookworm</span>
+</code></pre></div>
+
+<ul>
+<li>Update the <code>docker-compose.yml</code> file to use the <code>postgres:16</code> image</li>
+<li>Start containers: <code>docker compose up</code></li>
+</ul>
 <h2>Pre-built Images</h2>
 <p>Pre-built Docker images, built from the Dockerfile in the <code>/docker/</code> directory,
 are available <a href="https://hub.docker.com/r/healthchecks/healthchecks">on Docker Hub</a>.

templates/docs/self_hosted_docker.md

@@ -89,6 +89,31 @@ For example, in NGINX you can use the `$scheme` variable like so:
 proxy_set_header X-Forwarded-Proto $scheme;
 ```
 
+## Upgrading Database
+
+When you upgrade the database version in `docker-compose.yml` (for example,
+from `postgres:12` to `postgres:16`), you will also need to upgrade your postgres
+data directory. One way to do this is using the
+[pgautoupgrade](https://hub.docker.com/r/pgautoupgrade/pgautoupgrade) container.
+
+Steps:
+
+* As the very first step, **take a full backup of your database**.
+* Stop the `db` and `web` containers: `docker compose stop`
+* Look up the name of the postgres data volume name using `docker volume ls`
+* Run `pgautoupgrade` like so:
+
+```
+docker run --rm --name pgauto -it \
+   --mount type=volume,source=<pg-volume-name-here>,target=/var/lib/postgresql/data \
+   -e POSTGRES_PASSWORD=password \
+   -e PGAUTO_ONESHOT=yes \
+   pgautoupgrade/pgautoupgrade:16-bookworm
+```
+
+* Update the `docker-compose.yml` file to use the `postgres:16` image
+* Start containers: `docker compose up`
+
 ## Pre-built Images
 
 Pre-built Docker images, built from the Dockerfile in the `/docker/` directory,