Skip to content

Deployment EN

Jump to bottom
github-actions[bot] edited this page May 30, 2026 · 6 revisions

Spendif.ai — Deployment Guide

This document describes how to install, configure and update Spendif.ai. For backup, restore and database management → database.en.md. For installation on native Mac, Linux with Ollama and Windows with llama.cpp → installazione.en.md.

Table of contents

  1. Quick installation (one-liner Docker)
  2. Docker Compose installation from repository
  3. Native installation (development / Mac) 3b. Native desktop app (macOS / Windows / Linux)
  4. .env configuration
  5. Updating the application
  6. Docker operational commands
  7. Troubleshooting
  8. Uninstall

Docker concepts for beginners

Concept Analogy What it means in practice
Image Cooking recipe The package containing all the code and dependencies
Container Cooked dish The running app, created from the image
Volume External notebook The persistent folder where the database lives — survives even if the container is deleted

What does NOT delete your data:

  • docker compose down ✅ safe
  • docker compose up -d --build ✅ safe (rebuilds the image, data intact)

What DELETES data:

  • docker compose down -v ⚠️ deletes the volumes — use only for a full reset

1 — Quick installation (one-liner Docker)

The only prerequisite is Docker Desktop installed and running.

Mac / Linux:

curl -fsSL https://raw.githubusercontent.com/drake69/spendifai/main/installer/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/drake69/spendifai/main/installer/install.ps1 | iex

The script creates the ~/spendifai/ folder, downloads the image from GitHub Container Registry, starts the container and opens the browser at http://localhost:8501 automatically.

Local AI included (optional): the script asks whether to install Ollama with the gemma3:12b model — downloaded automatically in the background on first start (~8 GB, ~10–15 minutes). Alternatively you can configure an external API key (OpenAI/Anthropic) from the ⚙️ Settings page.

Update: docker compose --project-directory ~/spendifai pull && docker compose --project-directory ~/spendifai up -d

Uninstall: curl -fsSL https://raw.githubusercontent.com/drake69/spendifai/main/installer/uninstall.sh | bash

2 — Docker Compose installation from repository

Suitable for those who want to modify the code or configure LLM profiles (Ollama, llama.cpp).

2.1 — Clone the repository

git clone https://github.com/drake69/spendif-ai.git spendifai
cd spendifai

2.2 — Configure the environment

cp .env.example .env

2.3 — Build and start

docker compose up -d --build
  • --build forces the image to be rebuilt (required on first launch or after code updates)
  • -d starts in the background

The app is available at http://localhost:8501

The REST API is available at http://localhost:8000 · Interactive docs: http://localhost:8000/docs

2.4 — With local LLM (optional)

# Ollama (Linux / server with GPU)
docker compose --profile ollama up -d

# llama.cpp (Windows / CPU)
docker compose --profile llama-cpp up -d

For complete LLM backend configuration → installazione.en.md.

3 — Native installation (development / Mac)

Prerequisites

Tool Minimum version
Python 3.13
uv any — curl -Ls https://astral.sh/uv/install.sh | sh

Steps

git clone https://github.com/drake69/spendif-ai.git spendifai
cd spendifai
uv sync
cp .env.example .env

# Startup script (recommended)
./start.sh          # UI only (default)
./start.sh api      # REST API only
./start.sh all      # UI + API

# On Windows
start.bat           # same options: ui | api | all

# Or manually
uv run streamlit run app.py

The app is available at http://localhost:8501

To also start the REST API manually:

uv run uvicorn api.main:app --host 0.0.0.0 --port 8000

The ledger.db database is created automatically in the project folder on first launch.

3b — Native desktop app (macOS / Windows / Linux)

Spendif.ai can run as a native desktop application — a native window (pywebview) embedding the Streamlit server. No Terminal, no external browser.

Features

  • Native window using WebKit (macOS), Edge WebView2 (Windows) or GTK/WebKit (Linux)
  • Automatic download of the recommended LLM model for your hardware (1–7 GB depending on RAM)
  • Zero-touch llama.cpp configuration — everything works on first launch with no user intervention
  • Splash screen with progress bar during startup

Installation by platform

Platform Command
macOS (installer) bash packaging/macos/install.sh
macOS (Homebrew) brew tap drake69/spendifai && brew install --cask spendifai
Windows Right-click install.ps1 → "Run with PowerShell"
Windows (winget) winget install SpendifAi.SpendifAi
Ubuntu/Debian (.deb) bash packaging/linux/build-deb.sh && sudo apt install ./build/spendifai_*.deb
Ubuntu/Debian (script) bash packaging/linux/install-debian.sh
Red Hat/Fedora (.rpm) bash packaging/linux/build-rpm.sh && sudo dnf install ./build/spendifai-*.rpm
Red Hat/Fedora (script) bash packaging/linux/install-redhat.sh

Developer launch

uv sync --extra desktop
uv run python -m desktop.launcher

