Skip to main content

Migration History - September 2025

Overview​

Successfully migrated internal documentation platform from legacy repository (ravish-symphonycore/internal-docs) to new organization repository (symphonycore-org/internal-docs) with new Firebase project and Cloudflare Pages deployment.

DetailValue
Duration~4 hours
StatusCompleted
Production URLhttps://team.symphonycore.com
Preview URLhttps://symphonycore-docs.pages.dev

Root Cause Analysis​

Primary Issue​

The production deployment was building from the wrong GitHub repository (ravish-symphonycore/internal-docs), making it impossible to update production without access to that team member's repository.

Secondary Issues​

  1. Logo 403 Error: Cloudflare R2 bucket returned 403 Forbidden for logo.svg
  2. Repository Mismatch: Configuration files referenced different repository names
  3. Authentication Not Working: Firebase authentication gate was not integrated
  4. Environment Variable Issues: Firebase config couldn't access environment variables at runtime

Migration Strategy​

Decision: Create New Cloudflare Pages Project​

Reason: Unable to disconnect the old repository from existing Cloudflare Pages project due to permissions.

Approach: Create fresh deployment with correct repository and new Firebase project, then transfer custom domain.

Changes Implemented​

1. Repository Migration​

  • From: ravish-symphonycore/internal-docs
  • To: symphonycore-org/internal-docs
  • Updated git remote and pushed all commits

2. Configuration Updates​

  • package.json: Updated repository URL
  • docusaurus.config.js: Changed organizationName, updated GitHub links, fixed logo source

3. Logo Fix​

  • Issue: Cloudflare R2 returned 403 Forbidden
  • Solution: Bundled logo locally in static/img/logo.svg

4. Firebase Setup​

  • Project ID: symphonycore-internal-docs
  • Authentication: Google SSO only
  • Domain Restriction: @symphonycore.com accounts only
  • Authorized Domains: team.symphonycore.com, symphonycore-docs.pages.dev

5. Authentication Integration​

  • Created src/theme/Root.js - Wraps app with AuthProvider
  • Updated src/component/firebase_init.js - Hardcoded Firebase config

6. Cloudflare Pages Setup​

  • Project Name: symphonycore-docs
  • Repository: symphonycore-org/internal-docs
  • Branch: master
  • Build Command: npm run build
  • Output Directory: build

Architecture After Migration​

┌─────────────────────────────────────┐
│  symphonycore-org/internal-docs     │
│  (New org repo - full control)      │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│  Cloudflare Pages: symphonycore-docs│
│  (New project - our control)        │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│  Firebase: symphonycore-internal... │
│  (New project - full control)       │
└──────────────────┬──────────────────┘
                   │
                   ▼
┌─────────────────────────────────────┐
│  team.symphonycore.com              │
│  ✅ Logo bundled locally            │
│  ✅ Authentication enforced         │
│  ✅ Latest content                  │
│  ✅ Full control                    │
└─────────────────────────────────────┘

Lessons Learned​

1. Environment Variables in Docusaurus/React​

  • Browser can't access Node.js process.env directly
  • Solution: Hardcode public values (Firebase API keys are safe to expose)

2. Firebase API Key Security​

  • Firebase API keys are designed to be public
  • Security comes from domain restrictions and authentication rules
  • Safe to commit to repositories

3. Cloudflare Pages Permissions​

  • Repository connections are tied to the user who created them
  • Other team members may not be able to disconnect/modify
  • Solution: Create new project instead of modifying existing

4. Docusaurus Authentication​

  • Use src/theme/Root.js to wrap entire app with auth provider
  • Don't rely on window.__DOCUSAURUS_CONTEXT__

5. Logo/Asset Management​

  • External asset URLs can cause CORS/auth issues
  • Better approach: Bundle assets locally in static/ directory

Key Resources​

ResourceURL
Repositoryhttps://github.com/symphonycore-org/internal-docs
Cloudflare Dashboardhttps://dash.cloudflare.com/ → symphonycore-docs
Firebase Consolehttps://console.firebase.google.com/project/symphonycore-internal-docs
Production URLhttps://team.symphonycore.com
Preview URLhttps://symphonycore-docs.pages.dev

Common Operations​

Deploy to Production:

git add .
git commit -m "Your changes"
git push origin master
# Automatic deployment triggers

Add New Firebase Domain:

  1. Go to Firebase Console → Authentication → Settings → Authorized domains
  2. Click "Add domain"
  3. Enter domain (e.g., new-docs.symphonycore.com)

Migration Completed: September 30, 2025

Authentication Migration - December 2025

Overview​

Migrated authentication from Firebase Auth (client-side) to Cloudflare Access (edge-level) for simpler architecture and support for external users.

DetailValue
Duration~2 hours
StatusCompleted
DateDecember 8, 2025

Why We Migrated​

IssueFirebaseCloudflare Access
External usersNot supportedSupported via email OTP
Bundle size+200KB (Firebase SDK)No additional JS
Auth locationClient-sideEdge (before content)
Code complexity~270 lines auth code0 lines
Session managementFirebase SDKCloudflare (automatic)

Changes Made​

Files Removed​

  • src/theme/Root.js - Auth wrapper
  • src/component/firebase_init.js - Firebase config
  • src/component/auth_wrapper_component.js - Auth UI

Files Updated​

  • docusaurus.config.js - Removed Firebase clientModules and customFields
  • package.json - Removed firebase dependency

Cloudflare Access Setup​

  • Application: Internal Docs
  • Domain: team.symphonycore.com
  • Policy: Allow emails ending in @symphonycore.com
  • Identity Provider: One-time PIN (email OTP)
  • Session Duration: 1 month

New Architecture​

User Request
     │
     ▼
┌─────────────────────────────────┐
│      Cloudflare Access          │
│   - One-time PIN via email      │
│   - @symphonycore.com policy    │
│   - 1 month session             │
└──────────────┬──────────────────┘
               │
               ▼
┌─────────────────────────────────┐
│      Cloudflare Pages           │
│   - Static Docusaurus site      │
│   - No auth code                │
└─────────────────────────────────┘

Managing Access​

For @symphonycore.com users: No action needed - automatic access

For external users:

  1. Go to Cloudflare Zero Trust Dashboard (https://one.dash.cloudflare.com)
  2. Access controls → Applications → Internal Docs
  3. Edit policy to add specific email addresses

Firebase Cleanup (Optional)​

The Firebase project symphonycore-internal-docs is no longer used for authentication. It can be:

  • Disabled (Authentication → Settings → disable sign-in methods)
  • Deleted entirely if not used for other purposes

Firebase Console: https://console.firebase.google.com/project/symphonycore-internal-docs