Host Kaneo on a VPS: Minimalist Open-Source Project Management

SaaS project management tools tend to grow heavier with every release: new views, AI dashboards and reporting modules that bury the features you actually use. Kaneo starts from the opposite assumption: most teams only need a Kanban board and a link to their code repository. By self-hosting it, you take full ownership — your tasks in a PostgreSQL database on your VPS, exportable as SQL at any time, without a premium plan to unlock webhooks or without quota history.

A ServOrbit VPS with Ubuntu 24.04 and at least 1 GB of RAM is sufficient for a small team. Kaneo is lightweight: the Hono (Node.js) API and the Vue.js SPA together consume under 200 MB at idle; PostgreSQL 16 adds around 300 MB. Docker and Docker Compose are provisioned automatically by AWX on deployment. A domain name is not required — Kaneo works behind the URL assigned by ServOrbit — but a dedicated subdomain (e.g. projects.your-domain.com) makes sharing easier.

Kaneo supports multiple workspaces on a single instance. Each workspace has its own projects, members and webhooks — useful for isolating clients or teams on one VPS without running multiple deployments.

To create a second workspace, click the selector in the top-left of the interface and choose 'New Workspace'. Members of one workspace have no access to others: the isolation is at the application level, not just visual. You can host client A's projects and client B's projects on the same server, each with their own boards and separate GitHub integrations.

If you need custom fields on tasks, check the official Kaneo documentation before relying on them: custom fields are on the roadmap, but availability may vary by deployed version. Review the release notes for your current version on the Kaneo GitHub repository before designing a workflow that depends on them.

Kaneo's webhooks are one of its most direct advantages for development teams. On every task state change — column move, assignment, comment — Kaneo sends a POST JSON to the URL of your choice.

Common use cases:

- Slack notification: add your channel's Incoming Webhook URL to receive an alert whenever a task moves to 'In Progress' or 'Done'.
- CI pipeline trigger: forward the event to your CI system (GitHub Actions, Gitea Actions, Jenkins) to automatically start a build or deployment when a task reaches a target column.
- External system sync: the endpoint can point to any REST API — reporting tool, ticket database, or a n8n webhook to orchestrate complex workflows.

The Kaneo payload structure is documented in the official repository. Test your endpoints with a service like webhook.site before wiring them into production, to verify the format matches what your CI expects.

Kaneo stores all its data in PostgreSQL 16. Regular backups are essential: without them, a failed update or volume corruption could cost you your entire task history.

Automating backups with cron and rclone

A two-step approach — daily local dump, then copy to remote object storage:

# /etc/cron.d/kaneo-backup
0 3 * * * root docker exec kaneo-db pg_dump -U kaneo kaneo | gzip > /var/backups/kaneo/$(date +\%Y\%m\%d).sql.gz
5 3 * * * root rclone copy /var/backups/kaneo/ s3:my-bucket/kaneo/ --max-age 30d

Replace kaneo-db with your actual PostgreSQL container name (docker ps to check) and kaneo with the credentials configured at deployment time.

Restoring a backup

# Stop the application before restoring
docker stop kaneo-app
# Restore the dump into the PostgreSQL container
gunzip -c /var/backups/kaneo/20260901.sql.gz | docker exec -i kaneo-db psql -U kaneo kaneo
# Restart
docker start kaneo-app

Keep at least 7 local dumps and 30 days of remote copies. Test a restore on a separate environment before you need it — a dump that cannot be restored is no better than no backup at all.

Kaneo publishes its releases on GitHub. The update procedure is standard for a Docker Compose deployment:

# Pull the updated image
docker compose pull
# Restart containers with the new image
docker compose up -d
# Verify containers are running
docker compose ps

Before any update, take a full backup (see the previous section). Read the release notes for the new version on GitHub: some updates include database migrations that run automatically when the container starts. If a migration fails, the application container logs (docker logs kaneo-app) will show the details.

If you deployed via the ServOrbit Marketplace, a template update in your control panel may trigger a redeployment with the next version — check your plan's documentation.

By default, Kaneo does not require an SMTP server: sign-up uses email and password without a verification link. This simplifies the initial deployment but limits email notifications (password reset, task alerts).

If your Kaneo version supports SMTP configuration, the settings live in the environment variables of the deployed docker-compose.yml:

SMTP_HOST=smtp.your-domain.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-password
[email protected]

If your ServOrbit instance includes a professional email plan, use the SMTP settings from your outbound mailbox. After changing environment variables, restart the containers with docker compose up -d. Test sending from the admin interface before closing public registration.

Container restarts in a loop on first start

Most common cause: a missing or malformed secret in the environment file. Check the application container logs (docker logs kaneo-app) — the error usually names the missing variable. Secrets are generated automatically on Marketplace deployment; on a manual install, make sure JWT_SECRET, DATABASE_URL and COOKIE_SECRET are defined.

Interface loads but login fails with 'Invalid credentials'

The first account created is the administrator. If you restarted the container without removing the PostgreSQL volume, the account already exists: try logging in with the credentials entered at first sign-up. If the volume was deleted, create a new account from the interface.

Webhooks do not fire

Check that the destination URL is reachable from the Kaneo container (not localhost on the host VPS — use an external IP or a domain name). Test with curl -X POST https://your-endpoint.com/webhook -d '{}' from within the container to confirm connectivity.

GitHub sync stops after a few hours

The GitHub App requires the callback URL to be reachable over HTTPS from the internet. Check that your SSL certificate is valid (certbot renew --dry-run) and that port 443 is open on your VPS.

Performance degrades with many tasks

On a 1 GB RAM VPS, PostgreSQL can become a bottleneck as data volume grows. Increase shared_buffers in the PostgreSQL configuration or upgrade to a plan with 2 GB of RAM. Kaneo is not designed for thousands of simultaneously active tasks — that is a deliberate design choice, not a defect.