Cómo autoalojar HedgeDoc en 2026: WebSockets, OAuth y archivos subidos

Hay dos versiones de «ejecutar HedgeDoc»: existe un contenedor o el servicio cumple realmente su función. Solo importa la segunda. En este caso, la prueba consiste en crear una nota, editarla simultáneamente desde dos navegadores, subir una imagen y autenticarse mediante el proveedor seleccionado.

HedgeDoc sirve para esto: notas Markdown colaborativas en tiempo real. La implementación debe conservar los componentes que hacen posible ese comportamiento; un puerto, un volumen y un certificado son elementos de entrada, no el resultado.

Haz copias de seguridad del estado que HedgeDoc no puede recrear

Define el punto y el tiempo objetivo de recuperación de HedgeDoc en términos de base de datos, archivos subidos y configuración de autenticación. Monta /hedgedoc/public/uploads antes del bootstrap, escribe datos de ejemplo sin importancia y sustituye el contenedor para demostrar que esa ruta es realmente persistente. Un volumen con nombre resuelve la persistencia entre redespliegues, pero no los problemas derivados de una intrusión o de la pérdida del servidor.

Prepara un entorno de restauración limpio, usa la misma versión fijada de la aplicación y demuestra que las notas, revisiones, usuarios y archivos subidos regresan, y que dos navegadores pueden colaborar en la nota restaurada. Registra los comandos, las correcciones de propietario y el tiempo transcurrido. La guía de copias de seguridad es un estándar útil: una copia de seguridad se considera fiable después de restaurarla, no después de subirla.

Separa HedgeDoc de sus dependencias

El estado del proceso y el estado del producto son aspectos independientes en HedgeDoc. El puerto 3000 puede responder mientras la transacción visible para el usuario sigue fallando. El contrato de red de HedgeDoc es Postgres, además de proveedores opcionales de OAuth y SMTP. Mantén los endpoints privados en DNS interno, permite solo las llamadas salientes necesarias y proporciona a HedgeDoc una credencial de servicio con permisos limitados.

Usa este ejercicio de readiness después de cambios importantes de configuración: crea una nota, edítala simultáneamente desde dos navegadores, sube una imagen y autentícate mediante el proveedor seleccionado. Mantén las comprobaciones externas costosas fuera de los probes de liveness para que una interrupción del proveedor no provoque un bucle de reinicios. El trabajo de capacidad debe hacer seguimiento de las conexiones WebSocket, las escrituras en la base de datos, los archivos multimedia subidos y el historial de documentos, ya que esto se aproxima más a la presión real de HedgeDoc que las solicitudes de página.

Cinco comprobaciones más sólidas que la salud del contenedor

Convierte la smoke test de HedgeDoc en un comando de release repetible o en un runbook breve. Su salida debe demostrar este resultado: crear una nota, editarla simultáneamente desde dos navegadores, subir una imagen y autenticarse mediante el proveedor seleccionado. Registra con el resultado la versión de la aplicación, el digest del contenedor, el hostname de la ruta y el identificador de los datos de prueba.

Ejecuta la misma comprobación después de sustituir un contenedor como parte de una operación rutinaria y después de restaurar la base de datos, los archivos subidos y la configuración de autenticación en otro lugar. La restauración se habrá completado correctamente cuando regresen las notas, revisiones, usuarios y archivos subidos, y dos navegadores puedan colaborar en la nota restaurada. Compara los tiempos y el consumo relacionados con las conexiones WebSocket, las escrituras en la base de datos, los archivos multimedia subidos y el historial de documentos; un cambio importante merece investigación aunque la acción final siga superándose.

Después, prueba un fallo seguro: deniega temporalmente a la identidad de prueba el acceso a Postgres, además de a los proveedores opcionales de OAuth y SMTP. Confirma que HedgeDoc muestra el error y vuelve a la normalidad sin cambios manuales destructivos. Conserva únicamente el fragmento de log necesario y con los datos sensibles eliminados. Este control de cuatro partes cubre el arranque, la persistencia, la recuperación y la gestión de fallos.

Inicia HedgeDoc sin ocultar los componentes importantes

Un comando mínimo resulta útil cuando deja claro qué gestionará posteriormente la plataforma.

docker run -d \
  --name hedgedoc \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v hedgedoc-data:/hedgedoc/public/uploads \
  -e CMD_SESSION_SECRET=replace-with-a-long-random-value \
  -e CMD_DOMAIN=app.example.com \
  -e CMD_PROTOCOL_USESSL=true \
  -e CMD_DB_URL=postgres://hedgedoc:replace-password@postgres.internal:5432/hedgedoc \
  quay.io/hedgedoc/hedgedoc:latest

Aquí el puerto 3000 permanece privado para el host y todas las rutas necesarias están declaradas explícitamente. Añade la configuración de conexión revisada para Postgres, además de los proveedores opcionales de OAuth y SMTP; usa nombres privados para los servicios privados. Verifica el arranque tanto con los logs como con la prueba específica de la aplicación: crea una nota, edítala simultáneamente desde dos navegadores, sube una imagen y autentícate mediante el proveedor seleccionado. Una vez verificado, fija la versión de la imagen para que una sustitución rutinaria no cambie el comportamiento silenciosamente.

