DEPLOY.md

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.