Flagger

A Discord HTTP bot for flag animation rendering. This is my participation to the 2025 Discord Developers Buildathon.

Core Components

This project integrates flagwaver as a git submodule (src/flagwaver), which serves as the core rendering engine for flag animations. Credit to the flagwaver project for providing the visualization component.

Technology Stack

• py-cord: Discord API wrapper
• pycord-rest (Paillat-dev/pycord-rest): rest (http interactions) bot implementation for py-cord
• Playwright: Browser automation for rendering
• MoviePy: Video processing
• Pydantic: Configuration and data validation

Requirements

• Python 3.13 or higher
• uv package manager

Development Workflow

This project uses tooling from Astral:

• uv: Fast Python package manager
• ruff: Linter and formatter
• ty: Type checker

Commands

Format code:

uv run ruff format .

Lint and auto-fix issues:

uv run ruff check --fix .

Type check:

uv run ty check .

Code Standards

All code is strictly typed and must pass type checking. The project enforces comprehensive linting rules with select exceptions defined in pyproject.toml. Any pull request must pass all checks before merging.

Configuration

Set the following environment variables:

Required

• DISCORD_TOKEN: Your Discord bot token
• DISCORD_PUBLIC_KEY: Your Discord application's public key

Optional

• FLAGGER_RENDERER_WORKERS: Number of concurrent renderer workers (default: 2)
• FLAGWAVER_HTTP_PORT: Port for the flagwaver HTTP server (default: 8910)
• UVICORN_HOST: Host address for the Uvicorn server (default: 0.0.0.0)
• AUTO_SYNC_COMMANDS: Whether to automatically sync slash commands with Discord (default: true)
• FLAGWAVER_PATH: Path to the flagwaver distribution directory (default: src/flagwaver/dist)
• LOG_LEVEL: Logging level for the application (default: INFO)
• COOLDOWN_RATE: Number of command uses allowed per cooldown period (default: 1)
• COOLDOWN_PER: Cooldown period in seconds (default: 900, i.e., 15 minutes)

Installation

1. Clone the repository with submodules:

git clone --recursive <repository-url>

If already cloned, initialize submodules:

git submodule update --init --recursive

2. Install dependencies:

uv sync

3. Set up environment variables in a .env file or export them directly.

4. Run the bot:

uv run python -m src

Docker Deployment

The project includes a Dockerfile for containerized deployment and compose.yaml for local development.

Using the pre-built Docker image

Pull the latest image:

docker pull ghcr.io/paillat-dev/flagger:master

Run the container:

docker run --env-file .env ghcr.io/paillat-dev/flagger:master

Building and Running with Docker

Build the image:

docker build -t flagger .

Run the container:

docker run --env-file .env flagger

Local Development with Docker Compose

For local development with hot reload:

docker compose up --watch

The compose configuration includes:

• Automatic restart on source code changes in src/
• Image rebuild on Dockerfile changes
• Environment variable loading from .env file

When developing locally, you will most likely need to use a service like ngrok to expose your local server to the internet for Discord interactions.

License

Copyright (c) Paillat-dev SPDX-License-Identifier: MIT