Documentation: Add volume permissions and PGDATA configuration requirements for timescaledb-ha image

[fcojaviergon]

📝 Issue for TimescaleDB Repository

Problem Summary

The official documentation for timescale/timescaledb-ha Docker image does not document critical requirements for volume permissions and PGDATA configuration, leading to data loss and initialization failures that are difficult to troubleshoot.

Current Documentation Gap

The official installation guide at https://docs.tigerdata.com/self-hosted/latest/install/installation-docker/ does not mention:

1. Volume Permissions: The HA image requires volumes with 1000:1000 ownership (hardcoded postgres UID/GID)
2. PGDATA Configuration: When using custom volume mounts, PGDATA must be explicitly set to match the mount point
3. Differences from Standard Image: The HA image behaves differently from timescale/timescaledb regarding permissions and paths

Issues Encountered

Without this documentation, developers encounter these problems:

1. Permission Errors on Initialization

initdb: error: could not change permissions of directory "/var/lib/postgresql/data": Operation not permitted

2. Data Loss After Container Recreate

• Data appears to persist but is actually stored in container layer (not volume)
• When container recreates, all data is lost
• Alembic/Flyway migrations re-run from scratch

3. Volume Not Used

• Volume mounted at /var/lib/postgresql/data
• HA image actually uses /home/postgres/pgdata/data by default
• Volume remains empty, data stored ephemerally

Related Issues

This has been reported multiple times but never addressed in official docs:

• initdb: error: could not change permissions of directory "/home/postgres/pgdata/data": Operation not permitted #334 - initdb permission errors
• deployment as in docker stack has data volume permission problems #311 - Docker stack volume permission problems
• Cannot use this image with a custom uid/gid and bind-mounts. #345 - Cannot use custom uid/gid with bind-mounts
• Image not fully compatible with standard postgres images #272 - Image not fully compatible with standard postgres images

Proposed Documentation Improvements

1. Add "Volume Permissions" Section

# ⚠️ IMPORTANT: HA image requires specific permissions
services:
  # Initialize volume with correct permissions (UID 1000:1000)
  db-init:
    image: alpine
    volumes:
      - timescale-data:/data
    command: sh -c "chown -R 1000:1000 /data && chmod -R 700 /data"
    restart: "no"

  timescaledb:
    image: timescale/timescaledb-ha:pg16
    depends_on:
      db-init:
        condition: service_completed_successfully
    environment:
      POSTGRES_PASSWORD: password
      PGDATA: /var/lib/postgresql/data  # ← Must match volume mount
    volumes:
      - timescale-data:/var/lib/postgresql/data

volumes:
  timescale-data:

2. Add "Common Issues" Section

Problem: Data lost after docker compose up --build

Cause: Volume permissions incorrect or PGDATA misconfigured

Solution: Use init container (see above) or manually set permissions:

docker run --rm -v timescale-data:/data alpine chown -R 1000:1000 /data

3. Add "HA vs Standard Image" Comparison Table

Feature	timescaledb	timescaledb-ha
Postgres UID	999 (configurable)	1000 (hardcoded)
Default PGDATA	/var/lib/postgresql/data	/home/postgres/pgdata/data
Volume permissions	Flexible	Requires 1000:1000
Init complexity	Simple	Requires init container

Impact

Without this documentation:

• ✗ Developers waste hours debugging permission errors
• ✗ Data loss in production due to misconfiguration
• ✗ Poor developer experience with HA image
• ✗ Users switch to standard image to avoid issues

Suggested Documentation Locations

1. Installation Docker page - Add "Prerequisites" section about permissions
2. Configuration page - Add "Volume Management" section
3. Troubleshooting page - Add "Permission Denied Errors" section
4. README in timescaledb-docker-ha repo - Add prominent warning

Additional Context

• This issue affects Docker Compose, Docker Swarm, and Kubernetes deployments
• The standard timescale/timescaledb image does not have these issues
• Community has documented workarounds in various blog posts and Stack Overflow

References

• Tiger Data Docs: https://docs.tigerdata.com/self-hosted/latest/install/installation-docker/
• Docker Hub: https://hub.docker.com/r/timescale/timescaledb-ha
• Community workarounds: Multiple GitHub issues and Stack Overflow threads

---

Would appreciate if this could be added to official documentation to help other developers avoid data loss.

[xmlking]

I recently switched from timescale/timescaledb:pg18-oss to timescale/timescaledb-ha:pg18-oss due to lack of pgvector in light version.
i faced data loss when I did docker compose down . changed the volume, now it works

  postgres:
    image: timescale/timescaledb-ha:pg18-oss
    hostname: postgres
    container_name: postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: postgres
      POSTGRES_PASSWORD: xxxxxxxxxxxx
      POSTGRES_USER: postgres
      WAL_LEVEL: logical
      MAX_REPLICATION_SLOTS: "10"
      MAX_WAL_SENDERS: "10"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB -q"]
      interval: 60s
      start_period: 1m
      start_interval: 10s
      timeout: 15s
      retries: 5
    ports:
      - "5432:5432"
    volumes:
      - type: volume
        source: pg_data
        # target: /var/lib/postgresql/data
        target: /home/postgres/pgdata/data
        read_only: false
      - ./infra/db/init-database.sh:/docker-entrypoint-initdb.d/init-data.sh:Z

[Kaszanas]

@fcojaviergon This is a great writeup, do you know how to mount to a specific Windows directory? I have the issue where:

postgres-1  | initdb: error: could not change permissions of directory "/postgres_data/postgresql/data": Operation not permitted                                                   
postgres-1  | fixing permissions on existing directory /postgres_data/postgresql/data ...   

✗ Developers waste hours debugging permission errors - Check
✗ Poor developer experience with HA image - Check
✗ Users switch to standard image to avoid issues - Almost

I have managed to configure this somehow with a local Windows mount to a specific fast SSD working as a storage pool.