The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →The dependable way to self-host Activepieces on a virtual private server is its Docker Compose deployment with four services: the Activepieces app, a worker, PostgreSQL, and Redis. Plan for at least 2 vCPU and 4 GB of RAM, assign a DNS name, expose a public HTTPS URL for webhooks, and back up both the PostgreSQL database and the generated .env secrets file. The simpler single-container option is suitable only for a personal, one-machine installation.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
Choose the right Activepieces deployment mode
Activepieces offers two materially different self-hosting patterns. Selecting the wrong one affects persistence, queues, scaling, backups, and whether you can later adopt enterprise features.
As an Amazon Associate I earn from qualifying purchases.
| Characteristic | Single-container hobbyist mode | PostgreSQL/Redis Docker Compose mode |
|---|---|---|
| Database | PGLite embedded in the container | PostgreSQL in its own container, with data in the postgres_data Docker volume |
| Queue | In-memory queue | Redis-backed queue |
| Scale | One machine and one container; cannot scale out | Separate app and worker services, allowing a production-oriented multi-container layout |
| Upgrade path | Restart or replace the container | Documented Compose upgrade process, with an optional AP_VERSION pin |
| Webhook use | Best for a personal project on one machine | Designed for a public URL that external services can reach |
| Backup | Embedded application data must be handled with the container’s storage | Back up PostgreSQL separately, plus the secrets in .env |
| Enterprise migration | Not a migration path; moving to Enterprise requires starting over | Appropriate foundation if you may need enterprise features later |
Use the Compose stack for a VPS that must survive routine upgrades, run multiple workers, receive third-party webhooks, or preserve an enterprise option. Choose the single-container command only when the installation is deliberately personal, local to one machine, and non-scalable.
What the production stack contains
The recommended Compose project runs four containers:
- app: the Activepieces API and web interface, listening on port 8080 inside the stack.
- worker: executes flows pulled from the queue.
- postgres: stores flows, runs, and connections.
- redis: provides the job queue used by workers.
Application records are persisted in the Docker volume named postgres_data. The Compose directory contains configuration, not the database itself; copying the project directory alone does not produce a usable database backup.
VPS requirements before installation
Minimum host specification
- Linux VPS with at least 2 vCPU and 4 GB RAM, the documented minimum for Activepieces.
- Docker Engine and Docker Compose v2. Use the
docker composesubcommand; the olddocker-composecommand is not supported. - Persistent disk capacity for the PostgreSQL volume, flow history, and logs.
- A DNS record for the hostname you intend to publish.
- A way to terminate HTTPS for that hostname before production webhook use.
Do not treat 2 vCPU and 4 GB as a performance guarantee. It is the documented minimum. Heavy flows, large run histories, or several workers require additional CPU, memory, and disk capacity based on your workload.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsPrepare the hostname and URL
Decide the final public URL before creating connections or registering webhooks. You will place that HTTPS address in AP_FRONTEND_URL. External webhook senders use this value, and browsers use it to reach the platform. A tunnel such as ngrok is documented for testing, but a stable domain reachable by external services is the production choice.
Install the Compose deployment
Option 1: use the documented installer
On the VPS, run:
curl -fsSL https://get.activepieces.com | shThe installer creates the deployment in its default location, generates the required configuration, and prepares the Compose project. If port 8080 is already occupied, supply another port:
curl -fsSL https://get.activepieces.com | sh -s -- --port <port>To select a particular installation directory, add the directory option:
curl -fsSL https://get.activepieces.com | sh -s -- --dir <path>Use a directory on persistent storage. Record its location because you will return there for configuration, backups, and upgrades.
Option 2: review the generated files manually
For a setup you want to inspect before starting, obtain the Activepieces source tree from its official distribution, enter that directory, and run:
sh tools/deploy.shThis process copies .env.example to .env and generates secrets. Before starting containers, confirm that these values are present and non-empty:
AP_ENCRYPTION_KEYAP_JWT_SECRETAP_POSTGRES_PASSWORD
Keep the resulting .env file private. It contains credentials and cryptographic material, not merely harmless settings. Activepieces documents that without AP_ENCRYPTION_KEY, stored connections cannot be decrypted, even from a complete database backup. Losing that key can therefore make a restored database unusable for its saved connections.
Configure the public URL and worker networking
Set AP_FRONTEND_URL for browsers and webhooks
Edit .env and set AP_FRONTEND_URL to the exact public HTTPS address users and third-party webhook providers will call. Use the real hostname rather than a private container name or a temporary loopback address.
AP_FRONTEND_URL=https://automation.example.comThe hostname must resolve to the VPS and remain reachable from the services that send webhooks. If the URL is wrong, the interface may load while generated webhook URLs point to an unusable address.
Give the worker the internal app address
Inside the worker service, override the variable so that the worker talks to the Compose service named app:
AP_FRONTEND_URL=http://appDo not set the worker’s internal value to localhost. In a container, localhost refers to that worker container itself, not the app container. The documented symptom is an empty Workers page or workers that fail to register. Keep the public value for the browser-facing app and the internal value for worker-to-app communication; they serve different network contexts.
Start Activepieces and create the administrator
From the installation directory, start the project in detached mode:
Free tools Windows power users keep installed
One-click scans. No signup required.
docker compose -p activepieces up -dThe project name activepieces makes subsequent status, log, backup, and upgrade commands address the same Compose project.
Open http://<server-ip>:<port> during initial testing, or use the configured hostname once DNS and HTTPS are ready. The first account you create becomes the platform administrator. There is no preset username or password, so protect that first registration and use a dedicated administrative address.
Verify every service before building flows
Check container status
docker compose -p activepieces psThe app, worker, postgres, and redis containers should all show Up. A running app with a stopped worker is not a healthy automation platform: the interface may open, but flows will not execute correctly.
Check the health endpoint
curl http://localhost:8080/api/v1/healthThe endpoint should respond successfully on the host port used by the app. If you selected a different published port, use that port in the request.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Investigate a missing worker
If the Workers page is empty or the worker is not registering, inspect socket-related messages and then verify the worker’s internal URL:
docker compose -p activepieces logs worker | grep -i socketConfirm that the worker override is AP_FRONTEND_URL=http://app, not localhost and not the public hostname.
Investigate an app startup failure
docker compose -p activepieces logs app | grep -i "failed to start"Review the complete app log if the filtered command returns no useful line. Common configuration checks include the presence of all three generated secrets, a valid PostgreSQL password, and a free host port.
Back up the installation correctly
A recoverable backup has two parts: the secrets file and a database dump. The database volume contains flows, runs, and connections; the .env file contains the key needed to decrypt those connections. Backing up only the Compose directory omits the database volume.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Protect the secrets file
Store a secured copy of .env outside the VPS. Limit access to the administrators who need to restore the service. Never publish it in a repository or paste it into an issue.
Dump PostgreSQL
Run the documented dump command from the Compose project:
docker compose -p activepieces exec postgres pg_dump -U postgres activepieces > backup.sqlMove the resulting SQL file to storage separate from the VPS. A dump on the same disk does not protect against disk loss or a deleted server. Test that your backup process preserves both backup.sql and the matching encryption key; a database file without the original key cannot decrypt stored connections.
Upgrade without losing configuration
Back up first
Take a fresh PostgreSQL dump and copy the current .env before changing versions. Record the current release if you have pinned one with AP_VERSION.
Run the installer upgrade
curl -fsSL https://get.activepieces.com | sh -s -- --upgradeThe documented upgrade keeps the existing .env, data, and Compose edits in place. It does not remove the need for a backup or for reviewing release notes: breaking changes can require configuration or migration work before you move versions.
Pin a known release when required
Set AP_VERSION in the environment when you need a controlled release rather than whatever the installer currently selects. Pinning helps coordinate testing and rollback planning; it does not replace database backups.
Enterprise edition and execution settings
The default installation runs on the free plan. If you are enabling enterprise features with the manual deployment, the documented settings include:
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11AP_EDITION=ee
AP_EXECUTION_MODE=SANDBOX_CODE_ONLYDo not copy an example value of UNSANDBOXED into this configuration; the documentation warns that it is rejected at startup for that setup. The core is MIT licensed, while packages/ee uses a separate enterprise license and requires an Activepieces license for enterprise features.
This is another reason to choose PostgreSQL and Redis for a serious VPS. The hobbyist PGLite/in-memory deployment cannot be migrated to Enterprise without starting over.
Operational security and reliability checklist
- Use a dedicated DNS hostname and publish the HTTPS URL in
AP_FRONTEND_URL. - Keep
.envprivate, especiallyAP_ENCRYPTION_KEY,AP_JWT_SECRET, andAP_POSTGRES_PASSWORD. - Use Docker Compose v2 commands exclusively.
- Keep PostgreSQL data on persistent disk and monitor available capacity.
- Back up both PostgreSQL and the secrets file before upgrades or VPS changes.
- Check all four containers after reboots, upgrades, and configuration edits.
- Use the worker’s internal
http://appaddress; reserve the public URL for browser and webhook traffic. - Review breaking changes before changing
AP_VERSIONor adopting a newer release.
Scaling decisions as usage grows
The documented minimum host is a starting point, not a fixed capacity target. The Compose architecture separates the API/UI from flow execution, while Redis separates queued work from the request path and PostgreSQL keeps durable state. If executions become frequent or concurrent, the first practical questions are whether the VPS has enough CPU and RAM, whether the PostgreSQL volume has sufficient space for run history, and whether additional workers are appropriate. Those changes should be made within the Compose architecture rather than by converting a production instance to the hobbyist container.
Keep the deployment mode aligned with the migration you expect. A one-machine personal project can remain on PGLite and an in-memory queue, but a public webhook service, a multi-worker installation, or a future enterprise deployment belongs on PostgreSQL and Redis from the beginning.
Recommended Free Tools
Troubleshooting by symptom
The installer cannot bind its port
Choose an unused port with the installer’s --port <port> option, then use that same port when opening the service and checking its health endpoint.
The page opens but webhook URLs are wrong
Replace a private, IP-only, or temporary value of AP_FRONTEND_URL with the public HTTPS hostname that external services can resolve and reach. Restart the Compose project after changing the environment.
The Workers page is empty
Check worker logs for socket messages and inspect the worker environment. Its internal URL must be http://app; localhost loops back to the worker container.
The app fails immediately after startup
Inspect the app logs for the startup failure message, then verify that generated secrets are non-empty, the PostgreSQL password matches, and the selected host port is available. For enterprise configuration, check that the execution mode is SANDBOX_CODE_ONLY rather than the rejected UNSANDBOXED example.
A restore brings back flows but connections do not work
Restore the matching .env file along with the SQL dump, including the original AP_ENCRYPTION_KEY. A database backup without that key cannot decrypt stored connections.
Recommended deployment sequence
- Provision a Linux VPS with at least 2 vCPU, 4 GB RAM, persistent disk, Docker Engine, and Docker Compose v2.
- Create DNS for the intended hostname and decide the public HTTPS URL.
- Run the installer, using
--portor--dironly when needed. - Inspect
.env; confirm the encryption, JWT, and PostgreSQL secrets are present, then secure a backup copy. - Set the public
AP_FRONTEND_URLand the worker’s internalhttp://appoverride. - Start with
docker compose -p activepieces up -d. - Register the first account, which becomes the platform administrator.
- Verify container status and the
/api/v1/healthendpoint. - Test a webhook from an external service only after the public URL resolves correctly.
- Schedule PostgreSQL dumps and secrets backups before production workloads.
For a reliable VPS installation, the four-container PostgreSQL/Redis Compose stack is the appropriate default: it preserves durable state, provides a real queue, supports worker separation, and leaves a documented upgrade path. The single-container mode is intentionally limited to personal, one-machine use.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
