Mastra @ poeticsoft — Documentación de despliegue

Este documento describe la arquitectura, configuración y operación del entorno Mastra multi-app alojado en /home/mastra, expuesto públicamente vía el subdominio mastra.poeticsoft.com.

Regla de mantenimiento: Tras cualquier cambio de infraestructura (nginx, systemd, puertos, servicios compartidos, RAG/Chroma, workspaces, nuevas apps), actualizar DOC.md y regenerar la documentación web con:

/home/mastra/scripts/build-doc-html.sh

Resumen

Estructura de directorios

/home/mastra/
├── DOC.md                      ← documentación (fuente de verdad)
├── package.json                ← monorepo npm workspaces
├── scripts/
│   ├── build-doc-html.sh       ← regenera www/doc/index.html
│   └── test-rag.ts             ← smoke test RAG por app
├── shared/
│   └── chroma/                 ← @poeticsoft/mastra-chroma (compartido)
│       ├── package.json
│       └── src/
│           ├── config.ts         # host, port, embeddings
│           ├── client.ts         # createChromaVector()
│           ├── ingest.ts         # ingestDocuments()
│           └── index.ts
├── www/
│   ├── index.html              ← landing (índice de apps)
│   ├── doc/
│   │   └── index.html            ← doc HTML pública (/doc/)
│   └── chroma/
│       └── index.html            ← panel ChromaDB (/chroma/)
└── mastra-a/                   ← app Mastra
    ├── .env
    ├── docs/                   ← corpus RAG de esta app
    ├── scripts/
    │   └── ingest-docs.ts      ← ingest → Chroma
    ├── src/mastra/
    │   ├── index.ts
    │   ├── agents/
    │   ├── tools/
    │   └── vectors/chroma.ts   # enlace a shared + index propio
    └── .mastra/output/         ← build de producción

Cada app Mastra tiene su propio package.json, .env, build y colección Chroma propia. La infra compartida (ChromaDB, módulo @poeticsoft/mastra-chroma, nginx, documentación) vive en la raíz /home/mastra.

Arquitectura

flowchart LR
    user[Usuario] --> nginx["nginx\nmastra.poeticsoft.com"]
    nginx --> root["GET /\n→ www/index.html"]
    nginx --> doc["GET /doc/\n→ www/doc/"]
    nginx --> chromaPanel["GET /chroma/\n→ panel RAG"]
    chromaPanel --> chroma["ChromaDB :8000"]
    nginx --> appA["GET /a/\n→ :4111"]
    appA --> mastraA["mastra-a.service"]
    mastraA --> chroma["ChromaDB :8000\nmastra-a"]
    mastraA --> libsql["LibSQL\nmemoria/threads"]
    mastraA --> duckdb["DuckDB\nobservability"]

Enrutamiento por rutas

Convención de puertos

Monorepo (npm workspaces)

Archivo: /home/mastra/package.json

{
  "workspaces": ["shared/chroma", "mastra-a"]
}

Instalar dependencias desde la raíz:

cd /home/mastra && npm install

Las apps importan el módulo compartido sin paths relativos:

import { createChromaVector, chromaIndexName, CHROMA_PROMPT } from '@poeticsoft/mastra-chroma';

Al añadir mastra-b, incluirla en workspaces y añadir "@poeticsoft/mastra-chroma": "*" en su package.json.

ChromaDB (compartido)

Servidor vectorial usado por RAG de todas las apps.

systemctl status chromadb
curl http://127.0.0.1:8000/api/v2/heartbeat

Módulo compartido @poeticsoft/mastra-chroma

Documentación del módulo: /home/mastra/shared/chroma/README.md

Ollama (embeddings RAG)

Embeddings locales para ingest y consultas vectoriales (sin cuota en la nube).

systemctl status ollama
ollama list
curl http://127.0.0.1:11434/api/tags

Variables en .env de cada app: OLLAMA_HOST, OLLAMA_PORT, EMBEDDING_MODEL, EMBEDDING_DIMENSIONS.

Panel web ChromaDB

Supervisión de colecciones y chunks indexados (solo lectura):

• URL: https://mastra.poeticsoft.com/chroma/
• Archivo: /home/mastra/www/chroma/index.html
• API proxy nginx: /chroma/api/ → http://127.0.0.1:8000/api/v2/ (GET/POST)

Muestra: estado del servidor, colecciones, conteo de vectores, source/path y vista previa de cada chunk.

App: mastra-a

Origen

Template "Agent Harness":

npx create-mastra@latest mastra-a --llm google --no-git --no-skills

Incluye agente con workspace, memoria, schedules, observabilidad (LibSQL + DuckDB) y RAG vía Chroma.

