# Vikunja Task Management

> Vikunja to-do app with PostgreSQL and Redis.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: vikunja, postgresql, redis, nginx
- Tags: vikunja, tasks, todo, project-management
- Source: https://docker.recipes/productivity/vikunja-tasks-stack

## Overview

Vikunja is a modern, open-source to-do application and project management tool that emphasizes simplicity, collaboration, and cross-platform accessibility. Born from the need for a privacy-focused alternative to proprietary task management solutions, Vikunja offers features like task hierarchies, labels, assignees, due dates, attachments, and CalDAV/CardDAV support for synchronization with external calendar applications. Its clean interface supports both individual productivity workflows and team collaboration scenarios.

This deployment orchestrates four specialized services: the main Vikunja application server, a PostgreSQL database for reliable task and project data storage, Redis for caching and session management to improve performance, and NGINX as a reverse proxy for optimized web traffic handling. The PostgreSQL backend ensures ACID compliance for critical task data, while Redis accelerates frequent operations like user sessions and temporary data storage. NGINX provides efficient static file serving and can be configured for SSL termination and load balancing.

This stack is ideal for teams and organizations seeking a self-hosted project management solution with enterprise-grade data reliability. The combination of Vikunja's comprehensive task management features with PostgreSQL's robust data integrity makes it suitable for businesses that need dependable project tracking without vendor lock-in. The Redis caching layer ensures responsive performance even under heavy usage, while NGINX provides production-ready web serving capabilities.

## Features

- Hierarchical task organization with projects, lists, and subtasks supporting complex workflow structures
- CalDAV and CardDAV integration allowing synchronization with external calendar and contact applications
- Real-time collaboration with task assignments, comments, and activity feeds for team coordination
- Advanced task filtering and sorting with labels, priorities, assignees, and custom date ranges
- File attachment support with secure storage in Docker volumes for project-related documents
- PostgreSQL backend ensuring ACID compliance and data integrity for critical project information
- Redis-powered caching improving application responsiveness and user session management
- Mobile application support with native iOS and Android apps connecting to the same backend

## Use cases

- Software development teams tracking bugs, features, and sprint planning with hierarchical project organization
- Marketing agencies managing client projects, campaign tasks, and deliverable timelines with team collaboration
- Educational institutions coordinating curriculum development, administrative tasks, and faculty assignments
- Small businesses organizing operational tasks, client projects, and internal process management
- Remote teams requiring centralized task coordination with calendar integration for deadline management
- Personal productivity enthusiasts seeking advanced task management with cross-device synchronization
- Consulting firms managing multiple client engagements with separate project workspaces and time tracking

## Prerequisites

- Docker and Docker Compose installed with minimum 2GB RAM for PostgreSQL and Redis performance
- Available ports 80 (NGINX) and 3456 (Vikunja) or alternative ports configured via environment variables
- Environment variables configured: DB_USER, DB_PASSWORD, and JWT_SECRET for secure authentication
- Basic understanding of task management workflows and project organization principles
- NGINX configuration file (nginx.conf) prepared for reverse proxy setup and static file serving
- Storage capacity planning for task attachments and PostgreSQL data growth over time

## docker-compose.yml

```yaml
services:
  vikunja:
    image: vikunja/vikunja:latest
    container_name: vikunja
    restart: unless-stopped
    ports:
      - "${VIKUNJA_PORT:-3456}:3456"
    environment:
      - VIKUNJA_DATABASE_TYPE=postgres
      - VIKUNJA_DATABASE_HOST=vikunja-db
      - VIKUNJA_DATABASE_DATABASE=vikunja
      - VIKUNJA_DATABASE_USER=${DB_USER}
      - VIKUNJA_DATABASE_PASSWORD=${DB_PASSWORD}
      - VIKUNJA_REDIS_ENABLED=true
      - VIKUNJA_REDIS_HOST=vikunja-redis:6379
      - VIKUNJA_SERVICE_JWTSECRET=${JWT_SECRET}
    volumes:
      - vikunja_files:/app/vikunja/files
    depends_on:
      - vikunja-db
      - vikunja-redis

  vikunja-db:
    image: postgres:15-alpine
    container_name: vikunja-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=vikunja
    volumes:
      - vikunja_db_data:/var/lib/postgresql/data

  vikunja-redis:
    image: redis:7-alpine
    container_name: vikunja-redis
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    container_name: vikunja-nginx
    restart: unless-stopped
    ports:
      - "${NGINX_PORT:-80}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

volumes:
  vikunja_files:
  vikunja_db_data:
```

## .env

```bash
# Vikunja
VIKUNJA_PORT=3456
DB_USER=vikunja
DB_PASSWORD=vikunja_password
JWT_SECRET=your_jwt_secret
NGINX_PORT=80
```

## Usage notes

- Vikunja at http://localhost:3456
- Register new account
- Mobile apps available
- CalDAV support included

## Troubleshooting

- Vikunja container fails to start with database connection errors: Verify DB_USER, DB_PASSWORD environment variables match PostgreSQL credentials and ensure vikunja-db container is healthy
- Tasks load slowly or session timeouts occur frequently: Check vikunja-redis container status and verify VIKUNJA_REDIS_ENABLED=true and correct Redis host configuration
- File attachments fail to upload or disappear after restart: Ensure vikunja_files Docker volume is properly mounted and has sufficient disk space available
- PostgreSQL connection refused errors: Confirm vikunja-db container is running and VIKUNJA_DATABASE_HOST points to 'vikunja-db' service name, not localhost
- NGINX returns 502 Bad Gateway errors: Verify nginx.conf proxy configuration points to vikunja:3456 and check that Vikunja container is responding on internal port 3456
- JWT authentication errors or constant login prompts: Generate a secure JWT_SECRET environment variable with sufficient entropy and restart all containers

