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

```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.