De un repositorio Git a producción: guía de despliegue con Dockup

Pasar un repositorio Git a producción requiere algo más que conectar un remote y pulsar el botón de despliegue. La plataforma debe conocer el destino del servicio, la rama, el método de build, el comando de inicio, el puerto de escucha, el entorno, el health gate y la estrategia de recuperación. Dockup hace explícitas estas decisiones y admite tanto builds automáticos con Nixpacks como Dockerfiles gestionados desde el repositorio.

Esta guía comienza con un repositorio que nunca se ha desplegado y termina con una URL verificada, un historial de despliegues, logs y un comando de rollback probado.

¿Qué se debe comprobar antes del primer despliegue en producción?

Confirma que el repositorio se puede desplegar sin depender de estado local no documentado. Un clone limpio debe contener todo lo necesario para instalar las dependencias e iniciar la aplicación, salvo los secretos.

Usa esta checklist:

Comprobación	Resultado esperado
Rama predeterminada	Existe la rama prevista para producción
Lockfile de dependencias	Está incluido en el repositorio para permitir instalaciones reproducibles
Proceso de inicio	Escucha en el puerto configurado y en 0.0.0.0
Ruta de health	Devuelve un resultado correcto sin efectos externos
Migraciones de base de datos	Tienen un plan de ejecución seguro y explícito
Secretos	Se almacenan fuera de Git
Archivos persistentes	Usan un volumen, no el sistema de archivos del contenedor
Rollback	Se puede volver a ejecutar el despliegue anterior

Instala la CLI y autentícate:

npm install -g dockup-cli
export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

Enumera los servicios existentes antes de crear nada:

dockup services --json

Esto evita crear recursos duplicados y confirma la convención exacta del workspace y del destino.

¿Cómo permite Dockup create realizar un despliegue desde Git?

El comando habitual para el primer despliegue crea el servicio, lo despliega, espera el resultado y vincula el directorio actual:

dockup create api \
  --repo https://github.com/acme/api \
  --project production \
  --branch main \
  --deploy \
  --wait \
  --link \
  --json

El destino resultante es production/api. El enlace .dockup permite que los comandos posteriores resuelvan ese servicio al ejecutarse dentro del repositorio, pero la documentación de producción debe registrar igualmente el destino completo.

Después de un intento de aprovisionamiento interrumpido, enumera los servicios e inspecciona el destino exacto antes de volver a ejecutar la creación:

dockup services --json

Si production/api ya existe, continúa consultando su estado y el historial de despliegues. Así evitas convertir un resultado de red incierto en un servicio duplicado. Mantén las credenciales de acceso al repositorio fuera del control de versiones y de la salida de los comandos.

¿Cómo elige Dockup entre Nixpacks y Dockerfile?

Si el repositorio contiene un Dockerfile, Dockup lo utiliza. En caso contrario, Nixpacks detecta la aplicación y la compila automáticamente. De este modo, la definición explícita del contenedor en el repositorio tiene prioridad.

Nixpacks es una buena primera opción cuando la aplicación sigue las convenciones habituales de su ecosistema y no necesita personalización a nivel del sistema operativo. Un Dockerfile resulta útil cuando necesitas una imagen base concreta, paquetes del sistema, un build multi-stage, un usuario de runtime personalizado o límites exactos para las copias.

No necesitas añadir un Dockerfile vacío solo para que el proyecto “parezca listo para producción”. Un Dockerfile incorrecto puede ser menos reproducible que un build automático convencional. Usa el proceso de decisión descrito en Nixpacks vs Dockerfile.

Inspecciona el servicio después de crearlo:

dockup info production/api --json

La respuesta incluye la URL del repositorio, la rama, el tipo de despliegue, el puerto, la configuración de build y de inicio, las claves de entorno, los dominios personalizados y los datos del último despliegue.

Si los comandos detectados necesitan un override, usa la configuración documentada:

dockup set production/api \
  --build "npm ci && npm run build" \
  --start "npm start" \
  --port 3000 \
  --json

La configuración se aplicará en el siguiente despliegue.

¿Cómo se configuran el entorno de producción y el health gate?

Añade los valores normales y los secretos por separado:

dockup env set NODE_ENV=production \
  -s production/api \
  --json

dockup env set DATABASE_URL="$DATABASE_URL" \
  --secret \
  -s production/api \
  --json

