wulf-pulse/DOCKER_README.md

Docker Setup for PSA-Utils

This application is configured to run in Docker with custom ports to avoid conflicts with other services.

Port Configuration

• Frontend/Backend (Next.js): Port 3100 (instead of default 3000)
• Redis Cache: Port 6380 (instead of default 6379)

Quick Start

1. Copy Environment Variables

cp .env.local .env.docker
# Edit .env.docker with your actual API credentials

2. Build and Run with Docker Compose

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

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Stop and remove volumes (clears Redis cache)
docker-compose down -v

3. Access the Application

Open your browser and navigate to: http://localhost:3100

Docker Services

Application Service

• Container Name: psa-utils-app
• Port: 3100
• Features:
  • Multi-stage build for optimized image size
  • Runs as non-root user for security
  • Automatic restart on failure
  • Environment variables passed from docker-compose

Redis Cache Service

• Container Name: psa-utils-redis
• Port: 6380
• Features:
  • Persistent data storage
  • Append-only file for durability
  • Health checks
  • Automatic restart on failure

Caching Strategy

The application implements Redis caching for API responses:

• Addigy Devices: Cached for 5 minutes
• Addigy Policies: Cached for 5 minutes
• Autotask Tickets: Can be cached (add to route)
• Autotask Companies: Can be cached (add to route)

Cache keys are structured as: service:entity:filter1:filter2

Example: addigy:devices:all:online

Development vs Production

Development Mode

# Run with mounted .env.local for easy configuration changes
docker-compose up

Production Mode

# Build with embedded environment variables
docker build --build-arg NODE_ENV=production -t psa-utils:latest .

# Run with environment file
docker run -d \
  --name psa-utils \
  -p 3100:3100 \
  --env-file .env.production \
  psa-utils:latest

Monitoring

Check Service Health

# Check if services are running
docker-compose ps

# Check Redis connection
docker exec psa-utils-redis redis-cli ping

# Monitor Redis cache
docker exec psa-utils-redis redis-cli monitor

# View cache keys
docker exec psa-utils-redis redis-cli keys "*"

View Logs

# All services
docker-compose logs -f

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

Troubleshooting

Port Already in Use

If ports 3100 or 6380 are already in use, modify the port mappings in docker-compose.yml:

services:
  app:
    ports:
      - "3200:3100"  # Change 3200 to your desired port
  redis:
    ports:
      - "6381:6379"  # Change 6381 to your desired port

Clear Redis Cache

# Connect to Redis and flush
docker exec psa-utils-redis redis-cli FLUSHDB

# Or restart with volume removal
docker-compose down -v
docker-compose up -d

Environment Variables Not Loading

Ensure your .env.local file exists and contains all required variables:

• AUTOTASK_* credentials
• DATTO_RMM_* credentials
• ADDIGY_* credentials
• REDIS_URL (set automatically in Docker)

Build Errors

# Clean build
docker-compose build --no-cache

# Remove all containers and images
docker-compose down
docker system prune -a

Performance Optimization

Redis Configuration

The Redis cache is configured with:

• AOF persistence for durability
• 5-minute TTL for most cached data
• Automatic retry on connection failure
• Health checks every 5 seconds

Next.js Optimization

• Standalone output mode for smaller Docker images
• Multi-stage build reduces final image size
• Static assets served efficiently
• Production optimizations enabled

Security Considerations

1. Non-root User: Application runs as nextjs user (UID 1001)
2. Environment Variables: Sensitive data kept in .env files, not in images
3. Network Isolation: Services communicate via Docker network
4. Port Mapping: Only necessary ports exposed to host
5. Redis Security: Redis only accessible within Docker network

Backup and Restore

Backup Redis Data

# Create backup
docker exec psa-utils-redis redis-cli BGSAVE
docker cp psa-utils-redis:/data/dump.rdb ./redis-backup.rdb

Restore Redis Data

# Restore backup
docker cp ./redis-backup.rdb psa-utils-redis:/data/dump.rdb
docker-compose restart redis