Parallel Migration Guide

Run your sovereign stack alongside Shopify during migration — no cutover risk, no forced downtime.

Overview

Five phases:

Deploy — Stand up the NotShop bundle (Replit + Fly.io)
Mirror — Import your product catalog from Shopify Storefront API
Route — Send a small percentage of traffic to your sovereign stack
Validate — Confirm orders, payments, and customer accounts work correctly
Cut over — Move all traffic; cancel Shopify

Customers always hit one URL. The Fly.io routing layer handles the split transparently.

Phase 1: Deploy

1.1 Fork and deploy to Replit

Fork git.wellspr.ing/WellBuilder/notshop-bundle
Import into Replit (New Repl → Import from Git)
Add environment variables in the Secrets tab (see .env.example)
Click Run — storefront starts on your Replit domain

1.2 Deploy the Fly.io routing proxy

flyctl auth login
flyctl launch --copy-config --name yourstore-proxy
flyctl secrets set SHOPIFY_ORIGIN=https://yourstore.myshopify.com
flyctl secrets set SOVEREIGN_ORIGIN=https://yourrepl.replit.app
flyctl secrets set SOVEREIGN_WEIGHT=0
flyctl deploy

1.3 Point your domain to Fly

Update DNS (Bunny.net recommended) to CNAME your domain to the Fly.io app:

yourstore.com  CNAME  yourstore-proxy.fly.dev

At this point 100% of traffic still routes to Shopify. Your sovereign stack is deployed but idle.

Phase 2: Mirror — import product catalog

npm run catalog:import

Pulls products, variants, and collections from the Shopify Storefront API into your PostgreSQL database. See storefront-api.md for token setup.

Re-run anytime to sync changes. For real-time sync, configure the webhook bridge (server/webhook-bridge.ts).

Phase 3: Route — split traffic

Once the catalog is imported and the storefront renders correctly:

flyctl secrets set SOVEREIGN_WEIGHT=10   # 10% to sovereign, 90% to Shopify
flyctl deploy

The proxy assigns a session cookie on first visit so each visitor stays on the same backend for their entire session.

Ramp gradually: 10 → 25 → 50 → 90 → 100. Each step is a 30-second Fly.io deploy.

Phase 4: Validate

While traffic is split:

Orders — Check /admin for successful orders
Payments — Confirm Authorize.net transactions in your Authorize.net control panel
Checkout flow — Go through checkout yourself
Customer accounts — Test account creation and login

Phase 5: Cut over

flyctl secrets set SOVEREIGN_WEIGHT=100
flyctl deploy

All traffic now goes to your sovereign stack. Then:

Cancel Shop Campaigns (if not already paused — do this first)
Export order history from Shopify Admin as CSV
Downgrade from Shopify Plus (requires notice period per your contract)

Timeline

Most merchants complete migration in 2–4 weeks:

Week	Work
1	Deploy, mirror catalog, validate storefront
2	Route 10% traffic, monitor orders
3	Ramp to 50%, tune any issues
4	Cut over to 100%, cancel Shopify

Support

Questions: notshop.org/report or open an issue in this repository.

3.3 KiB Raw Blame History Unescape Escape