(WIP) Major v16 tutorial edits (#1040)

a-velasco · web-flow · commit 4d5e9a51b713 · 2025-07-25T20:24:35.000+02:00
* feat: add rediraffe sphinx extension and discourse redirects for each page

* fix broken urls and update custom wordlist

* fix spelling errors

* polish explanation landing page and toctree

* Updated tutorial content and outputs for v16

* Added related link to Charmhub

* Added small clarification to password management guide

* Replace mentions of 16/edge with 16/stable

* fix styling issues with juju status outputs

* misc. small fixes

* updated data-integrator section

* update 14/stable status outputs to avoid confusion

* apply review comments
diff --git a/docs/explanation/interfaces-and-endpoints.md b/docs/explanation/interfaces-and-endpoints.md
@@ -16,7 +16,7 @@ Adding a relation is accomplished with `juju relate` (or `juju integrate` for Ju
 
 ```text
 # Deploy Charmed PostgreSQL cluster with 3 nodes
-juju deploy postgresql -n 3 --channel 16/edge
+juju deploy postgresql -n 3 --channel 16/stable
 
 # Deploy the relevant application charms
 juju deploy mycharm
diff --git a/docs/explanation/units.md b/docs/explanation/units.md
@@ -13,7 +13,7 @@ It is recommended to use 3+ units cluster size in production (due to [Raft conse
 
 All SQL transactions have to be confirmed by all Sync Standby unit(s) before Primary unit commit transaction to the client. Therefore, high-performance and high-availability is a trade-off between "sync standby" and "replica" unit count in the cluster.
 
-Starting from revision 561, all Charmed PostgreSQL units are configured as Sync Standby members by default. It provides better guarantees for the data survival when two of three units gone simultaneously. Users can re-configure the necessary synchronous units count using Juju config option '[synchronous_node_count](https://charmhub.io/postgresql/configurations?channel=16/edge)'.
+Starting from revision 561, all Charmed PostgreSQL units are configured as Sync Standby members by default. It provides better guarantees for the data survival when two of three units gone simultaneously. Users can re-configure the necessary synchronous units count using Juju config option '[synchronous_node_count](https://charmhub.io/postgresql/configurations?channel=16/stable)'.
 
 ## Primary
 
@@ -26,7 +26,7 @@ Model       Controller  Cloud/Region         Version  SLA          Timestamp
 postgresql  lxd         localhost/localhost  3.6.5    unsupported  13:04:15+02:00
 
 App         Version  Status  Scale  Charm       Channel    Rev  Exposed  Message
-postgresql  14.15    active      3  postgresql  14/stable  553  no       
+postgresql  16.9     active      3  postgresql  16/stable  843  no       
 
 Unit           Workload  Agent  Machine  Public address  Ports     Message
 postgresql/0*  active    idle   0        10.189.210.53   5432/tcp  Primary <<<<<<<<<<<<<<
diff --git a/docs/how-to/deploy/aws-ec2.md b/docs/how-to/deploy/aws-ec2.md
@@ -129,7 +129,7 @@ welcome  aws-us-east-1  aws/us-east-1  3.5.4    unsupported  13:33:05+02:00
 
 App              Version  Status  Scale  Charm            Channel        Rev  Exposed  Message
 data-integrator           active      1  data-integrator  latest/stable   41  no       
-postgresql       14.12    active      1  postgresql       14/stable      468  no       
+postgresql       16.9     active      1  postgresql       16/stable      843  no       
 
 Unit                Workload  Agent  Machine  Public address  Ports     Message
 data-integrator/0*  active    idle   1        50.19.16.57               
diff --git a/docs/how-to/deploy/azure.md b/docs/how-to/deploy/azure.md
@@ -182,7 +182,7 @@ welcome  azure       azure/centralus  3.6-rc1.1  unsupported  12:56:16+02:00
 
 App              Version  Status  Scale  Charm            Channel        Rev  Exposed  Message
 data-integrator           active      1  data-integrator  latest/stable   41  no       
-postgresql       14.12    active      1  postgresql       14/stable      468  no       
+postgresql       16.9     active      1  postgresql       16/stable      843  no       
 
 Unit                Workload  Agent  Machine  Public address  Ports     Message
 data-integrator/0*  active    idle   1        172.170.35.131            
@@ -256,7 +256,7 @@ welcome  azure       azure/centralus  3.6-rc1.1  unsupported  13:11:26+02:00
 
 App              Version  Status  Scale  Charm            Channel        Rev  Exposed  Message
 data-integrator           active      1  data-integrator  latest/stable   41  no       
-postgresql       14.12    active      1  postgresql       14/stable      468  yes       
+postgresql       16.9     active      1  postgresql       16/stable      843  yes       
 
 Unit                Workload  Agent  Machine  Public address  Ports     Message
 data-integrator/0*  active    idle   1        172.170.35.131            
diff --git a/docs/how-to/deploy/gce.md b/docs/how-to/deploy/gce.md
@@ -142,7 +142,7 @@ welcome  gce         google/us-east1  3.5.4    unsupported  23:24:05+02:00
 
 App              Version  Status  Scale  Charm            Channel        Rev  Exposed  Message
 data-integrator           active      1  data-integrator  latest/stable   41  no       
-postgresql       14.12    active      1  postgresql       14/stable      468  no       
+postgresql       16.9     active      1  postgresql       16/stable      843  no       
 
 Unit                Workload  Agent  Machine  Public address  Ports     Message
 data-integrator/0*  active    idle   1        34.73.238.173             
diff --git a/docs/how-to/deploy/juju-spaces.md b/docs/how-to/deploy/juju-spaces.md
@@ -27,7 +27,7 @@ peers     2         10.10.10.0/24
 
 The space `alpha` is default and cannot be removed. To deploy Charmed PostgreSQL Operator using the spaces:
 ```text
-juju deploy postgresql --channel 16/edge \
+juju deploy postgresql --channel 16/stable \
   --constraints spaces=client,peers \
   --bind "database-peers=peers database=client"
 ```
diff --git a/docs/how-to/deploy/juju-storage.md b/docs/how-to/deploy/juju-storage.md
@@ -2,7 +2,7 @@
 
 Charmed PostgreSQL uses the [Juju storage](https://documentation.ubuntu.com/juju/3.6/reference/storage/) abstraction to utilise data volume provided by different [clouds](https://documentation.ubuntu.com/juju/3.6/reference/cloud/#cloud) while keeping the same UI/UX for end users.
 
-[Charmed PostgreSQL 16](https://charmhub.io/postgresql?channel=16/edge) supports multiple storage types: `archive`, `data`, `logs` and `temp`.
+[Charmed PostgreSQL 16](https://charmhub.io/postgresql?channel=16/stable) supports multiple storage types: `archive`, `data`, `logs` and `temp`.
 
 The [legacy PostgreSQL charm](/explanation/legacy-charm) in track [`latest`](https://charmhub.io/postgresql?channel=latest/stable)" does **not** support the Juju storage abstraction.
 
@@ -83,7 +83,7 @@ Charmed PostgreSQL 16 uses Juju user secrets to handle credentials:
 
 # Re-deploy new app re-using old storage and old credentials
 > juju deploy postgresql \
-  --channel 16/edge \
+  --channel 16/stable \
   --attach-storage pgdata/5 \
   --config system-users=newsecret54321id
 
@@ -99,8 +99,8 @@ Prepare the test data to restore later:
 > juju add-model teststorage
 
 # Deploy the new postgresql to dump storage with credentials
-> juju deploy postgresql --channel 16/edge --storage pgdata=5Gcompleted
-Deployed "postgresql" from charm-hub charm "postgresql", revision 613 in channel 16/edge on ubuntu@24.04/stable
+> juju deploy postgresql --channel 16/stable --storage pgdata=5Gcompleted
+Deployed "postgresql" from charm-hub charm "postgresql", revision 613 in channel 16/stable on ubuntu@24.04/stable
 
 # Wait for deployment completed:
 > juju status
@@ -177,10 +177,10 @@ secret:d09vcn1oie738j7af4ng
 
 # Re-deploy app with old storage and old passwords
 > juju deploy postgresql \
-  --channel 16/edge \
+  --channel 16/stable \
   --attach-storage pgdata/0 \
   --config system-users=d09vcn1oie738j7af4ng
-Deployed "postgresql" from charm-hub charm "postgresql", revision 613 in channel 16/edge on ubuntu@24.04/stable
+Deployed "postgresql" from charm-hub charm "postgresql", revision 613 in channel 16/stable on ubuntu@24.04/stable
 
 # Grant new application access to manually created Juju User secret
 > juju grant-secret mypgpass postgresql
diff --git a/docs/how-to/deploy/maas.md b/docs/how-to/deploy/maas.md
@@ -121,7 +121,7 @@ Model       Controller       Cloud/Region        Version  SLA          Timestamp
 postgresql  maas-controller  maas-cloud/default  3.1.8    unsupported  12:50:26+02:00
 
 App         Version  Status  Scale  Charm       Channel    Rev  Exposed  Message
-postgresql  14.10    active      1  postgresql  14/stable  363  no       Primary
+postgresql  16.9     active      1  postgresql  16/stable  843  no       Primary
 
 Unit           Workload  Agent  Machine  Public address  Ports     Message
 postgresql/0*  active    idle   0        10.10.10.5      5432/tcp  Primary
diff --git a/docs/how-to/deploy/multi-az.md b/docs/how-to/deploy/multi-az.md
@@ -48,7 +48,7 @@ Model    Controller  Cloud/Region     Version    SLA          Timestamp
 mymodel  gce         google/us-east1  3.5.4      unsupported  00:16:52+02:00
 
 App         Version  Status  Scale  Charm       Channel    Rev  Exposed  Message
-postgresql  14.12    active      3  postgresql  14/stable  468  no       
+postgresql  16.9     active      3  postgresql  16/stable  843  no       
 
 Unit           Workload  Agent  Machine  Public address  Ports     Message
 postgresql/0   active    idle   0        34.148.44.51    5432/tcp  
@@ -93,7 +93,7 @@ Model    Controller  Cloud/Region     Version    SLA          Timestamp
 mymodel  gce         google/us-east1  3.5.4      unsupported  00:25:14+02:00
 
 App         Version  Status  Scale  Charm       Channel    Rev  Exposed  Message
-postgresql  14.12    active    2/3  postgresql  14/stable  468  no       
+postgresql  16.9     active    2/3  postgresql  16/stable  843  no       
 
 Unit           Workload  Agent  Machine  Public address  Ports     Message
 postgresql/0   active    idle   0        34.148.44.51    5432/tcp  
@@ -122,7 +122,7 @@ Model    Controller  Cloud/Region     Version    SLA          Timestamp
 mymodel  gce         google/us-east1  3.5.4      unsupported  00:30:09+02:00
 
 App         Version  Status  Scale  Charm       Channel    Rev  Exposed  Message
-postgresql  14.12    active      2  postgresql  14/stable  468  no       
+postgresql  16.9     active      2  postgresql  16/stable  843  no       
 
 Unit           Workload  Agent  Machine  Public address  Ports     Message
 postgresql/0   active    idle   0        34.148.44.51    5432/tcp  
@@ -144,7 +144,7 @@ Model    Controller  Cloud/Region     Version    SLA          Timestamp
 mymodel  gce         google/us-east1  3.5.4      unsupported  00:30:42+02:00
 
 App         Version  Status  Scale  Charm       Channel    Rev  Exposed  Message
-postgresql           active    2/3  postgresql  14/stable  468  no       
+postgresql           active    2/3  postgresql  16/stable  843  no       
 
 Unit           Workload  Agent       Machine  Public address  Ports     Message
 postgresql/0   active    idle        0        34.148.44.51    5432/tcp  
diff --git a/docs/how-to/deploy/sunbeam.md b/docs/how-to/deploy/sunbeam.md
@@ -40,7 +40,7 @@ To summarise, the relevant sections are:
 Add a model if you don't have one already, and deploy a PostgreSQL cluster. Use the `-n` flag to specify number of units.
 ```text
 juju add-model postgresql
-juju deploy postgresql --channel 16/edge --base ubuntu@22.04 -n 3
+juju deploy postgresql --channel 16/stable --base ubuntu@22.04 -n 3
 ```
 
 Sample output of `juju status --watch 1s`:
@@ -49,7 +49,7 @@ Model       Controller     Cloud/Region       Version  SLA          Timestamp
 postgresql  my-controller  sunbeam/RegionOne  3.5.4    unsupported  19:42:44Z
 
 App         Version  Status  Scale  Charm       Channel    Rev  Exposed  Message
-postgresql  16    active      3  postgresql     16/edge    468  no       
+postgresql  16.9     active      3  postgresql  16/stable  843  no       
 
 Unit           Workload  Agent  Machine  Public address   Ports     Message
 postgresql/0*  active    idle   0        192.168.122.211  5432/tcp  Primary
diff --git a/docs/how-to/deploy/terraform.md b/docs/how-to/deploy/terraform.md
@@ -50,7 +50,7 @@ resource "juju_application" "machine_postgresql" {
 
   charm {
     name    = "postgresql"
-    channel = "14/stable"
+    channel = "16/stable"
   }
 
   config = {
@@ -91,7 +91,7 @@ Model         Controller  Cloud/Region         Version  SLA          Timestamp
 my-model  lxd         localhost/localhost  3.5.2    unsupported  14:04:26+02:00
 
 App         Version  Status  Scale  Charm       Channel    Rev  Exposed  Message
-postgresql  14.11    active      1  postgresql  14/stable  429  no       
+postgresql  16.9     active      1  postgresql  16/stable  843  no       
 
 Unit           Workload  Agent  Machine  Public address  Ports     Message
 postgresql/0*  active    idle   0        10.142.152.90   5432/tcp  Primary
@@ -141,11 +141,11 @@ Terraform will perform the following actions:
       - units       = 1 -> null
 
       - charm {
-          - base     = "ubuntu@22.04" -> null
-          - channel  = "14/stable" -> null
+          - base     = "ubuntu@24.04" -> null
+          - channel  = "16/stable" -> null
           - name     = "postgresql" -> null
-          - revision = 429 -> null
-          - series   = "jammy" -> null
+          - revision = 843 -> null
+          - series   = "noble" -> null
         }
     }
 
diff --git a/docs/how-to/deploy/tls-vip-access.md b/docs/how-to/deploy/tls-vip-access.md
@@ -48,7 +48,7 @@ juju add-model my-external-tls-db
 Deploy `postgresql` and `self-signed-certificates`:
 
 ```text
-juju deploy postgresql --channel 14/stable -n 3
+juju deploy postgresql --channel 16/stable -n 3
 juju deploy self-signed-certificates
 juju integrate postgresql self-signed-certificates
 ```
@@ -85,7 +85,7 @@ App                       Version  Status  Scale  Charm                     Chan
 data-integrator                    active      3  data-integrator           latest/stable   78  no       
 hacluster                 2.1.2    active      3  hacluster                 2.4/stable     131  no       Unit is ready and clustered
 pgbouncer                 1.21.0   active      3  pgbouncer                 1/stable       396  no       VIP: 10.78.217.100
-postgresql                14.12    active      3  postgresql                14/stable      468  no       
+postgresql                16.9     active      3  postgresql                16/stable      843  no       
 self-signed-certificates           active      1  self-signed-certificates  latest/stable  155  no       
 
 Unit                         Workload  Agent  Machine  Public address  Ports     Message
diff --git a/docs/how-to/enable-ldap.md b/docs/how-to/enable-ldap.md
@@ -6,7 +6,7 @@ This guide goes over the steps to integrate LDAP as an authentication method wit
 
 ## Prerequisites
 
-* Charmed PostgreSQL channel `14/edge` or `16/edge` (revision `600` or higher)
+* Charmed PostgreSQL channel `14/stable` or `16/stable` (revision `600` or higher)
 * Juju `v3.6` or higher
 
 ## Deploy an LDAP server in a K8s environment
@@ -30,7 +30,7 @@ Deploy the [GLAuth charm](https://charmhub.io/glauth-k8s):
 ```text
 juju add-model glauth
 juju deploy self-signed-certificates
-juju deploy postgresql-k8s --channel 16/stable --trust
+juju deploy postgresql-k8s --channel 14/stable --trust
 juju deploy glauth-k8s --channel edge --trust
 ```
 
diff --git a/docs/how-to/enable-plugins-extensions/enable-timescaledb.md b/docs/how-to/enable-plugins-extensions/enable-timescaledb.md
@@ -2,7 +2,7 @@
 
 Charmed PostgreSQL separates TimescaleDB editions for different [Charmhub tracks](https://canonical-charmcraft.readthedocs-hosted.com/en/stable/howto/manage-channels/):
 
-[Charmed PostgreSQL 16](https://charmhub.io/postgresql?channel=16/edge) ships [Timescale Community edition](https://docs.timescale.com/about/latest/timescaledb-editions/).
+[Charmed PostgreSQL 16](https://charmhub.io/postgresql?channel=16/stable) ships [Timescale Community edition](https://docs.timescale.com/about/latest/timescaledb-editions/).
 
 ## Enable TimescaleDB
 
diff --git a/docs/how-to/manage-passwords.md b/docs/how-to/manage-passwords.md
@@ -14,7 +14,11 @@ To create a secret in Juju containing one or more user passwords:
 juju add-secret <secret_name> <user_a>=<password_a> <user_b>=<password_b>
 ```
 
-The command above will output a secret URI, which you'll need for configuring `system-users`.
+The command above will output a secret URI similar to the example below, which you'll need for configuring `system-users`:
+
+```text
+secret:a2whj30el0fco390bt9f
+```
 
 Admin users that were not included in the secret will use an automatically created password.
 
@@ -29,7 +33,11 @@ juju grant-secret <secret_name> postgresql
 To set the `system-users` config option to the secret URI:
 
 ```text
-juju config charm-app system-users=<secret_URI>
+juju config postgresql system-users=<secret_URI>
+```
+
+```{tip}
+Note that `<secret_URI>` includes the the scheme (`secret:`).
 ```
 
 When the `system-users` config option is set, the charm will:
diff --git a/docs/how-to/scale-replicas.md b/docs/how-to/scale-replicas.md
@@ -9,7 +9,7 @@ This guide will show you how to establish and change the amount of juju units us
 To deploy PostgreSQL with multiple replicas, specify the number of desired units with the `-n` option.
 
 ```text
-juju deploy postgresql --channel 14/stable -n <number_of_replicas>
+juju deploy postgresql --channel 16/stable -n <number_of_replicas>
 ```
 
 It is recommended to use an odd number to prevent a [split-brain](https://en.wikipedia.org/wiki/Split-brain_(computing)) scenario.
diff --git a/docs/index.md b/docs/index.md
@@ -1,10 +1,8 @@
-# Charmed PostgreSQL documentation
-
-```{caution}
-**Charmed PostgreSQL 16 is under development.** Please wait for the upcoming stable release before deploying it in production, or see the documentation for [version 14](https://canonical-charmed-postgresql.readthedocs-hosted.com/14/).
+---
+relatedlinks: "[Charmhub](https://charmhub.io/postgresql?channel=16/stable)"
+---
 
-Meanwhile, you’re welcome to explore the [`16/edge` track](https://charmhub.io/postgresql?channel=16/edge) and share your feedback as we continue to improve.
-```
+# Charmed PostgreSQL documentation
 
 Charmed PostgreSQL is an open-source software operator designed to deploy and operate object-relational databases on IAAS/VM. It packages the powerful database management system [PostgreSQL](https://www.postgresql.org/) into a charmed operator for deployment with [Juju](https://juju.is/docs/juju).
 
diff --git a/docs/reference/alert-rules.md b/docs/reference/alert-rules.md
@@ -1,9 +1,9 @@
 # Alert rules
 
 This page contains a markdown version of the alert rules described in the `postgresql-operator` repository.  The following file(s) are the source of truth:
-* [`src/prometheus_alert_rules/postgresql_rules.yaml`](https://github.com/canonical/postgresql-operator/blob/main/src/prometheus_alert_rules/postgresql_rules.yaml)
-* [`src/prometheus_alert_rules/pgbouncer_rules.yaml`](https://github.com/canonical/postgresql-operator/blob/main/src/prometheus_alert_rules/pgbouncer_rules.yaml)
-* [`src/prometheus_alert_rules/patroni_rules.yaml`](https://github.com/canonical/postgresql-operator/blob/main/src/prometheus_alert_rules/patroni_rules.yaml)
+* [`src/prometheus_alert_rules/postgresql_rules.yaml`](https://github.com/canonical/postgresql-operator/blob/16/edge/src/prometheus_alert_rules/postgresql_rules.yaml)
+* [`src/prometheus_alert_rules/pgbouncer_rules.yaml`](https://github.com/canonical/postgresql-operator/blob/16/edge/src/prometheus_alert_rules/pgbouncer_rules.yaml)
+* [`src/prometheus_alert_rules/patroni_rules.yaml`](https://github.com/canonical/postgresql-operator/blob/16/edge/src/prometheus_alert_rules/patroni_rules.yaml)
 
 > This documentation describes the latest alert rule expressions. See the YAML file(s) on listed above if you require an older version.
 
diff --git a/docs/reference/versions.md b/docs/reference/versions.md
@@ -2,7 +2,7 @@
 
 Charmed PostgreSQL is shipped in following [tracks](https://documentation.ubuntu.com/juju/3.6/reference/charm/#track): 
 
-* [PostgreSQL 16] (channel `16/edge`)
+* [PostgreSQL 16] (channel `16/stable`)
 * [PostgreSQL 14] (channel `14/stable`)
 * [Legacy PostgreSQL charm] (channel `latest/stable`) -> **deprecated**
 
diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md
