Skip to content
Klutch.sh Docs

Deploying Activepieces

Introduction

Activepieces is a powerful open-source workflow automation platform that enables you to build and run automated workflows with an intuitive visual interface. Similar to tools like Zapier, Make (formerly Integromat), and n8n, Activepieces allows you to connect different services, APIs, and applications to create sophisticated automation workflows without writing code. It features a rich ecosystem of pre-built integrations, a visual flow builder, webhook support, scheduling capabilities, and can be self-hosted for complete control over your data and automations.

This comprehensive guide walks you through deploying Activepieces on Klutch.sh using a Dockerfile. We’ll cover everything from initial setup and database configuration to persistent storage, environment variables, and production-ready deployment strategies. Whether you’re automating business processes, connecting SaaS applications, or building complex data pipelines, this guide provides the detailed steps you need to get Activepieces running on Klutch.sh.

Prerequisites

Before deploying Activepieces, ensure you have:

  • A Klutch.sh account
  • A GitHub repository for your Activepieces deployment files
  • A Klutch.sh project created for your application
  • Basic familiarity with Docker, environment variables, and workflow automation concepts
  • (Recommended for production) A PostgreSQL database instance

Understanding Activepieces Architecture

Activepieces consists of several components:

  • Backend API: Handles workflow execution, piece management, and business logic
  • Frontend UI: The visual workflow builder and dashboard
  • Database: Stores workflow definitions, execution history, and configuration (PostgreSQL recommended)
  • Workers: Execute workflow pieces and handle background jobs
  • File Storage: Stores uploaded files and temporary data

For production deployments, Activepieces requires a persistent database (PostgreSQL is recommended) and persistent storage for file uploads and execution artifacts.

Getting Started: Project Structure

To deploy Activepieces on Klutch.sh, you’ll need to create a repository with the necessary configuration files. Here’s the recommended structure:

activepieces-deploy/
├── Dockerfile
├── .dockerignore
├── docker-compose.yml (for local development only)
└── README.md

Note: Docker Compose can be used for local development and testing, but Klutch.sh does not support Docker Compose for deployment. We’ll use a standalone Dockerfile for deployment.

Deploying with a Dockerfile

Klutch.sh automatically detects a Dockerfile if present in the root directory of your repository. You don’t need to specify Docker as a deployment option in the UI—the platform handles this automatically.

1. Create the Dockerfile

Create a Dockerfile in your repository root with the following content. This uses the official Activepieces image and configures it for deployment on Klutch.sh:

# Use the official Activepieces image
FROM activepieces/activepieces:latest


# The container listens on port 80 by default
# Activepieces backend and frontend are served on this port
EXPOSE 80


# Environment variables will be configured through Klutch.sh dashboard
# No CMD needed - the base image provides the default command

This simple Dockerfile uses the official Activepieces image, which includes all necessary components. The image is production-ready and regularly updated by the Activepieces team.

2. Create a .dockerignore file

To optimize your Docker build, create a .dockerignore file:

.git
.gitignore
node_modules
npm-debug.log
README.md
.DS_Store
.env
.env.*
docker-compose.yml

3. Push to GitHub

Commit your files and push to your GitHub repository:

Terminal window
git add Dockerfile .dockerignore
git commit -m "Add Activepieces Dockerfile for Klutch.sh deployment"
git push origin main

Setting Up the Database

Activepieces requires a PostgreSQL database for production use. You have two options:

Option 1: Deploy PostgreSQL on Klutch.sh

    1. In the Klutch.sh dashboard, create a new app for PostgreSQL
    2. Use the official PostgreSQL Docker image
    3. Set up a persistent volume for the database data (mount path: /var/lib/postgresql/data)
    4. Configure environment variables for PostgreSQL (username, password, database name)
    5. Note the internal connection details for use in your Activepieces configuration

For detailed PostgreSQL setup instructions, see the Klutch.sh PostgreSQL guide.

Option 2: Use an External PostgreSQL Service

You can also use a managed PostgreSQL service like:

External services simplify maintenance and backups but may have additional costs.

Deploying Activepieces on Klutch.sh

