# Vikunja

> Open-source task management and to-do app.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: vikunja, mariadb
- Tags: vikunja, tasks, todo, planning
- Source: https://docker.recipes/productivity/vikunja

## Overview

Vikunja is a powerful open-source task management and to-do application that provides teams and individuals with comprehensive project organization tools. Born from the need for a privacy-focused alternative to proprietary task managers, Vikunja offers advanced features like Kanban boards, Gantt charts, time tracking, and CalDAV integration while maintaining complete data ownership. The application supports multiple project views, collaborative workspaces, and extensive customization options that rival enterprise solutions.

This deployment combines Vikunja with MariaDB to create a robust, production-ready task management system. MariaDB's enhanced performance characteristics and improved JSON handling make it ideal for Vikunja's complex data structures, including nested tasks, project hierarchies, and user permissions. The database's Aria storage engine provides better crash recovery for task data, while its advanced indexing capabilities ensure fast search and filtering across large project datasets.

This stack is perfect for development teams, small businesses, and organizations seeking complete control over their project management data. Unlike cloud-based alternatives, this self-hosted solution ensures sensitive project information remains within your infrastructure while providing enterprise-grade features like LDAP authentication, webhook integrations, and comprehensive API access for custom workflows.

## Features

- Multiple project views including List, Kanban, Table, and interactive Gantt charts for comprehensive project visualization
- CalDAV endpoint integration allowing synchronization with external calendar applications and mobile devices
- Built-in data migration tools supporting imports from Todoist, Trello, Microsoft To-Do, and other popular task managers
- MariaDB's enhanced JSON functions providing faster query performance for Vikunja's complex task metadata and custom fields
- Advanced task relationships including subtasks, dependencies, and cross-project linking with visual dependency mapping
- Time tracking and reporting features with detailed analytics on project progress and team productivity
- Collaborative workspaces with granular permission controls for teams, projects, and individual task assignments
- MariaDB's Galera Cluster compatibility enabling high-availability deployments for mission-critical project management

## Use cases

- Software development teams managing sprints, backlogs, and release planning with Kanban and Gantt chart visualization
- Marketing agencies coordinating campaign timelines, client deliverables, and creative asset production workflows
- Construction and project management companies tracking milestones, dependencies, and resource allocation across multiple sites
- Educational institutions managing curriculum development, research projects, and administrative task coordination
- Non-profit organizations coordinating volunteer activities, fundraising campaigns, and community outreach programs
- Personal productivity enthusiasts seeking advanced GTD (Getting Things Done) implementation with calendar integration
- Remote teams requiring collaborative task management with detailed progress tracking and reporting capabilities

## Prerequisites

- Minimum 1GB RAM recommended for MariaDB with moderate task datasets and multiple concurrent users
- Port 3456 available for Vikunja web interface access and API communications
- Basic understanding of task management concepts including projects, labels, and user permission structures
- Environment variable management knowledge for configuring database passwords and frontend URLs
- Storage planning for task attachments, as Vikunja files volume will grow with document uploads
- Network configuration knowledge if deploying behind reverse proxy for SSL termination and custom domains

## docker-compose.yml

```yaml
services:
  vikunja:
    image: vikunja/vikunja:latest
    container_name: vikunja
    restart: unless-stopped
    environment:
      VIKUNJA_DATABASE_TYPE: mysql
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: ${DB_PASSWORD}
      VIKUNJA_SERVICE_FRONTENDURL: http://localhost:3456/
    ports:
      - "3456:3456"
    volumes:
      - vikunja_files:/app/vikunja/files
    depends_on:
      - db

  db:
    image: mariadb:10
    container_name: vikunja-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
      MYSQL_DATABASE: vikunja
      MYSQL_USER: vikunja
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - vikunja_db:/var/lib/mysql

volumes:
  vikunja_files:
  vikunja_db:
```

## .env

```bash
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://vikunja.io/docs/
- Access at http://localhost:3456 - register first user as admin
- MariaDB backend for better performance at scale
- Views: List, Kanban, Table, and Gantt charts
- CalDAV endpoint for calendar sync at /dav/
- Migrate from Todoist, Trello, MS To-Do via import

## Troubleshooting

- Database connection failed: Verify DB_PASSWORD environment variable matches between Vikunja and MariaDB containers
- First user registration not creating admin privileges: Ensure clean database state and restart Vikunja container after MariaDB initialization
- CalDAV sync failing with calendar applications: Check VIKUNJA_SERVICE_FRONTENDURL points to externally accessible address, not localhost
- Task attachments not persisting: Confirm vikunja_files volume is properly mounted and container has write permissions
- MariaDB container exits with initialization errors: Remove vikunja_db volume and restart to reinitialize database with correct credentials
- Import from external services timing out: Increase MariaDB's max_allowed_packet setting for large dataset imports from Trello or Todoist

