Microsoft-Rewards-Bot/docs/docker-deployment.md

Docker Deployment Guide

🐳 Quick Start

1. Build the Image

cd docker
docker build -t microsoft-rewards-bot -f Dockerfile ..

Or use the npm script:

npm run docker:build

2. Configure Environment

Edit docker/compose.yaml:

environment:
  TZ: "America/New_York"        # Your timezone
  CRON_SCHEDULE: "0 9 * * *"    # Daily at 9 AM
  RUN_ON_START: "true"          # Run immediately on start

3. Start the Container

cd docker
docker compose up -d

📋 Configuration Files

The container needs access to your configuration files via volume mounts:

volumes:
  - ../src/accounts.jsonc:/usr/src/microsoft-rewards-bot/dist/accounts.jsonc:ro
  - ../src/config.jsonc:/usr/src/microsoft-rewards-bot/dist/config.jsonc:ro
  - ./sessions:/usr/src/microsoft-rewards-bot/dist/browser/sessions

Before starting:

1. Create src/accounts.jsonc (copy from src/accounts.example.jsonc)
2. Edit src/config.jsonc with your settings
3. (Optional) Create docker/sessions/ directory for persistent login

🔧 Environment Variables

Variable	Required	Default	Description
CRON_SCHEDULE	✅ Yes	N/A	Cron expression (e.g., 0 9 * * *)
TZ	❌ No	UTC	Timezone (e.g., America/New_York)
RUN_ON_START	❌ No	false	Run immediately on container start
SKIP_RANDOM_SLEEP	❌ No	false	Skip random delay before execution
MIN_SLEEP_MINUTES	❌ No	5	Minimum random delay (minutes)
MAX_SLEEP_MINUTES	❌ No	50	Maximum random delay (minutes)
STUCK_PROCESS_TIMEOUT_HOURS	❌ No	8	Kill stuck processes after N hours
PLAYWRIGHT_BROWSERS_PATH	🔒 Fixed	0	Use browsers in node_modules (DO NOT CHANGE)
FORCE_HEADLESS	🔒 Fixed	1	Headless mode (DO NOT CHANGE)
NODE_ENV	🔒 Fixed	production	Production environment (DO NOT CHANGE)

📅 Scheduling Examples

Use crontab.guru to create cron expressions.

Schedule	Cron Expression	Description
Daily at 9 AM	0 9 * * *	Once per day
Every 6 hours	0 */6 * * *	4 times daily
Twice daily (9 AM, 9 PM)	0 9,21 * * *	Morning & evening
Weekdays at 8 AM	0 8 * * 1-5	Monday-Friday only
Random time (7-8 AM)	0 7 * * * + random sleep	Use MIN_SLEEP_MINUTES/MAX_SLEEP_MINUTES

Example with Random Delay:

environment:
  CRON_SCHEDULE: "0 7 * * *"    # Start scheduling at 7 AM
  MIN_SLEEP_MINUTES: "0"        # No minimum delay
  MAX_SLEEP_MINUTES: "60"       # Up to 1 hour delay
  # Result: Runs between 7:00 AM - 8:00 AM randomly

🔍 Monitoring

View Logs

docker logs -f microsoft-rewards-bot

Check Container Status

docker ps -a | grep microsoft-rewards-bot

Health Check

docker inspect microsoft-rewards-bot --format='{{.State.Health.Status}}'

Expected output: healthy

Execute Commands Inside Container

# Check cron status
docker exec microsoft-rewards-bot crontab -l

# Check timezone
docker exec microsoft-rewards-bot date

# List running processes
docker exec microsoft-rewards-bot ps aux

🛠️ Troubleshooting

"Chromium not installed" After First Run

Symptoms:

• Bot works on first run
• Fails on subsequent scheduled runs with "Chromium not installed"

Root Cause: Fixed in latest version! Chromium browser files are now copied correctly from builder stage.

Solution:

# Rebuild with latest Dockerfile (includes fix)
docker build --no-cache -t microsoft-rewards-bot -f docker/Dockerfile ..
docker compose down
docker compose up -d

