TCG Platform — Staging Environment¶

Status: Deployed ✅ Deployed: 2026-04-22 — Phase 1 (Foundation). See Phase 1 Kickoff Plan. URL: https://tcg-staging.exzentcg.com Snapshot: initial-deploy Phase 2 applied: applied 2026-04-22 ✅ — TCG module scaffold, seed fixtures, stock-location scenarios. See Phase 2 Findings. Phase 3 applied: in progress ⏳ — Shopee inbound connector live; awaiting end-to-end validation with real Shopee credentials. See Phase 3 Findings. (Status flips to ✅ after a real test order completes the inbound flow + status update + escrow capture.) Phase 5 applied: applied 2026-05-12 ✅ — Operator dashboard live at https://dashboard-staging.exzentcg.com (Cloudflare Worker, gated by Access). Server-side /admin/dashboard/* endpoints (orders / exceptions / inventory / variant-editor / staff) all rendering real data. See Phase 5 Findings.

Purpose¶

Hosts the Medusa application for the TCG Commerce Operations Platform in a staging environment on the Proxmox host. Used during Phases 1–9 for integration testing, UAT, and parallel-run validation before Phase 10 go-live. This container runs only the Medusa server + its Postgres + Redis sidecars — no customer-facing traffic.

Why staging on Proxmox? Mirrors the homelab self-hosted pattern already used for n8n (CT 102) and Homepage (CT 103). No cloud spend until production host is decided in Phase 10. Cloudflare Tunnel + Access gates external access the same way as other internal services.

Deployment Details¶

Deployment Plan¶

Step 1 — Create LXC¶

From the Proxmox host (192.168.0.200):

pct create 105 local:vztmpl/debian-12-standard_12.12-1_amd64.tar.zst \
  --hostname tcg-staging \
  --cores 2 \
  --memory 4096 \
  --swap 2048 \
  --rootfs local-lvm:20 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.0.55/24,gw=192.168.0.1,firewall=1 \
  --nameserver 192.168.0.1 \
  --features nesting=1 \
  --onboot 1 \
  --start 1

Step 2 — Install Docker + set DNS¶

pct enter 105
apt update && apt upgrade -y && apt install curl -y
curl -fsSL https://get.docker.com | sh
exit

# Fix DNS from Proxmox host (router DNS has known ghcr.io lookup issues — see CT 103)
pct set 105 --nameserver 1.1.1.1
pct reboot 105

Step 3 — Deploy Medusa + sidecars¶

