How to Use Vikunja: The Beginner's Guide (First Install, the UID-1000 Rule, Sharing, and CalDAV Sync)

CodexFuse Team · 2026-10-31T10:29:05.533Z · 13 min read

The complete beginner guide to Vikunja: Docker Compose install, the UID-1000 rule, your first project and Quick Add Magic, sharing, CalDAV sync, PostgreSQL, and the hardening finish.

If you want to learn how to use Vikunja, this beginner guide takes you from zero to a running self-hosted task manager: installing Vikunja with Docker Compose, surviving the UID-1000 rule, creating your first project and task, sharing a project with someone else, syncing tasks to your phone with CalDAV, and locking down open registration when you are done. The install below assumes you can run containers — the Docker beginner guide gets you that far — and everything else is one beginner arc, not a manual.

What is Vikunja?

Vikunja is an open-source, self-hostable task and project management tool that organizes tasks, projects, and teams with lists, Kanban boards, Gantt charts, table views, labels, priorities, reminders, and file attachments — the feature set you would expect from Todoist, Trello, or Microsoft To Do — while running entirely on your own hardware with no cloud dependency (selfhosting.sh, verified March 2026).

Architecturally it is two parts — API and frontend — bundled into a single deployable binary or Docker container, so you only install one thing (Vikunja official installing docs, crawled 2026-10-31). Since v0.22 it ships as one container (vikunja/vikunja) that uses SQLite by default and optionally supports PostgreSQL or MySQL for larger deployments. It is written in Go with a Vue.js frontend, it runs comfortably on a Raspberry Pi 4 or a $5/month VPS, and it uses about 50 MB of RAM at idle — about 200 MB total with PostgreSQL under light use (selfhosting.sh).

Vikunja uses a hierarchy: tasks belong to projects, and projects can be nested into a hierarchy, with list, Kanban, Gantt, and table views displaying the same tasks in different ways (techdecode.online, updated October 6, 2026). That nesting is what makes it scale from a personal to-do list to a team workspace without changing apps.

What do I need before installing Vikunja?

You need a machine that stays on and a working Docker setup. The fastest path is the Docker beginner guide — every command below assumes Docker Engine and the Compose plugin — and if you want Vikunja on real server hardware instead of a home machine, the what is VPS hosting guide explains the box most people deploy it on. A spare Linux computer, a single-board computer like a Raspberry Pi, or a small VPS all work; Debian or Ubuntu Server are practical starting points (techdecode.online).

Resource requirements are tiny: selfhosting.sh lists a 512 MB RAM minimum (1 GB recommended with PostgreSQL) and 1 GB of free disk space. You need one free port — 3456, which Vikunja exposes for both its web UI and API.

If you are coming from the home-server ecosystem, this is the app layer: run it as a service on your home-server OS rather than as the OS itself. The Cosmos beginner guide covers the server-OS layer this kind of app typically deploys on, and the NocoDB beginner guide is the data sibling — the no-code database you might run next to Vikunja on the same machine.

How do I install Vikunja with Docker Compose?

You install Vikunja with Docker Compose by preparing two writable folders, pinning the image tag, setting three environment variables, and running docker compose up -d. This is the SQLite path — one container, the best beginner trial. Vikunja recommends MySQL or PostgreSQL for more than a handful of users (official docs), but SQLite is a fully supported backend, not a hack.

Create the project directory and the two folders Vikunja needs — files for attachments and db for the SQLite database:

mkdir -p ~/vikunja/files ~/vikunja/db
cd ~/vikunja
sudo chown 1000 ./files ./db
openssl rand -hex 32

The chown 1000 line is the step beginners skip, and it is why the next section exists. Save the openssl output as your private secret — it signs authentication tokens, so keep it out of public repositories (techdecode.online).

Save this as compose.yml. Note the pinned image tag — the current release is v2.7.1 (GitHub releases API for go-vikunja/vikunja, queried 2026-10-31; released 2026-10-20):

