Subdomains & Access Management

Guide for creating new subdomains, managing Cloudflare Access policies, and maintaining security.

---

Table of Contents

1. Domain Structure
2. Creating New Subdomains
3. Access Policies
4. Testing Workflows
5. Troubleshooting

---

Domain Structure

Our domain structure follows this pattern:

ourlantern.app
├── ourlantern.app              (production root)
├── dev.ourlantern.app          (development staging)
├── docs.ourlantern.app         (documentation site)
├── docs.dev.ourlantern.app     (dev documentation)
├── storybook.ourlantern.app    (component library)
├── storybook.dev.ourlantern.app (dev component library)
├── api.ourlantern.app          (future: backend/API)
└── blog.ourlantern.app         (future: marketing site)

Current Domains

Domain	Environment	Purpose	Access Policy
ourlantern.app	Production	Main app (live)	lantern-app (PIN)
dev.ourlantern.app	Development	Team testing/staging	lantern-app-dev (PIN)
docs.ourlantern.app	Production	Documentation site	Public (or PIN if restricted)
docs.dev.ourlantern.app	Development	Dev documentation	Public (or PIN if restricted)
storybook.ourlantern.app	Production	Component library	Public (recommended)
storybook.dev.ourlantern.app	Development	Dev component library	Public (recommended)
*.ourlantern.app	Any	Catch-all wildcard	lantern-app-wildcard (PIN)

---

Creating New Subdomains

Scenario: Adding a New Subdomain (e.g., api.ourlantern.app)

Step 1: Code Your Feature

Create a feature branch and develop your subdomain code:

git checkout -b feature/api-endpoint dev
# ... implement API functionality ...
git push origin feature/api-endpoint

Step 2: Test on Preview URL

Cloudflare auto-generates a preview URL:

• https://feature-api-endpoint.lantern-app-dev.pages.dev
• Already protected by dev Access app
• Test thoroughly before proceeding

Step 3: Merge to Dev

git checkout dev
git merge feature/api-endpoint
git push origin dev

Result: Deploys to dev.ourlantern.app for staging.

Step 4: Add DNS Record in Cloudflare

1. Go to Cloudflare Dashboard → DNS
2. Click Add record
3. Configure:
   • Type: CNAME
   • Name: api
   • Content: lantern-app.pages.dev (or your prod project)
   • Proxy status: Proxied (orange cloud)
   • TTL: Auto
4. Save

Step 5: Create/Update Access App

Option A: Use Wildcard App (Recommended)

• The existing lantern-app-wildcard app already protects *.ourlantern.app
• No new Access app needed
• New subdomain automatically inherits PIN policy

Option B: Create Specific Access App

1. Go to Cloudflare Zero Trust → Access → Applications
2. Click Add an application → Self-hosted
3. Configure:
   • Application name: lantern-app-api
   • Domain: api.ourlantern.app
4. Add same PIN policy as other apps
5. Save

Step 6: Deploy to Production

Once tested in dev:

git checkout main
git merge dev
git push origin main

Result: Lives at https://api.ourlantern.app (protected by Access)

---

Access Policies

Current Access Setup

Three Access applications protect our domains:

1. lantern-app (Production)

   • Domain: ourlantern.app
   • Policy: One-time PIN
   • Purpose: Main app, live users

2. lantern-app-dev (Development)

   • Domain: dev.ourlantern.app
   • Policy: One-time PIN
   • Purpose: Team testing/staging

3. lantern-app-wildcard (Catch-all)

   • Domain: *.ourlantern.app
   • Policy: One-time PIN
   • Purpose: Protect any future subdomains automatically

Modifying Access Policies

Change Authentication Method

For example, switch from "One-time PIN" to "Email Domain":

1. Go to Cloudflare Zero Trust → Access → Applications
2. Click the app name (e.g., lantern-app-dev)
3. Click Edit
4. Go to Policies tab
5. Click your existing policy
6. Change Require from "One-time PIN" to "Email addresses":
   • Add allowed email addresses (e.g., team members)
7. Save policy

Add a New Policy

Example: Allow GitHub organization members:

1. Go to Applications → Click app → Edit → Policies
2. Click Add a policy
3. Configure:
   • Action: Allow
   • Include rule:
     • Selector: GitHub Organization
     • Value: Your org name
   • Session duration: 24 hours
4. Save

Remove/Disable a Policy

1. Go to Applications → Click app → Edit → Policies
2. Click the X button on the policy to delete
3. Save

Session Management

Adjust how long users stay logged in:

1. Click app → Edit → Click policy
2. Under Session duration, choose:
   • 15 minutes (most secure)
   • 1 hour
   • 24 hours (current default)
   • Custom duration
3. Save

---

Testing Workflows

Testing New Subdomains Locally

Since new subdomains require Cloudflare DNS, test locally first:

# In your dev server, you can test by mocking the subdomain
# For example, test API logic without hitting Cloudflare DNS
npm run dev

# Visit http://localhost:5173 and test your code

Testing on Preview URL

Feature branches auto-deploy to preview URLs:

https://feature-api-endpoint.lantern-app-dev.pages.dev

Access PIN: Same as dev environment (request from team)

Testing in Dev Environment

After merging to dev:

https://dev.ourlantern.app

Full staging environment with dev Firebase, staging data, etc.

Testing in Production

After merging to main:

https://ourlantern.app

Live environment — use real Firebase, real data, and careful QA!

---

Common Tasks

Add a New Team Member to Access

1. Go to Access → Applications
2. Click the app (e.g., lantern-app-dev)
3. Click Edit → Policies
4. Edit the PIN or email policy
5. Add their email address
6. Save

Disable Access Temporarily

⚠️ Warning: This makes your site public. Use with caution.

1. Go to Access → Applications
2. Click app → Edit
3. Click the Delete button at the bottom
4. Confirm deletion
5. The domain becomes public (no more Access protection)

To re-enable: Create a new Access app with the same domain and policy.

Monitor Access Logs

1. Go to Access → Logs
2. View recent authentication attempts
3. Filter by domain, date range, or user
4. Useful for debugging access issues

Set Different PIN for Different Environments

Currently all use the same PIN. To differentiate:

1. Edit dev Access app → Click policy
2. Change PIN code
3. Save

Now dev has a different PIN than prod (useful for separating access).

---

Security Best Practices

✅ Do

• ✅ Keep Access enabled on all non-local environments
• ✅ Use strong, random PIN codes
• ✅ Limit who has access to production
• ✅ Review Access logs regularly
• ✅ Test new subdomains on preview before production
• ✅ Use the wildcard app for automatic protection

❌ Don't

• ❌ Share PIN codes publicly or in code
• ❌ Disable Access on production without a reason
• ❌ Use weak PIN codes (like "1234")
• ❌ Forget to add DNS records for new subdomains
• ❌ Commit environment secrets to Git

---

Troubleshooting

New Subdomain Not Working

Error: 404 or "Not Found"

Checks:

1. Is the DNS record created? Go to DNS tab and verify CNAME exists
2. Is it proxied (orange cloud)? If not, enable proxying
3. Did you wait for DNS propagation? (Usually instant, but can take 5 mins)
4. Is the code actually deployed to the right Pages project?

Fix:

# Verify DNS record
nslookup api.ourlantern.app

# Should resolve to lantern-app.pages.dev or lantern-app-dev.pages.dev

Access Redirecting to Wrong Domain

Error: dev.ourlantern.app redirects to ourlantern.app

Cause: Multiple Access apps covering the same domain

Fix:

1. Go to Access → Applications
2. Check for duplicate entries
3. Ensure each domain has only ONE app
4. Delete duplicates if found

PIN Not Working

Error: "Invalid PIN" even though you entered it correctly

Cause: PIN sent to your email may have expired (usually 15 mins)

Fix:

1. Go back and request a new PIN
2. Check spam/junk folder
3. If still issues, contact admin to reset

---

Related Documentation

• DEPLOYMENT.md — Main deployment guide
• ENVIRONMENT_SETUP.md — Setting up environments
• PWA.md — Progressive Web App setup