Skip to content
Klutch.sh Docs

Deploying a Budibase App

Introduction

Budibase is an open-source low-code platform that empowers you to build powerful internal tools, business apps, and workflows in minutes rather than months. With an intuitive drag-and-drop interface, powerful database integrations, and automation capabilities, Budibase is perfect for teams looking to quickly develop custom applications without extensive coding.

Budibase features:

  • Visual App Builder: Create applications with a drag-and-drop interface
  • Database Integration: Connect to PostgreSQL, MySQL, MongoDB, CouchDB, REST APIs, and more
  • Automation: Build workflows with triggers, actions, and integrations
  • Custom Components: Extend with custom JavaScript components
  • Role-Based Access Control: Secure your apps with granular permissions
  • Self-Hosted: Full control over your data and infrastructure
  • Mobile Responsive: Apps automatically adapt to mobile devices
  • Multi-Tenancy: Deploy apps for multiple organizations

This comprehensive guide walks you through deploying Budibase on Klutch.sh using Docker, including detailed installation steps, sample configurations, and production-ready best practices for persistent storage.

Prerequisites

Before you begin, ensure you have the following:

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Budibase deployment project:

Terminal window
mkdir budibase-klutch
cd budibase-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your Budibase container configuration:

FROM budibase/budibase:latest


# Set working directory
WORKDIR /app


# Optional: Add custom configuration
# COPY ./config /app/config


# Expose the default Budibase port
EXPOSE 10000


# The base image already has the CMD configured
# CMD is typically: ["./budibase"]

Note: Budibase provides official Docker images that are pre-configured and ready to use. The example above uses the latest stable version.

Step 3: (Optional) Create Environment Variables File

Create a .env.example file to document the environment variables your deployment might need:

Terminal window
# .env.example - Environment variables template


# Application settings
BUDIBASE_ENVIRONMENT=production
PORT=10000


# Security
JWT_SECRET=your-jwt-secret-here
INTERNAL_API_KEY=your-internal-api-key-here
MINIO_ACCESS_KEY=your-minio-access-key
MINIO_SECRET_KEY=your-minio-secret-key


# CouchDB Configuration
COUCH_DB_USER=admin
COUCH_DB_PASSWORD=your-couchdb-password


# Redis Configuration (for multi-instance deployments)
REDIS_URL=redis://localhost:6379


# Email Configuration (optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASSWORD=your-smtp-password


# Optional: Custom branding
PLATFORM_TITLE="My Budibase Platform"
LOGO_URL=https://example.com/logo.png

Important: Never commit actual secrets to your repository. This file is just a template.

Step 4: (Optional) Create a Docker Ignore File

Create a .dockerignore file to exclude unnecessary files from your Docker build:

.git
.gitignore
.env
.env.example
node_modules
*.log
README.md

Step 5: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Budibase setup locally:

Terminal window
# Build the Docker image
docker build -t my-budibase .


# Run the container
docker run -d \
  --name budibase-test \
  -p 10000:10000 \
  -v budibase-data:/data \
  -e JWT_SECRET=test-secret \
  -e INTERNAL_API_KEY=test-api-key \
  -e MINIO_ACCESS_KEY=test-access \
  -e MINIO_SECRET_KEY=test-secret \
  -e COUCH_DB_USER=admin \
  -e COUCH_DB_PASSWORD=admin \
  my-budibase


# Check if it's running
docker ps


# View logs
docker logs budibase-test


# Access Budibase at http://localhost:10000


# Stop and remove the test container when done
docker stop budibase-test
docker rm budibase-test

Step 6: Push to GitHub

Commit your Dockerfile and configuration files to your GitHub repository:

Terminal window
git add Dockerfile .env.example .dockerignore
git commit -m "Add Budibase Docker configuration"
git remote add origin https://github.com/yourusername/budibase-klutch.git
git push -u origin main

Deploying Without a Dockerfile

Klutch.sh uses Nixpacks to automatically detect and build your application. However, since Budibase is primarily distributed as pre-built Docker images, we recommend using the Dockerfile approach for Budibase deployments to ensure you’re using the official, tested images.

If you want to deploy Budibase from source or with custom modifications:

  1. Clone the Budibase repository and push your customizations to GitHub
  2. Log in to Klutch.sh
  3. Create a new project
  4. Create a new app:
    • Select your GitHub repository and branch
    • Select HTTP as the traffic type
    • Set the internal port to 10000
    • Add environment variables as needed

Note: If you need to customize the start or build command, you can set environment variables like START_COMMAND or BUILD_COMMAND for Nixpacks.

Klutch.sh will automatically detect a Dockerfile in your repository’s root directory. This is the recommended approach for Budibase deployments.

