Deploying a Botpress App

Introduction

Botpress is a powerful open-source conversational AI platform that enables developers and businesses to build, deploy, and manage intelligent chatbots and virtual assistants with advanced natural language understanding (NLU), multi-channel messaging support, and customizable conversation flows. With its visual flow editor, pre-built integrations, and extensible architecture, Botpress simplifies the creation of sophisticated conversational experiences for customer support, sales automation, internal tools, and interactive applications.

Deploying Botpress on Klutch.sh provides a production-ready, scalable infrastructure for your conversational AI applications with automated Docker deployments, persistent storage for bot data and conversations, secure environment variable management, PostgreSQL database support, and enterprise-grade reliability. Whether you’re building customer service bots, e-commerce assistants, HR automation tools, or complex multi-turn conversation systems, Klutch.sh streamlines the deployment process and ensures your Botpress instance is always available and performant.

This comprehensive guide walks you through deploying Botpress on Klutch.sh using a Dockerfile, configuring PostgreSQL databases for production, setting up persistent volumes for bot data and file storage, managing environment variables for security and customization, and implementing production best practices for scalable conversational AI development.

Prerequisites

Before you begin deploying Botpress on Klutch.sh, ensure you have:

A Klutch.sh account (sign up here)
A GitHub repository for your Botpress deployment configuration
Basic understanding of Docker containers and environment variables
(Recommended for production) A PostgreSQL database instance
Access to the Klutch.sh dashboard
Familiarity with conversational AI and chatbot concepts

Understanding Botpress Architecture

Botpress consists of several key components that work together to power your conversational AI applications:

Core Server: Node.js-based runtime that handles bot execution, NLU processing, and conversation management
Studio Interface: Visual editor for designing conversation flows, managing intents, and configuring bot behavior
NLU Engine: Natural language understanding system for intent recognition, entity extraction, and language processing
Database: PostgreSQL (recommended for production) or SQLite for storing conversations, bot configurations, and user data
Storage: Persistent volumes for bot definitions, media files, logs, and custom modules
Messaging Channels: Integration layer for connecting to platforms like Slack, WhatsApp, Telegram, Facebook Messenger, and web chat

When deployed on Klutch.sh, Botpress automatically detects your Dockerfile in the repository root and builds a container image that includes all necessary components. The platform manages traffic routing to port 3000 (Botpress default), SSL certificates, and provides persistent storage options for your bot data.

Project Structure

A minimal repository structure for deploying Botpress on Klutch.sh:

botpress-deployment/
├── Dockerfile
├── .dockerignore
├── .gitignore
├── README.md
└── .env.example

This simple structure allows Klutch.sh to automatically detect and build your Botpress container. You don’t need to include bot definitions in the repository—those will be created through the Botpress Studio interface and stored in persistent volumes.

Creating Your Dockerfile

Klutch.sh automatically detects a Dockerfile in the root directory of your repository. Create a Dockerfile that uses the official Botpress image or builds a custom configuration:

Option 1: Simple Dockerfile (Recommended for Quick Start)

FROM botpress/server:latest

# Set working directory
WORKDIR /botpress

# Expose the default Botpress port
EXPOSE 3000

# The official image includes the startup command
CMD ["./bp"]

Option 2: Production Dockerfile with Custom Configuration

FROM botpress/server:latest

# Set working directory
WORKDIR /botpress

# Install additional dependencies if needed
RUN apt-get update && apt-get install -y \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Expose the application port
EXPOSE 3000

# Add health check for monitoring
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:3000/status || exit 1

# Start Botpress server
CMD ["./bp"]

Option 3: Custom Dockerfile with Pre-configured Modules

FROM botpress/server:latest

# Set working directory
WORKDIR /botpress

# Install system dependencies
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Copy custom modules or configurations (optional)
# COPY ./modules /botpress/modules
# COPY ./custom-config.yml /botpress/data/global/config/botpress.config.yml

# Expose the application port
EXPOSE 3000

# Health check for production monitoring
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:3000/status || exit 1

