fix(docker): move Postgres to a named volume and bump to Postgres 18 (#486)

* fix(docker): store Postgres cluster in a pgdata subdirectory

The prod compose bind-mounted ./docker-data/postgres straight onto
/var/lib/postgresql/data. The mount-point root is owned by the host, so
Postgres could refuse to (re)initialize on repeated `docker compose up`
runs. Point PGDATA at a pgdata/ subdirectory the Postgres entrypoint
creates and owns itself, sidestepping the mount-point ownership.

Existing deployments must move their cluster into docker-data/postgres/pgdata
once before upgrading; documented in the Docker setup guide.

* fix(docker): rework Postgres ownership fix as a chown-init sidecar

Replace the PGDATA-subdirectory approach with a postgres-init service,
mirroring the existing elasticsearch-init pattern: it chowns the
bind-mounted ./docker-data/postgres path to postgres:postgres before
the postgres service starts. This corrects ownership in place on every
`docker compose up`, so existing deployments need no data migration
(the PGDATA subdirectory approach required moving the cluster on disk).

* fix(docker): apply the postgres-init chown sidecar to dev compose files

docker-compose.yml and docker-compose.dev.yml bind-mount ./docker-data/postgres
the same way the prod compose does, so they carry the same ownership bug.
Add the same postgres-init sidecar to both, gating postgres on it.

* fix(docker): move Postgres to a named volume, replacing the postgres-init sidecar

The postgres-init chown sidecar didn't address the actual reported bug
(#485): docker compose build fails at "load build context" because
Postgres locks ./docker-data/postgres down to 0700 once it's run, and
BuildKit's context walker needs to stat every entry under the build
context root regardless of .dockerignore rules — a permission-denied
directory anywhere in that tree aborts the whole context transfer, even
when .dockerignore would ultimately exclude it. Verified empirically:
fixing .dockerignore alone does not resolve the build failure; removing
the directory from the build context (named volume) does.

Switch Postgres's volume from a bind mount to the named Docker volume
testplanit-postgres-data across all three compose files, so its data
directory can never live inside the build context. Also fix the
.dockerignore inconsistency across the three ignore files as a
secondary hygiene fix, even though it isn't sufficient on its own.

Existing deployments need a one-time migration (documented in
docker-setup.md) to move their bind-mounted data into the named volume
and remove the old directory, since a leftover 0700 directory would
still break the build even after upgrading.

* feat(docker): bump Postgres from 15 to 18

15 is three majors behind current stable (18.4). No blocking compatibility
issues found: the app only uses the pg_trgm extension (stable since early
Postgres releases), and the audit trigger installer uses only long-standing
PL/pgSQL/SQL constructs. Verified against a real Postgres 18 instance: Prisma
client generation, `prisma db push`, all 69 audit triggers, and the full demo
seed all complete cleanly, and data survives a container restart.

Postgres 18's official image changed its default PGDATA to a version-specific
subdirectory and expects the volume mounted at /var/lib/postgresql instead of
.../data (docker-library/postgres#1259). Pin PGDATA back to the old flat path
so the existing named-volume mount doesn't need to change on every future
major bump, and to sidestep a still-open detection bug in the new layout
(docker-library/postgres#1400) that reproduced reliably in local testing.

Existing deployments need a real pg_dump/pg_restore migration, not a raw file
copy — Postgres 18 can't read a Postgres 15 data directory. Documented
alongside the named-volume migration note, since both land in the same
upgrade.

Author: therealbrad

docs/.dockerignore

@@ -11,3 +11,4 @@ docker-compose.yml
 *.log
 .DS_Store
 .vscode/
+**/docker-data/

docs/docs/deployment.md

@@ -232,11 +232,17 @@ docker compose -f docker-compose.prod.yml $PROFILES up -d
 # Backup data (if using Docker services)
 docker compose -f docker-compose.prod.yml $PROFILES down
 tar -czf testplanit-backup-$(date +%Y%m%d).tar.gz docker-data/
+docker run --rm -v testplanit-postgres-data:/data -v "$(pwd):/backup" \
+  alpine tar -czf /backup/testplanit-postgres-backup-$(date +%Y%m%d).tar.gz -C /data .
 
 # Restore from backup
 docker compose -f docker-compose.prod.yml $PROFILES down
 sudo rm -rf docker-data/
+docker volume rm testplanit-postgres-data
 tar -xzf testplanit-backup-YYYYMMDD.tar.gz
+docker volume create testplanit-postgres-data
+docker run --rm -v testplanit-postgres-data:/data -v "$(pwd):/backup" \
+  alpine tar -xzf /backup/testplanit-postgres-backup-YYYYMMDD.tar.gz -C /data
 docker compose -f docker-compose.prod.yml $PROFILES up -d
 ```
 
@@ -273,13 +279,15 @@ docker exec testplanit-workers pm2 logs notification-worker
 
 ### Data Persistence
 
-All service data is stored in `./docker-data/`:
+Most service data is stored in `./docker-data/`:
 
-- `postgres/` - Database files
 - `redis/` - Valkey persistence
 - `elasticsearch/` - Search indexes
 - `minio/` - File attachments
 
+Postgres data lives in the named Docker volume `testplanit-postgres-data` instead
+of a bind mount, so it can never end up inside the build context.
+
 ### File Storage Configuration
 
 **Option 1: Docker MinIO** (`with-minio` profile)

docs/docs/docker-setup.md

@@ -247,6 +247,7 @@ docker compose down --remove-orphans
 # Fresh start (removes all data!)
 docker compose down
 sudo rm -rf docker-data/
+docker volume rm testplanit-postgres-data
 docker compose up prod workers --build
 ```
 
@@ -307,16 +308,63 @@ docker compose -f docker-compose.prod.yml \
 
 ### Data Persistence
 
-All service data persists in `./docker-data/`:
+Most service data persists in `./docker-data/`:
 
 ```text
 docker-data/
-├── postgres/      # Database files
 ├── valkey/        # Valkey job queue persistence
 ├── elasticsearch/ # Search indexes
 └── minio/         # File attachments
 ```
 
+Postgres is the exception: it uses the named Docker volume `testplanit-postgres-data`
+instead of a bind mount. Its data directory can't live inside `./docker-data/`
+(or anywhere else under the build context) — once Postgres has run, it locks the
+directory down to `0700`, which makes `docker compose build` fail with a
+permission error on any later build.
+
+Postgres was also bumped from 15 to 18 in the same change, so this isn't a
+straight file-copy upgrade — Postgres 18 cannot read a Postgres 15 data
+directory. Existing deployments need a `pg_dump` / `pg_restore` migration
+instead.
+
+:::warning Upgrading an existing deployment
+
+Deployments created before this change run Postgres 15 with data directly in
+`docker-data/postgres/`. Dump the database **before** switching to the
+updated compose files — once you do, `postgres` starts on the new image and
+can no longer read the old data directory:
+
+```bash
+# 1. On the OLD stack (still Postgres 15), dump the database.
+docker compose exec -T postgres pg_dump -U user -Fc -d testplanit_prod > testplanit-backup.dump
+docker compose down
+```
+
+Pull the updated compose files, then bring up a fresh Postgres 18 instance and restore into it:
+
+```bash
+# 2. Bring up the new (empty) Postgres 18 named volume and restore.
+docker compose up postgres -d
+# wait for it to report healthy, then:
+docker compose exec -T postgres pg_restore -U user -d testplanit_prod --clean --if-exists < testplanit-backup.dump
+
+# 3. Verify the app reads the migrated data correctly, then bring up the rest.
+docker compose up prod workers -d
+```
+
+Once you've confirmed the migrated data is intact, the old `docker-data/postgres/`
+directory is no longer used and can be removed. It's already locked down to
+`0700` by the old Postgres process, so removing it needs a root context — either
+`sudo rm -rf docker-data/postgres`, or from a throwaway container that doesn't
+need host-level `sudo`:
+
+```bash
+docker run --rm -v "$(pwd)/docker-data:/data" alpine rm -rf /data/postgres
+```
+
+:::
+
 ### Backup & Restore
 
 **Create Backup:**
@@ -325,9 +373,15 @@ docker-data/
 # Stop services
 docker compose down
 
-# Create timestamped backup
+# Back up the bind-mounted service data
 tar -czf testplanit-backup-$(date +%Y%m%d).tar.gz docker-data/
 
+# Back up the Postgres named volume separately
+docker run --rm \
+  -v testplanit-postgres-data:/data \
+  -v "$(pwd):/backup" \
+  alpine tar -czf /backup/testplanit-postgres-backup-$(date +%Y%m%d).tar.gz -C /data .
+
 # Restart services
 docker compose up prod workers -d
 ```
@@ -338,10 +392,18 @@ docker compose up prod workers -d
 # Stop and remove current data
 docker compose down
 sudo rm -rf docker-data/
+docker volume rm testplanit-postgres-data
 
-# Extract backup
+# Extract the bind-mounted service data
 tar -xzf testplanit-backup-YYYYMMDD.tar.gz
 
+# Restore the Postgres named volume
+docker volume create testplanit-postgres-data
+docker run --rm \
+  -v testplanit-postgres-data:/data \
+  -v "$(pwd):/backup" \
+  alpine tar -xzf /backup/testplanit-postgres-backup-YYYYMMDD.tar.gz -C /data
+
 # Restart services
 docker compose up prod workers -d
 ```
@@ -507,5 +569,6 @@ docker exec testplanit-workers pm2 list
 # Nuclear option - fresh start
 docker compose down
 sudo rm -rf docker-data/
+docker volume rm testplanit-postgres-data
 docker compose up prod workers --build
 ```

testplanit/.dockerignore

@@ -11,4 +11,4 @@ README.md
 .DS_Store
 dist
 coverage
-docker-data/
+**/docker-data/

testplanit/docker-compose.dev.yml

@@ -82,13 +82,24 @@ services:
 
   postgres:
     container_name: testplanit-postgres
-    image: postgres:15-alpine # Use a specific Postgres version
+    image: postgres:18-alpine # Use a specific Postgres version
     environment:
       POSTGRES_USER: user # Must match the user in DATABASE_URL
       POSTGRES_PASSWORD: password # Must match the password in DATABASE_URL
       POSTGRES_DB: testplanit_dev # Creates this DB initially. Prod app uses testplanit_prod
+      # Postgres 18 defaults PGDATA to a version-specific subdirectory
+      # (/var/lib/postgresql/18/docker) and expects the volume mounted at
+      # /var/lib/postgresql instead of .../data. Pin the old flat layout so the
+      # mount path below doesn't have to change across major-version bumps, and
+      # to avoid a still-open docker-library/postgres detection bug around the
+      # new layout (github.com/docker-library/postgres/issues/1400).
+      PGDATA: /var/lib/postgresql/data
+    # Named volume, not a bind mount: Postgres's data directory must never live
+    # inside the build context (context: .. at the repo root). Once Postgres has
+    # run, it chmods the directory 0700, which makes BuildKit's context walker
+    # fail with "permission denied" on any subsequent `docker compose build`.
     volumes:
-      - ./docker-data/postgres:/var/lib/postgresql/data
+      - postgres-data:/var/lib/postgresql/data
     ports:
       - "${DOCKER_POSTGRES_PORT:-5432}:5432" # Expose Postgres on configurable host port
     networks:
@@ -117,3 +128,7 @@ services:
 networks:
   testplanit-net:
     driver: bridge
+
+volumes:
+  postgres-data:
+    name: testplanit-postgres-data

testplanit/docker-compose.prod.yml

@@ -80,13 +80,24 @@ services:
 
   postgres:
     container_name: testplanit-postgres
-    image: postgres:15-alpine
+    image: postgres:18-alpine
     environment:
       POSTGRES_USER: user
       POSTGRES_PASSWORD: password
       POSTGRES_DB: testplanit_prod
+      # Postgres 18 defaults PGDATA to a version-specific subdirectory
+      # (/var/lib/postgresql/18/docker) and expects the volume mounted at
+      # /var/lib/postgresql instead of .../data. Pin the old flat layout so the
+      # mount path below doesn't have to change across major-version bumps, and
+      # to avoid a still-open docker-library/postgres detection bug around the
+      # new layout (github.com/docker-library/postgres/issues/1400).
+      PGDATA: /var/lib/postgresql/data
+    # Named volume, not a bind mount: Postgres's data directory must never live
+    # inside the build context (context: .. at the repo root). Once Postgres has
+    # run, it chmods the directory 0700, which makes BuildKit's context walker
+    # fail with "permission denied" on any subsequent `docker compose build`.
     volumes:
-      - ./docker-data/postgres:/var/lib/postgresql/data
+      - postgres-data:/var/lib/postgresql/data
     ports:
       - "${DOCKER_POSTGRES_PORT:-5432}:5432"
     networks:
@@ -219,3 +230,7 @@ services:
 networks:
   testplanit-net:
     driver: bridge
+
+volumes:
+  postgres-data:
+    name: testplanit-postgres-data

testplanit/docker-compose.yml

@@ -199,13 +199,24 @@ services:
 
   postgres:
     container_name: testplanit-postgres
-    image: postgres:15-alpine # Use a specific Postgres version
+    image: postgres:18-alpine # Use a specific Postgres version
     environment:
       POSTGRES_USER: user # Must match the user in DATABASE_URL
       POSTGRES_PASSWORD: password # Must match the password in DATABASE_URL
       POSTGRES_DB: testplanit_dev # Creates this DB initially. Prod app uses testplanit_prod
+      # Postgres 18 defaults PGDATA to a version-specific subdirectory
+      # (/var/lib/postgresql/18/docker) and expects the volume mounted at
+      # /var/lib/postgresql instead of .../data. Pin the old flat layout so the
+      # mount path below doesn't have to change across major-version bumps, and
+      # to avoid a still-open docker-library/postgres detection bug around the
+      # new layout (github.com/docker-library/postgres/issues/1400).
+      PGDATA: /var/lib/postgresql/data
+    # Named volume, not a bind mount: Postgres's data directory must never live
+    # inside the build context (context: .. at the repo root). Once Postgres has
+    # run, it chmods the directory 0700, which makes BuildKit's context walker
+    # fail with "permission denied" on any subsequent `docker compose build`.
     volumes:
-      - ./docker-data/postgres:/var/lib/postgresql/data
+      - postgres-data:/var/lib/postgresql/data
     ports:
       - "${DOCKER_POSTGRES_PORT:-5432}:5432" # Expose Postgres on configurable host port
     networks:
@@ -325,3 +336,7 @@ services:
 networks:
   testplanit-net:
     driver: bridge
+
+volumes:
+  postgres-data:
+    name: testplanit-postgres-data

testplanit/e2e/a11y/ci-workflow.draft.yml

@@ -32,7 +32,7 @@ jobs:
 
     services:
       postgres:
-        image: postgres:15-alpine
+        image: postgres:18-alpine
         env:
           POSTGRES_USER: user
           POSTGRES_PASSWORD: password