Los valores secretos aparecen ocultos al listar el entorno. Se pueden establecer o reemplazar, pero el valor almacenado no se devuelve.

Los cambios de entorno requieren un redeploy, porque el proceso en ejecución no puede recibir retroactivamente un entorno nuevo. El ciclo de vida completo se explica en variables de entorno y secretos.

Configura un health gate que represente el estado de readiness:

dockup health production/api \
  --path /healthz \
  --interval 5 \
  --timeout 3 \
  --retries 5 \
  --json

Dockup utiliza un flujo blue-green sin downtime y solo dirige tráfico al nuevo despliegue cuando la readiness se completa correctamente. Si no se configura ninguna ruta HTTP, el gate puede recurrir a comprobar la readiness del puerto TCP.

Una ruta de health debe verificar que el proceso de la aplicación está listo para atender solicitudes. Evita que realice comprobaciones destructivas o tests costosos de todo el sistema. Las comprobaciones profundas de dependencias pueden provocar falsas interrupciones cuando un servicio opcional está degradado.

¿Cómo se despliega, supervisa y verifica producción?

Inicia el release y espera a que alcance un estado terminal:

dockup deploy production/api --wait --json

El timeout predeterminado es de 900 segundos. El código de salida 0 indica que la operación se ha completado correctamente. deploy_failed y deploy_timeout producen resultados distintos de cero, por lo que los scripts de shell y los sistemas de CI se detienen correctamente.

Para supervisar el build como NDJSON:

dockup logs production/api --build -f --json

El stream termina cuando la operación finaliza correctamente o falla. Si el build termina correctamente pero el contenedor se cae, inspecciona los logs de runtime:

dockup logs production/api --json

Después de un release correcto, verifica el estado de la plataforma y el comportamiento público:

dockup status production/api --json
dockup uptime production/api --hours 24 --json
dockup security production/api --json

Las sondas de uptime se ejecutan cada minuto e informan del tiempo de respuesta medio y p95. El análisis de seguridad comprueba las CVE de la imagen y la configuración. Añade un smoke test específico de la aplicación para el endpoint de negocio real; la readiness de la plataforma es necesaria, pero no suficiente.

El método detallado para consultar logs está disponible en depuración de logs de build y runtime.

¿Cómo se deben introducir los despliegues automáticos y las previews?

Realiza el primer release de producción manualmente y con el nivel de detalle suficiente para observar cada límite. Cuando conozcas el build, el health gate y el proceso de rollback, activa el despliegue al hacer push:

dockup auto-deploy production/api --on --json

El despliegue automático debe seguir una rama protegida y una política de code review. Un push es un trigger de producción, por lo que los permisos del repositorio se convierten en permisos de infraestructura.

Las previews de pull request y de ramas proporcionan URLs y entornos aislados:

dockup pr-preview production/api --on --json
dockup preview branch feature/login production/api --json

En un proyecto con networking privado, las previews se incorporan a la red del proyecto. Pueden acceder a la misma base de datos de producción mediante <slug>.internal, pero Dockup crea automáticamente un usuario de base de datos de solo lectura para la preview. La preview puede inspeccionar datos con una estructura similar a la de producción sin escribir en ellos.

Esto no elimina las obligaciones de privacidad. El acceso de las previews debe seguir estando limitado y auditado, y solo debe utilizarse cuando esté permitido leer datos de producción.

¿Cómo se hace rollback de un despliegue defectuoso?

Conserva las evidencias antes de iniciar la recuperación. Consulta los logs de build si se ha producido un fallo de build y los logs de runtime si se trata de un crash. Después, enumera el historial de despliegues:

dockup deployments production/api -n 20 --json

Selecciona un ID de despliegue cuyo estado y timestamp conozcas y vuelve a ejecutarlo:

dockup rollback <deploymentId> production/api --json

Un rollback debe ser una acción explícita de un incidente. Registra el ID del despliegue fallido, el ID de recuperación seleccionado, el motivo y la corrección posterior. Si una migración de base de datos no es compatible con versiones anteriores, hacer rollback de la aplicación por sí solo puede no restaurar la compatibilidad; el diseño de las migraciones debe formar parte del plan de release.

La guía de despliegues sin downtime explica el cambio de tráfico, mientras que la referencia de la CLI de Dockup documenta todos los flags de los comandos.

