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

```bash
# 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

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

### 3. Install Dependencies

```bash
# 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:

```bash
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:
```bash
# 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:

```nginx
# /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:
```bash
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)

```bash
# 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

```bash
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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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:
```bash
docker logs <container-name>
```

### System Resources

```bash
# Monitor PM2 processes
pm2 monit

# Monitor Docker containers
docker stats

# System resources
htop
```

## Backup Strategy

### Database Backups

```bash
# 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:
```bash
# Daily database backup at 2 AM
0 2 * * * /root/maternal-app/scripts/backup-database.sh
```

## Troubleshooting

### Backend Won't Start

```bash
# 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

```bash
# Check logs
pm2 logs parentflow-frontend --err

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

### Database Connection Issues

```bash
# 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

```bash
# 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:

```javascript
// 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