How to install Activepieces with Docker Compose and HTTPS

Activepieces is an open-source automation platform. You build flows from triggers and steps called pieces, which connect to business apps and AI services, add branches, loops and code steps, and expose flows as tools to AI agents. Its builder targets business users as well as developers, and self-hosting keeps connections and run data on your own server.

This guide follows the Docker Compose method from Activepieces' documentation: you clone the official repository, generate secrets with the bundled tools/deploy.sh script, and run the app, a worker, PostgreSQL and Redis with Docker Compose. The app listens only on 127.0.0.1, and Caddy serves it over HTTPS on your domain. You then create the platform admin account and set up backups and updates. A short section explains the official one-command installer as an alternative.

Step 1 — Clone the official repository

The repository contains the .env.example template and the secret generator. Clone it into /opt/activepieces; a shallow clone is enough:

sudo apt update
sudo apt install git openssl
sudo mkdir -p /opt/activepieces
sudo chown $USER:$USER /opt/activepieces
git clone --depth 1 https://github.com/activepieces/activepieces.git /opt/activepieces
cd /opt/activepieces

Step 2 — Generate secrets with the official script

tools/deploy.sh copies .env.example to .env and fills in random values with openssl: AP_API_KEY, AP_POSTGRES_PASSWORD, AP_JWT_SECRET (signs login tokens) and AP_ENCRYPTION_KEY (32 hex characters that encrypt your saved connections). Run it once and check that the important values are not empty:

sh tools/deploy.sh
grep -E '^(AP_ENCRYPTION_KEY|AP_JWT_SECRET|AP_POSTGRES_PASSWORD)=' .env
chmod 600 .env

All three lines must show a long value. Activepieces' documentation warns that the script can report success with blank values when openssl is missing.

Step 3 — Configure the core settings

Three settings in .env need your attention:

• AP_FRONTEND_URL is the public address used for redirects, OAuth callbacks and webhook URLs. External services must be able to reach it.
• AP_EDITION=ee is the value that Activepieces' Docker Compose documentation and its installer set. Add it as shown below.
• AP_EXECUTION_MODE controls how code steps are isolated. With AP_EDITION=ee the server refuses to start with the default UNSANDBOXED, so set SANDBOX_CODE_ONLY: each code step then runs in a fresh V8 isolate with 128 MB of memory and no file system access, which Activepieces recommends when users are not fully trusted. Code steps cannot use npm packages in this mode.

The Compose file in the next step also reads AP_VERSION, the image tag to run. 0.92.2 was the latest release on 2026-10-09; use the current tag from the Activepieces releases page on GitHub:

cd /opt/activepieces
sed -i 's|^AP_FRONTEND_URL=.*|AP_FRONTEND_URL=https://automation.example.com|' .env
sed -i 's|^AP_EXECUTION_MODE=.*|AP_EXECUTION_MODE=SANDBOX_CODE_ONLY|' .env
cat >> .env <<'EOF'
AP_EDITION=ee
AP_VERSION=0.92.2
EOF
grep -E '^AP_(FRONTEND_URL|EXECUTION_MODE|EDITION|VERSION)=' .env

The last command should print the four values you just set.

Step 4 — Adapt the Compose file

The repository's docker-compose.yml publishes port 8080 on every address, gives the database and Redis fixed container names and starts five workers. Keep a copy of the original and replace it with the version below. It matches the template that Activepieces' own installer writes, with two changes: the port is published on 127.0.0.1 only, and the image tag comes from AP_VERSION:

cp docker-compose.yml docker-compose.yml.orig
nano docker-compose.yml

services:
  app:
    image: ghcr.io/activepieces/activepieces:${AP_VERSION}
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    depends_on:
      - postgres
      - redis
    env_file: .env
    environment:
      - AP_CONTAINER_TYPE=APP
    volumes:
      - ./cache:/usr/src/app/cache
    networks:
      - activepieces
  worker:
    image: ghcr.io/activepieces/activepieces:${AP_VERSION}
    restart: unless-stopped
    depends_on:
      - app
    env_file: .env
    environment:
      - AP_CONTAINER_TYPE=WORKER
      - AP_FRONTEND_URL=http://app
    volumes:
      - ./cache:/usr/src/app/cache
    networks:
      - activepieces
  postgres:
    image: pgvector/pgvector:0.8.0-pg14
    restart: unless-stopped
    env_file: .env
    environment:
      - POSTGRES_DB=${AP_POSTGRES_DATABASE}
      - POSTGRES_PASSWORD=${AP_POSTGRES_PASSWORD}
      - POSTGRES_USER=${AP_POSTGRES_USERNAME}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - activepieces
  redis:
    image: redis:7.0.7
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - activepieces
volumes:
  postgres_data:
  redis_data:
networks:
  activepieces:

The worker's own AP_FRONTEND_URL=http://app overrides the public URL from .env: workers talk to the app over the internal network, and localhost inside the worker container would point at the worker itself. Check the file for syntax errors:

docker compose config --quiet && echo "compose file OK"

Step 5 — Start Activepieces

Pull the images and start the stack. The first start takes a minute or two while the app creates its database tables:

docker compose pull
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:8080/api/v1/health

All four services should be running, and the health endpoint answers with a short JSON status once the app is ready. If it does not, follow the app log with docker compose logs -f app.

Step 6 — Publish Activepieces over HTTPS with Caddy

Add a site block for the subdomain to /etc/caddy/Caddyfile:

automation.example.com {
    reverse_proxy 127.0.0.1:8080
}

Reload Caddy, allow only SSH and web traffic, and test the public address:

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
curl -I https://automation.example.com

