Vikunja: Gestión de Tareas Self-Hosted (Alternativa a Todoist/Notion) – Guía Completa 2026

—

📋 TL;DR (Resumen Ejecutivo)

¿Cansado de depender de servicios SaaS como Todoist o Notion para gestionar tus tareas? Vikunja es una aplicación de gestión de tareas de código abierto y autoalojada que te permite tener control total sobre tus datos mientras disfrutas de todas las funcionalidades de las herramientas comerciales. A diferencia de Todoist (requiere suscripción premium) o Notion (más enfocado en notas), Vikunja está diseñada específicamente para gestión de tareas con vistas Kanban, Gantt y calendario integradas, colaboración en equipo y sincronización móvil.

Lo que conseguirás:

• ✅ Stack completo de Vikunja funcionando en Docker-2025/) con PostgreSQL-guia-completa-tutorial-2025/)-mongodb-guia-completa-tutorial-2025/)
• ✅ Sistema de gestión de tareas con Kanban, Gantt y calendario
• ✅ Integración con n8n para automatización de tareas
• ✅ Apps móviles iOS y Android con sincronización en tiempo real
• ✅ Comparativa detallada: Vikunja vs Todoist vs Notion vs Trello

Tiempo de lectura: ~18 minutos | Nivel: Intermedio

—

📚 Tabla de Contenidos

1. Introducción: ¿Por Qué Vikunja?
2. ¿Qué es Vikunja?
3. Comparativa: Vikunja vs Todoist vs Notion
4. Instalación con Docker Compose
5. Configuración Inicial
6. Uso Básico: Crear Tareas y Proyectos
7. Vistas Avanzadas: Kanban, Gantt y Calendario
8. Integración con n8n: Automatización de Tareas
9. Apps Móviles y Sincronización
10. Migración desde Todoist/Notion
11. Troubleshooting: Errores Comunes
12. Mejores Prácticas
13. Preguntas Frecuentes
14. Conclusión y Próximos Pasos

—

> 📅 Última actualización: Enero 2026

> ✅ Verificado con: Vikunja v0.23 | Docker Compose v2.24 | PostgreSQL 13

> 🔄 Repositorio GitHub: learningaiagents/vikunja

—

