Deployment UX Feedback: Improving the self-hosting experience

[gabiudrescu]

Context

I recently deployed CloudMeet to Cloudflare Pages following the README instructions. While I eventually got it working, the experience was challenging. This issue aims to provide constructive feedback and spark discussion on how to improve the deployment UX for self-hosters.

Summary of Issues Encountered

During deployment, I encountered several bugs that are now tracked separately:

• #8 - Build fails due to duplicate variable declaration
• #9 - Event type creation fails silently
• #10 - Calendar availability only checks primary calendar
• #11 - SSR causes 500 errors on direct URL access

The Biggest Challenge: Lack of Observability

The most frustrating aspect of deployment was not knowing what went wrong when things failed.

What I Experienced

1. Generic 500 errors everywhere - When something fails, you get {"message":"Internal Error"} with zero context about what actually happened.

2. No access to logs - There's no easy way to see server-side logs. wrangler pages deployment tail exists but:

   • Requires knowing the specific deployment ID
   • Often doesn't capture the errors you need
   • Doesn't work well in non-interactive contexts

3. Silent authentication failures - When I set secrets with trailing newlines (using echo instead of printf), the OAuth flow entered an infinite redirect loop. No error was logged anywhere - I had to guess that the secrets were malformed.

4. SSR vs Client-side mystery - The booking page worked when navigating from the homepage but returned 500 when accessed directly. Same URL, same code, completely different behavior - and no indication why.

5. Database issues invisible - When I accidentally created two users (logged in with wrong account first), the public pages silently showed the wrong user. No warning, no error - just confusing behavior.

Impact

Each issue required significant debugging time:

• Reading source code to understand what could fail
• Making educated guesses about root causes
• Trial and error to find solutions

Suggestions for Improvement

1. Better Error Messages

Instead of:

{"message":"Internal Error"}

Consider:

{
  "message": "Failed to create event type",
  "code": "DB_INSERT_FAILED",
  "details": "Cannot call toString on null value",
  "file": "event-types/new/+page.server.ts",
  "line": 119
}

Even if detailed errors are only shown in development mode, it would help immensely.

2. Health Check Endpoint

A /api/health endpoint that verifies:

• Database connection works
• KV namespace is accessible
• Required environment variables are set
• OAuth configuration is valid

This would catch 90% of deployment issues immediately.

3. Deployment Verification Script

A npm run verify-deployment command that:

• Checks all required secrets are set
• Validates secret formats (no newlines, correct patterns)
• Tests database connectivity
• Verifies OAuth redirect URIs match APP_URL

4. Better Documentation for Edge Cases

The README covers the happy path well, but doesn't address:

• What to do when you get a 500 error
• How to debug authentication issues
• The single-user assumption and its implications
• Required wrangler.toml settings like nodejs_compat

5. Request Tracing

Add a request ID to all responses:

X-Request-Id: abc123

And log it server-side so errors can be correlated.

What Worked Well

To be fair, some things were smooth:

• The GitHub Actions workflow is well-structured
• D1 and KV setup via wrangler is straightforward
• The application itself is well-designed once running

Questions for Discussion

1. Is there appetite for improving observability, or is this considered out of scope for a "simple" Calendly alternative?
2. Would a --verbose deployment mode that logs more details be feasible?
3. Should the app detect common misconfigurations and warn users?

Happy to contribute PRs if there's alignment on the direction.

[gabiudrescu]

Step-by-Step Deployment Experience

To provide more context, here's the chronological journey of deploying CloudMeet to Cloudflare Pages with a custom domain:

---

Step 1: Clone and Sync Repository

Action: Forked repo, fetched upstream changes
Result: ✅ Smooth

---

Step 2: Build the Application

Action: npm install && npm run build
Result: ❌ Build failed

Issue encountered: Duplicate cacheKey variable declaration in availability endpoints.
→ Filed as #8

Resolution: Manually edited source files to remove duplicate declarations.

---

Step 3: Create Cloudflare Resources

Action: Create D1 database and KV namespace via wrangler CLI
Result: ✅ Smooth

wrangler d1 create cloudmeet-db
wrangler kv namespace create cloudmeet-kv

---

Step 4: Initialize Database

Action: Apply schema and migrations
Result: ⚠️ Minor issues

Migrations showed "column already exists" errors because schema.sql already includes migrated columns. Not blocking, but confusing for first-time deployers.

