Vikunja¶

License: AGPLv3

This guide is tested with Vikunja 2.3.0 on Uberspace 8.0.75. We can't guarantee it to work with newer versions.

Vikunja is an open source, self-hosted to-do and project management app. It ships as a single Go binary with the web frontend embedded, so no extra web server or build step is needed.

Note

For this guide you should be familiar with the basic concepts of:

Prerequisites¶

We store Vikunja's data in a MariaDB database. Look up your MariaDB credentials, you'll need the password for the config file later:

[isabell@moondust ~]$ my_print_defaults client
--user=isabell
--password=MySuperSecretPassword
--default-character-set=utf8mb4

Create a database for Vikunja:

[isabell@moondust ~]$ mariadb --execute "CREATE DATABASE ${USER}_vikunja"

Vikunja can send emails (e.g. for password resets and reminders). Add a mailbox for it:

[isabell@moondust ~]$ uberspace mail address add vikunja

Installation¶

Create a directory, download the latest full build (the -full archive contains the web frontend) and unpack it:

[isabell@moondust ~]$ mkdir ~/vikunja
[isabell@moondust ~]$ cd ~/vikunja
[isabell@moondust vikunja]$ wget "https://dl.vikunja.io/vikunja/v2.3.0/vikunja-v2.3.0-linux-amd64-full.zip"
[isabell@moondust vikunja]$ unzip vikunja-v2.3.0-linux-amd64-full.zip

The archive contains the binary, a checksum file, the sample config and the license. Verify the binary against the shipped checksum:

[isabell@moondust vikunja]$ sha256sum --check vikunja-v2.3.0-linux-amd64.sha256
vikunja-v2.3.0-linux-amd64: OK

Rename the binary to vikunja, make it executable and remove the archive:

[isabell@moondust vikunja]$ mv vikunja-v2.3.0-linux-amd64 vikunja
[isabell@moondust vikunja]$ chmod +x vikunja
[isabell@moondust vikunja]$ rm vikunja-v2.3.0-linux-amd64-full.zip

Configuration¶

Configure Vikunja¶

Create the file ~/vikunja/config.yml and add the following. Replace the placeholders with your own MariaDB password, mailbox password and username. Note that type: mysql is correct for MariaDB:

service:
  publicurl: "https://isabell.uber.space/"
  enableregistration: false
  timezone: "Europe/Berlin"

database:
  type: "mysql"
  host: "localhost"
  user: "isabell"
  password: "MySuperSecretPassword"
  database: "isabell_vikunja"

mailer:
  enabled: true
  host: "moondust.uberspace.de"
  port: 587
  authtype: "plain"
  username: "vikunja@isabell.uber.space"
  password: "MySuperSecretMailPassword"
  fromemail: "vikunja@isabell.uber.space"

Note

A full list of options is documented in the shipped config.yml.sample and in the official documentation.

Initialize the database¶

Run the database migrations to create all tables:

[isabell@moondust vikunja]$ ./vikunja migrate

Since we disabled public registration, create your first user from the command line:

[isabell@moondust vikunja]$ ./vikunja user create --username isabell --email isabell@uber.space

Warning

You'll be prompted for a password. Choose a strong one, this account can administer your whole instance.

Setup Systemd¶

Create a service so Vikunja keeps running in the background and starts automatically:

[isabell@moondust ~]$ uberspace service add vikunja "$HOME/vikunja/vikunja" --workdir "$HOME/vikunja"

Setup Web Backend¶

Note

The default port for Vikunja is 3456.

To make Vikunja reachable from the outside, point your web backend at that port:

[isabell@moondust ~]$ uberspace web backend add / port 3456 --force
OK: Added webbackend '/' to your Asteroid

Vikunja should now be running, and you can find it at https://isabell.uber.space. Log in with the user you created above.

Debugging¶

If something doesn't work as expected, run the built-in health check:

[isabell@moondust vikunja]$ ./vikunja doctor

Check whether your mail setup works by sending a test mail to yourself:

[isabell@moondust vikunja]$ ./vikunja testmail isabell@uber.space

The service writes its output to the journal:

[isabell@moondust ~]$ journalctl --user -u vikunja -n 100

Updates¶

Note

Check the update feed and the release notes regularly.

To update Vikunja, stop the service, download and verify the new binary (same steps as in Installation), replace the old binary and start the service again:

[isabell@moondust ~]$ systemctl --user stop vikunja
[isabell@moondust ~]$ cd ~/vikunja
[isabell@moondust vikunja]$ wget "https://dl.vikunja.io/vikunja/v2.3.0/vikunja-v2.3.0-linux-amd64-full.zip"
[isabell@moondust vikunja]$ unzip -o vikunja-v2.3.0-linux-amd64-full.zip
[isabell@moondust vikunja]$ sha256sum --check vikunja-v2.3.0-linux-amd64.sha256
[isabell@moondust vikunja]$ mv vikunja-v2.3.0-linux-amd64 vikunja
[isabell@moondust vikunja]$ chmod +x vikunja
[isabell@moondust vikunja]$ systemctl --user start vikunja

New versions apply their database migrations automatically on the next start.