Deploy to Render

Deploy your Clarity documentation to Render for hassle-free Node.js hosting with automatic deployments and built-in database support.

Why Render?

• 🚀 Native Node.js support - Perfect for Astro SSR
• 🔄 Auto-deploy from GitHub
• 🆓 Free tier available (auto-sleeps after 15 min)
• 🗄️ PostgreSQL included - Ready for v1.1 user management
• 🔒 Automatic SSL certificates
• 🌍 Global CDN included
• 📊 Built-in metrics and logs

Prerequisites

• Render account (sign up free)
• GitHub repository with your Clarity project
• OAuth credentials (optional, for authentication)

Deployment Architecture

Clarity uses two separate services on Render:

1. Frontend Service - Astro SSR documentation (main app)
2. Backend Service - Express OAuth authentication server

Both deploy automatically from your GitHub repository.

Quick Deploy (Recommended)

The fastest way to deploy is using the included render.yaml blueprint:

Step 1: Connect Repository

1. Go to Render Dashboard
2. Click New → Blueprint
3. Connect your GitHub account
4. Select your clarity repository
5. Click Apply

Render will automatically:

• ✅ Create both frontend and backend services
• ✅ Set up environment variables
• ✅ Configure build commands
• ✅ Deploy both apps

Timeline: 3-5 minutes for first deploy

Step 2: Configure Environment Variables

After blueprint deployment, update these variables:

Frontend Service (clarity-docs):

