Self-host Vikunja on a managed VPS: your tasks and projects on your own server

When you self-host Vikunja on a managed VPS, you keep your team’s tasks and projects on a machine of your own, which our teams keep up to date and monitor day and night. Vikunja is free software under the AGPL-3.0 license. This guide follows its official documentation: choosing a database, installing with Docker Compose, the public URL and the secret, accounts, HTTPS, Vikunja’s own settings, email, backups and updates.

Simon Vasconcelos Lee By Published on 19 November 202613 minute read

All guides

In short

  1. The AGPL-3.0 license lets you use Vikunja at work with no license to buy; if you modify it, your remote users must be able to get the source code of your version.
  2. Install it with Docker Compose: the vikunja/vikunja:2.8.0 image and PostgreSQL, with port 3456 published on 127.0.0.1 behind an HTTPS reverse proxy.
  3. Two settings belong in place from the start: service.publicurl, the HTTPS address of your instance, and service.secret, which signs sessions.
  4. Vikunja has no default account: create yours, then close registration and add the next accounts from the command line.
  5. Back up the database and the files folder together, before every update; database migrations run on their own at startup.

What Vikunja does

Vikunja is an open source, self-hosted task and project manager, which its repository describes as “the task manager you actually own”. The API, written in Go, and the web interface ship in a single binary, or a single Docker image: there is only one thing to install.

What the AGPL-3.0 license allows

Vikunja is published under the GNU AGPL version 3 or later, except for the desktop/ folder of its repository, the desktop app, which is under the GPL version 3 or later. You can use it, at work included, for your team as well as for your clients, with no license to buy. What remains is the cost of the server that runs it.

Section 13 adds a condition specific to the AGPL: if you modify the program, your version must prominently offer everyone who interacts with it remotely, over a network, the opportunity to get its source code, at no charge. If you distribute copies, the license’s source-sharing obligations apply as well. Running Vikunja without modifying it does not trigger this section.

This guide installs that open source edition, which the documentation describes as fully functional on its own. Vikunja Pro, an optional license, adds an admin panel, time tracking and audit logs for organizations.

Resources and database

Vikunja runs on SQLite, PostgreSQL, MySQL or MariaDB. The documentation gives no memory or CPU figures; it guides the choice of database by the number of users:

DatabaseWhat the documentation saysVersion tested in CI
SQLiteBundled with the binary and the Docker image, nothing to install. Beyond a handful of users, the documentation recommends MySQL or PostgreSQL.The bundled one
PostgreSQLThe database of the documentation’s Docker examples. Since 2.8.0, search ignores accents with the unaccent extension.18
MySQL, MariaDBMySQL 8.0 at least, as 5.7 is not supported. For non-Latin characters, the database must use utf8mb4.MySQL 8, MariaDB 12

The documentation recommends a database release that is still maintained. Redis can serve as a cache, but it notes you will probably not need it while the instance has only a handful of users: this guide does without it.

Disk usage mostly follows your attachments and project backgrounds, stored in the files folder, at 20 MB per file at most by default. On a managed VPS, tell us about your team, its number of users and how much it relies on attachments, and we will recommend the right size.

Installing with Docker Compose

The documentation installs Vikunja and PostgreSQL with Docker Compose. On a server with Docker installed, create a folder and first generate the instance secret, a random value you will paste into the file:

Terminal
openssl rand -hex 32

Then place this docker-compose.yml in the folder, taken from the documentation’s PostgreSQL example. Replace tasks.example.com with your domain name, paste-your-secret-here with the value you generated, and changeme with a strong password, the same in both places:

docker-compose.yml
services:
  vikunja:
    image: vikunja/vikunja:2.8.0
    environment:
      VIKUNJA_SERVICE_PUBLICURL: https://tasks.example.com/
      VIKUNJA_SERVICE_SECRET: paste-your-secret-here
      VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: changeme
      VIKUNJA_DATABASE_DATABASE: vikunja
    ports:
      - "127.0.0.1:3456:3456"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: changeme
    volumes:
      - ./db:/var/lib/postgresql
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
      interval: 30s
      start_period: 15s
      start_interval: 5s

