Instalación de Vikunja: Gestión de Tareas Self-Hosted

Vikunja es una plataforma open-source de gestión de tareas y proyectos que combina listas de tareas, tableros Kanban, vistas de calendario y diagramas de Gantt en una sola aplicación. Con soporte para CalDAV, API REST, colaboración en equipo y notificaciones, Vikunja es la alternativa self-hosted a Todoist, Asana o Trello para equipos y usuarios que quieren control total sobre sus datos de productividad.

Requisitos Previos

Servidor con Ubuntu 20.04+, Debian 11+ o CentOS 8+
Docker y Docker Compose instalados
Mínimo 512 MB de RAM
Puerto 3456 disponible (API) o proxy inverso configurado
Base de datos MySQL/MariaDB, PostgreSQL o SQLite

Instalación con Docker Compose

# Crear directorio de instalación
mkdir -p ~/vikunja && cd ~/vikunja

# Crear el archivo docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3'

services:
  vikunja:
    image: vikunja/vikunja
    container_name: vikunja
    restart: unless-stopped
    ports:
      - 3456:3456
    environment:
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: contrasena-db-segura
      VIKUNJA_DATABASE_TYPE: mysql
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_SERVICE_JWTSECRET: $(openssl rand -hex 32)
      VIKUNJA_SERVICE_PUBLICURL: https://tareas.tu-dominio.com/
      VIKUNJA_MAILER_ENABLED: "false"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mariadb:10.11
    container_name: vikunja-db
    restart: unless-stopped
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    environment:
      MYSQL_ROOT_PASSWORD: contrasena-root
      MYSQL_USER: vikunja
      MYSQL_PASSWORD: contrasena-db-segura
      MYSQL_DATABASE: vikunja
    volumes:
      - ./db:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h localhost -u $$MYSQL_USER --password=$$MYSQL_PASSWORD"]
      interval: 2s
      start_period: 30s
EOF

# Crear directorios necesarios
mkdir -p ~/vikunja/{files,db}

# Iniciar los servicios
docker compose up -d

# Ver los logs de inicio
docker compose logs -f vikunja

Acceder a Vikunja en http://TU-SERVIDOR:3456 para crear la cuenta de administrador.

Configuración del Servidor Vikunja

Para configuración más avanzada, usar un archivo de configuración:

# Crear archivo de configuración personalizado
cat > ~/vikunja/config.yaml << 'EOF'
service:
  # URL pública del servidor (importante para enlances en emails)
  publicurl: https://tareas.tu-dominio.com
  # Tiempo de expiración del token JWT (en segundos)
  jwtttl: 259200  # 3 días
  # Tiempo de expiración del token de refresco
  jwtttllong: 2592000  # 30 días
  # Habilitar registro de nuevos usuarios
  enableregistration: true
  # Zona horaria del servidor
  timezone: Europe/Madrid
  # Número máximo de resultados por página en la API
  maxitemsperpage: 50

database:
  type: mysql
  host: db
  user: vikunja
  password: contrasena-db-segura
  database: vikunja

mailer:
  enabled: true
  host: smtp.tu-dominio.com
  port: 587
  authtype: plain
  username: [email protected]
  password: contrasena-smtp
  fromemail: [email protected]
  skiptlsverify: false

log:
  level: info

files:
  # Ruta donde se guardan los archivos adjuntos
  basepath: /app/vikunja/files/
  # Tamaño máximo de archivo en bytes (100MB)
  maxsize: 104857600
EOF

# Montar el archivo de configuración en docker-compose.yml
# En el servicio vikunja, agregar en volumes:
# - ./config.yaml:/app/vikunja/config.yaml:ro

Configuración de Proyectos y Tareas

Una vez conectado a la interfaz web:

Estructura de organización:

Espacio de trabajo (Workspace): Área principal de organización
Proyectos: Colecciones de tareas relacionadas
Tareas: Unidades individuales de trabajo con fecha límite, etiquetas y asignados
Subtareas: División de tareas complejas

Crear proyectos via API:

# Obtener token de autenticación
TOKEN=$(curl -s -X POST https://tareas.tu-dominio.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"contrasena"}' | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# Crear un proyecto nuevo
curl -s -X PUT https://tareas.tu-dominio.com/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Proyecto de Desarrollo",
    "description": "Tareas del equipo de desarrollo",
    "color": "#1565C0",
    "is_archived": false
  }' | python3 -m json.tool

# Crear una tarea en el proyecto
curl -s -X PUT https://tareas.tu-dominio.com/api/v1/projects/1/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Configurar servidor de staging",
    "description": "Configurar el servidor de staging con Docker",
    "due_date": "2024-12-31T23:59:00Z",
    "priority": 3,
    "percent_done": 0
  }' | python3 -m json.tool

Tableros Kanban

Vikunja soporta vista Kanban con columnas personalizables:

# Crear un tablero Kanban via API
# Primero crear un "bucket" (columna)
curl -s -X PUT https://tareas.tu-dominio.com/api/v1/projects/1/buckets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Por Hacer",
    "limit": 0
  }'

