Cómo autoalojar Wiki.js en 2026: configuración de la base de datos, TLS y pruebas de restauración

La mayoría de las notas de instalación de Wiki.js terminan en la primera carga de la página. Es demasiado pronto: DB_HOST es localhost dentro del contenedor o faltan las cabeceras del proxy TLS. Una prueba de producción útil es más exigente: completar la configuración, crear y modificar una página, subir archivos multimedia, buscarlos y consultar el historial de versiones después de reiniciar.

El papel de Wiki.js es sencillo: un wiki en Markdown con control de versiones y un editor moderno. Sus límites operativos abarcan más que el proceso web, por lo que hay que definir explícitamente la dependencia, el estado almacenado y la ruta pública antes de que lleguen datos reales.

Delimita el entorno de ejecución de Wiki.js

La topología mínima responsable de Wiki.js contiene un listener privado en el puerto 3000, una ruta de entrada y un límite de estado documentado. El contrato de red de Wiki.js requiere una base de datos Postgres, MySQL, MariaDB, MSSQL o SQLite accesible. Mantén los endpoints privados en el DNS interno, permite solo las llamadas salientes necesarias y asigna a Wiki.js una credencial de servicio con permisos limitados.

Valida la topología pidiendo a un cliente limpio que complete la configuración, cree y modifique una página, suba archivos multimedia, los busque y consulte el historial de versiones después de reiniciar. Mientras se ejecuta, observa el tiempo de respuesta de la base de datos, la indexación de búsquedas, el almacenamiento multimedia y la latencia del proveedor de autenticación. El resultado indica si la siguiente mejora corresponde a la memoria, el almacenamiento, la red o un worker independiente, en lugar de fomentar un dimensionamiento arbitrario del contenedor.

Diseña la restauración de Wiki.js antes del lanzamiento

No se espera que haya estado de aplicación escribible dentro de la imagen estándar de Wiki.js. Conserva la base de datos y cualquier carga local o recurso personalizado, incluido el digest fijado y la configuración de rutas revisada, en lugar de hacer una copia de seguridad de un sistema de archivos de contenedor vacío.

Crea Wiki.js desde cero en otro host y verifica que regresen las páginas, el historial, los usuarios, los grupos, los archivos multimedia y la navegación, y que una página conocida siga apareciendo en las búsquedas. Si añades una base de datos independiente, un servidor de salas o una capa de autenticación, asigna a cada componente un responsable de recuperación explícito. La guía del repositorio a producción muestra cómo un artefacto reproducible sustituye a una copia de seguridad del contenedor.

Registra el comando de reconstrucción y la prueba con resultados conocidos junto con la release. Un plan de recuperación sin estado funciona al reproducir el comportamiento a partir de entradas fiables; no debe depender de copiar un contenedor opaco en ejecución.

Elige el límite de confianza de Wiki.js

Una implementación segura de Wiki.js comienza eliminando privilegios. Evita mantener expuesta la pantalla de configuración después de crear al primer administrador; en su lugar, elimina el acceso público a la configuración, restringe la administración y asigna al wiki su propia credencial de base de datos.

Trata DB_PASS según su función en Wiki.js: mantén los valores sensibles fuera de Git, documenta los efectos de la rotación y no sustituyas nunca un ejemplo público en producción. Restringe las rutas administrativas, usa DNS privado para las dependencias y revisa cada montaje. Cuando los registros se envíen de forma centralizada, filtra los secretos y el contenido privado antes de que abandonen el servidor.

Qué debe superar Wiki.js antes de recibir datos reales

Una puerta de producción para Wiki.js debe poder ejecutarla alguien que no haya creado la implementación. Dale a esa persona la versión fijada, una cuenta de prueba no sensible y esta tarea: completar la configuración, crear y modificar una página, subir archivos multimedia, buscarlos y consultar el historial de versiones después de reiniciar. Si las instrucciones requieren acceso no documentado al shell, el servicio aún no está listo desde el punto de vista operativo.

Repite la prueba sustituyendo únicamente el contenedor. Después, restaura la base de datos y cualquier carga local o recurso personalizado en una infraestructura vacía y demuestra que regresan las páginas, el historial, los usuarios, los grupos, los archivos multimedia y la navegación, y que una página conocida sigue apareciendo en las búsquedas. Mide el tiempo de respuesta de la base de datos, la indexación de búsquedas, el almacenamiento multimedia y la latencia del proveedor de autenticación durante ambas ejecuciones correctas; las diferencias inesperadas suelen revelar la ausencia de una caché, un índice, un worker o un montaje de datos.

Añade una prueba de fallos: deniega temporalmente a la identidad de prueba el acceso a una base de datos Postgres, MySQL, MariaDB, MSSQL o SQLite accesible. Wiki.js debe emitir un error útil, conservar el estado existente y recuperarse cuando vuelva a cumplirse la condición válida. Guarda las marcas de tiempo y las líneas de registro relevantes, con los secretos redactados. Esa evidencia se convierte en la referencia para la siguiente modificación de imagen o configuración.

