Skip to main content

OWL Site Deployment Instructions

Prerequisites​

Initial Setup (One-time)​

  1. Install Firebase CLI

    npm install -g firebase-tools

  2. Login to Firebase

    firebase login

  3. Initialize Firebase in the project

    firebase init hosting
    • Select "Use an existing project" or create new
    • Set public directory to: build
    • Configure as single-page app: Yes
    • Set up automatic builds with GitHub: No (can add later)
    • Don't overwrite build/index.html

Deploy Process​

  1. Build the Docusaurus site

    npm run build

  2. Deploy to Firebase

    firebase deploy --only hosting

  3. View your site

    • Firebase will provide URL: https://PROJECT-ID.web.app
    • Also available at: https://PROJECT-ID.firebaseapp.com

Custom Domain Setup​

  1. In Firebase Console → Hosting → Add custom domain
  2. Add DNS records as instructed
  3. SSL certificate auto-provisioned

CI/CD with GitHub Actions​

Create .github/workflows/deploy.yml:

name: Deploy to Firebase Hosting
on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run build
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: '${{ secrets.GITHUB_TOKEN }}'
          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
          channelId: live
          projectId: your-project-id

Alternative: GCP Cloud Storage + CDN​

Setup​

  1. Create GCS bucket:

    gsutil mb -l us-central1 gs://owl-site-static/
    gsutil web set -m index.html -e 404.html gs://owl-site-static/

  2. Make bucket public:

    gsutil iam ch allUsers:objectViewer gs://owl-site-static/

  3. Deploy:

    npm run build
    gsutil -m rsync -R -d build/ gs://owl-site-static/

  4. For HTTPS, add Cloud Load Balancer (costs ~$16/month)

Quick Commands Reference​

# Firebase
firebase deploy --only hosting          # Deploy
firebase hosting:channel:deploy preview # Preview deployment
firebase serve                          # Local preview

# Cloud Storage
gsutil -m rsync -R -d build/ gs://bucket-name/  # Sync files
gsutil web set -m index.html gs://bucket-name/  # Set index page

# Docusaurus
npm run build     # Production build
npm run serve     # Test production build locally
npm run clear     # Clear cache if issues

Troubleshooting​

  • Build fails: Run npm run clear then rebuild
  • Deploy fails: Check firebase-debug.log
  • 404 errors: Ensure single-page app rewrite is enabled
  • Slow loads: Check if CDN is enabled in Firebase Console

Costs​

  • Firebase Hosting: Free tier includes 10GB storage, 360MB/day bandwidth
  • Cloud Storage: ~$0.020/GB storage + bandwidth costs
  • Typical documentation site: Usually stays within free tier

Notes​

  • Firebase Hosting includes automatic SSL, global CDN, and easy rollbacks
  • For the OWL site, Firebase is recommended due to simplicity and free tier
  • Custom domain can be added after initial deployment
  • Preview channels useful for PR reviews