Lantern

Appearance

Cloudflare Setup Checklist for Docs Subdomain ​

Complete this checklist to set up the documentation subdomain deployment using Cloudflare's automatic Git integration (same method as your main app).

Prerequisites ​

  • [ ] Cloudflare account with ourlantern.app domain
  • [ ] Admin access to cattreedev/lantern_app GitHub repository
  • [ ] 10 minutes of time

No API tokens or GitHub secrets needed! This uses the same automatic Git integration as your main app deployment.

Step 1: Create Production Docs Project ​

  1. Go to Cloudflare Dashboard
  2. Navigate to Workers & Pages → Pages
  3. Click Create a project
  4. Click Connect to Git
  5. Select your GitHub account and repository: cattreedev/lantern_app
  6. Configure the project:
    • Project name: lantern-docs
    • Production branch: main
    • Build command: npm run docs:build
    • Build output directory: docs/.vitepress/dist
    • Root directory: (leave empty)
  7. Click Save and Deploy

Checkpoint: ✅ Production project created and connected to GitHub

Step 2: Create Development Docs Project ​

  1. Go back to Workers & Pages → Pages
  2. Click Create a project again
  3. Click Connect to Git
  4. Select the same repository: cattreedev/lantern_app
  5. Configure the project:
    • Project name: lantern-docs-dev
    • Production branch: dev ⚠️ (NOT main!)
    • Build command: npm run docs:build
    • Build output directory: docs/.vitepress/dist
    • Root directory: (leave empty)
  6. Click Save and Deploy

Checkpoint: ✅ Development project created

Step 3: Add Custom Domains ​

Production Domain ​

  1. Open the lantern-docs project
  2. Go to Settings tab
  3. Click Domains & accounts in the sidebar
  4. Click Set up a custom domain
  5. Enter: docs.ourlantern.app
  6. Click Continue
  7. Cloudflare will automatically create DNS records

Checkpoint: ✅ docs.ourlantern.app domain configured

Development Domain ​

  1. Open the lantern-docs-dev project
  2. Go to Settings tab
  3. Click Domains & accounts
  4. Click Set up a custom domain
  5. Enter: docs.dev.ourlantern.app
  6. Click Continue

Checkpoint: ✅ docs.dev.ourlantern.app domain configured

Step 4: Verify DNS Records ​

  1. Go to Cloudflare Dashboard → Select your ourlantern.app zone
  2. Click DNS → Records
  3. Verify these CNAME records exist (Cloudflare created them automatically):
Type    Name      Target                         Proxy Status
CNAME   docs      lantern-docs.pages.dev         Proxied (orange)
CNAME   docs      lantern-docs-dev.pages.dev     Proxied (orange)  [Note: should be "docs.dev"]

Note: The second record should have name "docs.dev" not "docs-dev". The domain setup in Step 3 handles this correctly.

Checkpoint: ✅ DNS records verified

Step 5: Test the Deployment ​

Test Dev Deployment ​

  1. Make a small change to any file in docs/ (e.g., add a space to a markdown file)
  2. Commit and push to dev branch:
    bash
    git add docs/
git commit -m "test: Trigger docs deployment"
git push origin dev
  3. Go to Cloudflare Dashboard → Pages → lantern-docs-dev
  4. Watch the Deployments tab (should start building within seconds)
  5. After ~2-3 minutes, visit https://docs.dev.ourlantern.app

Expected result: Docs site loads successfully

Checkpoint: ✅ Dev deployment working

Test Production Deployment ​

  1. Merge your changes to main:
    bash
    git checkout main
git merge dev
git push origin main
  2. Watch Cloudflare Dashboard → Pages → lantern-docs
  3. Visit https://docs.ourlantern.app

Expected result: Production docs site loads

Checkpoint: ✅ Production deployment working

How It Works ​

Automatic Deployment:

  • Cloudflare monitors your GitHub repository
  • When you push to main or dev, Cloudflare automatically:
    1. Detects the push
    2. Runs npm run docs:build
    3. Deploys the built files to the appropriate subdomain
    4. Updates the site in ~2-3 minutes

No manual steps needed! It works exactly like your main app deployment at ourlantern.app and dev.ourlantern.app.

Troubleshooting ​

Build Fails ​

Problem: Deployment fails in Cloudflare

Solution:

  1. Check Cloudflare Pages deployment logs
  2. Common issues:
    • Node version mismatch (should auto-detect from package.json)
    • Missing dependencies (should auto-install)
    • Build output directory incorrect (should be docs/.vitepress/dist)

DNS Not Resolving ​

Problem: docs.ourlantern.app shows "This site can't be reached"

Solution:

  1. Check DNS records in Cloudflare dashboard
  2. Ensure CNAME is proxied (orange cloud)
  3. Wait 5 minutes for propagation
  4. Try nslookup docs.ourlantern.app

Changes Not Appearing ​

Problem: Pushed changes but site looks the same

Solution:

  1. Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)
  2. Check Cloudflare Pages to ensure deployment succeeded
  3. Verify you pushed to the correct branch (dev vs main)

Wrong Environment Deployed ​

Problem: docs.dev.ourlantern.app shows production content

Solution:

  1. Verify lantern-docs-dev project is connected to dev branch
  2. Check Pages project settings in Cloudflare
  3. Ensure you pushed to dev branch, not main

Success Criteria ​

You're done when all these are true:

  • ✅ lantern-docs Cloudflare Pages project exists
  • ✅ lantern-docs-dev Cloudflare Pages project exists
  • ✅ Both projects are connected to GitHub (automatic Git integration)
  • ✅ docs.ourlantern.app domain is configured and working
  • ✅ docs.dev.ourlantern.app domain is configured and working
  • ✅ Pushing to dev auto-deploys to dev subdomain
  • ✅ Pushing to main auto-deploys to production subdomain
  • ✅ Documentation site is accessible at both URLs

What Happens Now? ​

On every push to dev:

  • Cloudflare automatically builds and deploys to docs.dev.ourlantern.app in ~2-3 min
  • No manual steps required

On every push to main:

  • Cloudflare automatically builds and deploys to docs.ourlantern.app in ~2-3 min
  • No manual steps required

On pull requests:

  • Cloudflare creates preview deployments automatically
  • Preview URL appears in the PR (e.g., abc123.lantern-docs-dev.pages.dev)
  • Test docs changes before merging

It's completely automatic, just like your main app!

Last updated: 2026-01-10

Built with VitePress

Copyright © 2026 Lantern