Qué es un deploy o despliegue

Escribir código que funciona en tu computadora es una cosa. Lograr que funcione para otras personas, todo el tiempo, en otra máquina, es otra. El puente entre ambas es el deploy.

La palabra viene del inglés deployment, que en español se traduce como "despliegue". En desarrollo se volvió el nombre de una rutina que repites decenas de veces: cambias el código, haces deploy y el cambio llega a producción. Entender qué ocurre dentro de esa rutina te ayuda a encontrar errores más rápido y a elegir mejores herramientas.

¿Qué es un deploy?#

Un deploy es el conjunto de pasos que lleva una versión específica de tu código a un entorno donde se ejecuta y se puede acceder a ella. El entorno suele ser un servidor, un VPS, un contenedor o una plataforma de hosting.

Un deploy tiene un inicio y un final claros: parte de un commit (o de una carpeta de archivos) y termina con el proceso de la aplicación en ejecución y verificado. Si el resultado es una aplicación que responde, el deploy salió bien. Si el proceso se cae al iniciar, falló, aunque todos los archivos hayan llegado.

No lo confundas con el hosting. El hosting es el lugar; el deploy es la acción de poner algo ahí. Para entender el lugar, mira VPS vs plataforma en la nube.

¿Qué entornos existen?#

Casi todo proyecto serio tiene más de un entorno, y haces deploy en cada uno:

• Desarrollo: tu máquina. Aquí ejecutas y rompes cosas con libertad.
• Staging (preproducción): una copia lo más parecida posible a producción, para probar antes de publicar.
• Producción: lo que usan los usuarios reales. Aquí un error cuesta caro.

Los proyectos pequeños, como un bot personal, muchas veces tienen solo desarrollo y producción. Funciona si pruebas con cuidado en local y sabes volver atrás (más abajo).

¿Qué pasa cuando haces un deploy?#

La metodología Twelve-Factor App divide el proceso en tres etapas, un buen modelo mental:

1. Build: convierte el código de un commit en algo ejecutable. Obtiene dependencias y compila lo que haya que compilar.
2. Release: une el build con la configuración del entorno (variables, claves, direcciones de base de datos). El resultado queda listo para ejecutarse.
3. Run: inicia los procesos de la aplicación usando un release elegido.

En la práctica, los pasos que ves son estos:

1. El código llega al servidor (subida, git pull, imagen de contenedor).
2. Se instalan las dependencias (npm ci, pip install -r requirements.txt).
3. Si el lenguaje lo exige, se compila el código (TypeScript, Go, Rust, Java).
4. Se aplica la configuración.
5. Se detiene el proceso antiguo y arranca el nuevo.
6. Verificas que funciona, revisando los logs y probando una ruta o un comando.

Cada paso falla por un motivo distinto. Una dependencia que no se instala es un problema de build. Una variable que falta es un problema de release. Un proceso que termina justo después de iniciar es un problema de run. Saber en qué etapa está el error ya recorta la mitad del diagnóstico.

Por eso el build y la configuración van separados. Lo que cambia entre entornos (un token, la URL de la base de datos) no vive dentro del código: entra por variables de entorno, y el mismo código corre en staging y producción sin cambios.

¿Cuáles son las formas de hacer deploy?#

Manual#

Copias los archivos al servidor (SFTP, scp, un panel de subida) y reinicias el proceso. Es simple y sirve para aprender. El costo es que el resultado depende de la memoria de quien lo hace: un archivo olvidado, un paso fuera de orden.

Con Git#

Haces git push y el servidor descarga el código nuevo y ejecuta los pasos. El historial de Git se convierte en el registro de versiones, y cada deploy corresponde a un commit identificable.

Con CI/CD#

CI (integración continua) ejecuta pruebas en cada cambio. CD (entrega o despliegue continuo) lleva el resultado aprobado hasta el entorno. Herramientas como GitHub Actions ejecutan ese pipeline en cada push. La ventaja es que el camino siempre es el mismo, y un commit con una prueba rota ni siquiera llega a producción.

Este pipeline de GitHub Actions ejecuta las pruebas de un proyecto Node.js en cada push a main:

name: ci
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
      - run: npm ci
      - run: npm test

El paso de publicar iría después de npm test y solo se ejecutaría si las pruebas pasan. Cómo publicar depende de tu proveedor; el paso a paso completo está en deploy automático con GitHub Actions.

Con contenedores#

Empaquetas la aplicación y sus dependencias en una imagen, y el deploy pasa a ser "ejecutar esa imagen". Así se reduce el clásico "en mi máquina funciona". Mira qué es Docker.

¿Qué hacer cuando un deploy sale mal?#

Nadie acierta siempre. Lo que separa un incidente pequeño de uno grande es la rapidez para volver atrás.

• Rollback: volver a la versión anterior. Twelve-Factor App menciona volver a un release anterior como capacidad típica de las herramientas de deploy. Con Git, la versión anterior es el commit anterior: haz deploy de él otra vez.
• Lee primero los logs. El mensaje de error suele indicar la etapa (build, configuración o run).
• Cambia una cosa a la vez. Un deploy con cinco cambios es difícil de depurar.
• Respalda los datos antes de cambios arriesgados, sobre todo las migraciones de base de datos. El código se recupera con Git; los datos, no.

Errores comunes: olvidar una variable de entorno en producción, usar una versión de runtime distinta a la local, depender de un archivo que está en .gitignore y nunca llega al servidor, o fijar un puerto en lugar de leer el que entrega la plataforma.

¿Qué términos acompañan al deploy?#

• Pipeline: la secuencia automatizada de etapas (probar, construir, publicar).
• Artefacto: el resultado del build (un paquete, una imagen).
• Downtime: tiempo en que la aplicación está fuera de línea. Si el proceso antiguo se detiene antes de que arranque el nuevo, hay una breve ventana de indisponibilidad. Estrategias como blue-green y rolling update existen para reducirla, pero requieren infraestructura que las soporte.
• Entorno efímero: un entorno creado para una tarea y descartado después.
• Hotfix: una corrección urgente enviada directo a producción.

Cómo hacerlo en Square Cloud#

En Square Cloud, las etapas de esta guía quedan a la vista y bajo tu control. El código llega subiendo un ZIP en el panel, con la CLI, desde GitHub (un push hace el deploy, mediante la GitHub Action oficial o un webhook) o con la extensión de VS Code. La plataforma no tiene paso de build: al iniciar, instala las dependencias (npm install en Node.js cuando no existe node_modules, pip install -r requirements.txt en Python), y la salida de la instalación aparece en los logs de la aplicación. Si tu proyecto necesita compilarse, ejecuta el build en el CI y sube el resultado, o pon el build en el comando de inicio.

La configuración entra por variables de entorno, definidas por aplicación, y un cambio surte efecto en el siguiente reinicio, sin volver a subir el código. El archivo squarecloud.app (nombre, archivo principal, memoria, versión) es opcional: el panel lo genera en el deploy, o lo escribes en la raíz del proyecto. Entre diversos runtimes, como Node.js, Python, Go y Java, también hay TypeScript sin paso de build; consulta los runtimes disponibles hoy en Runtimes.

Para tener un camino de vuelta, crea un snapshot manual antes de un cambio arriesgado: existe en todos los planes y restaura la aplicación entera. Mira las formas de deploy en funciones y cómo funcionan los snapshots.