Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallFor a dependable VPS deployment, run Activepieces as a Docker Compose stack with four services: the app, worker, PostgreSQL, and Redis. Use at least 2 vCPU and 4 GB of RAM, give the installation a persistent disk and DNS name, set a public HTTPS URL for webhooks, and back up both the PostgreSQL database and the generated .env file. The single-container PGLite mode is suitable only for a personal, one-machine experiment.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What a VPS installation should look like
Self-hosting Activepieces means that your own virtual private server runs the application and stores its data instead of sending execution data to a hosted instance. The production-oriented layout is a Docker Compose project containing four containers. Keeping these roles separate gives you durable storage, a real job queue, and an upgrade path that can support more than one worker later.
As an Amazon Associate I earn from qualifying purchases.
| Container | Role | Important detail |
|---|---|---|
app |
API and web interface | Listens on port 8080 inside the stack unless you map another host port. |
worker |
Executes flows | Must reach the app through the internal service address, not its own localhost. |
postgres |
Stores flows, runs and connections | Data is held in the persistent postgres_data Docker volume. |
redis |
Job queue | Provides the queue required by the multi-container deployment. |
The project directory contains Compose files and configuration, but it is not the database. Copying that directory without the postgres_data volume does not produce a usable database backup. Treat the database dump and the secrets file as separate backup assets.
Choose the deployment mode before you install
Activepieces also offers a one-container command intended for a hobbyist setup. It uses embedded PGLite for persistence and an in-memory queue. That simplicity is useful for trying the product on one machine, but it is deliberately constrained and should not be confused with the VPS production layout.
| Decision point | Single-container hobbyist mode | PostgreSQL/Redis Compose stack |
|---|---|---|
| Persistence | Embedded PGLite | PostgreSQL in the postgres_data volume |
| Queue | In memory | Redis |
| Scale | One machine and one container | Separate app and worker containers, with room for additional workers |
| Upgrade path | Restart or replace the container | Documented Compose installer upgrade, with optional version pinning |
| Webhook use | Limited to what the single machine can expose | Designed for a stable public URL reachable by outside services |
| Backups | Embedded database handling | Database dump plus the secrets file; the volume must be accounted for |
| Enterprise migration | Not a migration path; moving later requires starting over | Supports the documented enterprise configuration when properly licensed |
Choose the four-container stack if you expect production traffic, need reliable queued execution, may add workers, or might use enterprise features. Choose the hobbyist command only when a personal, single-machine installation and its limitations are acceptable.
VPS requirements
The documented minimum host size is 2 vCPU and 4 GB of RAM. That is a minimum, not a capacity promise for a particular number of flows or concurrent runs. Provision additional CPU, memory and disk when your workloads, retained run history or number of workers require it.
- A Linux VPS with at least 2 vCPU and 4 GB RAM.
- Docker Engine installed and running.
- Docker Compose v2. The old
docker-composecommand is not supported by the documented deployment. - Persistent disk space for PostgreSQL data, logs and backups.
- A DNS name for the public hostname that external webhook senders will call.
- Network access to the host port you choose for the app, plus HTTPS termination for the public URL.
Before installing, decide the final hostname and whether port 8080 is available. If it is already occupied, the installer can publish Activepieces on another host port.
Install the Compose stack
Use the recommended installer
On the VPS, run the documented installer as a shell pipeline:
curl -fsSL https://get.activepieces.com | shUse the installer options when the defaults do not fit your host:
curl -fsSL https://get.activepieces.com | sh -s -- --port <port> --dir <path>--port changes the host port when 8080 is occupied. --dir chooses where the Compose project and its environment file are placed. Record that directory; you will return to it for backups, upgrades and troubleshooting.
Use the manual deployment script when you need to review files
A manual installation is useful when you want to inspect the generated Compose project before starting it. Clone the Activepieces repository, then run:
sh tools/deploy.shThe script copies .env.example and generates secrets. Open the resulting .env and confirm that AP_ENCRYPTION_KEY, AP_JWT_SECRET and AP_POSTGRES_PASSWORD are all present and non-empty. Do not commit this file to a repository or make it downloadable from the web.
Start the services
From the installation directory, start the named Compose project in detached mode:
docker compose -p activepieces up -dThe command must be the Compose v2 form, with a space between docker and compose. After startup, open http://<server-ip>:<port> or the configured hostname. The first account you create becomes the platform administrator. There is no default username or password to retrieve.
Free tools Windows power users keep installed
One-click scans. No signup required.
Protect and configure the environment file
The generated environment file is part of the application’s recoverability. Keep a protected copy alongside your backup procedure, but restrict access because it contains credentials and encryption material.
Why the encryption key is essential
AP_ENCRYPTION_KEY is not an ordinary setting that can be regenerated after a disaster. Activepieces documentation states: “Without AP_ENCRYPTION_KEY, stored connections cannot be decrypted, even from a full database backup.” A database dump without the matching key can therefore leave saved service connections unusable. Back up the exact value and restore it with the database.
Configure the public URL
Set AP_FRONTEND_URL to the public HTTPS URL that users open in their browsers and that third-party webhook senders can reach. This value should be the final DNS name, not a private container address and not a temporary loopback address.
Give the worker an internal app URL
In the worker service, override the variable so that it uses:
Recommended Free Tools
AP_FRONTEND_URL=http://appInside a container, localhost refers to that same container. If the worker uses localhost, it can call itself instead of the app and the Workers page may remain empty. The browser-facing setting stays the public HTTPS URL; only the worker’s internal override uses http://app.
Free and enterprise settings
A normal installation runs on the free plan by default. If you are deploying licensed enterprise features, the manual instructions use:
AP_EDITION=ee
AP_EXECUTION_MODE=SANDBOX_CODE_ONLYDo not substitute the example UNSANDBOXED value for this configuration; the documentation warns that it is rejected at startup in that setup. The Docker image documentation describes the core as MIT licensed, while packages/ee uses a separate enterprise license and requires an Activepieces license for enterprise features.
Put Activepieces behind a real public URL
Webhooks are requests sent by systems outside your VPS. A private IP, an address reachable only on your LAN, or a URL that points at a container name will not work for those senders. Point DNS for your chosen hostname at the VPS, terminate HTTPS there, and use that HTTPS address for AP_FRONTEND_URL.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteA tunnel such as ngrok is documented for testing a webhook from an otherwise private development machine. It is not the recommended production arrangement. For production, use a stable domain that external services can resolve and reach. If you change the hostname later, update the environment value and restart the stack so generated webhook URLs and browser links use the new address.
Keep the internal and external paths distinct: users and webhook providers use the public URL, while the worker talks to http://app over the Compose network. This separation avoids the common failure where the UI is reachable but workers cannot register.
Verify the installation
Run the status check from the project directory:
docker compose -p activepieces psAll four services—app, worker, postgres and redis—should show Up. Check the application health endpoint from the VPS:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →curl http://localhost:8080/api/v1/healthA response from the health endpoint confirms that the app is answering on its internal port. If you published a different host port, use that mapped port when testing from outside; the container’s application port remains 8080 in the documented stack.
Test the user-facing path
- Open the configured HTTPS hostname in a browser.
- Create the first account; it becomes the platform administrator.
- Sign in and confirm that the interface loads without a connection error.
- Create a small test flow and run it manually.
- Send a test webhook from an external system or a controlled tunnel and confirm that the run appears in Activepieces.
Inspect logs when a check fails
If the Workers page is empty, inspect worker logs and search for socket-related errors:
docker compose -p activepieces logs worker | grep -i socketThen check that the worker’s internal AP_FRONTEND_URL is http://app, not localhost. For an application startup failure, run:
docker compose -p activepieces logs app | grep -i "failed to start"Also check that the three generated secrets are non-empty, that PostgreSQL and Redis are running, and that the host has not run out of memory or disk.
Back up the database and secrets
Backups must cover both database contents and the keys needed to interpret them. Save a protected copy of .env, then create a PostgreSQL dump before an upgrade or any risky configuration change:
docker compose -p activepieces exec postgres pg_dump -U postgres activepieces > backup.sqlStore backup.sql and the matching secrets file together in a protected location. A copy of the Compose project alone omits the postgres_data volume, so it does not contain flows, runs or connections. Test that your backup process can retrieve both files and that the key has not been rotated or overwritten.
The dump shown above is plain SQL redirected to a file on the VPS. Protect it as sensitive data: it contains application records and may include connection details. Keep more than one generation of backups so that a bad upgrade or accidental deletion is not your only restore point.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Upgrade without losing configuration
Back up the environment file and database first. Then run the documented installer upgrade from the installation directory:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →curl -fsSL https://get.activepieces.com | sh -s -- --upgradeThe installer leaves the existing .env, data and Compose edits in place. You can pin a release with AP_VERSION when you need a controlled rollout instead of immediately following the newest image. Read the release’s breaking changes before moving versions, especially when you use enterprise settings or custom Compose edits.
- Confirm that
docker compose -p activepieces psshows the expected project and record the current version. - Export the PostgreSQL database with
pg_dump. - Copy the complete
.env, includingAP_ENCRYPTION_KEY, to your protected backup location. - Review breaking changes and set
AP_VERSIONif you want to pin the target release. - Run the installer with
--upgrade. - Repeat the container status check, health request and a test flow.
If the new release does not start, inspect the app logs for “failed to start,” verify that the environment values were retained, and use the database and secrets backups as your recovery assets rather than deleting the persistent volume.
Scaling and operating the worker
The Compose architecture separates the API/UI from flow execution. That separation is the reason to choose it for a VPS that may need production reliability or multiple workers. The single-container hobbyist mode has neither the Redis queue nor the multi-container worker boundary, and it cannot be migrated to enterprise later without starting over.
Start with the documented four services and watch resource usage as flows become more frequent or complex. Adding capacity should preserve the same PostgreSQL database, Redis queue and encryption key. Do not create a second isolated installation merely to gain execution capacity unless you have a deliberate data and routing plan.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Common failure modes and fixes
| Symptom | Likely cause | Action |
|---|---|---|
The old docker-compose command fails |
Compose v1 is installed or being invoked | Install Docker Compose v2 and use docker compose with a space. |
| Workers page is empty | Worker is using localhost for the app URL |
Set the worker override to AP_FRONTEND_URL=http://app, then restart and inspect worker socket logs. |
| External webhook never arrives | The configured URL is private, HTTP-only, temporary or not DNS-resolvable | Use a stable public HTTPS hostname in AP_FRONTEND_URL; reserve a tunnel for testing. |
| App exits during startup | Missing secrets, invalid enterprise execution mode, or a dependent service that is down | Check the three secret variables, use SANDBOX_CODE_ONLY for the documented enterprise setup, and inspect app and dependency status. |
| Restored database cannot decrypt connections | The matching encryption key was not restored | Restore the original AP_ENCRYPTION_KEY from the protected environment backup. |
| Flows disappear after moving servers | Only the project directory was copied; the PostgreSQL volume was not backed up | Restore from the PostgreSQL dump and the matching secrets file; do not rely on a directory copy alone. |
| Upgrade changes behavior unexpectedly | A breaking change was applied without review | Read the release notes, pin AP_VERSION for controlled deployment, and keep the pre-upgrade dump. |
Production readiness checklist
- Host meets the documented minimum of 2 vCPU and 4 GB RAM, with persistent disk capacity.
- Docker Engine and Docker Compose v2 are installed; commands use
docker compose. - The four expected services are running: app, worker, PostgreSQL and Redis.
AP_ENCRYPTION_KEY,AP_JWT_SECRETandAP_POSTGRES_PASSWORDare non-empty and stored securely.- The first administrator account has been created and its credentials are managed securely.
AP_FRONTEND_URLis the public HTTPS hostname, while the worker override ishttp://app.- A real DNS name is used for production webhooks; a tunnel is limited to testing.
- Database dumps and the matching
.envfile are backed up together. - Upgrade procedures include a pre-upgrade dump, breaking-change review and a tested health check.
- Enterprise settings are used only with the required license and the documented execution mode.
Which setup should you use?
For a VPS that matters to your workflows, install the PostgreSQL/Redis Docker Compose stack. It meets the documented production shape, keeps execution in a worker service, supports a real queue, and gives you a defined backup and upgrade procedure. The one-container PGLite option is appropriate only when you intentionally accept one-machine operation, an in-memory queue, limited scaling and no later enterprise migration path.
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.
