uptime-kuma-discord-bot/README.md

# Uptime Kuma Discord Bot

A comprehensive Discord bot that integrates with [Uptime Kuma](https://github.com/louislam/uptime-kuma) to display real-time monitor status information in Discord channels.

## Features

- **Real-time Monitoring**: Socket.io connection with automatic updates
- **Slash Commands**: Configure everything directly from Discord with autocomplete
- **Rich Embeds**: Simple embeds with status indicators (green/red/yellow/blue circles)
- **Monitor Grouping**: Organize monitors into custom sections (Media, Gaming, etc.)
- **Persistent Configuration**: All settings saved automatically
- **Docker Support**: Full Docker and Docker Compose support
- **Fly.io Ready**: One-click deployment to Fly.io (free tier compatible)
- **Admin Controls**: Restrict commands to specific users
- **Auto-Reconnection**: Handles disconnections gracefully

## Commands

All configuration via simple, autocomplete-powered slash commands:

### Setup Commands
| Command | Description |
|---------|-------------|
| `/set-channel <channel>` | Set where to post status updates |
| `/set-title <title>` | Set the embed title (replaces "Uptime Kuma Status") |
| `/config` | Show full bot configuration and status |

### Monitor Commands
| Command | Description |
|---------|-------------|
| `/track <monitor>` | Add a monitor to tracking (autocomplete) |
| `/untrack <monitor>` | Remove a monitor from tracking (autocomplete) |
| `/track-all` | Track all available monitors |

### Group Commands
| Command | Description |
|---------|-------------|
| `/group-create <name>` | Create a new group (e.g., "Media Servers") |
| `/group-delete <group>` | Delete a group (autocomplete) |
| `/group-add-monitor <group> <monitor>` | Add monitor to group (both autocomplete) |
| `/group-remove-monitor <monitor>` | Remove monitor from its group (autocomplete) |
| `/groups` | List all groups and their monitors |

## Quick Start

### Deploy to Fly.io (Recommended)

See **[FLY_DEPLOY.md](FLY_DEPLOY.md)** for full instructions.

Super quick version:

```bash
fly launch --copy-config --auto-confirm --ha=false --name my-bot --now
fly secrets set DISCORD_BOT_TOKEN=xxx UPTIME_KUMA_URL=xxx UPTIME_KUMA_USERNAME=xxx UPTIME_KUMA_PASSWORD=xxx
# Then use /set-channel in Discord
```

### Self-Host with Docker

See **[QUICKSTART.md](QUICKSTART.md)** for detailed setup instructions.

**TL;DR:**
1. Create Discord bot and get token
2. Configure `.env` with bot token and Uptime Kuma credentials
3. Run: `docker-compose up -d` or `npm start`
4. Use `/set-channel` and `/track-all` in Discord

## Usage

### Basic Setup

```bash
/set-channel #status       # Set status channel
/set-title My Services     # Customize title (optional)
/track-all                 # Track all monitors
/config                    # Verify setup
```

### Organizing with Groups

```bash
/group-create Media Servers    # Create group
/group-add-monitor             # Assign monitors (autocomplete)
/groups                        # View organization
```

For detailed usage examples, see [QUICKSTART.md](QUICKSTART.md).

## Embed Preview

With groups configured, your embed looks like this:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Production Services

Overall Status: 87.5% Operational

🟢 Online: 7
🔴 Offline: 1
🟡 Pending: 0
🔵 Maintenance: 0

━━━━━━━━━━━━━━━━━━━━
Media Servers
🟢 Plex - UP
🟢 Jellyfin - UP

━━━━━━━━━━━━━━━━━━━━
Gaming Servers
🔴 Minecraft - DOWN
🟢 Valheim - UP

━━━━━━━━━━━━━━━━━━━━
Other Services
🟢 Website - UP 

Last updated: 2:30 PM
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Configuration

### Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `DISCORD_BOT_TOKEN` | Your Discord bot token | Yes | - |
| `UPTIME_KUMA_URL` | URL of your Uptime Kuma instance | Yes | `http://localhost:3001` |
| `UPTIME_KUMA_USERNAME` | Uptime Kuma username | Yes | - |
| `UPTIME_KUMA_PASSWORD` | Uptime Kuma password | Yes | - |
| `UPDATE_INTERVAL` | Update interval in seconds | No | `60` |
| `EMBED_COLOR` | Decimal color code | No | `5814783` |
| `ADMIN_USER_IDS` | Comma-separated Discord user IDs | No | `` (all users) |

### Setting Up Discord Bot

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" and name it
3. Go to "Bot" section, click "Add Bot", then "Reset Token" and copy it
4. Go to "OAuth2" then "URL Generator"
5. Select scopes: `bot` and `applications.commands`
6. Select permissions: `Send Messages`, `Embed Links`, `Read Message History`, `Use Slash Commands`
7. Open the generated URL to invite the bot to your server

### Getting Your Discord User ID (For Admin Access)

1. Enable Developer Mode (User Settings → Advanced → Developer Mode)
2. Right-click your username and select "Copy ID"
3. Add to `.env`: `ADMIN_USER_IDS=your_user_id`

## Advanced Features

### Monitor Groups

Create organized sections in your embed:
- **Media Servers**: Plex, Jellyfin, etc.
- **Gaming**: Minecraft, Valheim, etc.
- **Infrastructure**: Nginx, databases, etc.
- **Other Services**: Ungrouped monitors appear here

Monitors can only be in ONE group at a time. Assigning to a new group automatically removes from the old one.


## Docker Configuration

### Docker Network (Same Host as Uptime Kuma)

```bash
# Create network
docker network create uptime-kuma-network

# Connect Uptime Kuma
docker network connect uptime-kuma-network uptime-kuma

# Update docker-compose.yml (uncomment networks section)
# Update .env:
UPTIME_KUMA_URL=http://uptime-kuma:3001
```

### Persistent Data

Configuration saved to Docker volume `bot-data`:
- Channel ID
- Message IDs (for reuse)
- Tracked monitors
- Groups and assignments
- Custom title

## Security

1. **Secure `.env`**: Never commit to version control
2. **Restrict admins**: Set `ADMIN_USER_IDS` to specific users
3. **Dedicated account**: Create a bot-specific Uptime Kuma user
4. **Minimal permissions**: Only grant necessary Discord permissions

## Troubleshooting

### Bot doesn't post updates
- Use `/set-channel` to set a channel
- Use `/config` to verify setup
- Check bot permissions in that channel

### Commands don't appear
- Wait 5-10 minutes (Discord caches)
- Try kicking and re-inviting bot
- Restart Discord client

### "Permission denied" on commands
- Add your user ID to `ADMIN_USER_IDS`
- Restart bot
- Get ID: Right-click username → Copy ID

### Autocomplete doesn't show monitors
- Ensure bot is connected to Uptime Kuma
- Check `/config` for connection status
- View logs: `docker-compose logs -f`

### Bot creates new messages after restart
- This is fixed! Bot now reuses messages
- Message IDs saved to `data/bot-config.json`
- Check logs for message handling status

## Documentation Files

- **[README.md](README.md)** - This file
- **[QUICKSTART.md](QUICKSTART.md)** - Self-hosting setup guide
- **[FLY_DEPLOY.md](FLY_DEPLOY.md)** - Deploy to Fly.io (recommended)

## Tips

- Use `/config` to see everything at a glance
- Create groups BEFORE assigning monitors to them
- Use `/groups` to see your current organization
- `/track-all` then `/untrack` unwanted monitors is often faster

## Development

```bash
npm install
npm run dev  # Development mode with ts-node
```

## Project Structure

```
uptime-kuma-discord-bot/
├── src/
│   ├── config/
│   │   ├── config.ts          # Environment configuration
│   │   └── storage.ts         # Persistent configuration storage
│   ├── services/
│   │   ├── commands.service.ts  # Discord slash commands with autocomplete
│   │   ├── discord.service.ts   # Discord bot service
│   │   └── uptime-kuma.service.ts # Uptime Kuma Socket.io integration
│   ├── types/
│   │   └── uptime-kuma.ts     # TypeScript type definitions
│   ├── utils/
│   │   └── logger.ts          # Logging utility
│   └── index.ts               # Application entry point
├── data/                      # Persistent configuration (auto-created)
│   └── bot-config.json        # Stored settings and monitor groups
├── docker-compose.yml         # Docker Compose configuration
├── Dockerfile                 # Docker image definition
├── package.json               # Dependencies
└── tsconfig.json              # TypeScript configuration
```

## Why Not Use Uptime Kuma API Keys?

Uptime Kuma's [API Keys feature](https://github.com/louislam/uptime-kuma/wiki/API-Keys) (version >= 1.21.0) is designed for REST endpoints like Prometheus metrics, not Socket.io connections. This bot uses Socket.io for real-time monitor updates, which requires username/password authentication. API Keys are not supported for Socket.io authentication in Uptime Kuma.

## License

MIT License - see [LICENSE](LICENSE)

## Resources

- [Uptime Kuma](https://github.com/louislam/uptime-kuma)
- [Discord.js](https://discord.js.org/)
- [Socket.io](https://socket.io/)

## Support

If you encounter issues:
1. Check the logs: `docker-compose logs -f`
2. Verify your `.env` configuration
3. Try `/config` command to check connection status
4. Open an issue on GitHub with details