Files
cardputerzero-sync/docs/usage-and-operations.md

181 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Usage, Configuration & Operations Guide
---
## 1. Mac Receiver Operations (`cp0-mac-sync`)
Manage where photos land, check Tailscale/receiver health, view logs, and control the macOS background service using `cp0-mac-sync`.
### Command Reference
| Command | Description |
|---|---|
| `cp0-mac-sync status` | Show `LaunchAgent` state (`com.cardputerzero.photosync`), live HTTP `/health` check (`0.0.0.0:<port>`), destination directory, Tailscale CLI status, and active config path. |
| `cp0-mac-sync set-dir <path>` | Create `<path>` if needed and update `dest_root` in `config.json`. Picked up **automatically on the next upload** (no daemon restart required). |
| `cp0-mac-sync set-port <1-65535>` | Update `listen_port` in `config.json` and restart the `LaunchAgent` if installed (`launchctl kickstart -k`). Default: `8765`. |
| `cp0-mac-sync logs [-n LINES] [-f]` | Print recent lines (`-n 100` default) or tail live receiver logs (`~/Library/Logs/cp0-mac-sync.log`). |
| `cp0-mac-sync install-service` | Write `~/Library/LaunchAgents/com.cardputerzero.photosync.plist` and load/enable the service (`gui/<uid>/com.cardputerzero.photosync`). |
| `cp0-mac-sync uninstall-service` | Stop and unload the `LaunchAgent` and remove its `.plist`. |
### Running `cp0-mac-receiver` Manually (Foreground / Debug)
For foreground debugging without `launchd`:
```bash
./mac-receiver/bin/cp0-mac-receiver --config ~/.config/cp0-mac-sync/config.json --log-file /tmp/cp0-rec.log
```
### Destination Layout & Collision Safety
Uploaded files are written into:
```text
<dest_root>/<folder_label>/<rel_path>
```
For example, if `dest_root` is `~/Pictures/CardputerZero` and CardputerZero watches `/home/pi/Pictures/DCIM/Camera` (label `Camera`):
- `IMG_0042.JPG` → `~/Pictures/CardputerZero/Camera/IMG_0042.JPG`
- `2026-11/IMG_0043.JPG` → `~/Pictures/CardputerZero/Camera/2026-11/IMG_0043.JPG`
Collision & safety guarantees (`mac-receiver/cp0_mac_receiver/server.py`):
- **Atomic staging:** Body streams to a `.cp0-*.part` temp file, hashes SHA-256, validates `X-CP0-SHA256`, applies `os.utime` (`X-CP0-Mtime`) when valid, `fsync`s, and atomically replaces into place (`60s` socket timeout cleans up `.part` files if a connection drops mid-upload).
- **Idempotent duplicate:** If a file already exists at the destination with the **same SHA-256**, it returns `200 OK` (`status: "duplicate"`) without creating extra copies.
- **Collision rename:** If a file exists at the destination with a **different SHA-256**, it is saved alongside it as `<stem>_<YYYYMMDD_HHMMSS>_<sha8><ext>` (never overwriting).
- **Tailscale IP allowlist (`tailscale_only: true`):** Only accepts HTTP requests from Tailscale CGNAT (`100.64.0.0/10`), Tailscale IPv6 (`fd7a:115c:a1e0::/48`), or loopback (`127.0.0.0/8`, `::1/128`); all other client IPs receive `403 Forbidden`.
- **Notifications:** When `notify_on_batch: true`, debounced macOS Notification Center alerts (`2s` debounce window) summarize batch uploads (e.g., `"Synced 5 photos from CardputerZero"`).
---
## 2. CardputerZero Companion UI (`cp0-sync-ui`)
Launch **Photo Sync** from `APPLaunch` or run `cp0-sync-ui` from a shell. The UI refreshes daemon state every `1000 ms` over the daemon's Unix domain socket (falling back cleanly to read-only SQLite + `config.json` display when `cp0-syncd` is stopped).
### Top-Bar Status Pills
| Badge | Meaning |
|---|---|
| **`Mac Online`** | Daemon running, target Mac configured, and last upload/probe succeeded. |
| **`Syncing`** | Daemon is actively streaming queued photos over Tailscale. |
| **`Mac Sleeping`** | Target Mac unreachable; queued photos waiting safely until next wake-probe or `[Enter]`. |
| **`No Target`** | Daemon running, no Mac host configured yet — press **`C`** on `1 Status`. |
| **`Daemon Off`** | `cp0-syncd` IPC socket unreachable (shows read-only cached counts/logs below if `state.db` exists). |
### Tabs & Workflows
#### Tab `1 Status`
Displays two Bento summary tiles (**Pending Queue** file count + total bytes, **Total Synced** count + 1-way verified status), your **Target** host (`host:port`) with retry countdown/uploading/cached indicator, destination directory on the Mac, and last synced filename or error summary.
- Press **`C`** to open the **Target Mac Picker**:
- Automatically queries `tailscale status --json` and sorts **online macOS peers first**.
- Navigate with `j`/`k` or `Up`/`Down`, press **`Enter`** to select `<peer-ip-or-dns>:8765`.
- Press **`T`** inside the picker to manually enter `<host>` or `<host>:<port>` (or IPv6 `[host]:port`).
#### Tab `2 Folders`
Lists all watched directories with badges (`N queued`, `synced`, `N err`, or `! missing`). On first run, `cp0-syncd` creates `/home/pi/Pictures/DCIM/Camera` (label `Camera`) automatically.
- **Add folder (`A`):** Opens the on-device filesystem directory picker starting at your home directory (`~`):
- `j`/`k` or `Up`/`Down`: move highlight
- `Enter`: drill down into highlighted subdirectory
- `Backspace`: go up to parent directory
- `Space`: select & add the highlighted directory
- `.`: select & add the directory you are currently inside
- `T`: switch to manual path typing (supports `~/...` expansion)
- Nested or overlapping watched directories (parent or child of an existing watched folder) are rejected cleanly with an error toast to avoid double-uploading; duplicate base folder names (e.g., two `Camera` directories) automatically get unique labels (`Camera`, `Camera_2`, ...).
- **Remove folder (`D` or `Delete`):** Opens confirmation modal **`[Y] Confirm / [N] Cancel`**. Removing a watched folder stops watching it and purges `PENDING`/`UPLOADING` queue items, **never deleting photos on disk** and retaining historical `SYNCED` dedup records so re-adding the folder later won't re-upload old files.
#### Tab `3 Logs`
Displays timestamped `INFO`, `WARN`, and `ERROR` entries from SQLite (`state.db` retains the most recent 500 log rows).
- `j`/`k` or `Up`/`Down`: scroll through recent log rows.
- **`R`:** Reset all **`FAILED`** rows back to `PENDING` and trigger an immediate sync/wake probe.
#### Theme Toggle (`T`) & Exit (`Esc` / `Q`)
- Press **`T`** on any main tab (with no modal open) to toggle live between **Zinc Dark** (`#09090b`) and **Zinc Light** (`#fafafa`). The choice is saved to `config.json` via `cp0-syncd`.
- Press **`Esc`** or **`Q`** on main tabs to exit `cp0-sync-ui` cleanly (leaving `cp0-syncd` running in the background) and return to `APPLaunch`.
---
## 3. Daemon CLI & Runtime Behavior (`cp0-syncd`)
### `cp0-syncd` CLI Flags
```bash
cp0-syncd [--config PATH] [--db PATH] [--sock PATH] [--verbose]
```
### File Filtering & Queue Lifecycle
- **Watched media extensions (`DaemonConfig.extensions`):** `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.bmp`, `.dng`, `.raw`, `.mp4`, `.mov` (case-insensitive).
- **Ignored names:** Prefixes `.` or `~` (`DEFAULT_IGNORE_PREFIXES`), suffixes `.part`, `.tmp`, `.crdownload` (`DEFAULT_IGNORE_SUFFIXES`), and **0-byte files** (logged once as `WARN` without enqueueing).
- **Watch engine:** On Linux, uses native `ctypes` `inotify` (`IN_CLOSE_WRITE | IN_MOVED_TO | IN_CREATE | IN_DELETE_SELF | IN_MOVE_SELF`) plus `IN_ONLYDIR` ancestor watches so removable SD card mounts are detected automatically; falls back to periodic directory polling on non-Linux hosts.
- **Wake-probe backoff:** When a Mac sleeps or refuses connections, `Uploader` pauses uploads, logs cleanly, probes `GET /health` (`3s` timeout) on backoff `(5s → 10s → 20s → 40s → 60s max)` or wakes immediately on new captured photos or **`Enter`** in the UI.
- **HTTP failure triage:** Network errors, `403`, `408`, and `5xx` pause the queue and retry once the Mac recovers; `400`, `413`, and `422` (and missing local files) mark only that single file `FAILED` so later photos keep flowing.
- **Crash recovery:** On startup, any rows left in `UPLOADING` state from an unexpected power loss automatically reset to `PENDING` before scanning begins.
---
## 4. Configuration Files & Environment Variables
### On Mac
| Item | Default Path | Override Env Var |
|---|---|---|
| Config JSON | `~/.config/cp0-mac-sync/config.json` | `CP0_MAC_CONFIG` |
| Rotating Logs | `~/Library/Logs/cp0-mac-sync.log` *(5 MB × 2 backups)* | — |
| LaunchAgent | `~/Library/LaunchAgents/com.cardputerzero.photosync.plist` | — |
| Synced Photos | `~/Pictures/CardputerZero/<folder_label>/...` | *(via `cp0-mac-sync set-dir`)* |
**Mac `config.json` schema (`MacConfig`):**
```json
{
"dest_root": "/Users/you/Pictures/CardputerZero",
"listen_host": "0.0.0.0",
"listen_port": 8765,
"notify_on_batch": true,
"tailscale_only": true
}
```
### On CardputerZero
| Item | Default Path | Override Env Var |
|---|---|---|
| Config JSON | `~/.config/cp0-sync/config.json` | `CP0_SYNC_CONFIG` |
| SQLite WAL DB | `~/.local/share/cp0-sync/state.db` | `CP0_SYNC_DB` |
| Unix IPC Socket | `$XDG_RUNTIME_DIR/cp0-sync.sock` (fallback `/tmp/cp0-sync.sock`) | `CP0_SYNC_SOCK` |
| Sans / Mono Fonts | `/usr/share/cp0-sync/fonts/` → system fonts → 5×7 fallback | `CP0_FONT_SANS`, `CP0_FONT_MONO` |
| Framebuffer (`device` build) | `/dev/fb0` | `CP0_FB_DEVICE` |
| Keyboard `evdev` (`device` build) | Auto-scans `/dev/input/event*` for `EV_KEY` | `CP0_EVDEV_DEVICE` |
---
## 5. Troubleshooting
### UI displays **`Daemon Off`**
Check whether the background `systemd --user` service is running on CardputerZero:
```bash
systemctl --user status cp0-syncd.service
journalctl --user -u cp0-syncd.service -n 50 --no-pager
```
Restart it if needed:
```bash
systemctl --user restart cp0-syncd.service
```
### Status stays on **`Mac Sleeping`** while the Mac is awake
1. On Mac, verify the receiver is running and listening:
```bash
cp0-mac-sync status
```
2. Verify macOS Firewall / Little Snitch isn't blocking incoming connections to Python on TCP port `8765`.
3. From CardputerZero over SSH, test reachability over Tailscale:
```bash
curl -i http://<mac-tailscale-ip-or-magicdns>:8765/health
```
A healthy response returns HTTP `200` with `{"ok": true, "version": "1.0.0", "dest_root": "..."}`. If you get `403`, confirm traffic is traveling over Tailscale (`100.64.0.0/10`) rather than an unallowed LAN interface.
### One photo shows **`FAILED`** in Logs
Open **`3 Logs`** in `cp0-sync-ui` to view the error reason (e.g., permission denied, missing source file, destination path conflict), resolve the issue, and press **`R`** to re-queue all `FAILED` entries.
### Re-uploading previously synced photos
Because one-way sync tracks `(folder_id, rel_path, sha256)` in `state.db` so deleted files on your Mac aren't re-copied, intentionally re-syncing everything requires resetting `state.db`:
```bash
systemctl --user stop cp0-syncd.service
rm ~/.local/share/cp0-sync/state.db*
systemctl --user start cp0-syncd.service
```