Skip to Content
Installation

Install Vikunja

Keep track of the company's tasks on your own server, with a list, kanban and calendar, and the right folder permissions from the start.

Last reviewed:

What Vikunja is

A program for keeping track of tasks. You set up projects, fill them with tasks, set deadlines and assign owners, and view everything as a list, a kanban board, a table or a timeline (Gantt). The same tasks, four ways to look at them.

It sounds like any to-do app, and the difference only shows once you are five people. A task has an owner. It has a date. It has a comment thread where the discussion about that specific matter lives, instead of being scattered in a group chat where nobody can find their way back. When someone asks who is doing what, the answer is on one screen.

What makes Vikunja useful in a company is that it is your own. The tasks sit on a machine you control, and they do not disappear because a free service changes its terms in February.

This is a server program

Vikunja is not an installation file you double-click on. It needs a machine to run on and a database next to it, and the easiest way to get both is Docker. If you do not have Docker, start with Install Docker.

Vikunja also has a cloud service that they run themselves for a fee, plus apps for phone and computer that can point either to their server or to yours. What the cloud service costs is on vikunja.io.

Windows and Linux Mint

The same files on both. Create a folder called vikunja in the home folder, that is in C:\Users\ert-namn on Windows and in /home/ert-namn on Linux Mint, and create two empty subfolders in it called files and db. It matters that you create them yourself, and the reason why is at the bottom. Then put a text file called compose.yaml in the vikunja folder:

services:
  vikunja:
    image: vikunja/vikunja
    environment:
      VIKUNJA_SERVICE_PUBLICURL: http://localhost:3456
      VIKUNJA_SERVICE_SECRET: BYT_UT_MIG_1
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: BYT_UT_MIG_2
      VIKUNJA_DATABASE_DATABASE: vikunja
    ports:
      - "3456:3456"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: BYT_UT_MIG_2
    volumes:
      - ./db:/var/lib/postgresql
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
      interval: 2s
      start_period: 30s

Replace the two placeholders with real random strings and save them where the company saves passwords. The two lines called BYT_UT_MIG_2 must contain exactly the same string, since it is the database password in both places. If you write different ones, Vikunja starts but cannot get into the database.

Open the terminal and go into the folder. On Windows it is PowerShell:

cd $HOME\vikunja

On Linux Mint the program is called Terminal:

cd ~/vikunja

Then start:

docker compose up -d

If you are in the wrong folder, Docker answers that no compose.yaml was found, and then it is the cd line that is missing. The health check on the database makes Vikunja wait for it instead of crashing and restarting a couple of times. Open http://localhost:3456 and register the first account. We ran exactly this file, and Vikunja started right away with the latest version.

That address always points to your own computer, that is what localhost means. If you pass it on, the recipient lands on their own machine instead of on your projects. For learning the program it is good enough. If the company is going to share the tasks for real, Vikunja must run on a machine that is switched on, reached at that machine's address, for example http://192.168.1.42:3456, and VIKUNJA_SERVICE_PUBLICURL changed to the same address.

Three things to do first

  1. Turn off registration once everyone in the company has an account. Add the line VIKUNJA_SERVICE_ENABLEREGISTRATION: "false" under environment and run docker compose up -d again. Otherwise anyone who reaches the address can create an account for themselves.
  2. Set up one project per part of the company instead of one single large one. Marketing, finance, production. Tasks that end up in a shared pile never get done, because no one feels responsible for the pile.
  3. Assign an owner and a date to every task as soon as you create it. A task without an owner and without a date is a note, not a commitment, and the difference shows when things get busy.

The most common trap

Letting Docker create the folders for you. If you start without creating files and db first, Docker on Linux Mint creates them for root, while Vikunja inside the container runs as a regular user (uid 1000). The result is that the page loads but the log fills with permission denied, and attachments cannot be uploaded. We ran straight into this when we tested. On Windows with Docker Desktop, the same ownership problem normally does not occur.

The solution is simple and should be done before the first start: create the two folders yourself. If it has already happened on Linux Mint, you fix it with sudo chown -R 1000 files (only files needs the ownership change, the database container handles db itself) and restart with docker compose up -d.

If you see a warning that service.jwtsecret is going away, it means an older setting has been renamed. Use VIKUNJA_SERVICE_SECRET, just like in the file above, and you avoid it.

Back to the guides

Cart