# 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:

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

## 2. Get the code

Put the project folder 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/icon.png
Terminal=false
Categories=Utility;
```

Replace `USER` with the real username. Add any PNG as `icon.png` (the DRK logo
works well). 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

```bash
cd ~/Apps/DRK_Blutspende_Orte
git pull            # once the project is in git
.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. To move to a new laptop, copy the whole folder and redo steps 1 & 3.