Paddy
1bed723363
New Updater class + "Hilfe" menubar: - "Nach Update suchen": git fetch + count of new upstream commits. - Quiet background check on start; surfaces via status bar + menu label. - Install: git merge --ff-only, pip install if requirements.txt changed, then restart via os.execv. data/ is git-ignored and untouched. - Fast-forward only; diverged history or offline -> clear message, no action. - Inert unless run from a git clone with git on PATH. Also: "Version…" menu item shows the installed commit. Verified against throwaway git repos (check / ff-update / diverged / no-op / non-clone) and via GUI build on Python 3.14 / Tk 9. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
128 lines
3.4 KiB
Markdown
128 lines
3.4 KiB
Markdown
# 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.
|