Skip to content

Commit c6e80b3

Browse files
committed
release: merge develop into main for v0.30.4
2 parents 271f9e5 + 5c6c112 commit c6e80b3

10 files changed

Lines changed: 830 additions & 21 deletions

CHANGELOG.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [0.30.4] - 2026-04-24
9+
10+
Patch release with a **P0 race-condition fix** in the container entrypoint plus a complete Docker install experience (ready-to-run compose + full tutorial).
11+
12+
### Fixed
13+
14+
- **Race condition on shared `/workspace/config` volume (P0)** — when `dashboard`, `telegram` and `scheduler` boot in parallel against the same named volume (the canonical Docker / Swarm / Portainer deploy pattern), the first-boot bootstrap raced on four operations:
15+
- `[ ! -f .env ] && cp .env.example .env` — one container wins, others crash with `File exists`. Scheduler died visibly on every fresh v0.30.3 deploy.
16+
- `[ ! -f ] && cp` for `providers.json` / `heartbeats.yaml` — same race.
17+
- `grep -q EVONEXUS_SECRET_KEY || echo … >> .env` — two processes both see "not found" and append **two different keys**; Flask picks one at random per request, invalidating sessions silently.
18+
- Same pattern for `KNOWLEDGE_MASTER_KEY` — silently corrupted Knowledge Base encryption, losing all configured DB connections on second boot.
19+
20+
Fix: wrap the whole bootstrap in `flock` on a lockfile inside the shared volume, serializing all containers regardless of start order. Also added `cp -n` (no-clobber) as belt-and-suspenders. `flock` is part of `util-linux`, already present in both base images.
21+
22+
### Added
23+
24+
- **`docker-compose.hub.yml`** — ready-to-run compose file that pulls `evoapicloud/evo-nexus-*` from Docker Hub instead of building from source. Uses `depends_on: condition: service_healthy` to order the boot (dashboard first, then telegram/scheduler) — defense-in-depth on top of the flock fix. This is the recommended install for end users: `curl -O …docker-compose.hub.yml && docker compose -f docker-compose.hub.yml up -d`.
25+
- **`docs/guides/docker-install.md`** — complete Docker install guide. Prerequisites (Docker Engine 24+ is the only requirement — image ships everything), one-command boot, first-boot wizard walkthrough, update flow (`docker compose pull && up -d`), backup/restore recipes, advanced section documenting how to pass secrets via `environment:` or Docker Secrets (for CI/CD and immutable-infra users who prefer to keep secrets out of the `.env` volume), running behind Caddy for public HTTPS, troubleshooting table.
26+
- **Install method chooser in `docs/getting-started.md`** — table at the top comparing Docker vs CLI (`npx`) vs manual clone, with clear guidance on which to pick.
27+
28+
### Changed
29+
30+
- **`README.md`** — Docker promoted to Method 1 in Quick Start. Prerequisites split into two tracks (Docker-only vs CLI-flow), reflecting that the Docker image ships Claude Code, Python, Node, uv and `gh` baked in.
31+
- **`docs/guides/updating.md`** — new `docker compose -f docker-compose.hub.yml pull && up -d` section documenting the Docker Hub upgrade path. Swarm examples bumped to `v0.30.4`.
32+
833
## [0.30.3] - 2026-04-24
934

1035
Patch release completing the Docker Hub migration: official images now ship as **multi-arch manifests** (`linux/amd64` + `linux/arm64`) so ARM hosts (Apple Silicon, AWS Graviton, Oracle Cloud ARM, Raspberry Pi, many modern VPS) can pull without platform overrides.

README.md

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,16 @@ Social media accounts (YouTube, Instagram, LinkedIn) are connected via OAuth thr
111111

112112
## Prerequisites
113113

