Skip to main content

Deployment

This page covers best practices and recommendations for deploying your Base Worker in production environments.

Reverse Proxy & HTTPS​

danger

Never expose your Worker directly to the public internet.

  • Use a reverse proxy (Nginx, Traefik, Caddy, Apache) to:
    • Terminate SSL/TLS (HTTPS)
    • Forward requests securely to your Worker

Example Nginx config:

server {
listen 443 ssl;
server_name your-worker.example.com;

ssl_certificate /etc/ssl/certs/your-cert.pem;
ssl_certificate_key /etc/ssl/private/your-key.pem;

location / {
proxy_pass http://localhost:3000;
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_set_header Authorization $http_authorization;
proxy_read_timeout 310s;
proxy_buffering off;
client_max_body_size 10m;
}
}

Docker as a Service​

The supplied Docker image builds on node:24.22.1-bookworm and runs on node:24.22.1-bookworm-slim. The application runs as the non-root node user and cannot modify its own files, including dist: write any runtime data to a mounted volume or a temporary directory.

In production, we recommend using Docker and configuring it as a service. Here's how to configure your Worker 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-worker.service
  3. Complete it with your service configuration:

    [Unit]
    Description=Andera Worker
    Requires=docker.service
    After=docker.service

    [Service]
    Type=oneshot
    WorkingDirectory=/var/www/andera-worker
    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-worker
    sudo systemctl start andera-worker

Authentication and Secure Communication​

  • REST task and maintenance endpoints require AUTH_KEY; MCP requires the separate MCP_AUTH_KEY. Health has a minimal public response, while detailed health and logs accept either Authorization: <AUTH_KEY> or x-lb-auth: <LB_AUTH_KEY>. OpenAPI pages (/docs and /openapi) are unauthenticated when OPENAPI_ENABLED=true; keep them disabled in production or restrict access to them.
  • When the Load Balancer communicates with a Worker (for /task), it provides:
    • Authorization: <AUTH_KEY> (the Worker's AUTH_KEY)
    • x-lb-auth: <LB_AUTH_KEY> (the Load Balancer's LB_AUTH_KEY)
  • LB_AUTH_KEY must be identical on the Load Balancer and every Worker. The Load Balancer discovers Workers through authenticated /health and the WebSocket connection; with a different key it never discovers the Worker. Use a hexadecimal value, for example openssl rand -hex 32.
  • For direct client calls to /task, only Authorization: <AUTH_KEY> (the Worker's AUTH_KEY) is required.
  • Sensitive endpoints like /logs and authenticated /health (which displays more information than the unauthenticated public version) require valid authentication headers.
  • The Load Balancer connects to the Worker WebSocket port: ws:// for an HTTP Worker URL, wss:// for HTTPS. Worker Core itself serves plain WebSockets, so HTTPS deployments must also terminate TLS for the advertised WebSocket port. Publishing only the HTTP port is insufficient for cross-host WebSocket access.

Secrets​

  • Never commit secrets to git.
  • Use environment variables for all sensitive config (keys, passwords, etc.).
  • Rotate keys regularly.
  • Do not put secrets in WEBHOOK_HEADERS that API callers must not learn: these headers are sent to whatever webhook URL an authenticated caller supplies.

Network Security​

  • Restrict access to Worker ports using firewalls or security groups.
  • Only allow trusted sources (Load Balancer, internal services) to connect.
  • The supplied docker-compose.yml publishes the API port on 127.0.0.1 only, for a reverse proxy on the same host. A Load Balancer on the andera-net Docker network reaches the Worker by its service name (http://andera-base-worker:3000) and its WebSocket port directly.
  • Webhook destinations are chosen by authenticated callers and are not filtered; restrict outbound network access when callers are not fully trusted.

Checklist for Production​

  • Use HTTPS via a reverse proxy
  • Set strong, distinct AUTH_KEY and LB_AUTH_KEY, with LB_AUTH_KEY identical to the Load Balancer's
  • Keep OPENAPI_ENABLED=false unless the documentation pages are restricted
  • Use environment variables for secrets
  • Monitor logs and health endpoints
  • Restrict network access
  • Regularly update dependencies and images

Tip: For cloud deployments, use managed SSL, secrets managers, and autoscaling as provided by your platform.

Enable MCP in Docker​

Use the optional docker-compose.mcp.yml override. It loads MCP_AUTH_KEY and mounts a configuration directory read-only. See MCP Docker setup. Expose /mcp over HTTPS and forward its Authorization header.