Task Management with Vikunja

Vikunja is a task / project management application. The unpronounceable name apparently comes from a relative of the llama, overlooking the name for a moment this appears to be a great application. Deployment is a little trickier than with most applications as it, at a minimum, comes as three parts. You have a database, the api and the frontend. For the database you have a number of choices but I’m going with MariaDB (a fork of MySQL).

The absolute smallest deployment uses the compose shown below. This is close to the example given on the website with some tweaks to make it fit my environment. In particular I made the volume locations variables, I named the containers, and I changed the port for the frontend to 3080.

version: '3'

services:
  db:
    image: 'mariadb:10'
    command: '--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci'
    container_name: vikunja-db
    environment:
      - MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD
      - MYSQL_USER=$MYSQL_USER
      - MYSQL_PASSWORD=$MYSQL_PASSWORD
      - MYSQL_DATABASE=$MYSQL_DATABASE
    volumes:
      - $MYSQL_DATASTORE:/var/lib/mysql
    restart: unless-stopped
  api:
    image: vikunja/api
    container_name: vikunja-api
    environment:
      - VIKUNJA_DATABASE_HOST=$VIKUNJA_DATABASE_HOST
      - VIKUNJA_DATABASE_PASSWORD=$VIKUNJA_DATABASE_PASSWORD
      - VIKUNJA_DATABASE_TYPE=$VIKUNJA_DATABASE_TYPE
      - VIKUNJA_DATABASE_USER=$VIKUNJA_DATABASE_USER
      - VIKUNJA_DATABASE_DATABASE=$VIKUNJA_DATABASE_DATABASE
      - VIKUNJA_SERVICE_JWTSECRET=$VIKUNJA_SERVICE_JWTSECRET
      - VIKUNJA_SERVICE_FRONTENDURL=$VIKUNJA_SERVICE_FRONTENDURL
      - VIKUNJA_SERVICE_ENABLEREGISTRATION=$VIKUNJA_SERVICE_ENABLEREGISTRATION
    ports:
      - 3456:3456
    volumes:
      - $VIKUNJA_CONFIG:/app/vikunja/files
    depends_on:
      - db
    restart: unless-stopped
  frontend:
    image: vikunja/frontend
    container_name: vikunja-frontend
    ports:
      - 3080:80
    environment: 
      - VIKUNJA_API_URL=$VIKUNJA_API_URL
    restart: unless-stopped

#### MYSQL SETTINGS ####

MYSQL_ROOT_PASSWORD=root_secret
MYSQL_USER=vikunja
MYSQL_PASSWORD=user_secret
MYSQL_DATABASE=vikunja
MYSQL_DATASTORE=/data/vikunja/mysql

#### VIKUNJA API SETTINGS ####

# Name of the container running the database
VIKUNJA_DATABASE_HOST=vikunja-db
# Same as Mysql Password
VIKUNJA_DATABASE_PASSWORD=user_secret
# The type of database to use
VIKUNJA_DATABASE_TYPE=mysql
VIKUNJA_DATABASE_USER=vikunja
VIKUNJA_DATABASE_DATABASE=vikunja
# Token secret, this can change but it will invalidate sessions
VIKUNJA_SERVICE_JWTSECRET=a_long_random_string
# Apparently only used to send password rest emails
VIKUNJA_SERVICE_FRONTENDURL=http://vikunja.example.co.uk/
# Where the config and other files are stored
VIKUNJA_CONFIG=/data/vikunja/config
# Whether registrations are allowed. Initally this should be true, once all the accounts have been made switch it to false
VIKUNJA_SERVICE_ENABLEREGISTRATION='true'

#### VIKUNJA FROTNEND SETTINGS ####

# Address for the frontend to access teh backend
VIKUNJA_API_URL=http://vikunja.example.co.uk:3456/api/v1

To access the services configured above you’d visit http://media.example.co.uk:3080/ and it should just work. However, I want to reverse proxy it!

As this application has both a frontend and an api the reverse proxy configuration is a little more complex (I’m assuming you have a reverse proxy setup as pre my guide). The configuration given below should do it. There’s just one change you’ll need to make to the settings. The VIKUNJA_API_URL has to point to the same URL as the frontend or you’ll get CORS errors.

server {
        listen 80;
        server_name vikunja.example.co.uk;
        location / {
                proxy_pass      http://media.example.co.uk:3080;
        }

        location ~* ^/(api|dav|\.well-known)/ {
                proxy_pass http://media.example.co.uk:3456;
                client_max_body_size 20M;
        }
}

User Management

User management, at the time or writing, is absolutely terrible. There is no GUI interface for an admin to manage users but there is a very limited set of CLI tools. According to this message there might be a pay-for option developed in the future. I struggle to consider a project open source if it hides basic functionality behind a paywall. I have no problem with people making money off what they produce but call it what it is.

To get around this limitation I’ll create all the users I need and then set the environment variable VIKUNJA_SERVICE_ENABLEREGISTRATION on the API container to false. This will prevent accidental registrations.