How to Self-Host Activepieces with Docker in 2026: One-Command Install, Production Env, and Troubleshooting

Self-hosting Activepieces runs the automation engine on a server you control, instead of paying for Activepieces Cloud plans that bill by credits. The official install is one shell command that writes a Docker Compose stack with four containers: the app, a worker, PostgreSQL, and Redis. Cost comparisons live in our n8n vs Activepieces self-hosting guide and our Zapier to Activepieces migration guide. This guide covers only the install, the checks, the production settings, and the fixes for the errors the docs describe.

Prerequisites

According to the Activepieces Docker Compose install page, self-hosting needs Docker Compose v2, at least 2 vCPU and 4 GB of RAM, and WSL2 on Windows. Make sure your server meets those requirements before you start.

• A Linux VPS or home server with at least 2 vCPU and 4 GB of RAM.
• Docker Compose v2. The older hyphenated docker-compose command does not work with this stack.
• A free host port. The default is 8080.
• A public URL if you need webhooks. Third-party services must be able to reach AP_FRONTEND_URL.

Check your Compose version:

docker compose version

If the command is missing or reports an error, install the Docker Compose plugin before continuing.

The installer is a remote script. You can print it without running it first with curl -fsSL https://get.activepieces.com, as the install page describes.

Step 1 — One-command install

The one-command installer writes the Compose configuration, generates secrets, and starts the stack in a folder you choose. According to the installation overview, the Docker Compose path with PostgreSQL and Redis is the recommended self-host option, and the script wraps it into a single command.

Run the installer:

curl -fsSL https://get.activepieces.com | sh

To pick a different port and folder, pass flags:

curl -fsSL https://get.activepieces.com | sh -s -- --port 8090 --dir /opt/activepieces

The two flags are:

• --port <port>: the host port for the web app. The default is 8080.
• --dir <path>: where the .env file and Compose assets go. The default is ./activepieces.

The manual route

If you want to read the Compose file before anything starts, the docs describe a manual route. Clone the repository, generate the secrets, set the edition, then start the stack:

git clone --depth 1 https://github.com/activepieces/activepieces.git
cd activepieces
sh tools/deploy.sh

Confirm the secrets were generated:

grep -E '^(AP_ENCRYPTION_KEY|AP_JWT_SECRET|AP_POSTGRES_PASSWORD)=' .env

Every line must show a value. The docs warn that deploy.sh needs openssl. Without it, the script can still report success while leaving the values blank. If any value is empty, install openssl and run sh tools/deploy.sh again.

Next, set the edition and sandbox mode in .env:

AP_EDITION=ee
AP_EXECUTION_MODE=SANDBOX_CODE_ONLY

The template ships with AP_EXECUTION_MODE=UNSANDBOXED, which the server rejects at startup on the ee edition. The ee edition is also what lets you activate a license key later, according to the Docker Compose install page.

In docker-compose.yml, give the worker its own internal address:

worker:
  environment:
    - AP_CONTAINER_TYPE=WORKER
    - AP_FRONTEND_URL=http://app

Both services share .env, where AP_FRONTEND_URL is your public URL. Inside the worker container, that public address points back at the worker itself, so the worker needs the app’s service name instead.

Start the stack:

docker compose -p activepieces up -d

Step 2 — Verify the stack is healthy

A healthy install has four containers running and a health endpoint that responds. The Docker Compose install page names the four services as app, worker, postgres, and redis, and says the app serves the UI and API on port 8080.

Check the containers:

docker compose -p activepieces ps

All four should show Up. Then query the health endpoint:

curl http://localhost:8080/api/v1/health

Open http://localhost:8080, or your server’s IP and port, and create the first account. That account becomes the platform administrator, because the install has no default login. Then go to Platform Admin → Operations → Workers. At least one worker should be listed. If the list is empty, jump to the troubleshooting section below.

The app container serves the web interface and API. The worker runs your flows. postgres stores flows, runs, and connections. redis is the job queue. Your data lives in the postgres_data Docker volume, not in the activepieces folder.

Step 3 — Production environment checklist

Before you send real traffic through the server, review the settings that matter for production. The installer fills in the database and Redis connection settings. You must check the public URL and the keys. The environment variables reference marks the required production variables with a ❗. These are the four you need to review and, where noted, generate yourself:

