mirror of
https://github.com/goauthentik/authentik
synced 2026-04-28 18:37:42 +02:00
b96c477b6a
* 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
123 lines
3.2 KiB
Markdown
123 lines
3.2 KiB
Markdown
---
|
|
title: Upgrade PostgreSQL on Docker Compose
|
|
---
|
|
|
|
This guide describes a manual PostgreSQL major-version upgrade for the default authentik Docker Compose deployment.
|
|
|
|
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 you start
|
|
|
|
- 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.
|
|
|
|
## 1. Create a logical backup
|
|
|
|
Create a database dump:
|
|
|
|
```shell
|
|
docker compose exec postgresql pg_dump -U authentik -d authentik -cC > authentik-postgres-backup.sql
|
|
```
|
|
|
|
Before continuing, confirm that `authentik-postgres-backup.sql` exists and contains the expected database objects.
|
|
|
|
## 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 continue unless both the database dump and the filesystem or volume backup completed successfully.
|
|
:::
|
|
|
|
If you use Docker volumes:
|
|
|
|
```shell
|
|
docker volume rm -f authentik_database
|
|
```
|
|
|
|
Alternatively, if your PostgreSQL data is stored on the host filesystem:
|
|
|
|
```shell
|
|
rm -rf /path/to/postgres-data
|
|
```
|
|
|
|
## 5. Update the PostgreSQL image
|
|
|
|
Edit your `compose.yml` and update the PostgreSQL image tag to the new major version.
|
|
|
|
For example, change:
|
|
|
|
```yaml
|
|
image: docker.io/library/postgres:12-alpine
|
|
```
|
|
|
|
to:
|
|
|
|
```yaml
|
|
image: docker.io/library/postgres:16-alpine
|
|
```
|
|
|
|
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
|