Follow these steps to deploy Activepieces:

    1. Log in to Klutch.sh: Navigate to the Klutch.sh dashboard

    2. Create a new app: Click “Create App” and connect your GitHub repository containing the Dockerfile

    3. Configure basic settings:

      • Name: Choose a descriptive name (e.g., “activepieces-prod”)
      • Branch: Select the branch to deploy (usually main or master)
      • Region: Choose a region close to your users

    4. Set traffic type: Select HTTP as the traffic type

    5. Configure the internal port: Set the internal port to 80 (Activepieces listens on port 80 by default)

    6. Configure environment variables (see next section for details):

      • AP_POSTGRES_DATABASE
      • AP_POSTGRES_HOST
      • AP_POSTGRES_PASSWORD
      • AP_POSTGRES_PORT
      • AP_POSTGRES_USERNAME
      • AP_ENCRYPTION_KEY
      • AP_JWT_SECRET
      • AP_FRONTEND_URL
      • AP_API_KEY (optional, for programmatic access)

    7. Attach persistent volumes:

      • Mount path: /root/.activepieces
      • Size: At least 5GB (adjust based on expected usage)

    8. Configure compute resources: Choose instance size based on your expected workload

      • Small workflows: 1 CPU / 1GB RAM minimum
      • Production workloads: 2+ CPUs / 4GB+ RAM recommended

    9. Click “Create”: Klutch.sh will detect your Dockerfile, build the image, and deploy your app

Your Activepieces instance will be available at a URL like example-app.klutch.sh once deployment completes.

Environment Variables Configuration

Activepieces requires several environment variables for proper operation. Configure these in the Klutch.sh dashboard under your app’s settings:

Required Variables

Terminal window
# Database Configuration
AP_POSTGRES_DATABASE=activepieces
AP_POSTGRES_HOST=your-postgres-host
AP_POSTGRES_PORT=5432
AP_POSTGRES_USERNAME=activepieces_user
AP_POSTGRES_PASSWORD=your-secure-password


# Security & Encryption
AP_ENCRYPTION_KEY=your-random-32-char-encryption-key
AP_JWT_SECRET=your-random-jwt-secret-key


# Application URLs
AP_FRONTEND_URL=https://example-app.klutch.sh
AP_WEBHOOK_TIMEOUT_SECONDS=30

Generating Secret Keys

Generate secure random keys for encryption and JWT:

Terminal window
# Generate encryption key (32 characters)
openssl rand -hex 16


# Generate JWT secret
openssl rand -hex 32

Important: Store these keys securely and never commit them to your repository. Use Klutch.sh’s environment variable feature to store sensitive values.

Optional Variables

Terminal window
# Telemetry (set to false to disable)
AP_TELEMETRY_ENABLED=false


# Execution mode
AP_EXECUTION_MODE=SANDBOXED


# Rate limiting
AP_RATE_LIMIT_AUTHN_ENABLED=true


# API Key for programmatic access
AP_API_KEY=your-api-key-for-external-access


# Frontend configuration
AP_FRONTEND_URL=https://your-custom-domain.com


# Email configuration (for notifications)
AP_NOTIFICATION_EMAIL_SMTP_HOST=smtp.example.com
AP_NOTIFICATION_EMAIL_SMTP_PORT=587
AP_NOTIFICATION_EMAIL_SMTP_USER=your-email@example.com
AP_NOTIFICATION_EMAIL_SMTP_PASSWORD=your-email-password
AP_NOTIFICATION_EMAIL_FROM=noreply@example.com

For a complete list of environment variables, see the Activepieces documentation.

Persistent Storage Configuration

Activepieces needs persistent storage for:

  • File uploads and attachments
  • Workflow execution artifacts
  • Temporary data and caching
  • Plugin storage

In Klutch.sh, attach a persistent volume with the following configuration:

  • Mount Path: /root/.activepieces
  • Volume Size: Start with 5GB minimum, increase based on usage
  • Note: Volume names are automatically managed by Klutch.sh; you only need to specify the mount path and size

This ensures that your workflow data, file uploads, and execution history persist across container restarts and redeployments.

Sample Workflow: Getting Started with Activepieces

