Fuentes de Deploy

Dokploy soporta multiples formas de obtener tu codigo o imagenes para deployar. Cada metodo tiene sus ventajas y casos de uso. Aqui los vemos todos.

Fuentes de codigo disponibles

Fuente	Auto-deploy	Build en Dokploy	Repositorios privados
GitHub App	Si (webhooks)	Si	Si
GitHub OAuth	No	Si	Si
Git generico (GitLab, Bitbucket, etc.)	Si (webhook manual)	Si	Si (SSH key)
Docker Registry	No	No (imagen pre-built)	Si (credenciales)
ZIP Drop	No	Si	N/A

GitHub: el metodo principal

GitHub es la integracion mas completa en Dokploy. Hay tres formas de conectarlo.

GitHub App (recomendado)

La GitHub App es el metodo preferido. Ofrece permisos granulares, webhooks automaticos y acceso a repositorios especificos.

Configuracion:

1. Ve a Settings > Git Providers en Dokploy
2. Clic en Setup GitHub App
3. Dokploy te redirige a GitHub para crear e instalar la app
4. Selecciona la organizacion o cuenta personal
5. Elige los repositorios a los que la app tendra acceso:
   • All repositories: Acceso a todo
   • Only select repositories: Solo los que elijas (recomendado)
6. Confirma la instalacion

Una vez instalada, al crear un servicio:

1. Selecciona GitHub como provider
2. El dropdown muestra los repositorios disponibles
3. Selecciona el repositorio y la rama
4. Clic en Save

Auto-deploy con webhooks:

Con la GitHub App, cada push a la rama configurada dispara un deploy automatico. No necesitas configurar nada adicional:

• Push a main → deploy automatico
• Push a otra rama → no hace nada (a menos que sea la rama configurada)

Para desactivar auto-deploy, desmarca Auto Deploy en la configuracion del servicio.

GitHub OAuth

OAuth da acceso a todos los repositorios de tu cuenta sin instalar una app.

1. Ve a Settings > Git Providers
2. En la seccion GitHub, clic en Connect with OAuth
3. Autoriza a Dokploy en GitHub
4. Los repositorios aparecen disponibles al crear servicios

Diferencias con GitHub App:

• No tiene webhooks automaticos
• Accede a todos los repositorios (no puedes seleccionar)
• Permisos mas amplios
• No soporta auto-deploy

Token personal (PAT)

Para repositorios especificos sin instalar la GitHub App:

1. En GitHub, ve a Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Crea un token con permisos:
   • Contents: Read
   • Metadata: Read
3. En Dokploy, al configurar un servicio, selecciona Git como provider
4. Usa la URL del repositorio con el token:

https://<token>@github.com/usuario/repositorio.git

O configura el token en los campos de autenticacion del provider Git generico.

Git generico (GitLab, Bitbucket, Gitea, Forgejo)

Para cualquier repositorio Git accesible por HTTPS o SSH.

Configuracion con HTTPS

1. Al crear o editar un servicio, selecciona Git como provider
2. Ingresa la URL del repositorio:

https://gitlab.com/usuario/mi-proyecto.git
https://bitbucket.org/usuario/mi-proyecto.git
https://git.miserver.com/usuario/mi-proyecto.git

3. Si es privado, agrega las credenciales:
   • Username: Tu usuario
   • Password: Token de acceso personal (no tu password real)

Configuracion con SSH

Para repositorios privados via SSH:

1. En Settings > SSH Keys, Dokploy genera un par de llaves
2. Copia la llave publica
3. Agregala como deploy key en tu plataforma Git:
   • GitLab: Settings > Repository > Deploy Keys
   • Bitbucket: Repository settings > Access keys
   • Gitea/Forgejo: Settings > Deploy Keys
4. En el servicio, usa la URL SSH:

[email protected]:usuario/mi-proyecto.git
[email protected]:usuario/mi-proyecto.git

Webhooks manuales para auto-deploy

Con Git generico, debes configurar webhooks manualmente:

1. En Dokploy, ve al servicio y copia la Webhook URL (disponible en la seccion de deployment)
2. En tu plataforma Git, agrega un webhook:

GitLab: Settings > Webhooks > Add webhook

• URL: la URL copiada de Dokploy
• Trigger: Push events
• Branch filter: main (o la rama que quieras)

Bitbucket: Repository settings > Webhooks > Add webhook

• URL: la URL copiada
• Triggers: Repository push

Gitea/Forgejo: Settings > Webhooks > Add webhook (Gitea)

• Target URL: la URL copiada
• Events: Push

Cada push a la rama configurada dispara un nuevo deploy.

Deploy desde Docker Registry

Si ya tienes una imagen construida en un registry, Dokploy puede desplegarla directamente sin hacer build.

Registries soportados

