Flagger

A Discord HTTP bot for flag animation rendering.

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 (v2.7.0rc2): Discord API wrapper
• pycord-rest (Paillat-dev/pycord-rest): rest 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.

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.

Building and Running with Docker

Build the image:

docker build -t flagger .

Run the container:

docker run --env-file .env -p 8000:8000 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
• Port mapping for the HTTP server

License

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