Typebot Self-Hosting Deployment & Usage Guide

1. Prerequisites

Before installing Typebot, ensure your system meets these requirements:

Runtime & Database:

Node.js 18.x or higher
Docker and Docker Compose (recommended for production)
PostgreSQL 14+ database
Redis (for session management and caching)

Tools:

Git for cloning the repository
npm or yarn package manager
Make (optional, for using provided Makefile commands)

Optional Services (for full functionality):

Stripe account (for payment blocks)
OpenAI API key (for AI-powered blocks)
Google Sheets API credentials
SMTP server (for email notifications)
Custom domain with SSL certificate

2. Installation

Clone the Repository

git clone https://github.com/baptistearno/typebot.io.git
cd typebot.io

Install Dependencies

Typebot uses a monorepo structure with multiple packages. Install all dependencies:

npm install
# or
yarn install

Docker Installation (Simplified)

For production deployment, Docker is recommended. Pull the official images:

docker pull baptistearno/typebot-builder
docker pull baptistearno/typebot-viewer

3. Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

Required:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/typebot"
DIRECT_URL="postgresql://user:password@localhost:5432/typebot" # For Prisma

# Encryption
ENCRYPTION_SECRET="your-32-character-encryption-secret-here"

# Redis
REDIS_URL="redis://localhost:6379"

# Next.js
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-nextauth-secret-here"

# Storage (for file uploads)
S3_ENDPOINT="https://your-s3-endpoint.com"
S3_ACCESS_KEY="your-access-key"
S3_SECRET_KEY="your-secret-key"
S3_BUCKET="typebot"
S3_REGION="us-east-1"

Optional (for specific features):

# Email (SMTP)
SMTP_USERNAME="your-email@domain.com"
SMTP_PASSWORD="your-password"
SMTP_HOST="smtp.domain.com"
SMTP_PORT="587"

# Stripe (for payment blocks)
STRIPE_SECRET_KEY="sk_live_xxx"
STRIPE_WEBHOOK_SECRET="whsec_xxx"

# OpenAI
OPENAI_API_KEY="sk-xxx"

# Google Sheets
GOOGLE_SHEETS_CLIENT_ID="xxx"
GOOGLE_SHEETS_CLIENT_SECRET="xxx"
GOOGLE_SHEETS_REDIRECT_URI="http://localhost:3000/api/credentials/google-sheets/callback"

# PostHog Analytics (optional)
NEXT_PUBLIC_POSTHOG_KEY="phc_xxx"
NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com"

Database Setup

Initialize the PostgreSQL database with Prisma:

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma db push
# or for production:
npx prisma migrate deploy

4. Build & Run

Development Mode

Run Typebot in development mode with hot reload:

# Start all services (builder, viewer, bot-engine)
npm run dev
# or
yarn dev

# Alternatively, start services individually:
npm run dev:builder     # Builder UI (port 3000)
npm run dev:viewer      # Chat viewer (port 3001)
npm run dev:bot-engine  # Bot engine API (port 3002)

Production Build

Build the application for production:

# Build all packages
npm run build
# or
yarn build

# Start production server
npm run start

Using Docker Compose

For a complete production setup with all services:

# Using the provided docker-compose.yml
docker-compose up -d

# Or build and run
docker-compose -f docker-compose.prod.yml up --build -d

5. Deployment

Platform Recommendations

1. VPS/Cloud VM (Recommended for full control)

Platforms: DigitalOcean, AWS EC2, Google Cloud Compute, Azure VMs
Setup: Use Docker Compose with the provided configuration
Requirements: Minimum 2GB RAM, 2 vCPUs, 20GB storage

2. Container Platforms

Railway.app: One-click deployment with their Typebot template
Render.com: Deploy using Docker with persistent storage
Fly.io: Good for global distribution of chat viewers

3. Kubernetes For large-scale deployments:

# Example Kubernetes deployment for builder service
apiVersion: apps/v1
kind: Deployment
metadata:
  name: typebot-builder
spec:
  replicas: 2
  selector:
    matchLabels:
      app: typebot-builder
  template:
    metadata:
      labels:
        app: typebot-builder
    spec:
      containers:
      - name: builder
        image: baptistearno/typebot-builder:latest
        envFrom:
        - configMapRef:
            name: typebot-config
        ports:
        - containerPort: 3000

Deployment Steps

Set up infrastructure:

# Create a VM with Docker installed
# Clone repository
git clone https://github.com/baptistearno/typebot.io.git
cd typebot.io

Configure production environment:

# Copy example env file
cp .env.example .env.production
# Edit with production values
nano .env.production

Deploy with Docker:

# Set environment
export NODE_ENV=production

# Pull latest images
docker-compose -f docker-compose.prod.yml pull

# Start services
docker-compose -f docker-compose.prod.yml up -d

Set up reverse proxy (nginx example):

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable HTTPS with Let's Encrypt:

sudo certbot --nginx -d your-domain.com

Scaling Considerations

Database: Consider managed PostgreSQL (AWS RDS, Google Cloud SQL)
Redis: Use managed Redis (Redis Labs, AWS ElastiCache)
Storage: Use S3-compatible storage for file uploads
CDN: Use Cloudflare or similar for static assets

6. Troubleshooting

Common Issues

1. Database Connection Errors

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -h localhost -U typebot -d typebot

# Reset database (development only)
npx prisma migrate reset

2. Redis Connection Issues

# Test Redis connection
redis-cli ping
# Should return "PONG"

# Check Redis logs
sudo journalctl -u redis -f

3. Build Failures

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear Next.js cache
rm -rf .next
npm run build

4. Docker Container Issues

# Check container logs
docker-compose logs -f builder
docker-compose logs -f viewer

# Restart services
docker-compose restart

# Rebuild containers
docker-compose down
docker-compose up --build -d

5. File Upload Problems

Verify S3 credentials in environment variables
Check bucket permissions and CORS configuration
Ensure S3_ENDPOINT includes protocol (https://)

6. Email Not Sending

Verify SMTP credentials
Check spam folder
Test with a simple SMTP client:
```
telnet smtp.gmail.com 587
```

7. Payment Blocks Not Working

Ensure Stripe webhooks are configured
Verify Stripe secret keys are correct
Check webhook endpoint: /api/stripe-webhook

Getting Help

Documentation: https://docs.typebot.io
Discord Community: https://typebot.io/discord
GitHub Issues: Report bugs
Status Page: https://status.typebot.io

Monitoring

Set up monitoring for production deployments:

Application logs: Use Docker logs or systemd journal
Database monitoring: Enable PostgreSQL slow query logs
Performance: Monitor Redis memory usage and connection count
Uptime: Use UptimeRobot or similar service
Error tracking: Configure Sentry (already integrated in codebase)

How to Deploy & Use typebot.io