How to Run Kaneo as a Service: Docker Compose Deployment Guide

Run Kaneo as a service by deploying its Docker Compose stack, which orchestrates PostgreSQL, the Hono-based API, and the React web frontend behind a unified container network with automatic restart policies.

Kaneo is a self-hosted project-management platform delivered as a containerized multi-service application. To run Kaneo as a service on your infrastructure, you deploy three core components—a PostgreSQL database, a Node.js API server, and a Vite-powered React frontend—using the compose.yml file provided in the usekaneo/kaneo repository.

Architecture Overview

Kaneo consists of three containerized services defined in compose.yml at the repository root:

• PostgreSQL – The relational database that persists project data, user accounts, and task information.
• API Server – A Hono-based Node.js service (@kaneo/api) defined in apps/api/ that exposes OpenAPI endpoints and handles authentication.
• Web Frontend – A React application (@kaneo/web) built with Vite, located in apps/web/, which communicates with the API via TanStack Query.

These services share a Docker network, allowing the web container to reach the API internally using the hostname api.

Environment Configuration

Before starting the service, prepare the environment file. Copy .env.sample to .env in the repository root:

cp .env.sample .env

Edit .env to define required variables:

• AUTH_SECRET – Generate a 32-byte secret using openssl rand -hex 32
• POSTGRES_PASSWORD – Secure password for the database
• DATABASE_URL – Connection string (e.g., postgresql://kaneo:${POSTGRES_PASSWORD}@postgres:5432/kaneo)
• KANEO_API_URL – External URL for the API (e.g., http://localhost:1337)
• KANEO_CLIENT_URL – External URL for the web interface (e.g., http://localhost:5173)
• VITE_API_URL – Must match KANEO_API_URL for the web container

The API reads these values at runtime from the filesystem, while the web container consumes VITE_API_URL during its build process. For detailed troubleshooting and local development guidance, consult ENVIRONMENT_SETUP.md in the repository root.

Starting the Service

Launch Kaneo as a background service using Docker Compose:

docker compose up -d

The compose.yml file specifies restart: unless-stopped for all containers, ensuring the service automatically recovers from crashes and host reboots. Docker pulls the pre-built image ghcr.io/usekaneo/kaneo:latest (built via Dockerfile.kaneo), initializes PostgreSQL, and applies database migrations automatically.

Verify the running containers:

docker compose ps

You should see three healthy containers exposing ports 5173 (web), 1337 (API), and 5432 (PostgreSQL).

Production Deployment Options

For production workloads, consider these alternatives to the single-container deployment:

Separate Container Images Replace the monolithic image with specific service containers:

• ghcr.io/usekaneo/api for the API server
• ghcr.io/usekaneo/web for the frontend

This allows independent scaling and updating of components. Configuration in apps/api/vite.config.ts and apps/web/vite.config.ts controls the build behavior when creating custom images.

Kubernetes The repository includes a Helm chart in charts/kaneo/ (documented in charts/kaneo/README.md) for deploying Kaneo as a Kubernetes service with configurable replicas and ingress rules.

Reverse Proxy Configure Nginx or Traefik in front of the Docker Compose stack, updating KANEO_API_URL and KANEO_CLIENT_URL to use your domain names.

Systemd Integration

To integrate Kaneo with your host's init system, create a systemd unit file at /etc/systemd/system/kaneo.service:

[Unit]
Description=Kaneo project-management service
After=network.target docker.service
Requires=docker.service

[Service]
WorkingDirectory=/opt/kaneo
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable kaneo
sudo systemctl start kaneo

Summary

• Kaneo runs as a service via Docker Compose defined in compose.yml, orchestrating PostgreSQL, the Hono API, and the React web app.
• Configuration is centralized in a single .env file derived from .env.sample, requiring AUTH_SECRET, database credentials, and URL endpoints.
• The restart: unless-stopped policy ensures high availability across host reboots.
• For Kubernetes environments, use the official Helm chart in charts/kaneo/.
• Optional systemd integration provides native service management on Linux systems.

Frequently Asked Questions

How do I update Kaneo to the latest version?

Pull the latest images and recreate the containers:

docker compose pull
docker compose up -d

The API container automatically runs migrations on startup, preserving your PostgreSQL data stored in the Docker volume.

Can I run Kaneo without Docker?

While the repository provides Docker as the primary deployment method, you can run the services natively by installing Node.js, PostgreSQL, and building the applications from apps/api/ and apps/web/ using their respective Vite configurations. However, Docker Compose remains the recommended approach for running Kaneo as a reliable service.

How do I backup the Kaneo database?

Backup the PostgreSQL container using standard pg_dump commands:

docker exec kaneo-postgres-1 pg_dump -U kaneo kaneo > backup.sql

Restore by piping the SQL file back into the container. Ensure you also back up your .env file containing AUTH_SECRET and other configuration values.

What ports need to be open for Kaneo?

By default, the web interface exposes port 5173 and the API exposes port 1337 on your host. PostgreSQL runs on port 5432 but should remain firewalled from external access unless specifically required. Update these mappings in compose.yml if they conflict with existing services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}