Microsoft-Rewards-Bot/docs/docker.md

🐳 Docker Guide

Run the bot in a containerized environment with built-in cron scheduling.

---

⚡ Quick Start

1. Create required files

   • src/accounts.jsonc with your credentials
   • src/config.jsonc (optional, defaults apply if missing)

2. Start the container

   docker compose up -d
   

3. Watch logs

   docker logs -f microsoft-rewards-script
   

The container runs with cron scheduling enabled by default. Configure schedule via environment variables.

---

🎯 What's Included

• ✅ Chromium Headless Shell — Lightweight browser runtime
• ✅ Built-in Cron — Automated scheduling inside container
• ✅ Volume Mounts — Persistent sessions and configs
• ✅ Forced Headless Mode — Optimized for container stability
• ✅ Health Checks — Monitors cron daemon status
• ✅ Random Sleep — Spreads execution to avoid patterns

---

📁 Mounted Volumes

Host Path	Container Path	Purpose
./src/accounts.jsonc	/usr/src/microsoft-rewards-script/dist/accounts.jsonc	Account credentials (read-only)
./src/config.jsonc	/usr/src/microsoft-rewards-script/dist/config.jsonc	Configuration (read-only)
./sessions	/usr/src/microsoft-rewards-script/sessions	Cookies, fingerprints, and job-state
./reports	/usr/src/microsoft-rewards-script/reports	Run summaries and metrics

Edit compose.yaml to adjust paths or add additional mounts.

---

🌍 Environment Variables

Configure via compose.yaml:

services:
  microsoft-rewards-script:
    environment:
      # Required
      TZ: "America/Toronto"                   # Container timezone
      CRON_SCHEDULE: "0 7,16,20 * * *"       # When to run (crontab format)
      
      # Optional
      RUN_ON_START: "true"                    # Run immediately on startup
      NODE_ENV: "production"                  # Node environment
      
      # Randomization (spreads execution time)
      MIN_SLEEP_MINUTES: "5"                  # Min random delay (default: 5)
      MAX_SLEEP_MINUTES: "50"                 # Max random delay (default: 50)
      SKIP_RANDOM_SLEEP: "false"              # Set to "true" to disable
      
      # Safety
      STUCK_PROCESS_TIMEOUT_HOURS: "8"        # Kill stuck runs (default: 8h)

Key Variables

Variable	Default	Description
TZ	UTC	Container timezone for logs and scheduling
CRON_SCHEDULE	Required	Cron expression (use crontab.guru)
RUN_ON_START	false	Run once immediately when container starts
MIN_SLEEP_MINUTES	5	Minimum random delay before execution
MAX_SLEEP_MINUTES	50	Maximum random delay before execution
SKIP_RANDOM_SLEEP	false	Disable randomization (not recommended)
STUCK_PROCESS_TIMEOUT_HOURS	8	Timeout for stuck processes

---

🕐 Cron Schedule Examples

Schedule	Description	Cron Expression
Daily at 09:00	Single daily run	0 9 * * *
Three times daily	07:00, 16:00, 20:00	0 7,16,20 * * *
Every 6 hours	Four runs per day	0 */6 * * *
Weekdays at 08:00	Monday–Friday only	0 8 * * 1-5
Twice daily	09:00 and 21:00	0 9,21 * * *

Validate expressions: crontab.guru

---

🔧 Common Commands

# Start container
docker compose up -d

# View logs (follow)
docker logs -f microsoft-rewards-script

# View last 100 lines
docker logs --tail 100 microsoft-rewards-script

# Stop container
docker compose down

# Rebuild image (after code changes)
docker compose build --no-cache
docker compose up -d

# Restart container
docker compose restart

# Check container status
docker compose ps

---

🛠️ Troubleshooting

Problem	Solution
"accounts.jsonc not found"	Ensure file exists at ./src/accounts.jsonc
"Browser launch failed"	Verify FORCE_HEADLESS=1 is set (automatic in Dockerfile)
"Permission denied"	Fix file permissions: chmod 644 src/*.jsonc
Cron not running	Check logs for "Cron configured" message
Wrong timezone	Update TZ in compose.yaml and restart
No output in logs	Wait for cron schedule or set RUN_ON_START=true

Debug Container

# Enter container shell
docker exec -it microsoft-rewards-script /bin/bash

# Check Node.js version
docker exec -it microsoft-rewards-script node --version

# Inspect mounted config
docker exec -it microsoft-rewards-script cat /usr/src/microsoft-rewards-script/dist/config.jsonc

# Check environment variables
docker exec -it microsoft-rewards-script printenv | grep -E "TZ|CRON"

# View cron configuration
docker exec -it microsoft-rewards-script crontab -l

# Check if cron is running
docker exec -it microsoft-rewards-script ps aux | grep cron

---

<EFBFBD> Health Check

The container includes a health check that monitors the cron daemon:

healthcheck:
  test: ["CMD", "sh", "-c", "pgrep cron > /dev/null || exit 1"]
  interval: 60s
  timeout: 10s
  retries: 3
  start_period: 30s

Check health status:

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

---

⚠️ Important Notes

Platform Compatibility

The Docker build automatically generates platform-specific dependencies for the target architecture:

• ✅ Windows (x86_64) — Fully supported
• ✅ Linux (x86_64) — Fully supported
• ✅ Raspberry Pi (ARM64) — Fully supported
• ✅ macOS (ARM64/Apple Silicon) — Fully supported

The build process regenerates package-lock.json inside the container to ensure native dependencies (Playwright, etc.) match the target platform. This means:

• No cross-platform compatibility issues
• Native performance on all architectures
• Raspberry Pi users won't encounter binary mismatch errors

Headless Mode Required

Docker containers must run in headless mode. The Dockerfile automatically sets FORCE_HEADLESS=1. Do not disable this.

Random Sleep Behavior

• Enabled by default to avoid detection patterns
• Adds 5-50 minutes random delay before each run
• Disable only for testing: SKIP_RANDOM_SLEEP=true
• First run (when RUN_ON_START=true) skips random sleep

---

<EFBFBD> Resource Limits

Recommended settings in compose.yaml:

services:
  microsoft-rewards-script:
    mem_limit: 4g     # Maximum RAM
    cpus: 2           # CPU cores

Adjust based on your system and number of accounts.

---

🔒 Security Hardening

The compose file includes security measures:

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

Volumes are mounted read-only (:ro) for credentials to prevent tampering.

---

📚 Next Steps

Need 2FA setup?
→ Accounts & TOTP Guide

Want notifications?
→ Discord Webhooks
→ NTFY Push Alerts

Need proxy configuration?
→ Proxy Setup

External scheduling?
→ Scheduling Guide

---

← Back to Hub | Getting Started