Manual técnico

Introducción

Este manual explica cómo se instala, se configura, se despliega y se opera Deploya. Está escrito para tres lectores:

• Quien evalúa o prueba el proyecto y quiere levantarlo en su computadora con un comando (capítulo 3).
• Quien opera el servidor de la nube de Deploya: publicar una versión, respaldar, vigilar (capítulos 5 y 7).
• Quien instala Deploya en su propio servidor con el modo autoalojado (capítulo 6).

Tecnologías utilizadas

Stack

Estructura del repositorio

Instalación local

Requisitos

Levantar la plataforma con un comando

git clone https://github.com/derekCmorales/deploya.git
cd deploya
cp .env.example .env
# Edita .env y define ADMIN_CLAVE (obligatoria)
docker compose up --build

Compose arranca en orden: postgres y redis (con healthcheck), luego migracion (aplica las migraciones y el seed, y termina), luego api, worker, traefik, mailpit y web.

Cuentas de demostración

El seed es idempotente: se puede correr las veces que haga falta sin duplicar nada ni reescribir contraseñas.

Desarrollo fuera de Docker

pnpm install
docker compose up postgres redis mailpit     # solo la base, la cola y el correo
set -a; . ./.env; set +a
pnpm --filter @deploya/api exec prisma migrate deploy
pnpm --filter @deploya/api prisma:seed
pnpm dev:api                                 # http://localhost:3001 con recarga
pnpm dev:web                                 # http://localhost:3000 con recarga

Con MOTOR_ADAPTADORES=stub (valor de .env.example) el motor corre en memoria: los despliegues avanzan por sus etapas sin Docker, útil para trabajar en la interfaz. Con MOTOR_ADAPTADORES=docker se usan BullMQ, git, Docker y Traefik reales, y hace falta el worker.

Configuración

Toda la configuración entra por variables de entorno. El código no tiene dominios, credenciales ni proveedores escritos: el mismo build corre en local, en AWS y en autoalojado.

Variables principales

Archivos de configuración

Despliegue en AWS

El piloto corre en una EC2 creada con Terraform (ADR 0009): la misma plataforma de docker compose que en local, más HTTPS y el certificado comodín. La landing vive fuera del servidor, en S3 y CloudFront, para que siga arriba aunque la EC2 se reinicie (ADR 0011). Ningún secreto pasa por Terraform.

Infraestructura

Primera puesta en marcha

Requisitos: Terraform 1.9 o más, AWS CLI v2 con el plugin de Session Manager y credenciales de la cuenta.

cd infra/terraform
cp terraform.tfvars.example terraform.tfvars   # dominio y correos del presupuesto
terraform init
terraform plan -out=piloto.tfplan
terraform apply piloto.tfplan
terraform output siguientes_pasos             # imprime los pasos con la IP y el ID reales

1. DNS en Cloudflare, en «Solo DNS»: lo que imprime terraform output registros_dns.
2. Esperar a cloud-init (5 a 10 min): aws ssm start-session --target <id> y cloud-init status --wait. Deja Docker, el usuario deploya y el repositorio en /srv/deploya.
3. Copiar .env.vps dentro de la sesión de SSM, sin que pase por Terraform ni por un chat: sudo -iu deploya, cd /srv/deploya && umask 077 && cat > .env.vps y chmod 600 .env.vps.
4. Publicar: RAMA=main scripts/desplegar-vps.sh.
5. Guardar CLAVE_CIFRADO_VARIABLES fuera del servidor.

desplegar-vps.sh es idempotente: hace git pull --ff-only de la rama, genera la ruta de la plataforma para Traefik, corre docker compose --env-file .env.vps -f docker-compose.yml -f docker-compose.vps.yml up -d --build, repite migraciones y seed y espera a que la API responda. Cada publicación posterior es solo ese comando.

Con HOST_WEB=app.<dominio> la web queda en app.<dominio>, la API en api.<dominio>, cada proyecto en <proyecto>.<dominio> y el S3 de un proyecto en <proyecto>-s3.<dominio>. La raíz es la landing.

Landing en S3 y CloudFront

La landing es un sitio estático de Astro en el repositorio deploya_landing. Se publica con AWS CLI desde ese repositorio:

LANDING_BUCKET=$(terraform -chdir=infra/terraform output -raw landing_bucket) \
LANDING_DISTRIBUCION=$(terraform -chdir=infra/terraform output -raw landing_distribucion) \
pnpm deploy:aws     # aws s3 sync + invalidación de CloudFront

La primera vez, ACM necesita ver los CNAME de validación en Cloudflare antes de emitir el certificado: terraform apply -target=aws_acm_certificate.landing, crear los registros de registros_dns_validacion_landing y repetir el apply.

