maternal-app/PRODUCTION_DEPLOYMENT.md

ParentFlow Production Deployment Guide

Target Server: 10.0.0.240 Deployment Method: PM2 + Docker Last Updated: October 6, 2025

Overview

Production deployment uses a hybrid approach:

• Docker Compose: For databases (PostgreSQL, Redis, MongoDB, MinIO)
• PM2: For application services (Backend, Frontend)

Architecture

┌─────────────────────────────────────────────┐
│  Server: 10.0.0.240                         │
├─────────────────────────────────────────────┤
│  PM2 Processes:                             │
│    - Backend:  Port 3020 (Node.js/NestJS)   │
│    - Frontend: Port 3030 (Next.js)          │
├─────────────────────────────────────────────┤
│  Docker Containers:                         │
│    - PostgreSQL: Port 5432                  │
│    - Redis:      Port 6379                  │
│    - MongoDB:    Port 27017                 │
│    - MinIO:      Port 9000 (API)            │
│                  Port 9001 (Console)        │
└─────────────────────────────────────────────┘
         ↓                    ↓
   api.parentflowapp.com   web.parentflowapp.com

Prerequisites

1. Install Required Software

# Install Node.js 18+ and npm
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PM2 globally
sudo npm install -g pm2

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

2. Clone Repository

cd /root
git clone https://git.noru1.ro/andrei/maternal-app.git
cd maternal-app

3. Install Dependencies

# Backend dependencies
cd maternal-app/maternal-app-backend
npm install

# Frontend dependencies
cd ../../maternal-web
npm install
cd ../..

Configuration

1. Environment Variables

Copy the example environment file and update with production values:

cp .env.production.example .env.production
nano .env.production

Critical variables to update:

• POSTGRES_PASSWORD: Strong password for PostgreSQL
• REDIS_PASSWORD: Strong password for Redis
• MONGO_PASSWORD: Strong password for MongoDB
• JWT_SECRET: 64-character random string
• JWT_REFRESH_SECRET: Different 64-character random string
• OPENAI_API_KEY: Your OpenAI API key (for AI features)

Generate secure secrets:

# Generate JWT secrets
openssl rand -base64 64
openssl rand -base64 64

2. Update ecosystem.config.js

Ensure the production environment variables in ecosystem.config.js match your .env.production file.

3. Configure Nginx (Reverse Proxy)

Create Nginx configuration for domain routing:

# /etc/nginx/sites-available/parentflow

