> ## Documentation Index
> Fetch the complete documentation index at: https://bobprince-78964c2b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosting

> Run Hookdrop on your own infrastructure

You can run Hookdrop on your own servers. Self-hosting gives you full control over your data and infrastructure.

<Note>
  Self-hosting requires familiarity with Node.js, PostgreSQL, and Redis. If you want to get started quickly, the cloud-hosted version at [hookdrop.dev](https://hookdrop.dev) requires no setup.
</Note>

## Requirements

* Node.js v20+
* PostgreSQL 16+
* Redis 7+

## Setup

<Steps>
  <Step title="Clone the repository">
    Clone the repo and install dependencies:

    ```bash theme={null}
    git clone https://github.com/bobprince4u/hookdrop.git && cd hookdrop && npm install
    ```
  </Step>

  <Step title="Configure environment variables">
    Copy the example environment file:

    ```bash theme={null}
    cp .env.example .env
    ```

    Open `.env` and fill in your values. See `.env.example` in the repository for the full list of required variables. Key settings include:

    ```env theme={null}
    DATABASE_URL=postgresql://postgres:password@localhost:5432/hookdrop
    REDIS_URL=redis://localhost:6379
    JWT_SECRET=your-long-random-secret
    ```
  </Step>

  <Step title="Run database migrations">
    Apply the database schema:

    ```bash theme={null}
    npm run migrate:up
    ```
  </Step>

  <Step title="Start all services">
    Open four terminal windows and run one command in each:

    ```bash theme={null}
    # Terminal 1 — Ingestion API
    npm run dev:ingestion
    ```

    ```bash theme={null}
    # Terminal 2 — Delivery Worker
    npm run dev:worker
    ```

    ```bash theme={null}
    # Terminal 3 — Dashboard API
    npm run dev:api
    ```

    ```bash theme={null}
    # Terminal 4 — Frontend
    npm run dev:web
    ```
  </Step>
</Steps>

## Architecture overview

Hookdrop is composed of four services that run independently:

* **Ingestion API (port 3002)** — Receives incoming webhooks from providers like Stripe, GitHub, and Shopify. This is the URL you configure in your webhook provider settings.
* **Delivery Worker** — Picks up queued jobs from Redis and forwards events to your configured destinations. Handles retries with exponential backoff.
* **Dashboard API (port 3003)** — Powers the web dashboard. Handles authentication, endpoint management, event queries, and billing.
* **Frontend (port 3004)** — The web UI. Connects to the Dashboard API and streams live events via WebSocket.

<Tip>
  The Ingestion API and Dashboard API are intentionally separate. Under heavy webhook load, you can scale the Ingestion API independently without affecting the dashboard.
</Tip>

<Note>
  Docker Compose support is coming soon. A single `docker-compose.yml` for one-command self-hosting is on the roadmap.
</Note>