Skip to content

docker-install.md

Latest commit

 

History

History
284 lines (190 loc) · 9.81 KB

docker-install.md

File metadata and controls

284 lines (190 loc) · 9.81 KB
Raw

Installing EvoNexus with Docker

The fastest way to run EvoNexus on any machine — Linux, macOS (Intel or Apple Silicon), Windows with WSL2, or a bare VPS. Pulls official images from Docker Hub, no source checkout or build step required.

TL;DR

curl -O https://raw.githubusercontent.com/EvolutionAPI/evo-nexus/main/docker-compose.hub.yml
docker compose -f docker-compose.hub.yml up -d
open http://localhost:8080

The setup wizard on first boot asks for a provider key (Anthropic, OpenAI or Codex). Everything else — integrations, Telegram, Stripe, Omie, Bling, Asaas, etc. — is configured through the UI.

Prerequisites

  • Docker Engine 24+ with Docker Compose v2. Install on Mac / Windows / Linux.
  • 4 GB RAM minimum (8 GB recommended — the Claude CLI and embedding models can be hungry).
  • 2 GB free disk for images + a few hundred MB for data volumes.
  • An Anthropic API key (or OpenAI / ChatGPT Codex account) — you'll paste this into the wizard on first boot.

No Node.js, Python, or any SDK needs to be installed on the host. The images ship everything.

Multi-arch — ARM64 works out of the box

Images are published as multi-arch manifests (linux/amd64 + linux/arm64), so:

  • Apple Silicon (M1/M2/M3 Macs) — pulls arm64 natively, no Rosetta overhead.
  • AWS Graviton, Oracle Cloud ARM free tier, Raspberry Pi 4/5 — pulls arm64 natively.
  • Traditional x86_64 servers — pulls amd64 as usual.

You never pass --platform. Docker picks the right arch from the manifest list.

Step 1 — Get the compose file

Download the ready-to-run compose file. It pulls images from evoapicloud/evo-nexus-{dashboard,runtime} on Docker Hub — no git clone required.

curl -O https://raw.githubusercontent.com/EvolutionAPI/evo-nexus/main/docker-compose.hub.yml

Open it — it's commented and self-explanatory. Key things to know:

  • 3 services: dashboard (Flask + React + terminal), telegram (bot listener), scheduler (automated routines). Telegram and scheduler are optional — remove them from the file if you don't need them.
  • Ports exposed: 8080 (dashboard UI + API) and 32352 (terminal WebSocket).
  • Volumes: 6 named volumes that survive docker compose down and hold everything the UI configures.

Step 2 — Start the stack

docker compose -f docker-compose.hub.yml up -d

First run downloads the images (~800 MB total, a few minutes depending on your connection). Subsequent boots are instant.

Check that all 3 services are up:

docker compose -f docker-compose.hub.yml ps

You should see:

NAME                   STATUS
evonexus-dashboard     Up (healthy)
evonexus-telegram      Up
evonexus-scheduler     Up

If the dashboard takes longer than 30 seconds to go healthy, check logs:

docker compose -f docker-compose.hub.yml logs -f dashboard

Step 3 — Open the UI and run the setup wizard

Open http://localhost:8080 in your browser. You'll see the first-boot wizard:

  1. Create admin user — username + password for the dashboard itself.
  2. Pick a provider — paste your Anthropic API key, OpenAI key, or click "Login with ChatGPT" for Codex OAuth.
  3. Optional integrations — Telegram bot token, Stripe, Omie, etc. Everything else is optional and can be added later.

Once you save a provider key, the telegram and scheduler services (which were waiting in a 30s poll loop) pick it up and start working. No restart needed.

Step 4 — Everyday commands

Action Command
View logs docker compose -f docker-compose.hub.yml logs -f
Restart docker compose -f docker-compose.hub.yml restart
Stop docker compose -f docker-compose.hub.yml down
Stop + wipe data docker compose -f docker-compose.hub.yml down -v ⚠️
Update to latest See Updating below

Updating

Pull the latest stable image

docker compose -f docker-compose.hub.yml pull
docker compose -f docker-compose.hub.yml up -d

Your data volumes are preserved — everything you configured through the UI stays intact.

Pin to a specific version

Edit docker-compose.hub.yml and replace :latest with :vX.Y.Z (e.g. :v0.30.4). Available tags: https://hub.docker.com/r/evoapicloud/evo-nexus-dashboard/tags

Rolling back is just bumping the tag down and running pull && up -d.

Backup and restore

Your configuration, workspace files, memory, and agent state live in 6 named volumes. To snapshot them all:

