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`:**
```yaml
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:**
```yaml
# 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`:**
```yaml
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:**
```yaml
# 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`:**
```yaml
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:**
```yaml
# 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`:**
```yaml
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:**
```yaml
# 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.