Cómo autoalojar DocuSeal en 2026: enlaces de firma, SMTP y datos de auditoría

La mayoría de las guías de instalación de DocuSeal terminan cuando se carga la primera página. Es demasiado pronto: los enlaces de correo pueden apuntar a localhost o los encabezados del proxy pueden hacer que fallen las cookies seguras. Una prueba de producción útil es más exigente: subir una plantilla, colocar campos, enviar una solicitud de firma, completarla y descargar tanto el documento firmado como la información de auditoría.

La función de DocuSeal es sencilla: firmar documentos con un historial de firma auditable. Sus límites operativos abarcan más que el proceso web, por lo que la dependencia, el estado almacenado y la ruta pública deben definirse explícitamente antes de que lleguen datos reales.

La arquitectura de producción de DocuSeal

Define tres límites alrededor de DocuSeal: la entrada al puerto 3000, el estado persistente y los requisitos de soporte. El contenedor se puede sustituir, pero los otros dos elementos necesitan responsables explícitos. El contrato de red de DocuSeal es SMTP, además de una base de datos y almacenamiento de archivos persistentes. Mantén los endpoints privados en DNS interno, permite únicamente las conexiones salientes necesarias y proporciona a DocuSeal una credencial de servicio con permisos limitados.

El diagrama está completo cuando un cliente limpio puede subir una plantilla, colocar campos, enviar una solicitud de firma, completarla y descargar tanto el documento firmado como la información de auditoría. Recopila datos de tiempos y recursos relacionados con el almacenamiento de documentos, el procesamiento de PDF, la entrega de correo, los firmantes simultáneos y las transacciones de la base de datos. Si la transacción falla, el primer límite que no se comporte como está documentado indicará si debes investigar el enrutamiento, la capacidad local o un servicio de soporte.

Diseña la restauración de DocuSeal antes del lanzamiento

Protege el estado de DocuSeal antes de optimizar su contenedor. El conjunto necesario incluye la base de datos, los archivos firmados, las plantillas y los eventos de auditoría. Monta /data antes del bootstrap, escribe datos de ejemplo no sensibles y sustituye el contenedor para demostrar que esa ruta es realmente persistente. Si varios almacenes deben mantenerse coherentes, documenta el orden en el que se pausan las escrituras y se realizan las copias de seguridad.

Conserva copias fuera del servidor de despliegue y cifra el material que contenga credenciales o contenido privado. La recuperación es correcta cuando vuelven las plantillas, los envíos, los archivos firmados y los eventos de auditoría, y un envío completado sigue siendo verificable. La diferencia entre un volumen persistente y una copia independiente se explica en almacenamiento persistente y snapshots.

Cierra el acceso temporal de configuración

Analiza las amenazas de la acción que realiza DocuSeal, no solo las de su formulario de inicio de sesión. En este caso, el error de mayor riesgo es cambiar SECRET_KEY_BASE o considerar que copiar un archivo equivale a disponer de una copia de seguridad de auditoría completa. Implementa este límite: limita la administración de plantillas, protege los datos de los firmantes y establece el host HTTPS externo antes de enviar enlaces.

Genera SECRET_KEY_BASE una sola vez, mantenlo fuera de Git y consérvalo junto con el manifiesto de recuperación, porque cambiarlo puede invalidar el estado cifrado o firmado de la aplicación. No soluciones un error de permisos ejecutando el contenedor como root o montando el host de forma generalizada. Los límites de recursos también forman parte del diseño de seguridad cuando los usuarios pueden activar el almacenamiento de documentos, el procesamiento de PDF, la entrega de correo, los firmantes simultáneos y las transacciones de la base de datos.

Registra un despliegue de DocuSeal que funcione

Convierte la prueba de humo de DocuSeal en un comando de release repetible o en un runbook breve. Su resultado debe demostrar lo siguiente: subir una plantilla, colocar campos, enviar una solicitud de firma, completarla y descargar tanto el documento firmado como la información de auditoría. Registra la versión de la aplicación, el digest de la imagen, el hostname de la ruta y el identificador de los datos de prueba junto con el resultado.

Ejecuta la misma comprobación después de sustituir el contenedor como parte de una operación rutinaria y después de restaurar en otro lugar la base de datos, los archivos firmados, las plantillas y los eventos de auditoría. La restauración se ha realizado correctamente cuando vuelven las plantillas, los envíos, los archivos firmados y los eventos de auditoría, y un envío completado sigue siendo verificable. Compara los tiempos y el consumo relacionados con el almacenamiento de documentos, el procesamiento de PDF, la entrega de correo, los firmantes simultáneos y las transacciones de la base de datos; un cambio importante merece investigación aunque la acción final siga funcionando.

A continuación, provoca un fallo seguro: deniega temporalmente a la identidad de prueba el acceso a SMTP, a la base de datos persistente y al almacenamiento de archivos. Confirma que DocuSeal muestra el error y vuelve a la normalidad sin modificaciones manuales destructivas. Conserva únicamente el fragmento de log necesario y con los datos sensibles redactados. Este control en cuatro partes cubre el arranque, la persistencia, la recuperación y la gestión de fallos.

