Deployment

This guide covers building and deploying the EleAgent Docker stack on a host machine.

Prerequisites

• Docker Engine 24+ with Docker Compose v2
• At least 16 GB RAM (5 workers + controller + proxy)
• Project data files accessible on the host filesystem
• Either an Anthropic Max account or an Anthropic API key
• External Nginx ingress for HTTPS termination (not part of this delivery — configuration guidance provided below)

Quick Start

1. Clone and Configure

git clone <repository-url>
cd eleask_poc
cp .env.example .env

Edit .env with your settings:

# Required — change this in production
JWT_SECRET=your-secure-random-string

# Path to project data on host (mounted read-only)
DATA_PATH=/path/to/project/data

# Path for writable artefacts on host
ARTEFACTS_PATH=./artefacts

# Path to system prompt file on host
SYSTEM_PROMPT_PATH=./config/system_prompt.md

# Host path prefix for file citations in agent responses
HOST_SOURCE_BASE=/path/on/engineer-workstation/to/data

# Max concurrent sessions (default: 5)
MAX_ACTIVE_SESSIONS=5

2. Build Images

docker compose build

This builds two images:

• infralytics/eleask-poc:phase1-controller — lean web server
• infralytics/eleask-poc:phase1-worker — full analysis toolchain

3. Start the Stack

docker compose up -d

This starts 7 containers:

1. eleask_egress_proxy — Squid HTTP proxy (starts first)
2. eleask_worker_1 through eleask_worker_5 — AI query workers (wait for proxy)
3. eleask_controller — web UI + API (waits for all workers)

4. Verify Health

# Check all containers are healthy
docker compose ps

# Check controller health endpoint
curl http://localhost:3001/health

# Check individual worker health
curl http://localhost:3001/api/health

5. Access the Web UI

Open http://<host-ip>:3001 in a browser. On first access, you will be prompted to create an admin account.

Authentication Setup

EleAgent supports two modes for AI model access:

Option A: Anthropic Max Account (Recommended for Testing)

Log in with Anthropic Max credentials through the web UI. Credentials persist in /artefacts/state/home/.claude/.credentials.json.

Option B: API Key

Set the ANTHROPIC_API_KEY environment variable in the worker service configuration:

# In .env or docker-compose override
ANTHROPIC_API_KEY=sk-ant-...

WARNING

The API key is shared across all workers. Monitor usage to avoid unexpected costs.

HTTPS Termination with Nginx

The EleAgent web UI is served over HTTP on port 3001. For production use, place an Nginx reverse proxy in front for HTTPS termination.

Example Nginx configuration:

server {
    listen 443 ssl http2;
    server_name eleagent.example.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;

        # WebSocket support — required for streaming responses
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

TIP

The Upgrade and Connection headers are essential — the chat interface uses WebSockets for real-time streaming.

Data Preparation

Recommended: Use an rsync Copy

We recommend mounting an rsync copy of the project files rather than the originals. This provides an additional safety layer — even in the event of a software bug, the original files remain untouched.

# Create a read-only copy of project data
rsync -a /original/project/data/ /srv/eleagent/data/

# Set DATA_PATH in .env
DATA_PATH=/srv/eleagent/data

The data directory is mounted read-only (/data:ro) inside all containers. The agent can read files for analysis but cannot modify, delete, or create files in this directory.

Updating the System Prompt

The system prompt is mounted as a file and can be updated without rebuilding:

# Edit the system prompt
vim ./config/system_prompt.md

# The agent picks up changes on the next query — no restart needed

This enables rapid iteration based on testing experience.

Updating the Docker Image

# Pull latest code
git pull

# Rebuild images
docker compose build

# Restart with new images
docker compose down && docker compose up -d

INFO

Artefacts, conversation logs, and databases are stored on the host volume and persist across image rebuilds.

Resource Requirements

Resource	Minimum	Recommended
CPU	4 cores	8 cores
RAM	8 GB	16 GB
Disk (images)	5 GB	10 GB
Disk (artefacts)	1 GB	10 GB
Disk (data)	Size of project files	~11 GB for Karavanke

Troubleshooting

Containers fail to start

Check that the artefacts directory exists and is writable by UID 10001:

mkdir -p ./artefacts
sudo chown -R 10001:10001 ./artefacts

Workers not connecting

Verify the egress proxy is healthy first — workers depend on it:

docker compose logs egress-proxy

Permission denied on /data

Ensure the data files are readable by UID 10001:

sudo chmod -R o+r /srv/eleagent/data/

WebSocket connection errors behind proxy

Ensure your Nginx configuration includes the WebSocket upgrade headers (see HTTPS section above).