# Start Botpress with production settings
CMD ["./bp", "--production"]

Important Notes:

Botpress listens on port 3000 by default
Klutch.sh will route external HTTP traffic to port 3000 in your container
The container includes the NLU engine, Studio interface, and bot runtime
All bot data should be stored in persistent volumes, not in the container

Deploying to Klutch.sh

Create Your Repository

Create a new GitHub repository and add your Dockerfile:

mkdir botpress-deployment
cd botpress-deployment

# Create Dockerfile
cat > Dockerfile << 'EOF'
FROM botpress/server:latest

WORKDIR /botpress

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:3000/status || exit 1

CMD ["./bp"]
EOF

# Create .gitignore
cat > .gitignore << 'EOF'
node_modules/
.env
.DS_Store
data/
*.log
EOF

# Initialize git and push
git init
git add .
git commit -m "Initial Botpress deployment setup"
git remote add origin https://github.com/YOUR_USERNAME/botpress-deployment.git
git push -u origin main

Access the Klutch.sh Dashboard

Navigate to klutch.sh/app and log in to your account.
Create a New Project
- Click “New Project” in the dashboard
- Enter a project name (e.g., “AI Chatbots”)
- Select your preferred region for deployment
Create a New Application
- Within your project, click “New App”
- Name your application (e.g., “Botpress”)
- Connect your GitHub repository containing the Dockerfile
Configure Build Settings

Klutch.sh automatically detects the Dockerfile in your repository root. If your Dockerfile is in a subdirectory, specify the build context path in the dashboard.
Set Up Persistent Storage

Botpress requires persistent storage to retain bot definitions, conversations, and media files across deployments:
- In the app settings, navigate to the “Volumes” section
- Click “Add Volume”
- Set the mount path to /botpress/data
- Set the volume size (recommended: 10GB minimum for production)
- Click “Add” to attach the volume
Critical: The /botpress/data directory stores:
- Bot definitions and conversation flows
- NLU models and training data
- User conversations and analytics
- Uploaded media files and assets
- Database files (if using SQLite)
- Logs and debug information

Configure Environment Variables

In the app settings, add the following environment variables for optimal configuration:

Essential Variables (Development - SQLite):

BP_HOST=0.0.0.0
BP_PORT=3000
DATABASE_URL=sqlite:///botpress/data/botpress.db
BP_PRODUCTION=true

Production Variables (PostgreSQL - Recommended):

BP_HOST=0.0.0.0
BP_PORT=3000
DATABASE_URL=postgres://username:password@postgres-host:8000/botpress
BP_PRODUCTION=true
EXTERNAL_URL=https://example-app.klutch.sh

Optional Configuration:

# Licensing (for Botpress Pro features)
BP_LICENSE_KEY=your-license-key-here

# Admin credentials
SUPERADMIN_EMAIL=admin@yourdomain.com
SUPERADMIN_PASSWORD=your-secure-password

# Storage configuration
BPFS_STORAGE=database

# Logging
VERBOSE=true
DEBUG=bp:*

# Security
AUTH_SECRET=your-random-secret-32-chars-min

Security Best Practice: Always use the “Secret” checkbox for sensitive values like database passwords, license keys, and admin credentials.

Configure Traffic Settings
- In the “Networking” section, select HTTP as the traffic type
- Set the internal port to 3000 (Botpress’s default port)
- Enable automatic HTTPS/SSL (provided by Klutch.sh)
Deploy the Application
- Review all settings
- Click “Deploy” to start the build process
- Klutch.sh will:
  - Clone your repository
  - Detect the Dockerfile
  - Build the container image
  - Deploy to your selected region
  - Provision persistent storage
  - Configure networking and SSL
Monitor Deployment Progress
- View real-time build logs in the dashboard
- Wait for the deployment status to show “Running”
- Initial startup may take 2-3 minutes as Botpress initializes the database and NLU engine

Once deployment completes, your Botpress instance will be accessible at https://example-app.klutch.sh or your configured custom domain.

Database Setup and Configuration

