Self-Host Vikunja on Docker: The Modern, Private Alternative to Todoist

The High Cost of ‘Free’ Productivity

Managing projects shouldn’t feel like a side-hustle just to stay organized. I spent years juggling Todoist for daily chores, Trello for side projects, and Jira for technical tickets. While they worked, I eventually hit a wall: my data was trapped in proprietary silos, and essential features like Gantt charts were locked behind $10/month subscriptions. If you’re tired of subscription fatigue and want total control over your project data, it’s time to move your tasks home.

SaaS platforms prioritize recurring revenue over user sovereignty. For HomeLab enthusiasts, the alternative is clear: self-hosting. Vikunja is the solution I finally settled on. It is a lean, open-source powerhouse that handles Kanban boards, structured tables, and complex Gantt charts without breaking a sweat. It provides the polish of a commercial app with the privacy of a local database.

Quick Start: Deploy in 5 Minutes

Fire up your terminal. If you have Docker and Docker Compose ready, you can deploy a full Vikunja instance faster than you can brew a fresh pot of coffee. We will use a three-container stack to keep the database, logic, and interface separate.

First, create a dedicated project folder:

mkdir vikunja && cd vikunja
nano docker-compose.yml

Copy this configuration into your file. Note: I have updated the VIKUNJA_API_URL to ensure it works when you access it from other devices on your network.

services:
  db:
    image: postgres:14-alpine
    restart: always
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: ChangeThisSecurePassword
      POSTGRES_DB: vikunja
    volumes:
      - ./db:/var/lib/postgresql/data

  api:
    image: vikunja/api
    restart: always
    environment:
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: ChangeThisSecurePassword
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_NAME: vikunja
      # Generate a random string for the secret below
      VIKUNJA_SERVICE_JWTSECRET: "sh4red-secret-k3y-change-me"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      - db

  frontend:
    image: vikunja/frontend
    restart: always
    ports:
      - 8080:80
    environment:
      # Replace 'your-server-ip' with your actual local IP (e.g., 192.168.1.50)
      VIKUNJA_API_URL: http://your-server-ip:8080/api/v1
    depends_on:
      - api

Once saved, launch the stack:

docker compose up -d

Head to http://your-server-ip:8080 in your browser. You will see the clean Vikunja welcome screen. Click “Register” to create your primary admin account and start building your first list.

Why This Architecture Matters

Understanding the ‘why’ behind the setup is what separates a hobbyist from a pro. Vikunja uses a decoupled architecture: the API (the logic), the Frontend (the interface), and the Database (the storage). This isn’t just tech jargon; it means if you want to swap the web interface for a custom CLI or mobile app, the core stays intact.

Why separate them? Because the Frontend is a static application executed by your browser. This is why the VIKUNJA_API_URL is so critical. If you leave it as ‘localhost’, your browser will try to find the API on your laptop rather than the server. If you eventually move this behind a reverse proxy like Nginx Proxy Manager, you’ll simply update this URL to your domain name.

Boosting Performance with Redis

When my ‘HomeLab Upgrades’ list hit 1,200 items, the interface felt a bit sluggish. Adding Redis as a cache layer dropped my dashboard load times from 1.5 seconds to under 200ms. Just add a Redis service to your YAML and point the API to it using VIKUNJA_CACHE_TYPE: redis.

Hardening and Notifications

A task manager that doesn’t nag you is just a digital graveyard. To get email reminders working, you need an SMTP connection. If you use a Gmail account with 2FA, you’ll need a 16-character App Password. Add your SMTP credentials to the API environment variables to ensure you never miss a deadline again.

Lock down your server once your team is onboarded. Open registration is a magnet for bots. By setting VIKUNJA_SERVICE_ENABLEREGISTRATION: "false", you ensure your HomeLab stays your private sanctuary.

Real-World Workflow Tips

The tool is only as good as your habits. Here is how I actually use Vikunja every day:

• The 2-Minute Rule: I use the ‘Incoming’ bucket for every random thought. If it takes less than 2 minutes, I do it immediately. If not, it gets a due date.
• Visualizing Progress: Use Kanban for active projects like ‘Server Migration.’ Seeing tasks move from ‘Testing’ to ‘Done’ provides a psychological win that a simple checkbox can’t match.
• Sync Everywhere: Grab the mobile app from F-Droid. It connects directly to your self-hosted API, giving you Todoist-level convenience without the cloud-privacy trade-off.
• Effortless Migration: I moved 45 active projects from Todoist in under three minutes using the built-in importer. It even preserved my priority labels and recurring dates.

Self-hosting Vikunja bridges the gap between ‘too basic’ and ‘enterprise nightmare.’ It is fast, private, and scales with your ambition. Stop renting your productivity and start owning it.