Guías

Build y deploy

Qué pasa desde que haces push de un commit hasta que se sirve, y todo lo que puedes controlar en ese proceso.

Qué inicia un build

Un push a la rama configurada, si los deploys automáticos están activados (lo están por defecto).
La consola: el botón Desplegar rama actual de la página de la app.
La CLI: codaracloud deploy <app> --source.
La API, para sistemas de CI y automatizaciones.

Si prefieres publicar a mano, desactiva los deploys automáticos en cada app. El ajuste está en la página de configuración de la app; desde la CLI, usa --manual-deploys al crearla.

En un monorepo, las rutas vigiladas (watch paths) evitan que cambios que no tienen nada que ver lo vuelvan a construir todo. Son patrones glob relativos a la raíz del repositorio, y un push que no coincide con ninguno queda registrado como un deploy skipped en lugar de descartarse sin avisar.

bash

$ codaracloud apps update api \    --client my-workspace \    --watch-path "services/api/**" \    --watch-path "packages/shared/**"

Ante la duda, las rutas vigiladas dejan pasar el build

Si no se puede saber qué archivos cambiaron en un push, el build se ejecuta. Codara prefiere hacer un deploy innecesario antes que perderse una release.

Un repositorio, varias apps

El mismo repositorio y la misma rama pueden alimentar varias apps en distintos espacios de trabajo, proyectos y entornos. Un solo push pone en cola un build para cada app que coincide. Así es precisamente como mantienes staging y production en la misma rama, y por eso las rutas vigiladas importan en un monorepo.

Cómo se construye tu imagen

Codara examina el contexto de build y elige una estrategia siguiendo un orden fijo. Gana la primera que coincide:

Orden	Condición	Estrategia
1	Un archivo llamado exactamente `Dockerfile` en la raíz del build, o una ruta de Dockerfile indicada explícitamente	Tu Dockerfile
2	`nixpacks.toml` en la raíz del build	Nixpacks
3	Un manifiesto de lenguaje reconocido	Railpack (el buildpack por defecto)
4	Solo archivos estáticos	Una imagen de nginx generada
5	Nada reconocible	El build falla con un error de detección

La detección del Dockerfile distingue mayúsculas y minúsculas

La detección automática busca el nombre exacto Dockerfile en la raíz del contexto de build. Un dockerfile en minúsculas, o uno en un subdirectorio, no se detecta, y tu repositorio acabará construyéndose con un buildpack. Si tu Dockerfile está en otro sitio, indica su ruta explícitamente.

Nixpacks hay que activarlo: no es la opción por defecto

Un repositorio de Node, Python o Go sin nixpacks.toml se construye con Railpack, no con Nixpacks. Añade el archivo solo si quieres usar Nixpacks expresamente.

Directorio raíz

Define un directorio raíz para construir desde un subdirectorio. Todo se resuelve de forma relativa a él: la detección del Dockerfile, la detección del buildpack y el contexto de build.

Argumentos de build frente a variables de runtime

Son dos canales distintos, y confundirlos es una fuente habitual de errores.

	Argumentos de build	Variables de entorno
Disponibles durante el build	Solo para tu propio Dockerfile, mediante sus instrucciones `ARG`	No
Disponibles en runtime	No	Sí
Aptos para secretos	Nunca	Sí
Límites	Hasta 32 valores y 1024 caracteres en total	Hasta 65536 caracteres por valor

Nunca pongas un secreto en un argumento de build

Los argumentos de build se validan como datos no secretos y quedan grabados en las capas de la imagen. Todo lo sensible va en variables de entorno, que el build no puede ver.

Los argumentos de build solo llegan a un build a través de un Dockerfile tuyo: cada uno rellena la instrucción ARG con el mismo nombre. Los builds sin Dockerfile propio (Railpack, Nixpacks y sitios estáticos) no los reciben por ahora, aunque puedas definirlos en la app.

Si tu framework necesita un valor público en tiempo de build, como la URL base de una API que queda incluida en el bundle del cliente, tienes dos opciones:

Guárdalo en el repositorio, en el archivo que tu framework lee durante el build. Una app de Next.js lee los valores NEXT_PUBLIC_ de un .env.production incluido en el repositorio, y eso funciona con Railpack.
Haz el build con tu propio Dockerfile, declara ARG NOMBRE (y ENV NOMBRE=$NOMBRE si la herramienta de build lo lee del entorno) y define el valor como argumento de build.

En ambos casos el valor acaba en la imagen o en el bundle del cliente, así que úsalo solo para valores que publicarías. Todo lo demás va en las variables de entorno.

El rollout

Que el build haya terminado no significa que el deploy haya terminado. Codara sube la imagen, hace el rollout y espera a que los pods nuevos estén realmente sanos antes de marcar la release como activa.