services:
  vikunja:
    image: vikunja/vikunja:2.7.1
    environment:
      VIKUNJA_SERVICE_PUBLICURL: "http://localhost:3456/"
      VIKUNJA_SERVICE_SECRET: "${VIKUNJA_SECRET:?Set a private random secret}"
      VIKUNJA_DATABASE_TYPE: sqlite
      VIKUNJA_DATABASE_PATH: /db/vikunja.db
    ports:
      - "127.0.0.1:3456:3456"
    volumes:
      - ./files:/app/vikunja/files
      - ./db:/db
    restart: unless-stopped

Each environment variable has a job, and the jobs are worth knowing before anything goes wrong:

Start and test:

docker compose up -d
docker compose ps
docker compose logs --tail=80 vikunja

First startup takes 10–20 seconds while the database schema is created (selfhosting.sh). Then open http://localhost:3456/, click Register, and create your first user. Register a task and attach a small file, then restart the container (docker compose restart) and confirm both survive — that checks the two storage paths before you entrust Vikunja with real work (techdecode.online).

What is the Vikunja UID-1000 rule?

The Vikunja container runs as user ID 1000 with no group by default — and every file it writes must be writable by that UID on the host. If you skip the chown 1000 step, uploads fail and the database may refuse to write, even though the container starts fine (official installing docs, crawled 2026-10-31).

The symptom is distinctive: Vikunja logs show permission errors and the UI shows a generic upload failure when you attach a file to a task (selfhosting.sh). The fix always happens on the host, not inside the container — Vikunja uses a scratch-based image with no shell, so you cannot exec in and fix permissions from inside:

chown -R 1000 ~/vikunja/files ~/vikunja/db

You can also change the UID with Docker's --user flag, but the new user must have permissions on the files and db folders (official docs). The rule is simple to remember: Vikunja does not run as root, so the host folders it writes to must belong to its user.

How do I create my first project and task?

After logging in, click the plus icon and create your first project — then add tasks inside it. Projects are Vikunja's container; lists inside projects are views of the work. A project is where a thing lives; the view is how you look at it (techdecode.online; selfhosting.sh).

Vikunja gives you four views of the same tasks: list for quick capture, Kanban for seeing task status, Gantt for date-based planning, and table for comparing fields side by side. These are views of the same tasks, not four copies of the work — switching views never duplicates anything (techdecode.online).

Add a task by typing its title and pressing Enter. Vikunja supports natural language parsing — type "Buy groceries tomorrow at 5pm" and it sets the due date and time automatically (selfhosting.sh). Then learn Quick Add Magic, Vikunja's keyboard-first task creation mode. In the default mode these shortcuts work:

Always check the parsed result and your timezone before relying on a reminder, and quote the whole title when you want date-like words treated literally — a "Todoist mode" also exists with different shortcuts (techdecode.online). For a first real project, start small: a shopping list with short task names, or a homelab project where every task has a clear outcome, an owner, and a due date.

How do I share a project with someone else?

You share a project with another registered user — the classic example is a shared shopping list with a partner. Each person gets their own Vikunja account, and the project owner gives them access to the project (techdecode.online).

The practical order matters: create the other person's account first (send them to your Vikunja URL to register, or create it via the CLI's user create command), then share the project with them. Project ownership and sharing permissions are separate from instance administration — sharing a project does not make someone an admin of your instance (techdecode.online).

For a household shopping list, keep tasks short and share the project with the appropriate household members. For a small team, give each task a clear owner and due date, and use labels sparingly at first — start with the labels that make work easier to find, not every possible label on day one (techdecode.online).

How do I sync Vikunja tasks with my phone?

Vikunja exposes a CalDAV endpoint at /dav that syncs your tasks with calendar and task apps, and it also ships native mobile apps. You have two routes; pick one (selfhosting.sh).

The CalDAV route: your personal sync URL is https://tasks.example.com/dav/principals/YOUR_USERNAME/ — replace the domain with your instance and the username with your Vikunja username. In your client, use the instance URL with the /dav path as the server address and authenticate with your Vikunja username and password; your projects appear as separate task lists (selfhosting.sh).

Compatible clients are DAVx5 with OpenTasks on Android, Evolution on Linux, and KOrganizer on KDE. Known limitation to set expectations correctly: Thunderbird and iOS native CalDAV have known compatibility issues — use a dedicated task app instead (selfhosting.sh).