Botpress can use either SQLite (suitable for development) or PostgreSQL (recommended for production).

SQLite Database (Development)

For testing and development environments, SQLite provides a simple setup:

Advantages:

No external database setup required
Simplified configuration
Good for prototyping and small bots
Data stored in persistent volume

Limitations:

Not suitable for high-traffic production use
Limited concurrent connection support
May have performance issues with large conversation datasets

Configuration:

DATABASE_URL=sqlite:///botpress/data/botpress.db

PostgreSQL Database (Production - Recommended)

For production deployments, use a PostgreSQL database:

Provision a PostgreSQL Database

Deploy PostgreSQL on Klutch.sh or use a managed service:
- Follow the Klutch.sh PostgreSQL guide
- Or use a managed PostgreSQL service like managed PostgreSQL providers
Configure Database for TCP Traffic

When deploying PostgreSQL on Klutch.sh:
- Select TCP as the traffic type
- External connections will use port 8000
- Set the internal port to 5432 (PostgreSQL default)

Create Botpress Database and User

Connect to your PostgreSQL instance and create a dedicated database:

CREATE DATABASE botpress;
CREATE USER botpress_user WITH PASSWORD 'strong-secure-password';
GRANT ALL PRIVILEGES ON DATABASE botpress TO botpress_user;

-- Connect to the botpress database
\c botpress

-- Grant schema privileges
GRANT ALL ON SCHEMA public TO botpress_user;

Configure Connection String

In your Klutch.sh app environment variables, set the database URL:

For PostgreSQL on Klutch.sh (using TCP port 8000):
Terminal window
```
DATABASE_URL=postgres://botpress_user:strong-secure-password@your-postgres-app.klutch.sh:8000/botpress
```
For external PostgreSQL:
Terminal window
```
DATABASE_URL=postgres://botpress_user:strong-secure-password@external-host:5432/botpress
```
Verify Database Connection

After setting the environment variable, trigger a new deployment. Check the logs to confirm successful database connection:
```
[Database] Successfully connected to PostgreSQL
[Database] Running migrations...
[Database] Migrations completed successfully
```

Production Best Practices:

Use connection pooling for better performance
Enable SSL/TLS for database connections when possible
Regular database backups (automated via managed service or pg_dump)
Monitor database size and performance metrics
Use read replicas for high-traffic deployments

Setting Up Persistent Volumes

Persistent storage is critical for maintaining bot definitions, conversation history, and user data across deployments and restarts.

Required Mount Path

Configure a persistent volume in the Klutch.sh dashboard:

Mount Path: /botpress/data
Recommended Size: 10GB minimum (20GB+ for production with media storage)

What Gets Stored

The /botpress/data directory contains:

/botpress/data/
├── bots/                  # Bot definitions and configurations
├── global/                # Global configurations and modules
├── models/                # NLU models and training data
├── storage/               # Uploaded files and media
├── logs/                  # Application and error logs
└── botpress.db            # SQLite database (if not using PostgreSQL)

Backup Strategy

For production deployments, implement regular backups:

Schedule Volume Snapshots

Use Klutch.sh’s volume snapshot feature to create regular backups of the /botpress/data directory.

Database Backups

If using PostgreSQL:

# Create a backup
pg_dump -h your-postgres-app.klutch.sh -p 8000 -U botpress_user -d botpress > botpress-backup-$(date +%Y%m%d).sql

# Restore from backup
psql -h your-postgres-app.klutch.sh -p 8000 -U botpress_user -d botpress < botpress-backup-20241119.sql

Export Bot Definitions

Regularly export bot configurations through the Botpress Studio interface:
- Navigate to your bot in the Studio
- Click “Export Bot” to download a JSON archive
- Store exports in version control or secure storage
Store Backups Securely

Upload backups to object storage (S3, Google Cloud Storage, etc.) or a secure backup service.

Environment Variables Reference

Core Configuration