114+
**For the Docker install** (easiest — the container ships everything):
115+
116+
| Tool | Required | Install |
117+
|------|----------|---------|
118+
| **Docker Engine 24+** | Yes | [docs.docker.com/engine/install](https://docs.docker.com/engine/install/) |
119+
120+
That's it. The image includes Claude Code, Python, Node, uv, gh, and every other runtime dependency.
121+
122+
**For the CLI / from-source install** (the dev flow):
123+
114124
| Tool | Required | Install |
115125
|------|----------|---------|
116126
| **Claude Code** | Yes | `npm install -g @anthropic-ai/claude-code` ([docs](https://claude.ai/download)) |
@@ -150,15 +160,27 @@ The setup wizard asks which provider you want during `make setup`, and you can s
150160

151161
> **Starting out?** After installing, open Claude Code and call **`/oracle`**. It's the official entry point of EvoNexus: runs the initial setup, interviews you about your business, shows what the toolkit can automate for you, and delivers a **phased activation plan** — an index file at the top + one folder per phase + one file per item, each with suggested agent team, dependencies, and pending decisions. The plan is materialized by the `prod-activation-plan` skill (workspace canonical pattern) so you never have to guess the next step.
152162
153-
### Method 1 — One command (recommended)
163+
### Method 1 — Docker (no setup, runs anywhere)
164+
165+
The fastest way. Pulls official multi-arch images (`linux/amd64` + `linux/arm64`) from Docker Hub — works natively on Apple Silicon, AWS Graviton, Oracle ARM, Raspberry Pi, and x86_64 servers.
166+
167+
```bash
168+
curl -O https://raw.githubusercontent.com/EvolutionAPI/evo-nexus/main/docker-compose.hub.yml
169+
docker compose -f docker-compose.hub.yml up -d
170+
open http://localhost:8080
171+
```
172+
173+
The setup wizard loads on first boot. Paste your Anthropic / OpenAI / Codex key and you're done — no extra tooling on your host. Full guide: [docs/guides/docker-install.md](docs/guides/docker-install.md).
174+
175+
### Method 2 — One command (for CLI / terminal workflow)
154176

155177
```bash
156178
npx @evoapi/evo-nexus
157179
```
158180

159-
This downloads and runs the interactive setup wizard automatically.
181+
This downloads and runs the interactive setup wizard automatically. Requires the CLI prerequisites above (Claude Code, Python, Node, uv).
160182

161-
### Method 2 — Manual clone
183+
### Method 3 — Manual clone (for developers / contributors)
162184

163185
```bash
164186
git clone --depth 1 https://github.com/EvolutionAPI/evo-nexus.git

cli/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@evoapi/evo-nexus",
3-
"version": "0.30.3",
3+
"version": "0.30.4",
44
"description": "Unofficial open source toolkit for Claude Code — AI-powered business operating system",
55
"keywords": [
66
"claude-code",

docker-compose.hub.yml

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# ============================================================================
2+
# EvoNexus — docker-compose.yml para usuários finais (imagens do Docker Hub)
3+
#
4+
# Uso rápido:
5+
# $ curl -O https://raw.githubusercontent.com/EvolutionAPI/evo-nexus/main/docker-compose.hub.yml
6+
# $ docker compose -f docker-compose.hub.yml up -d
7+
# $ open http://localhost:8080
8+
#
9+
# Tudo (providers, integrações, chaves de API, secrets) é configurado
10+
# pela UI após o primeiro boot — abra http://localhost:8080 e siga o
11+
# wizard. Nenhum arquivo .env precisa ser editado à mão.
12+
#
13+
# Para DEVS que querem buildar a imagem local a partir do código-fonte,
14+
# veja docker-compose.yml (que usa `build:` em vez de `image:`).
15+
#
16+
# Para produção em Docker Swarm / Portainer, veja evonexus.stack.yml
17+
# e README.swarm.md.
18+
# ============================================================================
19+
20+
services:
21+
# Dashboard — Flask + React + terminal embutido + Claude CLI
22+
# Abra http://localhost:8080 após o boot.
23+
dashboard:
24+
image: evoapicloud/evo-nexus-dashboard:latest
25+
container_name: evonexus-dashboard
26+
ports:
27+
- "8080:8080" # Dashboard (UI + API)
28+
- "32352:32352" # Terminal server (WebSocket)
29+
environment:
30+
- TZ=America/Sao_Paulo
31+
- EVONEXUS_PORT=8080
32+
- TERMINAL_SERVER_PORT=32352
33+
- FORWARDED_ALLOW_IPS=*
34+
volumes:
35+
# Volumes nomeados mantêm a configuração entre reinícios.
36+
# Tudo que você configurar pela UI (providers, integrações, chaves)
37+
# vive em `evonexus_config`.
38+
- evonexus_config:/workspace/config
39+
- evonexus_workspace:/workspace/workspace
40+
- evonexus_dashboard_data:/workspace/dashboard/data
41+
- evonexus_memory:/workspace/memory
42+
- evonexus_adw_logs:/workspace/ADWs/logs
43+
- evonexus_agent_memory:/workspace/.claude/agent-memory
44+
restart: unless-stopped
45+
healthcheck:
46+
test: ["CMD", "curl", "-fsS", "http://localhost:8080/api/version"]
47+
interval: 30s
48+
timeout: 10s
49+
retries: 3
50+
start_period: 30s
51+
52+
# Telegram — bot que escuta mensagens e delega para agentes
53+
# Opcional: remova este serviço se não for usar Telegram.
54+
# Espera ANTHROPIC_API_KEY aparecer no .env (configurado pela UI) antes
55+
# de iniciar — não fica em crash-loop enquanto você configura.
56+
telegram:
57+
image: evoapicloud/evo-nexus-runtime:latest
58+
container_name: evonexus-telegram
59+
command: ["claude", "--channels", "plugin:telegram@claude-plugins-official", "--dangerously-skip-permissions"]
60+
environment:
61+
- TZ=America/Sao_Paulo
62+
- REQUIRE_ANTHROPIC_KEY=1
63+
volumes:
64+
- evonexus_config:/workspace/config
65+
- evonexus_workspace:/workspace/workspace
66+
- evonexus_memory:/workspace/memory
67+
- evonexus_adw_logs:/workspace/ADWs/logs
68+
- evonexus_agent_memory:/workspace/.claude/agent-memory
69+
stdin_open: true
70+
tty: true
71+
restart: unless-stopped
72+
depends_on:
73+
dashboard:
74+
condition: service_healthy
75+
76+
# Scheduler — executa rotinas automáticas (daily, weekly, monthly).
77+
# Opcional: remova este serviço se não for usar rotinas automatizadas.
78+
scheduler:
79+
image: evoapicloud/evo-nexus-runtime:latest
80+
container_name: evonexus-scheduler
81+
command: ["uv", "run", "python", "scheduler.py"]
82+
environment:
83+
- TZ=America/Sao_Paulo
84+
- REQUIRE_ANTHROPIC_KEY=1
85+
volumes:
86+
- evonexus_config:/workspace/config
87+
- evonexus_workspace:/workspace/workspace
88+
- evonexus_memory:/workspace/memory
89+
- evonexus_adw_logs:/workspace/ADWs/logs
90+
- evonexus_agent_memory:/workspace/.claude/agent-memory
91+
restart: unless-stopped
92+
depends_on:
93+
dashboard:
94+
condition: service_healthy
95+
96+
# ----------------------------------------------------------------------------
97+
# Volumes nomeados — seus dados vivem aqui. Backup: `docker volume ls` +
98+
# `docker run --rm -v evonexus_config:/src -v $PWD:/dst alpine tar czf /dst/config.tgz -C /src .`
99+
# ----------------------------------------------------------------------------
100+
volumes:
101+
evonexus_config:
102+
evonexus_workspace:
103+
evonexus_dashboard_data:
104+
evonexus_memory:
105+
evonexus_adw_logs:
106+
evonexus_agent_memory:

docs/getting-started.md

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
11
# Getting Started with EvoNexus
22

3-
## Prerequisites
3+
## Choose your install method
4+
5+
| Method | Best for | Requires |
6+
|---|---|---|
7+
| **[Docker](guides/docker-install.md)** | Anyone who wants a one-command install that works the same on every OS (Linux, macOS, Windows+WSL2, VPS) | Docker Engine 24+ |
8+
| **CLI (`npx`)** | Users who want to run EvoNexus alongside their existing Claude Code CLI | Claude Code, Python 3.11+, Node 18+, uv |
9+
| **Manual clone** | Developers who want to modify source | git, Claude Code, Python 3.11+, Node 18+, uv |
10+
11+
Pick the Docker flow if you're unsure. Keep reading for the CLI flow.
12+
13+
## Prerequisites (CLI flow only)
414

515
- **Claude Code CLI**[Install Claude Code](https://claude.ai/claude-code)
616
- **Python 3.11+** with [uv](https://docs.astral.sh/uv/)
@@ -9,15 +19,27 @@
919

1020
## Installation
1121

12-
### 1. Quick Install (recommended)
22+
### Option A — Docker (fastest)
23+
24+
Pulls the official multi-arch images and runs the wizard at http://localhost:8080. Full guide: [Installing with Docker](guides/docker-install.md).
25+
26+
```bash
27+
curl -O https://raw.githubusercontent.com/EvolutionAPI/evo-nexus/main/docker-compose.hub.yml
28+
docker compose -f docker-compose.hub.yml up -d
29+
open http://localhost:8080
30+
```
31+
32+
Skip to [Start with /oracle](#6-use-claude-code--start-with-oracle) after the wizard completes.
33+
34+
### Option B — `npx` (CLI flow)
1335

1436
```bash
1537
npx @evoapi/evo-nexus
1638
```
1739

1840
This downloads and runs the interactive setup wizard automatically.
1941

20-
### Alternative: Manual Clone
42+
### Option C — Manual clone
2143

2244
```bash
2345
git clone --depth 1 https://github.com/EvolutionAPI/evo-nexus.git

0 commit comments

Comments
 (0)