| # Mixly on Hugging Face Spaces — deploy & operations |
|
|
| The Space (`jay-hank/mixly`) is a **Docker** host. Its `Dockerfile` clones the |
| **private** GitHub repo `phamdung2209/Mixly` at build time and runs the Next.js app. |
|
|
| Public URL: `https://jay-hank-mixly.hf.space` |
|
|
| > ⚠️ **Data isolation.** Mixly lives under the `jay-hank` HF account — a |
| > **different account** from `solora-hq`, which hosts **Tierly** and is LIVE with |
| > real merchant data. Mixly's `DATABASE_URL`, `S3_BUCKET`, `S3_ENDPOINT`, and Space |
| > name are a completely separate set of identifiers from Tierly's — never copy a |
| > value from Tierly's `DEPLOY.md` here. Concretely: DB path is `/data/mixly.db` |
| > (not `tierly.db`), bucket is `Mixly-storage` (not `Tierly-storage`) under the |
| > `jay-hank` namespace (not `solora-hq`), Space is `jay-hank/mixly` (not |
| > `solora-hq/Tierly`). `jay-hank` has no access to `solora-hq` at all, so pointing |
| > Mixly at any of Tierly's identifiers won't just risk corrupting or leaking live |
| > merchant data — it will most likely just fail outright. |
| |
| --- |
| |
| ## 0. First-time setup (do this once — the Space already exists) |
| |
| The Space `jay-hank/mixly` has already been created (Docker SDK) on the |
| `jay-hank` HF account. What's left: |
| |
| 1. **Add the remote and push this repo**: |
| ``` |
| git remote add origin https://huggingface.co/spaces/jay-hank/mixly |
| git push -u origin main |
| ``` |
| The first build will fail (or crash-loop) until the secrets in §2 are set — |
| that's expected, HF just needs a repo to attach the build to. |
| 2. **Create the S3 storage bucket**: HF → your `jay-hank` account → **Storage** → |
| **New bucket** → name it exactly `Mixly-storage` (bare name, no slashes). Double |
| check it is not `Tierly-storage`. Read the risk note below first — Storage |
| Buckets may not be available on this account's plan. |
| 3. **Set every secret in §2 below** (Space → Settings → Variables and secrets), |
| then Space → Settings → **Factory rebuild**. |
| |
| > 🚧 **Risk: HF Storage Buckets may not be available on a free, non-Pro account.** |
| > `jay-hank` is a free, non-Pro account. This matters more than it sounds: the HF |
| > free tier has an **ephemeral** filesystem, so without a working S3 bucket the |
| > SQLite database is **destroyed on every rebuild, restart, or wake-from-sleep** — |
| > the app would silently lose every merchant's bundles, settings, and stats. |
| > Tierly has already suffered exactly this data-loss failure once, which is why |
| > the restore-on-boot mechanism (§4) exists. Before treating this deployment as |
| > production-ready, confirm that a bucket named `Mixly-storage` can actually be |
| > created under the `jay-hank` namespace and that `S3_ACCESS_KEY_ID` / |
| > `S3_SECRET_ACCESS_KEY` work against `https://s3.hf.co/jay-hank`. If HF storage |
| > buckets aren't available on this plan, the options are: enable HF Persistent |
| > Storage (paid), upgrade the account, or point the backup at a different |
| > S3-compatible provider (`src/lib/s3.ts` speaks plain S3, so any S3-compatible |
| > endpoint should work). |
| |
| --- |
| |
| ## 1. GitHub token (required — the repo is private) |
| |
| Cloning a private repo inside the Docker build needs a token. Create a |
| **fine-grained Personal Access Token**, scoped to just this repo, read-only: |
| |
| 1. GitHub → **Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new**. |
| 2. **Resource owner**: `phamdung2209`. **Repository access**: *Only select repositories* → `Mixly`. |
| 3. **Permissions → Repository → Contents: Read-only** (that's all it needs). |
| 4. Expiration: 90 days (rotate on expiry). Generate → copy the `github_pat_…`. |
| |
| Then add it to the Space as a **build secret**: |
| - Space → **Settings → Variables and secrets → New secret** |
| - Name: `GITHUB_TOKEN` · Value: the `github_pat_…` |
|
|
| > The Dockerfile reads it via `--mount=type=secret,id=GITHUB_TOKEN`, so it is |
| > **never baked into an image layer**. |
| |
| --- |
| |
| ## 2. Space secrets (runtime) — Settings → Variables and secrets |
| |
| 🔒 Paste values in the HF UI, never into code/git. **Secrets** (hidden) vs |
| **Variables** (visible) — put all credentials as *Secrets*. |
| |
| ### Required |
| | Name | Value / where from | |
| |---|---| |
| | `GITHUB_TOKEN` | build secret from §1 | |
| | `SHOPIFY_API_KEY` | Partner Dashboard → Mixly → API credentials | |
| | `SHOPIFY_API_SECRET` | ″ (secret) | |
| | `NEXT_PUBLIC_SHOPIFY_API_KEY` | **same value as** `SHOPIFY_API_KEY` | |
| | `SHOPIFY_SCOPES` | `read_orders,read_products,write_discounts` (match `shopify.app.toml`) | |
| | `SHOPIFY_APP_URL` | `https://jay-hank-mixly.hf.space` | |
| | `SHOPIFY_API_VERSION` | `2026-07` | |
| | `DATABASE_URL` | `file:/data/mixly.db` (persistent mount — see §3) | |
| | `SESSION_ENCRYPTION_KEY` | `openssl rand -hex 32`. **Set once, never change** (rotating it forces every store to re-auth). | |
| | `HF_SPACE_ID` | `jay-hank/mixly` — the in-code default (`src/lib/ops/backup.ts`) is still `solora-hq/Mixly`, which is wrong for this deployment, so this must be set explicitly. | |
|
|
| ### Ops Console + DB access (`/ops`, `/ops/studio`) |
| | Name | Value | |
| |---|---| |
| | `OPS_ALLOWLIST` | comma-separated emails allowed into `/ops` | |
| | `AUTH_SECRET` | `npx auth secret`. Keep stable (else your `/ops` sessions drop). | |
| | `AUTH_GOOGLE_ID` | Google Cloud Console → OAuth client ID | |
| | `AUTH_GOOGLE_SECRET` | ″ (redirect URI: `https://jay-hank-mixly.hf.space/api/auth/callback/google`) | |
|
|
| ### DB backup (§4) — HF Storage Bucket via S3 API |
| | Name | Value | |
| |---|---| |
| | `S3_ENDPOINT` | `https://s3.hf.co/jay-hank` (gateway scoped to the namespace) | |
| | `S3_BUCKET` | `Mixly-storage` (bare bucket name — **not** `Tierly-storage`) | |
| | `S3_ACCESS_KEY_ID` | `HFAK…` — HF **Access Tokens** → token (Write) → dropdown → **Generate S3 credentials** | |
| | `S3_SECRET_ACCESS_KEY` | ″ (shown once) | |
| | `HF_TOKEN` | HF bearer token — used to rebuild/restart the Space from `/ops/backup` after a DB restore (§4), and by `scripts/sync-env.mjs` (§5), NOT the S3 creds | |
|
|
| ### Optional (features degrade gracefully when unset) |
| `SENTRY_DSN`, `GITHUB_REPO` (overrides the clone source; the Dockerfile's |
| `ARG GITHUB_REPO` build arg already defaults to the right repo). |
|
|
| Mixly has **no** Crisp chat, QStash, or email (Resend) integration — unlike |
| Tierly, none of `NEXT_PUBLIC_CRISP_WEBSITE_ID`, `QSTASH_*`, `RESEND_API_KEY`, |
| `EMAIL_FROM`, or `CRON_SECRET` apply here; don't set them. |
|
|
| --- |
|
|
| ## 3. Persistent storage |
|
|
| Space → **Settings → Persistent storage** → enable (Small is plenty). It mounts |
| at `/data`, which is where `DATABASE_URL=file:/data/mixly.db` points. Without it, |
| `/data` resets on every rebuild — which is exactly why §4 exists. |
|
|
| > Do **not** mount the Storage Bucket as a data volume. Backup talks to it over the |
| > S3 API (§4); a bucket *mount* is a schedule-time dependency and, if HF can't attach |
| > it, the Space fails with "Scheduling failure: unable to schedule". |
|
|
| --- |
|
|
| ## 4. Database backup / restore (HF Storage Bucket, S3 API) |
|
|
| The app backs the SQLite DB up to a **Storage Bucket over the S3 API** and restores |
| it on boot if `/data` is empty — so data survives a rebuild even on the free tier. |
| Network-only (no mount), so it never blocks Space scheduling. |
|
|
| - **What's backed up:** only the SQLite DB file (`/data/mixly.db`). It holds |
| everything stateful: Shopify sessions (tokens encrypted at rest), bundle offers, |
| bundle configs, shop profiles, settings. Migrations live in git; nothing else |
| needs backing up. |
| - **The one thing that is NOT in the bucket:** `SESSION_ENCRYPTION_KEY`. It lives |
| only in Space secrets. Keep it — a restored DB with a lost/rotated key can't |
| decrypt stored Shopify tokens (the app then just re-exchanges them, no data loss, |
| but avoid churn). |
| - **Bucket:** `jay-hank/Mixly-storage`. Objects: `latest.db` (overwritten in place — |
| no history growth) + `snapshots/mixly-YYYY-MM-DD.db` (daily, pruned after 30 days). |
| - **Schedule:** in-process — an initial backup ~1 min after boot, then hourly, plus a |
| debounced write after each DB change and a final flush on SIGTERM (see |
| `src/lib/backup.ts` + `src/lib/s3.ts`, started from `src/instrumentation.ts`). |
| - **Operator-driven backup/restore:** unlike a plain snapshot loop, Mixly ships an |
| `/ops/backup` panel (Google-authenticated, see §2) that can trigger an immediate |
| backup, upload a snapshot to restore from, and inspect it (table/row checks) |
| before committing. Restoring requires typing `overwrite` to confirm, snapshots |
| the *current* DB as a `pre-restore-…db` rollback key first, then calls |
| `restartSpace()` (needs `HF_TOKEN`) to restart the Space onto the restored file. |
|
|
| --- |
|
|
| ## 5. Deploy / rebuild |
|
|
| - **Redeploy the web app:** push to GitHub `main`, then in the Space use |
| **Settings → Factory rebuild** (re-clones latest `main`). |
| - **Push local env vars as Space secrets:** `HF_TOKEN=… node scripts/sync-env.mjs |
| .env.production.local jay-hank/mixly` — reads `KEY=value` lines and pushes each |
| as a secret via the HF API. The script's built-in default Space is still |
| `solora-hq/Mixly` (wrong for this deployment), so always pass `jay-hank/mixly` |
| explicitly as the second arg. Changes apply on the next rebuild/restart. |
| - **Deploy the Shopify Function / extensions:** that is a *separate* target, run from |
| your machine (needs the Shopify CLI + Partner auth) — `npm run app:deploy`. The |
| container also runs this non-fatally during a Space build (see Dockerfile), gated |
| on the `SHOPIFY_CLI_PARTNERS_TOKEN` build secret. |
|
|
| > After changing scopes or the app URL, re-open the app in the store to re-consent. |
|
|
