I have had a mixed relationship with task management software over the years. Sometimes it seems to jive and I am excited to add tasks into it, and other times I leave it to slowly decay until I notice the subscription bill and cancel. One piece of software that I keep coming back to is Vikunja, which is completely open-source and can be either self-hosted, or you can use the hosted option and have it all taken care of for you on Vikunja cloud. Here, I will go over a super easy way to setup vikunja on a debian vps, and then use the vja command line tool to manage tasks from the command line. On mobile, you can either use the Vikunja web app, or tasks.org which will sync through Caldav.

Setting up the server

Vikunja with Docker

A $6 droplet (1GB/1vCPU/25GB SSD) from digital ocean has been sufficient to manage the load for the vikunja instance for just me. You can either select the docker app from the marketplace, or use the linux operating system of your choice and then install docker yourself.

Next, there are just two files that are required, a docker-compose.yml and a Caddyfile. These should be in the same directory. For me, I chose to use ~/vikunja to keep these components separate from other processes.

The docker compose file can be found in the Vikunja documentation, however I found that there were a few changes that needed to be made to make it work. Particularly, as the main image is no longer split into frontend and api, there shouldn’t be those components in the depends on section.

Note: You will need to change some arguments in the compose file below, such as changeme and the JWTSECRET.

services:
  vikunja:
    image: vikunja/vikunja
    environment:
      VIKUNJA_SERVICE_PUBLICURL: http://<the public url where vikunja is reachable>
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: changeme
      VIKUNJA_DATABASE_TYPE: mysql
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_SERVICE_JWTSECRET: <a super secure random secret>
    ports:
      - 3456:3456
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
  db:
    image: mariadb:10
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    environment:
      MYSQL_ROOT_PASSWORD: supersecret
      MYSQL_USER: vikunja
      MYSQL_PASSWORD: changeme
      MYSQL_DATABASE: vikunja
    volumes:
      - ./db:/var/lib/mysql
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h localhost -u $$MYSQL_USER --password=$$MYSQL_PASSWORD"]
      interval: 2s
      start_period: 30s
  caddy:
    image: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro

In the Caddyfile, you can use a very simple setup for the reverse proxy. Again, this requires a change from the official documentation since api is now no longer distinct from the frontend. Note that Caddyfile should not have a file extension, and the space between the domain name and { is important.

vikunja.example.com {
    reverse_proxy vikunja:3456
}

DNS and Starting the Server

Before you run docker compose up, I would recommend setting up your DNS records to point to the server, and then allowing some time for those records to propegate. If you are using a DigitalOcean droplet, then you would want to point an A record at the IP address of your server. Make sure that ports 80 and 443 are open (may need to be configured through ufw allow 80 and ufw allow 443).

Once you are ready to startup the server, you may run docker compose up -d. Then, after a minute or so, go to the (sub)domain you have chosen for this instance, and you should see the Vikunja login page. You will be able to register for an account. If there are difficulties to troubleshoot, docker ps to show processes, and then docker logs on the different container will show information about what each container is doing. Particularly important is that the Caddy server is able to successfully obtain a certificate.

Note: After registering an account, I would recommend turning further account creation off unless you plan to support multiple people through your instance. This can be done by placing VIKUNJA_SERVICE_ENABLEREGISTRATION:false as an environment variable in the docker-compose.yml under the vikunja container, then restarting the container. You can confirm that user registration is disabled by returning the login page, and you should not see the option to register an account.

Setting up the Command Line Capabilities

To interact with the Vikunja server, vja just has to be installed and then setup with the user credentials. Installing is simple with pip

python -m pip install --user vja
vja --help

Then, a configuration file can either be placed at $HOME/.vjacli/vja.rc or in a custom directory. The domains just need to be changed to the domain of the newly created server.

[application]
frontend_url=https://subdomain.example.com/
api_url=https://subdomain.example.com/api/v1

After the configuration file is set and saved, running vja ls will prompt for a username and password, and a 2FA code if that has been enabled.

Conclusion

That’s it! You now have the ability to manage tasks either through a web interace or through the command line on your own custom domain.