From aca51e1e19e8a49110c013a1225d3d219a520749 Mon Sep 17 00:00:00 2001 From: Anton Sychev Date: Wed, 25 Mar 2026 19:49:13 +0100 Subject: [PATCH] =?UTF-8?q?docs(installation):=20mejorar=20instrucciones?= =?UTF-8?q?=20y=20estructura=20de=20instalaci=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Reorganizar la sección de instalación con métodos y comandos más claros - Añadir opciones Docker con detalles para instalación manual y una línea - Incluir comandos útiles de Docker y PM2 para despliegue y gestión - Añadir sección para despliegue local con validaciones y pasos detallados - Incluir instrucciones completas para uso de PM2 con autoarranque y archivo ecosystem - Mejorar formato y lenguaje para mayor claridad en ejemplos y descripciones - Añadir encabezados y separadores para facilitar la lectura y navegación --- README.md | 212 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 156 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 91163c2..ba1157d 100644 --- a/README.md +++ b/README.md @@ -34,34 +34,45 @@ The app runs as a Next.js service and stores runtime state on disk (`./data`). - Code of conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) - Security policy: [SECURITY.md](./SECURITY.md) -## Installation (All Supported Paths) +## Installation -| Path | Best for | Command | +Choose the deployment method that best fits your needs: + +| Method | Best For | Command | | --- | --- | --- | -| One-command installer | Fastest setup, Docker-first | `curl -fsSL https://raw.githubusercontent.com/eggent-ai/eggent/main/scripts/install.sh \| bash` | -| Local production | Run directly on your machine (Node + npm) | `npm run setup:local` | -| Docker isolated | Containerized runtime | `npm run setup:docker` | -| Manual setup | Full control | see [Manual Setup](#manual-setup) | +| **Docker** (One-command) | Fastest setup, VPS, production | `curl -fsSL https://raw.githubusercontent.com/eggent-ai/eggent/main/scripts/install.sh \| bash` | +| **Docker** (Manual) | Containerized runtime, full control | `npm run setup:docker` | +| **Local/Node.js** | Run directly on your machine | `npm run setup:local` | +| **Development** | Active development, hot reload | `npm run dev` | -## 1) One-command Installer +--- + +## Docker Deployment + +### Option A: One-command Installer (Recommended) + +The fastest way to get Eggent running, especially on VPS: ```bash curl -fsSL https://raw.githubusercontent.com/eggent-ai/eggent/main/scripts/install.sh | bash ``` What it does: -- installs Docker (best-effort on macOS/Linux) if missing -- clones/updates Eggent in `~/.eggent` -- runs Docker deployment via `scripts/install-docker.sh` +- Installs Docker (best-effort on macOS/Linux) if missing +- Clones/updates Eggent in `~/.eggent` +- Runs Docker deployment via `scripts/install-docker.sh` -Installer environment variables: -- `EGGENT_INSTALL_DIR`: target directory (default: `~/.eggent`) -- `EGGENT_BRANCH`: git branch (default: `main`) -- `EGGENT_REPO_URL`: git repo URL (default: `https://github.com/eggent-ai/eggent.git`) -- `EGGENT_AUTO_INSTALL_DOCKER`: `1`/`0` (default: `1`) -- `EGGENT_APP_BIND_HOST`: Docker published bind host (`Linux default: 0.0.0.0`, otherwise `127.0.0.1`) +**Environment variables:** -Example: +| Variable | Default | Description | +| --- | --- | --- | +| `EGGENT_INSTALL_DIR` | `~/.eggent` | Target directory | +| `EGGENT_BRANCH` | `main` | Git branch to use | +| `EGGENT_REPO_URL` | `https://github.com/eggent-ai/eggent.git` | Repository URL | +| `EGGENT_AUTO_INSTALL_DOCKER` | `1` | Auto-install Docker if missing | +| `EGGENT_APP_BIND_HOST` | `0.0.0.0` (Linux) / `127.0.0.1` | Docker bind host | + +Example with custom options: ```bash EGGENT_INSTALL_DIR=~/apps/eggent \ @@ -70,24 +81,55 @@ EGGENT_AUTO_INSTALL_DOCKER=1 \ curl -fsSL https://raw.githubusercontent.com/eggent-ai/eggent/main/scripts/install.sh | bash ``` -On Linux (including VPS installs), the one-command installer publishes app port on all interfaces by default, so app is reachable at `http://:3000`. +On Linux (including VPS installs), the one-command installer publishes the app port on all interfaces by default, making it reachable at `http://:3000`. -## 2) Local Production Setup (Node + npm) +### Option B: Manual Docker Setup + +If you already have the repository cloned: + +```bash +npm run setup:docker +``` + +This script: +- Validates Docker + Compose +- Prepares `.env` and `data/` +- Builds image and starts container +- Waits for `GET /api/health` to succeed + +**Useful Docker commands:** + +```bash +docker compose logs -f app # View logs +docker compose restart app # Restart app +docker compose down # Stop and remove +docker compose up -d app # Start in background +``` + +Open: `http://localhost:3000` + +--- + +## Local/Node.js Deployment + +Run Eggent directly on your machine with Node.js: + +### Quick Start ```bash npm run setup:local ``` This script: -- validates Node/npm availability -- validates `python3` availability (required for Code Execution with Python runtime) -- validates `curl` availability (required for terminal commands like `curl ...`) -- warns if recommended utilities are missing: `git`, `jq`, `pip3`, `rg` -- creates `.env` from `.env.example` if needed -- generates secure defaults for token placeholders -- installs dependencies -- builds production output -- runs a health smoke-check +- Validates Node/npm availability +- Validates `python3` availability (required for Code Execution with Python runtime) +- Validates `curl` availability (required for terminal commands) +- Warns if recommended utilities are missing: `git`, `jq`, `pip3`, `rg` +- Creates `.env` from `.env.example` if needed +- Generates secure defaults for token placeholders +- Installs dependencies +- Builds production output +- Runs a health smoke-check Start the app: @@ -95,54 +137,112 @@ Start the app: npm run start ``` -Open: -- `http://localhost:3000` +Open: `http://localhost:3000` -## 3) Docker Isolated Setup +### PM2 Auto-start (Optional - Linux/macOS) + +For production deployments with auto-restart on boot, use PM2: + +**1. Install PM2 globally:** ```bash -npm run setup:docker +npm install -g pm2 ``` -This script: -- validates Docker + Compose -- prepares `.env` and `data/` -- builds image and starts container -- waits for `GET /api/health` to succeed - -Open: -- `http://localhost:3000` - -Useful Docker commands: +**2. Start Eggent with PM2:** ```bash -docker compose logs -f app -docker compose restart app -docker compose down +pm2 start npm --name eggent -- run start ``` -## 4) Manual Setup +**3. Save PM2 configuration:** ```bash -cp .env.example .env -# ensure python3 is installed and available in PATH -npm install -npm run build -npm run start +pm2 save ``` -Open: -- `http://localhost:3000` +**4. Setup systemd auto-start:** -## 5) Development Mode +```bash +pm2 startup systemd +``` + +Copy and execute the command output (requires sudo). + +**5. Verify auto-start works:** + +```bash +sudo reboot +# After reboot: +pm2 status +``` + +**Alternative: Using ecosystem file** + +Create `ecosystem.config.js` in your Eggent directory: + +```javascript +module.exports = { + apps: [ + { + name: "eggent", + cwd: "/home/YOUR_USERNAME/.eggent", + script: "npm", + args: "run start", + autorestart: true, + watch: false, + env: { + NODE_ENV: "production" + } + } + ] +} +``` + +Then start with: + +```bash +pm2 start ecosystem.config.js +pm2 save +pm2 startup systemd +``` + +**Common PM2 commands:** + +```bash +pm2 status # Check status +pm2 logs eggent # View logs +pm2 restart eggent # Restart app +pm2 stop eggent # Stop app +pm2 delete eggent # Remove from PM2 +``` + +--- + +## Development Mode + +For active development with hot reload: ```bash npm install npm run dev ``` -Open: -- `http://localhost:3000` +Open: `http://localhost:3000` + +### Manual Setup (Full Control) + +If you prefer complete manual control: + +```bash +cp .env.example .env +# Ensure python3 is installed and available in PATH +npm install +npm run build +npm run start +``` + +Open: `http://localhost:3000` ## Updating Eggent