How to Self-Host Activepieces (2026 Guide)

Updated 2026-09-25 · 974 words

This page may contain affiliate links. If you buy through them we may earn a commission at no extra cost to you.

Self-hosting Activepieces gets you the full MIT-licensed Community Edition, unlimited flows, unlimited runs, no artificial caps, running on your own infrastructure in about five minutes with Docker Compose. This guide covers the setup from a clean server to a production-ready instance, including the two steps most guides skip: generating your encryption keys correctly and planning for scale before you need it.

What you need before you start

You need a server or VPS with Docker and Docker Compose v2 installed (the older standalone docker-compose command isn't supported), at least 2 vCPU and 4GB of RAM for anything beyond local testing, and openssl available to generate secrets. If you're deploying somewhere the public internet needs to reach, for incoming webhook triggers, you'll also want a domain name pointed at the server, since Activepieces itself doesn't provision TLS certificates for you.

Step 1: Set up your project directory

Create a dedicated directory to keep your configuration files together and easy to back up:

mkdir -p /opt/activepieces && cd /opt/activepieces

Download the official docker-compose.yml and the .env.example template from the Activepieces repository into this directory, then copy the example file to .env, which is where your real configuration lives:

cp .env.example .env

Step 2: Generate your encryption keys

This is the step that gets skipped most often, and it's the one that causes real pain later. Activepieces needs two secrets: AP_ENCRYPTION_KEY, a 16-byte hex string that encrypts every stored connection credential (your API keys and OAuth tokens for every connected app), and AP_JWT_SECRET, a 32-byte hex string used for authentication.

Generate both with openssl:

openssl rand -hex 16   # AP_ENCRYPTION_KEY
openssl rand -hex 32   # AP_JWT_SECRET

Paste each value into the matching line in your .env file. Skip this step or lose the file later, and every connection you've configured becomes undecryptable, even with a full database backup, so treat this .env file with the same care as a password vault and back it up somewhere separate from your database backups.

Step 3: Configure your database and port

Set AP_POSTGRES_PASSWORD to a strong, unique password; the bundled Postgres container uses this on first boot. If you're running on a remote server, or want a port other than the default, change AP_HOST_PORT in your .env file, this controls the externally exposed port. Leave AP_PORT untouched: that's the port the app listens on inside the container, and changing it breaks the port mapping in the compose file rather than doing what you'd expect.

If you're exposing the instance publicly, also set AP_FRONTEND_URL to your actual domain (including https://), since this is what Activepieces uses to generate correct webhook and OAuth callback URLs.

Quick reference for the variables you just set:

Step 4: Launch and create your admin account

Start everything with:

docker compose up -d

Give it a minute for Postgres and Redis to initialize, then visit http://localhost:8080, or https://your-domain.com if you configured a public URL. The first account you create through the signup screen automatically becomes the platform administrator; there's no default username or password to change, so create this account immediately after launch rather than leaving the instance open.

Step 5: Put TLS in front of it (production)

For anything beyond local testing, put a reverse proxy in front of the Activepieces container to handle TLS. Traefik and Caddy are the two most common choices in the self-hosting community, both handle automatic certificate provisioning and renewal via Let's Encrypt with a few lines of configuration, so you're not managing certificates by hand. This step is non-negotiable if any of your flows use webhook triggers, since the services calling your webhook need a secure endpoint to reach.

Step 6: Harden it for real use

Set every container's restart policy to unless-stopped in your compose file, so a crashed container comes back on its own instead of silently staying down. Pin your Docker image to a specific version tag once you've confirmed the instance is stable, rather than tracking :latest, so an upstream update doesn't change your running instance unexpectedly. Finally, schedule a regular Postgres backup (a daily pg_dump to off-server storage is enough for most small teams) alongside your separate .env backup.

Step 7: Scale workers as usage grows

If you start running many concurrent flows or high-frequency triggers, the fix isn't a bigger single container, it's more workers. Scale horizontally with:

docker compose up -d --scale activepieces-worker=3

This runs three worker containers processing flow executions in parallel, and it's a live change you can apply and adjust without touching your data or reinstalling anything.

Common mistakes to avoid

Skipping the encryption key generation and leaving the example values from .env.example untouched is the most common one we've seen; the instance will run, but every connection you configure is at risk the moment that file is lost or moved. Changing AP_PORT instead of AP_HOST_PORT when you actually just want a different external port is the second, it breaks the container's internal port mapping rather than doing what most people expect. And running a production instance without a reverse proxy and TLS works right up until a webhook-based integration silently fails because the remote service refuses to call an insecure endpoint.

What's next

Once your instance is running, our Activepieces review covers what actually holds up once you're building real workflows, including where its simpler builder starts to feel limiting compared to a code-first tool. If you're deciding between Activepieces and the platform it's compared to most, n8n vs Activepieces covers that head-to-head, and our best self-hosted Zapier alternatives roundup places it against the wider self-hosted field if you're still deciding.

Try Activepieces

Save this to Pinterest