Getting Started

This guide will walk you through setting up the 10,000 Beers bot for the first time. You can choose between Docker (recommended) or a local Node.js setup.

Prerequisites

For Docker Setup (Recommended)

• Docker v20.10 or higher
• Docker Compose v2.0 or higher
• Git

For Non-Docker Setup

• Node.js v20.x or higher
• npm v10.x or higher
• PostgreSQL v16.x or higher
• Chromium browser (for WhatsApp Web interface)
• Git

---

Docker Setup (Recommended)

1. Clone the Repository

git clone <repository-url>
cd 10000-beers

2. Create Environment Configuration

Copy the example environment file:

cp .env.example .env

3. Configure Environment Variables

Edit the .env file and set the required variables:

Required:

• WHATSAPP_GROUP_ID - Your WhatsApp group ID (see Getting Your Group ID)
• POSTGRES_PASSWORD - Change from default for production

Recommended:

• ADMIN_IDS - Comma-separated list of admin WhatsApp IDs (e.g., [email protected],[email protected])
• LOG_LEVEL - Set to info for production, debug for development

Example .env for production:

# Database
POSTGRES_PASSWORD=your_secure_password_here
DATABASE_URL=postgresql://beers:your_secure_password_here@postgres:5432/beers

# WhatsApp
[email protected]

# Admins
[email protected]

# Application
NODE_ENV=production
LOG_LEVEL=info

4. Start the Services

Start all services (PostgreSQL, pgAdmin, and the bot):

docker compose up -d

This will:

• Pull required Docker images
• Create the database
• Run database migrations
• Start the bot

5. Authenticate with WhatsApp (First-Time Only)

View the bot logs to see the QR code:

docker compose logs -f bot

You should see a QR code displayed in the terminal. Scan it with WhatsApp:

1. Open WhatsApp on your phone
2. Tap Settings (⋮) → Linked devices
3. Tap Link a device
4. Scan the QR code from the terminal

Once authenticated, the session will be saved and persist across container restarts. You'll see a "Client is ready!" message in the logs.

6. Verify the Setup

Check that all services are running:

docker compose ps

You should see:

• postgres - running on port 5432
• pgadmin - running on port 5050
• bot - running

Send a test message with an image to your WhatsApp group to verify the bot is working.

7. Access pgAdmin (Optional)

Navigate to http://localhost:5050 in your browser:

• Email: [email protected] (or value from PGADMIN_EMAIL)
• Password: admin (or value from PGADMIN_PASSWORD)

To connect to the database in pgAdmin:

1. Add new server
2. Name: 10000-beers
3. Host: postgres
4. Port: 5432
5. Database: beers
6. Username: beers
7. Password: (value from POSTGRES_PASSWORD)

---

Non-Docker Setup

1. Clone the Repository

git clone <repository-url>
cd 10000-beers

2. Install Dependencies

npm install

This will also automatically run prisma generate to create the Prisma client.

3. Set Up PostgreSQL Database

Create a new PostgreSQL database:

# Using psql
createdb beers

# Or using SQL
psql -U postgres
CREATE DATABASE beers;
\q

4. Create Environment Configuration

Copy the example environment file:

cp .env.example .env

5. Configure Environment Variables

Edit the .env file:

Required:

• DATABASE_URL - Your PostgreSQL connection string
• WHATSAPP_GROUP_ID - Your WhatsApp group ID

Example .env for local development:

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/beers

# WhatsApp
[email protected]

# Admins
[email protected]

# Storage
IMAGE_STORAGE_PATH=./data/images

# Application
NODE_ENV=development
LOG_LEVEL=debug
REPLY_ON_SUBMISSION=true

6. Create Image Storage Directory

Create the directory for storing beer images:

mkdir -p ./data/images

Or set IMAGE_STORAGE_PATH to your preferred location in .env.

7. Run Database Migrations

Apply the database schema:

npm run prisma:migrate

This will create all necessary tables and indexes.