No des a HedgeDoc acceso a todo el host

En HedgeDoc, la superficie valiosa no es necesariamente la página de inicio. El error principal consiste en usar un session secret de ejemplo o permitir sin querer la creación anónima de notas. Contrarréstalo de forma deliberada: usa un session secret estable, decide si la creación anónima de notas es aceptable y restringe el acceso a las notas privadas.

Genera CMD_SESSION_SECRET como un valor aleatorio largo; rotarlo normalmente invalida las sesiones o los tokens, así que planifica el impacto para los usuarios en lugar de tratarlo como una migración de cifrado. Usa un usuario de contenedor sin privilegios cuando la imagen lo admita y no montes credenciales que no estén relacionadas. Aplica límites de rate o de tamaño en el ingress, donde el trabajo no confiable puede consumir conexiones WebSocket, escrituras en la base de datos, archivos multimedia subidos e historial de documentos.

Prueba HedgeDoc desde fuera del servidor

Elige el hostname definitivo de HedgeDoc antes de que los usuarios guarden callbacks o configuraciones del cliente; después, establece CMD_DOMAIN y CMD_PROTOCOL_USESSL para la URL pública. La ruta de la plataforma debe terminar TLS una sola vez y apuntar al puerto privado 3000.

Ejecuta la transacción de aceptación desde el exterior. Si el cliente nunca llega a HedgeDoc, usa la lista de comprobación de validación SSL para revisar el DNS y el certificado. Si la solicitud llega a HedgeDoc, pero la edición en tiempo real falla porque WebSockets o la configuración del dominio son incorrectos, deja de cambiar las redirecciones del proxy e inspecciona el límite específico de la aplicación.

Opera HedgeDoc en torno a su cuello de botella real

Usa crear una nota, editarla simultáneamente desde dos navegadores, subir una imagen y autenticarte mediante el proveedor seleccionado como smoke test de HedgeDoc después de cada despliegue. Sus métricas de soporte son las conexiones WebSocket, las escrituras en la base de datos, los archivos multimedia subidos y el historial de documentos; configura alertas cuando esos recursos se acerquen a un punto que degrade la acción del usuario.

El principal riesgo de cambio es que las migraciones de la base de datos de HedgeDoc, la configuración de OAuth y los cambios en plugins o renderers requieren un release gradual. Un release seguro parte de una snapshot restaurable y valida cualquier cambio de estado unidireccional antes de desviar el tráfico. Cuando la edición en tiempo real falla porque WebSockets o la configuración del dominio son incorrectos, conserva el contenedor fallido el tiempo suficiente para leer su configuración y el primer error.

Cómo Dockup elimina trabajo para HedgeDoc

Dockup puede encargarse de los componentes reemplazables de la plataforma: dirigir el tráfico al puerto 3000, emitir el dominio y el certificado, inyectar secrets, adjuntar almacenamiento persistente y conectar HedgeDoc con servicios gestionados o asociados de forma privada. Puede hacerlo en la infraestructura de Dockup o en un servidor que asocies.

El trabajo de aceptación de HedgeDoc sigue siendo explícito. Después del despliegue con un clic, establece CMD_DOMAIN y CMD_PROTOCOL_USESSL para la URL pública, conecta y prueba Postgres, además de los proveedores opcionales de OAuth y SMTP, y ejecuta este escenario: crea una nota, edítala simultáneamente desde dos navegadores, sube una imagen y autentícate mediante el proveedor seleccionado. Esta división es intencionada: Dockup elimina la configuración repetitiva de la infraestructura sin pretender que los roles de la aplicación, las credenciales de los proveedores o la política de restauración se elijan por sí solos.

Preguntas frecuentes

¿Qué necesita HedgeDoc para un despliegue en producción?

Dirige el contenedor de HedgeDoc en el puerto 3000 a través de un único origen HTTPS. El requisito de red complementario es Postgres, además de los proveedores opcionales de OAuth y SMTP. No consideres que HedgeDoc está listo hasta que puedas crear una nota, editarla simultáneamente desde dos navegadores, subir una imagen y autenticarte mediante el proveedor seleccionado.

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

Conserva /hedgedoc/public/uploads e incluye la base de datos, los archivos subidos y la configuración de autenticación en el mismo manifiesto de recuperación. Una restauración limpia de HedgeDoc solo se considera correcta cuando regresan las notas, revisiones, usuarios y archivos subidos, y dos navegadores pueden colaborar en la nota restaurada.

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

Usa HTTPS para el origen público de HedgeDoc y mantén el puerto 3000 en la ruta interna. Aplica correctamente la configuración de HedgeDoc: establece CMD_DOMAIN y CMD_PROTOCOL_USESSL para la URL pública. En HedgeDoc, HTTPS protege las credenciales o el contenido de los usuarios durante el tránsito y mantiene coherente el comportamiento del cliente sensible al origen.

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

Restaura el estado actual de HedgeDoc 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 de HedgeDoc, la configuración de OAuth y los cambios en plugins o renderers requieren un release gradual. Conserva la imagen anterior de HedgeDoc hasta comprender los límites de la migración de datos y del rollback.