Lorentz Hinrichsen
f429f3af54
- Implemented complete Addigy API v2 client with authentication via x-api-key - Added device and policy endpoints with automatic org ID resolution - Created field mapping from snake_case to Title Case for UI compatibility - Handles nested 'facts' response structure from Addigy devices API - Added comprehensive API documentation in ADDIGY_API_GUIDE.md - Multi-stage Dockerfile with optimized production build - Custom ports: App on 3100, Redis on 6380 (avoids conflicts) - Docker Compose orchestration with health checks - Standalone Next.js output for smaller container images - Non-root user execution for security - Implemented Redis caching layer for API responses - 5-minute TTL with graceful fallback if Redis unavailable - Cache key structure: service:entity:filter1:filter2 - Applied to Addigy devices endpoint with cache hit/miss logging - Fixed TypeScript strict mode errors for production builds - Added null safety checks with optional chaining throughout API routes - Wrapped useSearchParams in Suspense boundary for Next.js 15+ compatibility - Fixed type assertions for dynamic API responses - Corrected Set<string> type mismatches in device comparison logic - Created DOCKER_README.md with complete deployment guide - Updated ADDIGY_API_GUIDE.md with real-world API patterns - Documented response structures, field mappings, and troubleshooting - Next.js 16.0.0 with Turbopack - Redis 7 with AOF persistence - Podman/Docker compatible - TypeScript strict mode compliant
199 lines
4.4 KiB
Markdown
199 lines
4.4 KiB
Markdown
# 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
|
|
```
|