Una configuración base de Docker para DocuSeal

Inicia DocuSeal de forma que la ruta permanezca privada hasta completar el bootstrap.

docker run -d \
  --name docuseal \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v docuseal-data:/data \
  -e SECRET_KEY_BASE=replace-with-a-long-random-value \
  docuseal/docuseal:latest

Si el proceso entra en un bucle, compara el usuario esperado por la imagen con el propietario de cada ruta montada. Si permanece activo, prueba localmente el puerto 3000 y pasa directamente al flujo de trabajo: subir una plantilla, colocar campos, enviar una solicitud de firma, completarla y descargar tanto el documento firmado como la información de auditoría. Fija la versión de la imagen solo después de que esta comprobación de extremo a extremo se complete correctamente y registra la configuración exacta junto al servicio.

Evita que el proxy oculte un fallo de la aplicación

Trata la URL externa de DocuSeal como una configuración que debe sobrevivir a los redeploys. Primero establece el host de la aplicación y la configuración de HTTPS antes de enviar enlaces de firma; después dirige el hostname al puerto 3000 conservando intactos el host y el esquema originales.

La lista de comprobación de accesibilidad del despliegue puede demostrar que las solicitudes entran en el contenedor. A partir de ahí, el fallo conocido —los enlaces de correo apuntan a localhost o los encabezados del proxy hacen que fallen las cookies seguras— debe investigarse en DocuSeal, en su estado o en su carga de trabajo, no en la automatización de certificados.

Ensaya el cambio de DocuSeal de mayor riesgo

Un contenedor en estado correcto es necesario, pero no suficiente. El indicador de nivel de servicio es completar correctamente «subir una plantilla, colocar campos, enviar una solicitud de firma, completarla y descargar tanto el documento firmado como la información de auditoría», mientras que las señales de presión más probables son el almacenamiento de documentos, el procesamiento de PDF, la entrega de correo, los firmantes simultáneos y las transacciones de la base de datos.

El control de cambios es importante porque las migraciones de la base de datos y la continuidad de SECRET_KEY_BASE deben probarse: los archivos firmados por sí solos no reconstruyen el historial de auditoría. Conserva la imagen anterior, prueba las migraciones con una copia del estado y documenta si se admite el rollback después de modificar el esquema. Si los enlaces de correo apuntan a localhost o los encabezados del proxy hacen que fallen las cookies seguras, diagnostica el primer límite que difiera del entorno funcional.

Integra DocuSeal en el ciclo de vida de Dockup

La capa de plataforma de DocuSeal está formada por el puerto 3000, la entrada, TLS, la configuración de ejecución, el almacenamiento y la accesibilidad de las dependencias. Dockup puede reproducir esas piezas en su propia infraestructura o en un servidor que conecte el cliente.

Después, el operador completa la capa de producto: establece el host de la aplicación y la configuración de HTTPS antes de enviar enlaces de firma; aplica esta regla de acceso —limita la administración de plantillas, protege los datos de los firmantes y establece el host HTTPS externo antes de enviar enlaces—; y ejecuta «subir una plantilla, colocar campos, enviar una solicitud de firma, completarla y descargar tanto el documento firmado como la información de auditoría». Registrar esa prueba junto con el despliegue evita confundir el aprovisionamiento automatizado con la disponibilidad de la aplicación.

Preguntas frecuentes

¿Qué necesita DocuSeal para un despliegue de producción?

Dirige el contenedor de DocuSeal del puerto 3000 a través de un único origen HTTPS. El requisito de red de soporte es SMTP, además de una base de datos y almacenamiento de archivos persistentes. No consideres que DocuSeal está listo hasta que puedas subir una plantilla, colocar campos, enviar una solicitud de firma, completarla y descargar tanto el documento firmado como la información de auditoría.

¿Qué datos de DocuSeal deben incluirse en una copia de seguridad?

Haz persistente /data e incluye la base de datos, los archivos firmados, las plantillas y los eventos de auditoría en el mismo manifiesto de recuperación. Una restauración limpia de DocuSeal solo es correcta cuando vuelven las plantillas, los envíos, los archivos firmados y los eventos de auditoría, y un envío completado sigue siendo verificable.

¿DocuSeal necesita HTTPS detrás de un reverse proxy?

Usa HTTPS para el origen público de DocuSeal y mantén el puerto 3000 en la ruta interna. Aplica correctamente la configuración de DocuSeal: establece el host de la aplicación y la configuración de HTTPS antes de enviar enlaces de firma. En DocuSeal, HTTPS protege las credenciales o el contenido del usuario durante el tránsito y mantiene coherente el comportamiento del cliente sensible al origen.

¿Cómo debe probarse una actualización de DocuSeal?

Restaura el estado actual de DocuSeal en un despliegue aislado, aplica la versión candidata y repite su transacción de aceptación. Presta especial atención, porque las migraciones de la base de datos y la continuidad de SECRET_KEY_BASE deben probarse: los archivos firmados por sí solos no reconstruyen el historial de auditoría. Conserva la imagen anterior de DocuSeal hasta comprender los límites de la migración de datos y del rollback.