The native-app route: Vikunja has native apps for Android (Google Play Store and F-Droid) and iOS (App Store). Enter your instance URL and log in with your credentials — but remote connections require HTTPS with a valid certificate, so this route needs a reverse proxy with TLS before it works outside your LAN (selfhosting.sh). A domain name is optional for a home setup, but required for CalDAV and mobile apps over the internet.

Vikunja vs Todoist: should you switch?

Vikunja is most often compared to Todoist because both live in the "task manager" lane, but they are different propositions: Todoist is a polished SaaS product; Vikunja is a self-hosted open-source alternative (AGPL-3.0 licensed) where you control the data (selfhosting.sh; techdecode.online).

Switch if the data matters to you more than the convenience: self-hosters escaping SaaS task apps are the core Vikunja audience. Stay if you want zero maintenance — Vikunja's own managed offering, Vikunja Cloud, exists for people who would rather pay than maintain a server, and one-click hosts like Zenith, PikaPods, Pethost, and Hostim sit between the two extremes (official installing docs).

Should I use PostgreSQL with Vikunja?

For one person or a small team, SQLite — the default — is fine. For five or more concurrent users, or if you want easier backup and maintenance, use PostgreSQL (selfhosting.sh). This is the "vikunja postgres" branch of the guide.

The postgres setup runs two containers: Vikunja plus postgres:16-alpine, wired with environment variables. The database side needs a healthcheck so Vikunja does not try to connect before Postgres is ready — Vikunja does not retry database connections on its own (selfhosting.sh):

services:
  vikunja:
    image: vikunja/vikunja:2.7.1
    environment:
      VIKUNJA_SERVICE_PUBLICURL: https://tasks.example.com/
      VIKUNJA_SERVICE_SECRET: "${VIKUNJA_SECRET:?Set a private random secret}"
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: vikunja-db
      VIKUNJA_DATABASE_USER: ${POSTGRES_USER}
      VIKUNJA_DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
      VIKUNJA_DATABASE_DATABASE: ${POSTGRES_DB}
      TZ: Etc/UTC
    ports:
      - "3456:3456"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      vikunja-db:
        condition: service_healthy
    restart: unless-stopped
  vikunja-db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - ./db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $POSTGRES_USER"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 30s
    restart: unless-stopped

Put the postgres credentials and the public URL in a .env file, generating secrets with openssl rand -hex 32. Note the timezone variable: it affects reminder delivery and timestamps (selfhosting.sh).

One migration warning to know up front: Vikunja does not include a built-in migration tool from SQLite to PostgreSQL — moving later means exporting via the API and re-importing, so pick the backend you will keep (selfhosting.sh).

How do I lock down Vikunja after installing it?

Three jobs: stop open registration, expose it over HTTPS, and back it up. Do them in that order.

First, disable open registration once your users exist. The environment variable is VIKUNJA_SERVICE_ENABLEREGISTRATION — set it to false after everyone has registered, or strangers can create accounts on your instance (techdecode.online). About admins: in current Vikunja (v2.7.x era), the first registered account is NOT automatically an instance administrator — the CLI promotes users with vikunja user set-admin <username> --admin inside the container, but that command requires an active Vikunja Pro license with the admin panel feature (official CLI docs, crawled 2026-10-31). Older guides (selfhosting.sh, pinned to v2.1.0) say the first registered user gets admin automatically — so do not assume; verify against your version. Either way, project sharing is separate from instance administration: sharing a project never makes someone an admin.

Second, put Vikunja behind a reverse proxy for HTTPS and a clean domain, and update VIKUNJA_SERVICE_PUBLICURL to the exact public address — protocol included, no trailing slash confusion — or login and CORS break. The simplest proxy is a two-line Caddy block pointing at port 3456 (selfhosting.sh), and the Caddy beginner guide walks through that exact setup.

Third, back up two things: the database and the files folder. Vikunja's CLI gives you vikunja dump, which creates a zip containing the config, version, all files, and the full database, and vikunja restore to bring it back — run them inside the container with docker exec <container> /app/vikunja/vikunja dump (official CLI docs). On PostgreSQL, pg_dumpall covers the database side, and a cron job with off-server copies finishes the job (selfhosting.sh).

