# Setup & running

Target machine: **Linux Mint laptop**, single non-technical user. Day-to-day use
is a **double-click from the menu**; the terminal is needed once, for install.

## Quick install (Linux Mint)

```bash
mkdir -p ~/Apps && cd ~/Apps
git clone https://git.plutodev.de/Paddy/drk-blutspende-orte DRK_Blutspende_Orte
cd DRK_Blutspende_Orte
./install.sh
```

`install.sh` does everything:

1. `sudo apt install python3-tk python3-venv python3-pip git` (asks for the
   password),
2. creates `.venv` and installs the pinned `requirements.txt`,
3. writes `~/.local/share/applications/drk-blutspende-orte.desktop` with the
   correct absolute paths and the bundled `icon.png`.

After it finishes, **"DRK Blutspende – Arbeitsorte"** is in the application menu
(log out/in once if it doesn't show immediately). First manual test: `./run.sh`.

> Clone it — don't download a zip. The in-app updater and `run.sh` both rely on
> it being a real git checkout.

## What the pieces are

| File | Purpose |
|------|---------|
| `install.sh` | one-time setup (above). Safe to re-run. |
| `run.sh` | launches the app from `.venv`; the `.desktop` entry calls this. |
| `icon.png` | bundled launcher/window icon (red cross). Replace with the real DRK logo if wanted. |
| `requirements.txt` | fully pinned, tested on Python 3.12. |

## Running manually

```bash
cd ~/Apps/DRK_Blutspende_Orte
./run.sh                 # or: .venv/bin/python app.py
```

`data/orte.csv` is created automatically on first run if missing.

## Python / Tk version

Python 3.10–3.12 (Mint's `python3`). `ttkbootstrap` needs **Tk 8.6+**, which
Mint's `python3-tk` provides. The macOS CommandLineTools Python 3.9 ships Tk 8.5
and can't run the GUI — for dev on macOS use a Homebrew Python, see
[dev-notes.md](dev-notes.md).

## Updating

**From inside the app:** menu **Hilfe ▸ Nach Update suchen**. It 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. The updater only fast-forwards — if
the local copy was hand-edited 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
```

Publishing an update, from the dev machine: `git push` to
`https://git.plutodev.de/Paddy/drk-blutspende-orte` (branch `main`).

## Data location & backup

All state is in `data/` next to `app.py`:

- `orte.csv` — the data (git-ignored).
- `backups/` — automatic timestamped copies, newest 20 kept.
- `app.log`, `window.json`, `icon.png` (runtime fallback) — git-ignored.

To back up: copy `data/orte.csv` (and `data/backups/` for history). To move to a
new laptop: clone the repo, run `./install.sh`, copy `data/orte.csv` across.