Getting Started

Welcome to the Activity Challenge Bot development guide! This page will help you set up the project locally and start contributing.

Prerequisites

Before you begin, ensure you have the following installed:

• Bun v1.0 or higher - Modern JavaScript runtime
• PostgreSQL v14 or higher - Database
• Podman or Docker - Container runtime (optional, for containerized development)
• Git - Version control
• A Telegram account - For bot testing

Runtime Choice

This project uses Bun as the runtime instead of Node.js. Bun is a fast, modern JavaScript runtime with built-in TypeScript support, package management, and testing.

Quick Start

1. Clone the Repository

git clone https://github.com/EppuRuotsalainen/activity-challenge-bot.git
cd activity-challenge-bot

2. Install Dependencies

bun install

3. Set Up Environment Variables

Copy the example environment file and configure it. See Environment Setup for detailed configuration.

cp .env.example .env

Edit .env with your bot token and database credentials:

BOT_TOKEN=your_bot_token_here  # Get from @BotFather on Telegram
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/activity_challenge_bot

Get a Bot Token

Message @BotFather on Telegram, send /newbot, follow instructions, and copy the token to your .env file.

4. Set Up the Database

Option A: Local PostgreSQL

If you have PostgreSQL installed locally:

# Create the database
createdb activity_challenge_bot

# Run migrations
bun run migrate

Option B: Containerized Database

Use the provided Docker/Podman compose setup:

# Start PostgreSQL in a container
bun run pod:up

# Migrations run automatically on container startup

5. Populate Test Data (Optional)

Add sample data for testing:

bun run populate

This creates sample users, activities, and realistic competition data.

6. Start the Bot

# Development mode with hot reload
bun run dev

# Or production mode
bun run start

You should see:

✅ Database migrations completed
✅ Bot commands configured
🤖 Bot started successfully!

7. Test the Bot

1. Open Telegram
2. Find your bot (search for the username you gave it)
3. Send /start
4. Register and start logging activities!

Development Modes

Local Development (Recommended)

Run the bot directly on your machine with hot reload:

bun run dev

Changes to the code automatically restart the bot.

Containerized Development

Run the bot in a container with all dependencies:

# Start all services (bot + database)
bun run pod:dev

# View logs
bun run pod:logs

# Stop services
bun run pod:down

Kubernetes Development

For advanced testing with Kubernetes:

# Set up local cluster
bun run cluster:setup

# Deploy the bot
bun run cluster:deploy

# View logs
bun run cluster:logs

See Kubernetes Dev Guide for details.

Project Structure Overview

activity-challenge-bot/
├── src/              # Source code
├── scripts/          # Helper scripts
├── data/             # Activity data (MET values)
├── tests/            # Test files
├── docs/             # Documentation
└── webapp/           # Web app for statistics

See Project Structure for a detailed walkthrough.

Common Tasks

Clear Database

Remove all data but keep the schema:

bun run clear

Reset and Repopulate

bun run clear
bun run populate

Run Tests

# Run all tests
bun test

# Watch mode
bun run test:watch

# With coverage
bun run test:coverage

See Testing Guide for more details.

Lint Code

bun run lint

Next Steps

Now that you have the bot running locally:

1. Explore the code - Start with Project Structure
2. Understand flows - Read Flows and Wizards
3. Configure the bot - See Competition Setup and Guild Management
4. Start contributing - See Contributing Guide