DawnsorrowandCursor
0d6b0b2f80
Session-gated MinIO save sync with AppImage GUI, CLI edit/session flow, and Gitea release helper. Co-authored-by: Cursor <[email protected]>
84 lines
2.4 KiB
Markdown
84 lines
2.4 KiB
Markdown
# SyncGames
|
||
|
||
Session-gated save sync for Steam (incl. Seamless Coop) and emulator titles across Linux PCs/laptops and Android.
|
||
|
||
**Architecture:** Path 3 — MinIO SSOT on NAS, Python agent on Linux, light Kotlin UI on Android.
|
||
**Ingress:** Cloudflare → Tunnel → NGINX → MinIO (WAN HTTPS, no VPN required).
|
||
|
||
## Safety model
|
||
|
||
1. **Pull** SSOT into the game’s native save path only at session start.
|
||
2. Play against local WIP only.
|
||
3. **Push** WIP to SSOT only at session end (history slot + live promote).
|
||
4. One **lease** per game; hash gate blocks stale WIP overwrites.
|
||
5. Per-device history keeps the last N versions (default 5) for LOPE recovery.
|
||
|
||
Never point continuous sync tools at live game save directories.
|
||
|
||
## Download (multi-device)
|
||
|
||
Repo: [git.hisora.dev/Dawnsorrow/SyncGames](https://git.hisora.dev/Dawnsorrow/SyncGames)
|
||
|
||
Grab the latest **Release** assets (AppImage / APK) — do not commit binaries into git.
|
||
|
||
```bash
|
||
# Linux
|
||
chmod +x SyncGames-*-x86_64.AppImage
|
||
./SyncGames-*-x86_64.AppImage
|
||
```
|
||
|
||
Use the **Setup** tab for endpoint/keys, **Games** to add/edit titles, **Session** for start/end/restore.
|
||
|
||
## Quick start (Linux)
|
||
|
||
### Build AppImage from source
|
||
|
||
```bash
|
||
cd agent
|
||
./packaging/build-appimage.sh
|
||
# → agent/dist/SyncGames-*-x86_64.AppImage
|
||
```
|
||
|
||
### CLI / editable install
|
||
|
||
```bash
|
||
cd agent
|
||
python -m venv .venv && source .venv/bin/activate
|
||
pip install -e ".[gui]"
|
||
|
||
syncgames-gui # thin management UI
|
||
# or: syncgames gui
|
||
|
||
cp ../config/agent.toml.example ~/.config/syncgames/agent.toml
|
||
syncgames doctor
|
||
```
|
||
|
||
## Docs
|
||
|
||
| Doc | Purpose |
|
||
|-----|---------|
|
||
| [docs/architecture.md](docs/architecture.md) | System overview |
|
||
| [docs/protocol.md](docs/protocol.md) | Shared SSOT protocol (Python ↔ Android) |
|
||
| [docs/nas-minio-cloudflare.md](docs/nas-minio-cloudflare.md) | MinIO + NGINX + Cloudflare |
|
||
| [docs/add-game.md](docs/add-game.md) | Add / remove games |
|
||
| [docs/fallback-path1.md](docs/fallback-path1.md) | Syncthing fallback |
|
||
| [docs/planning/](docs/planning/) | Planning archive |
|
||
|
||
## Layout
|
||
|
||
```
|
||
SyncGames/
|
||
agent/ Python CLI + thin GUI (+ AppImage packaging)
|
||
android/ Kotlin/Compose light UI
|
||
config/ Device + game TOML
|
||
deploy/
|
||
docker/ Docker Compose (MinIO SSOT)
|
||
nginx/ Example NGINX vhost
|
||
systemd/ User units for watchers
|
||
docs/
|
||
```
|
||
|
||
## MinIO / NAS Docker
|
||
|
||
See [deploy/docker/README.md](deploy/docker/README.md) for Compose (`MinIO` on `127.0.0.1:9000` behind your existing NGINX).
|