Scaling Internal Productivity: How to Deploy Vikunja with Appwrite Authentication on a VPS

Introduction: The Case for Self-Hosted Project Management

In the modern corporate landscape, data sovereignty, customization, and cost efficiency are paramount. While SaaS project management tools offer convenience, they often come with recurring per-user fees, rigid feature sets, and compliance concerns regarding third-party data hosting. For enterprises seeking to maintain total control over their operational data while providing a seamless user experience across desktop and mobile platforms, building an internal ecosystem is the optimal strategy.

This technical guide demonstrates how to deploy Vikunja, an open-source, feature-rich task management platform, combined with Appwrite as a centralized authentication backend on a Virtual Private Server (VPS). By leveraging this architecture, your organization can establish a robust, centralized project management system that integrates smoothly with mobile applications and safeguards proprietary workflows.

Why Vikunja and Appwrite?

Selecting the right components for an internal productivity stack requires balancing frontend flexibility with backend security. Here is why the combination of Vikunja and Appwrite stands out for business infrastructure:

Vikunja: Unlike simpler to-do applications, Vikunja is built for scale. It supports multiple views (Kanban boards, Gantt charts, table views, and standard lists), features deep task relations, accommodates team namespaces, and offers a powerful API.
Appwrite: As a secure Backend-as-a-Service (BaaS), Appwrite simplifies user management. It provides out-of-the-box support for OAuth2, Multi-Factor Authentication (MFA), and token-based sessions. This makes it an ideal identity provider for both web platforms and native mobile applications.

By decoupling the project management interface from the authentication layer, businesses can implement a Single Sign-On (SSO) environment, allowing team members to use the same mobile-ready credentials across multiple internal tools.

Prerequisites and System Architecture

Before initiating the deployment, ensure your infrastructure meets the following baseline requirements:

A VPS running a clean installation of Ubuntu 22.04 LTS or later, with at least 2 vCPUs and 4GB of RAM.
A registered domain or subdomain pointed to your VPS IP address via A Records (e.g., tasks.yourcompany.com and auth.yourcompany.com).
Docker and Docker Compose installed on the host system.
An SSL certificate (managed automatically via Reverse Proxy like Nginx or Traefik).

Security Note: Always ensure that port 80 and port 443 are open on your cloud provider's firewall, while restricting access to administrative ports like 22 (SSH) to trusted IP addresses.

Step 1: Setting Up Appwrite as the Identity Provider

First, we must deploy Appwrite to handle our centralized user directory. Appwrite utilizes a Docker-compose setup for its microservices architecture. Run the official installation script on your VPS:

docker run -it --rm --volume /var/run/docker.sock:/var/run/docker.sock --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw --entrypoint="" appwrite/appwrite:latest sh -c "install"

Follow the on-screen prompts to configure your primary domain (e.g., auth.yourcompany.com). Once the installation completes, access the Appwrite Console, create an administrator account, and establish a new project named Corporate Auth.

Configuring OAuth2 and OpenID Connect

To enable Vikunja to offload authentication to Appwrite, navigate to the Auth section within your Appwrite project dashboard. Here, you will define the authentication parameters, access scopes, and token expiration policies. Take note of the Project ID, API Endpoint, and generate an API Key with users/sessions read privileges, as these will be required for the Vikunja configuration file.

Step 2: Deploying Vikunja via Docker Compose

Vikunja consists of two main components: the frontend (the user interface) and the API (the backend). We will deploy them alongside a PostgreSQL database using a single, cohesive docker-compose.yml file. Create a dedicated directory for your deployment:

mkdir -p /opt/vikunja && cd /opt/vikunja

Construct your deployment file with the following structural layout:

Database Service: PostgreSQL or MariaDB to manage persistent task data.
API Service: The core Go-based backend that handles processing and external calls.
Frontend Service: The web interface served via a lightweight web server.

Within the configuration block for the Vikunja API, map the OpenID Connect (OIDC) parameters to point directly to your Appwrite authentication endpoints. This tells Vikunja to trust identity tokens issued by your Appwrite server.

Step 3: Integrating Appwrite Auth into Vikunja

To finalize the integration, modify Vikunja’s main configuration file (config.yml). Under the auth section, enable external providers and input your Appwrite metrics:

auth:
  openid:
    enabled: true
    providers:
      - name: "Company Auth"
        issuer: "[https://auth.yourcompany.com/v1](https://auth.yourcompany.com/v1)"
        clientid: "YOUR_APPWRITE_PROJECT_ID"
        clientsecret: "YOUR_APPWRITE_API_KEY"
        scope: ["profile", "email"]

This directive establishes a secure handshake. When users navigate to your Vikunja login screen, they will see a prominent "Sign in with Company Auth" button. Clicking this redirects them to Appwrite, validates their active session or mobile token, and returns them securely to their workspace without requiring a separate Vikunja password.

Step 4: Nginx Reverse Proxy and SSL Configuration

To ensure all corporate data is encrypted in transit, we implement Nginx as a reverse proxy coupled with Let's Encrypt SSL certificates. This layout routes incoming HTTPS traffic correctly to either the Appwrite auth containers or the Vikunja frontend interface.

Create an Nginx configuration block that secures the headers and prevents common vulnerability exploits:

server {
    listen 443 ssl http2;
    server_name tasks.yourcompany.com;

    ssl_certificate /etc/letsencrypt/live/[tasks.yourcompany.com/fullchain.pem](https://tasks.yourcompany.com/fullchain.pem);
    ssl_certificate_key /etc/letsencrypt/live/[tasks.yourcompany.com/privkey.pem](https://tasks.yourcompany.com/privkey.pem);

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Execute sudo nginx -t to verify configuration integrity, followed by sudo systemctl restart nginx to apply the production-grade traffic routing rules.

Step 5: Optimizing for Cross-Platform Mobile Access

One of the primary business advantages of this architecture is its native compatibility with mobile workflows. Because Appwrite is explicitly designed as a mobile-first backend framework, syncing user profiles with Android and iOS applications is straightforward.

When deploying the Vikunja mobile application to internal staff devices:

Users open the mobile client and input the self-hosted instance URL ([https://tasks.yourcompany.com](https://tasks.yourcompany.com)).
The client detects the unified authentication constraint and opens a secure mobile browser window pointing to your Appwrite authentication portal.
Upon biometric verification or standard credentials input, Appwrite securely passes a secure JWT session token back to the native application container.

This guarantees that employees maintain immediate, secure access to their internal project pipelines whether working at their desks or in the field.

Conclusion: Long-term Operations and Maintenance

By coupling Vikunja with Appwrite Auth on an isolated VPS, your enterprise successfully retains total ownership of its operational data while matching the fluid user experience of enterprise SaaS platforms. To ensure the long-term reliability of this ecosystem, execute automated nightly backups of the PostgreSQL volume and monitor server metrics via standardized tools.

Implementing this infrastructure lays a powerful foundation for scalable internal operations, eliminating user licensing bottlenecks and securing sensitive corporate milestones inside a private cloud environment.