Siempre Listo Escuela
← Volver al listado de tecnologías ← Índice de Dokploy

Fuentes de Deploy

Por: Artiko
dokploydeploygitdocker-registryzip

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

FuenteAuto-deployBuild en DokployRepositorios privados
GitHub AppSi (webhooks)SiSi
GitHub OAuthNoSiSi
Git generico (GitLab, Bitbucket, etc.)Si (webhook manual)SiSi (SSH key)
Docker RegistryNoNo (imagen pre-built)Si (credenciales)
ZIP DropNoSiN/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
  1. 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
  1. 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
  1. 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

← Volver al listado de tecnologías ← Índice de Dokploy