From fa7d37cfdc2183bb88c3c6dd57c8abde93b91483 Mon Sep 17 00:00:00 2001
From: Stephan Pillhofer <43667664+DarkR0ast@users.noreply.github.com>
Date: Fri, 20 Mar 2026 13:10:30 +0100
Subject: [PATCH] Extended migration steps for PostgreSQL data

Extended migration steps for PostgreSQL data after upgrading to 2.55.4.
---
 docs/content/releases/os_upgrading/2.51.md | 40 ++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/content/releases/os_upgrading/2.51.md b/docs/content/releases/os_upgrading/2.51.md
index 839741a9779..af056256798 100644
--- a/docs/content/releases/os_upgrading/2.51.md
+++ b/docs/content/releases/os_upgrading/2.51.md
@@ -84,6 +84,46 @@ _Note: If you are using a bound volume, the path has changed for Postgres18. It
 > This has been fixed in 2.55.4 by explicitly setting `PGDATA: /var/lib/postgresql/data` in `docker-compose.yml`.
 >
 > If you customise the postgres service in your own `docker-compose.override.yml`, make sure `PGDATA` is set to the path where your volume is mounted.
+>
+> **Important for existing installations**
+>
+> If you previously ran DefectDojo with PostgreSQL 18 using the old default `docker‑compose.yml`, your PostgreSQL data may be stored inside a nested directory such as `/var/lib/postgresql/data/18/docker`
+> In that case, the root of the volume (`/var/lib/postgresql/data`) is non‑empty but is *not* itself a valid Postgres cluster root. After applying the fix that sets `PGDATA: /var/lib/postgresql/data` PostgreSQL may fail to start with an error like `initdb: error: directory "/var/lib/postgresql/data" exists but is not empty` because the existing cluster files still live under the nested versioned path.
+>
+> To fix this problem you can migrate the existing cluster files into the volume root:
+>
+> 1. **Stop the Postgres service**  
+>    ```sh
+>    docker compose stop postgres
+>    ```
+>
+> 2. **Verify where your cluster currently lives**  
+>    ```sh
+>    docker run --rm -it -v <your_volume_name>:/data alpine sh
+>    ls -la /data
+>    ```
+>    Look for a directory such as `18/docker` that contains `PG_VERSION`, `base/`, etc.
+>
+> 3. **Move the cluster files into the volume root**  
+>    ```sh
+>    docker run --rm \
+>      -v <your_volume_name>:/data alpine \
+>      sh -c "mv /data/18/docker/* /data/"
+>    ```
+>
+> 4. **Clean up empty folders (optional)**  
+>    ```sh
+>    docker run --rm \
+>      -v <your_volume_name>:/data alpine \
+>      sh -c "rm -rf /data/18 /data/data"
+>    ```
+>
+> 5. **Start Postgres again**  
+>    ```sh
+>    docker compose up -d postgres
+>    ```
+>
+> After this, the database should start using `PGDATA: /var/lib/postgresql/data`, and your existing data will be preserved.
 
 ### 0. Backup