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

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

### 2. Build and Run with Docker Compose

```bash
# 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
```bash
# Run with mounted .env.local for easy configuration changes
docker-compose up
```

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

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

### Clear Redis Cache
```bash
# 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
```bash
# 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
```bash
# Create backup
docker exec psa-utils-redis redis-cli BGSAVE
docker cp psa-utils-redis:/data/dump.rdb ./redis-backup.rdb
```

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