Alojar Vikunja en un VPS administrado significa guardar las tareas y los proyectos de su equipo en una máquina propia, que nuestros equipos mantienen actualizada y supervisan día y noche. Vikunja es software libre con licencia AGPL-3.0. Esta guía sigue su documentación oficial: la elección de la base de datos, la instalación con Docker Compose, la URL pública y el secreto, las cuentas, HTTPS, los ajustes propios de Vikunja, el correo, las copias de seguridad y las actualizaciones.
Por Simon Vasconcelos Lee
Publicado el 19 de noviembre de 202613 minutos de lectura
vikunja/vikunja:2.8.0 y PostgreSQL, con el puerto 3456 publicado en 127.0.0.1 detrás de un proxy inverso en HTTPS.service.publicurl, la dirección HTTPS de su instancia, y service.secret, que firma las sesiones.files a la vez, antes de cada actualización; las migraciones de la base se ejecutan solas al arrancar.Vikunja es un gestor de tareas y de proyectos de código abierto y autoalojado, que su repositorio describe como «el gestor de tareas que realmente le pertenece». La API, escrita en Go, y la interfaz web van en un solo binario, o en una sola imagen Docker: solo hay una cosa que instalar.
Vikunja se publica bajo la GNU AGPL versión 3 o posterior, salvo la carpeta desktop/ de su repositorio, la aplicación de escritorio, que está bajo la GPL versión 3 o posterior. Puede usarlo, también en una empresa, para su equipo y para sus clientes, sin ninguna licencia que comprar. Queda el coste del servidor que lo ejecuta.
La sección 13 añade una condición propia de la AGPL: si modifica el programa, su versión debe ofrecer de forma visible a todas las personas que interactúan con ella a distancia, a través de una red, la posibilidad de obtener su código fuente, de forma gratuita. Si distribuye copias, se aplican también las obligaciones de la licencia sobre el código fuente. Ejecutar Vikunja sin modificarlo no activa esta sección.
Esta guía instala esa edición de código abierto, que la documentación presenta como plenamente funcional por sí sola. Vikunja Pro, una licencia opcional, añade para las organizaciones un panel de administración, el registro del tiempo dedicado y registros de auditoría.
Vikunja funciona con SQLite, PostgreSQL, MySQL o MariaDB. La documentación no da ninguna cifra de memoria ni de procesador; orienta la elección de la base de datos según el número de usuarios:
| Base de datos | Lo que dice la documentación | Versión probada en la integración continua |
|---|---|---|
| SQLite | Incluida en el binario y en la imagen Docker, sin nada que instalar. Más allá de unos pocos usuarios, la documentación recomienda MySQL o PostgreSQL. | La incluida |
| PostgreSQL | La base de los ejemplos Docker de la documentación. Desde la 2.8.0, la búsqueda ignora los acentos con la extensión unaccent. | 18 |
| MySQL, MariaDB | MySQL 8.0 como mínimo, ya que la 5.7 no es compatible. Para los caracteres no latinos, la base debe usar utf8mb4. | MySQL 8, MariaDB 12 |
La documentación recomienda una versión de la base de datos que siga teniendo mantenimiento. Redis puede servir de caché, pero señala que probablemente no lo necesitará mientras la instancia tenga solo unos pocos usuarios: esta guía prescinde de él.
El espacio en disco depende sobre todo de sus archivos adjuntos y de los fondos de proyecto, guardados en la carpeta files, con 20 MB por archivo como máximo por defecto. En un VPS administrado, cuéntenos cómo es su equipo, su número de usuarios y cuánto recurre a los archivos adjuntos, y le recomendamos el tamaño adecuado.
La documentación instala Vikunja y PostgreSQL con Docker Compose. En un servidor con Docker instalado, cree una carpeta y genere primero el secreto de la instancia, un valor aleatorio que pegará en el archivo:
openssl rand -hex 32
Coloque después en la carpeta este docker-compose.yml, tomado del ejemplo PostgreSQL de la documentación. Sustituya tasks.example.com por su nombre de dominio, paste-your-secret-here por el valor generado y changeme por una contraseña robusta, la misma en los dos sitios:
services:
vikunja:
image: vikunja/vikunja:2.8.0
environment:
VIKUNJA_SERVICE_PUBLICURL: https://tasks.example.com/
VIKUNJA_SERVICE_SECRET: paste-your-secret-here
VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff
VIKUNJA_DATABASE_TYPE: postgres
VIKUNJA_DATABASE_HOST: db
VIKUNJA_DATABASE_USER: vikunja
VIKUNJA_DATABASE_PASSWORD: changeme
VIKUNJA_DATABASE_DATABASE: vikunja
ports:
- "127.0.0.1:3456:3456"
volumes:
- ./files:/app/vikunja/files
depends_on:
db:
condition: service_healthy
restart: unless-stopped
db:
image: postgres:18
environment:
POSTGRES_USER: vikunja
POSTGRES_PASSWORD: changeme
volumes:
- ./db:/var/lib/postgresql
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
interval: 30s
start_period: 15s
start_interval: 5s
Vikunja se ejecuta con el usuario 1000: cree la carpeta files y entréguesela antes del primer arranque, como pide la documentación, y arranque después los servicios:
mkdir files
sudo chown 1000 files
docker compose up -d
docker compose logs vikunja
En el primer arranque, Vikunja crea su base de datos y ejecuta todas sus migraciones. La línea http server started on [::]:3456 en los registros indica que está listo, y curl http://127.0.0.1:3456/api/v1/info, ejecutado en el servidor, devuelve su versión y sus ajustes públicos.
127.0.0.1: es aquí donde nos apartamos de los ejemplos de la documentación, que publican el puerto en todas las direcciones. Su lista de refuerzo de la seguridad pide que solo el proxy inverso pueda llegar a Vikunja: la interfaz se abre entonces a través de él, en HTTPS.VIKUNJA_SERVICE_PUBLICURL: la dirección HTTPS que abren sus usuarios, con la barra final. Vikunja la usa para construir sus enlaces, en los correos por ejemplo, y como origen CORS autorizado, activo por defecto: este ajuste es, por tanto, obligatorio. Una dirección errónea, a la que le falta el puerto por ejemplo, se manifiesta con un error «unauthorized» al crear la primera cuenta.VIKUNJA_SERVICE_SECRET firma los tokens de sesión. Si se deja vacío, se genera al azar en cada arranque, y cada reinicio cierra entonces la sesión de todos los usuarios.2.8.0 fija la versión, como recomienda la documentación, para que las actualizaciones lleguen cuando usted lo decida. latest sigue la última versión estable, y unstable las compilaciones de desarrollo.files y db guardan en el servidor los archivos adjuntos y los datos de PostgreSQL: son lo que se copia.scratch. docker exec hacia un shell no funciona, y las variables PUID y PGID de otras imágenes no tienen ningún efecto sobre ella. Los errores se leen con docker compose logs vikunja.Para unos pocos usuarios, la documentación propone SQLite: elimine el servicio db, el bloque depends_on y las variables VIKUNJA_DATABASE_*, y monte una carpeta en /db, donde la imagen ya guarda vikunja.db. Créela y entréguesela al usuario 1000, como files:
volumes:
- ./files:/app/vikunja/files
- ./db:/db
Desde la versión 2.4.0, Vikunja publica un repositorio de paquetes para Debian y Ubuntu, para amd64, arm64 y armhf, firmado con su clave GPG:
curl -fsSL https://dl.vikunja.io/repos/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/vikunja.gpg
echo "deb [signed-by=/usr/share/keyrings/vikunja.gpg] https://dl.vikunja.io/repos/apt stable main" | sudo tee /etc/apt/sources.list.d/vikunja.list
sudo apt update && sudo apt install vikunja
El paquete instala Vikunja en /opt/vikunja, con SQLite por defecto, y un servicio systemd habilitado pero aún sin arrancar. Escribe también un secreto aleatorio en una sección service de /etc/vikunja/config.yml: complete esa misma sección y arranque después el servicio.
service:
secret: "the value written by the package"
publicurl: "https://tasks.example.com/"
interface: "127.0.0.1:3456"
ipextractionmethod: "xff"
sudo systemctl start vikunja
Vikunja no crea ninguna cuenta por defecto. Una vez instalado HTTPS, abra https://tasks.example.com/ y regístrese: es su primera cuenta. El registro está abierto por defecto a cualquiera que llegue a la dirección; cuando existan las cuentas de su equipo, la documentación sugiere cerrarlo. Añada esta línea a las variables del servicio vikunja y vuelva a ejecutar docker compose up -d:
VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
Las cuentas siguientes se gestionan desde la línea de comandos. Como la imagen no tiene shell, se llama directamente a su binario:
docker compose exec vikunja /app/vikunja/vikunja user create -u marie -e marie@example.com
docker compose exec vikunja /app/vikunja/vikunja user list
docker compose exec vikunja /app/vikunja/vikunja user reset-password 2 --direct
user create pide la contraseña cuando la opción -p no la da, lo que la mantiene fuera del historial de su terminal.user reset-password envía por correo un enlace de restablecimiento, o sustituye directamente la contraseña con --direct, usando el identificador que muestra user list.user change-status desactiva o reactiva una cuenta, con --disable o --enable.doctor comprueba la configuración, la URL pública, el secreto, la base de datos, el acceso de escritura a files y, si está activado, el servidor SMTP.VIKUNJA_SERVICE_TIMEZONE vale GMT por defecto y espera un nombre de la base tz, Europe/Paris por ejemplo, nunca un desfase respecto a UTC. Sirve de zona horaria por defecto de los usuarios y fija, por tanto, la hora de sus recordatorios.Vikunja sirve HTTP sin cifrar. La documentación termina HTTPS en un proxy inverso, para que las contraseñas y los tokens nunca circulen sin cifrar: escucha en los puertos 80 y 443, obtiene el certificado y transmite a Vikunja en 127.0.0.1:3456.
Detrás de un proxy, Vikunja ve por defecto la dirección del proxy en cada petición: los registros y los límites de frecuencia afectan entonces a todo el mundo a la vez. El ajuste VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff, ya presente en el archivo Compose, le hace leer la cabecera X-Forwarded-For. Solo se fía de esa cabecera en las peticiones que llegan desde las direcciones de bucle local y de red privada, la red de Docker incluida: con el puerto publicado en 127.0.0.1, solo su proxy llega hasta ahí.
Este es el Caddyfile de la documentación. Caddy obtiene por sí mismo un certificado de Let’s Encrypt para el nombre indicado, transmite la cabecera X-Forwarded-For y deja pasar las conexiones WebSocket:
tasks.example.com {
reverse_proxy 127.0.0.1:3456
}
El bloque de la documentación se reduce a una línea proxy_pass y un tamaño de subida. Este bloque parte de él y añade dos cosas: la cabecera X-Forwarded-For, que Vikunja lee, y las cabeceras WebSocket. La interfaz de la versión 2.8.0 abre una conexión WebSocket en /api/v2/ws para sus actualizaciones en directo; si falla, sus notificaciones pasan a consultarse cada 10 segundos. Añada primero este bloque map a la sección http de /etc/nginx/nginx.conf:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
Después, este bloque de sitio, en el puerto 80 para que Certbot pueda instalar HTTPS:
server {
listen 80;
listen [::]:80;
server_name tasks.example.com;
location / {
proxy_pass http://127.0.0.1:3456;
client_max_body_size 20M;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
sudo nginx -t
sudo certbot --nginx
client_max_body_size 20M corresponde al tamaño máximo de archivo en Vikunja, 20 MB por defecto. Si lo aumenta con VIKUNJA_FILES_MAXSIZE, la documentación pide aumentar también esta línea.
Casi todas las claves del archivo config.yml tienen su variable de entorno: service.enablecaldav se convierte en VIKUNJA_SERVICE_ENABLECALDAV. Cuando una opción se define en los dos sitios, prevalece la variable. La lista de refuerzo de la seguridad de la documentación repasa las funciones que conviene desactivar si no las usa:
| Clave | Por defecto | Desactivarla para |
|---|---|---|
service.enablelinksharing | true | Impedir que se compartan proyectos mediante enlaces públicos |
service.enablecaldav | true | Retirar el punto de acceso CalDAV, que acepta la autenticación HTTP básica |
webhooks.enabled | true | Evitar que Vikunja envíe peticiones a direcciones que eligen los usuarios |
service.enabletaskattachments | true | Impedir la subida de archivos a las tareas |
service.enableuserdeletion | true | Impedir que los usuarios eliminen su propia cuenta |
plugins.enabled | false | Ya desactivada: mantener el código de terceros fuera de Vikunja |
Desde la 2.8.0, la búsqueda ignora los acentos en PostgreSQL cuando la extensión unaccent está activa: «cafe» encuentra también «café». La imagen oficial de PostgreSQL la incluye; actívela en la base de Vikunja y reinicie después Vikunja. El registro muestra entonces unaccent extension detected, search is accent-insensitive.
docker compose exec db psql -U vikunja -d vikunja -c 'CREATE EXTENSION IF NOT EXISTS unaccent;'
docker compose restart vikunja
Cada usuario importa sus tareas desde la pestaña «Import» de sus ajustes, donde también puede exportar todos sus datos en un archivo zip. Las importaciones de archivos, archivo de Vikunja, CSV, TickTick y WeKan, así como la importación desde una instancia de Planka, están siempre disponibles. Todoist, Trello y Microsoft To Do pasan por OAuth: están desactivados por defecto y se activan en la sección migration de la configuración, con los datos de acceso de la aplicación creada en cada servicio. La redirección OAuth se hace en el navegador: la instancia no necesita ser accesible para esos servicios, pero service.publicurl debe ser correcta.
CalDAV sincroniza las tareas con sus aplicaciones, con los datos de conexión de la pestaña CalDAV de los ajustes. La documentación presenta esta integración como una versión alfa que funciona bien con algunos clientes: pruebe el suyo antes de convertirlo en la herramienta de todo el equipo. En iPhone y iPad, cada proyecto se convierte en una lista de la aplicación Recordatorios. Una cuenta con autenticación en dos pasos se conecta con un token CalDAV dedicado.
Vikunja envía correos para los recordatorios de tareas, la confirmación de una cuenta nueva y el restablecimiento de contraseñas. El envío está desactivado por defecto: las cuentas quedan entonces activas en cuanto se crean, y el restablecimiento de la contraseña por correo no es posible. Una vez activado el envío, cada nueva cuenta local confirma su dirección antes de usarse.
Desde un VPS de Simafri, configure un servidor SMTP autenticado, en el puerto 587 o 465: el de su servicio de envío o el de su proveedor de correo. Añada estas variables al servicio vikunja:
VIKUNJA_MAILER_ENABLED: "true"
VIKUNJA_MAILER_HOST: smtp.example.com
VIKUNJA_MAILER_PORT: 587
VIKUNJA_MAILER_USERNAME: tasks@example.com
VIKUNJA_MAILER_PASSWORD: your-smtp-password
VIKUNJA_MAILER_FROMEMAIL: tasks@example.com
VIKUNJA_MAILER_FORCESSL: "true", que impone TLS desde el inicio de la conexión y rechaza las conexiones sin cifrar.plain por defecto, login o cram-md5 con VIKUNJA_MAILER_AUTHTYPE, según su servidor.Vuelva a ejecutar docker compose up -d y envíe después un mensaje de prueba. El comando comprueba la conexión con un comando SMTP NOOP, que algunos relés mínimos no admiten: prefiera un servidor SMTP completo.
docker compose exec vikunja /app/vikunja/vikunja testmail you@example.com
La documentación cuenta dos partes que copiar, a la vez: la base de datos y la carpeta de archivos adjuntos. Desde la 2.8.0, las tareas y los proyectos eliminados pasan primero 30 días en la papelera; pasado ese plazo o vaciada la papelera, solo una copia de seguridad los recupera.
| Elemento | Lo que guarda | Cómo copiarlo |
|---|---|---|
| La base de datos PostgreSQL | Las cuentas, los proyectos, las tareas, los comentarios y los ajustes | pg_dump, sin detener Vikunja |
files | Los archivos adjuntos, los avatares y los fondos de proyecto | Una copia de la carpeta |
Con SQLite, db/vikunja.db | Toda la base de datos | Una copia del archivo, con Vikunja detenido |
docker-compose.yml | El secreto, la URL pública y las contraseñas | Guardado aparte, como un secreto |
docker compose exec -T db pg_dump -U vikunja vikunja > vikunja-$(date +%F).sql
tar -czf vikunja-files-$(date +%F).tar.gz files
La documentación pide copias cifradas y guardadas fuera del servidor, y restauraciones probadas con regularidad: en una instancia aparte, inicie sesión y abra una tarea con un archivo adjunto. Colocados en el disco del servidor, estos archivos entran también en sus copias de seguridad nocturnas.
El comando vikunja dump reúne la configuración, la base de datos y todos los archivos en un archivo zip, y vikunja restore lo vuelve a cargar. El archivo contiene el archivo de configuración y todas las variables VIKUNJA_* en claro: cífrelo y protéjalo como la propia base de datos.
En una instalación nueva, con el mismo docker-compose.yml, cargue la exportación en la base aún vacía antes del primer arranque de Vikunja y vuelva a colocar después la carpeta files:
docker compose up -d db
docker compose exec -T db psql -U vikunja vikunja < vikunja-2026-11-19.sql
tar -xzf vikunja-files-2026-11-19.tar.gz
docker compose up -d
Vikunja ejecuta por sí solo las migraciones de su base de datos cuando arranca una nueva versión. Por eso la documentación pide una copia de seguridad antes de cada actualización, para poder volver al estado anterior, y una lectura de las notas de la versión, que señalan los posibles pasos manuales.
files.docker-compose.yml, por ejemplo de 2.8.0 a la versión siguiente.docker compose pull
docker compose up -d
Con el paquete Debian, sudo apt update && sudo apt upgrade sustituye el binario y reinicia el servicio. Pasar de una versión estable a las compilaciones unstable funciona, pero la documentación desaconseja volver atrás: espere mejor a la siguiente versión estable.
Las correcciones de seguridad se publican como avisos de seguridad de GitHub y se anuncian en las notas de la versión. La versión 2.8.0 del 5 de noviembre de 2026 corrige diecinueve, y su anuncio pide actualizar en cuanto pueda. Para recibir los avisos, siga las versiones del repositorio de GitHub o el canal RSS del registro de cambios.
El autoalojamiento exige mantener el servidor además de la aplicación. En un VPS administrado, nuestros equipos se encargan del servidor y siguen su instancia de forma proactiva; Vikunja sigue siendo su software, con sus ajustes, sus proyectos y sus tareas.
| Tema | Nuestros equipos | Usted |
|---|---|---|
| El servidor | Actualizaciones del sistema y de seguridad, con intervenciones en el servidor incluidas | El momento que mejor convenga a su actividad |
| La supervisión | Servidor vigilado las 24 horas del día, los 7 días de la semana, con intervención sin esperar su llamada | La lectura de los registros de su instancia |
| Vikunja | Seguimiento proactivo: errores, lentitud y espacio en disco detectados, corrección recomendada | Su instalación, sus actualizaciones y sus ajustes, que aplica usted o su asistente de IA |
| Las cuentas y los proyectos | El servidor que los soporta, vigilado y con copias de seguridad | Las cuentas de su equipo, el registro, los proyectos compartidos y los permisos |
| El correo | Un servidor que llega a su servidor SMTP en el puerto 587 o 465 | Su servicio de envío y sus datos de acceso |
| Las copias de seguridad | Cada noche, cifradas y guardadas fuera de la máquina; restauración incluida | Sus exportaciones de la base de datos y de la carpeta files, y la petición de restauración, cuando la necesite |
| La migración | Su servidor actual migrado, gratis | El momento del cambio |
Si prefiere que nuestros equipos intervengan en la propia aplicación, ese servicio se factura por horas o a precio cerrado, con un presupuesto comunicado antes de la intervención.
Con un VPS administrado de Simafri, nuestros equipos mantienen actualizado el servidor de su instancia de Vikunja, lo vigilan día y noche e intervienen sin esperar su llamada; también siguen su instancia de forma proactiva y le recomiendan las correcciones útiles, que aplica usted o su asistente de IA. Las copias de seguridad se cifran cada noche y se guardan fuera de la máquina, su restauración está incluida, y la migración de su servidor actual es gratuita.
Sí. Vikunja tiene licencia AGPL-3.0: puede usarlo en su empresa sin ninguna licencia que comprar. Si lo modifica, sus usuarios a distancia deben poder obtener el código fuente de su versión. Queda el coste del servidor que lo ejecuta.
SQLite, incluida en la imagen, basta para unos pocos usuarios. Más allá, la documentación recomienda PostgreSQL o MySQL. PostgreSQL es la base de sus ejemplos Docker, y desde la 2.8.0 su búsqueda ignora los acentos con la extensión unaccent.
Cree un docker-compose.yml con las imágenes vikunja/vikunja:2.8.0 y postgres:18, el puerto 3456 publicado en 127.0.0.1, una carpeta files entregada al usuario 1000, la URL pública y el secreto, y ejecute docker compose up -d. Coloque después delante del puerto 3456 un proxy inverso en HTTPS.
service.publicurl es la dirección HTTPS de su instancia: Vikunja construye a partir de ella sus enlaces y su origen CORS, de ahí un error unauthorized cuando es errónea. service.secret firma las sesiones; si se deja vacío, cambia en cada arranque y cierra la sesión de todos los usuarios.
Vikunja no tiene ninguna cuenta por defecto: regístrese en su instancia. Cierre después el registro poniendo VIKUNJA_SERVICE_ENABLEREGISTRATION en false, y cree las cuentas siguientes con el comando vikunja user create, ejecutado dentro del contenedor.
Active el envío con VIKUNJA_MAILER_ENABLED e indique después el host, el puerto 587 o 465, el usuario, la contraseña y la dirección del remitente de su servidor SMTP. Sin correo, las cuentas quedan activas en cuanto se crean y las contraseñas se restablecen desde la línea de comandos.
Copie a la vez la base de datos, con pg_dump para PostgreSQL, y la carpeta files de los archivos adjuntos. Guarde las copias cifradas y fuera del servidor, haga una antes de cada actualización y pruebe su restauración con regularidad.
Un VPS administrado cubre el servidor: sistema, seguridad, supervisión y copias de seguridad. Nuestros equipos siguen también su instancia de forma proactiva y le recomiendan las correcciones útiles, que aplica usted. Una intervención en la aplicación se factura por horas o a precio cerrado.
Simafri
Hablemos de su proyecto
Díganos en pocas palabras lo que necesita: le respondemos rápidamente.
¡Gracias! Su solicitud ha sido enviada. Le responderemos en breve.
¿Prefiere el correo? Escríbanos a support@simafri.com.