---
title: MyAPI Hub
emoji: 🚀
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: sub2api + bundled PG/Redis sidecar with bucket dumps
---

# MyAPI Hub on Hugging Face Spaces

Single-container deployment of [Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api)
that bundles **PostgreSQL 18** and **Redis** as sidecars inside the same Space.
PGDATA lives on the Space's ephemeral disk; `pg_dump` runs on a timer and writes
to a mounted **Hugging Face bucket** for persistence across rebuilds.

## Architecture

```
┌──────────── HF Space container (single image) ─────────────┐
│  supervisord                                                │
│    ├─ postgres   (127.0.0.1:5432, PGDATA=/var/lib/...)      │
│    ├─ redis      (127.0.0.1:6379, in-memory)                │
│    ├─ backup.sh  (every BACKUP_INTERVAL_MIN min)            │
│    │     pg_dump | gzip → /backup/pg-<ts>.sql.gz            │
│    │                       /backup/latest.sql.gz            │
│    └─ sub2api    (0.0.0.0:7860, talks to localhost PG/Redis)│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼  /backup is FUSE-mounted
                  hf://buckets/<you>/sub2api-pgdump
```

On cold boot, if PGDATA is empty *and* `/backup/latest.sql.gz` exists, the
entrypoint restores it before launching the app.

## Why not mount the bucket as PGDATA directly?

HF buckets are S3-style storage exposed via a FUSE filesystem. PostgreSQL
requires real `fsync` semantics for durability; running PGDATA on FUSE risks
silent corruption. We therefore keep live PGDATA on the Space disk and only
write **dumps** to the bucket (a workload FUSE handles safely).

## 1. Prerequisites

```bash
hf auth login                            # HF token with write to your namespace
hf buckets create <you>/sub2api-pgdump --private
hf spaces volumes set <you>/myapi-hub \
    -v hf://buckets/<you>/sub2api-pgdump:/backup
```

Free accounts get **100 GB private storage**, far more than needed for dump
snapshots (a hobby DB compresses to a few MB).

## 2. Required Space secrets

In **Settings → Variables and secrets** add as **secrets**:

```
POSTGRES_PASSWORD   = <strong random — used by both PG and sub2api>
JWT_SECRET          = <openssl rand -hex 32>      # MUST be stable
TOTP_ENCRYPTION_KEY = <openssl rand -hex 32>      # MUST be stable
ADMIN_EMAIL         = you@example.com
ADMIN_PASSWORD      = <leave empty to auto-generate; check logs>

DATABASE_PASSWORD   = <same value as POSTGRES_PASSWORD>
```

Optional **variables** (defaults in parentheses):

```
POSTGRES_USER       = sub2api
POSTGRES_DB         = sub2api
BACKUP_INTERVAL_MIN = 30          # how often to dump
BACKUP_KEEP         = 24          # how many timestamped dumps to retain
DATABASE_USER       = sub2api     # same as POSTGRES_USER
DATABASE_DBNAME     = sub2api     # same as POSTGRES_DB
LOG_LEVEL           = info
```

Do **not** override `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_SSLMODE`,
`REDIS_HOST`, `REDIS_PORT`, `REDIS_ENABLE_TLS` — they are set in the Dockerfile
for the in-container loopback.

## 3. Deploy

Push `Dockerfile`, `entrypoint.sh`, `backup.sh`, `supervisord.conf`, `README.md`
to the Space repo. First build runs `initdb`, creates the database, and starts
the four sidecar processes. Subsequent rebuilds will restore from the latest
bucket dump if the ephemeral disk was wiped.

## 4. Operating

- **List dumps:** `hf buckets list <you>/sub2api-pgdump`
- **Download latest dump locally:** `hf buckets cp hf://buckets/<you>/sub2api-pgdump/latest.sql.gz ./`
- **Force a manual dump:** restart the Space (next cycle fires after `BACKUP_WARMUP_SEC`), or open a shell via dev mode and run `/usr/local/bin/backup.sh once`.
- **Disaster recovery:** download `latest.sql.gz`, restore into any Postgres with `gunzip -c latest.sql.gz | psql -d <db>`.

## 5. Caveats

- **RPO ≈ BACKUP_INTERVAL_MIN.** Crash between dumps loses up to that many minutes of writes.
- **No external PG access.** Postgres binds `127.0.0.1` inside the Space; only the bundled sub2api can reach it. For psql from outside, use the dump file or run a tunnel (cloudflared/chisel) — not provided here.
- **Cold start = potential restore.** Free Spaces sleep after inactivity and may evict the ephemeral disk on hardware moves. The restore step runs only when PGDATA is empty, so warm restarts are fast.
- **Redis is non-persistent.** AOF/RDB disabled by design (sessions are cheap to re-create). Restart logs users out.
- **Pin secrets.** `JWT_SECRET` / `TOTP_ENCRYPTION_KEY` must not change across rebuilds, or all sessions / 2FA invalidate.

## License

Apache-2.0 (inherits from upstream sub2api).