LGS Forge

Appearance

Documentation Deployment Setup Checklist ​

Quick checklist for setting up automated documentation deployment to Firebase Hosting.

Prerequisites ​

  • [ ] Firebase CLI installed (npm install -g firebase-tools)
  • [ ] Firebase project created
  • [ ] Firebase login complete (firebase login)
  • [ ] GitHub repository with Actions enabled

Firebase Setup ​

1. Create Hosting Sites ​

bash
# Create main app site
firebase hosting:sites:create lgs-ledger-app

# Create docs site
firebase hosting:sites:create lgs-ledger-docs

✅ Record your site IDs for the next steps.

2. Configure .firebaserc ​

bash
# Copy template
cp .firebaserc.example .firebaserc

# Edit with your actual IDs
# Replace:
# - your-firebase-project-id → YOUR_PROJECT_ID
# - your-main-app-site-id → lgs-ledger-app (or your choice)
# - your-docs-site-id → lgs-ledger-docs (or your choice)

3. Apply Hosting Targets ​

bash
firebase target:apply hosting app lgs-ledger-app
firebase target:apply hosting docs lgs-ledger-docs

4. Verify Configuration ​

bash
# List hosting sites
firebase hosting:sites:list

# Check targets
firebase target:list

GitHub Actions Setup ​

1. Generate Firebase Service Account ​

Option A: Automatic (Recommended)

bash
firebase init hosting:github

Follow prompts to:

  • Select your GitHub repository
  • Generate service account
  • Add secrets to GitHub automatically

Option B: Manual

  1. Go to Firebase Console
  2. Select your project
  3. Project Settings → Service Accounts
  4. Click Generate New Private Key
  5. Download the JSON file
  6. Copy entire JSON content

2. Add GitHub Secrets ​

Go to: GitHub Repository → Settings → Secrets and variables → Actions

Add these secrets:

Secret NameValueWhere to Get
FIREBASE_SERVICE_ACCOUNTFull JSON from service accountFirebase Console → Project Settings → Service Accounts
FIREBASE_PROJECT_IDYour project ID (e.g., lgs-ledger-prod)Firebase Console → Project Settings
FIREBASE_APP_SITE_IDMain app site ID (e.g., lgs-ledger-app)Run firebase hosting:sites:list
FIREBASE_DOCS_SITE_IDDocs site ID (e.g., lgs-ledger-docs)Run firebase hosting:sites:list

To add a secret:

  1. Click New repository secret
  2. Name: Enter secret name
  3. Value: Paste the value
  4. Click Add secret

3. Verify Workflow File ​

Check that .github/workflows/deploy-docs.yml exists:

bash
ls -la .github/workflows/deploy-docs.yml

Local Testing ​

Before pushing, test locally:

1. Install Docs Dependencies ​

bash
npm run docs:install
# Or: cd docs && npm install

2. Build Docs Locally ​

bash
npm run docs:build

Expected output: docs/.vitepress/dist/

3. Preview Build ​

bash
npm run docs:preview

Visit: http://localhost:4173

4. Test Manual Deployment ​

bash
# Deploy to Firebase (production)
npm run deploy:docs

Deployment Verification ​

1. Push to Main Branch ​

bash
git add .
git commit -m "Add docs deployment workflow"
git push origin main

2. Monitor GitHub Actions ​

  1. Go to Actions tab in GitHub
  2. Find "Deploy Documentation" workflow
  3. Watch the deployment progress
  4. Check for green checkmark ✅

3. Verify Live Site ​

Default Firebase URL:

  • App: https://lgs-ledger-app.web.app
  • Docs: https://lgs-ledger-docs.web.app

Visit your docs site and verify:

  • [ ] Site loads correctly
  • [ ] Neobrutalism theme is applied
  • [ ] All pages are accessible
  • [ ] Navigation works
  • [ ] Search works

Custom Domain Setup ​

1. Add Custom Domain in Firebase ​

For Docs Site:

  1. Firebase Console → Hosting
  2. Select docs site
  3. Click Add custom domain
  4. Enter: docs.lgsforge.com
  5. Firebase provides DNS configuration

2. Configure DNS ​

Add DNS records with your domain provider:

Option A: A Records (Recommended)

Type: A
Name: docs
Value: 151.101.1.195  (or IPs from Firebase)
Value: 151.101.65.195

Option B: CNAME

Type: CNAME
Name: docs
Value: lgs-ledger-docs.web.app

3. Wait for SSL Certificate ​

  • DNS Propagation: 15 minutes - 24 hours
  • SSL Certificate: Automatic, shown in Firebase Console
  • Status: Check Firebase Console → Hosting → Domain status

4. Verify Custom Domain ​

bash
# Check DNS propagation
nslookup docs.lgsforge.com

# Test HTTPS
curl -I https://docs.lgsforge.com

Expected: HTTP/2 200 with SSL certificate

Testing the Workflow ​

Manual Trigger Test ​

  1. Go to Actions → Deploy Documentation
  2. Click Run workflow
  3. Choose preview environment
  4. Click Run workflow
  5. Check Firebase Console for preview URL

Automatic Trigger Test ​

  1. Edit a file in docs/ (e.g., add a comment)
  2. Commit and push to main
  3. Workflow should trigger automatically
  4. Check Actions tab for progress

Troubleshooting Checklist ​

If deployment fails, check:

  • [ ] Firebase service account JSON is valid
  • [ ] FIREBASE_SERVICE_ACCOUNT secret exists in GitHub
  • [ ] FIREBASE_PROJECT_ID matches your actual project
  • [ ] Hosting sites exist: firebase hosting:sites:list
  • [ ] Targets applied: firebase target:list
  • [ ] .firebaserc has correct IDs
  • [ ] docs/package-lock.json exists and is committed
  • [ ] GitHub Actions is enabled for repository

Success Criteria ​

Deployment is successful when:

✅ GitHub Action completes with green checkmark ✅ Firebase Console shows new release ✅ https://lgs-ledger-docs.web.app shows updated content ✅ https://docs.lgsforge.com resolves (if custom domain configured) ✅ SSL certificate is active (HTTPS works) ✅ All documentation pages load correctly ✅ Neobrutalism theme is applied

Maintenance ​

Regular Tasks ​

After docs changes:

  • Push to main → automatic deployment
  • No manual intervention needed

Updating dependencies:

bash
cd docs
npm update
npm run build  # Test build
git add package-lock.json
git commit -m "Update docs dependencies"
git push

Monitoring:

  • Check GitHub Actions tab for deployment status
  • Monitor Firebase Console for usage/analytics
  • Review deployment logs if issues occur

Quick Reference ​

Common Commands ​

bash
# Local development
npm run docs:dev          # Dev server
npm run docs:build        # Production build
npm run docs:preview      # Preview build

# Deployment
npm run deploy:docs       # Deploy docs only
npm run deploy:all        # Deploy app + docs

# Firebase CLI
firebase hosting:sites:list       # List sites
firebase target:list              # List targets
firebase hosting:channel:list     # List deployments

Important Files ​

.firebaserc                          # Firebase project config
firebase.json                        # Hosting configuration
.github/workflows/deploy-docs.yml    # GitHub Action workflow
docs/.vitepress/config.js            # VitePress config
docs/.vitepress/theme/custom.css     # Neobrutalism theme

URLs ​

Need Help?

  • Check FIREBASE_DOCS_DEPLOYMENT.md for detailed instructions
  • Check .github/workflows/README.md for workflow documentation
  • Review GitHub Actions logs for errors
  • Consult Firebase Hosting documentation

Last Updated: January 2026