120 lines
3.3 KiB
Markdown
120 lines
3.3 KiB
Markdown
# Parallel Migration Guide
|
||
|
||
Run your sovereign stack alongside Shopify during migration — no cutover risk, no forced downtime.
|
||
|
||
## Overview
|
||
|
||
Five phases:
|
||
|
||
1. **Deploy** — Stand up the NotShop bundle (Replit + Fly.io)
|
||
2. **Mirror** — Import your product catalog from Shopify Storefront API
|
||
3. **Route** — Send a small percentage of traffic to your sovereign stack
|
||
4. **Validate** — Confirm orders, payments, and customer accounts work correctly
|
||
5. **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
|
||
|
||
1. Fork [git.wellspr.ing/WellBuilder/notshop-bundle](https://git.wellspr.ing/WellBuilder/notshop-bundle)
|
||
2. Import into Replit (New Repl → Import from Git)
|
||
3. Add environment variables in the Secrets tab (see `.env.example`)
|
||
4. Click Run — storefront starts on your Replit domain
|
||
|
||
### 1.2 Deploy the Fly.io routing proxy
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
npm run catalog:import
|
||
```
|
||
|
||
Pulls products, variants, and collections from the Shopify Storefront API into your PostgreSQL database.
|
||
See [storefront-api.md](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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
flyctl secrets set SOVEREIGN_WEIGHT=100
|
||
flyctl deploy
|
||
```
|
||
|
||
All traffic now goes to your sovereign stack. Then:
|
||
|
||
1. Cancel Shop Campaigns (if not already paused — do this first)
|
||
2. Export order history from Shopify Admin as CSV
|
||
3. 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](https://notshop.org/report) or open an issue in this repository.
|