Skip to main content

Vikunja - Task Manager & To-Do List

Description

Vikunja is a task manager / to-do list application. It features organization, scheduling, and (my favorite part) Kanban boards.

Access

Vikunja is reverse-proxied by the Secure Web Application Gateway. It is published on tasks.kasad.com.

Cloudflare Access authentication/authorization is required to access the Vikunja instance.

Deployment details

Docker container stack

Vikunja consists of two containers: (1) the backend/API and (2) the web interface frontend. The images for those containers are

  1. vikunja/api:latest
  2. vikunja/frontend:latest

The Docker Compose file for the stack follows:

version: '3'

services:
 api:
   image: vikunja/api
   container_name: vikunja-api
   environment:
     PUID: 938 # swag
     PGID: 941 # servlets
     VIKUNJA_DATABASE_TYPE: sqlite
     VIKUNJA_DATABASE_PATH: ./data/vikunja.db
     VIKUNJA_FILES_BASEPATH: ./data/files
     VIKUNJA_SERVICE_JWTSECRET: [redacted]
     VIKUNJA_SERVICE_FRONTENDURL: https://tasks.kasad.com/
     VIKUNJA_SERVICE_ENABLEREGISTRATION: false
     VIKUNJA_SERVICE_TIMEZONE: America/Los_Angeles
     TZ: America/Los_Angeles
     VIKUNJA_CORS_ENABLE: true
     VIKUNJA_CORS_ORIGINS: https://tasks.kasad.com
     VIKUNJA_MAILER_ENABLED: true
     VIKUNJA_MAILER_HOST: mail.kasad.com
     VIKUNJA_MAILER_PORT: 587
     VIKUNJA_MAILER_FORCESSL: false
     VIKUNJA_MAILER_AUTHTYPE: plain
     VIKUNJA_MAILER_USERNAME: vikunja
     VIKUNJA_MAILER_PASSWORD: [redacted]
     VIKUNJA_MAILER_FROMEMAIL: noreply@tasks.kasad.com
   volumes:
     - /srv/vikunja/config.yml:/app/vikunja/config.yml:ro
     - /srv/vikunja/data:/app/vikunja/data
   networks:
     - default
     - swag
   restart: unless-stopped
   
 frontend:
   image: vikunja/frontend
   container_name: vikunja-frontend
   environment:
     VIKUNJA_API_URL: https://tasks.kasad.com/api/v1/
   networks:
     - default
     - swag
   restart: unless-stopped
   
networks:
 swag:
   name: swag_default
   external: true

Configuration

The Vikunja frontend is typically configured using a YAML configuration file. However with the Docker container, it's easier to use environment variables. The environment variables' names are just the flattened representation of the configuration file's keys, prefixed with VIKUNJA_.

For example, the following environment file and YAML file represent the same configuration:

VIKUNJA_MAILER_ENABLED=true
VIKUNJA_MAILER_HOST=mail.kasad.com
VIKUNJA_MAILER_PORT=587
VIKUNJA_MAILER_FORCESSL=false
mailer:
  enabled: true
  host: mail.kasad.com
  port: 587
  forcessl: false

Database

Vikunja supports multiple database backends. As this is a relatively small instance, a SQLite3 database is used (VIKUNJA_DATABASE_TYPE: sqlite). The database path is set to ./data/vikunja.db so that the database will be located inside the data volume. (This is the VIKUNJA_DATABASE_PATH option).

File storage location

Vikunja supports file attachments. The location where uploaded files are stored is set to ./data/files so it is inside the data volume and doesn't require a separate persistent volume. (This is the VIKUNJA_FILES_BASEPATH option).

OpenID Connect parameters

All configuration can be done via environment variables except for OIDC configuration. Instead, that must be done within a YAML configuration file. In the Docker container, this file is located at /app/vikunja/config.yml.

Here is the configuration for Vikunja to use Authentik as the auth provider:

auth:
  local:
    enabled: false

  openid:
    enabled: true
    redirecturl: https://tasks.kasad.com/auth/openid/
    providers:
      - name: Kasad Auth
        authurl: https://auth2.kasad.com/application/o/vikunja/
        clientid: [redacted]
        clientsecret: [redacted]
Authentik provider configuration

In Authentik, create a new OpenID Connect provider. Add the two following redirect URLs:

https://tasks.kasad.com/auth/openid/
https://tasks.kasad.com/auth/openid/kasadauth

Under Advanced protocol settings, ensure Issuer mode is set to Each provider has a different issuer, based on the application slug.. Vikunja expects the issuer to be the same as the authurl parameter in the configuration file, which is what this setting enables.

Sending Email

Vikunja can send email reminders. In order to do this, it needs to connect to an SMTP server. A mail-enabled account has been created for Vikunja at mail.kasad.com with the username vikunja. It is authorized to send emails from any user at the tasks.kasad.com domain. See the Sending Emails from Web Apps page for details.