Storage (roles)

Variables de entorno

Archivo: /home/mastra/mastra-a/.env

GOOGLE_GENERATIVE_AI_API_KEY=<clave-google>
PORT=4111
CHROMA_HOST=127.0.0.1
CHROMA_PORT=8000
CHROMA_INDEX_NAME=mastra-a

RAG (proyecto)

• Colección Chroma: mastra-a — conocimiento del proyecto (no infra del servidor)
• Corpus: mastra-a/docs/ — añade .md/.txt del producto; npm run ingest cuando esté listo
• Estado actual: colección mastra-a creada vacía (sin vectores)
• Tool: search_knowledge_base
• Ingest:

cd /home/mastra/mastra-a && npm run ingest

• Test:

node --experimental-strip-types /home/mastra/scripts/test-rag.ts mastra-a "tu consulta"

Scripts npm

cd /home/mastra/mastra-a

npm run dev      # desarrollo (Studio en localhost:4111)
npm run build    # compila a .mastra/output/
npm run start    # servidor de producción
npm run ingest   # reindexar documentos en Chroma

Despliegue tras cambios

cd /home/mastra && npm install          # si cambió shared/ o workspaces
cd /home/mastra/mastra-a && npm run build
sudo systemctl restart mastra-a
/home/mastra/scripts/build-doc-html.sh  # si cambió infra → actualizar doc web

Servicio systemd

Archivo: /etc/systemd/system/mastra-a.service

[Unit]
Description=Mastra app mastra-a
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/home/mastra/mastra-a
EnvironmentFile=/home/mastra/mastra-a/.env
ExecStart=/usr/bin/node .mastra/output/index.mjs
Restart=always
RestartSec=5
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

sudo systemctl status mastra-a
sudo systemctl restart mastra-a
sudo journalctl -u mastra-a -f

Nginx

Archivo: /etc/nginx/sites-available/mastra.poeticsoft.com

SSL: Let's Encrypt en /etc/letsencrypt/live/mastra.poeticsoft.com/

sudo nginx -t && sudo systemctl reload nginx

Documentación web

Regenerar tras editar DOC.md:

/home/mastra/scripts/build-doc-html.sh

Checklist: cambio de infraestructura

1. Aplicar el cambio (nginx, systemd, shared/, nueva app, etc.)
2. Verificar servicios (systemctl status, curl health checks)
3. Actualizar DOC.md (este archivo)
4. Ejecutar /home/mastra/scripts/build-doc-html.sh
5. Si aplica: actualizar www/index.html y www/chroma/ (landing / panel)

Añadir una nueva app (plantilla)

1. Crear proyecto y registrar en monorepo

cd /home/mastra
npx create-mastra@latest mastra-b --llm google --no-git --no-skills

Añadir "mastra-b" a workspaces en /home/mastra/package.json.

En mastra-b/package.json:

"@poeticsoft/mastra-chroma": "*"

cd /home/mastra && npm install

2. Configurar entorno, puerto y RAG (opcional)

# mastra-b/.env
GOOGLE_GENERATIVE_AI_API_KEY=<clave>
PORT=4112
CHROMA_INDEX_NAME=mastra-b
CHROMA_HOST=127.0.0.1
CHROMA_PORT=8000

src/mastra/vectors/chroma.ts:

import { createChromaVector, chromaIndexName } from '@poeticsoft/mastra-chroma';

export const chromaVector = createChromaVector('chroma');
export const CHROMA_INDEX_NAME = chromaIndexName('mastra-b');

3. Build, systemd, nginx

cd /home/mastra/mastra-b && npm run build
# Crear mastra-b.service (copiar mastra-a.service)
# Añadir location /b/ en nginx
sudo nginx -t && sudo systemctl reload nginx

4. Actualizar documentación y landing

• Editar DOC.md
• /home/mastra/scripts/build-doc-html.sh
• Enlace en www/index.html

Verificación

# Apps
curl http://127.0.0.1:4111/health
curl https://mastra.poeticsoft.com/a/health

# ChromaDB
curl http://127.0.0.1:8000/api/v2/heartbeat
systemctl status chromadb

# RAG
node --experimental-strip-types /home/mastra/scripts/test-rag.ts mastra-a "nginx poeticsoft"

# Documentación
curl -s https://mastra.poeticsoft.com/doc/ | head -5

Requisitos del sistema

• Node.js ≥ 22.13.0
• nginx + SSL (certbot)
• systemd
• ChromaDB (chromadb.service)

Referencias

• Mastra — Quickstart
• Mastra — RAG retrieval
• Mastra — Chroma vector store
• Mastra — Deploy server

Última actualización: agosto 2026