Vikunja Upgrade to Major Release 1.x

Vikunja has evolved significantly since the 0.x series. With the release of 1.0.0 and later versions, the way the frontend is distributed has changed: it is now embedded in the RPM package and no longer delivered as a separate set of files. This simplifies deployment but requires some adjustments during migration. In this guide, we’ll walk through a smooth upgrade from Vikunja 0.24 to 1.1.0 on a Linux system.

For users who want mobile access, an early version of the Vikunja app is available on the Play Store: Vikunja Early Access.

Vikunja 2.1.0 has been released.

If you are still following this article for version 1.x, you should upgrade directly to 2.1.0 instead of installing 1.1.0 first. The RPM-based upgrade procedure is documented here:

→ Jump directly to Chapter: Upgrading Vikunja 1.1.0 to 2.1.0 Using RPM

This ensures you deploy the current release with the integrated frontend and latest database schema.

Notes

For readers eager to get started with Vikunja, the detailed installation and setup process is covered in a separate, comprehensive blog article.

That guide walks you through everything step by step ensuring a smooth launch and a solid foundation for your task management journey. You can explore the full installation guide here.

Prepare for the Upgrade

Before starting, back up your current configuration:

cp /etc/vikunja/config.yml /etc/vikunja/config.yml.backup

It’s also recommended to review the release notes for the 1.x series to check for any breaking changes or migration instructions specific to your environment.

Download and Install the New RPM

The new versions include both the API/backend and the frontend in a single RPM package:

wget https://dl.vikunja.io/vikunja/v1.1.0/vikunja-v1.1.0-x86_64.rpm
dnf update vikunja-v1.1.0-x86_64.rpm

This updates the application while keeping your existing data intact.

Handle Configuration Files

RPM updates may create a .rpmsave file for your previous configuration. To keep your settings and migrate safely:

cp /etc/vikunja/config.yml /etc/vikunja/config.yml.v1.1.0
cp /etc/vikunja/config.yml.rpmsave /etc/vikunja/config.yml

This ensures that the new version uses the appropriate configuration while preserving your old settings for reference.

Restart Vikunja

After updating the configuration, restart the service:

systemctl restart vikunja
systemctl status vikunja

You should see logs indicating successful startup and migrations:

Jan 5 21:28:41 vikunja01 systemd[1]: Started Vikunja.
Jan 5 21:28:41 vikunja01 vikunja[291542]: time=2026-01-05T21:28:41.754+01:00 level=INFO msg="Using config file: /etc/vikunja/config.yml"
Jan 5 21:28:41 vikunja01 vikunja[291542]: time=2026-01-05T21:28:41.756+01:00 level=INFO msg="Running migrations…"
Jan 5 21:28:41 vikunja01 vikunja[291542]: time=2026-01-05T21:28:41.803+01:00 level=INFO msg="Ran all migrations successfully."
Jan 5 21:28:41 vikunja01 vikunja[291542]: time=2026-01-05T21:28:41.806+01:00 level=INFO msg="Vikunja version v1.1.0"
Jan 5 21:28:41 vikunja01 vikunja[291542]: time=2026-01-05T21:28:41.808+01:00 level=INFO msg="HTTP server listening on :3456"

Migrations run automatically, so no manual database updates are needed.

Update Nginx Configuration

With the embedded frontend, you no longer need to serve static files manually. Instead, use Nginx to reverse proxy requests to Vikunja’s internal server:

server {
    listen 80;
    server_name tasks.examplecorp.io;
    return 301 https://$server_name$request_uri;
    access_log /var/log/nginx/vikunja_access.log;
    error_log /var/log/nginx/vikunja_error.log;
}

server {
    listen 443 ssl;
    server_name tasks.examplecorp.io;
    index index.html index.htm index.php;
    access_log /var/log/nginx/vikunja_access.log;
    error_log /var/log/nginx/vikunja_error.log;
    ssl_certificate /etc/nginx/conf.d/tasks.examplecorp.io.crt;
    ssl_certificate_key /etc/nginx/conf.d/tasks.examplecorp.io.key;

    location / {
        proxy_pass http://localhost:3456;
        client_max_body_size 20M;
    }
}

This setup ensures secure HTTPS access while keeping the backend and frontend bundled in the same service.

Final Checks

After restarting Nginx:

systemctl restart nginx
systemctl status nginx

Visit your Vikunja instance in a browser (https://tasks.examplecorp.io) to verify that everything works as expected.

Conclusion

Migrating from Vikunja 0.24 to 1.x is straightforward thanks to the embedded frontend in the RPM package. Key steps include backing up configuration, updating the RPM, handling .rpmsave files, and ensuring the reverse proxy is properly configured. Following these steps allows a smooth transition without losing settings or requiring manual frontend deployment.

Upgrading Vikunja 1.1.0 to 2.1.0 using RPM

This guide covers the RPM-based installation of Vikunja.
While Docker is the recommended deployment method, this article focuses explicitly on upgrading a native RPM installation.

Backup Database and Data

# Database backup (compressed)
pg_dump vikunja | gzip > ~/vikunja-db-backup.sql.gz
# Backup configuration and data
tar cjf ~/vikunja-backup.tar.bz2 \
  /etc/vikunja \
  /opt/vikunja

Stop the Service

sudo systemctl stop vikunja

Download the RPM from the Official Source

Download the release directly from the official download server:

wget https://dl.vikunja.io/vikunja/v2.1.0/vikunja-v2.1.0-x86_64.rpm

Install / Upgrade the Package

If Vikunja 1.1.0 is already installed, use:

sudo rpm -Uvh vikunja-v2.1.0-x86_64.rpm

For a fresh install, you would use:

sudo rpm -i vikunja-v2.1.0-x86_64.rpm

Handling the Config After Upgrade

After upgrading via RPM, Vikunja installs a new default config.yml and preserves your old configuration as config.yml.rpmsave. The easiest approach:

  • Use your old config (config.yml.rpmsave) by copying it over the new one:
cd /etc/vikunja
cp config.yml config.yml.v2.0.1
cp config.yml.rpmsave config.yml
  • Then run the migration:
vikunja migrate

For most installations, keeping your old configuration and adding only the new required keys ensures a smooth upgrade from 1.x to 2.1.0 without manually merging hundreds of lines.

Enable and Start the Service

sudo systemctl enable --now vikunja
sudo systemctl status vikunja

Verification

Open your Vikunja URL and verify:

  • Tasks and projects are accessible
  • Attachments are intact
  • Authentication works as expected

The upgrade from 1.1.0 to 2.1.0 is straightforward when backups and migrations are handled properly.

Related Posts