Variable	Description	Example	Required
`BP_HOST`	Host binding address	`0.0.0.0`	Yes
`BP_PORT`	Port number for Botpress server	`3000`	Yes
`DATABASE_URL`	Database connection string	`postgres://user:pass@host:8000/botpress`	Yes
`BP_PRODUCTION`	Enable production mode	`true`	Yes
`EXTERNAL_URL`	Public URL for your Botpress instance	`https://example-app.klutch.sh`	Recommended

Authentication & Security

Variable	Description	Example
`AUTH_SECRET`	Secret for JWT token generation (min 32 chars)	`your-random-secret-key-here`
`SUPERADMIN_EMAIL`	Default admin email address	`admin@yourdomain.com`
`SUPERADMIN_PASSWORD`	Default admin password	`secure-password-here`

Storage & Performance

Variable	Description	Default
`BPFS_STORAGE`	Storage backend (database or disk)	`database`
`BP_MAX_SERVER_REBOOT`	Max server reboots before exit	`3`
`BP_LOGGING_ENABLED`	Enable logging	`true`

NLU Configuration

Variable	Description	Default
`NLU_PROVIDER`	NLU provider (native or external)	`native`
`NLU_DUCKLING_URL`	Duckling server URL for entity extraction	-

Messaging Channels

Variable	Description
`MESSAGING_ENDPOINT`	Endpoint for messaging API
`WEBCHAT_CONFIG`	Web chat widget configuration

Licensing (Botpress Pro)

Variable	Description
`BP_LICENSE_KEY`	Botpress Pro license key

Custom Domain Configuration

To use your own domain with Botpress on Klutch.sh:

Add Domain in Dashboard
- Navigate to your Botpress app in the Klutch.sh dashboard
- Go to “Domains” section
- Click “Add Custom Domain”
- Enter your domain (e.g., bot.yourdomain.com)

Configure DNS Records

Add a CNAME record in your DNS provider:

Type: CNAME
Name: bot (or your subdomain)
Value: example-app.klutch.sh
TTL: 3600

Enable SSL/TLS

Klutch.sh automatically provisions and manages SSL certificates for your custom domain using Let’s Encrypt.
Update Botpress Configuration

Add an environment variable for the custom domain:
Terminal window
```
EXTERNAL_URL=https://bot.yourdomain.com
```
Verify Configuration
- Wait for DNS propagation (usually 5-15 minutes)
- Visit https://bot.yourdomain.com
- Verify SSL certificate is active and Botpress loads correctly

For detailed domain configuration, see the Klutch.sh Custom Domains guide.

Getting Started with Botpress

After deploying your Botpress instance, follow these steps to create your first chatbot:

Initial Setup

Access Your Instance

Navigate to https://example-app.klutch.sh (or your custom domain).
Create Administrator Account

If you didn’t set SUPERADMIN_EMAIL and SUPERADMIN_PASSWORD environment variables:
- Enter your email address
- Set a strong password
- Complete the setup wizard
Otherwise, log in with your pre-configured admin credentials.
Configure Workspace
- Set your workspace name
- Configure language settings
- Choose your bot’s primary language

Creating Your First Bot

Create a New Bot
- Click “Create Bot” in the Botpress Studio
- Enter a bot name (e.g., “Customer Support Bot”)
- Select a template or start from scratch
- Choose the bot’s default language
Design Your Conversation Flow

Botpress uses a visual flow editor for building conversations:
- Create a Flow: Click “Create Flow” and name it (e.g., “Welcome Flow”)
- Add Nodes: Drag and drop nodes from the panel:
  - Entry Node: Where users start the conversation
  - Text Node: Send messages to users
  - Question Node: Ask users for input
  - Action Node: Execute code or API calls
  - Router Node: Branch conversations based on conditions
Example welcome flow:
```
[Entry] → [Text: "Welcome! How can I help you?"]
    ├─ [Quick Reply: "Product Info"] → [Product Flow]
    ├─ [Quick Reply: "Support"] → [Support Flow]
    └─ [Quick Reply: "About Us"] → [About Flow]
```
Configure Intents and Entities

