koopa-admin-log/scripts/taler-landing/README.md

# taler-landing — generic multi-stack landing stats

One collector (`collect_bank_stats.py` + `collect-landing-stats.sh`) for any
currency / stack. **Defaults = GOA / hacktivism**; stage TESTPAYSAN uses a
profile file.

Public landing numbers (example GOA):

- https://bank.hacktivism.ch/intro/ → `stats.json`
- https://exchange.hacktivism.ch/intro/ → `stats.json`
- https://taler.hacktivism.ch/intro/ → `stats.json`

Stage TESTPAYSAN (shared bank feed on all three hosts):

- https://stage.bank.lefrancpaysan.ch/intro/stats.json  
  (same file also under stage.exchange / stage.monnaie landings)

Produced by **one host process** (user systemd timer), not three crons.

LFP stage landings (`francpaysan-admin-log`) also render **`recent_withdraws`**
and **`recent_incoming`** from this feed (amount, bank account / merchant
instance, time). QR_Taler assets on monnaies match bank-landing style
(`qr-logo.png` + blue ring); collector code stays here, HTML lives in
francpaysan-admin-log.

## Why host / user systemd

| Concern | Approach |
|--------|----------|
| **All accounts / all money** | Python full scan + tx pagination (not capped at 80 accounts) |
| **High ladder GOA** | `amount_alt` / UI alt units (Kilo-/Mega-/Peta-GOA) — tiles stay short |
| **No root cron** | `systemctl --user` as hernani + `loginctl enable-linger` |
| **Failure safety** | failed run only updates `stats-run.json`; last good `stats.json` stays |

## Install (on koopa as hernani)

```bash
cd ~/src/koopa/koopa-admin-log
./scripts/taler-landing/install-landing-stats-host.sh

# timer without login session:
sudo loginctl enable-linger hernani

# run once:
systemctl --user start taler-landing-stats.service
journalctl --user -u taler-landing-stats.service -n 50 --no-pager
systemctl --user list-timers 'taler-landing-stats*'
```

Units:

- `configs/systemd/user/taler-landing-stats.service` — oneshot collector  
- `configs/systemd/user/taler-landing-stats.timer` — every **2 minutes** after boot  

Installed paths:

| Path | Role |
|------|------|
| `~/.local/bin/collect-landing-stats.sh` | orchestrator |
| `~/.local/lib/taler-landing/*.py` | bank scan + alt enrich |
| `~/.local/state/taler-landing-stats/` | logs |
| `~/.config/systemd/user/taler-landing-stats.*` | user units |

## What the collector does

1. **Bank** — `collect_bank_stats.py`  
   - admin token → list **all** accounts  
   - for each account (except `SCAN_SKIP`, default **`exchange`**) page through **all** transactions  
   - sum credits / Taler withdraws / other debits  
   - emit `amount` + `amount_alt` / `amount_full`  
   - `podman cp` → `taler-hacktivism-bank:/var/www/bank-landing/stats.json`

2. **Exchange** — run `landing-stats-exchange.sh` inside exchange container, then **enrich** alt fields on the host and write back.

3. **Merchant** — same for merchant container.

4. **Resources (all three)** — `collect_container_resources.sh` runs
   `mem-snapshot` **inside** each podman container (not host `/proc`):
   container RSS (+ cgroup limit label), postgres/java/taler/nginx groups,
   top-10 processes, loadavg. Merged into `performance.memory` /
   `performance.loadavg` via `merge_resources.py`.

`exchange` is skipped in the bank **flow** scan so the same GOA is not counted once as customer withdraw and again as exchange credit. **Admin**, **explorer**, and every auto-account are included.

## Secrets

Preferred order:

1. `~/src/koopa/koopa-admin-secrets/koopa/host-root/taler-bank/bank-admin-password.txt`  
2. `~/.config/taler-landing/bank-*-password.txt`  
3. `podman exec taler-hacktivism-bank cat /root/bank-admin-password.txt`

Explorer password optional (shared-pool balance).

## Profiles

| File | Stack |
|------|--------|
| `profiles/goa.env` | hacktivism GOA (container publish) |
| `profiles/stage-testpaysan.env` | FrancPaysan stage; **shared** host `stats.json` |

```bash
# Stage (on stagepaysan):
STACK_PROFILE=stage-testpaysan ./scripts/taler-landing/install-landing-stats-host.sh
# or: francpaysan-admin-log/scripts/stagepaysan/install-landing-stats.sh
```

`~/.config/taler-landing/stack.env` is sourced on each run.

## Env overrides

| Env | Default | Meaning |
|-----|---------|---------|
| `BANK_URL` | `http://127.0.0.1:9012` | libeufin loopback |
| `BANK_CURRENCY` | *(auto)* | `GOA` / `TESTPAYSAN` / … |
| `SCAN_SKIP` | `exchange` | usernames excluded from flow |
| `COLLECT_BANK` / `_EXCHANGE` / `_MERCHANT` | `1` | phase switches |
| `COLLECT_RESOURCES` | `1` | container RSS/loadavg merge |
| `HOST_STATS_DIRS` | empty | space-separated host dirs for **shared** bank `stats.json` |
| `PUBLISH_PODMAN` | `1` | also `podman cp` into container landings |
| `TX_PAGE` | `500` | transactions page size |
| `MAX_TX_PAGES` | `0` | `0` = unlimited pages / account |
| `ACCOUNTS_DELTA` | `-10000` | account list window |
| `ADMIN_LOG` | `%h/src/koopa/koopa-admin-log` | refresh in-container scripts |
| `STATS_SOURCE_LABEL` | `host collect_bank_stats.py` | `stats.source` field |

## UI alt names

`configs/shared/goa-amount.js` formats large amounts as e.g. `1.23 Mega-GOA` (tooltip = full `GOA:…`). Landings load it as `/intro/goa-amount.js` (deploy via `deploy-landings.sh`).

## Legacy in-container bank cron

`scripts/taler-bank/landing-stats.sh` remains a **fallback** inside the bank container. Once the hernani timer is healthy, disable the old in-container minutely cron to avoid races:

```bash
podman exec taler-hacktivism-bank crontab -l   # inspect
# remove landing-stats.sh line if present
```

## Manual run

```bash
~/.local/bin/collect-landing-stats.sh
# or from checkout:
./scripts/taler-landing/collect-landing-stats.sh

curl -sS https://bank.hacktivism.ch/intro/stats.json | python3 -m json.tool | head
```

## Landing content version (per site)

Each landing footer shows **Bank|Exchange|Merchant landing vN** + last content
change + linkified git commit. Versions are **independent** (start **v42** each).

- State: `configs/shared/landing-version.json` → `sites.bank|exchange|merchant`
- After editing one site (example bank):
  ```bash
  ./scripts/taler-landing/stamp-landing-version.sh --bump bank
  git add configs/ && git commit -m "landing(bank): …"
  ./scripts/taler-landing/stamp-landing-version.sh bank
  git add configs/ && git commit --amend --no-edit   # optional pin
  ```
- Re-stamp all without bump: `./scripts/taler-landing/stamp-landing-version.sh --all`