Skip to main content

Installation

info

Before deploying your Worker, ensure you have configured your .env file 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).
  • npm
  • Docker (optional, for containerized deployment)

Manual Installation​

  1. Clone the Base Worker repository:

    git clone https://github.com/andera-top/base-worker.git
    cd base-worker
  2. Install dependencies:

    npm install
  3. Configure your .env by copying .env.example (cp .env.example .env), and edit src/config/index.ts as needed.

    Set AUTH_KEY and LB_AUTH_KEY to two distinct random values, for example with openssl rand -hex 32. If the Worker is managed by a Load Balancer, LB_AUTH_KEY must be the same value as the Load Balancer's. See Configuration for all variables and their validation rules: an invalid value stops the Worker at startup.

    You can add your configuration variables:

    export const config: Config = {
    ...coreConfig,
    baseWorkerSpecificConfig: {
    customConfigOption: process.env.CUSTOM_CONFIG || 'default-value', // Example
    },
    port: Number(process.env.PORT || '3000'),
    websocketPort: Number(process.env.WEBSOCKET_PORT || '3001'),
    }
  4. Start the Worker:

    npm run build
    npm start

    During development, npm run dev runs the TypeScript sources directly with ts-node.

Docker Installation​

  1. Clone the repository and navigate to the folder:

    git clone https://github.com/andera-top/base-worker.git
    cd base-worker
  2. Configure your .env by copying .env.example, and edit src/config/index.ts as needed. See Manual Installation to add your own configuration variables.

  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

    Compose passes the variables declared in docker-compose.yml. For MCP settings and the configuration mount, include the MCP Compose override.

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

The image is named andera-top/base-worker by default. It runs the application as the non-root node user, which cannot modify the application files (including dist).

Only the API port is published, on 127.0.0.1. On the andera-net network, add the Worker to the Load Balancer's workers.json as http://andera-base-worker:3000 (the Compose service name); the Load Balancer also reaches the WebSocket port over this network.

You are now ready to build your own custom Worker by adding functions, services, helpers, and tags.