# Cloudflare Deployment Lessons
## Publishing and Securing code::core DNS Analytics

Version: 2.0
Last Updated: May 2026

---

## Deployment Model
You are deploying two planes:
1. Teaching plane: static lesson site on Cloudflare Pages.
2. Data plane: private analytics services protected by Cloudflare Tunnel and optionally exposed via Workers.

---

## Lesson A: Publish the Teaching Site (Cloudflare Pages)
Objective: make the course content accessible to your team.

Interpret:
- This lesson teaches separation of content publishing from backend service deployment.
- You verify that lesson content can be versioned, built, and served consistently from source control.

Run:
1. Push repository to GitHub.
2. Connect repository in Cloudflare Pages.
3. Use no framework preset.
4. Build output directory: .

Checkpoint:
- Site loads at pages.dev URL.
- index.html renders correctly on desktop and mobile.

---

## Lesson B: Route a Custom Domain
Objective: provide stable internal/external entrypoint.

Interpret:
- This lesson teaches stable addressing through domain abstraction.
- You verify continuity for learners and operators even if provider endpoints change.

Run:
- Add CNAME from your domain to pages.dev target.

Checkpoint:
- DNS propagates.
- Site available via custom domain over HTTPS.

---

## Lesson C: Protect Private Services with Cloudflare Tunnel
Objective: keep PostgreSQL and internal services off the public internet.

Interpret:
- This lesson teaches outbound-only exposure using Cloudflare Tunnel.
- You verify private service reachability without opening inbound firewall ports.

Run:
1. Install cloudflared on your DNS analytics host.
2. Authenticate and create tunnel.
3. Configure ingress rules.
4. Register tunnel DNS route.
5. Start cloudflared service.

Checkpoint:
- Service is reachable through tunnel hostname.
- No inbound firewall holes required for public access.

---

## Lesson D: Build API Endpoints with Workers
Objective: expose curated analytics, not raw database access.

Interpret:
- This lesson teaches API policy enforcement at the edge with Workers.
- You verify that only curated analytics are exposed with controlled response behavior.

Run:
- Implement endpoint handlers for top domains, categories, heatmap.
- Add CORS and basic caching headers.
- Deploy with wrangler.

Checkpoint:
- API endpoints return expected JSON.
- Error handling returns controlled messages.

---

## Lesson E: Add Security Controls
Objective: prevent unauthorized reads and abuse.

Interpret:
- This lesson teaches layered security for identity, access scope, and request control.
- You verify that unauthorized access is blocked and abusive load is bounded.

Run:
- Add token/JWT checks.
- Use read-only database role for analytics endpoints.
- Apply rate limiting strategy.

Checkpoint:
- Unauthorized requests are denied.
- Query load is bounded under abuse scenarios.

---

## Lesson F: Operate and Troubleshoot
Objective: keep deployment stable over time.

Interpret:
- This lesson teaches multi-layer operations monitoring across content, edge, tunnel, and data planes.
- You verify fault isolation by checking each layer independently during troubleshooting.

Run:
- Monitor Pages deploy logs.
- Monitor Worker errors and latency.
- Monitor tunnel health.
- Verify rollup freshness in database.

Checkpoint:
- You can identify which layer failed: content, edge API, tunnel, or database.

---

## MikroTik Lab Integration Note
If your home lab uses:
- network 10.10.10.0/24
- router 10.10.10.10
- local domain codeandcore.home

Then keep local authoritative DNS on your resolver and only publish sanitized analytics summaries at the edge.

---

## Verification Runbook
1. Open lesson site URL.
2. Call one API endpoint.
3. Verify tunnel connectivity.
4. Run SQL check for latest rollup date.
5. Confirm no sensitive internal endpoint is directly exposed.

---

## Common Failures and Meaning
- Pages deploy fails: content/build issue.
- Worker 5xx: endpoint logic or binding issue.
- Tunnel unavailable: cloudflared or route issue.
- Empty API results: rollup not executed or query window too narrow.

---

## Completion Standard
Deployment is complete when:
- Lesson site is reachable.
- API is reachable and authenticated.
- Database remains private.
- Team can run verification runbook successfully.