Verification: Check that Chromium is present in the container:

docker exec microsoft-rewards-bot ls -la /usr/src/microsoft-rewards-bot/node_modules/@playwright/

You should see browser-chromium/ directory.

Container Exits Immediately

Check logs:

docker logs microsoft-rewards-bot

Common causes:

1. Missing CRON_SCHEDULE: Set environment variable in compose.yaml
2. Invalid cron expression: Validate at https://crontab.guru
3. Permission issues: Ensure config files are readable

Fix:

# Update compose.yaml with correct CRON_SCHEDULE
docker compose down
docker compose up -d

Random Delays Not Working

Check environment variables:

docker exec microsoft-rewards-bot env | grep SLEEP

Verify run_daily.sh receives variables:

docker exec microsoft-rewards-bot cat docker/run_daily.sh

Test manually:

docker exec microsoft-rewards-bot docker/run_daily.sh

Timezone Incorrect

Check container timezone:

docker exec microsoft-rewards-bot date

Fix:

1. Update TZ in compose.yaml
2. Restart container:

docker compose restart

Verify:

docker exec microsoft-rewards-bot date
docker logs microsoft-rewards-bot | grep "Timezone:"

Health Check Failing

Check cron daemon:

docker exec microsoft-rewards-bot ps aux | grep cron

Expected output:

root         1  0.0  0.0   2576  1024 ?        Ss   12:00   0:00 cron -f

Restart container if missing:

docker compose restart

Sessions Not Persisting

Check volume mount:

docker inspect microsoft-rewards-bot | grep sessions

Verify local directory exists:

ls -la docker/sessions/

Fix permissions:

# Linux/Mac
chmod -R 755 docker/sessions/

# Windows
# No action needed (NTFS handles permissions)

Out of Memory Errors

Increase memory limit in compose.yaml:

mem_limit: 6g  # Increase from 4g

Restart:

docker compose down
docker compose up -d

Monitor memory usage:

docker stats microsoft-rewards-bot

🔄 Updates

Update to Latest Version

Method 1: Rebuild (Recommended)

# Pull latest code
git pull origin main

# Rebuild image
docker build --no-cache -t microsoft-rewards-bot -f docker/Dockerfile ..

# Restart container
docker compose down
docker compose up -d

Method 2: Auto-Update (If Enabled in config.jsonc) The bot can auto-update itself if update.enabled: true in config.jsonc. After auto-update, container will restart automatically (Docker restarts on exit).

Backup Before Update

# Backup sessions
cp -r docker/sessions/ docker/sessions.backup/

# Backup config
cp src/config.jsonc src/config.jsonc.backup
cp src/accounts.jsonc src/accounts.jsonc.backup

📊 Resource Usage

Typical resource consumption:

• CPU: 50-80% during active runs, <1% idle
• RAM: 1-3 GB during active runs, <100 MB idle
• Disk: ~500 MB (base image + browsers)
• Network: Minimal (<10 MB per run)

Recommended limits:

mem_limit: 4g
cpus: 2

🔐 Security Hardening

The default compose.yaml includes:

security_opt:
  - no-new-privileges:true  # Prevent privilege escalation

Additional hardening (optional):

security_opt:
  - no-new-privileges:true
  - seccomp:unconfined  # Only if Chromium fails to start
read_only: false  # Must be false (Chromium needs write access)
tmpfs:
  - /tmp
  - /root/.cache

🆘 Getting Help

If issues persist:

1. Check logs: docker logs -f microsoft-rewards-bot
2. Rebuild with no cache: docker build --no-cache ...
3. Verify Chromium: docker exec microsoft-rewards-bot ls -la node_modules/@playwright/
4. Discord Support: https://discord.gg/k5uHkx9mne
5. GitHub Issues: https://github.com/Obsidian-wtf/Microsoft-Rewards-Bot/issues

📚 Related Documentation

• Build System: docs/build-system.md
• Scheduling: src/scheduler/README.md
• Configuration: src/config.jsonc (inline comments)
• Accounts: docs/accounts.md

---

Last Updated: November 2025
Applies To: v2.56.7+