Installing Vikunja in Docker

Containers Sep 11, 2021

Vikunja is a well-respected to-do / task based app which gives you a fair amount of functionality and options. You can use lists, kanban or gantt charts, and you can share and collaborate with other users.

Today we'll look at how to self-host it. We'll be using docker-compose with a .env file to create this app. The stack iteself has a few moving parts: a database, the api (backend), the frontend, and a proxy (nginx).

Creating our network and directories

The first thing we'll do is create some directories which are required for the services mentioned above. We can do this in a number of ways, I'll focus on SSH as our method.

  • Log in to your box with SSH, and navigate to your docker directory (from now on I'll call this the '$DOCKERDIR')
  • Run the following commands:
mkdir vikunja
cd vikunja
mkdir db && mkdir files && mkdir nginx
this creates our Vikunja directory, and then the db, files and nginx directories inside it
  • Type in ls to make sure the folders have been created - you should see something like this:
we've created our vikunja directory, and the db, files and nginx subdirectories
  • Navigate inside your nginx directory and type in touch nginx.conf to create the nginx.conf file (we'll come back to this later)
  • Now we'll create our docker network, by typing:
docker network create vikunja
you can read up more on docker networking here

Creating our docker-compose file

  • Let's go back up to our vikunja directory. Type cd .. to do so
  • We'll now create our docker-compose file by typing touch docker-compose.yml
  • Using your favourite editor, nanoor vim into your newly made docker-compose.yml file by typing nano docker-compose.yml
  • Copy and past the following into your compose file:
    external: true

    image: mariadb:10
    container_name: vikunja_db
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
      - $DOCKERDIR/vikunja/db:/var/lib/mysql
    restart: unless-stopped
      - vikunja
    image: vikunja/api
    container_name: vikunja_api
      VIKUNJA_DATABASE_HOST: vikunja_db
      - $DOCKERDIR/vikunja/files:/app/vikunja/files
      - mariadb
    restart: unless-stopped
      - vikunja
    image: vikunja/frontend
    container_name: vikunja_front
    restart: unless-stopped
      - vikunja

    image: nginx
    container_name: vikunja_proxy
      - 80:80
      - $DOCKERDIR/vikunja/nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - api
      - frontend
    restart: unless-stopped
      - vikunja
the whole stack in docker-compose
if you're using vim, type i to edit, copy the above, press Esc, then :wq! and Enter to save and exit the editor

Creating the .env file

You'll notice a number of variables above preceded by $. This means the docker-compose.yml will look for these variables in an associated .env file. Let's create that now:

  • In the same directory as your docker-compose.yml file, create your .env file:
touch .env
if you run ls you will NOT be able to see the .env file as it is a hidden file. You may be able to type in ls -al which will bring it up, but similarly it may not. Don't worry if this is the case
  • We now need to edit it to add in our variables which will be passed to the compose file. Once more, vim or nano into your file with vim .env and copy in the following:
MYSQLROOTPWD=a super strong password
VIKDBUSR=vikunja #change if you like
VIKDBPWD=#a strong password
VIKDBNAME=vikunja #change if you like
DOCKERDIR=/volume1/docker #change to your docker directory

change the variables to the right of the = sign as needed
if you've been following along but doing all of this in Windows via SMB, you should have a file directory that looks a little like this:

Setting our nginx.conf file

The final thing before spinning up our containers is to make sure that our nginx.conf is populated so that we can access our container once it's running.

  • Navigate to your /vikunja/nginx folder and vim nginx.conf
  • Copy and paste the following, which we shouldn't have to change at all:
server {
    listen 80;

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

    location ~* ^/(api|dav|\.well-known)/ {
        proxy_pass http://api:3456;
        client_max_body_size 20M;
paste this into your nginx.conf file

Creating and accessing the container

  • Type cd .. to go up a directory to your vikunja folder, and type the following:
sudo docker-compose -p "vikunja" up -d
'Sudo' is required if your user doesn't have docker privileges. -p names the stack whatever you put into the " " marks
  • You should see something like this:
note that because I have another instance of mariadb already running in another container, there was no need for my system to pull the image, though it did create another container of it here

You should now be able to access this at your nginx port, by typing in http://localhost:IP. For me, my NAS is located at, and the nginx published port was 80, so I could also type in and I would get the following login page:

  • Hit the register button to create a new user, fill in the relevant fields, and you will be able to create tasks, reminders, lists and namespaces in no time!

Related Article

Portainer - Easy Container Management for Docker
A step-by-step docker walkthrough to installing and configuring Portainer, your one-stop container-management resource


PTS fell down the selfhosted rabbit hole after buying his first NAS in October 2020, only intending to use it as a Plex server. Find him on the Synology discord channel

Have some feedback or something to add? Comments are welcome!

Please note comments should be respectful, and may be moderated