website/docs: Clean up PostgreSQL documentation (#21131)

* Clean up PostgreSQL documentation

* Overview

* SSL wording

* Conn age

* Schema text

* Replica line

* Direct tip

* Backup text

* Restore text

* Access text

* Copy text

* Issue text

* Sentence case

* Section intro

* Primary reads

* Username text

* Password text

* TLS modes

* Health checks

* Replica case

* Replica intro

* Backup guides

* Docker intro

* Stop stack

* Stop wording

* Backup alt

* Dump wording

* Remove alt

* Network note

* Verify login

* Dump safety

* Log names

website/docs/troubleshooting/postgres/upgrade_docker.md

@@ -2,46 +2,121 @@
 title: Upgrade PostgreSQL on Docker Compose
 ---
 
-### Dump your database
+This guide describes a manual PostgreSQL major-version upgrade for the default authentik Docker Compose deployment.
 
-Dump your existing database with `docker compose exec postgresql pg_dump -U authentik -d authentik -cC > upgrade_backup_12.sql`.
+It assumes the PostgreSQL service is named `postgresql` and the authentik database is named `authentik`. If your Compose file uses different names, adjust the commands accordingly.
 
-Before continuing, ensure the SQL dump file (`upgrade_backup_12.sql`) includes all your database content.
+## Before you start
 
-### Stop your authentik stack
+- Make sure you have enough free disk space for:
+    - a SQL dump of the database
+    - a copy of the existing PostgreSQL data directory or volume
+    - the newly initialized PostgreSQL data directory
+- Expect downtime while the database is exported, recreated, and restored.
+- Review the [Backup and restore](../../sys-mgmt/ops/backup-restore.md) guidance before proceeding.
 
-Stop all services with `docker compose down`.
+## 1. Create a logical backup
 
-### Backup your existing database
+Create a database dump:
 
-If you use Docker volumes you can run the following command: `docker volume create authentik_database_backup && docker run --rm -v authentik_database:/from -v authentik_database_backup:/to alpine sh -c 'cd /from && cp -a . /to'`. You can find the name of the `authentik_database` volume with `docker volume ls`.
+```shell
+docker compose exec postgresql pg_dump -U authentik -d authentik -cC > authentik-postgres-backup.sql
+```
 
-If your data is a file path: `cp -a /path/to/v12-data /path/to/v12-backup`
+Before continuing, confirm that `authentik-postgres-backup.sql` exists and contains the expected database objects.
 
-### Delete your old database
+## 2. Stop your authentik stack
+
+Stop all services with this command:
+
+```shell
+docker compose down
+```
+
+## 3. Back up the PostgreSQL data directory
+
+Back up the existing PostgreSQL data before replacing it.
+
+If you use Docker volumes:
+
+```shell
+docker volume create authentik_database_backup
+docker run --rm -v authentik_database:/from -v authentik_database_backup:/to alpine sh -c 'cd /from && cp -a . /to'
+```
+
+You can find the exact name of the PostgreSQL volume with `docker volume ls` if it differs from `authentik_database`.
+
+Alternatively, if your PostgreSQL data is stored on the host filesystem:
+
+```shell
+cp -a /path/to/postgres-data /path/to/postgres-data-backup
+```
+
+## 4. Remove the old data directory
 
 :::danger
-Do not execute this step without checking that the backup (previous step) completed successfully.
+Do not continue unless both the database dump and the filesystem or volume backup completed successfully.
 :::
 
-If you use Docker volumes: `docker volume rm -f authentik_database`.
+If you use Docker volumes:
 
-If your data is a file path: `rm -rf /path/to/v12-data`
+```shell
+docker volume rm -f authentik_database
+```
 
-### Modify your compose.yml file
+Alternatively, if your PostgreSQL data is stored on the host filesystem:
 
-Update the PostgreSQL service image from `docker.io/library/postgres:12-alpine` to `docker.io/library/postgres:16-alpine`.
+```shell
+rm -rf /path/to/postgres-data
+```
 
-Add `network_mode: none` to prevent connections being established to the database during the upgrade.
+## 5. Update the PostgreSQL image
 
-### Recreate the database container
+Edit your `compose.yml` and update the PostgreSQL image tag to the new major version.
 
-Pull new images and re-create the PostgreSQL container: `docker compose pull && docker compose up --force-recreate -d postgresql`
+For example, change:
 
-Apply your backup to the new database: `cat upgrade_backup_12.sql | docker compose exec -T postgresql psql -U authentik`
+```yaml
+image: docker.io/library/postgres:12-alpine
+```
 
-Remove the network configuration setting `network_mode: none` that you added to the Compose file in the previous step.
+to:
 
-### Recreate authentik
+```yaml
+image: docker.io/library/postgres:16-alpine
+```
 
-Start authentik again: `docker compose up --force-recreate -d`
+Temporarily add `network_mode: none` to the PostgreSQL service to prevent connections being established to the database during the upgrade.
+
+## 6. Recreate PostgreSQL and restore the database
+
+Pull images and start only PostgreSQL:
+
+```shell
+docker compose pull
+docker compose up --force-recreate -d postgresql
+```
+
+Restore the logical backup:
+
+```shell
+cat authentik-postgres-backup.sql | docker compose exec -T postgresql psql -U authentik
+```
+
+After the restore succeeds, remove the temporary `network_mode: none` setting from `compose.yml`.
+
+## 7. Start authentik again
+
+Start the full stack:
+
+```shell
+docker compose up --force-recreate -d
+```
+
+## 8. Verify the upgrade
+
+After the stack is healthy again:
+
+- confirm that authentik loads normally
+- check the server, worker, and postgresql logs for startup or migration errors
+- log in to authentik through the UI to verify the application is functioning normally