You should get an HTTP 200 response with a valid certificate. Port 8080 stays closed to the internet because Docker publishes it on the loopback address only. For Nginx or Traefik instead of Caddy, see Nginx with Certbot and Traefik.

Step 7 — Create the platform admin account

Open https://automation.example.com straight away and sign up. On a fresh instance the first account becomes the platform administrator. After that, new people join through invitations from the admin console; open sign-up only happens if you set AP_ALLOW_OPEN_SIGN_UP=true, which you should not do on a public server.

Then open Platform Admin → Operations → Workers and check that at least one worker is listed. Configure outgoing email in the admin console so that invitations and the emailed six-digit sign-in codes work. Alternatively, set AP_SMTP_HOST (for example smtp.example.com), AP_SMTP_PORT (587), AP_SMTP_USERNAME, AP_SMTP_PASSWORD, AP_SMTP_SENDER_EMAIL and AP_SMTP_SENDER_NAME in .env; Activepieces only uses these variables when the admin screen has no email configuration and host, port, username and password are all set. Users with a password can always sign in through the Use password link.

To run more flows in parallel, add workers with docker compose up -d --scale worker=2. Activepieces' production guidance favours several workers with AP_WORKER_CONCURRENCY=1 over one worker with many parallel jobs, because an out-of-memory error then affects only one run.

Alternative: the one-command installer

Activepieces also offers an official installer at get.activepieces.com. It checks for Docker Compose v2, creates an activepieces folder with a docker-compose.yml and a .env full of generated secrets (AP_EDITION=ee, SANDBOX_CODE_ONLY), pulls the latest release and starts the stack. It never overwrites an existing .env, and the same script handles --upgrade and --uninstall. Download it and read it before running it:

curl -fsSL https://get.activepieces.com -o install-activepieces.sh
less install-activepieces.sh
sh install-activepieces.sh --dir /opt/activepieces

The official one-line form pipes the same script into sh. Note that the installer publishes the app on port 8080 on all addresses and sets AP_FRONTEND_URL to http://localhost:8080; Docker bypasses ufw, so the port is reachable from the internet until you change it. Create the admin account immediately, then set AP_HOST_PORT=127.0.0.1:8080 and your HTTPS AP_FRONTEND_URL in the generated .env and apply them with docker compose up -d in that folder.

Back up and restore

Activepieces keeps flows, runs, connections and users in PostgreSQL, in the postgres_data volume, not in the project folder. The second essential item is .env with the encryption key. Redis only holds the job queue, and the cache folder is rebuilt automatically. Back up the database and the configuration:

sudo mkdir -p /opt/backups
sudo chown $USER:$USER /opt/backups
cd /opt/activepieces
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' > /opt/backups/activepieces-db-$(date +%F).dump
tar czf /opt/backups/activepieces-config-$(date +%F).tar.gz -C /opt/activepieces .env docker-compose.yml
chmod 600 /opt/backups/activepieces-*

To restore, on the same server or on a new one, put .env and docker-compose.yml from the archive into /opt/activepieces, start PostgreSQL alone, load the dump and start the rest:

cd /opt/activepieces
docker compose stop app worker
docker compose up -d postgres
until docker compose exec postgres pg_isready -U postgres; do sleep 2; done
docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' < /opt/backups/activepieces-db-2026-10-09.dump
docker compose up -d

Replace the date with the one in your file name. Copy /opt/backups to another machine or object storage regularly; backups that stay on the same server are lost with it.

Update Activepieces

Activepieces releases often. Before each update, read the breaking-changes page in its documentation, which lists changes that affect self-hosted instances and individual pieces, and back up the database and .env. Then set AP_VERSION in .env to the new release and recreate the containers:

cd /opt/activepieces
nano .env
docker compose pull
docker compose up -d
docker compose logs --tail=50 app

Database migrations run when the app starts. Keep the PostgreSQL and Redis image tags as they are during routine updates; a PostgreSQL major upgrade needs a dump and restore. If you used the one-command installer, run it again with --upgrade instead, which updates AP_VERSION and keeps your .env and data.

Troubleshooting

Webhook and redirect URLs point to localhost:8080

AP_FRONTEND_URL in .env still has its default value. Set it to https://automation.example.com and run docker compose up -d --force-recreate app. Webhook URLs copied into external services before the change must be updated there.

Flows stay queued and no worker is listed

The worker cannot reach the app. Make sure the worker service sets AP_FRONTEND_URL=http://app and that both containers share the activepieces network, then read docker compose logs worker. Platform Admin → Operations → Workers must list at least one worker.

The app stops right after start with AP_EDITION=ee

With AP_EDITION=ee, the server rejects AP_EXECUTION_MODE=UNSANDBOXED at startup. Set AP_EXECUTION_MODE=SANDBOX_CODE_ONLY in .env and run docker compose up -d. The modes SANDBOX_PROCESS and SANDBOX_CODE_AND_PROCESS would need privileged containers and are not used in this guide.

Connections fail after a restore

The AP_ENCRYPTION_KEY in the current .env is not the one that encrypted the data. Put the original .env back and recreate the containers. Without the original key, saved connections cannot be recovered and must be reconnected.

A code step cannot import an npm package

SANDBOX_CODE_ONLY runs code in a V8 isolate without require or npm. Move the logic into a piece or call an external API instead.

Port 8080 is already in use

Another service uses port 8080 on the loopback address. Change the host side of the mapping, for example "127.0.0.1:8081:80", update the Caddy site block to match and run docker compose up -d. Do not change AP_PORT, which is the app's internal listen port.

Next steps

• Compare Activepieces with n8n and Node-RED.
• Learn more about Compose files in Docker Compose basics.
• Find servers sized for automation workloads on the Activepieces hosting page.
• Read the Activepieces self-hosting documentation for environment variables, sandboxing and scaling.