picpeak/PRODUCTION_DEPLOYMENT_FIXES.md

Production Deployment Fixes

This document describes the fixes applied to resolve production deployment issues in Docker.

Issues Fixed

1. Database Connection Error: "getaddrinfo ENOTFOUND postgres"

Problem: The backend was trying to connect to hostname "postgres" but the database service is named "db" in docker-compose. Solution:

• Updated knexfile.js to use correct default host "db" instead of "postgres"
• Added depends_on: db to backend service in docker-compose.prod.yml

2. Backend Starting Before Database Ready

Problem: Backend service started before PostgreSQL was ready, causing connection failures. Solution:

• Created wait-for-db.sh script that waits for PostgreSQL to be ready
• Updated Dockerfile to install postgresql-client and use the wait script
• Script also runs migrations automatically on startup

3. Email Processor Initialization Failure

Problem: Email processor tried to initialize on module load before database was available. Solution:

• Modified emailProcessor.js to export initialization functions
• Updated server.js to call initialization after database is ready
• Added proper error handling for email service initialization

4. Missing Environment Variables

Problem: Critical storage path environment variables were missing. Solution:

• Added STORAGE_PATH, EVENTS_PATH, and ARCHIVE_PATH to docker-compose.prod.yml
• Created .env.example documenting all required environment variables

5. Enhanced Health Check

Problem: Basic health check didn't verify database connectivity. Solution:

• Updated /api/health endpoint to check database connection
• Returns proper HTTP 503 status when unhealthy

Files Modified

1. backend/knexfile.js - Fixed production database defaults
2. backend/wait-for-db.sh - Created database wait script
3. backend/Dockerfile - Added postgresql-client and wait script
4. docker-compose.prod.yml - Added dependencies and environment variables
5. backend/src/services/emailProcessor.js - Disabled auto-initialization
6. backend/server.js - Added email initialization and improved health check
7. backend/.env.example - Created environment variable documentation

Deployment Steps

1. Ensure all environment variables are set according to .env.example
2. Build and deploy with docker-compose:

   docker-compose -f docker-compose.prod.yml build
   docker-compose -f docker-compose.prod.yml up -d
   

3. The backend will now:
   • Wait for PostgreSQL to be ready
   • Run migrations automatically
   • Initialize all services in proper order
   • Provide health status at /api/health

Verification

Check deployment health:

curl http://localhost/api/health

Expected response:

{
  "status": "ok",
  "database": "connected",
  "timestamp": "2025-07-13T20:30:00.000Z"
}

Email Configuration

Email service requires configuration in the database. If email is not configured:

• The service will log a warning but continue running
• Emails will be queued but not sent
• Configure email settings in the admin panel after deployment

PostgreSQL Connection Fix

Issue: "no pg_hba.conf entry for host"

This error occurs when PostgreSQL requires SSL but the client connects without encryption.

Solution:

• Disabled SSL requirement for PostgreSQL in Docker environment (ssl=off)
• Added proper authentication method (scram-sha-256)
• This is acceptable for internal Docker networks where all traffic is isolated

Security Note:

For production deployments exposed to the internet:

1. Use SSL certificates for PostgreSQL
2. Or ensure the database is only accessible within the Docker network
3. Never expose PostgreSQL port (5432) directly to the internet