deploykit_docs

docs Exportar e importar

Exportar e importar

Exporta la configuración de tu instancia como YAML para revisarla en git, clonarla en otro servidor o reconstruir tras perder un host.

Resumen

DeployKit puede describir toda tu instancia —o un único proyecto— como un manifiesto YAML. Guárdalo en git para revisar los cambios de infraestructura, aplícalo en un host nuevo para clonar la configuración, o úsalo para restaurar tras perder un servidor. Las exportaciones son deterministas: las claves están ordenadas, así que volver a exportar una instancia sin cambios produce un archivo idéntico y los diffs de git muestran solo los cambios reales.

Esto es configuración, no datos. El contenido de las bases de datos, los volúmenes y los mundos de juegos no se incluyen: usa los backups de bases de datos para eso.

Dos archivos: configuración y secretos

Manifiesto de configuración

kind: deploykit/instance-config

Proyectos, miembros (por email), aplicaciones, bases de datos, stacks de Compose con sus archivos Compose, dominios, variables de entorno, tareas programadas, programaciones de backups y ajustes de la página de estado. Las credenciales se omiten y solo se listan por nombre. Es seguro subirlo a un repositorio privado.

Archivo de secretos

kind: deploykit/instance-secrets

Los valores omitidos, en texto plano: variables de entorno y build args secretos, contraseñas de bases de datos, tokens de acceso a repositorios, secretos de webhook por aplicación y archivos de montaje sensibles de stacks. Solo se genera cuando lo pides. No lo subas nunca a un repositorio.

yaml
version: 1
kind: deploykit/instance-config
exportedAt: "2026-10-14T10:00:00.000Z"
projects:
  - name: shop
    applications:
      - name: storefront
        sourceType: github
        repositoryUrl: https://github.com/acme/storefront
        branch: main
        buildType: nixpacks
        port: 3000
        env:
          NODE_ENV: production
          API_BASE_URL: https://api.acme.com
        withheldSecrets:
          - STRIPE_SECRET_KEY
          - sourceToken
        domains:
          - domain: shop.acme.com
            port: 3000
            https: true

Qué se considera un secreto

Las variables de entorno se omiten del archivo de configuración cuando se cumple alguna de estas condiciones:

  • El nombre contiene PASS, PWD, SECRET, TOKEN, KEY, CRED, PRIVATE, SALT, SIGNING, CIPHER o DSN
  • El valor parece una credencial: una URL con user:password@, una clave privada PEM, un JWT o un prefijo de token conocido (ghp_, sk_, xoxb-, AKIA…, glpat- y otros)
  • El valor parece generado: 32+ caracteres, sin espacios y con al menos tres clases de caracteres

Los nombres que terminan en _URL, _HOST o _ENDPOINT permanecen en el manifiesto salvo que el propio valor contenga credenciales: son justo lo que quieres revisar. Las contraseñas de bases de datos, los tokens de repositorios, los secretos de webhook, los build args sensibles y el contenido de los montajes de stacks se omiten siempre.

Revisa antes de hacer push: el archivo de configuración sigue conteniendo todos los archivos Compose y el nombre de cada variable de entorno. La detección es deliberadamente amplia, pero revisa el archivo antes de subirlo a un repositorio público.

Lo que nunca se exporta

  • Servidores y claves SSH — los recursos hacen referencia a los servidores por nombre
  • La GitHub App — sus credenciales pertenecen a la instancia y a su URL de webhook. Las aplicaciones llevan el id de su repositorio de GitHub, y la importación las vuelve a enlazar con una instalación coincidente en el destino
  • Usuarios — los miembros se emparejan por email al importar; nunca se crean usuarios
  • Servidores de juegos, canales de notificación y reglas de alerta
  • Estado de ejecución: estado e ids de contenedores, historial de despliegues, modo de mantenimiento, entornos de preview y la última ejecución de cada tarea

Exportar desde el dashboard

  • Toda la instancia (administradores): Settings → Configuration export and import → “Export configuration” descarga deploykit-config-<date>.yaml; “Export secrets” descarga deploykit-secrets-<date>.yaml
  • Un proyecto (operadores del proyecto y administradores): el botón “Export” de la página del proyecto descarga la configuración de ese proyecto, sin secretos

