UptimeKuma-DiscordBot/DOCKER_SETUP.md

Docker Setup for UptimeKuma Discord Bot

This guide will help you containerize and run the UptimeKuma Discord Bot using Docker and Docker Compose.

Prerequisites

• Docker and Docker Compose installed on your system
• Uptime Kuma instance running and accessible
• Discord bot application created

Quick Start

1. Clone the repository

   git clone <repository-url>
   cd UptimeKuma-DiscordBot
   

2. Configure environment variables

   cp env.example .env
   

   Edit the .env file with your actual values:

   # Discord Bot Configuration
   DISCORD_TOKEN=your_discord_bot_token_here
   GUILD_ID=your_discord_guild_id_here
   CHANNEL_ID=your_discord_channel_id_here
   CLIENT_ID=your_discord_client_id_here
   UPDATE_TIME=30
   
   # Uptime Kuma Configuration
   UPTIME_KUMA_URL=https://your-uptime-kuma-instance.com/metrics
   UPTIME_KUMA_API_KEY=your_uptime_kuma_api_key_here
   

3. Build and start the containers

   docker-compose up -d
   

4. Check the logs

   docker-compose logs -f
   

Configuration Details

Environment Variables

Variable	Description	Required
DISCORD_TOKEN	Your Discord bot token	Yes
GUILD_ID	Discord server (guild) ID	Yes
CHANNEL_ID	Discord channel ID for status messages	Yes
CLIENT_ID	Discord bot client ID	Yes
UPDATE_TIME	Update frequency in seconds (default: 30)	No
UPTIME_KUMA_URL	Full URL to your Uptime Kuma metrics endpoint	Yes
UPTIME_KUMA_API_KEY	API key from Uptime Kuma dashboard	Yes

Services

Discord Bot (discord-bot)

• Image: Built from Bot/Dockerfile
• Port: Internal only (no external port)
• Health Check: Node.js process check
• Dependencies: web-backend

Web Backend (web-backend)

• Image: Built from Web/Dockerfile
• Port: 8080 (external) → 80 (internal)
• Health Check: HTTP endpoint check
• Access: http://localhost:8080/back-end.php

Docker Commands

Build and Start

# Build and start all services
docker-compose up -d

# Build and start with rebuild
docker-compose up -d --build

# Start specific service
docker-compose up -d discord-bot

Management

# View logs
docker-compose logs -f
docker-compose logs -f discord-bot
docker-compose logs -f web-backend

# Stop services
docker-compose down

# Stop and remove volumes
docker-compose down -v

# Restart services
docker-compose restart

# Update services
docker-compose pull
docker-compose up -d

Debugging

# Execute shell in running container
docker-compose exec discord-bot sh
docker-compose exec web-backend bash

# View container status
docker-compose ps

# View resource usage
docker stats

Troubleshooting

Common Issues

1. Docker build fails with npm ci error

   npm error The `npm ci` command can only install with an existing package-lock.json
   

   Solution: The Dockerfile uses npm install instead of npm ci to work without a lock file.

2. Bot not connecting to Discord

   • Verify DISCORD_TOKEN is correct
   • Check Discord bot permissions
   • Ensure bot is invited to the server

3. Backend not responding

   • Verify UPTIME_KUMA_URL and UPTIME_KUMA_API_KEY
   • Check Uptime Kuma instance accessibility
   • Test API endpoint manually: curl http://localhost:8080/back-end.php

4. Permission errors

   • Ensure Docker has proper permissions
   • Check file ownership in mounted volumes

5. Container health checks failing

   • Check logs: docker-compose logs
   • Verify all environment variables are set
   • Test individual services

Health Checks

Both services include health checks:

• Discord Bot: Checks if Node.js process is running
• Web Backend: Checks if PHP endpoint responds

View health status:

docker-compose ps

Logs

Monitor logs in real-time:

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f discord-bot
docker-compose logs -f web-backend

# Last 100 lines
docker-compose logs --tail=100

Security Considerations

• Both containers run as non-root users
• Environment variables are used instead of hardcoded secrets
• Network isolation between services
• Health checks for monitoring

Production Deployment

For production deployment:

1. Use Docker secrets for sensitive data
2. Set up reverse proxy (nginx/traefik) for SSL termination
3. Configure log rotation and monitoring
4. Use Docker Swarm or Kubernetes for orchestration
5. Set up backup strategies for persistent data

Example Production docker-compose.yml

version: '3.8'
services:
  discord-bot:
    # ... existing config ...
    deploy:
      replicas: 1
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    secrets:
      - discord_token
      - uptime_kuma_api_key

  web-backend:
    # ... existing config ...
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3

secrets:
  discord_token:
    external: true
  uptime_kuma_api_key:
    external: true

Support

For issues and questions:

• Check the logs first: docker-compose logs -f
• Verify configuration: docker-compose config
• Test individual services
• Review this documentation

Contributing

When contributing Docker-related changes:

1. Test with docker-compose up -d --build
2. Verify health checks pass
3. Test with different environment configurations
4. Update this documentation if needed