Cómo autoalojar Vikunja en 2026: URL pública, base de datos y almacenamiento de archivos

Si ya has intentado autoalojar Vikunja, probablemente te resulte familiar esta situación frustrante: la interfaz aparece, pero la URL pública de la API es incorrecta o los archivos subidos no están en un volumen. Recrear el contenedor rara vez resuelve un desacuerdo entre las URL, el estado y las dependencias.

Esta guía utiliza un único criterio concreto para considerar la tarea completada: crear un proyecto, una tarea, un archivo adjunto y un recordatorio; mover la tarea en un tablero; y verificar su evento de calendario y su notificación. Cada decisión de configuración se evalúa según ese criterio, no según un indicador verde del contenedor.

De qué depende Vikunja

Establece tres límites alrededor de Vikunja: la entrada al puerto 3456, el estado persistente y los requisitos de soporte. El contenedor se puede reemplazar, pero los otros dos elementos necesitan responsables explícitos. El contrato de red de Vikunja para equipos en producción requiere Postgres o MySQL y SMTP. Mantén los endpoints privados en DNS interno, permite únicamente las llamadas salientes necesarias y proporciona a Vikunja una credencial de servicio con permisos limitados.

El diagrama está completo cuando un cliente limpio puede crear un proyecto, una tarea, un archivo adjunto y un recordatorio; mover la tarea en un tablero; y verificar su evento de calendario y su notificación. Recopila datos de tiempos y recursos para el tráfico de archivos adjuntos, las consultas a la base de datos, los trabajos en segundo plano y el correo saliente, en lugar de observar únicamente el pequeño proceso de la API. Si la transacción falla, el primer límite que no se comporte como está documentado indica si debes investigar el enrutamiento, la capacidad local o un servicio de soporte.

Los volúmenes son solo la primera capa de recuperación

Enumera el estado antes de crear el primer registro real: la base de datos, los archivos subidos y la configuración. Monta /app/vikunja/files antes del bootstrap, escribe datos de ejemplo inocuos y reemplaza el contenedor para demostrar que esa ruta es realmente persistente. Confirma el montaje escribiendo datos inocuos, reemplazando Vikunja y volviendo a leerlos.

Las snapshots son útiles para volver atrás rápidamente, pero necesitas una copia de seguridad independiente cuando el host o el volumen desaparecen. Restaura en un entorno vacío con la imagen fijada y verifica que vuelven los proyectos, el historial de tareas, los archivos adjuntos, los recordatorios y los usuarios, y que una notificación programada sigue activándose. Usa volúmenes persistentes y snapshots para mantener diferenciados estos dos mecanismos de recuperación.

Protege la parte valiosa de Vikunja

Después del primer inicio de sesión, revisa qué puede hacer un visitante anónimo, un usuario normal y un administrador. El fallo de Vikunja que debes evitar es utilizar un secreto JWT sin cambiar o dejar abierto el registro de usuarios por accidente. La política prevista consiste en usar un secreto JWT estable, cerrar el registro cuando termine la incorporación de usuarios y separar a los miembros normales de los administradores de proyectos.

Genera VIKUNJA_SERVICE_JWTSECRET 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. Mantén separadas las cuentas de dependencias de las cuentas humanas, deniega el tráfico saliente que no utilices cuando sea práctico y limita el trabajo que puedan provocar el tráfico de archivos adjuntos, las consultas a la base de datos, los trabajos en segundo plano y el correo saliente, en lugar de limitar únicamente el pequeño proceso de la API.

Convierte la prueba de humo de Vikunja en una comprobación de lanzamiento

Una release candidate de Vikunja se gana el tráfico al completar un escenario fijo: crear un proyecto, una tarea, un archivo adjunto y un recordatorio; mover la tarea en un tablero; y verificar su evento de calendario y su notificación. Captura el digest de la imagen, la configuración efectiva sin secretos, el origen público y las marcas de tiempo de ese escenario. Los datos de prueba deben poder desecharse, pero ser suficientemente realistas como para ejercitar la misma ruta que utilizan los usuarios.

Ejecútalo después de reemplazar el runtime y, a continuación, vuelve a compilar el servicio a partir de la base de datos, los archivos subidos y la configuración. La recuperación es correcta cuando vuelven los proyectos, el historial de tareas, los archivos adjuntos, los recordatorios y los usuarios, y una notificación programada sigue activándose. Compara con la release anterior las mediciones de recursos del tráfico de archivos adjuntos, las consultas a la base de datos, los trabajos en segundo plano y el correo saliente, en lugar de comparar únicamente el pequeño proceso de la API, e investiga cualquier desviación significativa antes de promocionarla.

Por último, simula este fallo controlado: deniega temporalmente a la identidad de prueba el acceso a Postgres o MySQL y SMTP para equipos en producción. Verifica que Vikunja explica el fallo, no daña el estado existente y se recupera cuando vuelve a cumplirse la condición válida. Guarda un fragmento de log anonimizado y el tiempo de recuperación. En conjunto, estas comprobaciones cubren el comportamiento, la durabilidad y la operabilidad, no solo que el proceso esté activo.