Once your Activepieces instance is deployed, follow these steps to create your first workflow:

    1. Access the UI: Navigate to your Activepieces URL (e.g., https://example-app.klutch.sh)

    2. Create an account: On first visit, you’ll be prompted to create an admin account

    3. Create a new flow:

      • Click “Create Flow” in the dashboard
      • Give your flow a descriptive name

    4. Add a trigger: Choose from:

      • Schedule: Run workflows on a schedule (cron-like)
      • Webhook: Trigger via HTTP POST request
      • App Event: Trigger from integrated apps (e.g., new email, new row in spreadsheet)

    5. Add actions: Build your workflow by adding steps:

      • Connect to services (Gmail, Slack, Google Sheets, etc.)
      • Transform data with built-in operations
      • Add conditional logic and loops
      • Make HTTP requests to any API

    6. Test your workflow: Use the test button to run your workflow with sample data

    7. Enable and publish: Once tested, enable your workflow to start processing real data

Example: Simple Webhook Workflow

Here’s a sample workflow that receives webhook data and logs it:

  1. Trigger: Webhook trigger

    • Generates a webhook URL like: https://example-app.klutch.sh/api/v1/webhooks/your-webhook-id

  2. Action 1: Data Mapper

    • Extract specific fields from webhook payload
    • Transform data format if needed

  3. Action 2: HTTP Request

    • Send processed data to another service
    • Or save to a database

Test the webhook with curl:

Terminal window
curl -X POST https://example-app.klutch.sh/api/v1/webhooks/your-webhook-id \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user.signup",
    "email": "user@example.com",
    "timestamp": "2024-01-15T10:30:00Z"
  }'

Local Development with Docker Compose

For local development and testing before deploying to Klutch.sh, you can use Docker Compose. Create a docker-compose.yml file:

version: '3.8'


services:
  activepieces:
    image: activepieces/activepieces:latest
    ports:
      - "8080:80"
    environment:
      - AP_POSTGRES_DATABASE=activepieces
      - AP_POSTGRES_HOST=postgres
      - AP_POSTGRES_PORT=5432
      - AP_POSTGRES_USERNAME=postgres
      - AP_POSTGRES_PASSWORD=postgres
      - AP_ENCRYPTION_KEY=your-local-encryption-key-32-chars
      - AP_JWT_SECRET=your-local-jwt-secret
      - AP_FRONTEND_URL=http://localhost:8080
      - AP_TELEMETRY_ENABLED=false
    depends_on:
      - postgres
    volumes:
      - activepieces-data:/root/.activepieces


  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=activepieces
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"


volumes:
  activepieces-data:
  postgres-data:

Run locally:

Terminal window
docker-compose up -d

Access at http://localhost:8080.

Remember: Docker Compose is for local development only. For production deployment on Klutch.sh, use the standalone Dockerfile approach described earlier.

Production Best Practices

Security

  • Use strong secrets: Generate cryptographically secure keys for AP_ENCRYPTION_KEY and AP_JWT_SECRET
  • Enable HTTPS: Klutch.sh provides automatic HTTPS for all apps
  • Rotate credentials: Regularly update database passwords and API keys
  • Restrict access: Use IP allowlisting or authentication middleware if needed
  • Keep updated: Regularly update to the latest Activepieces version for security patches

Performance

  • Database optimization: Use connection pooling and optimize database queries
  • Scale horizontally: Run multiple instances behind a load balancer for high availability
  • Monitor resources: Track CPU, memory, and disk usage in the Klutch.sh dashboard
  • Clean up executions: Configure retention policies to remove old workflow execution logs
  • Use caching: Enable caching for frequently accessed data

Reliability

  • Backup regularly: Set up automated backups for your PostgreSQL database
  • Use persistent volumes: Ensure all data is stored on persistent volumes
  • Health checks: Configure health check endpoints to monitor application status
  • Graceful degradation: Design workflows with error handling and retry logic
  • Monitoring: Set up alerts for failed workflows and system errors

Scaling

Start with these baseline resources and adjust based on monitoring:

  • Small/Testing: 1 CPU, 1GB RAM
  • Medium/Production: 2 CPUs, 4GB RAM
  • Large/Enterprise: 4+ CPUs, 8GB+ RAM

Database sizing:

  • Small: 2GB storage, 1 CPU
  • Medium: 10GB storage, 2 CPUs
  • Large: 50GB+ storage, 4+ CPUs

Custom Domain Configuration