Por defecto, el rollout es gradual: los pods nuevos tienen que arrancar sanos antes de retirar los antiguos, así que no hay tiempo de inactividad. Una app con un volumen conectado usa en su lugar un rollout de parar y arrancar, porque el disco solo puede montarlo un pod a la vez. En esas apps, cuenta con un breve corte en cada deploy.

Si el reemplazo falla, la release sana sigue activa

Si la versión nueva nunca llega a estar sana, el deploy se marca como fallido y la release anterior sigue sirviendo. No tienes que hacer nada para que todo siga funcionando; solo averiguar por qué falló la nueva.

Health checks

Configura una ruta de health check en la app y Codara la usará para decidir tanto si un pod está vivo como si está listo para recibir tráfico. Sin ella, un contenedor que arranca pero nunca llega a ser utilizable puede acabar desplegado igualmente. Merece la pena añadir un endpoint /health ligero que devuelva 200.

Comandos previos al deploy

Un comando previo al deploy se ejecuta una vez en la imagen nueva antes de que le llegue tráfico. Es el sitio para las migraciones de la base de datos: si el comando falla, la release se abandona y tu versión actual sigue sirviendo.

npm run migrate:deploy

Hacer rollback

Un rollback vuelve a publicar la imagen de un deploy anterior. No hace un build nuevo, así que es rápido y produce exactamente los mismos bytes que estaban en marcha antes.

bash

$ codaracloud deploys list my-api$ codaracloud rollback my-api --to-deploy <deploy-id>

El rollback queda registrado como un deploy nuevo que apunta a la imagen antigua, así que tu historial refleja con fidelidad qué estaba en marcha en cada momento.

Algunos deploys antiguos necesitan un build nuevo

Puedes hacer rollback a cualquiera de los 10 últimos deploys completados con éxito de una app, incluido el que está en marcha: Codara conserva sus imágenes. Las imágenes anteriores al 24 de septiembre de 2026, salvo las que las apps tenían en marcha, no se copiaron al registro de Codara en la UE, y las copias de GitHub se borraron ese día. La consola indica qué deploys se pueden restaurar. Para volver más atrás, o a uno de esos deploys, vuelve a construir su commit con codaracloud deploy my-api --commit <sha>.

Promover entre entornos

La promoción lleva la imagen exacta que probaste en un entorno a otro, sin hacer un build nuevo. El destino conserva sus propias variables de entorno, dominios y escalado; solo cambia la imagen.

bash

$ codaracloud promote my-api \    --from-deploy <deploy-id> \    --from-env staging \    --to-env production

Consulta Entornos para ver cómo organizarlo.

Cancelar un build

Un build en cola o en curso se puede cancelar hasta el momento en que se promueve. La release que está sirviendo no se ve afectada.

bash

$ codaracloud deploys cancel my-api <deploy-id> --confirm

Desplegar una imagen ya construida

Una app puede apuntar a una imagen de contenedor existente en lugar de a un repositorio, algo útil para software de terceros y para imágenes construidas en otro sitio.

bash

$ codaracloud apps image my-app ghcr.io/acme/my-app:v1.4.2

Si vuelves a pasar la misma referencia, la imagen se descarga de nuevo; así se actualiza una etiqueta que va cambiando, como :latest. Para un registro privado, configura antes las credenciales:

bash

$ echo "$REGISTRY_TOKEN" | codaracloud apps registry set my-app \    --username acme-ci \    --password-stdin

La contraseña solo se lee desde stdin, y la API nunca devuelve las credenciales.

Límites de build que conviene conocer

Límite	Valor
Duración máxima del build	30 minutos; pasado ese tiempo, el build falla
Builds simultáneos	4 a la vez en toda la plataforma; los siguientes esperan en cola e indican su posición. Cada build en curso reserva además 2,5 vCPU y 4,5 GiB del límite máximo de tu plan para apps y builds.
Retención de los logs de build	24 horas. Después, el endpoint de logs devuelve una respuesta vacía.
Reintentos de build	Ninguno: un build fallido es definitivo hasta que lances otro

Los logs de build no se archivan

La salida del build se lee en directo desde el contenedor del build y desaparece unas 24 horas después de que termine. Si te importa un fallo de build, guarda la salida mientras siga disponible.

Los límites del plan pueden bloquear deploys

Cada plan incluye un número de inicios de build por mes natural (UTC), y los builds fallidos cuentan. Cuando se agotan, no pueden empezar builds nuevos hasta el mes siguiente; las apps en marcha no se ven afectadas. Las demás peticiones que superan un límite del plan se rechazan, normalmente con 402 plan_limit_exceeded, que indica qué límite es. Una suscripción cancelada o vencida no permite deploys nuevos, y sus cargas de trabajo en marcha se pausan; los datos se conservan. Consulta Planes y capacidad.

Última actualización: 26 de septiembre de 2026