Train your bot to understand user messages:
- Click “NLU” in the sidebar
- Create intents (user intentions):
```
Intent: greeting
Examples:
- "hello"
- "hi there"
- "good morning"
- "hey"
```
- Create entities (data extraction):
```
Entity: product_name
Type: list
Values: ["laptop", "phone", "tablet"]
```

Add Conversational Responses

In your flow, add a Text node with dynamic content:

// Simple text response
Hello {{user.name}}! How can I assist you today?

// Dynamic response based on intent
{% if event.nlu.intent.name === 'greeting' %}
  Hi there! Welcome to our store.
{% elif event.nlu.intent.name === 'farewell' %}
  Thank you for visiting! Have a great day.
{% endif %}

Implement Actions with Code

Create custom logic in Action nodes:

/**
 * @title Fetch Product Info
 * @category Custom
 */
const fetchProductInfo = async () => {
  const productName = event.nlu.entities.find(e => e.type === 'product_name')?.value

  if (productName) {
    // Make API call to fetch product details
    const response = await axios.get(`https://api.yourstore.com/products/${productName}`)
    temp.productData = response.data
  } else {
    temp.productData = null
  }
}

return fetchProductInfo()

Test Your Bot
- Click “Emulator” button in the bottom right
- Start a conversation with your bot
- Test different intents and conversation paths
- Refine responses and flows based on testing
Publish Your Bot
- Click “Publish” when you’re satisfied with your bot
- Your bot is now live and ready to handle conversations

Sample Bot: Customer Support Assistant

Here’s a complete example of building a customer support chatbot:

Bot Structure:

Main Flow
├── Welcome Node
│   └── Text: "Hi! I'm your support assistant. I can help with:"
│       └── Quick Replies: ["Order Status", "Return Item", "Product Question", "Talk to Human"]
├── Order Status Flow
│   ├── Question: "Please provide your order number"
│   ├── Action: Fetch order from database
│   └── Text: "Your order #{{temp.orderNumber}} is {{temp.orderStatus}}"
├── Return Flow
│   ├── Question: "What's your order number?"
│   ├── Action: Check return eligibility
│   └── Text: "I've initiated your return. You'll receive an email shortly."
└── Human Handoff Flow
    ├── Action: Create support ticket
    └── Text: "I've connected you with an agent. Please wait..."

Intent Configuration:

check_order_status

Examples:
- "where is my order"
- "order status"
- "track my package"
- "when will my order arrive"

return_item

Examples:
- "I want to return something"
- "how do I return an item"
- "return policy"
- "start a return"

product_inquiry

Examples:
- "tell me about product X"
- "what are the features of"
- "product specifications"
- "is this item in stock"

Custom Action: Fetch Order Status

/**
 * @title Get Order Status
 * @category E-commerce
 */
const getOrderStatus = async () => {
  const orderNumber = event.payload.text

  try {
    // Call your backend API
    const response = await axios.get(`https://api.yourstore.com/orders/${orderNumber}`, {
      headers: {
        'Authorization': `Bearer ${process.env.API_KEY}`
      }
    })

    temp.orderNumber = orderNumber
    temp.orderStatus = response.data.status
    temp.estimatedDelivery = response.data.estimatedDelivery
    temp.trackingUrl = response.data.trackingUrl

    return { success: true }
  } catch (error) {
    temp.error = 'Order not found'
    return { success: false }
  }
}

return getOrderStatus()

Connecting to External Services

Botpress can integrate with various external services and APIs:

Database Connections

Connect to databases deployed on Klutch.sh or external services:

Configure Database Access

For TCP services on Klutch.sh (PostgreSQL, MySQL, MongoDB):
- Use port 8000 for external connections
- Configure the service with TCP traffic type

Add Database Client in Actions

Install database client in a custom Action:

const { Pool } = require('pg')

const pool = new Pool({
  host: 'your-database.klutch.sh',
  port: 8000,
  database: 'your_database',
  user: 'your_user',
  password: process.env.DB_PASSWORD
})