To use a custom domain with your Activepieces instance:

    1. In the Klutch.sh dashboard, navigate to your Activepieces app

    2. Go to the “Domains” section and click “Add Domain”

    3. Enter your custom domain (e.g., workflows.yourdomain.com)

    4. Follow the DNS configuration instructions provided by Klutch.sh

    5. Update the AP_FRONTEND_URL environment variable to match your custom domain:

      Terminal window
      AP_FRONTEND_URL=https://workflows.yourdomain.com

    6. Redeploy your app to apply the changes

Klutch.sh automatically provisions and manages SSL/TLS certificates for your custom domain. For more details, see the Custom Domains guide.

Troubleshooting

Common Issues

Connection refused / 502 errors

  • Verify the internal port is set to 80
  • Check that the container started successfully in the logs
  • Ensure environment variables are correctly configured

Database connection failures

  • Verify PostgreSQL is running and accessible
  • Check database credentials in environment variables
  • Ensure network connectivity between Activepieces and database
  • Verify the database name exists and user has proper permissions

Workflows not executing

  • Check the workflow execution logs in the UI
  • Verify webhook URLs are accessible from external services
  • Ensure the execution mode is set correctly (AP_EXECUTION_MODE=SANDBOXED)
  • Check resource limits aren’t being exceeded

File upload issues

  • Verify the persistent volume is properly mounted at /root/.activepieces
  • Check available disk space on the volume
  • Ensure proper file permissions

UI not loading

  • Clear browser cache and cookies
  • Check browser console for JavaScript errors
  • Verify AP_FRONTEND_URL matches your actual URL
  • Check that HTTPS is properly configured

Viewing Logs

Access application logs through the Klutch.sh dashboard to diagnose issues:

  1. Navigate to your Activepieces app
  2. Click on “Logs” in the sidebar
  3. Filter by time range and log level
  4. Look for error messages and stack traces

Upgrading Activepieces

To upgrade to a newer version of Activepieces:

    1. Backup your data: Create a backup of your PostgreSQL database and persistent volumes

    2. Update the Dockerfile: Change the image tag to the desired version:

      FROM activepieces/activepieces:0.30.0

      Or use latest for the most recent version.

    3. Review release notes: Check the Activepieces releases page for breaking changes

    4. Test in staging: If possible, test the upgrade in a staging environment first

    5. Deploy: Push your changes to GitHub to trigger a new deployment on Klutch.sh

    6. Verify: Check that existing workflows still function correctly after upgrade

Monitoring and Observability

Built-in Monitoring

Activepieces provides built-in execution monitoring through its dashboard:

  • View workflow execution history
  • Monitor success/failure rates
  • Inspect individual execution logs
  • Set up email notifications for failures

External Monitoring

For production environments, consider integrating external monitoring:

For Klutch.sh-specific monitoring capabilities, see the Monitoring documentation.

Backup and Disaster Recovery

Database Backups

Regular database backups are critical for disaster recovery:

For Klutch.sh-hosted PostgreSQL:

  • Use Klutch.sh’s built-in backup features
  • Configure automated backup schedules
  • Test restore procedures regularly

For external PostgreSQL services:

  • Most managed services provide automated backups
  • Configure point-in-time recovery if available
  • Download periodic manual backups for extra safety

Volume Backups

Backup your persistent volume data:

  1. Create snapshots through Klutch.sh dashboard
  2. Schedule regular backups
  3. Store backups in a different region for redundancy

Disaster Recovery Plan

  1. Document your configuration: Keep a copy of all environment variables and settings
  2. Test recovery: Periodically test restoring from backups
  3. Have a rollback plan: Keep previous Docker images available for quick rollback
  4. Monitor backup status: Set up alerts for failed backups

Resources and Further Reading

Official Documentation

Klutch.sh Resources

Community

Conclusion

You now have a comprehensive understanding of how to deploy Activepieces on Klutch.sh with a Dockerfile. This setup provides a production-ready workflow automation platform with persistent storage, secure configuration, and scalability built in.

Key takeaways:

  • Klutch.sh automatically detects and builds your Dockerfile
  • PostgreSQL is required for production deployments
  • Persistent volumes ensure data survives container restarts
  • Environment variables control all configuration
  • The platform provides automatic HTTPS and domain management
  • Regular backups and monitoring are essential for production use

Start building powerful automation workflows with Activepieces on Klutch.sh today!