# Backup
mkdir -p evonexus-backup
for vol in config workspace dashboard_data memory adw_logs agent_memory; do
  docker run --rm \
    -v evonexus_${vol}:/src:ro \
    -v "$PWD/evonexus-backup":/dst \
    alpine tar czf /dst/${vol}.tgz -C /src .
done

# Restore on a fresh host
for vol in config workspace dashboard_data memory adw_logs agent_memory; do
  docker volume create evonexus_${vol}
  docker run --rm \
    -v evonexus_${vol}:/dst \
    -v "$PWD/evonexus-backup":/src:ro \
    alpine tar xzf /src/${vol}.tgz -C /dst
done

Advanced: passing secrets via environment variables

The default flow is "configure everything through the UI, which writes to a persisted .env inside the evonexus_config volume." Most users should stick with that.

If you prefer to keep secrets out of the volume (for CI/CD, Vault, Doppler, or immutable infra), you can pass any env var directly in the compose file. They take precedence over the volume's .env:

services:
  dashboard:
    image: evoapicloud/evo-nexus-dashboard:latest
    environment:
      - TZ=America/Sao_Paulo
      - EVONEXUS_PORT=8080
      # Bypass the UI — pass keys directly
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}      # read from shell or .env.compose
      - EVONEXUS_SECRET_KEY=${EVONEXUS_SECRET_KEY}
      - KNOWLEDGE_MASTER_KEY=${KNOWLEDGE_MASTER_KEY}
    env_file:
      - ./secrets.env   # or load from a file — this file is NOT inside the volume

Tradeoffs:

  • Pro: secrets live with the infrastructure, not the user-editable volume. Rotate by redeploying.
  • Con: the Providers page in the UI will still work (and will write to the volume's .env), but any value you pass via environment: wins. This can be confusing for non-technical users.

For the absolutely purist flow, pass REQUIRE_ANTHROPIC_KEY=0 on the telegram and scheduler services so they don't wait for a UI-saved key — they'll just use whatever is in environment:.

Advanced: Docker Secrets

Every env var also supports a _FILE counterpart. Point it at a file, and the entrypoint reads the content into the var at boot. This works natively with Docker Secrets in Swarm mode:

services:
  dashboard:
    environment:
      - ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic_key
    secrets:
      - anthropic_key

secrets:
  anthropic_key:
    external: true

Additionally, every file under /run/secrets/ is auto-discovered: /run/secrets/anthropic_api_key → sets ANTHROPIC_API_KEY if it's not already set.

Running on a VPS with a public domain

For production on a single-host VPS (not a Swarm cluster), put a reverse proxy in front of docker-compose.hub.yml. The simplest path is Caddy:

# Caddyfile next to docker-compose.hub.yml
evonexus.example.com {
    reverse_proxy /terminal/* localhost:32352
    reverse_proxy localhost:8080
}

Then caddy run and you have HTTPS with automatic Let's Encrypt certificates pointing at your EvoNexus stack.

For Docker Swarm with Traefik, see README.swarm.md and evonexus.stack.yml.

Troubleshooting

Dashboard port 8080 is already in use

Another service on your host is bound to 8080. Change the host port in the compose file:

ports:
  - "9090:8080"     # host 9090 → container 8080

Then open http://localhost:9090.

Telegram / scheduler logs say "waiting for ANTHROPIC_API_KEY"

Expected. These services poll .env every 30s. Configure a provider key in Dashboard → Providers and they'll pick it up automatically — no restart needed.

Services keep restarting after up -d

Check logs:

docker compose -f docker-compose.hub.yml logs --tail=50 <service>

99% of the time this is either (a) port conflict, (b) volume mount permission issue (rare, usually only on SELinux-enabled hosts — add :Z to volume mounts), or (c) disk full.

Fresh install doesn't show any agents / skills on /agents or /skills

On a brand-new volume, the APIs return {"error": "Setup required", "needs_setup": true} until the wizard completes. Open http://localhost:8080 and complete the wizard first.

Want to see what's inside the running container

docker compose -f docker-compose.hub.yml exec dashboard bash

Useful paths inside the container:

  • /workspace/config/.env — everything the UI saves (ports, keys, integrations)
  • /workspace/workspace/ — generated artifacts (reports, dashboards, daily logs)
  • /workspace/memory/ — long-term memory the agents write
  • /workspace/.claude/agent-memory/ — per-agent persistent state
  • /workspace/ADWs/logs/ — routine execution logs (JSONL)

Uninstall

docker compose -f docker-compose.hub.yml down -v

The -v flag also deletes the named volumes — all your configuration and data is gone. Skip the flag to keep volumes around for a future reinstall.

See also