Follow these steps to deploy Budibase on Klutch.sh with persistent storage:

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “Budibase Platform”).

    3. Create a New App

      Navigate to Create App and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (Budibase web interface uses HTTP/HTTPS)
      • Internal Port: Set to 10000 (the port your container listens on)

    6. Set Environment Variables

      Add the following environment variables for your Budibase configuration:

      • BUDIBASE_ENVIRONMENT: Set to production
      • JWT_SECRET: A strong secret key for JWT token signing (use a secure password generator)
      • INTERNAL_API_KEY: A strong secret key for internal API authentication
      • MINIO_ACCESS_KEY: Access key for MinIO object storage
      • MINIO_SECRET_KEY: Secret key for MinIO object storage
      • COUCH_DB_USER: CouchDB admin username (default: admin)
      • COUCH_DB_PASSWORD: Strong password for CouchDB
      • Add any other custom environment variables your setup requires

      Security Note: Always use strong, unique secret keys for production deployments. Each key should be at least 32 characters long and randomly generated.

    7. Attach a Persistent Volume

      This is critical for ensuring your application data, databases, and user-uploaded files persist across deployments and restarts:

      • In the Volumes section, click “Add Volume”
      • Mount Path: Enter /data (this is where Budibase stores application data, databases, and file uploads)
      • Size: Choose an appropriate size based on your expected data volume (minimum 5GB recommended, 10GB or more for production)

      Important: Budibase requires persistent storage to maintain your apps, database records, user uploads, and configurations between container restarts.

    8. Configure Additional Settings

      • Region: Select the region closest to your users for optimal latency
      • Compute Resources: Choose CPU and memory based on your workload (minimum 1GB RAM recommended for Budibase)
      • Instances: Start with 1 instance (you can scale up later based on usage)

    9. Deploy Your Application

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image
      • Attach the persistent volume
      • Start your Budibase container
      • Assign a URL for external access

    10. Access Your Budibase Instance

      Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Navigate to this URL in your browser to access your Budibase instance and complete the initial setup.

Getting Started with Budibase

Once your Budibase instance is deployed and running, you can start building applications:

Initial Setup

  1. Open your deployed Budibase URL (example-app.klutch.sh) in a browser
  2. Create your admin account when prompted
  3. Set up your organization details
  4. You’ll be taken to the Budibase builder interface

Creating Your First App

Here’s how to create a simple employee directory application:

Step 1: Create a New App

  1. Click “Create new app” on the Budibase home screen
  2. Enter a name (e.g., “Employee Directory”)
  3. Choose to start from scratch or use a template

Step 2: Create a Data Source

// Example: Define employee table structure
{
  "name": "employees",
  "schema": {
    "first_name": { "type": "string", "required": true },
    "last_name": { "type": "string", "required": true },
    "email": { "type": "string", "required": true },
    "department": { "type": "string" },
    "hire_date": { "type": "date" },
    "phone": { "type": "string" },
    "active": { "type": "boolean", "default": true }
  }
}

Step 3: Build Your Interface

  1. Go to the “Design” tab
  2. Drag and drop components (tables, forms, buttons)
  3. Connect components to your data source
  4. Customize styling and layout

Step 4: Add Automation

// Example automation: Send welcome email on new employee
{
  "trigger": "Row Created",
  "table": "employees",
  "actions": [
    {
      "type": "Send Email",
      "to": "{{ trigger.row.email }}",
      "subject": "Welcome to the team!",
      "body": "Hi {{ trigger.row.first_name }}, welcome aboard!"
    }
  ]
}

Sample Application Structure

Here’s a sample multi-screen application structure:

📱 Employee Management App
├── 🏠 Dashboard
│   ├── Total Employees (Card)
│   ├── Department Breakdown (Chart)
│   └── Recent Hires (Table)
├── 👥 Employees List
│   ├── Search & Filter Bar
│   ├── Employee Table
│   └── Add Employee Button
├── 📝 Employee Details
│   ├── Profile Information
│   ├── Department & Role
│   ├── Contact Details
│   └── Edit/Delete Actions
└── 📊 Reports
    ├── Headcount by Department
    ├── Tenure Analysis
    └── Export Options

Connecting to External Databases

Budibase can connect to external data sources. Here’s an example PostgreSQL connection:

// PostgreSQL connection configuration
{
  "type": "PostgreSQL",
  "host": "your-postgres-host.com",
  "port": 5432,
  "database": "your_database",
  "username": "your_username",
  "password": "{{ env.DB_PASSWORD }}", // Use environment variable
  "ssl": true
}

Using REST API Integration

Connect to external APIs:

// REST API datasource example
{
  "name": "External API",
  "config": {
    "url": "https://api.example.com",
    "defaultHeaders": {
      "Authorization": "Bearer {{ env.API_TOKEN }}",
      "Content-Type": "application/json"
    }
  },
  "queries": {
    "getUsers": {
      "method": "GET",
      "path": "/users",
      "transformer": "return data.users"
    }
  }
}

Production Best Practices

