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.
By Simon Vasconcelos Lee
Published on 19 November 202613 minute read
vikunja/vikunja:2.8.0 image and PostgreSQL, with port 3456 published on 127.0.0.1 behind an HTTPS reverse proxy.service.publicurl, the HTTPS address of your instance, and service.secret, which signs sessions.files folder together, before every update; database migrations run on their own at startup.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.
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.
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:
| Database | What the documentation says | Version tested in CI |
|---|---|---|
| SQLite | Bundled with the binary and the Docker image, nothing to install. Beyond a handful of users, the documentation recommends MySQL or PostgreSQL. | The bundled one |
| PostgreSQL | The database of the documentation’s Docker examples. Since 2.8.0, search ignores accents with the unaccent extension. | 18 |
| MySQL, MariaDB | MySQL 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.
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:
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:
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:
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.
127.0.0.1: this is where we depart from the documentation’s examples, which publish the port on every address. Its hardening checklist asks that only the reverse proxy can reach Vikunja: the interface then opens through it, over HTTPS.VIKUNJA_SERVICE_PUBLICURL: the HTTPS address your users open, with the trailing slash. Vikunja uses it to build its links, in emails for example, and as the allowed CORS origin, which is on by default: this setting is therefore required. A wrong address, a missing port for example, shows up as an “unauthorized” error when you create the first account.VIKUNJA_SERVICE_SECRET signs session tokens. Left empty, it is drawn at random at every start, and every restart then logs all users out.2.8.0 tag pins the version, as the documentation recommends, so updates happen when you decide. latest follows the latest stable release, and unstable the development builds.files and db folders keep attachments and PostgreSQL data on the server: they are what you back up.scratch. docker exec into a shell does not work, and the PUID and PGID variables of other images have no effect on it. Errors are read with docker compose logs vikunja.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:
volumes:
- ./files:/app/vikunja/files
- ./db:/db
Since version 2.4.0, Vikunja publishes a package repository for Debian and Ubuntu, for amd64, arm64 and armhf, signed with its GPG key:
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.
service:
secret: "the value written by the package"
publicurl: "https://tasks.example.com/"
interface: "127.0.0.1:3456"
ipextractionmethod: "xff"
sudo systemctl start vikunja
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:
VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
Further accounts are managed from the command line. Since the image has no shell, you call its binary directly:
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
user create asks for the password when the -p flag does not give it, which keeps it out of your terminal history.user reset-password emails a reset link, or replaces the password directly with --direct, using the ID that user list shows.user change-status disables or re-enables an account, with --disable or --enable.doctor checks the configuration, the public URL, the secret, the database, write access to files and, when enabled, the SMTP server.VIKUNJA_SERVICE_TIMEZONE defaults to GMT and expects a tz database name, Europe/Paris for example, never a UTC offset. It serves as the default time zone of users, and so sets the time of their reminders.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.
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:
tasks.example.com {
reverse_proxy 127.0.0.1:3456
}
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:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
Then this server block, on port 80 so Certbot can set up HTTPS:
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;
}
}
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.
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:
| Key | Default | Turn it off to |
|---|---|---|
service.enablelinksharing | true | Prevent sharing projects through public links |
service.enablecaldav | true | Remove the CalDAV endpoint, which accepts HTTP basic auth |
webhooks.enabled | true | Stop Vikunja from sending requests to addresses users choose |
service.enabletaskattachments | true | Prevent file uploads to tasks |
service.enableuserdeletion | true | Prevent users from deleting their own accounts |
plugins.enabled | false | Already off: keep third-party code out of Vikunja |
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.
docker compose exec db psql -U vikunja -d vikunja -c 'CREATE EXTENSION IF NOT EXISTS unaccent;'
docker compose restart vikunja
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 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.
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:
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
VIKUNJA_MAILER_FORCESSL: "true", which enforces TLS from the start of the connection and refuses unencrypted connections.plain by default, login or cram-md5 with VIKUNJA_MAILER_AUTHTYPE, depending on your server.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.
docker compose exec vikunja /app/vikunja/vikunja testmail you@example.com
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.
| Item | What it holds | How to copy it |
|---|---|---|
| The PostgreSQL database | Accounts, projects, tasks, comments and settings | pg_dump, without stopping Vikunja |
files | Attachments, avatars and project backgrounds | A copy of the folder |
With SQLite, db/vikunja.db | The whole database | A copy of the file, with Vikunja stopped |
docker-compose.yml | The secret, the public URL and the passwords | Kept apart, like a secret |
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.
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:
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
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.
files folder.docker-compose.yml, for example from 2.8.0 to the next version.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.
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.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits your business |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Reading your instance’s logs |
| Vikunja | Proactive monitoring: errors, slowdowns and disk space spotted, fix recommended | Its installation, updates and settings, which you apply, yourself or through your AI assistant |
| Accounts and projects | The server that carries them, monitored and backed up | Your team’s accounts, registration, shares and permissions |
| A server that reaches your SMTP server on port 587 or 465 | Your sending service and its credentials | |
| Backups | Every night, encrypted and kept off the machine; restores included | Your exports of the database and the files folder, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Simafri
Let's talk about your project
Tell us what you need in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.