GPB

GPB is a self-hosted Google Photos backup control plane. Connectors discover media, a canonical pipeline applies quota and strict destination dedup, and the system backs it up through a capable GPB Sync device or the gotohp server lane.

Native apps use one v5 peer identity with any combination of SOURCE, GOOGLE_EXECUTOR and LAN_RECEIVER. Telegram account/bot, WebDAV and SFTP are server/protocol connectors that feed the same pipeline without pretending to be native peers.

Features

• Go/Gin backend with SQLite, durable work, retries and verification
• React/Vite control panel deployed independently from the backend
• Android and macOS GPB Sync peers with browser/QR pairing
• strict destination dedup before media bytes move
• direct verified LAN transfer or resumable server relay
• Google execution by a device or gotohp cloud lane
• Telegram account history/live sync and Telegram bot intake
• per-user WebDAV and SFTP connectors
• file-count, storage-size and unlimited user quotas
• administrator analytics, structured logs and maintenance controls
• Server-Sent Events for live UI updates

V5 is an immediate cutover. Native v3/v4 routes are not mounted and old device credentials are intentionally not migrated; rebuild and pair each app again.

Documentation

Start with the documentation index.

Document	Purpose
V5 architecture	Peer capabilities, lifecycle, policy and cutover.
Architecture	Runtime topology and end-to-end flow.
API	Browser, peer v5 and connector surfaces.
Pipeline	Canonical file/work lifecycle and retries.
Connectors	Native library, Telegram, WebDAV, SFTP and API intake.
Direct transfer	LAN trust, rendezvous, grants and routing.
Cloud lane	gotohp account execution.
Settings	Maintenance boundaries, quotas and field audit.
Frontend	UI structure, vocabulary and production delivery.
Client v5 handoff	Implementation brief for the macOS and Android GPB Sync refactors.
Operations	Backup, restore, deploy and rollback.

Repository structure

cmd/server/                 backend entrypoint
internal/core/              domain models and ports
internal/service/           admission, scheduling, peers, sync and connectors
internal/adapters/          SQLite, v5 HTTP, Telegram, WebDAV, SFTP and gotohp
internal/web/               browser API, middleware and routing
webapp/                     React application and Nginx image
extension/                  optional Google-account connector extension
scripts/                    operational backup/deployment helpers
docs/                       technical and operational documentation

Some physical SQLite tables/columns retain legacy node/client names. Active Go, JSON and UI names are v5; explicit mappings keep live-data deployment safe.

Deployment

1. Clone the repository and copy docker/example.env to .env.

2. Set strong ADMIN_PASSWORD and SESSION_SECRET values plus public domains.

3. Create the external Traefik network if it does not already exist:

   docker network create traefik-public
   

4. Build and start the stack:

   docker compose up -d --build
   

5. Verify GET /healthz and GET /readyz through the backend.

Backend and Web images are separate services. Publish a Web-only change without restarting backend workers. The Web image's Nginx serves Vite assets, compression/cache headers and SPA route fallback; Traefik remains the public TLS router and directs /api to the backend.

SQLite lives at data/gpb/gpb.db; staged media lives below data/uploads. Never deploy a schema change without an integrity-checked database backup. See OPERATIONS.md for the exact production procedure.

Web UI

Page	Path
Overview	/
Transfers	/transfers
Analytics	/analytics
Logs	/logs
Backup devices	/backup-devices
Sync apps	/apps
Connectors	/connectors
Settings	/settings

Legacy browser bookmarks redirect to these paths. Pairing approval is /pair.

API overview

The browser uses /api/web. Native apps use only /api/v5; paired calls send X-Peer-ID and X-Peer-Secret. Important native operations are:

POST /api/v5/pair/start
POST /api/v5/pair/poll
POST /api/v5/pair/qr
GET  /api/v5/capabilities
GET  /api/v5/me
POST /api/v5/items:declare
POST /api/v5/sync
POST /api/v5/logs
POST /api/v5/uploads
POST /api/v5/uploads:init

See API.md for the complete contract.

Development

Backend: go test ./... and go build ./cmd/server.

Frontend: run npm ci, npm run check, npm test and npm run build from webapp/. More detail is in DEVELOPMENT.md.

Security and backup

• Terminate public traffic with HTTPS.
• Use a unique session secret; it also protects direct-transfer CA material.
• WebDAV/SFTP passwords are separate from panel passwords.
• Pairing codes and grants are short-lived and single-purpose.
• Back up SQLite through its backup API plus the ledger and required secrets; do not plain-copy a live database file.

See SECURITY.md and OPERATIONS.md.