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

Clone the repository with submodules:

git clone --recursive <repository-url>

If already cloned, initialize submodules:

git submodule update --init --recursive

Install dependencies:

uv sync

Set up environment variables in a .env file or export them directly.
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.

README.md

Flagger

Core Components