Installation Guide

Installation Guide

This guide walks you through setting up ImageBot for local development and production deployment.

Prerequisites

Before you begin, ensure you have:

• Node.js 18 or higher
• npm or yarn package manager
• Cloudflare Account (free tier works)
• Git for version control

Step 1: Clone Repository

git clone https://github.com/your-org/imagebot.git
cd imagebot

Step 2: Install Dependencies

npm install

This installs all required packages including:

• Astro frontend framework
• React for UI components
• Cloudflare Workers for backend
• Database and storage clients

Step 3: Cloudflare Setup

Install Wrangler CLI

npm install -g wrangler

Login to Cloudflare

wrangler login

This opens your browser for authentication.

Create D1 Database

wrangler d1 create imagebot-db

Important: Copy the database_id from the output.

Create R2 Bucket

wrangler r2 bucket create imagebot-images

Step 4: Configuration

Update wrangler.toml

Edit wrangler.toml and add your database ID:

[[d1_databases]]
binding = "DB"
database_name = "imagebot-db"
database_id = "your-database-id-here"  # ← Add your ID here

[[r2_buckets]]
binding = "IMAGES"
bucket_name = "imagebot-images"

Set Environment Secrets

# JWT Secret (generate a strong random string)
wrangler secret put JWT_SECRET

# Stripe Keys (optional, for payments)
wrangler secret put STRIPE_SECRET_KEY
wrangler secret put STRIPE_WEBHOOK_SECRET

# Email Service (optional)
wrangler secret put MAILERSEND_API_TOKEN

# GitHub OAuth (optional)
wrangler secret put GITHUB_CLIENT_SECRET

Generate JWT Secret:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Create .env File

cp .env.example .env

Edit .env:

PUBLIC_API_URL=http://localhost:8787

Step 5: Database Migration

Apply all database schemas:

# Core schema
wrangler d1 execute imagebot-db --remote --file database/schema-init.sql

# Feature schemas
wrangler d1 execute imagebot-db --remote --file database/license-certificates-schema.sql
wrangler d1 execute imagebot-db --remote --file database/multi-model-comparison-schema.sql
wrangler d1 execute imagebot-db --remote --file database/api-keys-schema.sql
wrangler d1 execute imagebot-db --remote --file database/teams-minimal.sql
wrangler d1 execute imagebot-db --remote --file database/batch-schema.sql
wrangler d1 execute imagebot-db --remote --file database/branding-schema.sql
wrangler d1 execute imagebot-db --remote --file database/prompt-packs-schema.sql

Verify database:

wrangler d1 execute imagebot-db --remote --command "SELECT COUNT(*) as table_count FROM sqlite_master WHERE type='table'"

You should see 41+ tables.

Step 6: Local Development

Start Frontend Dev Server

# Terminal 1
npm run dev

Access at: http://localhost:4321

Start Worker Dev Server

# Terminal 2
npm run worker:dev

Worker runs at: http://localhost:8787

Step 7: Verify Setup

1. Open http://localhost:4321
2. Click “Register” to create an account
3. Try generating an image
4. Check that it appears in the Gallery

Troubleshooting

Database Connection Errors

# Check database exists
wrangler d1 list

# Verify binding in wrangler.toml
cat wrangler.toml | grep database_id

Worker Deployment Issues

# Check Wrangler version
wrangler --version

# Clear cache
rm -rf .wrangler
npm run worker:dev

Port Already in Use

# Kill process on port 4321
kill $(lsof -t -i:4321)

# Or use different port
npm run dev -- --port 3000

R2 Bucket Access

# List buckets
wrangler r2 bucket list

# Test upload
echo "test" > test.txt
wrangler r2 object put imagebot-images/test.txt --file=test.txt

Production Deployment

See Deployment Guide for production setup.

Next Steps

• Create Your First Image
• Explore Features
• API Documentation
• Security Best Practices

Additional Resources

• Cloudflare Workers Docs
• Cloudflare D1 Guide
• Astro Documentation

Getting Help

If you encounter issues:

1. Check Troubleshooting
2. Search GitHub Issues
3. Join Discord Community
4. Email: support@imagebot.com