homelab-docker-config/central-database/MIGRATION_GUIDE.md

Service Configuration Migration Guide

This guide shows how to update each service to use the central PostgreSQL database.

Service-Specific Configuration Updates

1. Synapse Matrix

Current configuration in synapse/docker-compose.yml:

synapse_db:
  image: docker.io/library/postgres:17
  restart: always
  volumes:
    - ${SYNAPSE_POSTGRES_DATA_DIR}:/var/lib/postgresql/data
  environment:
    POSTGRES_DB: ${SYNAPSE_POSTGRES_DB}
    POSTGRES_USER: ${SYNAPSE_POSTGRES_USER}
    POSTGRES_PASSWORD: ${SYNAPSE_POSTGRES_PASSWORD}
    POSTGRES_INITDB_ARGS: '--encoding=UTF-8  --locale=C'
  ports:
    - 5442:5432

synapse:
  # ... other config ...
  environment:
    POSTGRES_HOST: synapse_db
    POSTGRES_PORT: 5432
    POSTGRES_DB: ${SYNAPSE_POSTGRES_DB}
    POSTGRES_USER: ${SYNAPSE_POSTGRES_USER}
    POSTGRES_PASSWORD: ${SYNAPSE_POSTGRES_PASSWORD}

Updated configuration:

# Remove the synapse_db service entirely

synapse:
  # ... other config ...
  environment:
    POSTGRES_HOST: postgres
    POSTGRES_PORT: 5432
    POSTGRES_DB: synapse
    POSTGRES_USER: synapse_user
    POSTGRES_PASSWORD: ${SYNAPSE_POSTGRES_PASSWORD}
  depends_on:
    - postgres  # Add this dependency
  networks:
    - default  # Ensure same network as postgres container

2. Paperless

Current configuration in paperless/docker-compose.yml:

db:
  image: docker.io/library/postgres:17
  restart: always
  volumes:
    - ${PAPERLESS_POSTGRES_DATA_DIR}:/var/lib/postgresql/data
  environment:
    POSTGRES_DB: ${PAPERLESS_POSTGRES_DB}
    POSTGRES_USER: ${PAPERLESS_POSTGRES_USER}
    POSTGRES_PASSWORD: ${PAPERLESS_POSTGRES_PASSWORD}
  ports:
    - 5434:5432

paperless:
  # ... other config ...
  environment:
    PAPERLESS_DBHOST: db
    PAPERLESS_DBNAME: ${PAPERLESS_POSTGRES_DB}
    PAPERLESS_DBUSER: ${PAPERLESS_POSTGRES_USER}
    PAPERLESS_DBPASS: ${PAPERLESS_POSTGRES_PASSWORD}

Updated configuration:

# Remove the db service entirely

paperless:
  # ... other config ...
  environment:
    PAPERLESS_DBHOST: postgres
    PAPERLESS_DBNAME: paperless
    PAPERLESS_DBUSER: paperless_user
    PAPERLESS_DBPASS: ${PAPERLESS_POSTGRES_PASSWORD}
  depends_on:
    - postgres  # Add this dependency
  networks:
    - default

3. Immich

Current configuration in immich/docker-compose.yml:

database:
  container_name: immich_postgres
  image: ghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0
  environment:
    POSTGRES_USER: ${IMMICH_POSTGRES_USER}
    POSTGRES_PASSWORD: ${IMMICH_POSTGRES_PASSWORD}
    POSTGRES_DB: ${IMMICH_POSTGRES_DB}
    POSTGRES_INITDB_ARGS: '--data-checksums'
  ports:
    - 5433:5432
  volumes:
    - ${IMMICH_DB_LOCATION}:/var/lib/postgresql/data

immich-server:
  # ... other config ...
  environment:
    DB_HOSTNAME: ${IMMICH_DB_HOSTNAME}
    DB_USERNAME: ${IMMICH_POSTGRES_USER}
    DB_PASSWORD: ${IMMICH_POSTGRES_PASSWORD}
    DB_DATABASE_NAME: ${IMMICH_POSTGRES_DB}

Updated configuration:

# Remove the database service entirely

immich-server:
  # ... other config ...
  environment:
    DB_HOSTNAME: postgres
    DB_USERNAME: immich_user
    DB_PASSWORD: ${IMMICH_POSTGRES_PASSWORD}
    DB_DATABASE_NAME: immich
  depends_on:
    - postgres  # Add this dependency
  networks:
    - default

4. Shlink

Current configuration in shlink/docker-compose.yml:

shlink_db:
  image: postgres:17
  container_name: shlink_db
  restart: always
  volumes:
    - ${SHLINK_POSTGRES_DIR}:/var/lib/postgresql/data
  environment:
    POSTGRES_DB: ${SHLINK_POSTGRES_DB}
    POSTGRES_USER: ${SHLINK_POSTGRES_USER}
    POSTGRES_PASSWORD: ${SHLINK_POSTGRES_PASSWORD}
  ports:
    - 5436:5432

shlink:
  # ... other config ...
  environment:
    DB_HOST: shlink_db
    DB_NAME: ${SHLINK_POSTGRES_DB}
    DB_USER: ${SHLINK_POSTGRES_USER}
    DB_PASSWORD: ${SHLINK_POSTGRES_PASSWORD}

Updated configuration:

# Remove the shlink_db service entirely

shlink:
  # ... other config ...
  environment:
    DB_HOST: postgres
    DB_NAME: shlink
    DB_USER: shlink_user
    DB_PASSWORD: ${SHLINK_POSTGRES_PASSWORD}
  depends_on:
    - postgres  # Add this dependency
  networks:
    - default

General Pattern

For each service:

1. Remove the service-specific database container

2. Update the main service container's environment variables:

   • POSTGRES_HOST/DB_HOST → postgres
   • POSTGRES_PORT/DB_PORT → 5432
   • POSTGRES_DB/DB_NAME → <service_name> (e.g., synapse, paperless)
   • POSTGRES_USER/DB_USER → <service_name>_user
   • POSTGRES_PASSWORD/DB_PASSWORD → ${SERVICE_POSTGRES_PASSWORD} (keep existing)

3. Add dependency on postgres service

4. Update network configuration if needed (ensure services can reach postgres container)

Testing Migration

After updating each service:

1. Stop the service: docker-compose down
2. Start with new config: docker-compose up -d
3. Check logs: docker-compose logs -f
4. Test functionality: Verify the service works correctly
5. Rollback plan: Keep old database container until migration is confirmed successful

Network Considerations

Ensure all services are on the same Docker network or can reach the central_postgres container. You may need to:

1. Add services to the same network
2. Use Docker's internal DNS
3. Configure network aliases if needed

Password Management

Keep using the same password variables but ensure they match the central database user passwords. The migration script preserves existing passwords for seamless transition.