---

Step 5: Create Google OAuth Credentials

Action: Attempted to use gcloud CLI
Result: ❌ Not supported

gcloud CLI doesn't support creating OAuth 2.0 web application credentials. Had to use Google Cloud Console UI instead.

Suggestion: Document this limitation in README.

---

Step 6: Set Environment Secrets

Action: Set secrets using source .env && echo "$VAR" | wrangler pages secret put
Result: ❌ Silent failure

Secrets were set with trailing newlines, causing authentication to fail later. No error was shown during secret creation.

Resolution: Used printf and jq for clean piping:

printf "value" | wrangler pages secret put SECRET_NAME --project=cloudmeet

---

Step 7: Deploy to Cloudflare Pages

Action: wrangler pages deploy
Result: ✅ Deployed successfully

---

Step 8: Configure Custom Domain

Action: Attempted to add custom domain via wrangler CLI
Result: ❌ Not supported

Wrangler doesn't have a command for adding custom domains to Pages projects. Had to use Cloudflare API directly.

Additional issue: API adds the domain but doesn't create DNS record. Had to manually add CNAME in Cloudflare DNS.

---

Step 9: Test Authentication

Action: Navigate to /auth/login
Result: ❌ Infinite redirect loop

OAuth flow kept redirecting between Google and the app. No error messages anywhere.

Root cause: Trailing newlines in secrets (from Step 6).

Resolution: Re-set all secrets properly, redeploy.

---

Step 10: First Login

Action: Logged in with Google account
Result: ⚠️ Wrong account used

Accidentally logged in with personal Google account instead of intended admin account. This created a user record in the database.

Impact discovered later: Public pages query SELECT ... FROM users LIMIT 1, returning the wrong user.

---

Step 11: Create Event Type

Action: Fill form and submit without "Override calendar settings" checked
Result: ❌ 500 Internal Error

No indication of what went wrong. Had to read source code to discover .toString() was being called on null values.

→ Filed as #9

Workaround: Enable "Override calendar settings" checkbox.

---

Step 12: View Public Booking Page

Action: Navigate to homepage
Result: ❌ Shows "No Available Meeting Types"

Event type was created but not visible. No error shown.

Root cause: Two users in database; homepage shows first user's events, but event was created by second user.

Resolution: Manually delete wrong user from D1:

wrangler d1 execute cloudmeet-db --remote --command="DELETE FROM users WHERE email = 'wrong@email.com'"

---

Step 13: Test Booking Page Direct Access

Action: Access /event-slug directly or refresh page
Result: ❌ 500 Internal Error

Page works when navigating from homepage (client-side), but returns 500 on direct URL or refresh (SSR).

→ Filed as #11

---

Step 14: Test Actual Booking

Action: Book a time slot that conflicts with shared calendar event
Result: ⚠️ Double-booking allowed

Availability check only queries primary calendar, ignoring shared/subscribed calendars.

→ Filed as #10

---

Summary

Step	Outcome	Issue
1. Clone repo	✅	-
2. Build	❌	#8
3. Create CF resources	✅	-
4. Init database	⚠️	Confusing errors
5. Google OAuth	❌	gcloud limitation
6. Set secrets	❌	Silent newline issue
7. Deploy	✅	-
8. Custom domain	❌	API + manual DNS
9. Test auth	❌	Redirect loop
10. First login	⚠️	Wrong account
11. Create event	❌	#9
12. View public page	❌	Two users issue
13. Direct URL access	❌	#11
14. Test booking	⚠️	#10

5 steps worked smoothly, 9 steps had issues.

This is not meant as criticism - CloudMeet is a great project! But the deployment experience could be significantly improved with better error messages, validation, and documentation.

[dennisklappe]

Thanks for the detailed write-up!

Logs: Server-side logs are available in the Cloudflare dashboard under Workers & Pages

Did you use the GitHub Actions workflow to deploy? Looking at your steps, it seems like you deployed manually with wrangler CLI. The https://github.com/dennisklappe/CloudMeet/blob/main/.github/workflows/deploy.yml handles most of what you ran into—D1/KV creation, migrations, and secrets (written directly to wrangler.toml, avoiding the newline issues).

The /api/health endpoint idea is good though!

[gabiudrescu]

I'm not that familiar with cloudflare, but I used this repo to get familiar with. Anyway, glad I was helpful