docs/persistence.md

# Persistence — staying logged in

The Chrome profile (cookies/logins) lives in `/home/chrome/data`. How it survives a restart
depends on where you run.

## Hugging Face → Neon Postgres (required)

HF free `cpu-basic` Spaces have **no persistent disk** — the filesystem is wiped on every
restart/rebuild. So the profile is snapshotted to an external Postgres DB by the `profilesync` tool:

- **Boot:** `profilesync restore` pulls the last snapshot.
- **Every 5 min + on shutdown:** `profilesync backup` saves it.
- Stored as one row: `chrome_profile(id, updated_at, data bytea)` (auto-created).
- **Gated on `DATABASE_URL`.** Not set → restore/backup skipped → logins lost on restart.

### Setup
1. Free DB at [neon.tech](https://neon.tech) → copy the connection string
   (`postgresql://user:pass@host.neon.tech/db?sslmode=require`).
2. HF Space → Settings → Variables and secrets → secret **`DATABASE_URL`** = that string.
3. Saving auto-restarts the Space. **Log in once** after that → first backup within 5 min → survives
   all future restarts.

### Verify a backup landed
```sql
SELECT id, updated_at, octet_length(data) FROM chrome_profile;
```
A row with non-zero size = persisted. (Profile stays small — junk/cache is stripped each boot;
typically 0.5–2 MB. Neon free = 512 MB, so it's ~0.1% used.)

## Self-host Docker → named volume (no DB needed)

`docker-compose.yml` mounts the `chrome-profile` named volume at `/home/chrome/data`, so logins
survive `docker compose down/up` and reboots automatically. **`DATABASE_URL` is not needed** for
Docker. To wipe the profile: `docker compose down -v`.

> Important: setting a new secret on HF forces a restart. If you log in *before* `DATABASE_URL` is
> set, that login is lost on the restart the secret triggers — log in again afterward.