Installation Guide¶

This guide walks you through installing and running Kanso using Docker (recommended) or local development setup.

Prerequisites¶

Docker (Recommended)Local Development

Docker and Docker Compose
Modern web browser (Chrome, Firefox, Safari, Edge)

Python 3.13+
uv package manager (install guide)
Modern web browser

Quick Start with Docker¶

No repository clone needed! Use the pre-built Docker image.

Step 1: Download Docker Compose File¶

# Create a directory for Kanso
mkdir kanso && cd kanso

# Download the production compose file
curl -o docker-compose.yml https://raw.githubusercontent.com/dstmrk/kanso/main/docker-compose.yml

Or create docker-compose.yml manually:

services:
  kanso:
    image: ghcr.io/dstmrk/kanso:latest
    ports:
      - "9525:9525"  # Change host port if needed (e.g., "8080:9525")
    environment:
      - APP_ENV=prod
    volumes:
      - ./kanso-data:/app/data
    restart: unless-stopped

Step 2: Start Kanso¶

docker compose up -d

This will:

Pull the latest Kanso Docker image
Start the application on port 9525
Create a persistent volume for data storage

Step 3: Access the Application¶

Open your browser and navigate to:

http://localhost:9525

You'll see the onboarding wizard on first launch.

Before Starting the Wizard

Make sure you have ready:

Google Sheets service account JSON - See Google Sheets Setup
Your Google Sheet URL - The spreadsheet where your financial data is stored

Having these ready ensures a smooth onboarding experience!

Optional Configuration¶

The application uses default settings from .env.prod (embedded in the image).

To override defaults, add environment variables in docker-compose.yml:

environment:
  - APP_ENV=prod              # Required - loads .env.prod defaults
  - LOG_LEVEL=INFO            # Override: Change log verbosity
  - CACHE_TTL_SECONDS=3600    # Override: Cache duration (seconds)
  - ROOT_PATH=/kanso          # Override: Reverse proxy path prefix

To change the port, modify the port mapping (not environment variables):

ports:
  - "8080:9525"  # Access on http://localhost:8080

Local Development Setup¶

Step 1: Install Dependencies¶

# Clone repository
git clone https://github.com/dstmrk/kanso.git
cd kanso

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

Step 2: Run the Application¶

uv run main.py

The application will start on http://localhost:9525 with development settings (debug mode, hot-reload enabled).

Step 3: Run Tests (Optional)¶

# Run unit tests
uv run pytest tests/unit/ -v

# Run E2E tests (requires Playwright)
uv run playwright install chromium
uv run pytest tests/e2e/ -v

First-Time Setup¶

When you first access Kanso, you'll see the onboarding wizard:

Welcome Screen - Introduction to Kanso
Storage Setup - Configure Google Sheets credentials (service account JSON and sheet URL)

After completing onboarding, you'll be redirected to the dashboard.

Google Sheets Required

Kanso uses Google Sheets as its data backend. This gives you the flexibility to edit your financial data from any device.

Next Steps¶

Google Sheets Setup - Prepare your financial data
Configuration Guide - Customize Kanso settings
Architecture Overview - Understand how Kanso works

Troubleshooting¶

Port Already in Use¶

If port 9525 is already taken on your host machine, change the host port (left side) in docker-compose.yml:

ports:
  - "8080:9525"  # Access on http://localhost:8080 instead

The container always uses port 9525 internally.

Docker Compose Issues¶

Check logs for errors:

docker compose logs -f kanso

Rebuild the image:

docker compose build --no-cache
docker compose up -d

Permission Errors¶

Ensure the data directory is writable:

mkdir -p ./kanso-data
chmod 755 ./kanso-data

Browser Storage Issues¶

Clear browser storage and cookies for localhost:9525 if you see authentication issues.

Updating Kanso¶

Docker¶

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d

Local Development¶

# Pull latest changes
git pull origin main

# Update dependencies
uv sync

# Restart application
uv run python main.py

Uninstalling¶

Docker¶

# Stop and remove containers
docker compose down

# Remove volumes (⚠️ deletes all data)
docker compose down -v

# Remove downloaded image
docker rmi ghcr.io/dstmrk/kanso:latest

Local Development¶

# Remove virtual environment
rm -rf .venv

# Remove data directory
rm -rf ./kanso-data

Data Backup

Before uninstalling, export your data from Google Sheets or backup the kanso-data directory.