task-manager/DEPLOYMENT.md

TaskFlow - Docker Deployment Guide

This guide explains how to deploy TaskFlow using Docker with a separate PostgreSQL database.

Prerequisites

• Docker Engine 20.10 or later
• Docker Compose 2.0 or later
• At least 2GB of available RAM
• 10GB of available disk space

Quick Start

1. Environment Configuration

Create a .env file in the root directory:

cp .env.example .env

Edit the .env file with your configuration:

# Application Configuration
NODE_ENV=production
PORT=5000

# Database Configuration
POSTGRES_USER=taskflow
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_DB=taskflow
POSTGRES_PORT=5432

# Database URL (update with your credentials)
DATABASE_URL=postgresql://taskflow:your_secure_password_here@postgres:5432/taskflow

# Application Port (external mapping)
APP_PORT=5000

Important: Change the POSTGRES_PASSWORD to a secure password!

2. Start the Application

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Check service status
docker-compose ps

The application will be available at http://localhost:5000

3. Stop the Application

# Stop services
docker-compose down

# Stop and remove volumes (WARNING: This will delete all data!)
docker-compose down -v

Production Deployment

Using Docker Stack (Swarm Mode)

1. Initialize Docker Swarm (if not already done):

docker swarm init

2. Create a production .env file:

# Set secure credentials
export POSTGRES_PASSWORD="your_very_secure_password"
export POSTGRES_USER="taskflow"
export POSTGRES_DB="taskflow"

3. Deploy the stack:

docker stack deploy -c docker-compose.yml taskflow

4. Check stack status:

docker stack services taskflow
docker stack ps taskflow

5. View logs:

docker service logs taskflow_app
docker service logs taskflow_postgres

6. Remove the stack:

docker stack rm taskflow

Using External PostgreSQL Database

If you want to use an external PostgreSQL instance instead of the containerized one:

1. Update .env file:

DATABASE_URL=postgresql://username:password@your-db-host:5432/your-db-name

2. Modify docker-compose.yml to remove the postgres service:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    container_name: taskflow-app
    restart: unless-stopped
    environment:
      NODE_ENV: production
      DATABASE_URL: ${DATABASE_URL}
      PORT: 5000
    ports:
      - "${APP_PORT:-5000}:5000"

3. Start only the app service:

docker-compose up app -d

Database Management

Backup Database

# Create backup
docker exec taskflow-db pg_dump -U taskflow taskflow > backup_$(date +%Y%m%d_%H%M%S).sql

# Or using docker-compose
docker-compose exec postgres pg_dump -U taskflow taskflow > backup.sql

Restore Database

# Restore from backup
docker exec -i taskflow-db psql -U taskflow taskflow < backup.sql

# Or using docker-compose
docker-compose exec -T postgres psql -U taskflow taskflow < backup.sql

Access Database

# Connect to PostgreSQL shell
docker exec -it taskflow-db psql -U taskflow -d taskflow

# Or using docker-compose
docker-compose exec postgres psql -U taskflow -d taskflow

Run Migrations

The application automatically runs database migrations on startup. To manually trigger migrations:

# Inside the container
docker exec taskflow-app npm run db:push

# Or rebuild and restart
docker-compose up --build -d

Monitoring and Maintenance

Health Checks

Both services have health checks configured:

• App: http://localhost:5000/api/health
• Database: Automatic PostgreSQL health check

Check health status:

docker-compose ps

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f app
docker-compose logs -f postgres

# Last 100 lines
docker-compose logs --tail=100 app

Update Application

# Pull latest changes
git pull

# Rebuild and restart
docker-compose up --build -d

# Remove old images
docker image prune -f

Troubleshooting

Application won't start

1. Check logs: docker-compose logs app
2. Verify DATABASE_URL is correct
3. Ensure PostgreSQL is healthy: docker-compose ps

Database connection errors

1. Verify PostgreSQL is running: docker-compose ps postgres
2. Check connection string in .env
3. Ensure network connectivity: docker network inspect taskflow_taskflow-network

Port already in use

Change the APP_PORT in .env file:

APP_PORT=8080

Then restart: docker-compose up -d

Out of disk space

# Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Remove unused networks
docker network prune

Security Best Practices

1. Change default passwords in .env file
2. Use environment variables for sensitive data
3. Enable SSL/TLS for production databases
4. Restrict network access using firewall rules
5. Regular backups of database
6. Keep Docker images updated regularly
7. Use secrets management for production (Docker Secrets, Vault, etc.)

Performance Tuning

PostgreSQL

Edit docker-compose.yml to add PostgreSQL configuration:

postgres:
  command: postgres -c max_connections=200 -c shared_buffers=256MB

Application

Scale the application service:

docker-compose up -d --scale app=3

Support

For issues and questions:

• Check logs first: docker-compose logs
• Review this guide
• Check Docker and PostgreSQL documentation