Inicia Wiki.js sin ocultar las piezas importantes

Mantén la invocación inicial de Wiki.js lo bastante reproducible como para revisarla en un pull request.

docker run -d \
  --name wiki-js \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e DB_PASS=replace-with-a-long-random-value \
  -e DB_TYPE=postgres \
  -e DB_HOST=postgres.internal \
  -e DB_PORT=5432 \
  -e DB_USER=wiki \
  -e DB_NAME=wiki \
  ghcr.io/requarks/wiki:2

No dependas de latest cuando ya existan datos reales. Captura el digest operativo, el usuario del contenedor y la propiedad de los montajes. Sigue el registro de la aplicación durante una prueba completa —completar la configuración, crear y modificar una página, subir archivos multimedia, buscarlos y consultar el historial de versiones después de reiniciar— y anota cualquier migración antes de poner la ruta detrás del tráfico de producción.

Mantén claras las URL internas y externas

Trata la URL externa de Wiki.js como una configuración que debe sobrevivir a los redeploys. Configura primero la URL del sitio después de enrutar el servicio mediante HTTPS; después, dirige el hostname al puerto 3000 conservando intactos el host y el esquema originales.

La lista de comprobación de accesibilidad de la implementación puede demostrar que las solicitudes entran en el contenedor. A partir de ese punto, el fallo conocido —DB_HOST es localhost dentro del contenedor o faltan las cabeceras del proxy TLS— debe investigarse en Wiki.js, en su estado o en su workload, no en la automatización de certificados.

Observa el workload, no solo el contenedor

Crea dashboards en torno al tiempo de respuesta de la base de datos, la indexación de búsquedas, el almacenamiento multimedia y la latencia del proveedor de autenticación. Un gráfico de CPU sin el contexto de ese workload no puede explicar por qué Wiki.js funciona lentamente. Añade una comprobación sintética o programada que intente completar la configuración, crear y modificar una página, subir archivos multimedia, buscarlos y consultar el historial de versiones después de reiniciar usando datos de prueba inocuos.

Antes de actualizar, ten en cuenta este riesgo específico de la aplicación: las migraciones de base de datos y los módulos de autenticación de Wiki.js deben probarse en staging antes de pasar a otra línea de releases. Restaura una copia de seguridad reciente en una implementación aislada, ejecuta allí las migraciones y compara el comportamiento. Si DB_HOST es localhost dentro del contenedor o faltan las cabeceras del proxy TLS, inspecciona primero el límite implicado —origen público, almacenamiento o dependencia— antes de modificar ajustes no relacionados.

Mantén explícito Wiki.js mientras Dockup gestiona el enrutamiento

El enrutamiento, los certificados, la sustitución de servicios y el almacenamiento asociado son objetivos razonables para la automatización. Dockup los gestiona para Wiki.js y puede aprovisionar la base de datos administrada relacionada o conectarse a servicios en el servidor del cliente.

Lo que no debe inventar es la política de confianza de Wiki.js. Después de la implementación, configura la URL del sitio tras enrutar el servicio mediante HTTPS, aplica este límite —elimina el acceso público a la configuración, restringe la administración y asigna al wiki sus propias credenciales— y verifica el resultado de este escenario: completar la configuración, crear y modificar una página, subir archivos multimedia, buscarlos y consultar el historial de versiones después de reiniciar. El resultado es una infraestructura de un solo clic con una prueba de aceptación específica de la aplicación.

Preguntas frecuentes

¿Qué necesita Wiki.js para una implementación de producción?

Enruta el contenedor de Wiki.js en el puerto 3000 a través de un único origen HTTPS. El requisito de red de soporte es una base de datos Postgres, MySQL, MariaDB, MSSQL o SQLite accesible. No consideres que Wiki.js está listo hasta que puedas completar la configuración, crear y modificar una página, subir archivos multimedia, buscarlos y consultar el historial de versiones después de reiniciar.

¿Qué datos de Wiki.js deben incluirse en una copia de seguridad?

La imagen estándar de Wiki.js no tiene ningún montaje obligatorio para datos de aplicación. Conserva la configuración de la implementación y realiza copias de seguridad de cualquier estado conectado por separado; la recuperación se supera cuando regresan las páginas, el historial, los usuarios, los grupos, los archivos multimedia y la navegación, y una página conocida sigue apareciendo en las búsquedas.

¿Wiki.js requiere HTTPS detrás de un reverse proxy?

Usa HTTPS para el origen público de Wiki.js y mantén el puerto 3000 en la ruta interna. Aplica correctamente el ajuste de Wiki.js: configura la URL del sitio después de enrutar el servicio mediante HTTPS. En Wiki.js, 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 Wiki.js?

Restaura el estado actual de Wiki.js en una implementación aislada, aplica la versión candidata y repite su transacción de aceptación. Presta especial atención porque las migraciones de base de datos y los módulos de autenticación de Wiki.js deben probarse en staging antes de pasar a otra línea de releases. Conserva la imagen anterior de Wiki.js hasta comprender los límites de migración de datos y de rollback.