Build Command
El campo Build Command en Configuración Avanzada te permite controlar exactamente cómo se prepara tu aplicación antes de iniciarse. Su comportamiento varía según el runtime.
Dónde encontrarlo
El Build Command está en la sección Configuración Avanzada del Step 2 del wizard de deploy. También puedes editarlo desde la configuración de la app.
Comportamiento por runtime
Node.js
| Situación | Qué ejecuta Kubiy |
|---|---|
| Build Command vacío | npm ci --omit=dev |
| Build Command con valor | Tu comando (reemplaza npm ci) |
El Build Command reemplaza completamente la instalación automática. Si tu comando no instala dependencias, las dependencias no estarán disponibles.
# Instalar deps y luego compilar TypeScript
npm ci && npm run build
# Con yarn
yarn install --frozen-lockfile && yarn build
# Solo producción (equivalente al default)
npm ci --omit=dev
# Con pnpm
pnpm install --frozen-lockfile && pnpm build
Python
| Situación | Qué ejecuta Kubiy |
|---|---|
| Build Command vacío | pip install -r requirements.txt |
| Build Command con valor | Tu comando (reemplaza el pip install) |
El Build Command reemplaza la instalación automática de requirements.txt. Sin embargo, gunicorn y uvicorn siempre se instalan en el virtualenv, independientemente del Build Command.
# Instalar desde un archivo alternativo
pip install -r requirements/prod.txt
# Múltiples archivos
pip install -r requirements.txt -r requirements-optional.txt
# Con upgrade de pip primero (recomendado si hay problemas de compatibilidad)
pip install --upgrade pip && pip install -r requirements.txt
# Sin cache (si tienes problemas con versiones cacheadas)
pip install --no-cache-dir -r requirements.txt
Go
| Situación | Qué ejecuta Kubiy |
|---|---|
| Build Command vacío | go build -o kubiy-app . |
| Build Command con valor | Tu comando (reemplaza el go build) |
El Build Command reemplaza el build por defecto. Eres responsable de producir el binario ./kubiy-app en la raíz del proyecto.
# Compilar desde un subdirectorio cmd/
go build -o kubiy-app ./cmd/server
# Con flags de optimización
go build -ldflags="-s -w" -o kubiy-app .
# Con CGO deshabilitado
CGO_ENABLED=0 go build -o kubiy-app .
# Con version embedding
go build -ldflags="-X main.version=1.0.0 -X main.buildTime=$(date -u '+%Y-%m-%dT%H:%M:%SZ')" -o kubiy-app .
# Build del módulo específico en monorepo
go build -o kubiy-app ./services/api
Si el Build Command no produce un archivo llamado kubiy-app en la raíz del proyecto, el deploy fallará al intentar iniciar la aplicación.
.NET
| Situación | Qué ejecuta Kubiy |
|---|---|
| Build Command vacío | dotnet publish (automático) |
| Build Command con valor | Tu comando antes de dotnet publish |
En .NET, el Build Command es un pre-build hook: se ejecuta antes del dotnet publish. El publish siempre se ejecuta después. Esto es diferente al comportamiento de otros runtimes.
# Restaurar herramientas globales de .NET
dotnet tool restore
# Generar código con EF Core antes del publish
dotnet ef migrations bundle
# Instalar dependencias de npm para un proyecto con assets frontend
npm ci && npm run build:assets
# Ejecutar un script de preparación
./scripts/pre-build.sh
Casos de uso avanzados
Monorepo con múltiples proyectos
Si tu repositorio tiene varios proyectos y el build de tu app depende de otros:
Node.js con workspaces:
# Instalar desde la raíz del monorepo y compilar el paquete específico
npm ci && npm run build --workspace=packages/api
Con subdirectorio configurado:
Si configuras Subdirectorio: apps/api, el Build Command se ejecuta en ese directorio. Si necesitas acceder a la raíz del monorepo, usa rutas relativas o absolutas.
Proyectos con assets frontend
Next.js con variables de entorno de build:
npm ci && NEXT_PUBLIC_API_URL=$API_URL npm run build
SvelteKit:
npm ci && npm run build
Nuxt:
npm ci && npx nuxt build
Proyectos con generación de código
Prisma (ORM para Node.js):
npm ci && npx prisma generate && npm run build
GraphQL Code Generator:
npm ci && npm run codegen && npm run build
OpenAPI Generator (.NET):
# En el Build Command (pre-build hook de .NET)
dotnet tool restore && dotnet openapi generate
Optimizaciones de build
Node.js — cache de dependencias con npm ci:
npm ci ya usa el cache de npm de forma eficiente. Para proyectos con muchas dependencias, considera usar pnpm:
npm install -g pnpm && pnpm install --frozen-lockfile && pnpm build
Python — compilar paquetes nativos:
pip install --upgrade pip setuptools wheel && pip install -r requirements.txt
Go — descarga de módulos con caché:
Go descarga módulos automáticamente durante go build. La primera vez puede ser lenta; deploys subsecuentes son más rápidos gracias al cache de módulos en el servidor.
Validación antes del build
Puedes agregar validaciones al inicio del Build Command:
# Node.js — verificar que el package-lock.json existe
[ -f package-lock.json ] && npm ci || { echo "ERROR: package-lock.json no encontrado"; exit 1; }
# Python — verificar que requirements.txt existe
[ -f requirements.txt ] && pip install -r requirements.txt || { echo "ERROR: requirements.txt no encontrado"; exit 1; }
Scripts externos
Si tienes un script de build en tu repositorio:
# Node.js
chmod +x ./scripts/build.sh && ./scripts/build.sh
# Python
bash scripts/build.sh
# Go
bash scripts/build.sh && go build -o kubiy-app .
Errores comunes
"command not found" en el Build Command
La herramienta que intentas usar no está disponible en el servidor. Opciones:
- Instala la herramienta como parte del build:
npm install -g <tool> && <tool> build
- Usa las herramientas disponibles para cada runtime (npm, pip, go, dotnet están disponibles)
Node.js: la app no encuentra módulos instalados
Tu Build Command no instaló las dependencias, o las instaló en un directorio incorrecto. Asegúrate de que el Build Command incluye npm ci o npm install.
Go: el deploy inicia pero la app falla inmediatamente
El binario kubiy-app no está en la raíz del proyecto, o no es ejecutable. Verifica que el Build Command produce ./kubiy-app correctamente.
Python: módulos instalados pero no disponibles
El Build Command puede haber instalado módulos fuera del virtualenv. Si usas un script externo que activa un entorno virtual diferente, los módulos pueden no estar disponibles cuando la app inicie. Usa pip install directamente sin activar virtualenvs adicionales.
.NET: el Build Command falla pero el publish tendría que funcionar
Recuerda que en .NET el Build Command es un pre-hook. Si el Build Command falla (sale con código distinto de 0), el publish no se ejecuta y el deploy falla. Asegúrate de que tu comando de pre-build termina correctamente.
Referencia rápida
| Runtime | Vacío | Con valor | Output requerido |
|---|---|---|---|
| Node.js | npm ci --omit=dev | Reemplaza npm ci | Node modules en node_modules/ |
| Python | pip install -r requirements.txt | Reemplaza pip install | Paquetes en el venv |
| Go | go build -o kubiy-app . | Reemplaza go build | Binario ./kubiy-app |
| .NET | dotnet publish (auto) | Se ejecuta ANTES del publish | El publish sigue corriendo después |