Skip to content
Klutch.sh Docs

Deploying a Vikunja App

Introduction

Vikunja is an open-source task management platform with a lightweight API and web UI. This guide shows how to containerize Vikunja, connect it to PostgreSQL (and optionally Redis), persist uploads, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • PostgreSQL database (managed or deployed separately).
  • Optional Redis instance for rate limiting and caching.
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM vikunja/api:latest


# Default Vikunja port
ENV VIKUNJA_HTTP_PORT=3456
EXPOSE 3456

Required environment variables

  • VIKUNJA_DATABASE_TYPE=postgres
  • VIKUNJA_DATABASE_HOST – database host
  • VIKUNJA_DATABASE_DATABASE – database name
  • VIKUNJA_DATABASE_USER
  • VIKUNJA_DATABASE_PASSWORD
  • VIKUNJA_SERVICE_JWTSECRET – strong secret for tokens
  • VIKUNJA_SERVICE_FRONTENDURL – e.g., https://example-app.klutch.sh
  • VIKUNJA_HTTP_PORT=3456

Optional environment variables

  • VIKUNJA_REDIS_ENABLED=true and Redis connection settings
  • VIKUNJA_SERVICE_ENABLEREGISTRATION=false to control signups
  • VIKUNJA_LOG_LEVEL=info

Persistence

If you store file uploads locally, attach a volume:

  • Mount path: /app/vikunja/files
  • Size: based on expected attachment volume

Networking

  • Protocol: HTTP
  • Internal port: 3456
  • Users reach https://example-app.klutch.sh while Klutch.sh routes to port 3456 inside the container.
Terminal window
curl -I http://localhost:3456/health

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 3456.
  5. Add environment variables for database connection, VIKUNJA_SERVICE_JWTSECRET, and VIKUNJA_SERVICE_FRONTENDURL. Add Redis variables if used. Mark sensitive values as secrets.
  6. Attach a persistent volume at /app/vikunja/files if storing uploads locally.
  7. Deploy. After the app starts, create your admin user via the UI.

Verification

  • UI: open https://example-app.klutch.sh and confirm the login/setup screen loads.

  • Health:

    Terminal window
    curl -I https://example-app.klutch.sh/health

Next steps

  • Configure registration policies and JWT rotation.
  • Enable Redis to improve performance and rate limiting.
  • Set up database backups and volume backups for file uploads.