Install Vikunja in Docker for self-hosted Task Tracking

In this guide, I’m going to show you how to install Vikunja using Docker-Compose. Vikunja is an open-source task management / task tracking application. It offers features of many popular cloud-hosted solutions such as Trello, TickTick, Todoist, or Microsoft To-Do – with that caveat that is selfhosted!

Currently, I use a combination of Google Keep for notetaking and the mobile app TickTick for task-tracking. Both of those solutions work pretty well for my needs, but honestly, I only really used those because there wasn’t a great selfhosted alternative. Until I stumbled across Vikunja.

Vikunja is the perfect solution for homelab enthusiasts looking for a way to track tasks, set reminders and due dates, categorize tasks into lists, and prioritize projects in your everyday life.

Note: Although you can expose Vikunja externally, I will not be exposing my instance with a reverse proxy or including instructions for that in this guide. Additional parameters for setting up a reverse proxy can be found here. Or, you can access Vikunja remotely by following either one of my guides:

• Install Wireguard VPN in Home Assistant to access self-hosted services
• Install Nginx Proxy Manager in Docker

Let’s get started!

---

Vikunja Features

Vikunja is one of the most fully-featured self-hosted task tracking softwares available today. As of writing this guide, I’m am installing Vikunja 0.18, which includes some of the following features:

• Organize tasks into list
• Group lists together
• Collaborate / share lists with others
• Classic list or Gantt view
• Ability to set due dates/reminders
• Ability to set recurring tasks
• Kanban board
• Import existing lists from Trello, Microsoft To-Do, or Todoist

There’s a lot more it can do too, so I suggest spinning it up yourself and seeing if it meets your needs.

---

Step 1: Install Docker and Docker-Compose

Before you get started, you’ll first need to have Docker-Compose installed. If you don’t have that installed yet, you can follow step 1 of my How To Install Docker-Compose in Ubuntu guide.

---

Step 2: SSH into your Docker host

First, you’ll need to SSH into your environment which has Docker-Compose installed. You can use Putty or any other SSH tool (I prefer Termius myself).

I typically put all of my Docker containers into one directory (/srv/config), so the first step is to navigate to that directory.

cd /srv/config

Then, create a new folder:

mkdir vikunja

Next, navigate into the newly created folder:

cd /srv/config/vikunja

---

Step 3: Create Docker-Compose.yml file

To create the docker-compsoe file for Vikunja, enter this command:

touch docker-compose.yml

Now, we need to edit this file using the Nano file editor and paste in the Docker-Compose.yml example file from their website.

nano docker-compose.yml

Then, paste in the file below. You will want to change the default usernames and passwords below. Other than that, you can copy everything exactly as below.

version: '3'

services:
  db:
    image: mariadb:10
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    environment:
      MYSQL_ROOT_PASSWORD: supersecret
      MYSQL_USER: vikunja
      MYSQL_PASSWORD: secret
      MYSQL_DATABASE: vikunja
    volumes:
      - ./db:/var/lib/mysql
    restart: unless-stopped
  api:
    image: vikunja/api
    environment:
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: secret
      VIKUNJA_DATABASE_TYPE: mysql
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_DATABASE: vikunja
    volumes: 
      - ./files:/app/vikunja/files
    depends_on:
      - db
    restart: unless-stopped
  frontend:
    image: vikunja/frontend
    restart: unless-stopped
  proxy:
    image: nginx
    ports:
      - 80:80
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - api
      - frontend
    restart: unless-stopped

To save the Docker-compose file, press CTRL + X, then Y for yes, and then ENTER.

---

Step 4: Create Nginx.conf file

After the docker-compose file has been created, we need to create one more file for the proxy service (even if you aren’t using a reverse-proxy, this portion is required).

Assuming you are still in your vikunja directory (in my case, /srv/config/vikunja), create a new file called nginx.conf:

touch nginx.conf

Then, edit the file:

nano nginx.conf

Paste this in:

server {
    listen 80;

    location / {
        proxy_pass http://frontend:80;
    }

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

Then save this file by clicking CTRL + X, Y, and Enter.

---

Step 5: Confirm both files have been created

To confirm both files have successfully been created, you can simply run this when in your Vikunja directory

ls

---

Step 6: Launch and Run Vikunja Containers

Now that everything has been created, it’s time to launch the containers.

sudo docker-compose up -d

In the docker-compose file, we told it to run on port 80. After a minute or so, you should be able to launch Vikuna from your docker host IP using port 80 in a web browser ( i.e – 192.168.68.137:80)

---

Step 7: Register for a new account

The first thing you’ll need to do is register for your Vikunja account. This is pretty straightforward, but just click Register and enter a username, email address and password.

It will automatically log you in afterwards.

---

Step 8: Basic Use and Setup

Once you log in for the first time, you’ll be able to create a new list right or import your data from Trello, Todoist, or Microsoft To-Do. I won’t be importing anything as I’m currently using TickTick, so I’m just going to create a brand new list.

---

Create Lists

A list can be thought of as a parent folder or topic, where different tasks or lists of tasks can go inside of. It’s a great way to organize similar tasks together rather than keeping everything in one giant list.

To start out, I am creating 5 lists. Each list can be given their own color.

• Home Projects
• Home Assistant
• Smart Home Pursuits
• Docker
• Personal

---

Create Tasks

To create a new task, first click into the list from the sidebar. Then, just add a new task. After the task has been created, you can click the pencil icon to view some basic options of the task (Title, Description, Reminders, labels, task colors, etc).

You can also cycle between different views such as List, Gantt, Table, or Kanban.

Or, if you click the task itself – you’ll find a ton of other configurable options like:

---

Vikunja Wishlist Items

Overall, I’m really pleased with Vikunja. I have completely moved over of my tasks and todo lists to it after installing it.

A couple things I’d like to point out is that:

1. Setting Due Dates only works on the hour. For example, you can set a Due Date for 11:00pm, and even though there is a time picker for add minutes and make it 11:30pm, it reverts to 11pm.
2. Notifications. I am going to miss mobile notifications whenever certain tasks or recurring tasks are due. I’m hoping to someday to have the ability to get notifications via Telegram or Gotify, but in the meantime – it’s easy enough to log into the app via my Homer Dashboard and quickly see what items are due. There is a bell icon at the very top that keeps track of your reminder items.

---

Wrapping Up

All in all, I think Vikunja is a fantastic self-hosted task management solution. It offers many of the features of the biggest cloud providers on the market, it’s free and open-source, and is actively developed.

If you’ve been looking for a todo app to prioritize your home projects, definitely check it out!

---

My Homelab Equipment

Here is some of the gear I use in my Homelab. I highly recommend each of them.

• Server 2019 w/ Hyper-V
• Case: Fractal Design Node 804
• Graphics Card: NVIDEA Quadro K600
• CPU: AMD Ryzen 7 2700

The full list of server components I use can be found on my Equipment List page.