fix(deploy): create /opt/staging and write compose.yml on every deploy

The VPS had no /opt/staging directory or compose file, causing the deploy
step to fail with "No such file or directory". Now the workflow:
- Creates /opt/staging if missing
- Writes compose.yml on every deploy (keeps it in sync with CI)
- Touches .env so podman compose doesn't error if no secrets file exists yet

Also adds deploy/staging/.env.example documenting runtime secrets that must
be set manually on the VPS after first deploy.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/deploy-staging.yml

@@ -194,6 +194,41 @@ jobs:
           podman pull --tls-verify=false "${REGISTRY}/storefront:staging"
           podman pull --tls-verify=false "${REGISTRY}/admin:staging"
 
+          mkdir -p /opt/staging
+
+          # Write the compose file on every deploy so it stays in sync with CI.
+          # REGISTRY is interpolated by bash here (not by podman compose), so the
+          # actual registry host:port/owner value is embedded in the file.
+          cat > /opt/staging/compose.yml << 'COMPOSE'
+name: petloft-staging
+
+services:
+  storefront:
+    image: ${REGISTRY}/storefront:staging
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    env_file:
+      - path: .env
+        required: false
+
+  admin:
+    image: ${REGISTRY}/admin:staging
+    restart: unless-stopped
+    ports:
+      - "3001:3001"
+    env_file:
+      - path: .env
+        required: false
+COMPOSE
+          # Substitute the actual registry value into the compose file
+          sed -i "s|\${REGISTRY}|${REGISTRY}|g" /opt/staging/compose.yml
+
+          # Create a minimal .env if one doesn't exist yet.
+          # Runtime secrets (CLERK_SECRET_KEY, etc.) should be added manually
+          # to /opt/staging/.env on the VPS after first deploy.
+          touch /opt/staging/.env
+
           cd /opt/staging
           podman compose up -d --remove-orphans
 

deploy/staging/.env.example

@@ -0,0 +1,15 @@
+# Runtime secrets for staging containers.
+# Copy this file to /opt/staging/.env on the VPS and fill in the values.
+# NEXT_PUBLIC_* vars are already baked into the Docker images at build time —
+# only server-side secrets that Next.js reads at runtime go here.
+
+# Storefront — Clerk server-side key
+CLERK_SECRET_KEY=
+
+# Admin — Clerk server-side key (different Clerk instance)
+# Add a second .env or use per-service env_file if keys differ per container.
+# For now a single .env is shared; storefront ignores keys it doesn't use.
+
+# Stripe (used by storefront checkout server actions if any)
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=