Deploy: postgres + ngrok tunnel + gradio watcher + backups

.env.example

@@ -0,0 +1,23 @@
+# Copy to .env for local runs, or set these as Hugging Face Space secrets.
+
+# Required for a public connection URL (free: https://dashboard.ngrok.com)
+NGROK_AUTHTOKEN=
+
+# Recommended: locks the web UI behind Basic auth (username: admin)
+APP_PASSWORD=
+
+# Optional: fixed Postgres credentials (otherwise password is auto-generated each boot)
+POSTGRES_USER=demo
+POSTGRES_DB=demo
+POSTGRES_PASSWORD=
+
+# --- Backups (so data survives restarts) ---
+# Off-Space durable backups to a PRIVATE HF Dataset repo (works on the free tier).
+# Create a write token at https://huggingface.co/settings/tokens
+HF_TOKEN=
+HF_BACKUP_REPO=your-username/pg-backups
+
+# Tuning (optional)
+BACKUP_INTERVAL_MIN=30
+BACKUP_KEEP=24
+# BACKUP_DIR is auto-chosen: /data/backups if persistent storage is on, else local.

Dockerfile

@@ -0,0 +1,43 @@
+FROM python:3.11-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# PostgreSQL + tools we need at runtime
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        postgresql postgresql-contrib \
+        curl ca-certificates bash \
+    && rm -rf /var/lib/apt/lists/*
+
+# ngrok v3 (gives us a public TCP endpoint for Postgres) — pick the right arch
+RUN ARCH="$(dpkg --print-architecture)" \
+    && curl -fsSL "https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-${ARCH}.tgz" \
+        -o /tmp/ngrok.tgz \
+    && tar -xzf /tmp/ngrok.tgz -C /usr/local/bin \
+    && rm /tmp/ngrok.tgz \
+    && chmod +x /usr/local/bin/ngrok
+
+# HF Spaces runs the container as uid 1000 — create a matching user
+RUN useradd -m -u 1000 appuser
+ENV HOME=/home/appuser
+
+WORKDIR /app
+COPY app/requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY app /app
+COPY start.sh /app/start.sh
+RUN chmod +x /app/start.sh \
+    && mkdir -p /home/appuser/data \
+    && chown -R appuser:appuser /home/appuser /app
+
+USER appuser
+
+ENV PGDATA=/home/appuser/data/pgdata \
+    POSTGRES_USER=demo \
+    POSTGRES_DB=demo \
+    PGPORT=5432 \
+    APP_PORT=7860
+
+EXPOSE 7860
+
+CMD ["/app/start.sh"]

README.md

@@ -1,10 +1,129 @@
 ---
 title: Remote Postgres
-emoji: 🐠
+emoji: 🐘
 colorFrom: indigo
 colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Remote Postgres on Hugging Face Spaces
+
+A single Docker container that runs **PostgreSQL** + a small **web UI** that hands you a
+**public connection URL** to drop into any demo project that needs a Postgres database.
+
+Because Hugging Face Spaces only exposes one HTTP port (no raw TCP), the container opens an
+outbound **ngrok TCP tunnel** so Postgres is reachable from anywhere with a normal
+`postgresql://…` URL and any client/ORM.
+
+> ⚠️ **Ephemeral & throwaway.** Data is wiped on every restart/rebuild, and the public URL
+> changes each time. Great for demos; do not use for anything you need to keep.
+
+---
+
+## Deploy (5 minutes)
+
+1. **Get a free ngrok authtoken** — sign up at <https://dashboard.ngrok.com>, copy *Your Authtoken*.
+2. **Create a Space** → New Space → **SDK: Docker** → (recommended) **Visibility: Private**.
+3. **Push these files** to the Space repo (or upload them in the web UI):
+   `Dockerfile`, `start.sh`, `README.md`, and the `app/` folder.
+4. **Add Space secrets** (Settings → *Variables and secrets*):
+   | Secret | Required | Purpose |
+   |---|---|---|
+   | `NGROK_AUTHTOKEN` | ✅ | Opens the public TCP tunnel for Postgres |
+   | `APP_PASSWORD` | recommended | Locks the web UI (Basic auth, user `admin`) so only you see the URL |
+   | `POSTGRES_PASSWORD` | optional | Fixed DB password (otherwise one is generated per boot) |
+   | `POSTGRES_USER` / `POSTGRES_DB` | optional | Defaults: `demo` / `demo` |
+5. The Space builds and starts. Open it → the UI shows your **connection URL** + a Copy button.
+
+## Use it
+
+Open the Space, copy the `postgresql://…` URL, and use it anywhere:
+
+```bash
+psql "postgresql://demo:PASSWORD@0.tcp.ngrok.io:12345/demo"
+```
+
+```python
+import psycopg
+conn = psycopg.connect("postgresql://demo:PASSWORD@0.tcp.ngrok.io:12345/demo")
+```
+
+Works the same with SQLAlchemy, Prisma, Drizzle, node-postgres, etc.
+
+## Endpoints
+
+- `/` — **Gradio uptime-watcher dashboard**: live Postgres/tunnel status, container uptime,
+  availability %, recent-checks table, keep-alive counter, and the copyable connection URL.
+  Login-protected (user `admin`) when `APP_PASSWORD` is set.
+- `/api/connection` — JSON with the URL + fields (also protected).
+- `/keepalive?src=<label>` — open; bumps the keep-alive counter and logs the hit. Hit by the
+  in-container loop (`src=self`) and the external cron (`src=github-actions`).
+- `/health` — open status check: `{"status","postgres","tunnel","uptime"}`.
+
+## Don't lose the data (persistence)
+
+The container stacks two independent safeguards — use either or both:
+
+1. **Persistent volume (cleanest).** Enable **persistent storage** on the Space
+   (Settings → Storage). It mounts a writable `/data`; on boot the container detects it and
+   stores the live Postgres cluster at `/data/pgdata`, so data survives restarts as-is. Zero
+   extra config. (Paid HF add-on.)
+2. **Backups + auto-restore (works on free tier).** Every `BACKUP_INTERVAL_MIN` minutes the
+   DB is `pg_dump`ed to `BACKUP_DIR`, and — if you set `HF_TOKEN` + `HF_BACKUP_REPO` — mirrored
+   to a **private HF Dataset repo** (durable off-Space). On a fresh boot the container
+   **auto-restores the latest dump**, so even a wiped ephemeral Space comes back with your data
+   (you lose at most the last interval). There's also a **Back up now** button on the dashboard.
+
+   To enable off-Space backups, add Space secrets:
+   | Secret | Example | Purpose |
+   |---|---|---|
+   | `HF_TOKEN` | `hf_xxx` (write) | Lets the Space push/pull dumps — [create one](https://huggingface.co/settings/tokens) |
+   | `HF_BACKUP_REPO` | `your-name/pg-backups` | Private dataset repo (auto-created) holding the dumps |
+
+   Optional: `BACKUP_INTERVAL_MIN` (default 30), `BACKUP_KEEP` (default 24 local dumps).
+
+> Recommended combo for "I don't want to risk it" on free tier: **HF Dataset backups every
+> 15–30 min** + the external hourly keep-alive below. Data is safe across restarts; only the
+> ngrok URL still rotates (re-copy it from the dashboard after a restart).
+
+## Keeping the Space awake
+
+Free Spaces sleep after **48h with no HTTP traffic to the web app**. Your Postgres queries go
+through ngrok and do **not** count — only requests to this app's web port do. Two layers keep
+it awake:
+
+1. **In-container self-ping (automatic).** A loop hits `https://$SPACE_HOST/keepalive` every
+   20 min and logs each hit. Keeps the Space from ever going idle *while the container runs* —
+   but it cannot wake a Space that already slept (it's asleep too).
+2. **External hourly cron (recommended).** An outside request also **wakes** a slept Space.
+   Pick one:
+   - **GitHub Actions** — [`.github/workflows/keepalive.yml`](.github/workflows/keepalive.yml)
+     is included. Push this repo to GitHub, add a repo secret **`SPACE_URL`** =
+     `https://<your-space>.hf.space`, and it pings every hour. (Note: GitHub disables scheduled
+     workflows after 60 days with no commits — push occasionally, or use the option below.)
+   - **No-code:** [cron-job.org](https://cron-job.org) or [UptimeRobot](https://uptimerobot.com)
+     → GET `https://<your-space>.hf.space/keepalive` every hour. Truly set-and-forget.
+
+You can watch the **Keep-alive hits** counter on the dashboard to confirm pings are landing.
+
+> A sleep/wake or any rebuild still wipes data and rotates the URL — keep-alive only keeps the
+> Space *running*; it does not make the data or the URL permanent.
+
+## Keep it secure
+
+- Set the Space to **Private** and set **`APP_PASSWORD`** so the URL isn't world-readable.
+- The DB itself is internet-exposed via the tunnel — anyone with the URL **and** password can
+  connect. Use a strong `POSTGRES_PASSWORD` and treat the data as disposable.
+
+## Local test
+
+```bash
+docker build -t remote-pg .
+docker run -p 7860:7860 \
+  -e NGROK_AUTHTOKEN=your_token \
+  -e APP_PASSWORD=letmein \
+  remote-pg
+# open http://localhost:7860
+```

app/backup.py

@@ -0,0 +1,153 @@
+"""Backup / restore for the in-container Postgres.
+
+Two durable targets, either or both:
+  * BACKUP_DIR        — local dir (durable only if it's on HF persistent /data)
+  * HF_BACKUP_REPO    — a private HF Dataset repo (durable even on the free tier)
+
+A fresh boot calls `restore()` to pull the latest dump back; a background scheduler
+calls `backup()` every BACKUP_INTERVAL_MIN minutes.
+"""
+import os
+import sys
+import glob
+import gzip
+import time
+import threading
+import subprocess
+from datetime import datetime
+
+PG_USER = os.environ.get("POSTGRES_USER", "demo")
+PG_DB = os.environ.get("POSTGRES_DB", "demo")
+PG_PORT = os.environ.get("PGPORT", "5432")
+PGHOST = "/tmp"
+
+BACKUP_DIR = os.environ.get("BACKUP_DIR", "/home/appuser/backups")
+KEEP = int(os.environ.get("BACKUP_KEEP", "24"))
+INTERVAL_MIN = int(os.environ.get("BACKUP_INTERVAL_MIN", "30"))
+
+HF_REPO = os.environ.get("HF_BACKUP_REPO", "").strip()      # e.g. "user/pg-backups"
+HF_TOKEN = os.environ.get("HF_TOKEN", "").strip()
+HF_LATEST = "backups/latest.sql.gz"
+
+# Surfaced on the dashboard.
+STATE = {"count": 0, "last": None, "last_name": None, "error": None,
+         "dir": BACKUP_DIR, "hf": bool(HF_REPO and HF_TOKEN)}
+
+
+def _ts():
+    return datetime.now().strftime("%Y%m%d-%H%M%S")
+
+
+def _hf_api():
+    from huggingface_hub import HfApi
+    return HfApi(token=HF_TOKEN)
+
+
+def ensure_repo():
+    if not (HF_REPO and HF_TOKEN):
+        return
+    try:
+        _hf_api().create_repo(repo_id=HF_REPO, repo_type="dataset",
+                              private=True, exist_ok=True)
+        print(f"[backup] HF dataset ready: {HF_REPO}", flush=True)
+    except Exception as e:
+        print(f"[backup] create_repo failed: {e}", flush=True)
+
+
+def backup():
+    """Dump the DB to a gzip file locally, rotate, and mirror to HF (latest)."""
+    os.makedirs(BACKUP_DIR, exist_ok=True)
+    name = f"backup-{_ts()}.sql.gz"
+    path = os.path.join(BACKUP_DIR, name)
+    try:
+        dump = subprocess.run(
+            ["pg_dump", "-h", PGHOST, "-p", PG_PORT, "-U", PG_USER,
+             "-d", PG_DB, "--clean", "--if-exists"],
+            stdout=subprocess.PIPE, check=True,
+        ).stdout
+        with gzip.open(path, "wb") as f:
+            f.write(dump)
+
+        # keep only the newest KEEP local dumps
+        for old in sorted(glob.glob(os.path.join(BACKUP_DIR, "backup-*.sql.gz")))[:-KEEP]:
+            try:
+                os.remove(old)
+            except OSError:
+                pass
+
+        if HF_REPO and HF_TOKEN:
+            try:
+                _hf_api().upload_file(
+                    path_or_fileobj=path, path_in_repo=HF_LATEST,
+                    repo_id=HF_REPO, repo_type="dataset",
+                    commit_message=f"backup {name}",
+                )
+            except Exception as e:
+                print(f"[backup] HF upload failed: {e}", flush=True)
+
+        STATE.update(count=STATE["count"] + 1, last=datetime.now(),
+                     last_name=name, error=None)
+        print(f"[backup] wrote {name} ({os.path.getsize(path)} bytes)", flush=True)
+        return path
+    except Exception as e:
+        STATE["error"] = str(e)
+        print(f"[backup] FAILED: {e}", flush=True)
+        raise
+
+
+def restore():
+    """Restore the most recent dump (prefers HF, falls back to local). Returns bool."""
+    src = None
+    if HF_REPO and HF_TOKEN:
+        try:
+            from huggingface_hub import hf_hub_download
+            src = hf_hub_download(HF_REPO, HF_LATEST, repo_type="dataset",
+                                  token=HF_TOKEN)
+            print(f"[backup] fetched latest dump from HF dataset {HF_REPO}", flush=True)
+        except Exception as e:
+            print(f"[backup] no HF backup to restore ({e})", flush=True)
+    if src is None:
+        local = sorted(glob.glob(os.path.join(BACKUP_DIR, "backup-*.sql.gz")))
+        src = local[-1] if local else None
+    if not src:
+        print("[backup] no backup found — starting empty", flush=True)
+        return False
+
+    print(f"[backup] restoring from {src}", flush=True)
+    with gzip.open(src, "rb") as f:
+        subprocess.run(
+            ["psql", "-h", PGHOST, "-p", PG_PORT, "-U", PG_USER,
+             "-d", PG_DB, "-v", "ON_ERROR_STOP=0", "-q"],
+            input=f.read(), check=True,
+        )
+    print("[backup] restore complete", flush=True)
+    return True
+
+
+def _loop():
+    while True:
+        time.sleep(INTERVAL_MIN * 60)
+        try:
+            backup()
+        except Exception:
+            pass
+
+
+def start_scheduler():
+    """Called from the web app: ensure the HF repo exists and start periodic backups."""
+    ensure_repo()
+    threading.Thread(target=_loop, daemon=True).start()
+    print(f"[backup] scheduler started — every {INTERVAL_MIN} min, "
+          f"dir={BACKUP_DIR}, hf={'on' if STATE['hf'] else 'off'}", flush=True)
+
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else ""
+    if cmd == "backup":
+        backup()
+    elif cmd == "restore":
+        restore()
+    elif cmd == "ensure-repo":
+        ensure_repo()
+    else:
+        print("usage: backup.py [backup|restore|ensure-repo]")

app/main.py

@@ -0,0 +1,233 @@
+import os
+import time
+import secrets
+import threading
+from datetime import datetime, timedelta
+
+import httpx
+import psycopg
+import gradio as gr
+
+import backup
+from fastapi import FastAPI, Depends, HTTPException, status
+from fastapi.responses import JSONResponse
+from fastapi.security import HTTPBasic, HTTPBasicCredentials
+
+PG_USER = os.environ.get("POSTGRES_USER", "demo")
+PG_PASSWORD = os.environ.get("POSTGRES_PASSWORD", "")
+PG_DB = os.environ.get("POSTGRES_DB", "demo")
+PG_PORT = os.environ.get("PGPORT", "5432")
+
+# If set, the Gradio UI and the JSON API require this password (username: admin).
+APP_PASSWORD = os.environ.get("APP_PASSWORD", "")
+APP_USER = os.environ.get("APP_USER", "admin")
+
+NGROK_API = "http://127.0.0.1:4040/api/tunnels"
+
+BOOT = datetime.now()
+HISTORY: list[tuple[str, bool, bool]] = []   # (HH:MM:SS, postgres_up, tunnel_up)
+HISTORY_MAX = 500
+
+# Keep-alive counter (incremented by the in-container loop AND any external cron).
+KEEPALIVE = {"count": 0, "last": None, "src": "—"}
+
+
+# ---------------------------------------------------------------- helpers ----
+def get_tunnel():
+    """Return (host, port) of the public ngrok TCP tunnel, or None."""
+    try:
+        r = httpx.get(NGROK_API, timeout=3)
+        for t in r.json().get("tunnels", []):
+            if t.get("proto") == "tcp":
+                host, port = t["public_url"].split("://", 1)[1].split(":")
+                return host, port
+    except Exception:
+        return None
+    return None
+
+
+def pg_ok() -> bool:
+    try:
+        with psycopg.connect(
+            host="/tmp", port=PG_PORT, user=PG_USER,
+            dbname=PG_DB, password=PG_PASSWORD, connect_timeout=3,
+        ):
+            return True
+    except Exception:
+        return False
+
+
+def build_url(tunnel):
+    if not tunnel:
+        return None
+    host, port = tunnel
+    return f"postgresql://{PG_USER}:{PG_PASSWORD}@{host}:{port}/{PG_DB}"
+
+
+def humanize(delta: timedelta) -> str:
+    s = int(delta.total_seconds())
+    d, s = divmod(s, 86400)
+    h, s = divmod(s, 3600)
+    m, s = divmod(s, 60)
+    if d:
+        return f"{d}d {h}h {m}m"
+    if h:
+        return f"{h}h {m}m {s}s"
+    return f"{m}m {s}s"
+
+
+def record_check():
+    ok = pg_ok()
+    tn = get_tunnel() is not None
+    HISTORY.append((datetime.now().strftime("%H:%M:%S"), ok, tn))
+    del HISTORY[:-HISTORY_MAX]
+    return ok, tn
+
+
+def _watcher_loop():
+    while True:
+        try:
+            record_check()
+        except Exception:
+            pass
+        time.sleep(30)
+
+
+# Background uptime watcher — records a sample every 30s while the container lives.
+threading.Thread(target=_watcher_loop, daemon=True).start()
+
+# Periodic Postgres backups (to BACKUP_DIR and/or a private HF Dataset).
+backup.start_scheduler()
+
+
+# ------------------------------------------------------------- JSON / API ----
+api = FastAPI(title="Remote Postgres", docs_url=None, redoc_url=None)
+security = HTTPBasic(auto_error=False)
+
+
+def require_auth(credentials: HTTPBasicCredentials | None = Depends(security)):
+    if not APP_PASSWORD:
+        return
+    if credentials is None or not (
+        secrets.compare_digest(credentials.username, APP_USER)
+        and secrets.compare_digest(credentials.password, APP_PASSWORD)
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required",
+            headers={"WWW-Authenticate": "Basic"},
+        )
+
+
+@api.get("/health")
+async def health():
+    """Open endpoint — used by the self keep-alive and external uptime monitors."""
+    tunnel = get_tunnel()
+    ok = pg_ok()
+    return JSONResponse({
+        "status": "ok" if ok else "degraded",
+        "postgres": ok,
+        "tunnel": bool(tunnel),
+        "uptime": humanize(datetime.now() - BOOT),
+    })
+
+
+@api.get("/keepalive")
+async def keepalive(src: str = "self"):
+    """Hit to reset HF's idle timer (by the in-container loop AND any external cron).
+    Open + logged so you can confirm pings are landing."""
+    KEEPALIVE["count"] += 1
+    KEEPALIVE["last"] = datetime.now()
+    KEEPALIVE["src"] = src
+    print(f"[keepalive] hit #{KEEPALIVE['count']} from '{src}' at "
+          f"{KEEPALIVE['last'].strftime('%Y-%m-%d %H:%M:%S')}", flush=True)
+    return {"ok": True, "count": KEEPALIVE["count"], "src": src}
+
+
+@api.get("/api/connection")
+async def connection(_: None = Depends(require_auth)):
+    tunnel = get_tunnel()
+    host, port = tunnel if tunnel else (None, None)
+    return {
+        "postgres_up": pg_ok(),
+        "connection_url": build_url(tunnel),
+        "host": host, "port": port,
+        "user": PG_USER, "password": PG_PASSWORD, "database": PG_DB,
+    }
+
+
+# ------------------------------------------------- Gradio uptime watcher ----
+def snapshot():
+    tunnel = get_tunnel()
+    up = pg_ok()
+    url = build_url(tunnel) or "— no public tunnel yet (set NGROK_AUTHTOKEN) —"
+    host, port = tunnel if tunnel else ("—", "��")
+
+    samples = len(HISTORY)
+    pct = (100 * sum(1 for _, o, _ in HISTORY if o) / samples) if samples else 100.0
+    status_md = (
+        f"### Status\n"
+        f"- **Postgres:** {'🟢 up' if up else '🔴 down'}\n"
+        f"- **Public tunnel:** {'🟢 up' if tunnel else '🟡 off'}\n"
+        f"- **Container uptime:** {humanize(datetime.now() - BOOT)}\n"
+        f"- **PG availability (this container):** {pct:.1f}%  ·  {samples} checks\n"
+        f"- **Keep-alive hits:** {KEEPALIVE['count']}  ·  last from "
+        f"`{KEEPALIVE['src']}` at "
+        f"{KEEPALIVE['last'].strftime('%H:%M:%S') if KEEPALIVE['last'] else 'never'}\n"
+        f"- **Backups:** {backup.STATE['count']} taken  ·  last: "
+        f"{backup.STATE['last'].strftime('%H:%M:%S') if backup.STATE['last'] else 'none yet'}"
+        f"  ·  HF off-Space: {'on' if backup.STATE['hf'] else 'off'}\n"
+        f"- **Last checked:** {datetime.now().strftime('%H:%M:%S')}"
+    )
+    table = [
+        [t, "✅" if o else "❌", "✅" if n else "❌"]
+        for (t, o, n) in reversed(HISTORY[-25:])
+    ]
+    return status_md, url, host, port, PG_USER, PG_PASSWORD, PG_DB, table
+
+
+with gr.Blocks(title="Remote Postgres — Uptime Watcher", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# 🐘 Remote Postgres — Uptime Watcher")
+    gr.Markdown(
+        "Throwaway Postgres for demo projects, exposed over an ngrok TCP tunnel. "
+        "Data is **ephemeral** and the URL **changes on every restart**."
+    )
+    status_box = gr.Markdown()
+    url_box = gr.Textbox(
+        label="Connection URL — paste into your projects",
+        interactive=False, show_copy_button=True,
+    )
+    with gr.Row():
+        host_box = gr.Textbox(label="Host", interactive=False)
+        port_box = gr.Textbox(label="Port", interactive=False)
+    with gr.Row():
+        user_box = gr.Textbox(label="User", interactive=False)
+        pw_box = gr.Textbox(label="Password", interactive=False)
+        db_box = gr.Textbox(label="Database", interactive=False)
+    history_box = gr.Dataframe(
+        headers=["time", "postgres", "tunnel"],
+        label="Recent checks (newest first)",
+        interactive=False,
+    )
+    with gr.Row():
+        refresh_btn = gr.Button("Refresh now", variant="primary")
+        backup_btn = gr.Button("Back up now")
+
+    def backup_now():
+        try:
+            backup.backup()
+        except Exception as e:
+            print(f"[ui] manual backup failed: {e}", flush=True)
+        return snapshot()
+
+    outputs = [status_box, url_box, host_box, port_box,
+               user_box, pw_box, db_box, history_box]
+    timer = gr.Timer(10)
+    timer.tick(snapshot, outputs=outputs)
+    refresh_btn.click(snapshot, outputs=outputs)
+    backup_btn.click(backup_now, outputs=outputs)
+    demo.load(snapshot, outputs=outputs)
+
+
+auth = (APP_USER, APP_PASSWORD) if APP_PASSWORD else None
+app = gr.mount_gradio_app(api, demo, path="/", auth=auth)

app/requirements.txt

@@ -0,0 +1,5 @@
+gradio==4.44.1
+huggingface_hub==0.25.2
+fastapi==0.112.2
+psycopg[binary]==3.1.19
+httpx==0.27.0

start.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Postgres client/server binaries live in /usr/lib/postgresql/<ver>/bin on Debian
+export PATH="$(ls -d /usr/lib/postgresql/*/bin 2>/dev/null | head -n1):$PATH"
+
+: "${POSTGRES_USER:=demo}"
+: "${POSTGRES_DB:=demo}"
+: "${PGPORT:=5432}"
+: "${APP_PORT:=7860}"
+export PGHOST=/tmp   # local clients connect over the unix socket in /tmp (trust auth)
+
+# ---- pick data + backup locations ----
+# HF persistent storage (if enabled) mounts a writable /data owned by uid 1000.
+# When present we keep BOTH the live cluster AND backups there so they survive restarts.
+if [ -d /data ] && [ -w /data ]; then
+  echo "[start] Persistent /data detected — using it for the cluster and backups."
+  export PGDATA="${PGDATA:-/data/pgdata}"
+  export BACKUP_DIR="${BACKUP_DIR:-/data/backups}"
+else
+  echo "[start] No persistent /data — cluster is EPHEMERAL; relying on backup/restore."
+  export PGDATA="${PGDATA:-/home/appuser/data/pgdata}"
+  export BACKUP_DIR="${BACKUP_DIR:-/home/appuser/backups}"
+fi
+mkdir -p "$BACKUP_DIR"
+
+# Generate a strong password if the user didn't supply one as a Space secret
+if [ -z "${POSTGRES_PASSWORD:-}" ]; then
+  POSTGRES_PASSWORD="$(python3 -c 'import secrets;print(secrets.token_urlsafe(18))')"
+  echo "[start] No POSTGRES_PASSWORD secret set — generated one for this session."
+fi
+export POSTGRES_PASSWORD POSTGRES_USER POSTGRES_DB PGPORT BACKUP_DIR
+
+FRESH_INIT=0
+
+# ---- initialize the cluster (only when the data dir is empty) ----
+if [ ! -s "$PGDATA/PG_VERSION" ]; then
+  FRESH_INIT=1
+  echo "[start] Initializing PostgreSQL cluster at $PGDATA"
+  mkdir -p "$PGDATA"
+  chmod 700 "$PGDATA"
+  PWFILE="$(mktemp)"
+  printf '%s' "$POSTGRES_PASSWORD" > "$PWFILE"
+  initdb -D "$PGDATA" \
+         --auth-host=scram-sha-256 \
+         --auth-local=trust \
+         -U "$POSTGRES_USER" \
+         --pwfile="$PWFILE" >/dev/null
+  rm -f "$PWFILE"
+
+  {
+    echo "listen_addresses = '*'"
+    echo "port = $PGPORT"
+    echo "unix_socket_directories = '/tmp'"
+  } >> "$PGDATA/postgresql.conf"
+
+  {
+    echo "host all all 0.0.0.0/0 scram-sha-256"
+    echo "host all all ::/0      scram-sha-256"
+  } >> "$PGDATA/pg_hba.conf"
+fi
+
+# ---- start postgres ----
+echo "[start] Starting PostgreSQL on port $PGPORT"
+pg_ctl -D "$PGDATA" -o "-p $PGPORT" -w -l "$PGDATA/server.log" start
+
+# ensure the target database exists
+if ! psql -p "$PGPORT" -U "$POSTGRES_USER" -d postgres -tAc \
+       "SELECT 1 FROM pg_database WHERE datname='$POSTGRES_DB'" | grep -q 1; then
+  echo "[start] Creating database '$POSTGRES_DB'"
+  createdb -p "$PGPORT" -U "$POSTGRES_USER" "$POSTGRES_DB"
+fi
+
+# ---- restore the latest backup onto a freshly-initialized cluster ----
+# On a fresh boot (ephemeral disk, or first run) pull back the most recent dump so the
+# data "survives" restarts. Skipped when the cluster already had data (persistent disk).
+if [ "$FRESH_INIT" = "1" ]; then
+  echo "[start] Fresh cluster — checking for a backup to restore"
+  python /app/backup.py restore || echo "[start] no restore performed"
+fi
+
+# ---- expose Postgres publicly via ngrok TCP tunnel ----
+if [ -n "${NGROK_AUTHTOKEN:-}" ]; then
+  echo "[start] Configuring ngrok and opening TCP tunnel for port $PGPORT"
+  ngrok config add-authtoken "$NGROK_AUTHTOKEN" >/dev/null 2>&1 || true
+  ngrok tcp "$PGPORT" --log=stdout > "$HOME/ngrok.log" 2>&1 &
+else
+  echo "[start] NGROK_AUTHTOKEN not set — Postgres is only reachable INSIDE the Space."
+  echo "[start] Add a free ngrok authtoken as a Space secret to get a public URL."
+fi
+
+# ---- keep the Space awake (free Spaces sleep after 48h with NO http traffic) ----
+# Postgres/ngrok traffic does NOT count — only requests to this web app do. So we hit
+# the PUBLIC url (goes through HF's router => resets the idle timer). SPACE_HOST is
+# injected by HF, e.g. user-space.hf.space. Each hit is logged to the Space logs.
+if [ -n "${SPACE_HOST:-}" ]; then
+  echo "[start] Self keep-alive enabled — pinging https://${SPACE_HOST}/keepalive every 20m"
+  ( while true; do
+      sleep 1200
+      ts="$(date '+%Y-%m-%d %H:%M:%S')"
+      code="$(curl -fsS -o /dev/null -w '%{http_code}' \
+              "https://${SPACE_HOST}/keepalive?src=self" 2>/dev/null || echo 000)"
+      echo "[keepalive] self ${ts} -> ${code}"
+    done ) &
+fi
+
+# ---- start the web UI (foreground; keeps the container alive) ----
+echo "[start] Starting web UI on port $APP_PORT"
+cd /app
+exec uvicorn main:app --host 0.0.0.0 --port "$APP_PORT"