const queryData = async () => {
  const result = await pool.query('SELECT * FROM customers WHERE id = $1', [event.userId])
  temp.userData = result.rows[0]
}

return queryData()

REST API Integration

Call external APIs from your bot:

/**
 * @title Call External API
 * @category Integration
 */
const callAPI = async () => {
  try {
    const response = await axios.post('https://api.example.com/endpoint', {
      userId: event.userId,
      message: event.payload.text
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.API_KEY}`
      }
    })

    temp.apiResponse = response.data
  } catch (error) {
    bp.logger.error('API call failed:', error)
    temp.apiResponse = { error: 'Service unavailable' }
  }
}

return callAPI()

Webhook Integration

Receive data from external systems:

Create Webhook Endpoint

In Botpress Studio:

Go to “Code Editor”
Create a new file: src/webhooks/external-webhook.js

module.exports = async (req, res) => {
  const { userId, message, metadata } = req.body

  // Create or retrieve user conversation
  await bp.createConversation(userId)

  // Send event to bot
  await bp.events.sendEvent({
    botId: req.params.botId,
    channel: 'api',
    target: userId,
    type: 'text',
    payload: { text: message }
  })

  res.send({ status: 'received' })
}

Configure Webhook URL

Your webhook will be available at:

https://example-app.klutch.sh/api/v1/bots/{botId}/webhook/external-webhook

Messaging Channel Configuration

Connect your bot to popular messaging platforms:

Web Chat (Built-in)

Botpress includes a customizable web chat widget:

Enable Web Chat
- In Botpress Studio, go to “Channel Configurations”
- Enable “Web Chat”
- Customize appearance and behavior

Embed on Your Website

Add this code to your website:

<script src="https://example-app.klutch.sh/assets/modules/channel-web/inject.js"></script>
<script>
  window.botpressWebChat.init({
    host: 'https://example-app.klutch.sh',
    botId: 'your-bot-id',
    botName: 'Support Bot',
    botAvatarUrl: 'https://yoursite.com/bot-avatar.png',
    showConversationsButton: false,
    enableReset: true,
    enableTranscriptDownload: false,
    className: 'webchat-container',
    containerWidth: '360px',
    layoutWidth: '360px'
  })
</script>

Slack Integration

Create Slack App
- Visit Slack API
- Click “Create New App”
- Choose “From scratch”
- Name your app and select workspace
Configure Bot Token
- Go to “OAuth & Permissions”
- Add bot token scopes: chat:write, im:history, im:read, im:write
- Install app to workspace
- Copy Bot User OAuth Token
Configure in Botpress
- In Botpress Studio, enable “Slack” channel
- Add environment variable:
  Terminal window
```
SLACK_BOT_TOKEN=xoxb-your-token-here
```
- Set webhook URL in Slack:
```
https://example-app.klutch.sh/api/v1/messaging/webhooks/slack
```

Other Channels

Botpress supports many messaging platforms:

Microsoft Teams
Facebook Messenger
WhatsApp (via Twilio)
Telegram
SMS (via Twilio)

Refer to the Botpress Channels documentation for specific integration guides.

Production Best Practices

Security Hardening

Enable Authentication

Protect your Botpress Studio interface:

SUPERADMIN_EMAIL=admin@yourdomain.com
SUPERADMIN_PASSWORD=strong-secure-password
AUTH_SECRET=random-32-char-secret-key

Use Environment Variables for Secrets

Never hardcode sensitive information:

// ❌ Bad
const apiKey = 'sk_live_abc123'

// ✅ Good
const apiKey = process.env.API_KEY

Enable HTTPS Only

Klutch.sh provides automatic HTTPS. Ensure all external integrations use HTTPS URLs.

Implement Rate Limiting

Protect your bot from abuse:

// In bot config
{
  "rateLimiting": {
    "enabled": true,
    "maxRequests": 100,
    "windowMs": 60000
  }
}

Regular Security Updates

Keep Botpress updated by specifying versions in your Dockerfile:
```
FROM botpress/server:v12.26.0
```
Regularly update to newer stable versions and redeploy.
Sanitize User Input

Always validate and sanitize user input before using in queries or API calls.

Performance Optimization

Use PostgreSQL for Production

PostgreSQL significantly outperforms SQLite for production workloads:
Terminal window
```
DATABASE_URL=postgres://user:pass@host:8000/botpress
```
Enable Caching

Configure Redis for session and state caching:
Terminal window
```
REDIS_URL=redis://your-redis-host:6379
```
Optimize NLU Models
- Use appropriate training data size (200-500 examples per intent)
- Regularly prune unused intents and entities
- Enable NLU caching for frequently detected intents
Monitor Resource Usage
- Set up monitoring in the Klutch.sh dashboard
- Watch CPU, memory, and disk usage
- Scale vertically (larger instance) if needed
Implement Conversation Pruning

Regularly archive or delete old conversations:
```
DELETE FROM events WHERE created_on < NOW() - INTERVAL '90 days';
```
Use Database Connection Pooling

Configure PostgreSQL connection pooling for better performance.

Monitoring and Logging

Enable Detailed Logging

Configure logging levels:
Terminal window
```
VERBOSE=true
DEBUG=bp:*
BP_LOGGING_ENABLED=true
```
Access Logs

View logs in the Klutch.sh dashboard or access from the volume:
Terminal window
```
/botpress/data/logs/
```
Monitor Conversation Metrics

Track key metrics in Botpress Analytics:
- Total conversations
- Average conversation length
- User retention rate
- Intent recognition accuracy
- Fallback frequency
Set Up Alerts

Configure alerts for:
- Application downtime
- High error rates
- Database connection failures
- NLU confidence below threshold
Implement Health Checks

Use the built-in health endpoint:
Terminal window
```
curl https://example-app.klutch.sh/status
```

Backup and Disaster Recovery

Automated Volume Snapshots

Schedule regular snapshots of the /botpress/data volume through the Klutch.sh dashboard.

Database Backups

For PostgreSQL, set up automated backup schedules:

# Daily backup script
pg_dump -h your-postgres-app.klutch.sh -p 8000 -U botpress_user -d botpress > botpress-backup-$(date +%Y%m%d).sql
gzip botpress-backup-$(date +%Y%m%d).sql
# Upload to S3 or backup service

Export Bot Configurations
- Regularly export bot definitions through Studio
- Store exports in version control (Git)
- Document bot flow changes
Test Recovery Procedures

Periodically test restoring from backups to ensure they work correctly.

Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container starts but Botpress UI is not accessible

Solutions:

Check logs in the Klutch.sh dashboard
Verify environment variables are set correctly (BP_HOST=0.0.0.0, BP_PORT=3000)
Ensure persistent volume is attached to /botpress/data
Verify database connectivity if using PostgreSQL
Check that port 3000 is correctly configured in traffic settings

Database Connection Errors

Symptoms: “Unable to connect to database” errors in logs

Solutions:

Verify connection string format:

DATABASE_URL=postgres://user:pass@host:8000/botpress

Check TCP port configuration (use 8000 for Klutch.sh TCP traffic)
Verify database credentials and network connectivity

Test connection manually:

psql -h your-postgres-app.klutch.sh -p 8000 -U botpress_user -d botpress

Ensure PostgreSQL database and user exist

NLU Not Working

Symptoms: Bot doesn’t recognize user intents

Solutions:

Verify NLU training completed successfully
Check intent examples are diverse and representative
Review NLU confidence scores in logs
Increase training data for low-confidence intents
Ensure language model is appropriate for your bot’s language
Clear NLU cache and retrain

Slow Response Times

Symptoms: Bot takes long to respond to messages

Solutions:

Check resource usage in Klutch.sh dashboard
Upgrade to a larger instance size
Switch from SQLite to PostgreSQL
Enable database connection pooling
Optimize custom action code
Review and optimize conversation flows
Enable caching with Redis

Messages Not Delivering to Channels

Symptoms: Bot works in emulator but not in Slack/Teams/etc.

Solutions:

Verify channel configuration and credentials
Check webhook URLs are correctly set
Ensure EXTERNAL_URL matches your actual domain
Review channel-specific logs
Test webhook endpoint manually
Verify SSL certificate is valid

Data Loss After Redeployment

Symptoms: Bots or conversations missing after redeployment

Solutions:

Critical: Ensure persistent volume is correctly attached to /botpress/data
Verify volume wasn’t accidentally deleted
Check volume mount configuration in Klutch.sh dashboard
Restore from backup if necessary
Export bots regularly to prevent data loss

Scaling Your Botpress Deployment

As your usage grows, consider these scaling strategies:

Vertical Scaling

Increase resources for your Botpress instance:

Upgrade to a larger instance type in the Klutch.sh dashboard
Increase persistent volume size if storage is constrained
Recommended specs for production:
- Small deployments (< 1,000 daily conversations): 2 CPU, 4GB RAM
- Medium deployments (1,000-10,000 daily conversations): 4 CPU, 8GB RAM
- Large deployments (10,000+ daily conversations): 8+ CPU, 16+ GB RAM

Database Scaling

Use managed PostgreSQL with read replicas for high-traffic deployments
Enable connection pooling
Implement database indexing for frequently queried fields
Consider database sharding for very large deployments

Caching Strategy

Deploy Redis for state management and caching
Enable NLU result caching
Cache frequently accessed bot configurations

Multi-Region Deployment

For global availability:

Deploy multiple Botpress instances in different regions
Use a load balancer to route traffic
Replicate database across regions
Ensure conversation state synchronization

Example Deployment Repository

For a complete working example, you can reference this sample repository structure:

botpress-on-klutch/
├── Dockerfile
├── .dockerignore
├── .gitignore
├── README.md
└── .env.example

Dockerfile:

FROM botpress/server:v12.26.0

WORKDIR /botpress

RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:3000/status || exit 1

CMD ["./bp", "--production"]

.env.example:

# Core Configuration
BP_HOST=0.0.0.0
BP_PORT=3000
BP_PRODUCTION=true
EXTERNAL_URL=https://example-app.klutch.sh

# Database (PostgreSQL recommended for production)
DATABASE_URL=postgres://botpress_user:password@postgres-host:8000/botpress

# Security
AUTH_SECRET=change-me-to-random-32-char-string
SUPERADMIN_EMAIL=admin@yourdomain.com
SUPERADMIN_PASSWORD=change-me-to-secure-password

# Storage
BPFS_STORAGE=database

# Logging (optional)
# VERBOSE=true
# DEBUG=bp:*

# Redis (optional, for caching)
# REDIS_URL=redis://redis-host:6379

# Licensing (optional, for Botpress Pro)
# BP_LICENSE_KEY=your-license-key

README.md:

# Botpress on Klutch.sh

Production-ready Botpress deployment for conversational AI applications.

## Quick Start

1. Clone this repository
2. Copy `.env.example` to `.env` and configure variables
3. Push to GitHub
4. Deploy on Klutch.sh following the official guide

## Requirements

- PostgreSQL database (recommended for production)
- Persistent volume mounted at /botpress/data

## Support

See the full deployment guide at https://docs.klutch.sh/guides/open-source-software/botpress

Additional Resources

Conclusion

Deploying Botpress on Klutch.sh provides a powerful, scalable platform for building intelligent conversational AI applications without the complexity of managing infrastructure. With automatic Dockerfile detection, persistent storage for bot data, PostgreSQL database support, secure environment management, and production-ready configurations, you can focus on creating engaging conversational experiences that drive customer satisfaction and business value.

Whether you’re building customer support chatbots, sales automation assistants, internal HR tools, or complex multi-turn conversation systems, Botpress on Klutch.sh offers the reliability, performance, and flexibility you need. Start building your conversational AI applications today and transform how your business interacts with users through natural, intelligent dialogue.

For additional help or questions, reach out to the Botpress community or explore the Klutch.sh dashboard to get started with your deployment.