drk-blutspende-orte/docs/setup.md

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.

Install (Linux Mint)

The target user's account is a Standard account (no sudo). Install is therefore two steps: one system step by an admin, then the rest by the user.

Step 1 — system packages (admin account, once)

python3-tk, python3-venv and git are system packages. From an account with admin rights (Patrick's):

cd /path/to/DRK_Blutspende_Orte
./install-system.sh          # sudo apt install python3-tk python3-venv git

Skip this if those three are already present.

Step 2 — the app (user account, no sudo)

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 needs no sudo once step 1 is done. It:

1. checks the system packages are there (if not, and the account does have sudo, it installs them; otherwise it prints the exact install-system.sh line an admin must run and stops),
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. The clone lives in the user's home so she can update it without sudo.

If you do both steps yourself in one go: run ./install-system.sh as admin, then su - <heraccount> -c '~/Apps/DRK_Blutspende_Orte/install.sh' (or just log in as her and run step 2).

What the pieces are

File	Purpose
install-system.sh	admin, once: apt install python3-tk python3-venv git.
install.sh	user, no sudo: venv + deps + menu entry. 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

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.

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

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.