Registro de finalización del primer despliegue

Al finalizar el flujo de repositorio Git a producción, registra:

• El destino exacto project/service.
• El repositorio y la rama de producción.
• El método de build: Nixpacks o Dockerfile.
• Los comandos de build e inicio cuando se hayan sobrescrito.
• El puerto de escucha y la ruta de health.
• El ID del despliegue y su estado terminal.
• La URL de producción y el plan de dominios personalizados.
• La verificación de uptime y seguridad.
• El ID del despliegue de rollback o la regla de selección.

Este registro convierte el segundo despliegue en una operación rutinaria, en lugar de repetir el proceso de descubrimiento.

Separa el estado de la aplicación de la imagen del contenedor

El sistema de archivos escribible dentro de un contenedor de servicio debe tratarse como reemplazable. Un nuevo despliegue crea una nueva versión y un rollback vuelve a ejecutar una imagen anterior; los archivos escritos únicamente dentro del contenedor antiguo no constituyen una estrategia de datos duradera.

Usa bases de datos gestionadas para el estado relacional, documental o de caché, y adjunta un volumen para los archivos que deban persistir entre despliegues. Confirma las rutas de montaje antes del primer release de producción. Un directorio de uploads del contenedor que nunca se montó puede parecer saludable hasta que el siguiente despliegue elimina los datos.

Consulta volúmenes persistentes y snapshots antes de trasladar archivos generados por usuarios. Para el estado de la base de datos, utiliza el sistema de backup específico de la base de datos en lugar de tratar un snapshot en caliente del volumen como un backup coherente a nivel transaccional.

Calcula el primer mes sin inventar una factura fija de instancia

Dockup mide el consumo de CPU, RAM y disco por minuto y resta el uso del saldo del plan. El plan Free incluye un crédito inicial de 10 $ y hasta tres despliegues; el plan Pro recomendado cuesta 20 $ al mes e incluye 20 $ de crédito de uso.

Cuando el servicio tenga tráfico real, revisa su consumo de CPU, RAM y disco en app.dockup.ai. Utiliza el consumo por minuto observado —no un máximo estimado— para decidir si es necesario ajustar el servicio, la base de datos o el disco persistente.

Verifica que el segundo despliegue se realiza correctamente

Después del primer release, realiza un cambio revisado e inocuo y vuelve a desplegar. Esto confirma que el enlace al repositorio, las suposiciones sobre la caché del build, el health gate, el entorno y el historial funcionan como un proceso continuo y no solo como un aprovisionamiento puntual correcto.

Mantén el destino explícito

Registra la cadena final project/service.

Conserva la URL del release

Registra la URL de producción junto al ID del despliegue.

Confirma el siguiente trigger

Registra si los releases futuros serán manuales o utilizarán el deploy-on-push opcional. Así, los permisos del repositorio, la protección de ramas y las expectativas de producción seguirán alineados después del primer despliegue.

Empieza con un despliegue verificable

Elige un repositorio pequeño con un comando de inicio y una ruta de health claros y documenta el destino exacto y el ID de rollback después del primer release correcto.

Empieza gratis en app.dockup.ai. El plan Free cuesta 0 $ al mes, incluye un crédito inicial de 10 $ y admite un workspace, tres bases de datos y tres despliegues.

FAQ

¿Puede Dockup desplegar un repositorio sin Dockerfile?

Sí. Cuando no hay ningún Dockerfile, Dockup utiliza Nixpacks para detectar y compilar la aplicación automáticamente.

¿Qué hace dockup create --link?

Escribe un enlace .dockup en el directorio actual para que los comandos posteriores puedan resolver el destino asociado de proyecto/servicio.

¿Por qué el primer despliegue debe utilizar --wait?

Mantiene el comando conectado hasta que el despliegue alcanza el estado de éxito, error o timeout, y devuelve un código de salida que representa correctamente el resultado terminal.

¿Los cambios en las variables de entorno se aplican de inmediato?

No. Se aplican a un contenedor nuevo en el siguiente despliegue, por lo que debes volver a desplegar el servicio después de cambiar la configuración del entorno.

¿Cómo hace Dockup rollback de una aplicación?

Enumera el historial de despliegues, identifica un ID conocido de un despliegue anterior y utiliza dockup rollback con ese ID y el destino exacto del servicio.