Security Recommendations

  • Use Strong Secrets: Never use default or weak secret keys in production. Generate strong, random keys using a password manager or cryptographic tools:

    Terminal window
    # Generate secure random keys
    openssl rand -base64 32  # For JWT_SECRET
    openssl rand -base64 32  # For INTERNAL_API_KEY
    openssl rand -base64 32  # For MINIO_SECRET_KEY

  • Environment Variables: Store all sensitive credentials as environment variables in Klutch.sh, never in your Dockerfile or repository.

  • HTTPS: Klutch.sh provides HTTPS by default, ensuring encrypted connections to your Budibase instance.

  • Regular Backups: Implement a backup strategy for your persistent volume data, especially the /data directory.

  • Access Control: Configure role-based access control (RBAC) within Budibase for your apps.

  • Database Security: If using external databases, ensure they’re properly secured with strong passwords and network restrictions.

  • Update Regularly: Keep your Budibase Docker image updated to the latest stable version for security patches.

Performance Optimization

  • Resource Monitoring: Monitor your Budibase instance’s CPU and memory usage through Klutch.sh dashboard.
  • Volume Size: Allocate sufficient storage for your expected data growth. Budibase stores databases, uploads, and app definitions.
  • Scaling: If you experience high traffic, consider:
    • Scaling up compute resources (CPU/RAM)
    • Using Redis for caching and session management
    • Implementing a load balancer for multiple instances
  • Database Optimization: For large datasets, use external databases (PostgreSQL, MySQL) instead of internal CouchDB.
  • Caching: Enable caching for frequently accessed data and static assets.

Data Management

  • Persistent Volumes: Always use persistent volumes for production deployments to prevent data loss.

  • Regular Maintenance: Periodically check disk usage and clean up unnecessary data:

    Terminal window
    # Monitor volume usage
    docker exec budibase df -h /data

  • Database Backups: Implement automated backup schedules for your CouchDB or external database:

    • Back up the /data volume regularly
    • Test backup restoration procedures
    • Store backups in a separate location or cloud storage

  • File Upload Management: Monitor and manage user-uploaded files to prevent storage exhaustion.

Monitoring

Monitor your Budibase deployment for:

  • Response times and page load speeds
  • CPU and memory utilization
  • Disk space usage on persistent volumes
  • Database query performance
  • Application errors and logs (viewable in Klutch.sh dashboard)
  • User activity and concurrent connections
  • API rate limits and usage patterns

Multi-Instance Deployment

For high availability, deploy multiple Budibase instances:

  1. Set up Redis for session management:

    Terminal window
    REDIS_URL=redis://your-redis-host:6379
    ENABLE_REDIS_CLUSTERING=true

  2. Configure shared storage: Ensure all instances share the same persistent volume or use S3-compatible storage:

    Terminal window
    USE_MINIO=true
    MINIO_URL=https://your-minio-host

  3. Enable clustering: Configure Budibase for cluster mode:

    Terminal window
    CLUSTER_MODE=true
    CLUSTER_PORT=10001

Troubleshooting

Cannot Access Budibase

  • Verify that your deployment is running in the Klutch.sh dashboard
  • Check that the internal port is set to 10000
  • Ensure HTTP is selected as the traffic type
  • Review deployment logs for any startup errors
  • Verify all required environment variables are set

Data Not Persisting

  • Verify that the persistent volume is correctly attached at /data
  • Check that the volume has sufficient space allocated
  • Ensure the volume mount path matches Budibase’s data directory
  • Check file permissions on the volume

Performance Issues

  • Review resource utilization in the Klutch.sh dashboard
  • Consider increasing CPU and memory allocation (minimum 1GB RAM for Budibase)
  • Check if disk I/O is a bottleneck (upgrade volume if needed)
  • Monitor database query performance
  • Consider using external databases for better performance
  • Enable Redis caching for improved response times

Configuration Problems

  • Verify all environment variables are set correctly in Klutch.sh
  • Check Docker logs for configuration errors
  • Ensure the Dockerfile is correctly formatted and builds locally
  • Verify JWT_SECRET and other secrets are properly set
  • Check CouchDB credentials and connectivity

Database Connection Issues

  • For external databases, verify network connectivity
  • Check database credentials in environment variables
  • Ensure database server allows connections from Klutch.sh
  • Test database connection strings locally first

Email/SMTP Issues

  • Verify SMTP credentials and server settings
  • Test email configuration with a simple test email
  • Check SMTP port is correct (usually 587 for TLS)
  • Ensure firewall rules allow outbound SMTP connections

Additional Resources

Conclusion

Deploying Budibase to Klutch.sh with Docker provides a robust, self-hosted low-code platform with full control over your business applications and data. By following this guide, you’ve set up a production-ready Budibase instance with persistent storage, proper security configurations, and the ability to scale as your needs grow. Your platform is now ready to empower your team to build custom internal tools, automate workflows, and connect to various data sources—all while maintaining complete control over your infrastructure and data privacy.