Si un valor no se puede descifrar (por ejemplo, tras un cambio de ENCRYPTION_KEY ), se omite y se lista en las advertencias de la exportación. Cada exportación queda registrada en el registro de auditoría como config.export.

Importar

Los administradores importan desde Settings → Configuration export and import → Import:

  • “Choose manifest” y, opcionalmente, “Choose secrets file”
  • Opcionalmente marca “Run on the local host when a server named in the file does not exist here”
  • Haz clic en Preview para ver el plan: todavía no se escribe nada
  • Haz clic en Import para aplicar exactamente ese plan

El plan lista cada elemento como a crear, ya existente, omitido (con un motivo, como un email de miembro desconocido) o bloqueante. Cualquier error bloqueante deshabilita Import: la importación se ejecuta como una única transacción, porque una restauración a medias es peor que ninguna. El plan también muestra advertencias, valores omitidos sin nada que restaurar y conflictos de nombres de contenedor.

Comportamiento ante conflictos

Una importación crea lo que falta y nunca modifica lo que ya existe. Los recursos se emparejan por nombre (sin distinguir mayúsculas):

  • Proyecto existente — se mantiene tal cual, pero se recorre igualmente su contenido: volver a aplicar un manifiesto tras añadir una aplicación crea solo esa aplicación
  • Aplicación, base de datos o stack existente — se deja intacto, incluidos sus dominios, variables de entorno y tareas. Añadir un dominio o un cron job a algo que ya se está ejecutando es un cambio, no un recurso que falta
  • Dominio ya enrutado en esta instancia — se omite
  • Dos proyectos (o servidores) existentes con el mismo nombre — error bloqueante hasta que renombres uno
  • Slug de página de estado ya en uso — el proyecto se importa con su página de estado deshabilitada
  • El servidor indicado en el archivo no existe — error bloqueante por defecto, o el recurso se ejecuta en el host local si marcaste la opción
  • Falta la contraseña de la base de datos — se genera una nueva (advertencia: hay que actualizar todo lo que tenga la cadena de conexión anterior)
  • Aplicaciones enlazadas a una GitHub App — se vuelven a enlazar con la única instalación de aquí que puede ver el repositorio; si no, recurren a la URL de su repositorio con una advertencia

Conflictos de nombres de contenedor: los contenedores se nombran dk-<name> según el recurso, y un despliegue reemplaza cualquier contenedor que ya tenga ese nombre. Si el plan informa de un conflicto, desplegar el recurso importado reemplazaría al existente: renombra uno de ellos primero.

Después de importar

No se despliega nada: la importación escribe configuración, no contenedores. Las aplicaciones y stacks importados esperan a un Deploy, y las bases de datos importadas a su primer Start. Las tareas programadas y las programaciones de backups de bases de datos se registran de inmediato. Cada importación aplicada queda registrada en el registro de auditoría como config.import.

Usar la API

No hay ningún comando de CLI para exportar o importar; automatízalo mediante la API en su lugar. Los tres procedimientos son mutations (POST), por lo que las respuestas que pueden contener secretos nunca se cachean.

bash
# Export the instance (admin). Returns { manifest, secrets, warnings, counts };
# manifest and secrets are YAML strings (secrets is null unless requested).
curl -s https://deploy.example.com/trpc/config.exportInstance \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"includeSecrets":false}'

# Export one project (project operator or admin)
curl -s https://deploy.example.com/trpc/config.exportProject \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"<project-uuid>","includeSecrets":false}'

# Import (admin). dryRun defaults to true and returns the plan;
# send the same request with "dryRun": false to apply it.
curl -s https://deploy.example.com/trpc/config.import \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --rawfile m deploykit-config.yaml --rawfile s deploykit-secrets.yaml \
        '{manifest: $m, secrets: $s, dryRun: true, onMissingServer: "fail"}')"

onMissingServer es "fail" (por defecto) o "local". Límites: 2 MB para el manifiesto y 500 KB para el archivo de secretos.