curl -s -X PUT https://tareas.tu-dominio.com/api/v1/projects/1/buckets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "En Progreso",
    "limit": 5
  }'

curl -s -X PUT https://tareas.tu-dominio.com/api/v1/projects/1/buckets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Completado"}'

Desde el panel web, cambiar a la vista Kanban con el icono de tablero en la barra superior.

Sincronización CalDAV

Vikunja implementa CalDAV para sincronizar tareas con calendarios:

# URL del servidor CalDAV de Vikunja
# https://tareas.tu-dominio.com/dav/

# Configurar en GNOME Calendar/Thunderbird:
# URL: https://tareas.tu-dominio.com/dav/
# Usuario: tu usuario de Vikunja
# Contraseña: tu contraseña de Vikunja

# Configurar en Nextcloud (como fuente externa)
# CalDAV principal: https://tareas.tu-dominio.com/dav/calendars/usuario/

Clientes CalDAV compatibles:

Thunderbird con Lightning
GNOME Calendar / Evolution
DAVx5 en Android
Apple Calendar en iOS/macOS

Notificaciones por Email

# Verificar la configuración del mailer
docker exec vikunja /app/vikunja/vikunja check --config /app/vikunja/config.yaml

# Probar el envío de email
curl -s -X POST https://tareas.tu-dominio.com/api/v1/user/settings/email/test \
  -H "Authorization: Bearer $TOKEN"

# Las notificaciones se activan automáticamente cuando:
# - Se te asigna una tarea
# - Se agrega un comentario a una tarea tuya
# - Una tarea llega a su fecha límite
# - Alguien menciona tu usuario en un comentario

# Configurar preferencias de notificación:
# Panel web > Configuración > Notificaciones

API de Vikunja

Vikunja tiene una API REST completa documentada en Swagger:

# Documentación interactiva de la API
# https://tareas.tu-dominio.com/api/v1/docs

# Endpoints principales:
# GET    /api/v1/projects              - Listar proyectos
# PUT    /api/v1/projects              - Crear proyecto
# GET    /api/v1/projects/{id}/tasks   - Listar tareas del proyecto
# PUT    /api/v1/projects/{id}/tasks   - Crear tarea
# POST   /api/v1/tasks/{id}            - Actualizar tarea
# DELETE /api/v1/tasks/{id}            - Eliminar tarea

# Ejemplo: Obtener todas las tareas pendientes
curl -s "https://tareas.tu-dominio.com/api/v1/tasks/all?filter_by=done&filter_value=false" \
  -H "Authorization: Bearer $TOKEN" | \
  python3 -c "import sys,json; [print(f\"- {t['title']}\") for t in json.load(sys.stdin)]"

# Marcar una tarea como completada
curl -s -X POST "https://tareas.tu-dominio.com/api/v1/tasks/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"done": true}' | python3 -m json.tool

Proxy Inverso con Nginx

# Obtener certificado SSL
sudo certbot --nginx -d tareas.tu-dominio.com

# Configuración de Nginx para Vikunja
sudo tee /etc/nginx/sites-available/vikunja << 'EOF'
server {
    listen 443 ssl http2;
    server_name tareas.tu-dominio.com;

    ssl_certificate /etc/letsencrypt/live/tareas.tu-dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tareas.tu-dominio.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3456;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        # WebSocket para notificaciones en tiempo real
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/vikunja /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Solución de Problemas

Vikunja no inicia:

# Ver logs detallados
docker compose logs vikunja --tail 50
docker compose logs db --tail 20

# Verificar que la base de datos está accesible
docker exec vikunja-db mariadb -u vikunja -pcontrasena-db-segura vikunja -e "SELECT 1"

# Comprobar la configuración
docker exec vikunja /app/vikunja/vikunja --help

Error al iniciar sesión o token inválido:

# El JWT_SECRET debe ser consistente entre reinicios
# Verificar la variable de entorno:
docker exec vikunja env | grep JWT

# Si cambió el secreto, todos los tokens existentes se invalidan
# Los usuarios deberán volver a iniciar sesión

CalDAV no sincroniza:

# Verificar que el endpoint CalDAV responde
curl -v https://tareas.tu-dominio.com/dav/ \
  -u "admin:contrasena" 2>&1 | grep -E "HTTP|DAVF"

# Verificar la configuración del proxy Nginx
# El CalDAV requiere soporte para los métodos PROPFIND, REPORT, etc.
# Agregar en Nginx:
# proxy_method $request_method;

Conclusión

Vikunja ofrece una gestión de tareas moderna y completa con una API robusta que permite integraciones con otras herramientas. Su soporte nativo para CalDAV facilita la sincronización con aplicaciones de calendario existentes, y su interfaz limpia con vistas Kanban y de Gantt lo hace adecuado tanto para uso personal como para equipos pequeños que buscan control total sobre su gestión de proyectos.

Vikunja Task Management Installation

On this page