# Setup & running

Target machine: **Linux Mint laptop**, single non-technical user. The goal is
that day-to-day use is a **double-click**, with the terminal only needed once
during install.

## 1. System packages

Tkinter is not bundled with the system Python on Mint and must be installed
separately. `git` is needed for the in-app updater:

```bash
sudo apt update
sudo apt install python3-tk python3-venv python3-pip git
```

## 2. Get the code

**Clone it** (don't download a zip) – the in-app "Nach Update suchen" only works
from a git clone:

```bash
mkdir -p ~/Apps && cd ~/Apps
git clone <repo-url> DRK_Blutspende_Orte
```

Put it somewhere stable, e.g. `~/Apps/DRK_Blutspende_Orte`.

## 3. Create a virtual environment and install dependencies

```bash
cd ~/Apps/DRK_Blutspende_Orte
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

`requirements.txt`:

```
ttkbootstrap==1.10.1
geopy>=2.4.1
folium>=0.17.0
pandas>=2.2.0
```

> Only `ttkbootstrap` is pinned exactly. For a machine you hand to someone else,
> consider pinning all four (see [improvements.md](improvements.md#5-packaging--distribution)).

## 4. Run it

```bash
.venv/bin/python app.py
```

The window should open. `data/orte.csv` is created automatically on first run if
it is missing.

## 5. Make it a double-click launcher

### Launcher script

Create `run.sh` in the project root:

```bash
#!/usr/bin/env bash
cd "$(dirname "$0")"
exec .venv/bin/python app.py
```

```bash
chmod +x run.sh
```

### Desktop entry

Create `~/.local/share/applications/drk-blutspende-orte.desktop`:

```ini
[Desktop Entry]
Type=Application
Name=DRK Blutspende – Arbeitsorte
Comment=Einsatzorte protokollieren und auf der Karte anzeigen
Exec=/home/USER/Apps/DRK_Blutspende_Orte/run.sh
Icon=/home/USER/Apps/DRK_Blutspende_Orte/data/icon.png
Terminal=false
Categories=Utility;
```

Replace `USER` with the real username. The app writes a simple red-cross
`data/icon.png` on first run; drop in the real DRK logo at that path if you have
one. The entry then shows up in the Mint menu and can be pinned to the panel or
the desktop.

## Python / Tk version

Python 3.9+ is fine (the code uses `from __future__ import annotations`). The
system Python on current Mint releases is well above that.

`ttkbootstrap` needs **Tk 8.6 or newer**. Linux Mint's `python3-tk` provides
that. The macOS CommandLineTools Python used during development ships Tk 8.5 and
**cannot run the GUI** — see [dev-notes.md](dev-notes.md).

## Updating

**From inside the app:** menu **Hilfe ▸ Nach Update suchen**. The app also
checks quietly on start and offers the update if there is one. It fast-forwards
to the server version, reinstalls dependencies if `requirements.txt` changed,
and restarts itself. `data/` is never touched.

For this to work the app must run from a **git clone** (step 2) whose `.venv`
was made with the same Python it runs on, and `git` must be installed. The
updater only ever fast-forwards – if the local copy has been changed by hand it
refuses and says to get in touch.

**Manually** (equivalent):

```bash
cd ~/Apps/DRK_Blutspende_Orte
git pull --ff-only
.venv/bin/pip install -r requirements.txt
```

## Data location

All state is in `data/orte.csv` next to `app.py`. To back up the app, copy that
one file (plus `data/backups/` if you want the history). To move to a new
laptop, clone the repo again and redo steps 1 & 3; copy `data/orte.csv` across.