honey-be/DOCKER_LOGGING_SETUP.md

# Docker Logging Setup - Automatic Configuration

## Overview

The Docker setup is **automatically configured** to use external `logback-spring.xml` for runtime log level changes. No manual configuration needed!

## How It Works

### 1. Dockerfile Configuration

Both `Dockerfile` and `Dockerfile.inferno` automatically:
- Copy `logback-spring.xml` to `/app/config/logback-spring.xml` in the container
- Create `/app/logs` directory for log files
- Set default environment variables:
  - `LOGGING_CONFIG=/app/config/logback-spring.xml`
  - `LOG_DIR=/app/logs`
- Configure Java to use external config via `-Dlogging.config` and `-DLOG_DIR`

### 2. Docker Compose Configuration

Both `docker-compose.inferno.yml` and `docker-compose.prod.yml` automatically:
- **Mount external config**: `/opt/app/backend/config/logback-spring.xml` → `/app/config/logback-spring.xml` (read-write, editable on VPS)
- **Mount logs directory**: `/opt/app/logs` → `/app/logs` (persistent storage)
- **Set environment variables**: `LOGGING_CONFIG` and `LOG_DIR`

## Initial Setup (One-Time)

### Option 1: Use Setup Script (Recommended)

```bash
cd /opt/app/backend
# Make script executable (if not already)
chmod +x scripts/setup-logging.sh
# Run the script
./scripts/setup-logging.sh
```

This script will:
1. Create `/opt/app/backend/config` directory
2. Create `/opt/app/logs` directory
3. Extract `logback-spring.xml` from JAR (if available)
4. Set proper permissions

### Option 2: Manual Setup

```bash
# Create directories
mkdir -p /opt/app/backend/config
mkdir -p /opt/app/logs

# Extract logback-spring.xml from JAR
cd /opt/app/backend
unzip -p target/lottery-be-*.jar BOOT-INF/classes/logback-spring.xml > /opt/app/backend/config/logback-spring.xml

# Or copy from source (if building from source on VPS)
cp src/main/resources/logback-spring.xml /opt/app/backend/config/logback-spring.xml

# Set permissions
chmod 644 /opt/app/backend/config/logback-spring.xml
chmod 755 /opt/app/logs
```

## Usage

### Start Application

Just start Docker Compose as usual:

```bash
cd /opt/app/backend
docker compose -f docker-compose.inferno.yml up -d
```

The external logging configuration is **automatically active** - no additional steps needed!

### Change Log Level at Runtime

1. **Edit the mounted config file**:
   ```bash
   nano /opt/app/backend/config/logback-spring.xml
   ```

2. **Change log level** (example: enable DEBUG):
   ```xml
   <logger name="com.lottery" level="DEBUG"/>
   ```

3. **Save the file**. Logback will automatically reload within 30 seconds.

4. **Verify**:
   ```bash
   # View logs from VPS
   tail -f /opt/app/logs/lottery-be.log
   
   # Or from inside container
   docker exec lottery-backend tail -f /app/logs/lottery-be.log
   ```

### View Logs

```bash
# Real-time monitoring
tail -f /opt/app/logs/lottery-be.log

# Search for errors
grep -i "error" /opt/app/logs/lottery-be.log

# View last 100 lines
tail -n 100 /opt/app/logs/lottery-be.log

# From inside container
docker exec lottery-backend tail -f /app/logs/lottery-be.log
```

## File Locations

### On VPS (Host)
- **Config file**: `/opt/app/backend/config/logback-spring.xml` (editable)
- **Log files**: `/opt/app/logs/lottery-be.log` and rolled files

### Inside Container
- **Config file**: `/app/config/logback-spring.xml` (mounted from host)
- **Log files**: `/app/logs/lottery-be.log` (mounted to host)

## Verification

### Check Configuration is Active

```bash
# Check container logs for logback initialization
docker logs lottery-backend | grep -i "logback\|logging"

# Check mounted file exists
ls -la /opt/app/backend/config/logback-spring.xml

# Check log directory
ls -la /opt/app/logs/

# Check environment variables in container
docker exec lottery-backend env | grep LOG
```

### Expected Output

You should see:
- `LOGGING_CONFIG=/app/config/logback-spring.xml`
- `LOG_DIR=/app/logs`
- Log files appearing in `/opt/app/logs/`

## Benefits

✅ **No manual configuration needed** - Works automatically with Docker  
✅ **Runtime log level changes** - Edit file, changes take effect in 30 seconds  
✅ **No container restart required** - Changes apply without restarting  
✅ **Persistent logs** - Logs survive container restarts  
✅ **Editable config** - Edit logback-spring.xml directly on VPS  

## Troubleshooting

### Config file not found

```bash
# Check if file exists
ls -la /opt/app/backend/config/logback-spring.xml

# If missing, extract from JAR or copy from source
./scripts/setup-logging.sh
```

### Logs not appearing

```bash
# Check log directory permissions
ls -ld /opt/app/logs

# Check container can write
docker exec lottery-backend ls -la /app/logs

# Check disk space
df -h /opt/app/logs
```

### Log level changes not working

1. Verify `scan="true" scanPeriod="30 seconds"` in logback-spring.xml
2. Check for XML syntax errors
3. Wait 30 seconds after saving
4. Check container logs for Logback errors:
   ```bash
   docker logs lottery-backend | grep -i "logback\|error"
   ```

## Summary

**You don't need to do anything manually!** The Docker setup automatically:
- Uses external logback-spring.xml
- Mounts it as a volume (editable on VPS)
- Sets all required environment variables
- Configures log directory

Just run `docker compose up` and you're ready to go! 🚀