Crea un contenedor de Vikunja reemplazable

El siguiente comando hace visible el límite del contenedor sin fingir que aprovisiona todos los servicios externos.

docker run -d \
  --name vikunja \
  --restart unless-stopped \
  -p 127.0.0.1:3456:3456 \
  -v vikunja-data:/app/vikunja/files \
  -e VIKUNJA_SERVICE_JWTSECRET=replace-with-a-long-random-value \
  vikunja/vikunja:latest

Antes de abrir la entrada, inspecciona el entorno resuelto, los montajes y el listener. Añade la configuración de conexión revisada para Postgres o MySQL y SMTP para equipos en producción; utiliza nombres privados para los servicios privados. Un lanzamiento correcto termina cuando puedes crear un proyecto, una tarea, un archivo adjunto y un recordatorio; mover la tarea en un tablero; y verificar su evento de calendario y su notificación, no cuando docker ps muestra Up.

Enruta Vikunja sin falsear el uso de HTTPS

Evita utilizar orígenes públicos temporales y permanentes para Vikunja. En su lugar, establece VIKUNJA_SERVICE_PUBLICURL con el origen HTTPS exacto, apunta el nombre DNS elegido a la ruta de la plataforma y usa el proxy únicamente hacia el puerto 3456.

Ejecuta esta acción desde fuera del host: crea un proyecto, una tarea, un archivo adjunto y un recordatorio; mueve la tarea en un tablero; y verifica su evento de calendario y su notificación. Si la entrada falla, la guía de resolución de problemas de 502 cubre los errores de puertos y listeners. Si Vikunja recibe la solicitud, pero la URL pública de la API es incorrecta o los archivos subidos no están en un volumen, las pruebas apuntan ahora a un problema más allá del proxy.

Diagnostica un Vikunja que parece estar saludable

En Vikunja, supervisa una transacción en lugar de un proceso: crea un proyecto, una tarea, un archivo adjunto y un recordatorio; mueve la tarea en un tablero; y verifica su evento de calendario y su notificación. Combina su latencia y tasa de errores con el tráfico de archivos adjuntos, las consultas a la base de datos, los trabajos en segundo plano y el correo saliente, en lugar de observar únicamente el pequeño proceso de la API, para que una alerta identifique el componente limitado.

El ensayo de actualización debe cubrir que las migraciones de la base de datos y la compatibilidad entre frontend y API deben probarse antes de cambiar las versiones de Vikunja. Restaura, migra y ejecuta la transacción antes de reemplazar la versión en producción. Si la URL pública de la API es incorrecta o los archivos subidos no están en un volumen, no borres los datos para que el arranque aparezca en verde; compara, en este orden, la versión, las variables, los montajes y la accesibilidad de las dependencias.

Despliega Vikunja en Dockup sin perder sus límites

Dockup puede encargarse de las piezas reemplazables de la plataforma: dirigir el tráfico al puerto 3456, emitir el dominio y el certificado, inyectar secretos, conectar el almacenamiento persistente y conectar Vikunja con servicios gestionados o conectados de forma privada. Puede hacerlo en la infraestructura de Dockup o en un servidor que conectes.

El trabajo de aceptación de Vikunja sigue siendo explícito. Después del despliegue con un clic, establece VIKUNJA_SERVICE_PUBLICURL con el origen HTTPS exacto, conecta y prueba Postgres o MySQL y SMTP para equipos en producción, y ejecuta este escenario: crea un proyecto, una tarea, un archivo adjunto y un recordatorio; mueve la tarea en un tablero; y verifica su evento de calendario y su notificación. Esta división es intencionada: Dockup elimina la configuración repetitiva de la infraestructura sin fingir que los roles de la aplicación, las credenciales del proveedor o la política de restauración se eligen por sí solos.

Preguntas frecuentes

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

Enruta el contenedor de Vikunja en el puerto 3456 a través de un único origen HTTPS. El requisito de red de soporte es Postgres o MySQL y SMTP para equipos en producción. No consideres Vikunja listo hasta que puedas crear un proyecto, una tarea, un archivo adjunto y un recordatorio; mover la tarea en un tablero; y verificar su evento de calendario y su notificación.

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

Haz persistir /app/vikunja/files e incluye la base de datos, los archivos subidos y la configuración en el mismo manifiesto de recuperación. Una restauración limpia de Vikunja solo es correcta cuando vuelven los proyectos, el historial de tareas, los archivos adjuntos, los recordatorios y los usuarios, y una notificación programada sigue activándose.

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

Utiliza HTTPS para el origen público de Vikunja y mantén el puerto 3456 en la ruta interna. Aplica correctamente la configuración de Vikunja: establece VIKUNJA_SERVICE_PUBLICURL con el origen HTTPS exacto. En Vikunja, HTTPS protege las credenciales o el contenido de los usuarios durante el tránsito y mantiene coherente el comportamiento del cliente que depende del origen.

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

Restaura el estado actual de Vikunja 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 compatibilidad entre frontend y API deben probarse antes de cambiar las versiones de Vikunja. Conserva la imagen anterior de Vikunja hasta comprender los límites de migración de datos y rollback.