What the installer does

  1. Installs Python, uv and system dependencies (pywebview requires WebKit/GTK on Linux)
  2. Clones the repository and creates the virtualenv with uv sync --extra desktop
  3. Detects hardware (RAM, GPU) and downloads the recommended GGUF model from HuggingFace
  4. Configures .env with LLM_BACKEND=local_llama_cpp and the model path
  5. Creates a launcher (.app on macOS, shortcut on Windows, .desktop on Linux)

User data: the database and models live in ~/.spendifai/ (macOS/Linux) or %APPDATA%\Spendif.ai\ (Windows), separate from the code. Reinstalling the code does not touch your data.

4 — .env configuration

The .env file contains only two parameters. All other settings (LLM, API keys, date format, language, etc.) are configured from the interface on the ⚙️ Settings page.

cp .env.example .env
Parameter Description Default
SPENDIFAI_DB SQLite database URI sqlite:///ledger.db
TAXONOMY_PATH Path to the YAML file used as initial seed for categories. At runtime the taxonomy lives in the DB (taxonomy_category / taxonomy_subcategory) and is managed from the UI. The YAML is read only on first start or when changing language. taxonomy.yaml 
SPENDIFAI_DB=sqlite:///ledger.db
TAXONOMY_PATH=taxonomy.yaml

# Only for the llama-cpp profile:
# LLAMA_MODEL=gemma-3-4b-it-Q4_K_M.gguf

Never add .env to git — verify that .gitignore contains the line .env.

5 — Updating the application

One-liner Docker

docker compose --project-directory ~/spendifai pull
docker compose --project-directory ~/spendifai up -d

Docker Compose from repository

git pull origin main
docker compose down
docker compose up -d --build

Native

git pull origin main
uv sync
pkill -f "streamlit run app.py"
uv run streamlit run app.py

Database migrations are applied automatically on startup — no manual intervention is required.

6 — Docker operational commands

# Container status
docker compose ps

# Real-time logs
docker compose logs -f spendifai

# Healthcheck
docker inspect spendifai_app --format='{{.State.Health.Status}}'

# Stop (data intact)
docker compose down

# Stop + remove orphan containers (data intact)
docker compose down --remove-orphans

# ⚠️  Full reset including volumes (DATA LOSS)
docker compose down -v

For the one-liner installation, add --project-directory ~/spendifai to every command, e.g. docker compose --project-directory ~/spendifai logs -f.

7 — Troubleshooting

The app does not start / port 8501 is busy

# Check what is using the port
lsof -i :8501

# Native
pkill -f "streamlit run app.py"

# Docker
docker compose down && docker compose up -d

The Docker container keeps restarting

docker compose logs --tail=50 spendifai

Common causes:

  • .env missing or incorrect values
  • Volume not mounted correctly
  • Port 8501 already in use

Insufficient memory for Ollama

The gemma3:12b model requires ~8 GB of RAM. Change the model from the ⚙️ Settings page:

Model Required RAM
gemma3:12b ~8 GB
qwen2.5:7b ~5 GB
llama3.2:3b ~3 GB

Database issues

Errors such as database is locked, file corruption, restore from backup → database.en.md.

8 — Uninstall

The uninstall scripts interactively remove all Spendif.ai components. No data is deleted without explicit confirmation.

Mac / Linux:

curl -fsSL https://raw.githubusercontent.com/drake69/spendifai/main/installer/uninstall.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/drake69/spendifai/main/installer/uninstall.ps1 | iex

The script asks separately for each component:

What Detail
Transaction database Volumes spendifai_data and spendifai_logs
Ollama models Volume ollama_models (~8 GB)
llama.cpp + models/ folder llama.cpp:server image + GGUF files
Docker images ghcr.io/drake69/spendif-ai + ollama/ollama (~500 MB–1 GB)
Installation folder ~/spendifai/ (or SPENDIFAI_INSTALL_DIR)
Docker Desktop removal guide Step-by-step guide for macOS / Linux / Windows

Uninstalling the native desktop app

For native installations (non-Docker), each platform has its own uninstaller:

Channel Command
macOS (script) bash packaging/macos/uninstall.sh
macOS (Homebrew) brew uninstall --cask spendifai (to also remove data: --zap)
Windows (script) .\packaging\windows\uninstall.ps1 (supports -Silent)
Windows (Apps & features) Settings → Apps → Spendif.ai → Uninstall
Windows (winget) winget uninstall SpendifAi.SpendifAi
Ubuntu/Debian sudo apt remove spendifai
Fedora/RHEL sudo dnf remove spendifai
Linux (script) bash packaging/linux/uninstall.sh

All uninstallers ask for interactive confirmation before removing user data (~/.spendifai/). AI models are asked separately (they can be 1–7 GB).

Data preserved: uninstalling the code (via package manager or script) does not remove the database and models in ~/.spendifai/. For a full cleanup, use the uninstall script or manually remove ~/.spendifai/.

Clone this wiki locally