Why Self-Hosting Your Task Manager Makes Sense
Most task management apps ask you to trust a third-party server with your to-do lists, project timelines, and deadlines. That’s fine until the company raises prices, gets acquired, or quietly changes its data retention policy. Vikunja is an open-source task management server you host yourself, giving you full ownership of your data and a clean, capable interface that competes with paid tools without the subscription.
Vikunja supports lists, kanban boards, Gantt charts, and recurring tasks out of the box. It has a REST API, mobile apps, and integrations with CalDAV, so it fits into existing workflows without much friction. If you already run a home server or a small VPS, adding Vikunja takes less than an hour.
This guide walks through setting up Vikunja using Docker Compose on a Linux server.
What You Need Before You Start
You need a Linux server – a VPS, a home server, or even a Raspberry Pi 4 with at least 1GB of RAM. Docker and Docker Compose must be installed. If you plan to access Vikunja from outside your home network, you also need a domain name pointing to your server’s IP address and a reverse proxy like Nginx or Caddy to handle HTTPS. Without HTTPS, the browser app will throw warnings and some features may behave unexpectedly.
Vikunja stores data in a database. The Docker Compose setup covered here uses MariaDB, which is the most straightforward option for persistent storage. You can use PostgreSQL or SQLite if you prefer, but MariaDB is well-tested with Vikunja and handles multi-user setups cleanly. Make sure port 3456 (Vikunja’s default) is not already in use on your server before proceeding.
You will also want to decide early whether you need email functionality. Vikunja can send password reset emails and task reminders, but that requires configuring an SMTP server. For a personal single-user setup, you can skip email entirely and still get full use of the app. For a team or family setup, email is worth configuring from the start rather than retrofitting it later.
Setting Up Vikunja with Docker Compose
Create a directory for your Vikunja installation and place a docker-compose.yml file inside it. The compose file defines three services: the database, the Vikunja API backend, and the Vikunja frontend. The frontend is a separate container that serves the web interface and communicates with the API.
A working compose file looks like this. The database service uses the mariadb:10 image with environment variables for the root password, database name, user, and user password. The API service uses vikunja/api and depends on the database container. It needs two key environment variables: VIKUNJA_DATABASE_HOST set to the database service name, and VIKUNJA_SERVICE_JWTSECRET set to a long random string you generate yourself – use openssl rand -hex 32 to create one. The frontend service uses vikunja/frontend and needs VIKUNJA_API_URL pointing to your API address, which is typically your domain followed by /api/v1. Map port 80 on the frontend container to whatever port you want to expose on the host, or skip port mapping entirely if a reverse proxy handles routing.
Once the file is saved, run docker compose up -d from that directory. Docker pulls the images and starts all three containers. Check that they are running with docker compose ps. If the API container exits immediately, check its logs with docker compose logs api – the most common cause is a missing or misformatted environment variable. Give the database container about 20 seconds to initialize fully before the API connects, which the depends_on directive handles automatically in most cases.
Configuring Nginx and Accessing the App
If you are using Nginx as a reverse proxy, create a server block that forwards requests to the Vikunja frontend container and routes /api requests to the API container separately. The frontend and API run on different ports internally, so your Nginx config needs two proxy_pass directives split by location. A typical setup proxies /api/v1 and /api/swagger to the API container on port 3456, and everything else to the frontend container on port 80. Enable HTTPS using a Let’s Encrypt certificate via Certbot – run certbot –nginx -d yourdomain.com and follow the prompts.
With Nginx configured and reloaded, open your domain in a browser. The Vikunja login screen appears. The first account you create automatically becomes the admin. From the admin panel, you can enable or disable user registration, set storage limits, and manage existing accounts. For a personal setup, turn off open registration immediately after creating your account so strangers cannot sign up.
Vikunja’s interface is straightforward. Projects appear in the left sidebar, and each project supports multiple views – list, kanban, table, and Gantt. Tasks can have due dates, assignees, labels, priorities, attachments, and comments. The Gantt view calculates dependencies automatically when you set start and end dates. For those already running other self-hosted tools, Vikunja fits naturally into a setup that includes something like a self-hosted browser startpage where you can link directly to your Vikunja instance for quick access.
Keeping Vikunja Running Long-Term
Back up the MariaDB database regularly using docker exec to run mysqldump inside the database container, then copy the output file somewhere off the server. Also back up any file attachments, which Vikunja stores in a directory mapped via a Docker volume. Updating Vikunja means pulling new images with docker compose pull and restarting the stack – check the Vikunja changelog before major version upgrades because database migrations occasionally require manual steps that the docs spell out clearly. If you skip versions and migrations stack up, the API will refuse to start and log exactly which migration failed, so the error is never ambiguous.