# Backend API
server {
    listen 80;
    server_name api.parentflowapp.com;

    location / {
        proxy_pass http://localhost:3020;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Frontend
server {
    listen 80;
    server_name web.parentflowapp.com;

    location / {
        proxy_pass http://localhost:3030;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/parentflow /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4. SSL Certificates (Optional but Recommended)

# Install Certbot
sudo apt-get install certbot python3-certbot-nginx

# Obtain certificates
sudo certbot --nginx -d api.parentflowapp.com -d web.parentflowapp.com

Deployment

First-Time Deployment

cd /root/maternal-app

# Start production environment
./start-production.sh

The script will:

1. ✅ Start Docker containers (databases)
2. ✅ Wait for databases to be healthy
3. ✅ Run database migrations
4. ✅ Build backend (if needed)
5. ✅ Build frontend (if needed)
6. ✅ Start PM2 processes
7. ✅ Verify all services

Subsequent Deployments

cd /root/maternal-app

# Pull latest changes
git pull origin main

# Rebuild applications
cd maternal-app/maternal-app-backend
npm install
npm run build

cd ../../maternal-web
npm install
npm run build

cd ../..

# Restart PM2 processes
pm2 restart all

# Or use the full restart script
./stop-production.sh
./start-production.sh

Management Commands

PM2 Commands

# View process status
pm2 status

# View logs
pm2 logs

# View specific service logs
pm2 logs parentflow-backend
pm2 logs parentflow-frontend

# Restart services
pm2 restart all
pm2 restart parentflow-backend
pm2 restart parentflow-frontend

# Stop services
pm2 stop all

# Delete processes
pm2 delete all

# Save PM2 process list
pm2 save

# Setup PM2 to start on system boot
pm2 startup
pm2 save

Docker Commands

# View running containers
docker ps

# View logs
docker logs parentflow-postgres-prod
docker logs parentflow-redis-prod
docker logs parentflow-mongodb-prod
docker logs parentflow-minio-prod

# Follow logs in real-time
docker logs -f parentflow-postgres-prod

# Access database shell
docker exec -it parentflow-postgres-prod psql -U parentflow_user -d parentflow_production

# Access Redis CLI
docker exec -it parentflow-redis-prod redis-cli -a parentflow_redis_password_2024

# Access MongoDB shell
docker exec -it parentflow-mongodb-prod mongo -u parentflow_admin -p parentflow_mongo_password_2024

# Stop all containers
docker-compose -f docker-compose.production.yml down

# Stop and remove volumes (WARNING: deletes data)
docker-compose -f docker-compose.production.yml down -v

Application Management

# Start production
./start-production.sh

# Stop production
./stop-production.sh

# Check migration status
cd maternal-app/maternal-app-backend
./scripts/check-migrations.sh

# Run migrations manually
./scripts/master-migration.sh

Monitoring

Health Checks

• Backend: http://localhost:3020/api/health
• Frontend: http://localhost:3030
• MinIO Console: http://localhost:9001

Log Files

PM2 logs are stored in:

• ~/.pm2/logs/parentflow-backend-out.log
• ~/.pm2/logs/parentflow-backend-error.log
• ~/.pm2/logs/parentflow-frontend-out.log
• ~/.pm2/logs/parentflow-frontend-error.log

Docker logs via:

docker logs <container-name>

System Resources

# Monitor PM2 processes
pm2 monit

# Monitor Docker containers
docker stats

# System resources
htop

Backup Strategy

Database Backups

# PostgreSQL backup
docker exec parentflow-postgres-prod pg_dump -U parentflow_user parentflow_production > backup-$(date +%Y%m%d).sql

# Restore PostgreSQL
cat backup-20251006.sql | docker exec -i parentflow-postgres-prod psql -U parentflow_user -d parentflow_production

# MongoDB backup
docker exec parentflow-mongodb-prod mongodump --username parentflow_admin --password parentflow_mongo_password_2024 --out /data/backup

# Redis backup (automatic with AOF persistence)
docker exec parentflow-redis-prod redis-cli -a parentflow_redis_password_2024 BGSAVE

Automated Backups

Add to crontab:

# Daily database backup at 2 AM
0 2 * * * /root/maternal-app/scripts/backup-database.sh

Troubleshooting

Backend Won't Start

# Check logs
pm2 logs parentflow-backend --err

# Check if port is already in use
lsof -i:3020

# Verify database connection
docker exec -it parentflow-postgres-prod psql -U parentflow_user -d parentflow_production -c "SELECT version();"

Frontend Won't Start

# Check logs
pm2 logs parentflow-frontend --err

# Rebuild frontend
cd maternal-web
rm -rf .next
npm run build

Database Connection Issues

# Check if containers are running
docker ps

# Check container health
docker inspect parentflow-postgres-prod --format='{{.State.Health.Status}}'

# View container logs
docker logs parentflow-postgres-prod

Migrations Failed

# Check migration status
cd maternal-app/maternal-app-backend
./scripts/check-migrations.sh

# Manually run specific migration
PGPASSWORD=parentflow_secure_password_2024 psql -h localhost -p 5432 -U parentflow_user -d parentflow_production -f src/database/migrations/V001_create_core_auth.sql

Security Checklist

• Updated all default passwords in .env.production
• Generated secure JWT secrets
• Configured firewall (ufw/iptables) to restrict database ports
• Enabled SSL certificates with Certbot
• Configured Nginx rate limiting
• Set up PM2 with non-root user (recommended)
• Enabled Docker container resource limits
• Configured backup strategy
• Set up monitoring/alerting

Performance Optimization

PM2 Cluster Mode

For better performance, run backend in cluster mode:

// ecosystem.config.js
{
  name: 'parentflow-backend',
  instances: 'max', // Use all CPU cores
  exec_mode: 'cluster',
  // ... other settings
}

Database Optimization

• Enable PostgreSQL connection pooling (already configured)
• Monitor slow queries
• Add indexes for frequently queried fields
• Configure Redis maxmemory policy

CI/CD Integration

See docs/REMAINING_FEATURES.md for Gitea Actions workflow setup for automated deployments to 10.0.0.240.

Support

For issues or questions:

• Check logs: pm2 logs and docker logs
• Review documentation: /root/maternal-app/docs/
• Check migration status: ./scripts/check-migrations.sh

---

Last Updated: October 6, 2025 Deployment Version: 1.0.0