deploy/

Una entrada por destino de despliegue: local, ssh, ftp, docker, digitalocean.

deploy/

Cada entrada deploy/*.bx/.json describe un intento de destino de despliegue - un lugar al que enviar un proyecto construido/empaquetado:

// deploy/production.bx
class {

	function configure() {
		return {
			target       : "digitalocean",
			appName      : "my-agent",
			region       : "nyc",
			registry     : { type : "ghcr", repository : "myorg/my-agent" },
			httpPort     : 8080,
			instanceSize : "apps-s-1vcpu-1gb",
			envs         : [ { key : "OPENAI_API_KEY", scope : "RUN_TIME", type : "SECRET" } ]
		};
	}

}

Ejecútalo con:

bxAgents deploy --name=production

deploy/ deliberadamente no se valida en cada build - la configuración de despliegue nunca afecta la app ColdBox generada ni su manifest, así que comprobarla en cada build sería puro overhead para proyectos que nunca despliegan. Solo se descubre y valida cuando deploy realmente se ejecuta.

El caso más simple no necesita ninguna carpeta deploy/ en absoluto:

bxAgents deploy --destination=/path/to/somewhere

es la forma abreviada para el destino local. Cada otro destino necesita más configuración de la que un par de flags puede razonablemente transportar, así que requiere una entrada nombrada deploy/* (--name=<entry>).

Destinos

Cada destino implementa la misma interfaz IDeploymentTarget (struct function deploy( config, context )) - el campo target elige cuál se ejecuta.

local

Copia el .bxa empaquetado más nuevo (por tiempo de modificación de archivo, nunca un ordenamiento léxico de nombre de archivo - v9.0.0 de lo contrario ordenaría después de v10.0.0) a un directorio destino.

{ target: "local", destination: "/path/to/somewhere" }

Requiere un bxAgents package previo.

ssh

Envía el .bxa más nuevo a un servidor desnudo vía scp, luego opcionalmente ejecuta un comando de reinicio remoto vía ssh.

{
	target         : "ssh",
	host           : "example.com",
	username       : "deploy",
	remotePath     : "/srv/apps/my-agent",
	identityFile   : "/home/me/.ssh/id_rsa",   // opcional
	restartCommand : "systemctl restart my-agent"   // opcional
}

Requiere un bxAgents package previo. Invoca los binarios reales scp/ssh - deben estar instalados y en PATH.

docker

Construye una imagen Docker desde .build/app y la sube a un registro de contenedores, invocando la CLI real de docker.

{
	target   : "docker",
	registry : { type : "ghcr", repository : "myorg/my-agent" },   // type: "dockerhub" | "ghcr" | "docr"
	tag      : "1.0.0"   // opcional, por defecto "latest"
}

Requiere un bxAgents build previo (no package - construye directamente desde .build/app). La plantilla de Dockerfile incorporada se basa en la imagen real y publicada ortussolutions/boxlang:miniserver - sobreescríbela por completo añadiendo tu propio deploy/Dockerfile, o apunta a uno diferente vía dockerfile: "/absolute/path".

docker login solo se ejecuta cuando tanto DOCKER_USERNAME como DOCKER_PASSWORD están configuradas en el entorno - un registro que un daemon Docker local ya autenticado puede alcanzar no necesita ninguna de las dos.

digitalocean

Despliega a una app de DigitalOcean App Platform - "push y provisión mínima": construye/sube la imagen exactamente como docker (reutiliza la misma forma de configuración registry), luego ya sea redespliega una app existente o crea una desde cero si aún no existe.

{
	target        : "digitalocean",
	appName       : "my-agent",
	region        : "nyc",   // opcional, por defecto "nyc"
	registry      : { type : "docr", repository : "myorg/my-agent" },   // forma "namespace/repo"
	httpPort      : 8080,   // opcional, por defecto 8080
	instanceSize  : "apps-s-1vcpu-1gb",   // opcional
	instanceCount : 1,   // opcional, por defecto 1
	envs          : [ { key : "OPENAI_API_KEY", scope : "RUN_TIME", type : "SECRET" } ]   // opcional
}

registry.repository debe estar en forma namespace/repo (por ejemplo, myorg/my-agent) - el bloque image del App Spec de DigitalOcean necesita el namespace y el repositorio como campos separados. Requiere un bxAgents build previo.

Una app existente se encuentra por nombre (GET /v2/apps, filtrado del lado del cliente sobre spec.name) en lugar de recordar un archivo local de ID de app, así que esto funciona idénticamente desde cualquier máquina o corredor de CI sin estado local que pueda quedar obsoleto.

ftp / sftp

Envía el .bxa más nuevo a un directorio remoto vía FTP o SFTP simple, a través del componente real bx:ftp - una dependencia de runtime genuina de este proyecto (como bx-ai), no empaquetada. remotePath es un directorio remoto - el archivo subido conserva su propio nombre, la misma convención que usa el destino scp de ssh.

// deploy/ftp-production.bx
{
	target         : "ftp",
	host           : "ftp.example.com",
	username       : "deploy",
	passwordEnvVar : "FTP_PASSWORD",
	remotePath     : "/uploads/my-agent",
	port           : 21,       // opcional, por defecto 21
	passive        : true,     // opcional, por defecto true
	timeout        : 30,       // opcional, segundos, por defecto 30
	proxyServer    : "proxy.company.com:8080"   // opcional
}

// deploy/sftp-production.bx
{
	target           : "sftp",
	host             : "sftp.example.com",
	username         : "deploy",
	key              : "/home/me/.ssh/id_rsa",   // se requiere passwordEnvVar O key
	passphraseEnvVar : "SFTP_KEY_PASSPHRASE",     // opcional, solo si la propia clave está protegida por passphrase
	fingerprint      : "SHA256:...",              // verificación opcional de clave de host
	remotePath       : "/uploads/my-agent",
	port             : 22,       // opcional, por defecto 22
	timeout          : 30        // opcional, segundos, por defecto 30
}

Requiere un bxAgents package previo. ftp requiere un passwordEnvVar; sftp acepta ya sea un passwordEnvVar o un key (ruta de archivo de clave privada SSH). passwordEnvVar/passphraseEnvVar nombran variables de entorno que contienen el secreto real - nunca el valor del secreto mismo - resueltas en vivo en tiempo de despliegue; key permanece como una ruta simple, ya que no es en sí misma material secreto. Cada acción de bx:ftp lanza en caso de fallo (conexión rechazada, autenticación rechazada, una respuesta negativa del servidor) en lugar de devolver un fallo suave - este destino captura eso y lo relanza como un BxAgents.DeployFailed claro, siempre cerrando la conexión después, incluso en caso de error.

Secrets stay external

Ningún destino lee jamás un secreto (token de API, clave SSH, contraseña de registro) desde la configuración de deploy/* - cada credencial se resuelve desde una variable de entorno en tiempo de despliegue, coincidiendo con la regla existente de este proyecto de que las claves de API de proveedor nunca se incrustan en un build o package (ver Despliegue y secretos):

Validación

• target debe ser uno de local, ssh, docker, digitalocean, ftp, sftp.
• Los nombres de entrada deben ser únicos a través de deploy/*.bx y deploy/*.json.
• Los campos requeridos de cada destino (arriba) se comprueban cuando se ejecuta deploy - local necesita destination, ssh/ftp/sftp necesitan host/username/remotePath (el mismo nombre de campo en los tres), docker/digitalocean necesitan registry.repository, digitalocean también necesita appName, ftp también necesita passwordEnvVar, sftp también necesita passwordEnvVar o key.