Saltar a contenido

Instalación pip (índice privado)

Guía para instalar Cortex y plugins desde wheels en Cloudsmith o dist/wheels/, sin clonar el monorepo completo.

Cada plugin también tiene repositorio Git propio (cortex-ia-com-co/cortex-plugin-*); pip instala el wheel empaquetado, no el submódulo. Ver Repositorios y submódulos.

Requisitos

  • Python 3.12+
  • PostgreSQL 16 y Redis 7 (producción)
  • Acceso al índice privado o directorio dist/wheels/

Construir wheels (monorepo)

Requiere submódulos inicializados (git submodule update --init --recursive).

./deploy/build-wheels.sh

Genera wheels en dist/wheels/ para cortex, cortex-core, cortex-framework y todos los plugins del workspace.

Publicación al registry privado:

./scripts/publish-cloudsmith.sh

Índice por defecto: https://npm.cloudsmith.io/cortex-u044/cortex-hive/ (npm) y Python en el repo Cloudsmith cortex-u044/cortex-hive.

Instalar plataforma mínima

python -m venv .venv
source .venv/bin/activate
pip install --find-links dist/wheels "cortex[operations-core]"

Activar plugins

Producción (SaaS)

La instalación pip registra plugins en el catálogo; no los activa para negocio.

En un despliegue SaaS el tenant no tiene acceso a variables de entorno de activación. Configura solo infraestructura:

export CORTEX_DATABASE_URL=postgresql+asyncpg://...
export CORTEX_REDIS_URL=redis://...
# No definir CORTEX_ENABLED_PLUGINS ni CORTEX_ENABLED_PANELS
cortex-api

Flujo operativo:

  1. pip install del extra o plugin → aparece en GET /api/v1/control/plugins como instalado, enabled: false.
  2. Superadmin (scope sudo) entra a /control/plugins y activa los módulos contratados.
  3. El estado persiste en PostgreSQL (platform_plugin_state).
  4. Los namespaces de panel (operations, admin, …) emergen cuando plugins habilitados inyectan módulos con ese panel_id.
  5. Si hace falta recargar código no presente en el boot, la API responde requiresRestart: true.

Builtins: template y el panel control están siempre disponibles.

Índice privado (Cloudsmith)

pip install --index-url https://pypi.cloudsmith.io/cortex-u044/cortex-hive/simple/ \
  --extra-index-url https://pypi.org/simple \
  "cortex[operations-core]"

También puedes servir dist/wheels/ con un servidor estático interno:

pip install --find-links dist/wheels "cortex[operations-core]"

Bundle profiles

Extra pip Contenido
operations-core panel, booking, clients, resources
operations-full operations-core + discounts, events
admin-finance admin, payments, pricing, sales, billing
all todos los plugins first-party

Los extras definen qué wheels se instalan, no qué queda activo en runtime (eso lo decide /control en SaaS).

Verificación

curl http://localhost:8000/api/v1/health
curl http://localhost:8000/api/v1/control/plugins
curl http://localhost:8000/api/v1/panels/routes

Referencias