Installation
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
nodeuser. - npm
- Redis (the Docker Compose stack uses Redis 7.4.11)
- Docker (optional, for containerized deployment)
Manual Installation
-
Clone the Load Balancer repository:
git clone https://github.com/andera-top/load-balancer.gitcd load-balancer -
Install dependencies:
npm install -
Configure your
.envby copying.env.example:cp .env.example .envSet
LB_AUTH_KEYto a random value, for example generated withopenssl rand -hex 32. Every Worker behind this Load Balancer must use the sameLB_AUTH_KEY; the Load Balancer does not start without it. For Redis running locally outside Docker, setREDIS_HOST=localhost, and ensure Redis is running. Add Worker URLs toworkers.json. -
Start the Load Balancer:
npm run buildnode dist/app.js
Docker Installation
-
Clone the repository and navigate to the folder:
git clone https://github.com/andera-top/load-balancer.gitcd load-balancer -
Configure your
.envby copying.env.example(cp .env.example .env) and setLB_AUTH_KEYas described above. -
Create a Docker network for Andera:
docker network create andera-net -
Build and run the stack with Docker Compose:
docker compose builddocker compose upThis will start both Redis and the Load Balancer, and mount your local
workers.jsonfile 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 on127.0.0.1only, for a reverse proxy running on the same host.Inside the container,
localhostrefers to the Load Balancer container itself, not to your machine: see Docker network for the Worker URLs to use.
Do not use
docker rundirectly. The recommended way is to usedocker compose upto ensure all dependencies and configuration are handled correctly.
You are now ready to route and manage tasks with the Andera Load Balancer.