Despliegue inicial en Coolify
El entorno de referencia es un VPS Linux con Coolify. Business Central cloud accede a una API pública HTTPS; las tablets usan una PWA pública HTTPS. PostgreSQL y los PDFs permanecen en recursos persistentes del servidor.
Si ya existen los recursos, usa Actualizar en Coolify.
Para la firma visible con certificado, selecciona las imágenes 0.2.16 después de confirmar su publicación e integra AL 1.1.0.0 con los recursos del visor incluidos. La guía de actualización de esta versión explica los cambios necesarios en backend y extensión; esta versión no introduce migraciones ni variables de entorno en ejecución.
Preparar los recursos
Elige tus dominios y una versión de imagen publicada. Los ejemplos usan https://api.example.com y https://tablet.example.com. Configura DNS hacia el servidor y HTTPS en el proxy de Coolify.
| Recurso | Fuente | Puerto interno | Persistencia | Healthcheck interno |
|---|---|---|---|---|
db |
PostgreSQL 16 | 5432, privado |
Datos PostgreSQL | Disponibilidad de PostgreSQL |
api |
ghcr.io/jdmarquezdev/bc-pdf-sign-api:<version> |
8080 |
/app/storage |
HTTP /health |
tablet |
ghcr.io/jdmarquezdev/bc-pdf-sign-tablet:<version> |
8080 |
Sin volumen | HTTP / |
docs, opcional |
Git y docs.Dockerfile |
8080 |
Sin volumen | HTTP / |
Los contenedores sirven HTTP internamente; el proxy termina HTTPS. Configura los checks internos por HTTP al puerto 8080. Para imágenes privadas, prepara antes el acceso a GHCR.
1. Crear PostgreSQL
Crea la base de datos con usuario y contraseña dedicados, volumen persistente y acceso solo por la red interna. Anota su hostname interno real; db en los ejemplos es un marcador, no una dirección garantizada por Coolify.
La API se conecta con DATABASE_URL. Dentro del contenedor, localhost apunta al propio contenedor API, no a PostgreSQL.
2. Crear la API
Crea un recurso Docker Image, elige el repositorio de API y un tag fijo publicado. Configura el dominio HTTPS, el puerto interno 8080 y el volumen en /app/storage, escribible por el usuario del contenedor.
Variables mínimas de ejemplo:
ASPNETCORE_ENVIRONMENT=Production
SWAGGER_ENABLED=true
DATABASE_URL=Host=db;Port=5432;Database=bc_pdf_sign;Username=bcpdfsign;Password=<contraseña>
BC_BEARER_TOKEN=<token-del-entorno>
STORAGE_ROOT=/app/storage
ALLOWED_ORIGINS=https://tablet.example.com
ENABLE_HTTPS_ONLY=true
Introduce secretos en la configuración protegida del backend. Concede acceso de red desde el proxy a la API; el código acepta cabeceras reenviadas de cualquier proxy, por lo que ese acceso debe quedar controlado.
Las migraciones se aplican durante el arranque. Comprueba el log y https://api.example.com/health: debe devolver status: "ok", databaseOk: true y storageOk: true.
La imagen API incluye UANATACA CA1 2021 y ROOT 2016 desde 0.2.14; para esa CA no hay que montar/subir emisores ni añadir variables. BC puede enviar solo la hoja y mantiene su clave privada. Otras entidades usan AIA y el catálogo público; permite la salida DNS/HTTP(S) necesaria o provisiona un respaldo local según Configuración. Las descripciones de estos campos en Swagger se publican desde 0.2.15; confirma la publicación del tag antes de seleccionarlo.
3. Crear la tablet
Crea otro recurso Docker Image con el repositorio de tablet y el tag elegido. Configura HTTPS, puerto 8080 y:
VITE_API_BASE_URL=https://api.example.com
VITE_DEFAULT_DEVICE_ID=
VITE_POLLING_INTERVAL_MS=4000
La configuración se inyecta en runtime-config.js al arrancar el contenedor. Cambiar estas variables requiere redesplegar/recrear el contenedor; no requiere recompilar la imagen. Son valores públicos, nunca tokens.
Abre la PWA desde la tablet. Instálala y sigue Alta inicial.
4. Configurar Business Central
Para firma manuscrita, implementa el flujo de integración BC con el bearer de ese entorno.
Para certificados, copia el código AL completo en tu extensión existente y sigue Integración manual desde AL para compilarla, configurar y firmar. El servidor no necesita PFX, contraseña ni claves privadas.
5. Publicar documentación, si corresponde
Crea un recurso desde Git/Dockerfile con contexto en la raíz y docs.Dockerfile. Configura un dominio y el puerto 8080.
La build instala requirements-docs.txt, ejecuta mkdocs build --strict y sirve el sitio con Nginx. Los cambios de documentación necesitan una reconstrucción propia de este recurso; el workflow de imágenes API/tablet no lo publica.
Antes de usar documentos reales
Comprueba salud, activación de tablet, creación/lectura/firma/descarga y acceso desde BC cloud. Guarda backups de PostgreSQL y /app/storage, y comprueba su restauración en otro entorno. Los resultados tienen retención limitada: BC debe archivarlos donde corresponda al negocio.
El plan de validación distingue pruebas disponibles y validaciones aún pendientes. Esta guía no confirma que producción esté desplegada o validada.
Fallos frecuentes
| Problema | Acción |
|---|---|
PostgreSQL en 127.0.0.1:5432 |
Usar su hostname interno en DATABASE_URL |
| Redirección/HTTPS incorrecto | Revisar dominio, proxy y X-Forwarded-Proto |
| Healthcheck interno con error SSL | Cambiar el check a HTTP en el puerto interno |
PWA llama a 127.0.0.1 |
Corregir VITE_API_BASE_URL y recrear tablet |
| CORS en navegador | Comprobar origen exacto de tablet y ALLOWED_ORIGINS |
| Storage no escribible | Revisar montaje persistente y permisos del usuario del contenedor |
| Descarga GHCR rechazada | Seguir credenciales GHCR |
Para laboratorio sin Coolify, consulta Desarrollo local. compose.yaml expone PostgreSQL, usa credenciales de ejemplo y desactiva HTTPS; necesita adaptación antes de publicarse.