Skip to main content

Installation

info

Before deploying your Load Balancer, ensure you have configured your .env and workers.json files and reviewed the Deployment recommendations. Proper security setup is essential before exposing your service to any network.

Dependencies​

  • Node.js 22.23.4+, 24.22.1+ or 26.12.1+ (Node 24 LTS recommended). The supplied Docker image uses Node 24.22.1 and runs as the non-root node user.
  • npm
  • Redis (the Docker Compose stack uses Redis 7.4.11)
  • Docker (optional, for containerized deployment)

Manual Installation​

  1. Clone the Load Balancer repository:

    git clone https://github.com/andera-top/load-balancer.git
    cd load-balancer
  2. Install dependencies:

    npm install
  3. Configure your .env by copying .env.example:

    cp .env.example .env

    Set LB_AUTH_KEY to a random value, for example generated with openssl rand -hex 32. Every Worker behind this Load Balancer must use the same LB_AUTH_KEY; the Load Balancer does not start without it. For Redis running locally outside Docker, set REDIS_HOST=localhost, and ensure Redis is running. Add Worker URLs to workers.json.

  4. Start the Load Balancer:

    npm run build
    node dist/app.js

Docker Installation​

  1. Clone the repository and navigate to the folder:

    git clone https://github.com/andera-top/load-balancer.git
    cd load-balancer
  2. Configure your .env by copying .env.example (cp .env.example .env) and set LB_AUTH_KEY as described above.

  3. Create a Docker network for Andera:

    docker network create andera-net
  4. Build and run the stack with Docker Compose:

    docker compose build
    docker compose up

    This will start both Redis and the Load Balancer, and mount your local workers.json file read-only into the container for live updates (hot-reload). The mount targets a single file: editors that save by replacing the file (atomic save) leave the container on the old version, so edit it in place or restart the Load Balancer. The port is published on 127.0.0.1 only, for a reverse proxy running on the same host.

    Inside the container, localhost refers to the Load Balancer container itself, not to your machine: see Docker network for the Worker URLs to use.

Do not use docker run directly. The recommended way is to use docker compose up to ensure all dependencies and configuration are handled correctly.

You are now ready to route and manage tasks with the Andera Load Balancer.