From fc7fc16073dcc1a5da45fbd184ba0260a4e81fb7 Mon Sep 17 00:00:00 2001 From: minguezsanzjuanjose Date: Sun, 3 May 2026 14:41:28 +0200 Subject: [PATCH] Initial commit - Engram wiki docs --- 01-setup-maquina-nueva.md | 122 ++++++++++++++++++++++++++++++ 02-nuevo-proyecto-cloud.md | 53 +++++++++++++ 03-seguridad-cloud.md | 149 +++++++++++++++++++++++++++++++++++++ README.md | 58 +++++++++++++++ 4 files changed, 382 insertions(+) create mode 100644 01-setup-maquina-nueva.md create mode 100644 02-nuevo-proyecto-cloud.md create mode 100644 03-seguridad-cloud.md create mode 100644 README.md diff --git a/01-setup-maquina-nueva.md b/01-setup-maquina-nueva.md new file mode 100644 index 0000000..0738587 --- /dev/null +++ b/01-setup-maquina-nueva.md @@ -0,0 +1,122 @@ +# Engram — Setup en máquina nueva + +Guía para instalar Engram en un equipo nuevo y recuperar toda la memoria del cloud. + +--- + +## 1. Descargar el binario + +Ve a: +``` +https://github.com/Gentleman-Programming/engram/releases/latest +``` + +Descarga `engram_1.15.2_windows_amd64.zip` y extrae `engram.exe` en: +``` +C:\Users\TuUsuario\bin\ +``` + +--- + +## 2. Añadir al PATH + +Abre PowerShell y ejecuta (solo una vez): + +```powershell +[Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User") +``` + +Cierra y abre PowerShell de nuevo. Verifica: + +```powershell +engram version +``` + +--- + +## 3. Apuntar al servidor cloud + +```powershell +engram cloud config --server https://engram.v-encore-lab.com +``` + +--- + +## 4. Enrollar el proyecto + +```powershell +engram cloud enroll planificacion_proyectos +``` + +--- + +## 5. Descargar memorias del cloud + +```powershell +engram sync --cloud --project planificacion_proyectos --import +``` + +Esto descarga toda la memoria almacenada en el VPS a la máquina nueva. + +--- + +## 6. Configurar OpenCode + +```powershell +engram setup opencode +``` + +--- + +## 7. Arrancar el servidor HTTP + +```powershell +engram serve +``` + +Déjalo corriendo en una terminal aparte. + +--- + +## 8. Arranque automático con Windows + +1. Pulsa `Win + R` y escribe: +``` +shell:startup +``` + +2. Crea un archivo `engram.bat` con este contenido: +```bat +@echo off +start /min engram serve +``` + +A partir de ahora `engram serve` arranca solo cada vez que inicias Windows. + +--- + +## 9. Verificar que todo funciona + +Abre OpenCode en tu proyecto y escribe: +``` +mem_context +``` + +Si responde con información de sesión, todo está funcionando correctamente. + +--- + +## Sync manual en cualquier momento + +```powershell +cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN_AQUI && engram sync --cloud --project nombre_proyecto" +``` + +--- + +## Notas + +- El cloud está en `https://engram.v-encore-lab.com` +- El dashboard está en `https://engram.v-encore-lab.com/dashboard/` +- La base de datos local está en `C:\Users\TuUsuario\.engram\engram.db` +- El autosync se ejecuta cada ~5 minutos automáticamente \ No newline at end of file diff --git a/02-nuevo-proyecto-cloud.md b/02-nuevo-proyecto-cloud.md new file mode 100644 index 0000000..40dc1f7 --- /dev/null +++ b/02-nuevo-proyecto-cloud.md @@ -0,0 +1,53 @@ +# Engram — Añadir nuevo proyecto al cloud + +Pasos para registrar un nuevo proyecto en Engram Cloud. + +--- + +## 1. En el VPS — Permitir el proyecto + +Edita el docker-compose: + +```bash +nano /opt/engram/docker-compose.cloud.yml +``` + +Añade el nuevo proyecto a la variable `ENGRAM_CLOUD_ALLOWED_PROJECTS`: + +```yaml +ENGRAM_CLOUD_ALLOWED_PROJECTS: smoke-project,planificacion_proyectos,gestion-talleres-2000,NOMBRE_NUEVO_PROYECTO +``` + +Reinicia el contenedor para aplicar los cambios: + +```bash +docker compose -f docker-compose.cloud.yml up -d --force-recreate cloud +``` + +--- + +## 2. En tu PC — Enrollar y sincronizar + +```powershell +engram cloud enroll NOMBRE_NUEVO_PROYECTO +cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN && engram sync --cloud --project NOMBRE_NUEVO_PROYECTO" +``` + +--- + +## Notas + +- El nombre del proyecto se normaliza automáticamente a minúsculas con guiones bajos. Por ejemplo `PLANIFICACION_PROYECTOS` → `planificacion_proyectos` +- Cada proyecto tiene su propia memoria aislada en el cloud +- El dashboard muestra todos los proyectos en `https://engram.v-encore-lab.com/dashboard/` + +## Si el sync falla por mutaciones legacy + +```powershell +C:\Users\juanm\Downloads\sqlite3.exe C:\Users\juanm\.engram\engram.db "DELETE FROM sync_mutations WHERE entity = 'relation' AND project = 'NOMBRE_PROYECTO';" +``` + +Luego vuelve a hacer sync: +```powershell +cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN && engram sync --cloud --project NOMBRE_NUEVO_PROYECTO" +``` \ No newline at end of file diff --git a/03-seguridad-cloud.md b/03-seguridad-cloud.md new file mode 100644 index 0000000..b6cc108 --- /dev/null +++ b/03-seguridad-cloud.md @@ -0,0 +1,149 @@ +# Engram Cloud — Configuración de Seguridad + +Guía completa para securizar Engram Cloud en el VPS. + +--- + +## Configuración actual + +- **Servidor:** `https://engram.v-encore-lab.com` +- **Dashboard:** `https://engram.v-encore-lab.com/dashboard/` +- **Token:** `e5ace1caed605543642c1032ef9e24f803f092b4ef9863cc068a8eceaa01445b` +- **Modo:** enterprise con autenticación JWT activa +- **Proyectos permitidos:** `smoke-project`, `planificacion_proyectos`, `gestion-talleres-2000` + +--- + +## Docker Compose del VPS + +Ubicación: `/opt/engram/docker-compose.cloud.yml` + +```yaml +services: + postgres: + restart: always + image: postgres:16-alpine + container_name: engram-cloud-postgres + environment: + POSTGRES_USER: engram + POSTGRES_PASSWORD: engram_dev + POSTGRES_DB: engram_cloud + ports: + - "127.0.0.1:5433:5432" + healthcheck: + test: ["CMD-SHELL", "pg_isready -U engram -d engram_cloud"] + interval: 5s + timeout: 3s + retries: 10 + volumes: + - engram-cloud-pg:/var/lib/postgresql/data + cloud: + restart: always + build: + context: . + dockerfile: docker/cloud/Dockerfile + container_name: engram-cloud + depends_on: + postgres: + condition: service_healthy + environment: + ENGRAM_DATABASE_URL: postgres://engram:engram_dev@postgres:5432/engram_cloud?sslmode=disable + ENGRAM_JWT_SECRET: "e5ace1caed605543642c1032ef9e24f803f092b4ef9863cc068a8eceaa01445b" + ENGRAM_CLOUD_TOKEN: "e5ace1caed605543642c1032ef9e24f803f092b4ef9863cc068a8eceaa01445b" + ENGRAM_CLOUD_ALLOWED_PROJECTS: smoke-project,planificacion_proyectos,gestion-talleres-2000 + ENGRAM_CLOUD_HOST: 0.0.0.0 + ENGRAM_PORT: "18080" + ports: + - "127.0.0.1:18080:18080" + command: ["cloud", "serve"] +volumes: + engram-cloud-pg: +``` + +--- + +## Si el VPS se cae o necesitas reinstalar + +### 1. Clonar el repo y arrancar + +```bash +cd /opt +sudo git clone https://github.com/Gentleman-Programming/engram +cd /opt/engram +``` + +Sobreescribe el docker-compose con la configuración segura: + +```bash +cat > /opt/engram/docker-compose.cloud.yml << 'EOF' +# pega aquí el contenido del bloque de arriba +EOF +``` + +Arranca: + +```bash +docker compose -f docker-compose.cloud.yml up -d +``` + +### 2. Conectar a la red de Nginx Proxy Manager + +```bash +docker network connect nginx-proxy-manager_default engram-cloud +``` + +--- + +## Si necesitas regenerar el token + +En el VPS genera uno nuevo: + +```bash +openssl rand -hex 32 +``` + +Actualiza `ENGRAM_JWT_SECRET` y `ENGRAM_CLOUD_TOKEN` en el docker-compose y reinicia: + +```bash +docker compose -f docker-compose.cloud.yml up -d --force-recreate cloud +``` + +--- + +## Acceso al dashboard + +- URL: `https://engram.v-encore-lab.com/dashboard/` +- Campo **Cloud Token:** pega el `ENGRAM_CLOUD_TOKEN` +- Sin el token nadie puede acceder a los datos + +--- + +## Verificar que el servidor está seguro + +```bash +docker logs engram-cloud --tail 10 +``` + +✅ Correcto — debe mostrar solo: +``` +Starting Engram cloud server on port 18080 +[engram-cloud] listening on 0.0.0.0:18080 +``` + +❌ Inseguro — si aparece esta línea hay que eliminarla del docker-compose: +``` +warning: ENGRAM_CLOUD_INSECURE_NO_AUTH=1 disables cloud API authentication +``` + +--- + +## Nginx Proxy Manager — Configuración del proxy host + +| Campo | Valor | +|---|---| +| Domain | `engram.v-encore-lab.com` | +| Scheme | `http` | +| Forward Hostname | `engram-cloud` | +| Forward Port | `18080` | +| SSL | Let's Encrypt | +| Force SSL | | \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..2603bd5 --- /dev/null +++ b/README.md @@ -0,0 +1,58 @@ +# Engram Wiki + +Documentación de configuración, instalación y gestión de Engram. + +--- + +## Índice + +1. **[01-setup-maquina-nueva.md](01-setup-maquina-nueva.md)** — Instalar Engram en un PC nuevo +2. **[02-nuevo-proyecto-cloud.md](02-nuevo-proyecto-cloud.md)** — Añadir proyectos al cloud +3. **[03-seguridad-cloud.md](03-seguridad-cloud.md)** — Configuración de seguridad VPS + +--- + +## Proyectos sincronizados + +- `planificacion_proyectos` +- `gestion-talleres-2000` + +--- + +## Tokens + +- **Cloud Token:** `e5ace1caed605543642c1032ef9e24f803f092b4ef9863cc068a8eceaa01445b` +- **Gitea Token:** `187130f38d937b03f19e1aea1afccb9e3e3ec01d` + +--- + +## URLs + +- **Gitea:** `https://git.v-encore-lab.com/` +- **Engram Cloud:** `https://engram.v-encore-lab.com` +- **Dashboard:** `https://engram.v-encore-lab.com/dashboard/` + +--- + +## Comandos útiles + +```powershell +# Ver estado +cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN && engram cloud status" + +# Sincronizar +cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN && engram sync --cloud --project NOMBRE_PROYECTO" + +# Buscar memorias +engram search "texto a buscar" + +# Ver contexto +mem_context +``` + +--- + +## SQLite (para solves legacy) + +- Ubicación: `C:\Users\juanm\Downloads\sqlite3.exe` +- DB: `C:\Users\juanm\.engram\engram.db` \ No newline at end of file