The Medusa repo is ExzenTCG/tcg-platform (created in Phase 1, task D1). As of 2026-05-09 the repo is a yarn-workspaces monorepo — Medusa lives at apps/server/ (Phase 5 PR #51). On the staging CT:

pct enter 105
mkdir -p /opt/tcg-platform && cd /opt/tcg-platform
git clone https://github.com/ExzenTCG/tcg-platform.git .
# Compose lives at apps/server/docker-compose.yml after the monorepo move.
# It uses `name: tcg-platform` so volumes/networks stay `tcg-platform_*`
# regardless of cwd, but the runbook standard is to invoke from apps/server/.
cd apps/server
# Place the staging .env here (gitignored). Required keys: every Phase 3
# key (DATABASE_URL, JWT_SECRET, COOKIE_SECRET, SHOPEE_*) plus:
# - COOKIE_DOMAIN=.exzentcg.com (dashboard-staging can forward cookies)
# - PUBLIC_API_BASE_URL=https://tcg-staging.exzentcg.com (Phase 7 Shopee URLs)
docker compose up -d --build
docker compose ps
docker compose logs --tail 100 medusa

Expected containers (from ExzenTCG/tcg-platform/docker-compose.yml):

• medusa — Node.js 20 + Yarn Berry, exposes 192.168.0.55:9000
• postgres — Postgres 16, container-internal only (port not published)
• redis — Redis 7, container-internal only (port not published)

First-boot checks:

• Entrypoint runs yarn medusa db:migrate then yarn medusa db:sync-links before medusa start. Migrations are idempotent — ~30s first boot creating ~150 tables, a no-op after.
• Once logs show Server is ready on port: 9000, the admin UI is at http://192.168.0.55:9000/app (direct LAN / Tailscale) or https://tcg-staging.exzentcg.com/app/ once the tunnel + NPM are in place.
• Seed the initial Admin user: docker compose exec medusa yarn medusa user --email <admin-email> --password <password> (password rotated immediately after first login).

Step 4 — LXC Firewall¶

Create /etc/pve/firewall/105.fw on the Proxmox host:

[OPTIONS]
enable: 1

[RULES]
IN ACCEPT -source +edge_gw -p tcp -dport 9000      # Only edge-gateway can reach Medusa
IN ACCEPT -source +admin_desktop -p tcp -dport 22   # SSH from admin
IN ACCEPT -source +admin_desktop -p tcp -dport 9000 # Direct LAN access for dev
IN DROP                                              # Block all other inbound
OUT ACCEPT -dest +router_gw -p udp -dport 53        # DNS
OUT ACCEPT -dest +router_gw -p tcp -dport 53        # DNS
OUT ACCEPT -p udp -dport 53                          # Public DNS fallback (1.1.1.1)
OUT DROP -dest +lan_subnet                           # Lateral movement prevention
OUT ACCEPT -p tcp -dport 443                         # HTTPS — npm registry, Medusa upgrades, outbound APIs
OUT ACCEPT -p tcp -dport 80                          # HTTP fallback (apt, some image registries)

Verify after boot:

# From inside CT 105

# 1. LAN lateral-movement should be blocked (OUT DROP +lan_subnet)
curl -s --connect-timeout 3 http://192.168.0.16 -o /dev/null -w "HTTP %{http_code}\n"
# Expected: HTTP 000 (LAN blocked)

# 2. Proxmox host should be blocked (same OUT DROP rule)
curl -s --connect-timeout 3 https://192.168.0.200:8006 -o /dev/null -w "HTTP %{http_code}\n"
# Expected: HTTP 000 (Proxmox blocked)

# 3. Medusa self-reachability — use LOOPBACK, not the LAN IP.
# iptables OUTPUT fires even for packets destined to this container's own
# LAN NIC IP (192.168.0.55), so testing via the LAN IP hits the +lan_subnet
# DROP before Medusa. Loopback avoids the issue entirely.
curl -s --connect-timeout 3 http://localhost:9000/health -o /dev/null -w "HTTP %{http_code}\n"
# Expected: HTTP 200 (Medusa reachable via loopback)

External reachability test — from CT 101 edge-gateway, proves NPM will be able to proxy traffic to this container:

pct enter 101
curl -s --connect-timeout 3 http://192.168.0.55:9000/health -o /dev/null -w "HTTP %{http_code}\n"
# Expected: HTTP 200 (+edge_gw is explicitly allowed inbound on 9000 by 105.fw)
exit

Step 5 — Edge-gateway firewall update¶

Edit /etc/pve/firewall/101.fw on the Proxmox host. Add before the OUT DROP -dest +lan_subnet line:

OUT ACCEPT -dest 192.168.0.55 -p tcp -dport 9000   # Proxy to tcg-staging Medusa

Step 6 — NPM Proxy Host¶

Open NPM admin: http://192.168.0.51:81 → Proxy Hosts → Add:

Step 7 — Cloudflare Tunnel Route¶

Cloudflare → Zero Trust → Networks → Tunnels → exzentcg-homelab → Published application routes → Add:

Cloudflare auto-creates the DNS CNAME (proxied).

Step 8 — Cloudflare Access policy¶

Zero Trust → Access → Applications → Add → Self-hosted:

Policy — team-access (new, broader than owner-only — D1/D2/D3 all need access during Phase 1+):

• Action: Allow
• Selector: Emails → (D1, D2, D3 emails — add to homelab/00_secrets/Credentials Index.md)

Step 8b — Dashboard static-asset Access bypass¶

For dashboard-staging.exzentcg.com, create a second, higher-precedence Access application for public static build assets:

This bypass applies only to content-hashed public assets, not to dashboard pages or Medusa API calls. It is required because the Next.js Worker serves SSR HTML and client bundles from the same hostname. If Access protects /_next/static/*, the browser receives a cross-origin Cloudflare Access redirect for module scripts and server-action assets; the page looks rendered but client-only widgets such as the /imports/new variant picker stay inert. More-specific Access apps win by path, so keep this above the catch-all dashboard Access app.

Step 9 — Seed first Admin user¶

After the app is up and before handing off to the team:

pct enter 105
cd /opt/tcg-platform
docker compose exec medusa yarn medusa user \
  --email admin@exzentcg.com \
  --password <temporary-bootstrap-password>

Log in once at https://tcg-staging.exzentcg.com/app, force password rotation, then invite the rest of the team through the admin UI.

Step 10 — Verification¶

• [ ] https://tcg-staging.exzentcg.com/app → Cloudflare Access login → Medusa admin login page
• [ ] Admin login succeeds with the seeded user
• [ ] Admin UI shows empty products, locations, orders (expected — no seed data)
• [ ] docker compose logs medusa shows no error lines
• [ ] Postgres migrations applied: docker compose exec postgres psql -U medusa -d medusa -c "\dt" returns ~150+ tables

Step 11 — Snapshot¶

pct snapshot 105 initial-deploy --description "tcg-staging initial deployment — Medusa v2 + Postgres 16 + Redis 7"

Updates needed elsewhere (post-deploy)¶

• [ ] Add tcg-staging to homelab/00_secrets/Credentials Index.md (SSH key, seeded admin pw, Postgres pw, Redis pw, team email allowlist)
• [ ] Update homelab/01_planning/Phase 1/Architecture Diagram.md — add CT 105 to the IP address map and Mermaid diagram
• [ ] Add CT 105 to homelab/02_setup_logs/Phase 1 Health Checks.md
• [ ] Update Homepage services.yaml on CT 103 with a card for tcg-staging (internal LAN only — don't expose widget API key externally)
• [ ] Update tcg-platform/phase-1-plan.md to flip this runbook from Planned to Deployed

Troubleshooting (to be filled in during deploy)¶

Shopee connector troubleshooting¶

Phase 6 — multi-environment Shopee¶

Applied + validated 2026-05-15 — Phase 6 originally stored sandbox + live Shopee credentials in shopee_environment_credentials (Postgres table; secrets AES-256-GCM-encrypted with a key derived from JWT_SECRET). Phase 7 migrated those rows into shopee_connector_profile and dropped the legacy table. Keep this section for historical path-routed URL behavior; use the Phase 7 section below for the current operator workflow. See Phase 6 Implementation Plan, Phase 6 Findings, and Phase 7 Findings.

Path-routed URLs¶

Each environment registers its own webhook + OAuth-callback URLs in its own Shopee Partner Center:

Legacy /connectors/shopee/webhook (no env suffix) keeps working — it aliases to sandbox. Operators didn't need to re-register the existing Sandbox webhook URL when upgrading to Phase 6, but live URLs had to be registered separately in the live Partner Center. Phase 7's profile detail screen now shows the current per-profile URLs, including ?profile_id=....

Adding live Shopee to staging (operator workflow)¶

1. Create the Live Shopee Open Platform app (separate from the Sandbox app you already have). Note the live partner_id, partner_key, and push_partner_key.
2. Register redirect URL in the Live Partner Center: https://tcg-staging.exzentcg.com (Shopee accepts only the bare origin — see note above).
3. Open the dashboard at /connectors/shopee and click the Live tab.
4. Save credentials in the form: paste the live partner_id, partner_key, push_partner_key, shop_id, region (GLOBAL for SG live), and the URLs from the table above. Click Save credentials.
5. Click Connect to start the OAuth flow against your live shop. Authorize in Shopee, return to dashboard with ?status=connected.
6. Click Switch to Live when you want live to become the active environment. (Inactive sandbox webhooks will now 200-drop until you switch back.)

SHOPEE_* env vars are now advisory¶

After PR-1 lands and the boot-seeder runs, the SHOPEE_* env vars on CT 105 (SHOPEE_PARTNER_ID, SHOPEE_PARTNER_KEY, SHOPEE_PUSH_PARTNER_KEY, SHOPEE_SHOP_ID, SHOPEE_REGION, SHOPEE_API_BASE_URL, SHOPEE_DEFAULT_LOCATION_ID, SHOPEE_PUSH_URL, SHOPEE_OAUTH_CALLBACK_URL, SHOPEE_OAUTH_RETURN_URL) are only read on first-ever boot to seed the sandbox row. Subsequent reads come from the encrypted DB row.

To rotate sandbox credentials, edit them via the dashboard — not via .env. Editing .env post-seed has no effect on running behavior.

SHOPEE_OAUTH_RETURN_URL (the URL the OAuth callback redirects back to after token exchange) and JWT_SECRET (the source of the AES key for credential encryption) remain env-var-driven — they're infrastructure-level config, not connector credentials.

Don't edit legacy credential rows via raw SQL¶

Direct UPDATE … WHERE environment = '<env>' against the old Phase 6 table appeared to land, but the Medusa service kept reading the pre-update value until the credential cache was invalidated. Discovered during the 2026-05-15 smoke-test cleanup: a manual UPDATE … SET partner_id = NULL showed in psql immediately but the /admin/dashboard/connectors/shopee?env=live endpoint kept returning the prior value. Mikro-ORM's identity map across requests is the suspect; the Worker-side fetch is cache: 'no-store' so it's not the dashboard.

The supported edit path is the dashboard's profile UI — profile save / activation / reconnect endpoints invalidate the relevant SDK cache after writes. Operators using the UI never hit this. Only direct DB edits do.

If you must UPDATE connector rows directly (e.g., a maintenance script), restart Medusa afterwards (docker compose restart medusa) to force-clear all caches before the next request hits.

JWT_SECRET rotation caveat¶

The encrypted secret columns (partner_key_encrypted, push_partner_key_encrypted, access_token_encrypted, refresh_token_encrypted) are decryptable only with the JWT_SECRET they were written under. Rotating JWT_SECRET without re-encrypting the rows leaves the connector unable to verify webhook signatures or make outbound API calls. Phase 6 / 7 do not ship rotation tooling; if you need to rotate:

1. Read the existing rows + decrypt with the old JWT_SECRET (docker compose exec medusa node -e "..." snippet)
2. Set the new JWT_SECRET in .env + compose
3. PATCH the secrets back via the dashboard (which re-encrypts under the new key)
4. Restart Medusa

Plan a maintenance window — webhooks during steps 2–3 will fail signature verification.

Phase 7 — Shopee Connector Overhaul¶

Applied + validated 2026-05-16 — The connector now uses an N-profile model.

1. Environment variable: PUBLIC_API_BASE_URL is mandatory. It drives dynamic push and OAuth callback URLs:
2. Webhook: ${PUBLIC_API_BASE_URL}/connectors/shopee/webhook?env=${env_type}&profile_id=${profileId}
3. OAuth callback: ${PUBLIC_API_BASE_URL}/connectors/shopee/oauth/callback/${env_type}?profile_id=${profileId}
4. Profile management: Use the dashboard to manage shopee_connector_profile rows. Each profile identifies a region, partner, and shop tuple. Exactly one profile per env_type is active.
5. Location selection: Use the Refresh Locations button in the profile UI to sync warehouse IDs from Shopee into shopee_warehouse_location for dropdown selection.
6. Advisory locks: Proactive token refresh is serialized via Postgres advisory locks to prevent refresh-token rotation races.
7. Cutover state: the migration window is closed on current tcg-platform/main. Migration20260516220000_drop_legacy_credentials_and_plaintext_tokens re-synced any drift from shopee_environment_credentials, dropped that legacy table, and dropped plaintext shopee_auth_token.access_token / refresh_token. Current token bytes live only in access_token_encrypted and refresh_token_encrypted; diagnostics expose metadata only.