Costo del piloto

El modelo completo, con la capacidad por nodo y el margen por plan, está en docs/costos.md. terraform destroy borra también el disco: antes, respaldo y copia de la clave de cifrado.

Comprobar que quedó

curl -I https://<dominio>                     # la landing, desde CloudFront
curl -I https://app.<dominio>                 # la web
curl -I https://api.<dominio>/health          # 200 con el certificado *.<dominio>
curl -I https://algo.<dominio>                # 404 de Traefik, pero con el certificado comodín
curl -I http://hola-deploya.<dominio>         # 301 hacia https
echo | openssl s_client -connect <dominio>:443 -servername x.<dominio> 2>/dev/null \
  | openssl x509 -noout -subject -enddate

Modo autoalojado

Deploya es de código abierto (AGPL-3.0) y se instala en un servidor propio. En autoalojado no hay cobro: un único plan «Autoalojado» sin vencimiento, límites por proyecto que fija el administrador y registro abierto, con invitación o cerrado (ADR 0008).

./scripts/instalar.sh                  # instala por etapas
./scripts/instalar.sh --continuar      # retoma después de corregir lo que falló
./scripts/instalar.sh --sin-comodin    # certificado por HTTP-01 si no hay token DNS
./scripts/instalar.sh --codigo-nuevo   # genera otro código de configuración

Con el código, se abre https://<dominio>/configurar: el asistente pide el código, crea la cuenta de administrador, prueba el SMTP (o sigue sin correo) y elige la política de registro. Lo guardado vive en la tabla ConfiguracionInstalacion, no en archivos, y se cambia después en Admin · Instalación.

Operación

Actualizar y respaldar

./scripts/respaldar.sh                         # base + configuración, sin la clave de cifrado
./scripts/respaldar.sh --restaurar AAAA-MM-DD  # vuelve a un respaldo
./scripts/actualizar.sh                        # respalda, migra y reinicia api, web y worker
./scripts/actualizar.sh --volver               # restaura el respaldo previo a la actualización

• respaldar.sh guarda la base y la configuración, conserva los 7 más recientes y no pisa dos respaldos del mismo día. La clave de cifrado no entra al respaldo: se guarda aparte.
• actualizar.sh no detiene los contenedores de las apps de los clientes: solo reinicia la plataforma.

• Además, Data Lifecycle Manager toma un snapshot diario del disco completo y guarda 7: es la copia fuera del servidor.

Recursos de datos: respaldo y restauración

Cada PostgreSQL, Redis o S3 que crea un cliente es un contenedor deploya-datos-<subdominio>-<tipo> con un volumen del mismo nombre (ADR 0012). El volumen sobrevive a despliegues, reversiones y reinicios; solo se borra al eliminar el recurso o el proyecto dueño.

docker system df -v | grep deploya-datos-               # uso de disco por volumen
C=deploya-datos-nimbo-api-postgres
docker exec $C pg_dump -U deploya -Fc app > app.dump    # respaldo lógico sin detenerlo
docker exec -i $C pg_restore -U deploya -d app --clean < app.dump

Tareas programadas recomendadas

Bitácoras y diagnóstico

docker compose logs -f api         # peticiones, errores de dominio, fallos de SMTP
docker compose logs -f worker      # pipeline de despliegue, docker build, salud
docker compose logs -f traefik     # rutas y emisión del certificado (ACME)
docker compose ps                  # estado y salud de cada servicio

El panel también muestra el estado: Admin · Infraestructura (CPU, memoria y disco del nodo, cola y última muestra de cada entorno) y Admin · Instalación (salud de Docker, DNS, certificado, disco y correo).

Pruebas

Las pruebas unitarias no usan Docker, red, base ni reloj reales: los servicios reciben dobles de sus puertos y un Reloj falso. Cada escenario de OpenSpec tiene su prueba con el mismo nombre.

Solución de problemas

Generar esta documentación

Los cuatro documentos viven como HTML en docs/sitio/doc/, con el design system v4.1 en modo claro, y se publican tal cual en Cloudflare Pages junto con sus PDF. Los diagramas salen de los .mmd de docs/diagramas/.

pnpm diagramas:sync                    # los .md y .mmd al día
node scripts/docs-sitio/construir.mjs  # diagramas, índice con páginas y los cuatro PDF

El script redibuja los diagramas marcados, genera cada PDF con Chromium, numera el índice con las páginas reales (con pdftotext) y vuelve a generar el PDF. El sitio queda en docs/sitio/: Cloudflare Pages lo sirve sin paso de construcción.