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 after login and for CORS
HTTP_API_URL	Backend API base URL used for the Discord OAuth2 callback and CORS
HTTP_COOKIE_DOMAIN	Cookie domain for session
HTTP_COOKIE_SECURE	Whether session cookies require HTTPS
DISCORD_OAUTH2_CLIENT_ID	Discord OAuth2 client ID
DISCORD_OAUTH2_CLIENT_SECRET	Discord OAuth2 client secret
CHECK_INTERVAL_MINUTES	Shared background task interval
DATABASE_URL	PostgreSQL database URL

Set the Discord OAuth2 redirect URI to HTTP_API_URL/auth/login.

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

• ANNOUNCEMENT_CHANNEL_ID
• CTFMENU_CHANNEL_ID
• CTF_CHANNEL_CATEGORY_ID
• ARCHIVE_CATEGORY_ID
• PM_ROLE_ID
• MEMBER_ROLE_ID

Launch the Bot

Choose your preferred method:

# Apply database migrations and launch the service (recommended)
./startup.sh

# Or run each step manually
uv run alembic upgrade head
uv run uvicorn --host 0.0.0.0 --port 5000 ctfeed:app

startup.sh applies all pending database migrations before starting the service. If a migration fails, the service will not start.

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

At startup and while running, CTFeed will:

1. Apply pending database migrations before service startup (startup.sh does this automatically)
2. Initialize singleton database records, config cache, and the HTTP client session in the FastAPI lifespan
3. Start the Discord bot alongside FastAPI
4. Poll CTFTime for new, updated, and removed events
5. Post notifications to the announcement channel
6. Create/join event channels and manage membership
7. Create, update, or recover Discord scheduled events
8. Auto-archive expired or canceled events