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:

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 scripts/setup-logging.sh

Or manually:

# 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:

# 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

# 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

# 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:

# 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:

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:

   nano /opt/app/backend/config/logback-spring.xml
   

2. Change the level (example: enable DEBUG):

   <logger name="com.lottery" level="DEBUG"/>
   

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

4. Verify:

   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:

   nano /opt/lottery-be/logback-spring.xml
   

2. Change the level (example: enable DEBUG):

   <logger name="com.lottery" level="DEBUG"/>
   

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

4. Verify:

   tail -f /var/log/lottery-be/lottery-be.log
   

Common Log Level Changes

Enable DEBUG for entire app:

<logger name="com.lottery" level="DEBUG"/>

Enable DEBUG for specific service:

<logger name="com.lottery.lottery.service.GameRoomService" level="DEBUG"/>

Enable DEBUG for WebSocket:

<logger name="com.lottery.lottery.controller.GameWebSocketController" level="DEBUG"/>

Change root level (affects everything):

<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