Paddy
37c9642877
Existing app (single-file Tkinter/ttkbootstrap desktop tool for logging blood-drive work assignments and mapping them) plus the first round of improvements: - Data safety: atomic CSV writes (tmp + fsync + os.replace), rotating backups in data/backups/ (startup + before every change, keep 20), fallback to empty/backup on missing/empty/corrupt orte.csv. - Geocoder robustness: per-item try/except so the worker thread survives failures; GeocodingUnavailable + one-time "service unreachable" dialog. - Input: DateEntry calendar picker with parse_date() validation; manual lat/lon fields in the edit dialog; Tab 2 highlights/filters rows without coordinates and adds a right-click "Koordinaten suchen". - Logging to data/app.log; shared autocomplete helpers; config constants; map fit_bounds. docs/ describes current state, architecture, data model, setup (Linux Mint), and the full improvement roadmap. data/orte.csv is gitignored for now. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
106 lines
2.5 KiB
Markdown
106 lines
2.5 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:
|
||
|
||
```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.
|