Introducción: ¿Por Qué Vikunja? {#introduccion}

Si utilizas herramientas de gestión de tareas como Todoist o Notion, probablemente hayas experimentado estas frustraciones: dependes de servicios externos, pagas suscripciones mensuales y tus datos están en servidores de terceros. Además, las versiones gratuitas suelen tener limitaciones (número de proyectos, funcionalidades premium bloqueadas) que te obligan a pagar para acceder a características básicas.

El problema:

• Todoist requiere suscripción premium ($4-6/mes) para características avanzadas
• Notion es más una herramienta de notas que de gestión de tareas
• Tus datos están en servidores de terceros sin control real
• Falta personalización y extensibilidad en herramientas SaaS
• Sincronización móvil limitada o con restricciones

La solución: Vikunja

Vikunja es una aplicación de gestión de tareas de código abierto y autoalojada diseñada específicamente para reemplazar herramientas comerciales como Todoist, Notion y Trello. A diferencia de estas soluciones, puedes alojarla en tu propio servidor, manteniendo control total sobre tus datos y sin pagar suscripciones.

En esta guía completa aprenderás:

• Cómo instalar Vikunja en Docker con PostgreSQL
• Configurar tu primer proyecto y crear tareas eficientemente
• Usar vistas Kanban, Gantt y calendario para gestionar proyectos
• Integrar Vikunja con n8n para automatizar creación de tareas
• Configurar apps móviles iOS y Android con sincronización
• Migrar tus tareas desde Todoist o Notion
• Optimizar rendimiento y aplicar mejores prácticas de seguridad
• Resolver errores comunes y problemas de sincronización

Ya seas desarrollador que busca una alternativa self-hosted, sysadmin que quiere controlar sus datos, o entusiasta de homelab que quiere dejar de depender de servicios SaaS, esta guía te dará todo lo necesario para empezar con Vikunja.

—

¿Qué es Vikunja? {#que-es-vikunja}

Vikunja es una aplicación de gestión de tareas de código abierto y autoalojada desarrollada en Go (Golang) y Vue.js. A diferencia de herramientas comerciales como Todoist o Notion, puedes alojarla en tu propio servidor, manteniendo control total sobre tus datos y personalización completa.

Características Principales

1. Organización Jerárquica de Tareas

Vikunja permite crear una estructura ilimitada de proyectos, listas y subproyectos. Puedes organizar tareas de forma jerárquica, facilitando la gestión de proyectos complejos con múltiples niveles de organización.

2. Vistas Múltiples

Una de las fortalezas de Vikunja es la variedad de vistas disponibles:

• Vista de Lista: Lista tradicional con checkboxes, ideal para tareas simples
• Tablero Kanban: Organiza tareas en columnas (Todo, En Progreso, Hecho), perfecto para workflows
• Diagrama de Gantt: Visualiza dependencias y plazos, útil para planificación de proyectos
• Vista de Tabla: Edición masiva y filtros avanzados, excelente para análisis
• Calendario: Vista mensual y semanal de tareas programadas, ideal para gestión temporal

3. Colaboración en Equipo

Vikunja incluye funcionalidades completas de colaboración:

• Compartir proyectos con permisos granulares (lectura, escritura, administración)
• Asignación de tareas a usuarios específicos
• Creación de equipos para gestionar múltiples usuarios
• Notificaciones en tiempo real y por email
• Comentarios en tareas para discusiones

4. Integraciones y Automatización

Vikunja ofrece múltiples formas de integrarse con otras herramientas:

• API REST completa: Integración programática con cualquier sistema
• CalDAV: Sincronización con calendarios (Google Calendar, Apple Calendar, Thunderbird)
• Webhooks: Automatización con n8n, Zapier o scripts personalizados
• RSS feeds: Seguimiento de proyectos y listas mediante RSS

5. Aplicaciones Móviles

Vikunja cuenta con aplicaciones nativas para:

• iOS: Disponible en App Store, sincronización completa
• Android: Disponible en Google Play, todas las funcionalidades
• Funciona sin conexión con sincronización posterior
• Notificaciones push para recordatorios

6. Privacidad y Control de Datos

Al ser autoalojada, Vikunja garantiza:

• Tus datos permanecen en tu servidor, no en servidores de terceros
• Cero dependencia de servicios externos
• Cumplimiento de GDPR y regulaciones de privacidad
• Posibilidad de backup y restauración completa

Arquitectura Técnica

Vikunja está construido con tecnologías modernas:

• Backend: Go (Golang) – Alto rendimiento y bajo consumo de recursos
• Frontend: Vue.js – Interfaz moderna y responsive
• Base de datos: PostgreSQL o MySQL/MariaDB
• API: RESTful API con documentación OpenAPI
• Autenticación: JWT tokens, OAuth2, LDAP/Active Directory

Casos de Uso Ideales

1. Gestión Personal de Tareas (GTD)

Organiza tu vida personal con proyectos, listas y etiquetas. Perfecto para metodologías como Getting Things Done (GTD).

2. Proyectos de Desarrollo

Gestiona sprints, bugs y features con vistas Kanban y Gantt. Ideal para equipos pequeños de desarrollo.

3. Proyectos Domésticos

Organiza tareas domésticas, compras y recordatorios con calendario integrado.

4. Colaboración en Equipo

Comparte proyectos con tu equipo, asigna tareas y mantén a todos sincronizados.

NO uses Vikunja si:

• ❌ Necesitas una herramienta de notas rica (usa Notion o Obsidian)
• ❌ Quieres una solución completamente cloud sin gestión de servidor (usa Todoist)
• ❌ Solo necesitas gestión básica de tareas sin vistas avanzadas

—

Comparativa: Vikunja vs Todoist vs Notion {#comparativa}

¿Cuándo Usar Cada Una?

Usa Vikunja si:

• ✅ Quieres control total sobre tus datos
• ✅ Prefieres no pagar suscripciones mensuales
• ✅ Necesitas vistas Gantt para planificación
• ✅ Quieres sincronización CalDAV con calendarios
• ✅ Tienes capacidad técnica para self-hosting

Usa Todoist si:

• ✅ Buscas una solución cloud sin gestión de servidor
• ✅ Necesitas integración con herramientas como Gmail, Slack
• ✅ Prefieres simplicidad sobre funcionalidades avanzadas
• ✅ No te importa pagar suscripción premium

Usa Notion si:

• ✅ Necesitas más que gestión de tareas (notas, bases de datos)
• ✅ Trabajas con documentos largos y wikis
• ✅ Quieres una herramienta todo-en-uno
• ✅ Prefieres diseño visual sobre funcionalidad técnica

Recomendación general: Si tienes un homelab o servidor propio y valoras la privacidad, Vikunja es la mejor opción. Ofrece todas las funcionalidades de herramientas comerciales sin costos mensuales y con control total sobre tus datos.

—

Instalación con Docker Compose {#instalacion}

Requisitos Previos

Antes de instalar Vikunja, asegúrate de tener:

• ✅ Docker 20.10+ y Docker Compose 2.0+: docker --version y docker compose version
• ✅ Puertos libres: 80 (HTTP) y opcionalmente 443 (HTTPS)
• ✅ Memoria RAM: Mínimo 512MB, recomendado 1GB
• ✅ Espacio en disco: 1GB para instalación + espacio para base de datos

Paso 1: Crear Estructura de Directorios

# Crear directorio para Vikunja
mkdir -p ~/vikunja/{db,files}
cd ~/vikunja

Paso 2: Crear docker-compose.yml

Crea docker-compose.yml con el siguiente contenido:

version: '3'

services:
  vikunja-db:
    image: postgres:13
    container_name: vikunja-db
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:-changeme}
      POSTGRES_USER: vikunja
      POSTGRES_DB: vikunja
    volumes:
      - vikunja-db:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - vikunja

  vikunja-api:
    image: vikunja/api:latest
    container_name: vikunja-api
    environment:
      VIKUNJA_SERVICE_PUBLICPATH: ${VIKUNJA_URL:-http://localhost:3456}
      DB_TYPE: postgres
      DB_HOST: vikunja-db
      DB_USER: vikunja
      DB_PASSWORD: ${DB_PASSWORD:-changeme}
      DB_DATABASE: vikunja
      JWT_SECRET: ${JWT_SECRET:-changeme}
      CORS_ENABLED: "true"
      LOG_LEVEL: info
    ports:
      - "3456:3456"
    depends_on:
      - vikunja-db
    restart: unless-stopped
    networks:
      - vikunja

  vikunja-proxy:
    image: vikunja/proxy:latest
    container_name: vikunja-proxy
    ports:
      - "80:80"
    environment:
      VIKUNJA_API_URL: http://vikunja-api:3456
    depends_on:
      - vikunja-api
    restart: unless-stopped
    networks:
      - vikunja

volumes:
  vikunja-db:

networks:
  vikunja:
    driver: bridge

Paso 3: Configurar Variables de Entorno (Opcional)

Crea un archivo .env para configurar variables de entorno:

# .env
VIKUNJA_URL=http://localhost
DB_PASSWORD=tu_password_seguro_aqui
JWT_SECRET=$(openssl rand -base64 32)

⚠️ Importante: Cambia DB_PASSWORD y JWT_SECRET por valores seguros. Para generar un JWT_SECRET aleatorio:

openssl rand -base64 32

Paso 4: Iniciar Vikunja

# Iniciar contenedores
docker compose up -d

# Verificar que están corriendo
docker compose ps

# Ver logs si hay problemas
docker compose logs -f vikunja-api

Explicación: Este comando inicia los tres servicios:

• vikunja-db: Base de datos PostgreSQL
• vikunja-api: API backend de Vikunja
• vikunja-proxy: Frontend y proxy reverso

Paso 5: Acceder a la Interfaz Web

Abre tu navegador en:

• URL local: http://localhost
• URL con IP: http://TU_IP_SERVIDOR

Verás la pantalla de registro. Crea tu primera cuenta de administrador.

✅ Verificación: Si ves la interfaz de registro, la instalación fue exitosa.

—

Configuración Inicial {#configuracion}

Crear Cuenta de Administrador

1. En la pantalla de registro, ingresa:

– Usuario: Tu nombre de usuario preferido

– Email: Tu email (requerido para recuperación de contraseña)

– Contraseña: Una contraseña segura (mínimo 8 caracteres)

1. Haz clic en «Registrarse»

1. Inicia sesión con tus credenciales

Configuración Básica

Una vez dentro de Vikunja:

1. Configurar Perfil

• Ve a Configuración → Perfil
• Actualiza tu nombre y avatar
• Configura preferencias de idioma y zona horaria

2. Crear tu Primer Proyecto

• Haz clic en el botón «+ Nuevo» en la barra lateral
• Selecciona «Lista» o «Proyecto»
• Nombra tu proyecto (ej: «Tareas Personales»)
• Haz clic en «Crear»

3. Configurar Notificaciones (Opcional)

• Ve a Configuración → Notificaciones
• Activa notificaciones por email si lo deseas
• Configura recordatorios de tareas

Configuración Avanzada para Producción

Si planeas usar Vikunja en producción con dominio propio:

1. Configurar SSL con Traefik

Crea docker-compose.traefik.yml:

version: '3'

services:
  vikunja-db:
    image: postgres:13
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: vikunja
      POSTGRES_DB: vikunja
    volumes:
      - vikunja-db:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - web

  vikunja-api:
    image: vikunja/api:latest
    environment:
      VIKUNJA_SERVICE_PUBLICPATH: https://vikunja.tudominio.com
      DB_TYPE: postgres
      DB_HOST: vikunja-db
      DB_USER: vikunja
      DB_PASSWORD: ${DB_PASSWORD}
      DB_DATABASE: vikunja
      JWT_SECRET: ${JWT_SECRET}
    depends_on:
      - vikunja-db
    restart: unless-stopped
    networks:
      - web
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.vikunja-api.rule=Host(`vikunja.tudominio.com`) && PathPrefix(`/api/v1`)"
      - "traefik.http.services.vikunja-api.loadbalancer.server.port=3456"

  vikunja-proxy:
    image: vikunja/proxy:latest
    depends_on:
      - vikunja-api
    restart: unless-stopped
    networks:
      - web
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.vikunja.rule=Host(`vikunja.tudominio.com`)"
      - "traefik.http.services.vikunja.loadbalancer.server.port=80"
      - "traefik.http.routers.vikunja.tls=true"
      - "traefik.http.routers.vikunja.tls.certresolver=letsencrypt"

volumes:
  vikunja-db:

networks:
  web:
    external: true

2. Desactivar Registro Público

En producción, desactiva el registro público:

environment:
  ENABLE_REGISTRATION: "false"

Solo los administradores podrán crear nuevas cuentas.

—

Uso Básico: Crear Tareas y Proyectos {#uso-basico}

Crear una Tarea

Método 1: Desde la Interfaz Web

1. Navega a tu proyecto o lista
2. Haz clic en el botón «+ Nueva Tarea»
3. Completa los campos:

– Título: Nombre de la tarea

– Descripción: Detalles adicionales (opcional)

– Fecha de vencimiento: Cuándo debe completarse (opcional)

– Prioridad: Baja, Normal, Alta, Urgente

– Etiquetas: Categorías para organizar (opcional)

1. Haz clic en «Guardar»

Método 2: Rápido con Atajos

• Presiona q para crear una tarea rápida
• Escribe el título y presiona Enter
• Edita después para añadir más detalles

Organizar Tareas con Etiquetas

Las etiquetas te permiten categorizar tareas independientemente del proyecto:

Crear Etiqueta:

1. Ve a Etiquetas en la barra lateral
2. Haz clic en «+ Nueva Etiqueta»
3. Elige un color y nombre (ej: «@Trabajo», «@Casa», «@Urgente»)
4. Guarda

Aplicar Etiqueta a Tarea:

• Abre una tarea y haz clic en «Etiquetas»
• Selecciona las etiquetas relevantes
• Las tareas se pueden filtrar por etiquetas más adelante

Crear Subtareas

Para tareas complejas, puedes crear subtareas:

1. Abre una tarea existente
2. En la sección «Subtareas», haz clic en «+ Subtarea»
3. Agrega cada paso o subtarea
4. Marca como completada cuando termines cada una

Ejemplo de uso:

• Tarea principal: «Publicar artículo sobre Vikunja»

– Subtarea 1: «Escribir introducción»

– Subtarea 2: «Redactar secciones principales»

– Subtarea 3: «Revisar y corregir»

– Subtarea 4: «Publicar en WordPress»

Establecer Fechas de Vencimiento

Las fechas de vencimiento son esenciales para gestión temporal:

1. Abre una tarea
2. Haz clic en el campo «Fecha de vencimiento»
3. Selecciona fecha y hora (opcional)
4. Vikunja mostrará la tarea en el calendario y enviará recordatorios

Tip: Usa fechas de vencimiento para priorizar visualmente tareas en la vista de calendario.

—

Vistas Avanzadas: Kanban, Gantt y Calendario {#vistas-avanzadas}

Vista Kanban

La vista Kanban es ideal para gestionar workflows con estados:

Configurar Vista Kanban:

1. Abre un proyecto o lista
2. Haz clic en el icono de vista (arriba a la derecha)
3. Selecciona «Kanban»

Columnas por Defecto:

• Todo: Tareas pendientes
• En Progreso: Tareas en ejecución
• Hecho: Tareas completadas

Personalizar Columnas:

1. Haz clic en «Configurar Columnas»
2. Añade nuevas columnas (ej: «Revisión», «Bloqueado»)
3. Arrastra tareas entre columnas para cambiar su estado

Tip: Usa Kanban para proyectos con múltiples etapas como desarrollo de software, donde cada columna representa una fase del proceso.

Vista Gantt

La vista Gantt es perfecta para planificación de proyectos con dependencias:

Acceder a Vista Gantt:

1. Abre un proyecto
2. Selecciona «Vista Gantt» desde el menú de vistas
3. Verás un diagrama de Gantt con todas las tareas y sus fechas

Funcionalidades:

• Visualizar plazos: Ve todas las fechas de vencimiento en una línea temporal
• Dependencias: Establece que una tarea debe completarse antes que otra
• Hitos: Marca fechas importantes del proyecto

Ejemplo de uso: Planifica un sprint de desarrollo donde algunas tareas dependen de otras.

Vista Calendario

La vista calendario muestra todas las tareas con fechas en formato calendario:

Acceder:

1. Haz clic en «Calendario» en la barra lateral
2. Verás vista mensual con todas las tareas programadas
3. Cambia a vista semanal o diaria según necesites

Características:

• Tareas con fecha aparecen en el día correspondiente
• Tareas sin fecha aparecen en «Sin fecha»
• Haz clic en una tarea para editarla directamente desde el calendario

Sincronización CalDAV:

Vikunja soporta CalDAV, permitiendo sincronizar tareas con calendarios externos:

1. Ve a Configuración → Integraciones → CalDAV
2. Copia la URL de CalDAV (ej: https://vikunja.tudominio.com/dav/)
3. Configura en tu cliente de calendario:

– Google Calendar: Añadir calendario por URL

– Apple Calendar: Añadir cuenta CalDAV

– Thunderbird: Añadir calendario remoto

—

Integración con n8n: Automatización de Tareas {#integracion-n8n}

Vikunja se integra perfectamente con n8n para automatizar la creación y gestión de tareas.

Obtener Token de API

Primero, necesitas un token de API de Vikunja:

1. Ve a Configuración → Tokens
2. Haz clic en «+ Nuevo Token»
3. Nombra el token (ej: «n8n Automation»)
4. Copia el token generado (solo se muestra una vez)

Workflow n8n: Crear Tarea desde Email

Este workflow crea automáticamente una tarea en Vikunja cuando recibes un email con un asunto específico:

Configuración en n8n:

1. Email Trigger (Gmail, IMAP, etc.)

– Configura para recibir emails

– Filtra por asunto si es necesario

1. Function Node (Parse Email)

// Extraer información del email
   const subject = $input.item.json.subject;
   const body = $input.item.json.text;
   const sender = $input.item.json.from;
   
   return {
     title: subject,
     description: `${body}\n\nDe: ${sender}`,
     priority: 2  // Normal
   };

1. HTTP Request Node (Crear Tarea en Vikunja)

– Method: POST

– URL: https://vikunja.tudominio.com/api/v1/lists/1/tasks

– Authentication: Header Auth

– Header Name: Authorization

– Header Value: Bearer TU_TOKEN_VIKUNJA

– Body:

{
     "title": "={{$json.title}}",
     "description": "={{$json.description}}",
     "priority": "={{$json.priority}}"
   }

Resultado: Cada email recibido crea automáticamente una tarea en Vikunja.

Workflow: Sincronizar GitHub Issues con Vikunja

Este workflow crea tareas en Vikunja cuando se abre un issue en GitHub:

1. Webhook de GitHub (triggered on issue opened)
2. Function Node (Transformar datos):

const issue = $input.item.json.issue;
   return {
     title: `[GitHub] ${issue.title}`,
     description: issue.body,
     labels: issue.labels.map(l => l.name)
   };

1. HTTP Request Node (Crear tarea en Vikunja)

API REST de Vikunja: Endpoints Útiles

Listar Tareas:

curl -X GET "https://vikunja.tudominio.com/api/v1/tasks" \
  -H "Authorization: Bearer TU_TOKEN"

Crear Tarea:

curl -X POST "https://vikunja.tudominio.com/api/v1/lists/1/tasks" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nueva tarea desde API",
    "description": "Creada automáticamente",
    "due_date": "2026-01-10T23:59:59Z",
    "priority": 3
  }'

Actualizar Tarea:

curl -X PUT "https://vikunja.tudominio.com/api/v1/tasks/123" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"done": true}'

Documentación completa: Consulta https://vikunja.io/api/ para todos los endpoints disponibles.

—

Apps Móviles y Sincronización {#apps-moviles}

App iOS

Instalación:

1. Abre App Store en tu iPhone/iPad
2. Busca «Vikunja»
3. Instala la app oficial

Configuración:

1. Abre la app
2. Toca «Añadir Instancia»
3. Ingresa la URL de tu servidor (ej: https://vikunja.tudominio.com)
4. Inicia sesión con tus credenciales
5. ¡Listo! Tus tareas se sincronizan automáticamente

Características:

• ✅ Sincronización en tiempo real
• ✅ Funciona sin conexión
• ✅ Notificaciones push
• ✅ Todas las funcionalidades (crear, editar, completar tareas)

App Android

Instalación:

1. Abre Google Play Store
2. Busca «Vikunja»
3. Instala la app oficial

Configuración:

Similar a iOS:

1. Abre la app
2. Añade tu instancia de Vikunja
3. Inicia sesión
4. Sincronización automática activada

Sincronización y Sincronización Offline

Sincronización en Tiempo Real:

• Los cambios en cualquier dispositivo se reflejan instantáneamente en otros
• No necesitas «tirar hacia abajo para actualizar»

Modo Offline:

• Las apps móviles funcionan sin conexión
• Los cambios se guardan localmente
• Cuando vuelves a tener conexión, se sincronizan automáticamente

Resolución de Conflictos:

• Si editas la misma tarea en dos dispositivos, Vikunja usa «last write wins»
• Los cambios más recientes sobrescriben los anteriores

—

Migración desde Todoist/Notion {#migracion}

Migrar desde Todoist

Paso 1: Exportar desde Todoist

1. Ve a Todoist Web
2. Configuración → Exportar datos
3. Descarga el archivo JSON con tus tareas

Paso 2: Script de Migración

Crea un script migrar_desde_todoist.sh:

#!/bin/bash
# Requiere: jq, curl

TODOIST_API_KEY="$1"
VIKUNJA_TOKEN="$2"
VIKUNJA_URL="https://vikunja.tudominio.com/api/v1"

# Obtener proyectos de Todoist
TODOIST_PROJECTS=$(curl -s "https://api.todoist.com/rest/v2/projects" \
  -H "Authorization: Bearer $TODOIST_API_KEY" | jq -r '.[] | "\(.id)|\(.name)"')

while IFS='|' read -r project_id project_name; do
  echo "Migrando proyecto: $project_name"
  
  # Crear lista en Vikunja
  LIST_RESPONSE=$(curl -s -X POST "$VIKUNJA_URL/lists" \
    -H "Authorization: Bearer $VIKUNJA_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"title\":\"$project_name\"}")
  
  LIST_ID=$(echo "$LIST_RESPONSE" | jq -r '.id')
  
  # Obtener tareas del proyecto
  TODOIST_TASKS=$(curl -s "https://api.todoist.com/rest/v2/tasks?project_id=$project_id" \
    -H "Authorization: Bearer $TODOIST_API_KEY")
  
  # Migrar cada tarea
  echo "$TODOIST_TASKS" | jq -r '.[] | "\(.id)|\(.content)|\(.due?.date)|\(.priority)"' | \
  while IFS='|' read -r task_id content due_date priority; do
    VIKUNJA_PRIORITY=2
    case $priority in
      4) VIKUNJA_PRIORITY=3 ;;  # Urgente
      3) VIKUNJA_PRIORITY=2 ;;  # Alta
      2) VIKUNJA_PRIORITY=1 ;;  # Normal
      1) VIKUNJA_PRIORITY=0 ;;  # Baja
    esac
    
    curl -s -X POST "$VIKUNJA_URL/lists/$LIST_ID/tasks" \
      -H "Authorization: Bearer $VIKUNJA_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{
        \"title\":\"$content\",
        \"due_date\":\"$due_date\",
        \"priority\":$VIKUNJA_PRIORITY
      }" > /dev/null
    
    echo "  ✓ Tarea migrada: $content"
  done
done <<< "$TODOIST_PROJECTS"

echo "✅ Migración completada"

Uso:

chmod +x migrar_desde_todoist.sh
./migrar_desde_todoist.sh TU_API_KEY_TODOIST TU_TOKEN_VIKUNJA

Migrar desde Notion

Notion no tiene una API de exportación directa, pero puedes:

Opción 1: Exportar Manualmente

1. En Notion, exporta tu base de datos como CSV
2. Usa un script Python para convertir CSV a formato Vikunja
3. Importa mediante API de Vikunja

Opción 2: Migración Manual Selectiva

• Exporta solo los proyectos importantes
• Crea manualmente en Vikunja
• Es más trabajo pero garantiza que todo esté correcto

—

Troubleshooting: Errores Comunes {#troubleshooting}

Error: No se puede conectar a la base de datos

Síntoma: FATAL: database "vikunja" does not exist

Solución:

# Verificar que el contenedor de DB está corriendo
docker ps | grep vikunja-db

# Si no existe, recrear la base de datos
docker compose down -v
docker compose up -d vikunja-db

# Esperar 10 segundos y luego iniciar API
sleep 10
docker compose up -d vikunja-api

Error: CORS habilitado pero no funciona

Síntoma: Error de CORS en el navegador al usar la API

Solución:

Añade en docker-compose.yml:

environment:
  CORS_ENABLED: "true"
  CORS_ALLOWED_ORIGINS: "https://tudominio.com,http://localhost:3000"

Reinicia los contenedores:

docker compose restart vikunja-api

Error: Sincronización móvil no funciona

Síntoma: La app móvil no sincroniza cambios

Solución:

1. Verificar que VIKUNJA_SERVICE_PUBLICPATH tiene la URL correcta (con https)
2. Verificar certificado SSL válido
3. Comprobar que los puertos están abiertos (80, 443)
4. Reiniciar contenedores:

docker compose restart

Error: Performance lenta con muchas tareas

Síntoma: La interfaz se vuelve lenta con >1000 tareas

Solución:

1. Activar índices en base de datos:

CREATE INDEX idx_tasks_list_id ON tasks(list_id);
   CREATE INDEX idx_tasks_due_date ON tasks(due_date);
   CREATE INDEX idx_tasks_done ON tasks(done);

1. Limitar resultados por página en API:

curl "https://vikunja.tudominio.com/api/v1/tasks?per_page=50"

1. Usar filtros en lugar de cargar todas las tareas

Error: Backup falla

Síntoma: El script de backup no puede acceder a la base de datos

Solución:

# Verificar credenciales en .env
cat .env | grep DB_PASSWORD

# Probar conexión manual
docker exec -it vikunja-db psql -U vikunja -d vikunja

# Si falla, verificar que el contenedor está corriendo
docker logs vikunja-db

—

Mejores Prácticas {#mejores-practicas}

Seguridad

1. Cambiar Contraseñas por Defecto

• Nunca uses changeme como contraseña en producción
• Genera contraseñas seguras: openssl rand -base64 32

2. Usar SSL/HTTPS

• Siempre configura SSL en producción
• Usa Let’s Encrypt con Traefik o Nginx Proxy Manager

3. Desactivar Registro Público

• En producción, desactiva registro público:

ENABLE_REGISTRATION: "false"

4. Backup Regular

• Configura backups automáticos diarios
• Prueba restauraciones periódicamente

Organización de Tareas

1. Usar Etiquetas Consistentemente

• Crea un conjunto de etiquetas estándar (@Trabajo, @Casa, @Urgente)
• Úsalas consistentemente para facilitar filtrado

2. Estructura de Proyectos Clara

• Organiza proyectos por área (Personal, Trabajo, Proyectos)
• Evita crear demasiados proyectos (máximo 10-15)

3. Fechas de Vencimiento Realistas

• Asigna fechas solo cuando son necesarias
• Revisa calendario semanalmente

Performance

1. Limitar Resultados en API

• Siempre usa paginación cuando consumes la API
• No cargues todas las tareas de una vez

2. Índices en Base de Datos

• Crea índices para campos frecuentemente consultados
• Monitorea performance con logs

3. Backup Eficiente

• Programa backups en horarios de bajo uso
• Comprime backups antiguos

—

Preguntas Frecuentes {#faq}

¿Vikunja es realmente gratuito?

Sí, Vikunja es 100% código abierto y gratuito. No hay versiones premium ni suscripciones. Todo el código está disponible en GitHub bajo licencia AGPL v3.

¿Necesito un servidor potente para Vikunja?

No. Vikunja es muy ligero. Funciona perfectamente con:

• 1 CPU core
• 512MB RAM (1GB recomendado)
• 1GB espacio en disco

Puede ejecutarse en una Raspberry Pi o VPS económico.

¿Puedo sincronizar con Google Calendar?

Sí, Vikunja soporta CalDAV. Puedes sincronizar tus tareas con Google Calendar, Apple Calendar o cualquier cliente CalDAV.

¿Vikunja tiene apps móviles?

Sí, Vikunja tiene apps nativas para iOS y Android disponibles en App Store y Google Play Store. Ambas apps incluyen todas las funcionalidades y sincronización en tiempo real.

¿Puedo importar mis tareas desde Todoist?

Sí, aunque no hay importación directa, puedes usar la API de Todoist para exportar y la API de Vikunja para importar. Hemos incluido un script de ejemplo en esta guía.

¿Vikunja soporta colaboración en equipo?

Sí, Vikunja incluye funcionalidades completas de colaboración:

• Compartir proyectos con permisos granulares
• Asignar tareas a usuarios específicos
• Crear equipos
• Notificaciones en tiempo real

¿Qué bases de datos soporta Vikunja?

Vikunja soporta:

• PostgreSQL (recomendado)
• MySQL/MariaDB
• SQLite (solo para desarrollo, no recomendado en producción)

¿Puedo usar Vikunja sin Docker?

Sí, Vikunja se puede ejecutar como binario standalone o compilar desde fuente. Sin embargo, Docker es el método más sencillo y recomendado.

¿Cómo hago backup de Vikunja?

Incluimos un script de backup en los ejemplos de esta guía. El backup incluye:

• Base de datos completa
• Archivos adjuntos (si los hay)
• Comprresión automática

¿Vikunja es seguro?

Sí, Vikunja es código abierto, lo que significa que cualquiera puede auditar el código. Además, al ser self-hosted, tus datos nunca salen de tu servidor.

¿Puedo personalizar la interfaz de Vikunja?

Sí, Vikunja permite personalización limitada de temas y colores. Para cambios más profundos, puedes modificar el código fuente (es código abierto).

¿Vikunja tiene límites de tareas o proyectos?

No, Vikunja no tiene límites. Puedes crear ilimitados proyectos, listas y tareas. El único límite es el espacio en disco de tu servidor.

¿Cómo actualizo Vikunja?

Simplemente actualiza la imagen Docker:

docker compose pull
docker compose up -d

Vikunja maneja migraciones de base de datos automáticamente.

¿Puedo usar Vikunja con Traefik o Nginx Proxy Manager?

Sí, Vikunja funciona perfectamente con cualquier reverse proxy. Hemos incluido ejemplos de configuración con Traefik en esta guía.

¿Vikunja funciona sin conexión a internet?

Una vez instalado, Vikunja funciona completamente offline. Solo necesitas conexión a internet para:

• Descargar la imagen Docker inicialmente
• Actualizar la aplicación

Las apps móviles también funcionan offline y se sincronizan cuando vuelves a tener conexión.

—

Conclusión y Próximos Pasos {#conclusion}

Vikunja es una excelente alternativa self-hosted a herramientas comerciales como Todoist y Notion. Ofrece todas las funcionalidades esenciales (Kanban, Gantt, calendario, colaboración) sin costos mensuales y con control total sobre tus datos.

En esta guía has aprendido:

• ✅ Cómo instalar Vikunja en Docker con PostgreSQL
• ✅ Configurar proyectos, tareas y etiquetas
• ✅ Usar vistas avanzadas (Kanban, Gantt, calendario)
• ✅ Integrar con n8n para automatización
• ✅ Configurar apps móviles con sincronización
• ✅ Migrar desde Todoist o Notion
• ✅ Aplicar mejores prácticas de seguridad y performance

Próximos pasos recomendados:

1. Explorar integraciones avanzadas:

– Configurar webhooks para automatizaciones complejas

– Integrar con otros servicios mediante API

1. Optimizar tu flujo de trabajo:

– Crear plantillas de proyectos para tareas recurrentes

– Configurar filtros personalizados para vistas eficientes

1. Aprender más sobre homelab:

– Consulta nuestros artículos sobre Docker Compose, n8n automatización y self-hosted productivity tools

1. Compartir tu experiencia:

– Únete a la comunidad de Vikunja en GitHub o r/selfhosted

📦 Descargar Ejemplos:

Todos los ejemplos de código, scripts y configuraciones de esta guía están disponibles en GitHub:

• 🔗 github.com/ziruelen/learningaiagents/vikunja

¿Necesitas ayuda?

• 📖 Documentación oficial de Vikunja
• 💬 Comunidad en GitHub Discussions
• 🔧 Reportar bugs o sugerir features

¡Feliz gestión de tareas con Vikunja! 🚀

—

Enlaces Relacionados

• Docker Compose: De 0 a Homelab Completo en 2025
• n8n: Automatiza 100+ Tareas Sin Código
• Guía Completa de Docker para Principiantes
• Traefik Reverse Proxy para Homelab
• Nextcloud: Tu Nube Privada Self-Hosted