Getting Started

This guide will help you set up and run Catto v2.x locally for development.

Prerequisites

• Node.js v20 or higher
• pnpm v10+
• Docker and Docker Compose (recommended)
• Rust (optional, for watermark microservice)

Installation

1. Clone the Repository

git clone https://github.com/cattxdev/catto.v2.git
cd catto

2. Install Dependencies

pnpm install

3. Build Watermark Service (Optional)

For faster evidence image processing, build the Rust watermark microservice:

cd services/watermark-rs
cargo build --release
cd ../..

If not built, the bot will use Sharp-based watermarking as a fallback.

4. Configure Environment

Copy the example environment file:

cp .env.example .env

Fill in the required values:

Variable	Description	Required
DISCORD_TOKEN	Your Discord bot token	Yes
CLIENT_ID	Discord application client ID	Yes
CLIENT_SECRET	Discord application client secret	Yes
DATABASE_URL	PostgreSQL connection string	Yes
REDIS_HOST	Redis server host	Yes
REDIS_PORT	Redis server port	Yes
REDIS_PASSWORD	Redis password (if any)	No
REDIS_DB	Redis database number	No
OWNER_IDS	Comma-separated owner user IDs	No
DEFAULT_PREFIX	Default command prefix	No
API_PORT	HTTP API port (default: 4000)	No
API_PREFIX	API route prefix	No
API_ORIGIN	OAuth2 origin URL	No
API_REDIRECT	OAuth2 redirect URL	No
B2_ENDPOINT	Backblaze B2 S3 endpoint (e.g. https://s3.us-west-004.backblazeb2.com)	No
B2_REGION	B2 region (e.g. us-west-004)	No
B2_KEY_ID	B2 application key ID (not master key)	No
B2_APP_KEY	B2 application key secret	No
B2_BUCKET_NAME	B2 bucket name	No
B2_BUCKET_ID	B2 bucket ID	No
EVIDENCE_HMAC_SECRET	Secret for evidence HMAC signing (min 32 chars)	No
DASHBOARD_URL	Moderator dashboard URL (default: http://localhost:3000)	No
WATERMARK_SERVICE_URL	Watermark microservice URL (default: http://localhost:3847)	No
WATERMARK_MAX_UPLOAD_SIZE	Max watermark upload size (default: 1gb)	No

Running the Bot

Option 1: Ephemeral Environment (Recommended for Development)

This starts temporary PostgreSQL and Redis instances in RAM:

pnpm dev:env

The script will:

• Start PostgreSQL and Redis containers
• Update .env with ephemeral DATABASE_URL and REDIS_* values (dev-only)
• Start the watermark microservice (if built)
• Apply migrations and seed the database
• Start the bot in watch mode

Option 2: Persistent Database

Use Docker Compose for persistent storage:

# Start PostgreSQL and Redis
docker-compose up -d

# Run migrations
pnpm prisma:migrate

# Start the bot in development mode
pnpm dev

Available Scripts

Script	Description
pnpm dev	Start bot in watch mode
pnpm dev:env	Start with ephemeral database + update .env
pnpm build	Compile TypeScript
pnpm start	Run compiled bot
pnpm lint	Run ESLint
pnpm lint:fix	Fix ESLint issues
pnpm format	Format code with Prettier
pnpm typecheck	Type-check without emitting
pnpm test	Run tests
pnpm test:watch	Run tests in watch mode
pnpm docs:all	Serve documentation locally

Prisma Scripts

Script	Description
pnpm prisma:generate	Generate Prisma client
pnpm prisma:migrate	Run migrations
pnpm prisma:studio	Open Prisma Studio
pnpm prisma:push	Push schema changes
pnpm prisma:seed	Seed the database
pnpm prisma:reset	Reset the database

Project Structure

catto/
├── src/
│   ├── index.ts              # Entry point
│   ├── config.ts             # Environment validation
│   ├── structures/           # BotClient and core structures
│   ├── commands/             # Slash commands
│   ├── listeners/            # Event handlers
│   ├── routes/               # REST API endpoints
│   ├── modules/              # Business logic modules
│   ├── lib/                  # Utilities and helpers
│   │   ├── storage/          # B2 storage and signing services
│   │   └── validation/       # Gate, permissions, rate limiting
│   ├── preconditions/        # Permission checks
│   └── interactions/         # Button/modal handlers
├── dashboard/                # Next.js moderator dashboard
│   ├── app/mod/              # Mod dashboard pages
│   ├── components/mod/       # Evidence gallery, viewer, upload
│   └── lib/                  # Services and types
├── services/
│   └── watermark-rs/         # Rust watermark microservice
├── prisma/
│   ├── schema.prisma         # Database schema
│   └── seed.ts               # Database seeder
├── languages/                # i18n translations
├── docs/                     # Documentation (you are here)
└── docker-compose.yml        # Docker services

Next Steps

• Dashboard Setup — Run the moderator dashboard and configure OAuth login
• Read the Architecture overview
• Learn about Coding Rules
• Explore the Internal APIs
• Create your first Command