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.

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.

Related Posts