Vikunja on Ubuntu 24.04 on Azure User Guide

Overview

Vikunja is the popular open source, self-hosted to-do list and project/task management application — lists, kanban boards, Gantt, table and calendar views, reminders, labels, assignees and sharing — a privacy-respecting alternative to hosted task managers, deployable in your own virtual network. The cloudimg image runs the Vikunja server (a single Go binary serving both the REST API and the bundled web app) behind nginx as a reverse proxy, with PostgreSQL as the datastore. The server listens on 127.0.0.1:3456 and is reached through nginx on port 80; the server and the database bind to the loopback interface only.

On the first boot of every deployed VM, a one-shot service generates a fresh session-signing secret unique to that VM, rotates the PostgreSQL password, runs the database migrations, and creates a single administrator account with a per-VM password. Open registration is disabled. The login is written to /root/vikunja-credentials.txt with mode 0600. Backed by 24/7 cloudimg support.

What is included:

• Vikunja 2.3 server binary at /opt/vikunja/vikunja (API + web app in one)
• nginx reverse proxy on :80 in front of the Vikunja server (bound to loopback :3456)
• PostgreSQL datastore, bound to loopback
• Two dedicated Azure data disks, re-provisioned with every VM: the PostgreSQL data tier at /var/lib/postgresql and the Vikunja binary + file attachments at /opt/vikunja
• Per-VM administrator login generated at first boot, in a root-only file; per-VM session secret and database password
• vikunja.service, postgresql.service + nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point; scale up for larger teams. NSG inbound: allow 22/tcp from your management network and 80/tcp (plus 443/tcp once you enable HTTPS) from the networks your users will reach Vikunja on.

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Vikunja by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the two dedicated data disks on the Disks tab, then Review + create → Create.

Step 2 — Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name vikunja \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name vikunja --port 80 --priority 1010

Step 3 — Connect to your VM

ssh azureuser@<vm-public-ip>

First-boot initialisation completes in under a minute; the credentials file is in place by the time SSH is ready.

Step 4 — Confirm the services are running

systemctl is-active vikunja.service postgresql.service nginx.service
curl -fsS http://127.0.0.1/api/v1/info

All three services report active and the open info endpoint returns JSON with a version — proof the full stack (nginx, the Vikunja server and PostgreSQL) is serving. Both data tiers live on their own Azure data disks:

findmnt -no SOURCE,SIZE,FSTYPE,TARGET /var/lib/postgresql
findmnt -no SOURCE,SIZE,FSTYPE,TARGET /opt/vikunja

Service status, the open /api/v1/info health endpoint, and the two dedicated data disks.

Step 5 — Retrieve your administrator login

The administrator password is generated uniquely on the first boot of your VM and written to a root-only file:

sudo cat /root/vikunja-credentials.txt

The file contains the Vikunja URL, the administrator username (admin) and the password, plus the PostgreSQL login for the local database. You can confirm the API authenticates end to end from the same session:

PASS=$(sudo grep '^vikunja.admin.pass=' /root/vikunja-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'no token  -> HTTP %{http_code}\n' http://127.0.0.1/api/v1/user
curl -s -H 'Content-Type: application/json' \
  -d "{\"username\":\"admin\",\"password\":\"$PASS\"}" \
  http://127.0.0.1/api/v1/login | head -c 80; echo

The unauthenticated request returns HTTP 401 and the login call returns a JSON Web Token.

The root-only credentials file and an API authentication round-trip — 401 without a token, a JWT with the per-VM password.

Step 6 — First sign-in

Open a web browser and navigate to http://<vm-public-ip>/. Vikunja presents its sign-in page. Enter the username admin and the password from /root/vikunja-credentials.txt, then select Login.

The Vikunja sign-in, served on first boot with a per-VM administrator login.

Step 7 — Create projects and tasks

Select Projects, then New project, give it a name, and open it. Add tasks with the Add a task... box — you can set priorities, due dates, labels, assignees and reminders. Tasks with a priority are flagged in the list with an Urgent, High or Medium badge.

A Vikunja project list view — tasks with priority labels.

Step 8 — Switch views: list, kanban, Gantt, table and calendar

Every project can be viewed as a List, a Gantt chart, a Table, or a Kanban board using the tabs at the top of the project. The kanban board organises tasks into columns such as To-Do, Doing and Done; drag a card between columns to update its state.

A Vikunja project as a kanban board.

Step 9 — Invite your team and use the API

Open Teams to create a team and share projects with other users. Because open registration is disabled by default, add users from the administrator account or re-enable registration in /etc/vikunja/config.yml. Every action in the web app is also available through the REST API at http://<vm-public-ip>/api/v1/ — authenticate with POST /api/v1/login to obtain a token, then call the API with an Authorization: Bearer <token> header.

Security baseline

The image ships fully patched at capture time and keeps patching itself: Ubuntu's unattended-upgrades service is enabled, so security updates are installed automatically on your running VM. Verify the state at any time:

systemctl is-enabled unattended-upgrades
grep -h . /etc/apt/apt.conf.d/20auto-upgrades
sudo ss -tlnp | grep -E ':(3456|5432) ' || true

The Vikunja server (:3456) and PostgreSQL (:5432) are bound to the loopback interface only — nginx on :80 is the single network-facing entry point.

Automatic security updates enabled, and the application tiers bound to loopback only.

Enabling HTTPS

For any production deployment serve Vikunja over HTTPS so logins cannot be intercepted. The image ships with nginx, which certbot can configure automatically. The following assumes a DNS record pointing your fully qualified domain name at the VM's public IP address (and 443/tcp open in the NSG):

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d tasks.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

After certbot finishes, set the public URL so generated links are correct, then restart Vikunja:

sudo sed -i 's|^  publicurl: .*|  publicurl: "https://tasks.your-domain.example/"|' /etc/vikunja/config.yml
sudo systemctl restart vikunja

Backup and maintenance

Vikunja keeps all of its state — projects, tasks, users and settings — in PostgreSQL, and any uploaded file attachments under /opt/vikunja/files. Back both up regularly:

sudo -u postgres pg_dump vikunja > <backup-dir>/vikunja-db-$(date +%F).sql
sudo tar czf <backup-dir>/vikunja-files-$(date +%F).tgz -C /opt/vikunja files

Because the database (/var/lib/postgresql) and the application directory (/opt/vikunja) are each on their own Azure data disk, you can also take coordinated disk snapshots in Azure. Keep the OS patched with sudo apt update && sudo apt upgrade. To upgrade Vikunja, replace /opt/vikunja/vikunja with a newer release and restart — migrations run automatically on start. See https://vikunja.io/docs/.

Support

This image is backed by 24/7 cloudimg support. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk for help with deployment, upgrades, integrations, TLS termination and database administration.

For general Vikunja questions consult the documentation at https://vikunja.io/docs/. Vikunja is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement. All product and company names are trademarks or registered trademarks of their respective holders.