Paddy
5b85596a46
The target laptop account has no sudo. install.sh now runs without root once the system packages exist; if they're missing and the account can't sudo it prints the exact command and stops. New install-system.sh holds the one-time "sudo apt install python3-tk python3-venv git" for an admin account. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
107 lines
3.8 KiB
Markdown
107 lines
3.8 KiB
Markdown
# 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):
|
||
|
||
```bash
|
||
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)
|
||
|
||
```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` 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
|
||
|
||
```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.
|