8. Start the Development Server

npm run dev

The server will start with hot reload enabled (changes to code will automatically restart the server).

9. Authenticate with WhatsApp (First-Time Only)

A QR code will be displayed in your terminal. Scan it with WhatsApp:

1. Open WhatsApp on your phone
2. Tap Settings (⋮) → Linked devices
3. Tap Link a device
4. Scan the QR code from the terminal

The session will be saved in .wwebjs_auth/session-10000-beers/ and will persist across restarts.

10. Verify the Setup

Once you see "Client is ready!" in the logs, send a test message with an image to your WhatsApp group.

11. Build for Production

When ready for production:

# Build TypeScript to JavaScript
npm run build

# Start the production server
npm start

---

Getting Your WhatsApp Group ID

If you don't know your group ID, follow these steps:

Method 1: Check the Logs

1. Start the bot (Docker or non-Docker)
2. Send any message in your WhatsApp group
3. Check the bot logs - you'll see the group ID in the format:
   • [email protected] (regular groups)
   • 1234567890@lid (large groups/communities)

Method 2: Temporarily Log All Messages

1. Temporarily remove or comment out the WHATSAPP_GROUP_ID check in the code
2. Start the bot
3. Send a message in your group
4. The logs will show the group ID
5. Add it to your .env file and restart

Method 3: Using WhatsApp Web

1. Open WhatsApp Web
2. Open your group
3. Look at the URL: https://web.whatsapp.com/send?id=1234567890
4. The ID is the numeric part - add @g.us to it: [email protected]

---

Getting Admin WhatsApp IDs

Admin IDs are in the format [email protected] (country code + phone number without + or spaces).

Format Examples:

• UK number +44 7123 456789 → [email protected]
• US number +1 555 123 4567 → [email protected]

Finding Your WhatsApp ID:

1. Start the bot and send a message to the group
2. Check the logs for your WhatsApp ID
3. Add it to ADMIN_IDS in .env:

   [email protected],[email protected]
   

---

Verifying Your Installation

Check the Bot is Connected

Send a message in your WhatsApp group. You should see log output in the terminal/Docker logs.

Test Beer Submission

1. Take a photo of a beer (or any beverage)
2. Send the image to your WhatsApp group
3. The bot should respond with a confirmation message (if REPLY_ON_SUBMISSION=true)
4. Check the logs to verify the submission was processed

Test Admin Commands (Optional)

If you've set ADMIN_IDS:

1. Send !leaderboard to the group
2. You should receive the current leaderboard

Check Database

Docker:

docker compose exec postgres psql -U beers -d beers -c "SELECT COUNT(*) FROM beers;"

Non-Docker:

psql -U username -d beers -c "SELECT COUNT(*) FROM beers;"

Or use Prisma Studio:

npm run prisma:studio

Navigate to http://localhost:5555 to view your data.

---

Next Steps

• Configuration - Learn about all environment variables and settings
• Commands - Explore available bot commands
• Development Guide - Start contributing to the codebase

---

Common First-Time Issues

QR Code Not Appearing

Solution: Check the logs for errors. Ensure Chromium is installed (non-Docker) or the Docker container has started successfully.

# Docker
docker compose logs bot

# Non-Docker
# Check the terminal output

"WhatsApp session not found" Error

Solution: Delete the session and re-authenticate:

# Docker
docker compose down
rm -rf .wwebjs_auth/session-10000-beers/
docker compose up -d

# Non-Docker
rm -rf .wwebjs_auth/session-10000-beers/
npm run dev

Database Connection Failed

Solution: Verify PostgreSQL is running and DATABASE_URL is correct:

# Docker
docker compose ps postgres

# Non-Docker
pg_isready

Permission Denied on Image Storage

Solution: Ensure the image storage directory is writable:

chmod -R 755 ./data/images

For Docker, ensure the volume mount is correct in docker-compose.yml.

---

Need more help? Check the GitHub Issues.