diff --git a/content/ca/sysadmins.md b/content/ca/sysadmins.md new file mode 100644 index 0000000..1e55b28 --- /dev/null +++ b/content/ca/sysadmins.md @@ -0,0 +1,410 @@ +--- +title: "Per a Administradors de Sistemes" +description: "Guies d'instal·lació i manteniment de LAMB" +date: 2026-05-07 +draft: false +weight: 200 +--- + +# Per a Administradors de Sistemes + +## Guia d'Instal·lació amb Docker + +Docker és el mètode recomanat per desplegar LAMB en entorns de producció. Aquesta guia us acompanyarà en el procés d'instal·lació i configuració de LAMB utilitzant contenidors Docker. + +### 1. Configuració del Fitxer de Variables d'Entorn + +El primer pas consisteix a crear un fitxer `.env` al directori arrel de la vostra instal·lació. Aquest fitxer contindrà totes les variables de configuració necessàries per al funcionament de LAMB. A continuació es mostra un exemple amb la configuració per defecte que podeu adaptar al vostre entorn: + +``` +# LAMB Next Docker Compose Environment Configuration +# Copy this file to .env (same directory as docker-compose.next.yaml). +# +# Current phase policy: +# - Required vars are UNCOMMENTED below (must be set). +# - Optional vars are COMMENTED and can be enabled only if needed. + +# ============================================================================ +# REQUIRED VARIABLES (compose fails if missing) +# ============================================================================ + +# Public/internal LAMB URLs +LAMB_WEB_HOST=http://localhost:9099 +LAMB_BACKEND_HOST=http://localhost:9099 + +# Database/data paths inside container +OWI_PATH=/data/openwebui + +# OpenWebUI internal API URL +OWI_BASE_URL=http://openwebui:8080 + +# Auth/secrets required by current backend config +LAMB_BEARER_TOKEN=change-me +SIGNUP_SECRET_KEY=change-me + +# OpenAI provider required by current backend config +OPENAI_BASE_URL=https://api.openai.com/v1 +OPENAI_MODEL=gpt-4o-mini + +# OpenWebUI bootstrap admin required by current backend config +OWI_ADMIN_NAME=Admin User +OWI_ADMIN_EMAIL=admin@owi.com +OWI_ADMIN_PASSWORD=admin + +# ============================================================================ +# OPTIONAL VARIABLES (uncomment to override defaults) +# ============================================================================ + +# Ports +# LAMB_PORT=9099 +# KB_PORT=9090 +# OPENWEBUI_PORT=8080 + +# OpenWebUI public/browser URL +# OWI_PUBLIC_BASE_URL=http://localhost:8080 + +# DB table prefix (defaults to LAMB_) +# Set empty for unprefixed schemas: LAMB_DB_PREFIX= +# LAMB_DB_PREFIX=LAMB_ + +# DB path override (defaults to /data/lamb) +# LAMB_DB_PATH=/data/lamb + +# Additional tokens/keys +# LAMB_KB_SERVER_TOKEN=change-me +# LAMB_API_KEY=change-me +# OPENAI_API_KEY= + +# LAMB/KB integration +# LAMB_KB_SERVER=http://kb:9090 +# KB_HOME_URL=http://localhost:9090 + +# KB embeddings +# EMBEDDINGS_MODEL=nomic-embed-text +# EMBEDDINGS_VENDOR=ollama +# EMBEDDINGS_ENDPOINT=http://ollama:11434 +# EMBEDDINGS_APIKEY= + +# KB optional Firecrawl integration +# FIRECRAWL_API_URL=http://host.docker.internal:3002 +# FIRECRAWL_API_KEY= + +# OpenAI model listing +# OPENAI_MODELS=gpt-4o-mini,gpt-4o + +# Ollama +# OLLAMA_BASE_URL=http://ollama:11434 +# OLLAMA_MODEL=nomic-embed-text +# EMBEDDINGS_ENDPOINT=http://ollama:11434 + +# Frontend runtime config (generated at container startup) +# LAMB_FRONTEND_BUILD_PATH=/app/frontend/build +# LAMB_FRONTEND_BASE_URL=/creator +# LAMB_FRONTEND_LAMB_SERVER= +# LAMB_FRONTEND_OPENWEBUI_SERVER= +# LAMB_ENABLE_OPENWEBUI=true +# LAMB_ENABLE_DEBUG=false + +# Feature/runtime toggles +# SIGNUP_ENABLED=true +# LTI_SECRET=change-me +# DEV_MODE=false +# GLOBAL_LOG_LEVEL=WARNING + +# OpenWebUI trusted headers/role/secret +# WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email +# WEBUI_AUTH_TRUSTED_NAME_HEADER=X-User-Name +# DEFAULT_USER_ROLE=user +# WEBUI_SECRET_KEY= + +# Production Caddy overlay (docker-compose.next.prod.yaml) +# CADDY_EMAIL=admin@yourdomain.com +# LAMB_PUBLIC_HOST=lamb.yourdomain.com +# OWI_PUBLIC_HOST=owi.lamb.yourdomain.com +``` + +### 2. Configuració de Docker Compose + +Creeu un fitxer `docker-compose.yml` al mateix directori on es troba el fitxer `.env`. Aquest fitxer defineix els serveis que componen l'arquitectura de LAMB: + +```yaml +services: + lamb: + image: ghcr.io/lamb-project/lamb:latest + build: + context: . + dockerfile: backend/Dockerfile + restart: unless-stopped + environment: + PORT: ${LAMB_PORT:-9099} + OWI_BASE_URL: ${OWI_BASE_URL?Set OWI_BASE_URL} + OWI_PATH: ${OWI_PATH?Set OWI_PATH} + LAMB_KB_SERVER: ${LAMB_KB_SERVER:-http://kb:9090} + LAMB_BACKEND_HOST: ${LAMB_BACKEND_HOST?Set LAMB_BACKEND_HOST} + LAMB_WEB_HOST: ${LAMB_WEB_HOST?Set LAMB_WEB_HOST} + LAMB_BEARER_TOKEN: ${LAMB_BEARER_TOKEN?Set LAMB_BEARER_TOKEN} + LAMB_KB_SERVER_TOKEN: ${LAMB_KB_SERVER_TOKEN:-0p3n-w3bu!} + OPENAI_API_KEY: ${OPENAI_API_KEY:-} + OPENAI_BASE_URL: ${OPENAI_BASE_URL?Set OPENAI_BASE_URL} + OPENAI_MODEL: ${OPENAI_MODEL?Set OPENAI_MODEL} + OPENAI_MODELS: ${OPENAI_MODELS:-gpt-4o-mini,gpt-4o} + SIGNUP_SECRET_KEY: ${SIGNUP_SECRET_KEY?Set SIGNUP_SECRET_KEY} + LTI_SECRET: ${LTI_SECRET:-lamb-lti-secret-key-2024} + OWI_ADMIN_NAME: ${OWI_ADMIN_NAME?Set OWI_ADMIN_NAME} + OWI_ADMIN_EMAIL: ${OWI_ADMIN_EMAIL?Set OWI_ADMIN_EMAIL} + OWI_ADMIN_PASSWORD: ${OWI_ADMIN_PASSWORD?Set OWI_ADMIN_PASSWORD} + ports: + - "9099:9099" + volumes: + - lamb-data:/data/lamb + - openwebui-data:/data/openwebui + depends_on: + kb: + condition: service_started + openwebui: + condition: service_healthy + + kb: + image: ghcr.io/lamb-project/lamb-kb:latest + build: + context: ./lamb-kb-server-stable + dockerfile: Dockerfile + restart: unless-stopped + environment: + PORT: ${KB_PORT:-9090} + HOME_URL: ${KB_HOME_URL:-http://localhost:9090} + LAMB_API_KEY: ${LAMB_API_KEY:-0p3n-w3bu!} + EMBEDDINGS_MODEL: ${EMBEDDINGS_MODEL:-nomic-embed-text} + EMBEDDINGS_VENDOR: ${EMBEDDINGS_VENDOR:-ollama} + EMBEDDINGS_ENDPOINT: ${EMBEDDINGS_ENDPOINT:-http://ollama:11434} + EMBEDDINGS_APIKEY: ${EMBEDDINGS_APIKEY:-} + FIRECRAWL_API_URL: ${FIRECRAWL_API_URL:-http://host.docker.internal:3002} + FIRECRAWL_API_KEY: ${FIRECRAWL_API_KEY:-} + ports: + - "9090:9090" + volumes: + - kb-data:/app/backend/data + - kb-static:/app/backend/static + + openwebui: + image: ghcr.io/lamb-project/openwebui:latest + build: + context: ./open-webui + dockerfile: Dockerfile + restart: unless-stopped + environment: + PORT: ${OPENWEBUI_PORT:-8080} + WEBUI_AUTH_TRUSTED_EMAIL_HEADER: ${WEBUI_AUTH_TRUSTED_EMAIL_HEADER:-X-User-Email} + WEBUI_AUTH_TRUSTED_NAME_HEADER: ${WEBUI_AUTH_TRUSTED_NAME_HEADER:-X-User-Name} + DEFAULT_USER_ROLE: ${DEFAULT_USER_ROLE:-user} + WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY:-} + ports: + - "8080:8080" + volumes: + - openwebui-data:/app/backend/data + healthcheck: + test: ["CMD", "curl", "-sf", "http://localhost:8080/health"] + interval: 10s + timeout: 5s + retries: 12 + start_period: 30s + + ollama: + image: ollama/ollama:latest + profiles: ["ollama"] + restart: unless-stopped + ports: + - "11434:11434" + volumes: + - ollama-data:/root/.ollama + +volumes: + lamb-data: + kb-data: + kb-static: + openwebui-data: + ollama-data: +``` + + +### 3. Iniciar els Serveis + +Un cop configurats els fitxers `.env` i `docker-compose.yml`, executeu la comanda següent per iniciar tots els serveis: + +```bash +docker compose up -d +``` + +Aquesta comanda descarregarà automàticament les imatges de Docker necessàries des del registre de contenidors i aixecarà tots els serveis en segon pla. + +#### Verificació del Desplegament + +Podeu verificar que tots els serveis estan funcionant correctament amb: + +```bash +docker compose ps +``` + +#### Accés a la Plataforma + +Un cop iniciats els serveis, podeu accedir a LAMB amb les credencials següents: + +- **URL**: `http://localhost:9099` (segons el valor de `LAMB_WEB_HOST` al vostre fitxer `.env`) +- **Usuari**: `admin@example.com` (segons el valor de `OWI_ADMIN_EMAIL`) +- **Contrasenya**: `admin` (segons el valor de `OWI_ADMIN_PASSWORD`) + +> **Important**: Per raons de seguretat, es recomana canviar aquestes credencials per defecte després del primer accés. + +### 4. Optimització per a Entorns de Producció + +#### 4.1. Configuració de Proxy Invers + +Per a entorns de producció, és altament recomanable configurar un proxy invers que gestioni les connexions HTTPS i proporcioni funcionalitats addicionals de seguretat i balanceig de càrrega. A continuació es mostra un exemple de configuració utilitzant **Caddy**. + +##### Configuració del Servei Caddy + +Afegiu el servei següent a la vostra configuració de Docker Compose: + +```yaml +services: + caddy: + image: caddy:2.8 + restart: unless-stopped + environment: + CADDY_EMAIL: ${CADDY_EMAIL:-admin@yourdomain.com} + LAMB_PUBLIC_HOST: ${LAMB_PUBLIC_HOST:-lamb.yourdomain.com} + OWI_PUBLIC_HOST: ${OWI_PUBLIC_HOST:-owi.lamb.yourdomain.com} + volumes: + - ./Caddyfile:/etc/caddy/Caddyfile:ro + - caddy-data:/data + - caddy-config:/config + ports: + - "80:80" + - "443:443" + depends_on: + - lamb + - kb + - openwebui + +volumes: + caddy-data: + caddy-config: +``` + +##### Fitxer Caddyfile + +Creeu un fitxer anomenat `Caddyfile` al mateix directori que el vostre `docker-compose.yml` amb el contingut següent: + +```caddyfile +{ + email {$CADDY_EMAIL} +} + +{$LAMB_PUBLIC_HOST} { + encode gzip + + handle /creator/* { + reverse_proxy lamb:9099 + } + + handle /api/* { + reverse_proxy lamb:9099 + } + + handle /lamb/* { + uri strip_prefix /lamb + reverse_proxy lamb:9099 + } + + handle /kb/* { + uri strip_prefix /kb + reverse_proxy kb:9090 + } + + @oldowi path /openwebui/* + handle @oldowi { + redir https://{$OWI_PUBLIC_HOST}{uri} 301 + } + + handle { + reverse_proxy lamb:9099 + } +} + +{$OWI_PUBLIC_HOST} { + encode gzip + reverse_proxy openwebui:8080 +} +``` + +##### Variables d'Entorn Necessàries + +Afegiu les variables següents al vostre fitxer `.env`: + +```bash +# Configuració de Caddy per a producció +CADDY_EMAIL=admin@yourdomain.com +LAMB_PUBLIC_HOST=lamb.yourdomain.com +OWI_PUBLIC_HOST=owi.lamb.yourdomain.com +``` + +##### Integració amb Docker Compose + +Aquesta configuració pot afegir-se directament al fitxer `docker-compose.yml` principal o, preferiblement, separar-se en un fitxer independent anomenat `docker-compose.prod.yml` per mantenir una millor organització entre entorns de desenvolupament i producció. + +Per utilitzar múltiples fitxers de configuració: + +```bash +docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d +``` + +Aquest enfocament permet mantenir la configuració base a `docker-compose.yml` i les extensions específiques de producció a `docker-compose.prod.yml`. + +#### 4.2. Configuració de Workers + +LAMB utilitza **Uvicorn** com a servidor ASGI per executar l'aplicació backend. En entorns de producció amb alta càrrega, és recomanable configurar múltiples processos workers per aprofitar millor els recursos del sistema i millorar el rendiment. + +##### Què són els Workers? + +Els workers són processos independents que poden gestionar peticions de forma concurrent. Cada worker pot processar sol·licituds de forma simultània, cosa que millora significativament la capacitat de resposta sota càrrega. + +##### Configuració mitjançant Variables d'Entorn + +Des de la versió que inclou el PR #362, LAMB suporta la configuració de workers mitjançant la variable d'entorn `LAMB_WORKERS`. Aquesta es pot definir al fitxer `.env`: + +```bash +# Nombre de workers d'Uvicorn (recomanat: 2-4 per a producció) +# LAMB_WORKERS=4 +``` + +##### Comportament + +- **No establert o buit**: S'executa un únic worker (mode desenvolupament, comportament per defecte d'Uvicorn) +- **Valor enter positiu** (ex: `4`): S'executen múltiples workers (mode producció) +- **Valor 0 o invàlid**: S'ignora i s'utilitza el comportament per defecte (un sol worker) + +##### Recomanacions + +| Entorn | Configuració Recomanada | Descripció | +|--------|-------------------------|------------| +| **Desenvolupament** | No establir o `LAMB_WORKERS=1` | Un sol worker facilita la depuració i redueix el consum de recursos | +| **Producció (baixa càrrega)** | `LAMB_WORKERS=2` | Configuració mínima per a producció amb redundància bàsica | +| **Producció (càrrega mitjana)** | `LAMB_WORKERS=4` | Configuració òptima per a la majoria de casos d'ús | +| **Producció (alta càrrega)** | `LAMB_WORKERS=4-8` | Ajustar segons el nombre de nuclis de CPU disponibles | + +##### Exemple de Configuració a `.env` + +```bash +# Per a un servidor amb 4 nuclis en producció +LAMB_WORKERS=4 +``` + +##### Verificació + +Després de configurar els workers, podeu verificar que s'estan utilitzant correctament revisant els logs del contenidor: + +```bash +docker compose logs lamb | grep -i worker +``` + +Hauríeu de veure missatges indicant que Uvicorn ha iniciat amb el nombre especificat de workers. diff --git a/content/en/sysadmins.md b/content/en/sysadmins.md new file mode 100644 index 0000000..278d39c --- /dev/null +++ b/content/en/sysadmins.md @@ -0,0 +1,410 @@ +--- +title: "For System Administrators" +description: "LAMB installation and maintenance guides" +date: 2026-05-07 +draft: false +weight: 200 +--- + +# For System Administrators + +## Docker Installation Guide + +Docker is the recommended method for deploying LAMB in production environments. This guide will walk you through the process of installing and configuring LAMB using Docker containers. + +### 1. Environment Variables Configuration + +The first step is to create a `.env` file in the root directory of your installation. This file will contain all the configuration variables necessary for LAMB to function. Below is an example with default configuration that you can adapt to your environment: + +``` +# LAMB Next Docker Compose Environment Configuration +# Copy this file to .env (same directory as docker-compose.next.yaml). +# +# Current phase policy: +# - Required vars are UNCOMMENTED below (must be set). +# - Optional vars are COMMENTED and can be enabled only if needed. + +# ============================================================================ +# REQUIRED VARIABLES (compose fails if missing) +# ============================================================================ + +# Public/internal LAMB URLs +LAMB_WEB_HOST=http://localhost:9099 +LAMB_BACKEND_HOST=http://localhost:9099 + +# Database/data paths inside container +OWI_PATH=/data/openwebui + +# OpenWebUI internal API URL +OWI_BASE_URL=http://openwebui:8080 + +# Auth/secrets required by current backend config +LAMB_BEARER_TOKEN=change-me +SIGNUP_SECRET_KEY=change-me + +# OpenAI provider required by current backend config +OPENAI_BASE_URL=https://api.openai.com/v1 +OPENAI_MODEL=gpt-4o-mini + +# OpenWebUI bootstrap admin required by current backend config +OWI_ADMIN_NAME=Admin User +OWI_ADMIN_EMAIL=admin@owi.com +OWI_ADMIN_PASSWORD=admin + +# ============================================================================ +# OPTIONAL VARIABLES (uncomment to override defaults) +# ============================================================================ + +# Ports +# LAMB_PORT=9099 +# KB_PORT=9090 +# OPENWEBUI_PORT=8080 + +# OpenWebUI public/browser URL +# OWI_PUBLIC_BASE_URL=http://localhost:8080 + +# DB table prefix (defaults to LAMB_) +# Set empty for unprefixed schemas: LAMB_DB_PREFIX= +# LAMB_DB_PREFIX=LAMB_ + +# DB path override (defaults to /data/lamb) +# LAMB_DB_PATH=/data/lamb + +# Additional tokens/keys +# LAMB_KB_SERVER_TOKEN=change-me +# LAMB_API_KEY=change-me +# OPENAI_API_KEY= + +# LAMB/KB integration +# LAMB_KB_SERVER=http://kb:9090 +# KB_HOME_URL=http://localhost:9090 + +# KB embeddings +# EMBEDDINGS_MODEL=nomic-embed-text +# EMBEDDINGS_VENDOR=ollama +# EMBEDDINGS_ENDPOINT=http://ollama:11434 +# EMBEDDINGS_APIKEY= + +# KB optional Firecrawl integration +# FIRECRAWL_API_URL=http://host.docker.internal:3002 +# FIRECRAWL_API_KEY= + +# OpenAI model listing +# OPENAI_MODELS=gpt-4o-mini,gpt-4o + +# Ollama +# OLLAMA_BASE_URL=http://ollama:11434 +# OLLAMA_MODEL=nomic-embed-text +# EMBEDDINGS_ENDPOINT=http://ollama:11434 + +# Frontend runtime config (generated at container startup) +# LAMB_FRONTEND_BUILD_PATH=/app/frontend/build +# LAMB_FRONTEND_BASE_URL=/creator +# LAMB_FRONTEND_LAMB_SERVER= +# LAMB_FRONTEND_OPENWEBUI_SERVER= +# LAMB_ENABLE_OPENWEBUI=true +# LAMB_ENABLE_DEBUG=false + +# Feature/runtime toggles +# SIGNUP_ENABLED=true +# LTI_SECRET=change-me +# DEV_MODE=false +# GLOBAL_LOG_LEVEL=WARNING + +# OpenWebUI trusted headers/role/secret +# WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email +# WEBUI_AUTH_TRUSTED_NAME_HEADER=X-User-Name +# DEFAULT_USER_ROLE=user +# WEBUI_SECRET_KEY= + +# Production Caddy overlay (docker-compose.next.prod.yaml) +# CADDY_EMAIL=admin@yourdomain.com +# LAMB_PUBLIC_HOST=lamb.yourdomain.com +# OWI_PUBLIC_HOST=owi.lamb.yourdomain.com +``` + +### 2. Docker Compose Configuration + +Create a `docker-compose.yml` file in the same directory where the `.env` file is located. This file defines the services that make up LAMB's architecture: + +```yaml +services: + lamb: + image: ghcr.io/lamb-project/lamb:latest + build: + context: . + dockerfile: backend/Dockerfile + restart: unless-stopped + environment: + PORT: ${LAMB_PORT:-9099} + OWI_BASE_URL: ${OWI_BASE_URL?Set OWI_BASE_URL} + OWI_PATH: ${OWI_PATH?Set OWI_PATH} + LAMB_KB_SERVER: ${LAMB_KB_SERVER:-http://kb:9090} + LAMB_BACKEND_HOST: ${LAMB_BACKEND_HOST?Set LAMB_BACKEND_HOST} + LAMB_WEB_HOST: ${LAMB_WEB_HOST?Set LAMB_WEB_HOST} + LAMB_BEARER_TOKEN: ${LAMB_BEARER_TOKEN?Set LAMB_BEARER_TOKEN} + LAMB_KB_SERVER_TOKEN: ${LAMB_KB_SERVER_TOKEN:-0p3n-w3bu!} + OPENAI_API_KEY: ${OPENAI_API_KEY:-} + OPENAI_BASE_URL: ${OPENAI_BASE_URL?Set OPENAI_BASE_URL} + OPENAI_MODEL: ${OPENAI_MODEL?Set OPENAI_MODEL} + OPENAI_MODELS: ${OPENAI_MODELS:-gpt-4o-mini,gpt-4o} + SIGNUP_SECRET_KEY: ${SIGNUP_SECRET_KEY?Set SIGNUP_SECRET_KEY} + LTI_SECRET: ${LTI_SECRET:-lamb-lti-secret-key-2024} + OWI_ADMIN_NAME: ${OWI_ADMIN_NAME?Set OWI_ADMIN_NAME} + OWI_ADMIN_EMAIL: ${OWI_ADMIN_EMAIL?Set OWI_ADMIN_EMAIL} + OWI_ADMIN_PASSWORD: ${OWI_ADMIN_PASSWORD?Set OWI_ADMIN_PASSWORD} + ports: + - "9099:9099" + volumes: + - lamb-data:/data/lamb + - openwebui-data:/data/openwebui + depends_on: + kb: + condition: service_started + openwebui: + condition: service_healthy + + kb: + image: ghcr.io/lamb-project/lamb-kb:latest + build: + context: ./lamb-kb-server-stable + dockerfile: Dockerfile + restart: unless-stopped + environment: + PORT: ${KB_PORT:-9090} + HOME_URL: ${KB_HOME_URL:-http://localhost:9090} + LAMB_API_KEY: ${LAMB_API_KEY:-0p3n-w3bu!} + EMBEDDINGS_MODEL: ${EMBEDDINGS_MODEL:-nomic-embed-text} + EMBEDDINGS_VENDOR: ${EMBEDDINGS_VENDOR:-ollama} + EMBEDDINGS_ENDPOINT: ${EMBEDDINGS_ENDPOINT:-http://ollama:11434} + EMBEDDINGS_APIKEY: ${EMBEDDINGS_APIKEY:-} + FIRECRAWL_API_URL: ${FIRECRAWL_API_URL:-http://host.docker.internal:3002} + FIRECRAWL_API_KEY: ${FIRECRAWL_API_KEY:-} + ports: + - "9090:9090" + volumes: + - kb-data:/app/backend/data + - kb-static:/app/backend/static + + openwebui: + image: ghcr.io/lamb-project/openwebui:latest + build: + context: ./open-webui + dockerfile: Dockerfile + restart: unless-stopped + environment: + PORT: ${OPENWEBUI_PORT:-8080} + WEBUI_AUTH_TRUSTED_EMAIL_HEADER: ${WEBUI_AUTH_TRUSTED_EMAIL_HEADER:-X-User-Email} + WEBUI_AUTH_TRUSTED_NAME_HEADER: ${WEBUI_AUTH_TRUSTED_NAME_HEADER:-X-User-Name} + DEFAULT_USER_ROLE: ${DEFAULT_USER_ROLE:-user} + WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY:-} + ports: + - "8080:8080" + volumes: + - openwebui-data:/app/backend/data + healthcheck: + test: ["CMD", "curl", "-sf", "http://localhost:8080/health"] + interval: 10s + timeout: 5s + retries: 12 + start_period: 30s + + ollama: + image: ollama/ollama:latest + profiles: ["ollama"] + restart: unless-stopped + ports: + - "11434:11434" + volumes: + - ollama-data:/root/.ollama + +volumes: + lamb-data: + kb-data: + kb-static: + openwebui-data: + ollama-data: +``` + + +### 3. Starting the Services + +Once the `.env` and `docker-compose.yml` files are configured, run the following command to start all services: + +```bash +docker compose up -d +``` + +This command will automatically download the necessary Docker images from the container registry and start all services in the background. + +#### Deployment Verification + +You can verify that all services are running correctly with: + +```bash +docker compose ps +``` + +#### Platform Access + +Once the services are started, you can access LAMB with the following credentials: + +- **URL**: `http://localhost:9099` (according to the `LAMB_WEB_HOST` value in your `.env` file) +- **Username**: `admin@example.com` (according to the `OWI_ADMIN_EMAIL` value) +- **Password**: `admin` (according to the `OWI_ADMIN_PASSWORD` value) + +> **Important**: For security reasons, it is recommended to change these default credentials after the first login. + +### 4. Production Environment Optimization + +#### 4.1. Reverse Proxy Configuration + +For production environments, it is highly recommended to configure a reverse proxy that manages HTTPS connections and provides additional security and load balancing features. Below is an example configuration using **Caddy**. + +##### Caddy Service Configuration + +Add the following service to your Docker Compose configuration: + +```yaml +services: + caddy: + image: caddy:2.8 + restart: unless-stopped + environment: + CADDY_EMAIL: ${CADDY_EMAIL:-admin@yourdomain.com} + LAMB_PUBLIC_HOST: ${LAMB_PUBLIC_HOST:-lamb.yourdomain.com} + OWI_PUBLIC_HOST: ${OWI_PUBLIC_HOST:-owi.lamb.yourdomain.com} + volumes: + - ./Caddyfile:/etc/caddy/Caddyfile:ro + - caddy-data:/data + - caddy-config:/config + ports: + - "80:80" + - "443:443" + depends_on: + - lamb + - kb + - openwebui + +volumes: + caddy-data: + caddy-config: +``` + +##### Caddyfile + +Create a file named `Caddyfile` in the same directory as your `docker-compose.yml` with the following content: + +```caddyfile +{ + email {$CADDY_EMAIL} +} + +{$LAMB_PUBLIC_HOST} { + encode gzip + + handle /creator/* { + reverse_proxy lamb:9099 + } + + handle /api/* { + reverse_proxy lamb:9099 + } + + handle /lamb/* { + uri strip_prefix /lamb + reverse_proxy lamb:9099 + } + + handle /kb/* { + uri strip_prefix /kb + reverse_proxy kb:9090 + } + + @oldowi path /openwebui/* + handle @oldowi { + redir https://{$OWI_PUBLIC_HOST}{uri} 301 + } + + handle { + reverse_proxy lamb:9099 + } +} + +{$OWI_PUBLIC_HOST} { + encode gzip + reverse_proxy openwebui:8080 +} +``` + +##### Required Environment Variables + +Add the following variables to your `.env` file: + +```bash +# Caddy configuration for production +CADDY_EMAIL=admin@yourdomain.com +LAMB_PUBLIC_HOST=lamb.yourdomain.com +OWI_PUBLIC_HOST=owi.lamb.yourdomain.com +``` + +##### Docker Compose Integration + +This configuration can be added directly to the main `docker-compose.yml` file or, preferably, separated into an independent file called `docker-compose.prod.yml` to maintain better organization between development and production environments. + +To use multiple configuration files: + +```bash +docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d +``` + +This approach allows you to keep the base configuration in `docker-compose.yml` and production-specific extensions in `docker-compose.prod.yml`. + +#### 4.2. Workers Configuration + +LAMB uses **Uvicorn** as an ASGI server to run the backend application. In production environments with high load, it is recommended to configure multiple worker processes to better utilize system resources and improve performance. + +##### What are Workers? + +Workers are independent processes that can handle requests concurrently. Each worker can process requests simultaneously, which significantly improves response capacity under load. + +##### Configuration via Environment Variables + +Since the version including PR #362, LAMB supports worker configuration through the `LAMB_WORKERS` environment variable. This can be defined in the `.env` file: + +```bash +# Number of Uvicorn workers (recommended: 2-4 for production) +# LAMB_WORKERS=4 +``` + +##### Behavior + +- **Not set or empty**: A single worker runs (development mode, Uvicorn default behavior) +- **Positive integer value** (e.g., `4`): Multiple workers run (production mode) +- **Value 0 or invalid**: Ignored and default behavior is used (single worker) + +##### Recommendations + +| Environment | Recommended Configuration | Description | +|-------------|---------------------------|-------------| +| **Development** | Not set or `LAMB_WORKERS=1` | Single worker facilitates debugging and reduces resource consumption | +| **Production (low load)** | `LAMB_WORKERS=2` | Minimum configuration for production with basic redundancy | +| **Production (medium load)** | `LAMB_WORKERS=4` | Optimal configuration for most use cases | +| **Production (high load)** | `LAMB_WORKERS=4-8` | Adjust according to available CPU cores | + +##### Configuration Example in `.env` + +```bash +# For a server with 4 cores in production +LAMB_WORKERS=4 +``` + +##### Verification + +After configuring workers, you can verify they are being used correctly by checking the container logs: + +```bash +docker compose logs lamb | grep -i worker +``` + +You should see messages indicating that Uvicorn has started with the specified number of workers. diff --git a/content/es/sysadmins.md b/content/es/sysadmins.md new file mode 100644 index 0000000..60d24a8 --- /dev/null +++ b/content/es/sysadmins.md @@ -0,0 +1,410 @@ +--- +title: "Para Sysadmins" +description: "Guías de instalación y mantenimiento de LAMB" +date: 2026-05-07 +draft: false +weight: 200 +--- + +# Para Administradores de Sistemas + +## Guía de Instalación con Docker + +Docker es el método recomendado para desplegar LAMB en entornos de producción. Esta guía le acompañará en el proceso de instalación y configuración de LAMB utilizando contenedores Docker. + +### 1. Configuración del Archivo de Variables de Entorno + +El primer paso consiste en crear un archivo `.env` en el directorio raíz de su instalación. Este archivo contendrá todas las variables de configuración necesarias para el funcionamiento de LAMB. A continuación se muestra un ejemplo con la configuración por defecto que puede adaptar a su entorno: + +``` +# LAMB Next Docker Compose Environment Configuration +# Copy this file to .env (same directory as docker-compose.next.yaml). +# +# Current phase policy: +# - Required vars are UNCOMMENTED below (must be set). +# - Optional vars are COMMENTED and can be enabled only if needed. + +# ============================================================================ +# REQUIRED VARIABLES (compose fails if missing) +# ============================================================================ + +# Public/internal LAMB URLs +LAMB_WEB_HOST=http://localhost:9099 +LAMB_BACKEND_HOST=http://localhost:9099 + +# Database/data paths inside container +OWI_PATH=/data/openwebui + +# OpenWebUI internal API URL +OWI_BASE_URL=http://openwebui:8080 + +# Auth/secrets required by current backend config +LAMB_BEARER_TOKEN=change-me +SIGNUP_SECRET_KEY=change-me + +# OpenAI provider required by current backend config +OPENAI_BASE_URL=https://api.openai.com/v1 +OPENAI_MODEL=gpt-4o-mini + +# OpenWebUI bootstrap admin required by current backend config +OWI_ADMIN_NAME=Admin User +OWI_ADMIN_EMAIL=admin@owi.com +OWI_ADMIN_PASSWORD=admin + +# ============================================================================ +# OPTIONAL VARIABLES (uncomment to override defaults) +# ============================================================================ + +# Ports +# LAMB_PORT=9099 +# KB_PORT=9090 +# OPENWEBUI_PORT=8080 + +# OpenWebUI public/browser URL +# OWI_PUBLIC_BASE_URL=http://localhost:8080 + +# DB table prefix (defaults to LAMB_) +# Set empty for unprefixed schemas: LAMB_DB_PREFIX= +# LAMB_DB_PREFIX=LAMB_ + +# DB path override (defaults to /data/lamb) +# LAMB_DB_PATH=/data/lamb + +# Additional tokens/keys +# LAMB_KB_SERVER_TOKEN=change-me +# LAMB_API_KEY=change-me +# OPENAI_API_KEY= + +# LAMB/KB integration +# LAMB_KB_SERVER=http://kb:9090 +# KB_HOME_URL=http://localhost:9090 + +# KB embeddings +# EMBEDDINGS_MODEL=nomic-embed-text +# EMBEDDINGS_VENDOR=ollama +# EMBEDDINGS_ENDPOINT=http://ollama:11434 +# EMBEDDINGS_APIKEY= + +# KB optional Firecrawl integration +# FIRECRAWL_API_URL=http://host.docker.internal:3002 +# FIRECRAWL_API_KEY= + +# OpenAI model listing +# OPENAI_MODELS=gpt-4o-mini,gpt-4o + +# Ollama +# OLLAMA_BASE_URL=http://ollama:11434 +# OLLAMA_MODEL=nomic-embed-text +# EMBEDDINGS_ENDPOINT=http://ollama:11434 + +# Frontend runtime config (generated at container startup) +# LAMB_FRONTEND_BUILD_PATH=/app/frontend/build +# LAMB_FRONTEND_BASE_URL=/creator +# LAMB_FRONTEND_LAMB_SERVER= +# LAMB_FRONTEND_OPENWEBUI_SERVER= +# LAMB_ENABLE_OPENWEBUI=true +# LAMB_ENABLE_DEBUG=false + +# Feature/runtime toggles +# SIGNUP_ENABLED=true +# LTI_SECRET=change-me +# DEV_MODE=false +# GLOBAL_LOG_LEVEL=WARNING + +# OpenWebUI trusted headers/role/secret +# WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email +# WEBUI_AUTH_TRUSTED_NAME_HEADER=X-User-Name +# DEFAULT_USER_ROLE=user +# WEBUI_SECRET_KEY= + +# Production Caddy overlay (docker-compose.next.prod.yaml) +# CADDY_EMAIL=admin@yourdomain.com +# LAMB_PUBLIC_HOST=lamb.yourdomain.com +# OWI_PUBLIC_HOST=owi.lamb.yourdomain.com +``` + +### 2. Configuración de Docker Compose + +Cree un archivo `docker-compose.yml` en el mismo directorio donde se encuentra el archivo `.env`. Este archivo define los servicios que componen la arquitectura de LAMB: + +```yaml +services: + lamb: + image: ghcr.io/lamb-project/lamb:latest + build: + context: . + dockerfile: backend/Dockerfile + restart: unless-stopped + environment: + PORT: ${LAMB_PORT:-9099} + OWI_BASE_URL: ${OWI_BASE_URL?Set OWI_BASE_URL} + OWI_PATH: ${OWI_PATH?Set OWI_PATH} + LAMB_KB_SERVER: ${LAMB_KB_SERVER:-http://kb:9090} + LAMB_BACKEND_HOST: ${LAMB_BACKEND_HOST?Set LAMB_BACKEND_HOST} + LAMB_WEB_HOST: ${LAMB_WEB_HOST?Set LAMB_WEB_HOST} + LAMB_BEARER_TOKEN: ${LAMB_BEARER_TOKEN?Set LAMB_BEARER_TOKEN} + LAMB_KB_SERVER_TOKEN: ${LAMB_KB_SERVER_TOKEN:-0p3n-w3bu!} + OPENAI_API_KEY: ${OPENAI_API_KEY:-} + OPENAI_BASE_URL: ${OPENAI_BASE_URL?Set OPENAI_BASE_URL} + OPENAI_MODEL: ${OPENAI_MODEL?Set OPENAI_MODEL} + OPENAI_MODELS: ${OPENAI_MODELS:-gpt-4o-mini,gpt-4o} + SIGNUP_SECRET_KEY: ${SIGNUP_SECRET_KEY?Set SIGNUP_SECRET_KEY} + LTI_SECRET: ${LTI_SECRET:-lamb-lti-secret-key-2024} + OWI_ADMIN_NAME: ${OWI_ADMIN_NAME?Set OWI_ADMIN_NAME} + OWI_ADMIN_EMAIL: ${OWI_ADMIN_EMAIL?Set OWI_ADMIN_EMAIL} + OWI_ADMIN_PASSWORD: ${OWI_ADMIN_PASSWORD?Set OWI_ADMIN_PASSWORD} + ports: + - "9099:9099" + volumes: + - lamb-data:/data/lamb + - openwebui-data:/data/openwebui + depends_on: + kb: + condition: service_started + openwebui: + condition: service_healthy + + kb: + image: ghcr.io/lamb-project/lamb-kb:latest + build: + context: ./lamb-kb-server-stable + dockerfile: Dockerfile + restart: unless-stopped + environment: + PORT: ${KB_PORT:-9090} + HOME_URL: ${KB_HOME_URL:-http://localhost:9090} + LAMB_API_KEY: ${LAMB_API_KEY:-0p3n-w3bu!} + EMBEDDINGS_MODEL: ${EMBEDDINGS_MODEL:-nomic-embed-text} + EMBEDDINGS_VENDOR: ${EMBEDDINGS_VENDOR:-ollama} + EMBEDDINGS_ENDPOINT: ${EMBEDDINGS_ENDPOINT:-http://ollama:11434} + EMBEDDINGS_APIKEY: ${EMBEDDINGS_APIKEY:-} + FIRECRAWL_API_URL: ${FIRECRAWL_API_URL:-http://host.docker.internal:3002} + FIRECRAWL_API_KEY: ${FIRECRAWL_API_KEY:-} + ports: + - "9090:9090" + volumes: + - kb-data:/app/backend/data + - kb-static:/app/backend/static + + openwebui: + image: ghcr.io/lamb-project/openwebui:latest + build: + context: ./open-webui + dockerfile: Dockerfile + restart: unless-stopped + environment: + PORT: ${OPENWEBUI_PORT:-8080} + WEBUI_AUTH_TRUSTED_EMAIL_HEADER: ${WEBUI_AUTH_TRUSTED_EMAIL_HEADER:-X-User-Email} + WEBUI_AUTH_TRUSTED_NAME_HEADER: ${WEBUI_AUTH_TRUSTED_NAME_HEADER:-X-User-Name} + DEFAULT_USER_ROLE: ${DEFAULT_USER_ROLE:-user} + WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY:-} + ports: + - "8080:8080" + volumes: + - openwebui-data:/app/backend/data + healthcheck: + test: ["CMD", "curl", "-sf", "http://localhost:8080/health"] + interval: 10s + timeout: 5s + retries: 12 + start_period: 30s + + ollama: + image: ollama/ollama:latest + profiles: ["ollama"] + restart: unless-stopped + ports: + - "11434:11434" + volumes: + - ollama-data:/root/.ollama + +volumes: + lamb-data: + kb-data: + kb-static: + openwebui-data: + ollama-data: +``` + + +### 3. Iniciar los Servicios + +Una vez configurados los archivos `.env` y `docker-compose.yml`, ejecute el siguiente comando para iniciar todos los servicios: + +```bash +docker compose up -d +``` + +Este comando descargará automáticamente las imágenes de Docker necesarias desde el registro de contenedores y levantará todos los servicios en segundo plano. + +#### Verificación del Despliegue + +Puede verificar que todos los servicios están funcionando correctamente con: + +```bash +docker compose ps +``` + +#### Acceso a la Plataforma + +Una vez iniciados los servicios, puede acceder a LAMB con las siguientes credenciales: + +- **URL**: `http://localhost:9099` (según el valor de `LAMB_WEB_HOST` en su archivo `.env`) +- **Usuario**: `admin@example.com` (según el valor de `OWI_ADMIN_EMAIL`) +- **Contraseña**: `admin` (según el valor de `OWI_ADMIN_PASSWORD`) + +> **Importante**: Por razones de seguridad, se recomienda cambiar estas credenciales por defecto tras el primer acceso. + +### 4. Optimización para Entornos de Producción + +#### 4.1. Configuración de Proxy Reverso + +Para entornos de producción, es altamente recomendable configurar un proxy reverso que gestione las conexiones HTTPS y proporcione funcionalidades adicionales de seguridad y balanceo de carga. A continuación se muestra un ejemplo de configuración utilizando **Caddy**. + +##### Configuración del Servicio Caddy + +Añada el siguiente servicio a su configuración de Docker Compose: + +```yaml +services: + caddy: + image: caddy:2.8 + restart: unless-stopped + environment: + CADDY_EMAIL: ${CADDY_EMAIL:-admin@yourdomain.com} + LAMB_PUBLIC_HOST: ${LAMB_PUBLIC_HOST:-lamb.yourdomain.com} + OWI_PUBLIC_HOST: ${OWI_PUBLIC_HOST:-owi.lamb.yourdomain.com} + volumes: + - ./Caddyfile:/etc/caddy/Caddyfile:ro + - caddy-data:/data + - caddy-config:/config + ports: + - "80:80" + - "443:443" + depends_on: + - lamb + - kb + - openwebui + +volumes: + caddy-data: + caddy-config: +``` + +##### Archivo Caddyfile + +Cree un archivo llamado `Caddyfile` en el mismo directorio que su `docker-compose.yml` con el siguiente contenido: + +```caddyfile +{ + email {$CADDY_EMAIL} +} + +{$LAMB_PUBLIC_HOST} { + encode gzip + + handle /creator/* { + reverse_proxy lamb:9099 + } + + handle /api/* { + reverse_proxy lamb:9099 + } + + handle /lamb/* { + uri strip_prefix /lamb + reverse_proxy lamb:9099 + } + + handle /kb/* { + uri strip_prefix /kb + reverse_proxy kb:9090 + } + + @oldowi path /openwebui/* + handle @oldowi { + redir https://{$OWI_PUBLIC_HOST}{uri} 301 + } + + handle { + reverse_proxy lamb:9099 + } +} + +{$OWI_PUBLIC_HOST} { + encode gzip + reverse_proxy openwebui:8080 +} +``` + +##### Variables de Entorno Necesarias + +Añada las siguientes variables a su archivo `.env`: + +```bash +# Configuración de Caddy para producción +CADDY_EMAIL=admin@yourdomain.com +LAMB_PUBLIC_HOST=lamb.yourdomain.com +OWI_PUBLIC_HOST=owi.lamb.yourdomain.com +``` + +##### Integración con Docker Compose + +Esta configuración puede añadirse directamente al archivo `docker-compose.yml` principal o, preferiblemente, separarse en un archivo independiente llamado `docker-compose.prod.yml` para mantener una mejor organización entre entornos de desarrollo y producción. + +Para utilizar múltiples archivos de configuración: + +```bash +docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d +``` + +Este enfoque permite mantener la configuración base en `docker-compose.yml` y las extensiones específicas de producción en `docker-compose.prod.yml`. + +#### 4.2. Configuración de Workers + +LAMB utiliza **Uvicorn** como servidor ASGI para ejecutar la aplicación backend. En entornos de producción con alta carga, es recomendable configurar múltiples procesos workers para aprovechar mejor los recursos del sistema y mejorar el rendimiento. + +##### ¿Qué son los Workers? + +Los workers son procesos independientes que pueden manejar peticiones de forma concurrente. Cada worker puede procesar solicitudes de forma simultánea, lo que mejora significativamente la capacidad de respuesta bajo carga. + +##### Configuración mediante Variables de Entorno + +Desde la versión que incluye el PR #362, LAMB soporta la configuración de workers mediante la variable de entorno `LAMB_WORKERS`. Esta puede definirse en el archivo `.env`: + +```bash +# Número de workers de Uvicorn (recomendado: 2-4 para producción) +# LAMB_WORKERS=4 +``` + +##### Comportamiento + +- **No establecido o vacío**: Se ejecuta un único worker (modo desarrollo, comportamiento por defecto de Uvicorn) +- **Valor entero positivo** (ej: `4`): Se ejecutan múltiples workers (modo producción) +- **Valor 0 o inválido**: Se ignora y se utiliza el comportamiento por defecto (un solo worker) + +##### Recomendaciones + +| Entorno | Configuración Recomendada | Descripción | +|---------|---------------------------|-------------| +| **Desarrollo** | No establecer o `LAMB_WORKERS=1` | Un solo worker facilita la depuración y reduce el consumo de recursos | +| **Producción (baja carga)** | `LAMB_WORKERS=2` | Configuración mínima para producción con redundancia básica | +| **Producción (carga media)** | `LAMB_WORKERS=4` | Configuración óptima para la mayoría de casos de uso | +| **Producción (alta carga)** | `LAMB_WORKERS=4-8` | Ajustar según el número de núcleos de CPU disponibles | + +##### Ejemplo de Configuración en `.env` + +```bash +# Para un servidor con 4 núcleos en producción +LAMB_WORKERS=4 +``` + +##### Verificación + +Después de configurar los workers, puede verificar que se están utilizando correctamente revisando los logs del contenedor: + +```bash +docker compose logs lamb | grep -i worker +``` + +Deberá ver mensajes indicando que Uvicorn ha iniciado con el número especificado de workers. diff --git a/content/eu/sysadmins.md b/content/eu/sysadmins.md new file mode 100644 index 0000000..8054e0a --- /dev/null +++ b/content/eu/sysadmins.md @@ -0,0 +1,428 @@ +--- +title: "Sistemaren Administratzaileentzat" +description: "LAMB instalazio eta mantentze gidak" +date: 2026-05-07 +draft: false +weight: 200 +--- + +# Sistemaren Administratzaileentzat + +## Docker Instalazio Gida + +Docker da LAMB produkzio inguruneetan hedatzeko gomendatutako metodoa. Gida honek Docker edukiontziak erabiliz LAMB instalatu eta konfiguratzeko prozesuan zehar lagunduko zaitu. + +### 1. Ingurune Aldagaien Fitxategiaren Konfigurazioa + +Lehenengo urratsa zure instalazioaren erroko direktorioan `.env` fitxategi bat sortzea da. Fitxategi honek LAMBen funtzionatzeko behar diren konfigurazio aldagai guztiak edukiko ditu. Jarraian, zure ingurunera egokitu dezakezun lehenetsitako konfigurazioarekin adibide bat erakusten da: + +``` +# LAMB Next Docker Compose Environment Configuration +# Copy this file to .env (same directory as docker-compose.next.yaml). +# +# Current phase policy: +# - Required vars are UNCOMMENTED below (must be set). +# - Optional vars are COMMENTED and can be enabled only if needed. + +# ============================================================================ +# REQUIRED VARIABLES (compose fails if missing) +# ============================================================================ + +# Public/internal LAMB URLs +LAMB_WEB_HOST=http://localhost:9099 +LAMB_BACKEND_HOST=http://localhost:9099 + +# Database/data paths inside container +OWI_PATH=/data/openwebui + +# OpenWebUI internal API URL +OWI_BASE_URL=http://openwebui:8080 + +# Auth/secrets required by current backend config +LAMB_BEARER_TOKEN=change-me +SIGNUP_SECRET_KEY=change-me + +# OpenAI provider required by current backend config +OPENAI_BASE_URL=https://api.openai.com/v1 +OPENAI_MODEL=gpt-4o-mini + +# OpenWebUI bootstrap admin required by current backend config +OWI_ADMIN_NAME=Admin User +OWI_ADMIN_EMAIL=admin@owi.com +OWI_ADMIN_PASSWORD=admin + +# ============================================================================ +# OPTIONAL VARIABLES (uncomment to override defaults) +# ============================================================================ + +# Ports +# LAMB_PORT=9099 +# KB_PORT=9090 +# OPENWEBUI_PORT=8080 + +# OpenWebUI public/browser URL +# OWI_PUBLIC_BASE_URL=http://localhost:8080 + +# DB table prefix (defaults to LAMB_) +# Set empty for unprefixed schemas: LAMB_DB_PREFIX= +# LAMB_DB_PREFIX=LAMB_ + +# DB path override (defaults to /data/lamb) +# LAMB_DB_PATH=/data/lamb + +# Additional tokens/keys +# LAMB_KB_SERVER_TOKEN=change-me +# LAMB_API_KEY=change-me +# OPENAI_API_KEY= + +# LAMB/KB integration +# LAMB_KB_SERVER=http://kb:9090 +# KB_HOME_URL=http://localhost:9090 + +# KB embeddings +# EMBEDDINGS_MODEL=nomic-embed-text +# EMBEDDINGS_VENDOR=ollama +# EMBEDDINGS_ENDPOINT=http://ollama:11434 +# EMBEDDINGS_APIKEY= + +# KB optional Firecrawl integration +# FIRECRAWL_API_URL=http://host.docker.internal:3002 +# FIRECRAWL_API_KEY= + +# OpenAI model listing +# OPENAI_MODELS=gpt-4o-mini,gpt-4o + +# Ollama +# OLLAMA_BASE_URL=http://ollama:11434 +# OLLAMA_MODEL=nomic-embed-text +# EMBEDDINGS_ENDPOINT=http://ollama:11434 + +# Frontend runtime config (generated at container startup) +# LAMB_FRONTEND_BUILD_PATH=/app/frontend/build +# LAMB_FRONTEND_BASE_URL=/creator +# LAMB_FRONTEND_LAMB_SERVER= +# LAMB_FRONTEND_OPENWEBUI_SERVER= +# LAMB_ENABLE_OPENWEBUI=true +# LAMB_ENABLE_DEBUG=false + +# Feature/runtime toggles +# SIGNUP_ENABLED=true +# LTI_SECRET=change-me +# DEV_MODE=false +# GLOBAL_LOG_LEVEL=WARNING + +# OpenWebUI trusted headers/role/secret +# WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email +# WEBUI_AUTH_TRUSTED_NAME_HEADER=X-User-Name +# DEFAULT_USER_ROLE=user +# WEBUI_SECRET_KEY= + +# Production Caddy overlay (docker-compose.next.prod.yaml) +# CADDY_EMAIL=admin@yourdomain.com +# LAMB_PUBLIC_HOST=lamb.yourdomain.com +# OWI_PUBLIC_HOST=owi.lamb.yourdomain.com +``` + +### 2. Docker Compose Konfigurazioa + +Sortu `docker-compose.yml` fitxategi bat `.env` fitxategia dagoen direktorio berean. Fitxategi honek LAMBen arkitektura osatzen duten zerbitzuak definitzen ditu: + +```yaml +services: + lamb: + image: ghcr.io/lamb-project/lamb:latest + build: + context: . + dockerfile: backend/Dockerfile + restart: unless-stopped + environment: + PORT: ${LAMB_PORT:-9099} + OWI_BASE_URL: ${OWI_BASE_URL?Set OWI_BASE_URL} + OWI_PATH: ${OWI_PATH?Set OWI_PATH} + LAMB_KB_SERVER: ${LAMB_KB_SERVER:-http://kb:9090} + LAMB_BACKEND_HOST: ${LAMB_BACKEND_HOST?Set LAMB_BACKEND_HOST} + LAMB_WEB_HOST: ${LAMB_WEB_HOST?Set LAMB_WEB_HOST} + LAMB_BEARER_TOKEN: ${LAMB_BEARER_TOKEN?Set LAMB_BEARER_TOKEN} + LAMB_KB_SERVER_TOKEN: ${LAMB_KB_SERVER_TOKEN:-0p3n-w3bu!} + OPENAI_API_KEY: ${OPENAI_API_KEY:-} + OPENAI_BASE_URL: ${OPENAI_BASE_URL?Set OPENAI_BASE_URL} + OPENAI_MODEL: ${OPENAI_MODEL?Set OPENAI_MODEL} + OPENAI_MODELS: ${OPENAI_MODELS:-gpt-4o-mini,gpt-4o} + SIGNUP_SECRET_KEY: ${SIGNUP_SECRET_KEY?Set SIGNUP_SECRET_KEY} + LTI_SECRET: ${LTI_SECRET:-lamb-lti-secret-key-2024} + OWI_ADMIN_NAME: ${OWI_ADMIN_NAME?Set OWI_ADMIN_NAME} + OWI_ADMIN_EMAIL: ${OWI_ADMIN_EMAIL?Set OWI_ADMIN_EMAIL} + OWI_ADMIN_PASSWORD: ${OWI_ADMIN_PASSWORD?Set OWI_ADMIN_PASSWORD} + ports: + - "9099:9099" + volumes: + - lamb-data:/data/lamb + - openwebui-data:/data/openwebui + depends_on: + kb: + condition: service_started + openwebui: + condition: service_healthy + + kb: + image: ghcr.io/lamb-project/lamb-kb:latest + build: + context: ./lamb-kb-server-stable + dockerfile: Dockerfile + restart: unless-stopped + environment: + PORT: ${KB_PORT:-9090} + HOME_URL: ${KB_HOME_URL:-http://localhost:9090} + LAMB_API_KEY: ${LAMB_API_KEY:-0p3n-w3bu!} + EMBEDDINGS_MODEL: ${EMBEDDINGS_MODEL:-nomic-embed-text} + EMBEDDINGS_VENDOR: ${EMBEDDINGS_VENDOR:-ollama} + EMBEDDINGS_ENDPOINT: ${EMBEDDINGS_ENDPOINT:-http://ollama:11434} + EMBEDDINGS_APIKEY: ${EMBEDDINGS_APIKEY:-} + FIRECRAWL_API_URL: ${FIRECRAWL_API_URL:-http://host.docker.internal:3002} + FIRECRAWL_API_KEY: ${FIRECRAWL_API_KEY:-} + ports: + - "9090:9090" + volumes: + - kb-data:/app/backend/data + - kb-static:/app/backend/static + + openwebui: + image: ghcr.io/lamb-project/openwebui:latest + build: + context: ./open-webui + dockerfile: Dockerfile + restart: unless-stopped + environment: + PORT: ${OPENWEBUI_PORT:-8080} + WEBUI_AUTH_TRUSTED_EMAIL_HEADER: ${WEBUI_AUTH_TRUSTED_EMAIL_HEADER:-X-User-Email} + WEBUI_AUTH_TRUSTED_NAME_HEADER: ${WEBUI_AUTH_TRUSTED_NAME_HEADER:-X-User-Name} + DEFAULT_USER_ROLE: ${DEFAULT_USER_ROLE:-user} + WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY:-} + ports: + - "8080:8080" + volumes: + - openwebui-data:/app/backend/data + healthcheck: + test: ["CMD", "curl", "-sf", "http://localhost:8080/health"] + interval: 10s + timeout: 5s + retries: 12 + start_period: 30s + + ollama: + image: ollama/ollama:latest + profiles: ["ollama"] + restart: unless-stopped + ports: + - "11434:11434" + volumes: + - ollama-data:/root/.ollama + +volumes: + lamb-data: + kb-data: + kb-static: + openwebui-data: + ollama-data: +``` + + +### 3. Zerbitzuak Abiarazi + +`.env` eta `docker-compose.yml` fitxategiak konfiguratu ondoren, exekutatu komando hau zerbitzu guztiak abiarazteko: + +```bash +docker compose up -d +``` + +Komando honek automatikoki deskargatuko ditu beharrezko Docker irudiak edukiontzien erregistrotik eta zerbitzu guztiak atzeko planoan abiaraziko ditu. + +#### Hedapenaren Egiaztapena + +Zerbitzu guztiak behar bezala funtzionatzen ari direla egiaztatu dezakezu honekin: + +```bash +docker compose ps +``` + +#### Plataformarako Sarbidea + +Zerbitzuak abiarazi ondoren, LAMBera sarbide hauek erabiliz sartu zaitezke: + +- **URLa**: `http://localhost:9099` (zure `.env` fitxategiko `LAMB_WEB_HOST` balioaren arabera) +- **Erabiltzailea**: `admin@example.com` (`OWI_ADMIN_EMAIL` balioaren arabera) +- **Pasahitza**: `admin` (`OWI_ADMIN_PASSWORD` balioaren arabera) + +> **Garrantzitsua**: Segurtasun arrazoiengatik, gomendagarria da lehenetsitako kredentzial hauek lehen sarbidearen ondoren aldatzea. + +### 4. Produkzio Inguruneetarako Optimizazioa + +#### 4.1. Alderantzizko Proxy Konfigurazioa + +Produkzio inguruneetan, oso gomendagarria da HTTPS konexioak kudeatzen dituen alderantzizko proxy bat konfiguratzea eta segurtasun eta karga orekatzeko funtzionalitate gehigarriak eskaintzea. Jarraian **Caddy** erabiliz konfigurazio adibide bat erakusten da. + +##### Caddy Zerbitzuaren Konfigurazioa + +Gehitu zerbitzu hau zure Docker Compose konfiguraziora: + +```yaml +services: + caddy: + image: caddy:2.8 + restart: unless-stopped + environment: + CADDY_EMAIL: ${CADDY_EMAIL:-admin@yourdomain.com} + LAMB_PUBLIC_HOST: ${LAMB_PUBLIC_HOST:-lamb.yourdomain.com} + OWI_PUBLIC_HOST: ${OWI_PUBLIC_HOST:-owi.lamb.yourdomain.com} + volumes: + - ./Caddyfile:/etc/caddy/Caddyfile:ro + - caddy-data:/data + - caddy-config:/config + ports: + - "80:80" + - "443:443" + depends_on: + - lamb + - kb + - openwebui + +volumes: + caddy-data: + caddy-config: +``` + +##### Caddyfile Fitxategia + +Sortu `Caddyfile` izeneko fitxategi bat zure `docker-compose.yml`ekin direktorio berean eduki honekin: + +```caddyfile +{ + email {$CADDY_EMAIL} +} + +{$LAMB_PUBLIC_HOST} { + encode gzip + + handle /creator/* { + reverse_proxy lamb:9099 + } + + handle /api/* { + reverse_proxy lamb:9099 + } + + handle /lamb/* { + uri strip_prefix /lamb + reverse_proxy lamb:9099 + } + + handle /kb/* { + uri strip_prefix /kb + reverse_proxy kb:9090 + } + + @oldowi path /openwebui/* + handle @oldowi { + redir https://{$OWI_PUBLIC_HOST}{uri} 301 + } + + handle { + reverse_proxy lamb:9099 + } +} + +{$OWI_PUBLIC_HOST} { + encode gzip + reverse_proxy openwebui:8080 +} +``` + +##### Konfigurazioaren Azalpena + +**Bloke Globala:** +- `email {$CADDY_EMAIL}`: Helbide elektronikoa SSL/TLS ziurtagiri automatikoak Let's Encrypt bidez emateko + +**LAMBen Ostalari Nagusia (`{$LAMB_PUBLIC_HOST}`):** +- `encode gzip`: Erantzunen konpresioa errendimenduaren hobekuntza +- `/creator/*`: Laguntzaileen sortzailearen interfazea → LAMB zerbitzua +- `/api/*`: Backend APIa → LAMB zerbitzua +- `/lamb/*`: LAMBen bide espezifikoak (aurrizkia kenduta) +- `/kb/*`: Ezagutza Basea (aurrizkia kenduta) → KB zerbitzua +- `/openwebui/*`: 301 birbideraketa OpenWebUIren ostalari espezifikora (atzerantz bateragarritasunerako) +- Gainerako bideak: Proxy LAMB zerbitzu nagusira + +**OpenWebUI Ostalarira (`{$OWI_PUBLIC_HOST}`):** +- OpenWebUIrako konfigurazio dedikatua gzip konpresioarekin +- Eskaera guztiak `openwebui:8080` zerbitzura bidaltzen dira + +##### Beharrezko Ingurune Aldagaiak + +Gehitu aldagai hauek zure `.env` fitxategian: + +```bash +# Caddyren konfigurazioa produkziorako +CADDY_EMAIL=admin@yourdomain.com +LAMB_PUBLIC_HOST=lamb.yourdomain.com +OWI_PUBLIC_HOST=owi.lamb.yourdomain.com +``` + +##### Docker Compose Integrazioa + +Konfigurazio hau zuzenean `docker-compose.yml` fitxategi nagusian gehitu daiteke edo, nahiago bada, `docker-compose.prod.yml` izeneko fitxategi independente batean banatu garapen eta produkzio inguruneen artean antolakuntza hobea mantentzeko. + +Konfigurazio fitxategi anitz erabiltzeko: + +```bash +docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d +``` + +Ikuspegi honek oinarrizko konfigurazioa `docker-compose.yml`n mantentzeko eta produkzio-hedapen espezifikoak `docker-compose.prod.yml`n mantentzeko aukera ematen du. + +#### 4.2. Worker-en Konfigurazioa + +LAMBek **Uvicorn** erabiltzen du ASGI zerbitzari gisa backend aplikazioa exekutatzeko. Karga handiko produkzio inguruneetan, gomendagarria da worker prozesu anitzak konfiguratzea sistemaren baliabideak hobeto aprobetxatu eta errendimendua hobetzeko. + +##### Zer dira Worker-ak? + +Worker-ak eskaerak aldi berean kudeatu ditzaketen prozesu independenteak dira. Worker bakoitzak eskaerak aldi berean prozesatu ditzake, eta honek kargapeko erantzun gaitasuna nabarmen hobetzen du. + +##### Ingurune Aldagaien bidezko Konfigurazioa + +PR #362 barne hartzen duen bertsiotik aurrera, LAMBek worker-en konfigurazioa onartzen du `LAMB_WORKERS` ingurune aldagaiaren bidez. Hau `.env` fitxategian definitu daiteke: + +```bash +# Uvicorn worker-en kopurua (gomendatua: 2-4 produkziorako) +# LAMB_WORKERS=4 +``` + +##### Portaera + +- **Ezarri gabe edo hutsa**: Worker bakarra exekutatzen da (garapen modua, Uvicornen lehenetsitako portaera) +- **Balio oso positiboa** (adib: `4`): Worker anitz exekutatzen dira (produkzio modua) +- **0 balioa edo baliogabea**: Ez ikusi egiten da eta lehenetsitako portaera erabiltzen da (worker bakarra) + +##### Gomendioak + +| Ingurunea | Gomendatutako Konfigurazioa | Deskribapena | +|-----------|----------------------------|--------------| +| **Garapena** | Ez ezarri edo `LAMB_WORKERS=1` | Worker bakarrak arazketa errazten du eta baliabideen kontsumoa murrizten du | +| **Produkzioa (karga txikia)** | `LAMB_WORKERS=2` | Produkziorako gutxieneko konfigurazioa oinarrizko erredundantziarekin | +| **Produkzioa (karga ertaina)** | `LAMB_WORKERS=4` | Erabilera kasu gehienetarako konfigurazio optimoa | +| **Produkzioa (karga handia)** | `LAMB_WORKERS=4-8` | Eskuragarri dauden CPU nukleoaren arabera doitu | + +##### Konfigurazio Adibidea `.env`-n + +```bash +# 4 nukleoko zerbitzari baterako produkzioan +LAMB_WORKERS=4 +``` + +##### Egiaztapena + +Worker-ak konfiguratu ondoren, behar bezala erabiltzen ari direla egiaztatu dezakezu edukiontziko log-ak berrikusten: + +```bash +docker compose logs lamb | grep -i worker +``` + +Uvicornek zehaztutako worker kopuruarekin hasi duela adierazten duten mezuak ikusi beharko zenituzke.