Vikunja runs as user 1000: create the files folder and hand it over before the first start, as the documentation asks, then start the services:

Terminal, in the docker-compose.yml folder
mkdir files
sudo chown 1000 files
docker compose up -d
docker compose logs vikunja

On first start, Vikunja creates its database and runs all its migrations. The line http server started on [::]:3456 in the logs means it is ready, and curl http://127.0.0.1:3456/api/v1/info, run on the server, returns its version and public settings.

With SQLite

For a handful of users, the documentation offers SQLite: remove the db service, the depends_on block and the VIKUNJA_DATABASE_* variables, and mount a folder on /db, where the image already stores vikunja.db. Create it and hand it to user 1000, like files:

docker-compose.yml, vikunja service
    volumes:
      - ./files:/app/vikunja/files
      - ./db:/db

Without Docker: the Debian package

Since version 2.4.0, Vikunja publishes a package repository for Debian and Ubuntu, for amd64, arm64 and armhf, signed with its GPG key:

Terminal
curl -fsSL https://dl.vikunja.io/repos/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/vikunja.gpg
echo "deb [signed-by=/usr/share/keyrings/vikunja.gpg] https://dl.vikunja.io/repos/apt stable main" | sudo tee /etc/apt/sources.list.d/vikunja.list
sudo apt update && sudo apt install vikunja

The package installs Vikunja in /opt/vikunja, with SQLite by default, and a systemd service that is enabled but not started yet. It also writes a random secret into a service section of /etc/vikunja/config.yml: complete that same section, then start the service.

/etc/vikunja/config.yml
service:
  secret: "the value written by the package"
  publicurl: "https://tasks.example.com/"
  interface: "127.0.0.1:3456"
  ipextractionmethod: "xff"
Terminal
sudo systemctl start vikunja

The first account and registration

Vikunja creates no account by default. Once HTTPS is in place, open https://tasks.example.com/ and sign up: that is your first account. Registration is open by default, to anyone who reaches the address; once your team’s accounts exist, the documentation suggests closing it. Add this line to the variables of the vikunja service, then run docker compose up -d again:

docker-compose.yml, under environment
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"

Further accounts are managed from the command line. Since the image has no shell, you call its binary directly:

Terminal, in the docker-compose.yml folder
docker compose exec vikunja /app/vikunja/vikunja user create -u marie -e marie@example.com
docker compose exec vikunja /app/vikunja/vikunja user list
docker compose exec vikunja /app/vikunja/vikunja user reset-password 2 --direct

Account security

HTTPS: the reverse proxy

Vikunja serves plain HTTP. The documentation terminates HTTPS at a reverse proxy, so that passwords and tokens never travel unencrypted: it listens on ports 80 and 443, obtains the certificate and forwards to Vikunja on 127.0.0.1:3456.

Behind a proxy, Vikunja sees the proxy’s address on every request by default: logs and rate limits then target everyone at once. The VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff setting, already in the Compose file, makes it read the X-Forwarded-For header. It only trusts that header on requests coming from loopback and private network addresses, Docker’s network included: with the port published on 127.0.0.1, only your proxy gets there.

With Caddy

Here is the documentation’s Caddyfile. Caddy obtains a Let’s Encrypt certificate for the given name on its own, passes on the X-Forwarded-For header and lets WebSocket connections through:

Caddyfile
tasks.example.com {
    reverse_proxy 127.0.0.1:3456
}

With Nginx

The documentation’s block comes down to a proxy_pass line and an upload size. This block builds on it with two additions: the X-Forwarded-For header, which Vikunja reads, and the WebSocket headers. The version 2.8.0 interface opens a WebSocket connection on /api/v2/ws for its live updates; when it fails, its notifications fall back to polling every 10 seconds. First add this map block to the http section of /etc/nginx/nginx.conf:

nginx.conf, inside http
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Then this server block, on port 80 so Certbot can set up HTTPS:

Nginx block
server {
    listen 80;
    listen [::]:80;
    server_name tasks.example.com;

    location / {
        proxy_pass http://127.0.0.1:3456;
        client_max_body_size 20M;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}
Terminal
sudo nginx -t
sudo certbot --nginx

client_max_body_size 20M matches the maximum file size in Vikunja, 20 MB by default. If you raise it with VIKUNJA_FILES_MAXSIZE, the documentation asks you to raise this line as well.

Settings specific to Vikunja

Almost every key of the config.yml file has its environment variable: service.enablecaldav becomes VIKUNJA_SERVICE_ENABLECALDAV. When an option is set in both places, the variable wins. The documentation’s hardening checklist reviews the features to turn off if you have no use for them:

KeyDefaultTurn it off to
service.enablelinksharingtruePrevent sharing projects through public links
service.enablecaldavtrueRemove the CalDAV endpoint, which accepts HTTP basic auth
webhooks.enabledtrueStop Vikunja from sending requests to addresses users choose
service.enabletaskattachmentstruePrevent file uploads to tasks
service.enableuserdeletiontruePrevent users from deleting their own accounts
plugins.enabledfalseAlready off: keep third-party code out of Vikunja

Accent-insensitive search on PostgreSQL

Since 2.8.0, search ignores accents on PostgreSQL when the unaccent extension is active: “cafe” also finds “café”. The official PostgreSQL image ships it; enable it in the Vikunja database, then restart Vikunja. The log then shows unaccent extension detected, search is accent-insensitive.

Terminal, in the docker-compose.yml folder
docker compose exec db psql -U vikunja -d vikunja -c 'CREATE EXTENSION IF NOT EXISTS unaccent;'
docker compose restart vikunja

Importing your tasks

Each user imports tasks from the “Import” tab of their settings, and can also export all their data there as a zip archive. The file imports, Vikunja archive, CSV, TickTick and WeKan, along with the import from a Planka instance, are always available. Todoist, Trello and Microsoft To Do go through OAuth: they are off by default and are enabled in the migration section of the configuration, with the credentials of the app created at each service. The OAuth redirect happens in the browser: the instance does not need to be reachable by those services, but service.publicurl must be correct.

CalDAV

CalDAV syncs tasks with your apps, using the connection details in the CalDAV tab of the settings. The documentation presents this integration as an alpha that works well with some clients: try yours before making it the whole team’s tool. On iPhone and iPad, each project becomes a list in the Reminders app. An account with two-factor authentication connects with a dedicated CalDAV token.

Email: reminders, confirmations and passwords

Vikunja sends emails for task reminders, new account confirmation and password resets. Sending is off by default: accounts are then active as soon as they are created, and password reset by email is not possible. Once sending is on, each new local account confirms its address before use.

From a Simafri VPS, set up an authenticated SMTP server, on port 587 or 465: the one from your sending service or your email provider. Add these variables to the vikunja service:

docker-compose.yml, under environment
      VIKUNJA_MAILER_ENABLED: "true"
      VIKUNJA_MAILER_HOST: smtp.example.com
      VIKUNJA_MAILER_PORT: 587
      VIKUNJA_MAILER_USERNAME: tasks@example.com
      VIKUNJA_MAILER_PASSWORD: your-smtp-password
      VIKUNJA_MAILER_FROMEMAIL: tasks@example.com

Run docker compose up -d again, then send a test message. The command checks the connection with an SMTP NOOP command, which some minimal relays do not support: prefer a full SMTP server.

Terminal
docker compose exec vikunja /app/vikunja/vikunja testmail you@example.com

Backups

The documentation counts two parts to back up, together: the database and the attachments folder. Since 2.8.0, deleted tasks and projects first spend 30 days in the trash; once that time has passed or the trash is emptied, only a backup brings them back.

ItemWhat it holdsHow to copy it
The PostgreSQL databaseAccounts, projects, tasks, comments and settingspg_dump, without stopping Vikunja
filesAttachments, avatars and project backgroundsA copy of the folder
With SQLite, db/vikunja.dbThe whole databaseA copy of the file, with Vikunja stopped
docker-compose.ymlThe secret, the public URL and the passwordsKept apart, like a secret
Terminal, in the docker-compose.yml folder
docker compose exec -T db pg_dump -U vikunja vikunja > vikunja-$(date +%F).sql
tar -czf vikunja-files-$(date +%F).tar.gz files

The documentation asks for encrypted backups kept off the server, and restores tested regularly: on a separate instance, log in and open a task with an attachment. Left on the server’s disk, these archives are also part of its nightly backups.

The vikunja dump command gathers the configuration, the database and all files into a zip archive, and vikunja restore loads it back. The archive holds the configuration file and every VIKUNJA_* variable in plain text: encrypt it and protect it like the database itself.

Restoring

On a fresh installation, with the same docker-compose.yml, load the export into the still empty database before Vikunja’s first start, then put the files folder back in place:

Terminal
docker compose up -d db
docker compose exec -T db psql -U vikunja vikunja < vikunja-2026-11-19.sql
tar -xzf vikunja-files-2026-11-19.tar.gz
docker compose up -d

Updates

Vikunja runs its database migrations on its own when a new version starts. The documentation therefore asks for a backup before every update, so you can return to the previous state, and for a read of the release notes, which flag any manual steps.

  1. Read the notes for the new version.
  2. Export the database and copy the files folder.
  3. Change the image tag in docker-compose.yml, for example from 2.8.0 to the next version.
  4. Pull the new image and restart the service.
Terminal
docker compose pull
docker compose up -d

With the Debian package, sudo apt update && sudo apt upgrade replaces the binary and restarts the service. Moving from a stable release to the unstable builds works, but the documentation advises against going back: wait for the next stable release instead.

Security fixes are published as GitHub security advisories and announced in the release notes. Version 2.8.0 of 5 November 2026 fixes nineteen of them, and its announcement asks you to update as soon as you can. To be notified, watch the releases of the GitHub repository or follow the changelog RSS feed.

Who does what on a managed VPS

Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Vikunja remains your software, with its settings, your projects and your tasks.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits your business
MonitoringServer monitored 24/7, with intervention without waiting for your callReading your instance’s logs
VikunjaProactive monitoring: errors, slowdowns and disk space spotted, fix recommendedIts installation, updates and settings, which you apply, yourself or through your AI assistant
Accounts and projectsThe server that carries them, monitored and backed upYour team’s accounts, registration, shares and permissions
EmailA server that reaches your SMTP server on port 587 or 465Your sending service and its credentials
BackupsEvery night, encrypted and kept off the machine; restores includedYour exports of the database and the files folder, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe timing of the switch

If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.

Vikunja, on a server run for you

With a Simafri Managed VPS, our teams keep your Vikunja instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.

Explore Managed VPS

Frequently asked questions

Is Vikunja free for a business?

Yes. Vikunja is under the AGPL-3.0 license: you can use it at work with no license to buy. If you modify it, your remote users must be able to get the source code of your version. What remains is the cost of the server that runs it.

Which database should I choose for Vikunja?

SQLite, bundled with the image, is enough for a handful of users. Beyond that, the documentation recommends PostgreSQL or MySQL. PostgreSQL is the database of its Docker examples, and since 2.8.0 its search ignores accents with the unaccent extension.

How do I install Vikunja with Docker Compose?

Create a docker-compose.yml with the vikunja/vikunja:2.8.0 and postgres:18 images, port 3456 published on 127.0.0.1, a files folder handed to user 1000, the public URL and the secret, then run docker compose up -d. Next, put an HTTPS reverse proxy in front of port 3456.

What are service.publicurl and service.secret for?

service.publicurl is the HTTPS address of your instance: Vikunja builds its links and its CORS origin from it, hence an unauthorized error when it is wrong. service.secret signs sessions; left empty, it changes at every start and logs all users out.

How do I create the first Vikunja account?

Vikunja has no default account: sign up on your instance. Then close registration by setting VIKUNJA_SERVICE_ENABLEREGISTRATION to false, and create the next accounts with the vikunja user create command, run inside the container.

How do I set up email in Vikunja?

Turn sending on with VIKUNJA_MAILER_ENABLED, then give the host, port 587 or 465, the username, the password and the sender address of your SMTP server. Without email, accounts are active as soon as they are created and passwords are reset from the command line.

How do I back up Vikunja?

Back up the database, with pg_dump for PostgreSQL, and the files folder of attachments together. Keep the copies encrypted and off the server, take one before every update and test restoring them regularly.

Does a managed VPS cover Vikunja?

A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.

Contact us