honey-be/VPS_DEPLOYMENT_NOTES.md

# VPS Deployment Notes - Logging Configuration

## Automatic Setup (Docker - Recommended)

The Docker setup is **automatically configured** to use external logback-spring.xml. No manual setup needed!

### How It Works

1. **Dockerfile** automatically:
   - Copies logback-spring.xml to `/app/config/logback-spring.xml` in the container
   - Sets `LOGGING_CONFIG` and `LOG_DIR` environment variables
   - Configures Java to use external config

2. **docker-compose.inferno.yml** automatically:
   - Mounts `/opt/app/backend/config/logback-spring.xml` → `/app/config/logback-spring.xml` (editable on VPS)
   - Mounts `/opt/app/logs` → `/app/logs` (persistent log storage)
   - Sets environment variables

### Initial Setup (One-Time)

Run the setup script to extract logback-spring.xml:

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

Or run directly with bash:
```bash
bash scripts/setup-logging.sh
```

Or manually:

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

# Extract logback-spring.xml from JAR (if building on VPS)
unzip -p target/lottery-be-*.jar BOOT-INF/classes/logback-spring.xml > /opt/app/backend/config/logback-spring.xml

# Or copy from source
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
```

### Verify Configuration

After starting the container, check that external config is being used:

```bash
# Check container logs
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/
```

## Manual Setup (Non-Docker)

If you're not using Docker, follow these steps:

### 1. Extract logback-spring.xml from JAR

```bash
# Option 1: Extract from JAR
unzip -p lottery-be.jar BOOT-INF/classes/logback-spring.xml > /opt/lottery-be/logback-spring.xml

# Option 2: Copy from source code
scp logback-spring.xml user@vps:/opt/lottery-be/
```

### 2. Set Up Log Directory

```bash
# Create log directory
mkdir -p /var/log/lottery-be
chown lottery:lottery /var/log/lottery-be
chmod 755 /var/log/lottery-be
```

### 3. Update Your Startup Script/Service

Add these environment variables or system properties:

```bash
# In your startup script or systemd service:
export LOGGING_CONFIG=/opt/lottery-be/logback-spring.xml
export LOG_DIR=/var/log/lottery-be

java -jar lottery-be.jar
```

Or with system properties:

```bash
java -Dlogging.config=/opt/lottery-be/logback-spring.xml \
     -DLOG_DIR=/var/log/lottery-be \
     -jar lottery-be.jar
```

### 4. Verify External Config is Being Used

Check application startup logs for:
```
Loading configuration from: /opt/lottery-be/logback-spring.xml
```

If you see this, the external config is active.

## Changing Log Level at Runtime

### Quick Method (30 seconds to take effect)

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

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

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

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

**For non-Docker deployment:**
1. Edit the external logback-spring.xml:
   ```bash
   nano /opt/lottery-be/logback-spring.xml
   ```

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

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

4. Verify:
   ```bash
   tail -f /var/log/lottery-be/lottery-be.log
   ```

### Common Log Level Changes

**Enable DEBUG for entire app:**
```xml
<logger name="com.lottery" level="DEBUG"/>
```

**Enable DEBUG for specific service:**
```xml
<logger name="com.lottery.lottery.service.GameRoomService" level="DEBUG"/>
```

**Enable DEBUG for WebSocket:**
```xml
<logger name="com.lottery.lottery.controller.GameWebSocketController" level="DEBUG"/>
```

**Change root level (affects everything):**
```xml
<root level="DEBUG">
```

## Important Notes

- **Default log level**: INFO (good for production)
- **High-traffic services**: WARN (GameRoomService, WebSocketController)
- **Auto-reload**: Changes take effect within 30 seconds
- **No restart needed**: Runtime log level changes work without restarting the app
- **Log location (Docker)**: `/opt/app/logs/` on VPS (mounted to `/app/logs` in container)
- **Log location (Non-Docker)**: `/var/log/lottery-be/` (or `./logs/` if LOG_DIR not set)
- **Config location (Docker)**: `/opt/app/backend/config/logback-spring.xml` on VPS
- **Config location (Non-Docker)**: `/opt/lottery-be/logback-spring.xml` (or your custom path)

## Troubleshooting

**If external config is not being used:**
1. Check the path is correct
2. Verify file permissions (readable by application user)
3. Check startup logs for errors
4. Ensure `-Dlogging.config=` or `LOGGING_CONFIG` is set correctly

**If log level changes don't work:**
1. Verify `scan="true" scanPeriod="30 seconds"` is in logback-spring.xml
2. Check for XML syntax errors
3. Wait 30 seconds after saving
4. Check application logs for Logback errors