Despliegue en Dokploy

Dokploy construye las imágenes desde tu repositorio y gestiona los certificados. API y Web se despliegan de forma independiente; API incluye el proceso Worker.

Lo que vas a crear

Dos despliegues de producto y dos servicios de datos:

API              Docker Compose: api + worker
Web              Application: panel + sitio público
Servicios        PostgreSQL · Redis
Volumen Files    compartido por api y worker

Crear PostgreSQL y Redis

Para una instalación nueva, crea PostgreSQL 16 y Redis 7 con contraseña. Si ya existen, reutilízalos. Configura sus credenciales solo en el despliegue API. Los contenedores deben poder alcanzarlos desde la red dokploy-network.

Conéctate a PostgreSQL una vez y habilita la extensión:

CREATE EXTENSION IF NOT EXISTS pgcrypto;

Crear API como Compose

Crea un servicio Compose llamado zapi-social-api. Selecciona Docker Compose, conecta el repositorio y guarda:

Campo	Valor
Branch	`main`
Compose Path	`./docker-compose.backend.yml`
Trigger Type	`On Push`
Enable Submodules	Desactivado

Este archivo construye los targets api y worker de Dockerfile.api con contexto raíz. Conserva la red externa dokploy-network; evita aislar el despliegue de los servicios de datos que necesita.

Configurar API y Files

En Environment, pega el bloque de API de Variables de entorno y activa Create Environment File. El Compose entrega a cada contenedor las variables que consume.

Para comenzar con almacenamiento nuevo, configura:

FILES_VOLUME_NAME=zapi-files

Compose crea el volumen si no existe; si ya existe, utiliza sus archivos. Los dos contenedores lo montan en /var/lib/zapi/files. Si conservas una instalación anterior, usa el nombre real de su volumen. Esta variable es un nombre de volumen, no una ruta.

🚫

Cambiar a un volumen vacío deja fuera los archivos anteriores. Mantén el nombre del volumen durante las actualizaciones y respáldalo junto con la base de datos.

Crear Web como Application

Crea una Application llamada zapi-social, conectada al mismo repositorio y rama:

Campo	Valor
Build Type	`Dockerfile`
Docker File	`Dockerfile.web`
Docker Context Path	`.`
Docker Build Stage	Vacío
Branch	`main`

En Environment, pega el bloque Web de Variables de entorno. Web ya incluye la landing, Portal y Admin. Cada imagen conserva su comando de arranque.

Configurar dominios

En Domains configura HTTPS:

Despliegue	Host	Service Name	Container Port
API	`api.zapisocial.com`	`api`	`3001`
Web	`app.zapisocial.com`	No aplica	`3000`
Web	`zapisocial.com`	No aplica	`3000`
Web	`www.zapisocial.com`, si lo usas	No aplica	`3000`

Deja Path e Internal Path en / y Strip Path desactivado. Worker no necesita dominio. Los cambios de dominio en Compose se aplican al desplegarlo.

Si aparece Services not found, confirma que el Compose está publicado en la rama, guarda el proveedor y revisa Preview Compose. Puedes usar Manual y escribir api; eso no corrige un archivo ausente o una ruta equivocada.

Vigilar solo lo que cambió

Añade las rutas por dependencia en Watch Paths para evitar reconstrucciones por cambios que no afectan a ese despliegue:

Aplicación	Rutas
Web	`apps/web/`, `packages/{ui,contracts,api-client}/`, `Dockerfile.web`
API	`apps/{api,worker}/`, `packages/{contracts,database,file-ingestion}/`, `infra/docker/**`, `Dockerfile.api`, `docker-compose.backend.yml`

Ambos añaden packages/{typescript-config,eslint-config}/**, package.json, bun.lock, tsconfig.json y .dockerignore. La landing entra por apps/web/**.

⚠️

Añade cada ruta por separado con el botón +. Si las pegas todas juntas separadas por espacios se crea un único patrón que no coincide con nada, y esa aplicación deja de desplegarse en silencio.

Aplicar las migraciones

El Compose de API usa PostgreSQL y Redis existentes y no aplica migraciones al arrancar. Respalda la base, verifica el rol y aplica las migraciones del repositorio contra la base correcta antes de iniciar código que dependa de ellas:

bun --filter @workspace/database db:migrate

Ejecuta el comando con una conexión y un rol autorizado para migrar. No borres ni recrees la base. El Compose completo sí incluye un servicio migrate; son dos modalidades distintas.

Desplegar

Publica los archivos en main antes de pulsar Deploy. Despliega API: Compose arranca sus contenedores api y worker. Comprueba que la API responde:

GET https://api.zapisocial.com/v1/health

Debe devolver status, database y redis en ok. Revisa también los registros de worker en Containers. Después despliega Web y completa las comprobaciones tras instalar.

Pasar desde tres aplicaciones

Prepara el Compose manteniendo disponibles API y Worker anteriores. Durante la ventana de cambio, detén el Worker anterior permitiendo terminar sus trabajos y despliega API con su Worker interno. Mueve el dominio API al servicio api y comprueba login, Files y publicaciones antes de retirar las aplicaciones anteriores.

Si la landing era una aplicación aparte, mueve sus dominios a Web y comprueba portada, blog y acceso al panel antes de retirarla. El resultado son dos despliegues de producto: API y Web. PostgreSQL, Redis y los volúmenes se conservan según la instalación elegida.

Caché de build

Los Dockerfiles instalan dependencias a partir de manifiestos y bun.lock antes de copiar el código. API y Worker reutilizan las etapas de paquetes compartidos. Web conserva .next/cache; las descargas Bun también usan un mount de caché.

Un cambio de aplicación reutiliza las capas previas mientras el builder las conserve. El primer build, un cambio de dependencias o una limpieza de caché puede tardar más. Revisa los logs para distinguir descargas, compilación y etapas marcadas CACHED.

Worker tiene un margen de cierre configurable de quince minutos para sus trabajos. Es un máximo al detener el contenedor, no un tiempo fijo añadido al build.

Certificados

Activa HTTPS en los hosts configurados. PostgreSQL y Redis permanecen en la red interna.

Requisitos Despliegue con Docker Compose