docker.recipes

Vikunja Task Management

intermediate

Vikunja to-do app with PostgreSQL and Redis.

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.

Key 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

Common Use Cases

  • 1Software development teams tracking bugs, features, and sprint planning with hierarchical project organization
  • 2Marketing agencies managing client projects, campaign tasks, and deliverable timelines with team collaboration
  • 3Educational institutions coordinating curriculum development, administrative tasks, and faculty assignments
  • 4Small businesses organizing operational tasks, client projects, and internal process management
  • 5Remote teams requiring centralized task coordination with calendar integration for deadline management
  • 6Personal productivity enthusiasts seeking advanced task management with cross-device synchronization
  • 7Consulting 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  vikunja: 
3    image: vikunja/vikunja:latest
4    container_name: vikunja
5    restart: unless-stopped
6    ports: 
7      - "${VIKUNJA_PORT:-3456}:3456"
8    environment: 
9      - VIKUNJA_DATABASE_TYPE=postgres
10      - VIKUNJA_DATABASE_HOST=vikunja-db
11      - VIKUNJA_DATABASE_DATABASE=vikunja
12      - VIKUNJA_DATABASE_USER=${DB_USER}
13      - VIKUNJA_DATABASE_PASSWORD=${DB_PASSWORD}
14      - VIKUNJA_REDIS_ENABLED=true
15      - VIKUNJA_REDIS_HOST=vikunja-redis:6379
16      - VIKUNJA_SERVICE_JWTSECRET=${JWT_SECRET}
17    volumes: 
18      - vikunja_files:/app/vikunja/files
19    depends_on: 
20      - vikunja-db
21      - vikunja-redis
22
23  vikunja-db: 
24    image: postgres:15-alpine
25    container_name: vikunja-db
26    restart: unless-stopped
27    environment: 
28      - POSTGRES_USER=${DB_USER}
29      - POSTGRES_PASSWORD=${DB_PASSWORD}
30      - POSTGRES_DB=vikunja
31    volumes: 
32      - vikunja_db_data:/var/lib/postgresql/data
33
34  vikunja-redis: 
35    image: redis:7-alpine
36    container_name: vikunja-redis
37    restart: unless-stopped
38
39  nginx: 
40    image: nginx:alpine
41    container_name: vikunja-nginx
42    restart: unless-stopped
43    ports: 
44      - "${NGINX_PORT:-80}:80"
45    volumes: 
46      - ./nginx.conf:/etc/nginx/nginx.conf:ro
47
48volumes: 
49  vikunja_files: 
50  vikunja_db_data:

.env Template

.env
1# Vikunja
2VIKUNJA_PORT=3456
3DB_USER=vikunja
4DB_PASSWORD=vikunja_password
5JWT_SECRET=your_jwt_secret
6NGINX_PORT=80

Usage Notes

  1. 1Vikunja at http://localhost:3456
  2. 2Register new account
  3. 3Mobile apps available
  4. 4CalDAV support included

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

vikunja
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
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
vikunja-redis:
  image: redis:7-alpine
  container_name: vikunja-redis
  restart: unless-stopped
nginx
nginx:
  image: nginx:alpine
  container_name: vikunja-nginx
  restart: unless-stopped
  ports:
    - ${NGINX_PORT:-80}:80
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf:ro

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  vikunja:
5    image: vikunja/vikunja:latest
6    container_name: vikunja
7    restart: unless-stopped
8    ports:
9      - "${VIKUNJA_PORT:-3456}:3456"
10    environment:
11      - VIKUNJA_DATABASE_TYPE=postgres
12      - VIKUNJA_DATABASE_HOST=vikunja-db
13      - VIKUNJA_DATABASE_DATABASE=vikunja
14      - VIKUNJA_DATABASE_USER=${DB_USER}
15      - VIKUNJA_DATABASE_PASSWORD=${DB_PASSWORD}
16      - VIKUNJA_REDIS_ENABLED=true
17      - VIKUNJA_REDIS_HOST=vikunja-redis:6379
18      - VIKUNJA_SERVICE_JWTSECRET=${JWT_SECRET}
19    volumes:
20      - vikunja_files:/app/vikunja/files
21    depends_on:
22      - vikunja-db
23      - vikunja-redis
24
25  vikunja-db:
26    image: postgres:15-alpine
27    container_name: vikunja-db
28    restart: unless-stopped
29    environment:
30      - POSTGRES_USER=${DB_USER}
31      - POSTGRES_PASSWORD=${DB_PASSWORD}
32      - POSTGRES_DB=vikunja
33    volumes:
34      - vikunja_db_data:/var/lib/postgresql/data
35
36  vikunja-redis:
37    image: redis:7-alpine
38    container_name: vikunja-redis
39    restart: unless-stopped
40
41  nginx:
42    image: nginx:alpine
43    container_name: vikunja-nginx
44    restart: unless-stopped
45    ports:
46      - "${NGINX_PORT:-80}:80"
47    volumes:
48      - ./nginx.conf:/etc/nginx/nginx.conf:ro
49
50volumes:
51  vikunja_files:
52  vikunja_db_data:
53EOF
54
55# 2. Create the .env file
56cat > .env << 'EOF'
57# Vikunja
58VIKUNJA_PORT=3456
59DB_USER=vikunja
60DB_PASSWORD=vikunja_password
61JWT_SECRET=your_jwt_secret
62NGINX_PORT=80
63EOF
64
65# 3. Start the services
66docker compose up -d
67
68# 4. View logs
69docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/vikunja-tasks-stack/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

vikunjapostgresqlredisnginx

Tags

#vikunja#tasks#todo#project-management

Category

Productivity & Collaboration

Related Recipes

Ad Space