Installation Guide

Copy Markdown

This guide will help you get Heddle up and running.

⚡ One-line install

This is the easiest way to try Heddle on your own computer. It needs nothing else: Postgres and everything Heddle runs on come in the download.

On Linux and macOS (Apple Silicon):

curl -fsSL https://heddlehq.github.io/website/install.sh | sh

On Windows 10 or later, in PowerShell:

irm https://heddlehq.github.io/website/install.ps1 | iex

Heddle then starts and opens in your browser, where you create the admin account. To use it again later, open a new terminal and run heddle. Press Ctrl+C to stop it.

  • Where it lives: ~/.heddle, or %LOCALAPPDATA%\Heddle on Windows. If your Windows user folder has an accent in its name, it's %ProgramData%\Heddle instead, because Postgres and Python can't load from one. Your data is in the data folder inside it.
  • Folders with accents: on Linux and macOS, a home folder like /home/joão needs HEDDLE_HOME set to a folder without accents.
  • Updating: stop Heddle and run the install command again. Your data stays, and a copy goes to the backups folder first, keeping the latest three. If a new version needs a Postgres your data can't use, the installer stops without changing anything.
  • Removing: delete that folder and remove it from your PATH.
  • Network access: this install answers on your computer only. Flows can run code with your account's permissions, so run only the ones you trust.
  • Python: the first start downloads Python, which needs an internet connection.

This install is for one person on one computer. For a server, or to share Heddle with a team, use Docker below. Linux with musl, like Alpine, also needs Docker.

🛠 Prerequisites for running from source

Before you begin, ensure you have the following installed:

  • Elixir ~> 1.15
  • Erlang/OTP 26+
  • PostgreSQL
  • Node.js (for assets)

🏗 Installation (Source)

Follow these steps to run Heddle directly from the source code.

1. Clone the repository

git clone https://github.com/heddlehq/heddle.git
cd heddle

2. Install dependencies and setup

This command will install Elixir dependencies, install the UI JavaScript dependencies in apps/heddle_ui/assets including Rete.js, preferring npm and falling back to bun, create the database, and run migrations.

mix setup

3. Start UI and worker together

Open two terminals.

In the first terminal:

cd apps/heddle_ui
mix phx.server

In the second terminal:

cd apps/heddle_worker
mix run --no-halt

Now you can visit localhost:4000 from your browser.

This is the recommended local setup. The UI can render without the worker, but asynchronous executions and webhooks need the worker running.

4. Start only one service

If you need to isolate a process during development:

Start only the UI:

cd apps/heddle_ui
mix phx.server

Start only the worker:

cd apps/heddle_worker
mix run --no-halt

🐳 Installation (Docker)

Running with Docker is the fastest way to get started without worrying about local dependencies.

1. Start Heddle

git clone https://github.com/heddlehq/heddle.git
cd heddle
docker compose up -d --build

This starts the UI, a worker and Postgres. The first build takes a few minutes.

2. Create your admin account

Visit localhost:4000. The first visit asks you to create the admin account.

From another machine, use this computer's address, like http://192.168.1.50:4000.

3. Optional settings

Nothing else is required. To change a default, copy .env.example to .env and edit it:

  • HEDDLE_PORT is the port published on this machine, when 4000 is taken.
  • PHX_HOST is your public domain, only when Heddle sits behind HTTPS. Setting it turns on the redirect to HTTPS, so your proxy must send X-Forwarded-Proto.
  • SECRET_KEY_BASE is generated on the first boot and kept in the heddle_data volume.

To run everything in a single service:

docker compose --profile all up -d --build db all

4. Run without Compose

Build the image and point it at your own Postgres. all is the default mode. Pass ui or worker to start only one of them.

docker build -t heddle .

docker run --rm -p 4000:4000 \
  --env-file .env \
  -e DATABASE_URL=ecto://USER:PASS@HOST/heddle \
  heddle

Mount a volume on /app/data, or set SECRET_KEY_BASE, to keep people signed in across restarts.

5. Use the database from source

To run mix phx.server against the Compose database, publish it on this machine:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d db

6. Concurrency and pool tuning

The default Docker setup now separates the main scaling knobs:

  • UI_POOL_SIZE=10
  • WORKER_POOL_SIZE=10
  • OBAN_EXECUTIONS_CONCURRENCY=50
  • OBAN_DEFAULT_CONCURRENCY=2
  • OBAN_RESCUE_AFTER_MINUTES=60

Increase worker replicas carefully and tune these values together with your Postgres limits.

OBAN_RESCUE_AFTER_MINUTES is how long a run can go on before Heddle assumes its worker died and starts it again from the beginning. Keep it longer than your longest flow, or a flow that is still running gets started twice.

7. API-only UI mode

The UI release can run as an HTTP API gateway without the visual interface:

HEDDLE_UI_MODE=api

In this mode Heddle starts the API endpoint only:

  • /api/* routes stay available
  • webhook execution endpoints stay available
  • LiveView routes are disabled
  • static visual assets are not served
  • /live is not registered

Docker example:

docker run --rm -p 4000:4000 \
  --env-file .env \
  -e DATABASE_URL=ecto://USER:PASS@HOST/heddle \
  -e HEDDLE_UI_MODE=api \
  heddle ui

🧪 Verification

To ensure everything is working correctly, you can run the test suite:

mix test

For multi-instance deployment and worker scaling, see guides/scaling.md.