Deploying Kresus

Introduction

Kresus is an open source personal finance manager that helps you track, categorize, and analyze your bank transactions. Originally designed to work with French banks through the Weboob/Woob library, Kresus now supports multiple bank connection methods including OFX imports and manual transaction entry.

The application provides a clean, privacy-focused interface for managing your finances without sending data to third-party services. All your financial data stays on your own server, giving you complete control over sensitive banking information.

Key features of Kresus:

• Bank Synchronization: Automatic transaction fetching from supported banks
• Transaction Categorization: Auto-categorize transactions with customizable rules
• Budget Management: Set and track budgets by category
• Multiple Accounts: Manage checking, savings, and credit accounts
• Spending Analysis: Charts and reports for understanding spending patterns
• Duplicate Detection: Automatically identify and merge duplicate transactions
• OFX/QIF Import: Import transactions from bank exports
• Recurring Transactions: Track and predict recurring expenses
• Search and Filter: Powerful search across all transactions
• Privacy-Focused: Self-hosted with no third-party data sharing
• Multi-User Support: Separate accounts for household members
• Mobile-Friendly: Responsive design for mobile access

This guide walks through deploying Kresus on Klutch.sh using Docker, configuring the database, and connecting your bank accounts.

Why Deploy Kresus on Klutch.sh

Deploying Kresus on Klutch.sh provides several advantages for personal finance management:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kresus without complex orchestration.

Persistent Storage: Attach persistent volumes for your financial database. Your transaction history survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for protecting sensitive financial data.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your data volume and sync frequency.

Environment Variable Management: Securely store database credentials and bank connection details.

Custom Domains: Assign a custom domain for easy, secure access to your finances.

Always-On Availability: Access your financial data anytime, anywhere.

Prerequisites

Before deploying Kresus on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• Bank statements in OFX/QIF format (or supported bank credentials)
• (Optional) A custom domain for your Kresus instance

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for deploying Kresus on Klutch.sh.

Repository Structure

kresus-deploy/
├── Dockerfile
├── config.ini
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM bnjbvr/kresus:latest

# Set environment variables
ENV KRESUS_DIR=/home/user/data
ENV KRESUS_SALT=${KRESUS_SALT}
ENV KRESUS_PYTHON_EXEC=/usr/bin/python3

# Create data directory
RUN mkdir -p /home/user/data

# Set permissions
RUN chown -R user:user /home/user/data

# Expose the web interface port
EXPOSE 9876

# The base image includes the default entrypoint

Creating the Configuration File

Create config.ini for custom settings:

[kresus]
; Kresus configuration

; Data directory
datadir=/home/user/data

; Port to listen on
port=9876

; Host to bind to
host=0.0.0.0

; Secret salt for password hashing (set via environment variable)
; salt=your-secret-salt

Environment Variables Reference

Variable	Required	Default	Description
KRESUS_SALT	Yes	-	Secret salt for password hashing
KRESUS_DIR	No	/home/user/data	Data directory path
KRESUS_PORT	No	9876	Port for the web interface
KRESUS_HOST	No	0.0.0.0	Host to bind to
KRESUS_PYTHON_EXEC	No	python3	Python executable path
KRESUS_URL_PREFIX	No	/	URL prefix for reverse proxy
KRESUS_EMAIL_HOST	No	-	SMTP host for notifications
KRESUS_EMAIL_PORT	No	-	SMTP port
KRESUS_EMAIL_USER	No	-	SMTP username
KRESUS_EMAIL_PASSWORD	No	-	SMTP password

Deploying Kresus on Klutch.sh

Generate a Secret Salt

Generate a secure salt for password hashing:

openssl rand -hex 32

Save this salt securely.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.ini .dockerignore README.md
git commit -m "Initial Kresus deployment configuration"
git remote add origin https://github.com/yourusername/kresus-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “kresus” or “finance-manager”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Kresus Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 9876 (Kresus default port)

Set Environment Variables

Add the following environment variables:

Variable	Value
KRESUS_SALT	Your generated secret salt
KRESUS_DIR	/home/user/data

Attach Persistent Volumes

Add volumes for data persistence:

Mount Path	Recommended Size	Purpose
/home/user/data	10 GB	Database and transaction data

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Kresus container
• Provision an HTTPS certificate

Access Kresus

Once deployment completes, access your Kresus instance at https://your-app-name.klutch.sh.

Initial Configuration

First-Time Setup

When you first access Kresus:

1. Create your admin account
2. Set up your first bank access or import method
3. Configure categories for your transactions
4. Set up budget targets

Importing Transactions

If automatic bank sync isn’t available for your bank:

1. Export transactions from your bank’s website (OFX or QIF format)
2. Go to Settings > Import
3. Upload your bank export file
4. Map accounts and review imported transactions

Setting Up Categories

Organize your spending:

1. Navigate to Categories
2. Review default categories
3. Add custom categories for your needs
4. Set up auto-categorization rules

Creating Budgets

Track your spending goals:

1. Go to Budget section
2. Set monthly limits per category
3. Review spending vs. budget
4. Adjust as needed based on analysis

Troubleshooting Common Issues

Salt Configuration Errors

• Ensure KRESUS_SALT is set correctly
• Salt must remain consistent across deployments
• Never change salt after initial setup (will invalidate passwords)

Import Failures

• Verify file format is OFX or QIF
• Check file encoding (UTF-8 recommended)
• Try importing smaller batches

Data Not Persisting

• Verify volume is mounted correctly
• Check permissions on data directory
• Ensure KRESUS_DIR matches volume mount path

Additional Resources

• Official Kresus Website
• Kresus Documentation
• Kresus Git Repository
• Kresus Community

Conclusion

Deploying Kresus on Klutch.sh gives you a privacy-focused personal finance manager with automatic builds, persistent storage, and secure HTTPS access. Take control of your financial data without relying on third-party services.