How to Self-Host Vikunja with CalDAV: Real-Time Calendar Sync Between VPS, Apple Calendar, and Google Calendar

Introduction: The Quest for Unified Task and Time Management

In the modern corporate ecosystem, efficiency is heavily dictated by how seamlessly our task lists interact with our schedules. Professionals often find themselves trapped between specialized to-do applications and platform-specific calendars like Apple Calendar or Google Calendar. This fragmentation leads to missed deadlines, scheduling conflicts, and cognitive overload.

While proprietary SaaS solutions offer integrations, they often come at the cost of data privacy, recurring subscription fees, and rigid customization constraints. Enter Vikunja, an open-source, high-performance task management platform that serves as a powerful self-hosted alternative to Todoist or Asana. When combined with CalDAV—the open standard for calendar data exchange—Vikunja transforms from a standalone to-do list into a centralized scheduling engine. This technical guide outlines the precise architecture and configuration required to self-host Vikunja on a Virtual Private Server (VPS) and establish real-time, bidirectional synchronization with both Apple and Google ecosystems.

Why Vikunja and CalDAV Are a Game-Changer for Professionals

Before diving into the technical deployment, it is vital to understand the strategic advantages of this specific stack:

Data Sovereignty: Hosting Vikunja on your own VPS ensures that sensitive corporate roadmaps, client deliverables, and personal schedules remain entirely under your control, complying with strict data protection standards.
Native CalDAV Implementation: Unlike platforms that rely on brittle third-party plugins, Vikunja features a robust, native CalDAV interface. This allows it to present tasks with due dates directly as calendar events.
Cross-Platform Synchronization: By bridging CalDAV with Apple Calendar and Google Calendar, you achieve a unified workflow. You can view, modify, or complete Vikunja tasks directly from your MacBook, iPhone, or Android device in real-time.

Prerequisites and Architecture Overview

To successfully execute this deployment, ensure you have the following prerequisites in place:

A VPS running a modern Linux distribution (e.g., Ubuntu 22.04 LTS or newer) with a public IP address.
A registered domain name with access to DNS management (e.g., vikinja.yourdomain.com).
Docker and Docker Compose installed on the host system.
A reverse proxy, such as Nginx Proxy Manager, Traefik, or Caddy, to handle SSL/TLS termination.

Note: For security reasons, running this infrastructure over unencrypted HTTP is highly discouraged. Ensure your reverse proxy is configured to enforce HTTPS via Let's Encrypt certificates.

Step 1: Deploying Vikunja via Docker Compose

Vikunja utilizes a decoupled architecture consisting of a frontend, a backend API, and a database (typically PostgreSQL or MariaDB). Using Docker Compose simplifies this multi-container arrangement into a single, maintainable configuration file.

Create a dedicated directory on your VPS and initialize a docker-compose.yml file with the following production-ready configuration:

version: '3.8'

services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: YourSecurePasswordHere
      POSTGRES_DB: vikunja
    volumes:
      - ./db:/var/lib/postgresql/data
    restart: unless-stopped

  api:
    image: vikunja/api
    environment:
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: YourSecurePasswordHere
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_NAME: vikunja
      VIKUNJA_SERVICE_JWTSECRET: YourRandomSuperLongJWTSecretKey
      VIKUNJA_SERVICE_FRONTENDURL: [https://vikunja.yourdomain.com/](https://vikunja.yourdomain.com/)
      VIKUNJA_CALDAV_ENABLED: "true"
      VIKUNJA_CALDAV_AUTH_LOCAL: "true"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      - db
    restart: unless-stopped

  frontend:
    image: vikunja/frontend
    restart: unless-stopped

Execute docker compose up -d to pull the images and launch the services in detached mode. Configure your reverse proxy to route incoming traffic from your subdomain (e.g., vikunja.yourdomain.com) to the frontend container, ensuring that paths matching /api/v1 or /dav are correctly proxied directly to the API container.

Step 2: Locating and Configuring the CalDAV Endpoint in Vikunja

Once your Vikunja instance is live, navigate to your web interface and create your administrative account. To link external calendars, you need to extract the specific CalDAV URL assigned to your namespaces. Vikunja automatically maps your namespaces and lists to distinct calendars.

Navigate to Settings > CalDAV within the Vikunja UI. You will be presented with a Principal URL structured as follows:

[https://vikunja.yourdomain.com/dav/principals/username/](https://vikunja.yourdomain.com/dav/principals/username/)

Copy this URL along with your account credentials. These details will serve as the authentication bridge for your calendar clients.

Step 3: Synchronizing with Apple Calendar (macOS & iOS)

Apple ecosystems natively support the CalDAV protocol, making the integration remarkably fluid and efficient. Follow these steps to map your self-hosted tasks directly to your Apple devices:

On macOS:

Open the Calendar app, click on Calendar in the menu bar, and select Settings > Accounts.
Click the + (Plus) icon to add a new account, select Other CalDAV Account..., and click Continue.
Change the Account Type to Manual or Advanced.
Input your Vikunja username, password, and paste the server address/Principal URL extracted in Step 2.
Click Sign In. Your Vikunja tasks containing due dates will instantly render as calendar events.

On iOS (iPhone/iPad):

Go to Settings > Calendar > Accounts > Add Account. Choose Other, then select Add CalDAV Account. Enter your server location and credentials. Once verified, ensure the "Calendars" toggle is enabled. Modifications made from your iPhone will reflect on your VPS instantaneously.

Step 4: Bridging to Google Calendar

Unlike Apple, Google Calendar does not support direct, native CalDAV client provisioning for external personal servers within its web UI. To synchronize Vikunja tasks to Google Calendar in real-time, you have two primary architectural choices:

Method A: Utilizing an Intermediate Sync Tool

Open-source utilities such as vdirsyncer or CalDAV-CalDAV bridges can be hosted on your VPS alongside Vikunja. These tools run as localized cron jobs or continuous daemons, reading changes from your Vikunja CalDAV endpoint and pushing them directly to the Google Calendar API. This guarantees a true bidirectional data flow.

Method B: The WebCal/iCal Subscription Alternative (Read-Only)

If your primary requirement is simply viewing tasks on Google Calendar without needing to edit them from the Google interface, you can leverage Vikunja's subscription tokens:

In Vikunja, navigate to your specific list settings and generate an iCal/WebCal export link.
Open Google Calendar via your web browser.
On the left-hand sidebar, click the + next to "Other calendars" and select From URL.
Paste your subscription link and click Add Calendar. Google will periodically poll your VPS for updates.

Conclusion: Achieving Ultimate Productivity Mastery

By self-hosting Vikunja and coupling it with CalDAV synchronization, you eliminate data silos and break free from platform lock-in. You now possess a highly secure, real-time productivity hub tailored specifically to your cross-platform workflow. Managing deliverables, tracking project milestones, and structuring your workday can now occur seamlessly from the calendar interface of your choice—backed by the power, privacy, and performance of your dedicated VPS infrastructure.