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

> Deploy Kaneo as a service using Docker Compose. Orchestrate PostgreSQL, Hono API, and React frontend in a unified container network with auto-restart for seamless operation.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) file provided in the `usekaneo/kaneo` repository.

## Architecture Overview

Kaneo consists of three containerized services defined in [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/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:

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) in the repository root.

## Starting the Service

Launch Kaneo as a background service using Docker Compose:

```bash
docker compose up -d

```

The [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/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:

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vite.config.ts) and [`apps/web/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`:

```ini
[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:

```bash
sudo systemctl enable kaneo
sudo systemctl start kaneo

```

## Summary

- Kaneo runs as a service via **Docker Compose** defined in [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/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:

```bash
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:

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) if they conflict with existing services.