CTFeed

A Discord bot that automatically tracks CTF (Capture The Flag) events from CTFtime.org and manages event workflows inside your guild.

Features

• Detect new, updated, and canceled CTFTime events
• Sends notifications
• Create/join event channels
• Manage events with slash commands and REST APIs

Prerequisites

Before getting started, you'll need:

• Python 3.13 and uv package manager
• Discord Bot Application with proper permissions
• Domain
• Docker and Docker compose (recommanded)

Setting Up Your Discord Bot

1. Visit the Discord Developer Portal and create a new application
2. Navigate to the "Bot" section and copy your bot token (keep this secure!)
3. Navigate to the "OAuth2" section and copy your Client ID and Client Secret (keep these secure!)
4. Configure the following scopes and bot permissions:
   • Scopes
     • applications.commands
     • bot
   • Bot Permissions
     • Manage Channels
     • Manage Roles
     • View Channels
     • Manage Events
     • Create Events
     • Send Messages
     • Create Public Threads
     • Create Private Threads
     • Send Messages in Threads
     • Manage Threads
     • Embed Links
     • Read Message History
     • Add Reactions
     • Use Slash Commands
     • Bypass Slowmode
5. Generate an invite link and add the bot to your Discord server

Domain

Follow the instructions here or the web interface may not work.

We suppose that your domain is example.com and you serve the frontend of the bot on bot.example.com.

Then you have to serve backend API on api.bot.example.com.

• frontend - bot.example.com
• backend - api.bot.example.com

Quick Start

The fastest way to get CTFeed running is through our automated Docker deployment.

Docker Deployment (Recommended)

Get up and running in just two commands:

git clone https://github.com/ICEDTEACTF/CTFeed && cd CTFeed
./setup_env.sh

The setup_env.sh script will:

• Check Docker requirements
• Help you create the .env file with Discord bot configuration
• Offer to run the bot with Docker immediately

Once setup is complete, manage your bot with:

./run.sh

Or run Docker commands directly:

sudo docker-compose up -d --build    # Run in background
sudo docker-compose up --build       # Run with live logs

Manual Setup

Prefer to set things up manually? Here's the traditional approach:

What You'll Need

• uv and Python 3.13
• Docker and Docker Compose

Install Dependencies

uv sync

Configure Your Environment

Start by copying the example configuration:

cp .env.example .env

Then edit the .env file with your specific settings:

| Variable | Description | |----------|-------------| | DISCORD_BOT_TOKEN | Discord bot token | | GUILD_ID | Target guild ID | | HTTP_SECRET_KEY | Session secret key for FastAPI | | HTTP_FRONTEND_URL | Frontend base URL (used for OAuth redirect) | | HTTP_COOKIE_DOMAIN | Cookie domain for session | | DISCORD_OAUTH2_CLIENT_ID | Discord OAuth2 client ID | | DISCORD_OAUTH2_CLIENT_SECRET | Discord OAuth2 client secret | | CHECK_INTERVAL_MINUTES | CTFTime polling interval | | DATABASE_URL | PostgreSQL database URL |

DISCORD_OAUTH2_REDIRECT_URI is derived from HTTP_FRONTEND_URL as HTTP_FRONTEND_URL/auth/login.

Discord-side config values are stored in database and set after launch:

• ANNOUNCEMENT_CHANNEL_ID
• CTF_CHANNEL_CATEGORY_ID
• ARCHIVE_CATEGORY_ID
• PM_ROLE_ID
• MEMBER_ROLE_ID

Launch the Bot

Choose your preferred method:

# With uv (recommended)
./startup.sh

# Or with Python directly
uvicorn --host 0.0.0.0 --port 5000 ctfeed:app

Docker Management

Interactive Management

Use our user-friendly script for easy bot management:

./run.sh

The run.sh script provides an interactive menu for Docker deployment options:

• Docker (background) - Recommended for production
• Docker (foreground) - See live logs
• Exit

Docker Command Reference

Docker command cheatsheet for this bot:

| Action | Command | Description | |--------|---------|-------------| | Start | sudo docker-compose up -d --build | Launch bot in background | | Monitor | sudo docker-compose logs -f ctfeed | View live logs | | Stop | sudo docker-compose down | Gracefully stop the bot | | Restart | sudo docker-compose restart ctfeed | Quick restart without rebuild |

How CTFeed Works

Once running, CTFeed will:

1. Start FastAPI and the Discord bot together in the app lifespan
2. Initialize database and config cache
3. Poll CTFTime for new, updated, and removed events
4. Post notifications to the announcement channel
5. Create/join event channels and manage membership
6. Create or recover Discord scheduled events
7. Auto-archive expired or canceled events