Skip to main content

Deployment

This page covers best practices and recommendations for deploying your Load Balancer in production environments.

Reverse Proxy & HTTPS​

danger

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 /dashboard or /bull endpoints

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.).

  1. Stop the Docker container if it was launched.

  2. Create a service:

    touch /etc/systemd/system/andera-load-balancer.service
  3. Complete it with your service configuration:

    [Unit]
    Description=Andera Load Balancer
    Requires=docker.service
    After=docker.service

    [Service]
    Type=oneshot
    WorkingDirectory=/var/www/andera-load-balancer
    ExecStart=/usr/bin/docker compose up -d
    ExecStop=/usr/bin/docker compose down
    RemainAfterExit=yes

    [Install]
    WantedBy=multi-user.target
  4. Activate the service:

    sudo systemctl daemon-reexec
    sudo systemctl enable andera-load-balancer
    sudo systemctl start andera-load-balancer

Authentication and Secure Communication​

  • /task, /logs and detailed /health use LB_AUTH_KEY. MCP uses its dedicated MCP_AUTH_KEY. Dashboard (/dashboard and /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_KEY must 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 with openssl rand -hex 32 works 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 /logs should 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
warning

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_KEY and AUTH_KEY (the same LB_AUTH_KEY on the Load Balancer and every Worker)
  • Keep DASHBOARD_ENABLED and BULL_BOARD_ENABLED off, or protect /dashboard and /bull at the reverse proxy
  • Set vm.overcommit_memory=1 on 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.