• Docker Hub: usuario/imagen:tag
• GitHub Container Registry (GHCR): ghcr.io/usuario/imagen:tag
• Amazon ECR: 123456789.dkr.ecr.us-east-1.amazonaws.com/imagen:tag
• Google GCR: gcr.io/proyecto/imagen:tag
• Registries privados: Cualquier registry compatible con OCI

Configuracion

1. Crea un servicio de tipo Application
2. En Provider, selecciona Docker
3. Ingresa la imagen completa con tag:

nginx:alpine
node:22-alpine
ghcr.io/mi-org/mi-api:v1.2.3
mi-registry.com:5000/mi-app:latest

4. Si el registry requiere autenticacion, configura las credenciales en Settings > Registry:
   • Docker Hub: Username + Access Token
   • GHCR: Username + Personal Access Token (con read:packages)
   • ECR: AWS Access Key + Secret Key

Agregar un registry privado

1. Ve a Settings > Registry
2. Clic en Add Registry
3. Completa los campos:
   • Registry URL: ghcr.io, 123456789.dkr.ecr.us-east-1.amazonaws.com, etc.
   • Username: Usuario o AWS Access Key
   • Password: Token o AWS Secret Key
4. Clic en Save

Una vez configurado, puedes usar imagenes de ese registry en cualquier servicio.

Actualizar la imagen

Cuando publicas una nueva version de la imagen:

1. Ve al servicio en Dokploy
2. Actualiza el tag si cambio (por ejemplo, v1.2.3 → v1.2.4)
3. Clic en Deploy

Si usas el tag latest, simplemente haz deploy de nuevo y Dokploy descarga la version mas reciente.

ZIP Drop deployment

Disponible desde Dokploy v0.28, permite subir un archivo ZIP con el codigo fuente directamente desde el navegador.

Cuando usar ZIP Drop

• Proyectos sin repositorio Git
• Deploys rapidos de prototipos
• Entornos donde no tienes acceso a Git
• Migraciones de plataformas legacy
• Demos y pruebas de concepto

Como funciona

1. Crea un servicio de tipo Application
2. En Provider, selecciona Drop
3. Arrastra o selecciona un archivo .zip con tu codigo
4. Dokploy extrae el ZIP y ejecuta el build (Nixpacks o Dockerfile, segun configuracion)
5. Despliega la aplicacion

Preparar el ZIP

El ZIP debe contener los archivos del proyecto en la raiz (no dentro de una carpeta):

# Correcto: archivos en la raiz del ZIP
cd mi-proyecto
zip -r ../mi-proyecto.zip . -x ".git/*" "node_modules/*"

# Incorrecto: carpeta contenedora
zip -r mi-proyecto.zip mi-proyecto/

Excluye archivos innecesarios para reducir el tamano:

zip -r deploy.zip . \
  -x ".git/*" \
  -x "node_modules/*" \
  -x ".env*" \
  -x "*.test.*" \
  -x "coverage/*"

Limitaciones del ZIP Drop

• No hay auto-deploy (debes subir manualmente cada version)
• No hay historial de Git (sin diff entre versiones)
• Tamano maximo del ZIP depende de la configuracion del servidor
• No es recomendable para proyectos en produccion activa

Deploy desde rama especifica o tag

Independientemente del provider Git, puedes elegir que rama o tag desplegar.

Configurar la rama

En la configuracion del servicio, el campo Branch define desde donde Dokploy obtiene el codigo:

main
develop
release/v2.0
feature/nueva-funcionalidad

Cada deploy clona o actualiza esa rama especifica.

Deploy desde tag

Para deployar un tag especifico (por ejemplo, para releases):

1. En el campo Branch, ingresa el nombre del tag:

v1.0.0
v2.3.1
release-2026-02

2. Clic en Deploy

Esto es util para:

• Releases de produccion con versiones fijas
• Rollback a una version anterior cambiando el tag
• Entornos de staging con tags de pre-release

Estrategia recomendada con ramas

main          → produccion (auto-deploy)
staging       → staging (auto-deploy)
develop       → desarrollo (deploy manual)

Configura un servicio por entorno, cada uno apuntando a su rama correspondiente.

Cuando usar cada fuente

GitHub App

• Proyectos en GitHub con equipo
• Necesitas auto-deploy confiable
• Quieres permisos granulares
• Multiples repositorios en una organizacion

Git generico (SSH/HTTPS)

• Repositorios en GitLab, Bitbucket, Gitea o Forgejo
• Git self-hosted
• Repositorios en multiples plataformas

Docker Registry

• Imagenes pre-construidas en CI/CD externo
• Servicios de terceros (nginx, postgres, redis)
• Cuando el build se hace en GitHub Actions o GitLab CI
• Cuando no quieres que Dokploy haga el build

ZIP Drop

• Prototipos y pruebas rapidas
• Proyectos sin repositorio
• Migraciones de plataformas que no usan Git
• Demos puntuales

---

Anterior: Capitulo 8: Docker Compose | Siguiente: Capitulo 10: PostgreSQL y MySQL