Sources

• Vikunja official installing docs (crawled 2026-10-31): single binary/container architecture; mkdir $PWD/files $PWD/db + chown 1000; container runs as UID 1000; VIKUNJA_SERVICE_PUBLICURL required for login (or disable CORS); images signed with cosign since v2.7.1; managed hosts Zenith/PikaPods/Pethost/Hostim.
• Vikunja official CLI docs (crawled 2026-10-31): vikunja user set-admin [username-or-id] --admin requires an active Vikunja Pro license with the admin panel feature; vikunja doctor, dump, restore, testmail commands; docker usage docker exec <name> /app/vikunja/vikunja <subcommand>.
• techdecode.online, "Conquer Your Chaos: Self-Hosting Vikunja at Home" (updated October 6, 2026): SQLite beginner compose.yml; chown 1000; VIKUNJA_SERVICE_SECRET is the current name (older VIKUNJA_SERVICE_JWTSECRET deprecated); first account not automatically admin; VIKUNJA_SERVICE_ENABLEREGISTRATION; Quick Add Magic syntax; views; backup and update guidance.
• selfhosting.sh, "Self-Host Vikunja" (updated March 2026, verified with latest Docker images): PostgreSQL compose with healthcheck; prerequisites (Ubuntu 22.04+, 512 MB RAM, 1 GB disk); CalDAV /dav endpoint and /dav/principals/YOUR_USERNAME/ format; compatible clients DAVx5+OpenTasks/Evolution/KOrganizer; Thunderbird/iOS known issues; mobile apps with HTTPS requirement; 20 MB default upload limit; ~50 MB idle RAM; troubleshooting (UID-1000 fix, CORS fix, DB connection).
• XDA Developers, "I self-host Vikunja on my home lab to manage my to-do lists for free" (published Feb 3, 2025): Proxmox helper-script and docker run install paths; first account creation; lightweight enough for Raspberry Pi.
• GitHub releases API, go-vikunja/vikunja (queried 2026-10-31): latest tag v2.7.1, released 2026-10-20.
• robert.penz.name HowTo notes (crawled 2026-10-31): VIKUNJA_SERVICE_PUBLICURL must not have a trailing slash (breaks password reset links); testmail CLI verification; mailer environment variables.

Frequently asked questions about using Vikunja

What is Vikunja used for?

Vikunja is a self-hosted task and project management tool used for personal to-do lists, shared household projects, and team work — with lists, Kanban boards, Gantt charts, table views, labels, priorities, reminders, and CalDAV sync. Self-hosters use it as the open-source alternative to Todoist, Trello, or Microsoft To Do when they want their data on their own hardware.

Is Vikunja really free?

Yes. Vikunja is open source under the AGPL-3.0 license and self-hosting costs no software license — your costs are the hardware, electricity, and your time maintaining it. Vikunja Pro is a separate optional offering for self-hosted instances (currently a private beta), and Vikunja Cloud is the paid managed alternative if you would rather not run a server (techdecode.online).

Does Vikunja work on mobile?

Yes — Vikunja has native apps for Android (Google Play Store and F-Droid) and iOS (App Store), and it also exposes a CalDAV endpoint at /dav for syncing tasks with apps like OpenTasks. Remote mobile access requires HTTPS with a valid certificate, so you need a reverse proxy with TLS before connecting from outside your LAN (selfhosting.sh).

Why does Vikunja fail with permission errors on Docker?

Because the container runs as user ID 1000, not root: the host folders mounted as /app/vikunja/files and /db must be writable by UID 1000, or attachments fail and the database cannot write. Fix it on the host with chown -R 1000 <folders> — you cannot fix it from inside the container, which has no shell (official installing docs; selfhosting.sh).

Can I use Vikunja without self-hosting?

Yes. Vikunja Cloud is the project's own hosted offering, and one-click managed hosts like Zenith, PikaPods, Pethost, and Hostim run Vikunja for you with backups handled (official installing docs). Sharing projects works identically when self-hosting — collaboration itself never requires buying cloud hosting (techdecode.online).