Vikunja is an open-source task manager: personal to-do lists, shared projects, and multiple views of the same tasks — list, table, Kanban and Gantt. It supports labels, due dates, reminders, recurring tasks, attachments, teams and sharing links, plus CalDAV for syncing tasks with other apps. Hosting it yourself keeps your plans private and free of per-user fees.

Requirements

  • A VPS with Docker (1 GB RAM is enough for a small team; 2 GB is comfortable).
  • A domain or subdomain, e.g. tasks.example.com, pointing to the server.

1. Docker Compose

Recent Vikunja versions ship the API and web front end as a single image.

mkdir -p /srv/vikunja/{files,db} && cd /srv/vikunja
chown 1000 files

compose.yaml:

services:
  vikunja:
    image: vikunja/vikunja:latest
    restart: unless-stopped
    environment:
      VIKUNJA_SERVICE_PUBLICURL: https://tasks.example.com
      VIKUNJA_SERVICE_JWTSECRET: ${JWT_SECRET}
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: ${DB_PASSWORD}
      VIKUNJA_DATABASE_DATABASE: vikunja
    ports:
      - "127.0.0.1:3456:3456"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: vikunja
    volumes:
      - ./db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U vikunja"]
      interval: 5s
      retries: 10

.env:

cat > .env <<EOF
JWT_SECRET=$(openssl rand -hex 32)
DB_PASSWORD=$(openssl rand -hex 16)
EOF
chmod 600 .env
docker compose up -d

Check the docs for your version — environment variable names follow the VIKUNJA_<SECTION>_<KEY> pattern of the config file.

2. HTTPS with Nginx

Proxy tasks.example.com to 127.0.0.1:3456 and add a certificate with Certbot — see Nginx reverse proxy for Docker containers. Raise client_max_body_size if you’ll upload attachments.

3. Create accounts

With registration disabled, create users from the command line:

docker compose exec vikunja /app/vikunja/vikunja user create \
  -u alice -e [email protected] -p 'a-strong-password'

(Or enable registration temporarily, create accounts, then disable it again.)

4. Email reminders and notifications

Add SMTP settings so Vikunja can send reminders, password resets and notifications:

      VIKUNJA_MAILER_ENABLED: "true"
      VIKUNJA_MAILER_HOST: smtp.example.com
      VIKUNJA_MAILER_PORT: "587"
      VIKUNJA_MAILER_USERNAME: [email protected]
      VIKUNJA_MAILER_PASSWORD: ${SMTP_PASSWORD}
      VIKUNJA_MAILER_FROMEMAIL: [email protected]

Use a transactional email provider or your own mail server. If you send directly from the VPS, you need open SMTP ports and rDNS — available on our USA VPS (see Email VPS); on other locations use an external SMTP service.

5. Using Vikunja

  • Projects contain tasks; create child projects for structure.
  • Switch between List, Table, Kanban and Gantt views per project.
  • Teams share projects with permissions (read, write, admin).
  • Link shares give read-only or editable access without an account.
  • CalDAV syncs tasks with apps like Thunderbird or mobile task apps.
  • Import from other to-do services is available in settings.

6. Backups and updates

Back up the database and the files directory nightly:

docker compose exec -T db pg_dump -U vikunja vikunja | gzip > /var/backups/vikunja-$(date +%F).sql.gz

Include /srv/vikunja/files in your off-site backups (automated VPS backups). Update:

docker compose pull && docker compose up -d

Read release notes before major upgrades.

Single sign-on

Vikunja supports OpenID Connect, so you can log in with an identity provider like Authentik — handy if you self-host several tools. Other apps that pair well on the same server: Passbolt for passwords and SFTPGo for files. A small Docker VPS runs all of them.

  • Productivity
  • Docker
  • Self-Hosting