1. Go to service → Environment
2. Update PUBLIC_SITE_URL to your Render URL (e.g., https://clarity-docs.onrender.com)

Backend Service (clarity-backend):

1. Go to service → Environment
2. Update FRONTEND_URL to match frontend URL
3. Add OAuth credentials (if using authentication):
   • GOOGLE_CLIENT_ID
   • GOOGLE_CLIENT_SECRET
   • GITHUB_CLIENT_ID
   • GITHUB_CLIENT_SECRET

Note: SESSION_SECRET is auto-generated by Render.

Step 3: Redeploy

Click Manual Deploy → Deploy latest commit on both services.

Your site will be live at https://clarity-docs.onrender.com!

Manual Deploy (Alternative)

If you prefer manual setup or customization:

Create Frontend Service

1. Dashboard → New → Web Service
2. Connect your GitHub repository
3. Configure:

Settings:

• Name: clarity-docs
• Region: Oregon (or closest to you)
• Branch: main
• Runtime: Node
• Build Command: pnpm install && pnpm build
• Start Command: node dist/server/entry.mjs
• Plan: Free

Environment Variables:

4. Click Create Web Service

Create Backend Service

1. Dashboard → New → Web Service
2. Select same GitHub repository
3. Configure:

Settings:

• Name: clarity-backend
• Region: Same as frontend
• Branch: main
• Runtime: Node
• Build Command: cd backend && pnpm install --prod
• Start Command: cd backend && node server.js
• Plan: Free

Environment Variables:

4. Click Create Web Service

Step 4: Update OAuth Callbacks

After deployment, update your OAuth provider settings:

Google Cloud Console

1. Go to Google Cloud Console
2. APIs & Services → Credentials
3. Edit your OAuth 2.0 Client ID
4. Add to Authorized redirect URIs:

   https://clarity-backend.onrender.com/auth/google/callback

GitHub OAuth App

1. Go to GitHub Developer Settings
2. Select your OAuth App
3. Update Authorization callback URL:

   https://clarity-backend.onrender.com/auth/github/callback

Step 5: Verify Deployment

1. Visit your frontend URL: https://clarity-docs.onrender.com
2. Navigate through documentation
3. Test search (Cmd/Ctrl + K)
4. Try authentication (if configured)
5. Check SSL certificate (should be automatic)

Note: Free tier apps sleep after 15 minutes of inactivity. First request after sleep takes 1-2 seconds to wake up.

Custom Domain Setup

Add Custom Domain

1. Go to your frontend service → Settings → Custom Domains
2. Click Add Custom Domain
3. Enter your domain (e.g., docs.yourdomain.com)
4. Add DNS records at your domain provider:

For subdomain (docs.yourdomain.com):

Type: CNAME
Name: docs
Value: clarity-docs.onrender.com

For root domain (yourdomain.com):

Type: A
Name: @
Value: [Render IP addresses - shown in dashboard]

5. SSL certificate auto-provisions in 5-10 minutes

Update Environment Variables

After custom domain is active:

Frontend service:

• Update PUBLIC_SITE_URL to https://docs.yourdomain.com

Backend service:

• Update FRONTEND_URL to match
• Update OAuth callbacks to use custom domain

Automatic Deployments

Render auto-deploys on every push to your main branch:

# Make changes
git add .
git commit -m "Update documentation"
git push origin main

# Render automatically:
# 1. Detects push
# 2. Runs build
# 3. Deploys new version
# 4. Live in 2-3 minutes

Deployment timeline:

• Build: 1-2 minutes
• Deploy: 30-60 seconds
• Total: 2-3 minutes

Environment-Specific Configuration

Enable Preview Environments

1. Service → Settings → Deploy
2. Enable Preview Environments
3. Every pull request gets its own preview URL

Add Database (for v1.1+)

1. Dashboard → New → PostgreSQL
2. Name: clarity-db
3. Region: Same as services
4. Plan: Free (256 MB)
5. Click Create Database
6. In your backend service, add environment variable:

   DATABASE_URL: [Copy from database Internal Connection String]

Troubleshooting

Service Won’t Start

Check logs:

1. Service → Logs tab
2. Look for errors in startup

Common issues:

• Missing environment variables
• Build command failed
• Wrong start command path

Solution: Verify build/start commands match your project structure.

”App Not Responding”

Free tier sleep behavior:

• Apps sleep after 15 min inactivity
• First request wakes app (1-2s delay)

Solution: Upgrade to paid plan ($7/mo) for always-on.

OAuth Callback Errors

Check:

• FRONTEND_URL matches actual frontend URL
• OAuth provider callbacks use correct backend URL
• No trailing slashes in URLs

Build Fails

Check:

• Node version compatibility (Render uses Node 20)
• pnpm is available (Render auto-installs)
• All dependencies in package.json

View build logs: Service → Logs → Filter by “build”

Slow Cold Starts

Free tier apps cold start in ~1-2 seconds.

Solutions:

• Upgrade to paid plan (no sleep)
• Use UptimeRobot to ping every 14 minutes (keeps warm)
• Accept cold starts (reasonable for docs)

Advanced Configuration

Add Redis Cache

For faster page loads (optional):

1. Dashboard → New → Redis
2. Free plan available
3. Add REDIS_URL to frontend service
4. Implement caching in your app

Enable CDN

1. Service → Settings → Advanced
2. Enable Render CDN
3. Static assets cached globally

Custom Build Command

Edit render.yaml or service settings:

# Build with specific Node version
buildCommand: nvm use 20 && pnpm install && pnpm build

# Build with environment-specific flags
buildCommand: NODE_ENV=production pnpm build

Health Checks

Render automatically pings your app to check health.

Configure in service settings:

• Health Check Path: / (or custom endpoint)
• Health Check Grace Period: 30 seconds

Cost Optimization

Free Tier Limits

Per service:

• 750 hours/month free
• 512 MB RAM
• 0.1 CPU
• Auto-sleep after 15 min

For always-on:

• $7/month per service
• 2 services = $14/month (frontend + backend)

Reduce Costs

1. Use free tier for testing

   • Upgrade production only
   • Keep staging on free tier

2. Combine services (advanced)

   • Run backend as child process of frontend
   • Single service = $7/month

3. Use external OAuth (free)

   • Auth0, Clerk, Supabase Auth
   • Eliminate backend service cost

Monitoring & Logs

View Logs

1. Service → Logs
2. Filter by: all, build, deploy, run
3. Search for specific errors
4. Real-time tail

Metrics

1. Service → Metrics
2. View:
   • CPU usage
   • Memory usage
   • Request count
   • Response times

Alerts

1. Service → Settings → Notifications
2. Enable:
   • Deploy success/failure
   • Service health issues
   • Custom alerts

Deployment Checklist

Before First Deploy

• GitHub repository connected
• OAuth credentials ready (if using auth)
• render.yaml configured
• Environment variables documented

After Deployment

• Both services running
• Frontend accessible
• Backend health check passing
• SSL certificate active
• OAuth callbacks updated
• Custom domain configured (optional)

For Production

• Upgrade to paid plan (no sleep)
• Add database (for v1.1)
• Configure alerts
• Set up uptime monitoring
• Document deployment process

Comparison: Render vs Others

What’s Next?

• Configure authentication
• Set up custom domain
• Add database for v1.1
• Configure monitoring
• Optimize performance

Resources

• Render Documentation
• Render Community
• Render Status
• GitHub Repository

Need Help?

Render Support:

• Render Docs
• Community Forum
• Email: support@render.com

Clarity Support:

• GitHub Issues
• Deployment Guide