Deployment
This page covers best practices and recommendations for deploying your Load Balancer in production environments.
Reverse Proxy & HTTPS
Never expose your Load Balancer directly to the public internet.
- Use a reverse proxy (Nginx, Traefik, Caddy, Apache) to:
- Terminate SSL/TLS (HTTPS)
- Forward requests securely to your Load Balancer
- Add authentication (basic auth, SSO, etc.) for
/dashboardor/bullendpoints
Example Nginx config:
server {
listen 443 ssl;
server_name your-lb.example.com;
ssl_certificate /etc/ssl/certs/your-cert.pem;
ssl_certificate_key /etc/ssl/private/your-key.pem;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 310s;
client_max_body_size 10m;
# Protect both exact paths and their subpaths, including case variants.
location ~* ^/(dashboard|bull)(/|$) {
proxy_pass http://localhost:4000;
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
}
# REST and MCP use their own bearer credentials in Authorization.
location / {
proxy_pass http://localhost:4000;
proxy_set_header Authorization $http_authorization;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
}
}
Basic authentication belongs only on the administrative routes. Applying it to /mcp would compete with the MCP bearer token for the Authorization header. Match the proxy body limit to REQUEST_BODY_LIMIT and the read timeout to TASK_TIMEOUT. proxy_buffering off lets streaming responses reach the client progressively.
Docker image
The supplied Docker image is built on node:24.22.1-bookworm and runs on node:24.22.1-bookworm-slim as the non-root node user. Docker Compose starts Redis 7.4.11 with append-only persistence, and publishes the Load Balancer port on 127.0.0.1 only, so a reverse proxy on the same host can reach it while other hosts cannot.
Docker as a Service
In production, we recommend using Docker and configuring it as a service. Here's how to configure your Load Balancer container as a service with systemd (compatible with Debian, Ubuntu, Fedora, CentOS 7+, RHEL 7+, Rocky, AlmaLinux, Arch Linux, etc.).
-
Stop the Docker container if it was launched.
-
Create a service:
touch /etc/systemd/system/andera-load-balancer.service -
Complete it with your service configuration:
[Unit]Description=Andera Load BalancerRequires=docker.serviceAfter=docker.service[Service]Type=oneshotWorkingDirectory=/var/www/andera-load-balancerExecStart=/usr/bin/docker compose up -dExecStop=/usr/bin/docker compose downRemainAfterExit=yes[Install]WantedBy=multi-user.target -
Activate the service:
sudo systemctl daemon-reexecsudo systemctl enable andera-load-balancersudo systemctl start andera-load-balancer
Authentication and Secure Communication
/task,/logsand detailed/healthuseLB_AUTH_KEY. MCP uses its dedicatedMCP_AUTH_KEY. Dashboard (/dashboardand/dashboard/api/*, which expose Worker URLs and logs) and Bull (/bull, which exposes job data and actions) have no built-in login: protect them at the reverse proxy or keep them disabled (the default).LB_AUTH_KEYmust be identical on the Load Balancer and every Worker. Because it is also sent as a WebSocket subprotocol, use token characters only; a hex key generated withopenssl rand -hex 32works everywhere.- When the Load Balancer communicates with a Worker (for
/task), it provides:Authorization: <AUTH_KEY>(the target Worker's AUTH_KEY)x-lb-auth: <LB_AUTH_KEY>(your Load Balancer's LB_AUTH_KEY)
- Sensitive endpoints like
/dashboard,/bull, and/logsshould be protected by your reverse proxy (authentication, IP allowlist, etc.). - Use HTTPS for all external communication.
Network Security
- Restrict access to Load Balancer ports using firewalls or security groups.
- Only allow trusted sources (clients, internal services) to connect.
- Protect dashboard and monitoring endpoints with authentication and/or IP allowlists.
System Configuration (Linux)
If you are running Redis on a Linux host (bare-metal or VM), it is recommended to set the following kernel parameter:
sudo sysctl vm.overcommit_memory=1
To make it persistent across reboots:
echo "vm.overcommit_memory=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
Without this setting, Redis background saves (BGSAVE) may fail under memory pressure because the Linux kernel refuses the fork() call. Redis itself logs a warning at startup if vm.overcommit_memory is not set to 1. This is critical for BullMQ reliability.
Checklist for Production
- Use HTTPS via a reverse proxy
- Set strong, unique
LB_AUTH_KEYandAUTH_KEY(the sameLB_AUTH_KEYon the Load Balancer and every Worker) - Keep
DASHBOARD_ENABLEDandBULL_BOARD_ENABLEDoff, or protect/dashboardand/bullat the reverse proxy - Set
vm.overcommit_memory=1on Linux hosts running Redis - Monitor logs, dashboard, and health endpoints
- Restrict network access
- Regularly update dependencies and images
Queue process boundary
Run one active Load Balancer process per Redis queue. BullMQ stores job payloads in Redis, but the waiting HTTP response and Worker credential stay only in that LB process. A queued request cannot be resumed by another LB replica or after a restart; an orphaned job is marked failed rather than reported as successful. This also applies to webhook-mode tasks: one that has not finished when the LB restarts is dropped without a webhook call. (A task that fails or times out while the LB is running is reported to its webhook; see Usage.) Clients should use bounded retries and idempotency for operations that must survive an LB restart.
Tip: For cloud deployments, use managed SSL, secrets managers, and autoscaling for Workers as provided by your platform.
Enable MCP in Docker
The optional docker-compose.mcp.yml override loads the MCP token and target credential environment variables and mounts a configuration directory read-only. Use a directory mount for reliable live reload after atomic file replacement. See MCP Docker setup. Expose /mcp over HTTPS and forward its Authorization header. The endpoint uses stateless Streamable HTTP, so no SSE-specific proxy configuration is needed.