Show Menu

Backend #

NOTE: If you intend to run Vikunja with mysql and/or to use non-latin characters make sure your db is utf-8 compatible.

Table of contents

Install from binary #

Download a copy of Vikunja from the download page for your architecture.

wget <download-url>

Verify the GPG signature #

Starting with version 0.7, all releases are signed using pgp. Releases from main will always be signed.

To validate the downloaded zip file use the signiture file .asc and the key FF054DACD908493A:

gpg --keyserver keyserver.ubuntu.com --recv FF054DACD908493A
gpg --verify vikunja-0.7-linux-amd64-full.zip.asc vikunja-0.7-linux-amd64-full.zip

Set it up #

Once you’ve verified the signature, you need to unzip it and make it executable, you’ll also need to create a symlink to it so you can execute Vikunja by typing vikunja on your system. We’ll install vikunja to /opt/vikunja, change the path where needed if you want to install it elsewhere.

mkdir -p /opt/vikunja
unzip <vikunja-zip-file> -d /opt/vikunja
chmod +x /opt/vikunja
ln -s /opt/vikunja/vikunja /usr/bin/vikunja

Systemd service #

Save the following service file to /etc/systemd/system/vikunja.service and adapt it to your needs:

[Unit]
Description=Vikunja
After=syslog.target
After=network.target
# Depending on how you configured Vikunja, you may want to uncomment these:
#Requires=mysql.service
#Requires=mariadb.service
#Requires=postgresql.service
#Requires=redis.service

[Service]
RestartSec=2s
Type=simple
WorkingDirectory=/opt/vikunja
ExecStart=/usr/bin/vikunja
Restart=always
# If you want to bind Vikunja to a port below 1024 uncomment
# the two values below
###
#CapabilityBoundingSet=CAP_NET_BIND_SERVICE
#AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

If you’ve installed Vikunja to a directory other than /opt/vikunja, you need to adapt WorkingDirectory accordingly.

After you made all necessary modifications, it’s time to start the service:

sudo systemctl enable vikunja
sudo systemctl start vikunja

Build from source #

To build vikunja from source, see building from source.

Updating #

Simply replace the binary and templates with the new version, then restart Vikunja. It will automatically run all necessary database migrations. Make sure to take a look at the changelog for the new version to not miss any manual steps the update may involve!

Docker #

(Note: this assumes some familiarity with docker)

Usage with docker is pretty straightforward:

docker run -p 3456:3456 vikunja/api

to run with a standard configuration. This will expose vikunja on port 3456 on the host running the container.

You can mount a local configuration like so:

docker run -p 3456:3456 -v /path/to/config/on/host.yml:/app/vikunja/config.yml:ro vikunja/api

Though it is recommended to use environment variables or .env files to configure Vikunja in docker. See config for a list of available configuration options.

Files volume #

By default the container stores all files uploaded and used through vikunja inside of /app/vikunja/files which is created as a docker volume. You should mount the volume somewhere to the host to permanently store the files and don’t loose them if the container restarts.

Setting user and group id of the user running vikunja #

You can set the user and group id of the user running vikunja with the PUID and PGID environment variables. This follows the pattern used by the linuxserver.io docker images.

This is useful to solve general permission problems when host-mounting volumes such as the volume used for task attachments.

Docker compose #

To run the backend with a mariadb database you can use this example docker-compose file:

version: '2'
services:
  api:
    image: vikunja/api:latest
    environment:
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: secret
      VIKUNJA_DATABASE_TYPE: mysql
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_SERVICE_JWTSECRET: <generated secret>
      VIKUNJA_SERVICE_FRONTENDURL: https://<your public frontend url with slash>/
    volumes:
      - ./files:/app/vikunja/files
  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

See full docker example for more variations of this config.

Debian packages #

Since version 0.7 Vikunja is also released as debian packages.

To install these, grab a copy from the download page and run

dpkg -i vikunja.deb

This will install the backend to /opt/vikunja. To configure it, use the config file in /etc/vikunja/config.yml.

FreeBSD / FreeNAS #

Unfortunately, we currently can’t provide pre-built binaries for FreeBSD. As a workaround, it is possible to compile vikunja for FreeBSD directly on a FreeBSD machine, a guide is available below:

Thanks to HungrySkeleton who originally created this guide in the forum.

Jail Setup #

  1. Create jail named vikunja
  2. Set jail properties to ‘auto start’
  3. Mount storage (/mnt to jailData/vikunja)
  4. Start jail & SSH into it

Installing packages # 

pkg update && pkg upgrade -y
pkg install nano git go gmake
go install github.com/magefile/mage

Clone vikunja repo # 

mkdir /mnt/GO/code.vikunja.io
cd /mnt/GO/code.vikunja.io
git clone https://code.vikunja.io/api
cd /mnt/GO/code.vikunja.io/api

Compile binaries # 

go install
mage build

Create folder to install backend server into # 

mkdir /mnt/backend
cp /mnt/GO/code.vikunja.io/api/vikunja /mnt/backend/vikunja
cd /mnt/backend
chmod +x /mnt/backend/vikunja

Set vikunja to boot on startup # 

nano /etc/rc.d/vikunja

Then paste into the file:

#!/bin/sh

. /etc/rc.subr

name=vikunja
rcvar=vikunja_enable

command="/mnt/backend/${name}"

load_rc_config $name
run_rc_command "$1"

Save and exit. Then execute:

chmod +x /etc/rc.d/vikunja
nano /etc/rc.conf

Then add line to bottom of file:

vikunja_enable="YES"

Test vikunja now works with

service vikunja start

The API is now available through IP:

192.168.1.XXX:3456

Configuration #

See available configuration options.

Default Password #

After successfully installing Vikunja, there is no default user or password. You only need to register a new account and set all the details when creating it.