• AP_FRONTEND_URL: the public URL used to build redirect and webhook URLs. It must be reachable by third parties for webhooks and app triggers to work.
• AP_ENCRYPTION_KEY: the key that encrypts stored connections. The reference says to generate it with openssl rand -hex 16.
• AP_JWT_SECRET: the key that signs authentication tokens. The reference says to generate it with openssl rand -hex 32.
• AP_POSTGRES_PASSWORD: the database password. Generate it with openssl rand -hex 32.

Generate each key with its command, then paste the output into .env. The file ends up with one line per setting:

AP_FRONTEND_URL=https://automation.example.com
AP_ENCRYPTION_KEY=paste the output of openssl rand -hex 16 here
AP_JWT_SECRET=paste the output of openssl rand -hex 32 here
AP_POSTGRES_PASSWORD=paste the output of openssl rand -hex 32 here

Store .env in a password manager. Without AP_ENCRYPTION_KEY, stored connections cannot be decrypted, even from a full database backup.

Two defaults in the Compose file also need attention before production. The image tag is pinned to a specific release, so you bump it yourself when you upgrade. The worker service is set to replicas: 5, which the Docker Compose install page describes as more than a single small machine wants. On a 2 vCPU and 4 GB server, lower that number, and use the Production Setup page to size the stack.

Back up the right things

Your flows, run history, and connections live in the postgres_data volume. Copying the activepieces folder alone does not back them up. The Activepieces docs give this dump command, which you run inside the database container:

docker compose -p activepieces exec postgres pg_dump -U postgres activepieces > backup.sql

Keep that dump together with .env, because the encryption key is needed to restore connections.

Troubleshooting: common install errors

The Activepieces install docs cover the common failures below, and the fixes follow the docs. Standard Compose commands are used where the docs only say to restart.

When something goes wrong, stream the logs:

docker compose -p activepieces logs -f app
docker compose -p activepieces logs -f worker

The Workers page is empty or shows Socket.IO errors

Symptom: The Workers list is empty, and the worker logs show repeated Socket.IO connection error messages.

Cause: The worker is pointed at an address that does not resolve to the app from inside its container. localhost refers to the worker itself.

Fix: Set the worker’s AP_FRONTEND_URL to http://app, as in Step 1, then recreate the worker:

docker compose -p activepieces up -d worker

Port 8080 is already in use

Symptom: The stack fails to start because host port 8080 is already taken.

Cause: Another service on the server is already listening on 8080.

Fix: On a fresh install, pass a different port to the installer, as in --port 8090. On an existing install, set AP_HOST_PORT in .env and restart. Do not change AP_PORT. That variable is the app’s internal listen port, and changing it breaks the port mapping.

AP_HOST_PORT=8090

docker compose -p activepieces up -d

The app container keeps restarting

Symptom: The app container restarts repeatedly and the web interface does not load.

Check the startup error first:

docker compose -p activepieces logs app | grep -i "failed to start"

Cause: The docs describe a common cause: the template’s AP_EXECUTION_MODE=UNSANDBOXED combined with AP_EDITION=ee. The server rejects that combination at startup.

Fix: Set the sandbox mode, then restart the stack:

AP_EDITION=ee
AP_EXECUTION_MODE=SANDBOX_CODE_ONLY

docker compose -p activepieces down && docker compose -p activepieces up -d

FAQ

Can I run Activepieces as a single Docker container?

The standalone Docker guide describes a single container with an embedded database, meant for personal use on one machine. It is not for production. It cannot scale, cannot move to Enterprise, and leaving it means starting over.

Where is my workflow data stored?

Flows, run history, and connections live in the postgres_data Docker volume that the Compose stack creates. The activepieces folder holds the .env file and Compose assets. Back up both, and keep AP_ENCRYPTION_KEY with them so connections can be restored.

Do I need Kubernetes to run Activepieces in production?

No. The installation overview lists Docker Compose with PostgreSQL and Redis as the recommended self-host option. It lists Kubernetes with a Helm chart only for teams that already run a cluster.

Next steps

Once your stack is healthy, the next step is moving workflows across. The Activepieces pricing page lists the cloud tiers if you want to compare against a hosted plan.

• Engine comparison: n8n vs Activepieces self-hosting compares the two platforms side by side.
• Zapier migration: migrating from Zapier to Activepieces.
• Make migration: migrating from Make to Activepieces.
• Alternative runner: self-hosting n8n on a VPS with Docker.

How this guide was built

This guide is based on Activepieces’ official install documentation and pricing page. We did not run the install on a live VPS for this article. Commands, file names, and environment variable names come from those pages, and the troubleshooting fixes come from the same docs.