A complete guide for indie developers and free-tier builders: from zero to a live uptime dashboard at your own domain.

Why Your Side Project Needs This

You've deployed your Next.js blog or SaaS app. It's live, it works, and you're proud of it. But here's the uncomfortable truth: you have no idea when it goes down.

Your MongoDB Atlas free cluster might hit its connection limit at 2 AM. Your Vercel serverless function might cold-start and fail silently. A missing environment variable after a redeployment could break auth for every user — and you won't know until someone tweets at you.

Professional teams solve this with status pages and uptime monitors. Tools like Datadog and StatusPage.io charge $20–$400/month. But if you're on the indie/free stack — Vercel Hobby, MongoDB Atlas free tier, Clerk free plan — you don't have that budget.

This guide shows you how to build the same thing for absolutely free using:

A custom /api/health endpoint in Next.js
cron-job.org for free uptime monitoring
A public status page at your own subdomain (e.g., health.yoursite.com)
Cloudflare DNS (free tier) for the custom domain

Part 1: Why Not Just Ping Your Homepage?

The instinct is to point your monitor at https://yoursite.com and call it a day. Don't. Here's why:

cron-job.org has a 64 KB response size limit. A modern Next.js homepage easily exceeds that with HTML, inline styles, hydration scripts, and meta tags. The monitor will fail with "output too large" : marking your site as down even when it's perfectly healthy.

A dedicated /api/health endpoint solves this by returning a tiny JSON payload (~500 bytes) that tells you not just "is the server responding" but "is every service my app depends on actually working?"

This is the difference between a smoke alarm and a fire detection system.

Part 2: Building the Health Check System

The Architecture

The health system has three layers:

GET /api/health

│

▼

route.ts ──────────────────────────────────────

│ Runs all checks in parallel

▼ via Promise.all()

buildHealthReport()

│

├── checkApp() → Is Node.js alive?

├── checkDatabase() → Is MongoDB pingable?

├── checkClerk() → Is auth API reachable?

├── checkCloudinary() → Are image env vars set?

├── checkGemini() → Is AI key present?

├── checkGmail() → Is SMTP configured?

├── checkWebhook() → Is webhook secret set?

└── checkUrlConfig() → Is the base URL valid?

│

▼

Aggregate → summary → HTTP 200 or 503

All 8 checks fire simultaneously. Total response time = the slowest single check, not the sum of all checks.

Step 1 — Create the Core Utilities

Create src/lib/health/checks.js. Start with the two foundational utilities every check depends on.

Utility 1: maskSensitiveValues — Security guard for error messages

When checks fail, JavaScript errors often contain your raw secrets in the message. For example, a MongoDB auth failure exposes your full connection string including password. This utility sanitizes errors before they reach your public JSON response:

const maskSensitiveValues = (message) => {

if (!message) return 'Check failed';

let sanitized = String(message);

// Mask MongoDB credentials: mongodb+srv://user:pass@cluster → mongodb+srv://***:***@cluster

sanitized = sanitized.replace(

/(mongodb(?:\+srv)?:\/\/)([^@\s]+)@/gi,

'$1***:***@'

);

// Mask Clerk secret keys: sk_live_abc123 → sk_live_***

sanitized = sanitized.replace(/(sk_(live|test)_)[A-Za-z0-9_-]+/g, '$1***');

// Mask email addresses: user@example.com → ***@***

sanitized = sanitized.replace(

/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,

'***@***'

);

// Truncate long error messages to 180 chars

return sanitized.length > 180 ? `${sanitized.slice(0, 177)}...` : sanitized;

};

Each regex targets a specific secret format. The truncation at 180 characters prevents enormous error messages from inflating your JSON response.

Utility 2: withTimeout — The race condition pattern

External services can hang indefinitely. A MongoDB Atlas cold connection can take 10+ seconds. Without a timeout, one slow service freezes your entire health check. This utility uses Promise.race() to enforce a hard deadline:

const withTimeout = async (promiseFactory, timeoutMs, checkName) => {

if (!timeoutMs || timeoutMs <= 0) {

return promiseFactory();

}

let timer;

try {

return await Promise.race([

promiseFactory(),

new Promise((_, reject) => {

timer = setTimeout(() => {

reject(new Error(`${checkName} timed out after ${timeoutMs}ms`));

}, timeoutMs);

}),

]);

} finally {

if (timer) clearTimeout(timer); // Always cancel the timer to prevent memory leaks

}

};

Why pass a function (promiseFactory) instead of a Promise directly?

A Promise starts executing the moment it's created. By passing a factory function, withTimeout controls exactly when the work starts — only after both race competitors are set up simultaneously.

The finally block is critical: if the check finishes before the timeout, the setTimeout is still alive in Node's event loop. clearTimeout cancels it, preventing ghost timers from accumulating.

Utility 3: runCheck — The universal wrapper

Every individual check function gets wrapped in runCheck, which handles timing, error catching, and severity routing:

export const runCheck = async (name, options, fn) => {

const startedAt = Date.now();

const { critical = false, timeoutMs = 0 } = options ?? {};

try {

const result = await withTimeout(fn, timeoutMs, name);

const normalizedStatus = result?.status ?? 'ok';

return {

status: normalizedStatus,

critical,

latencyMs: Date.now() - startedAt,

message: result?.message ?? `${name} check passed`,

...(result?.meta ? { meta: result.meta } : {}),

};

} catch (error) {

return {

status: critical ? 'fail' : 'degraded', // Severity routing

critical,

latencyMs: Date.now() - startedAt,

message: maskSensitiveValues(error?.message),

};

}

};

The critical flag is the key design decision here. It separates "my site is completely broken" from "a non-essential service is misconfigured":

`critical: true` + error`critical: false` + error
status = `'fail'`	status = `'degraded'`
HTTP 503 returned	HTTP 200 returned
cron-job.org marks site DOWN	cron-job.org marks site UP
You get emergency alert	You get a warning

Step 2 — Write the Individual Checks

Now write the actual check functions. The pattern is consistent: validate config first, then make a real network call if config exists.

// Check 1: Is the Node.js process alive? Always passes.

const checkApp = async () => ({

status: 'ok',

message: 'Application runtime is healthy',

});

// Check 2: Real MongoDB ping — not just "is the connection open?"

// but actually sends { ping: 1 } to MongoDB Admin

const checkDatabase = async () => {

if (!process.env.MONGODB_URI) {

throw new Error('MONGODB_URI is not configured');

}

await connect(); // Your singleton connection function

const db = mongoose.connection?.db;

if (!db) throw new Error('MongoDB connection is not ready');

await db.admin().ping(); // Real wire-level ping

return {

status: 'ok',

message: 'MongoDB ping succeeded',

meta: { dbName: db.databaseName }, // Extra context in the response

};

};

// Check 3: Live Clerk API call — validates your secret key works

const checkClerk = async () => {

if (!process.env.CLERK_SECRET_KEY) {

return { status: 'degraded', message: 'CLERK_SECRET_KEY is missing' };

}

const client = typeof clerkClient === 'function' ? clerkClient() : clerkClient;

await client.users.getUserList({ limit: 1 }); // Real API call, minimal data

return { status: 'ok', message: 'Clerk API reachable' };

};

// Check 4: Cloudinary — two-stage (env check, then API ping)

const checkCloudinary = async () => {

const required = ['CLOUDINARY_CLOUD_NAME', 'CLOUDINARY_API_KEY', 'CLOUDINARY_API_SECRET'];

const hasAllEnv = (keys) => keys.every((k) => Boolean(process.env[k]));

if (!hasAllEnv(required)) {

return { status: 'degraded', message: 'Cloudinary configuration is incomplete' };

}

await cloudinary.api.ping();

return { status: 'ok', message: 'Cloudinary API reachable' };

};

For services where you only store config (no real-time API call needed), just validate the env vars exist:

const checkGmailConfig = async () => {

if (!process.env.GMAIL_USER || !process.env.GMAIL_APP_PASSWORD) {

return { status: 'degraded', message: 'Gmail SMTP configuration is incomplete' };

}

return { status: 'ok', message: 'Gmail SMTP configuration present' };

};

Step 3 — Orchestrate Everything in `buildHealthReport`

export const buildHealthReport = async () => {

// Fire ALL checks simultaneously

const [app, database, clerk, cloudinaryCheck, ...rest] = await Promise.all([

runCheck('app', { critical: true }, checkApp),

runCheck('database', { critical: true, timeoutMs: 2000 }, checkDatabase),

runCheck('clerk', { critical: false, timeoutMs: 2000 }, checkClerk),

runCheck('cloudinary', { critical: false, timeoutMs: 2000 }, checkCloudinary),

// ... other non-critical checks

]);

const checks = { app, database, clerk, cloudinary: cloudinaryCheck };

const checkValues = Object.values(checks);

const summary = {

total: checkValues.length,

ok: checkValues.filter(c => c.status === 'ok').length,

degraded: checkValues.filter(c => c.status === 'degraded').length,

fail: checkValues.filter(c => c.status === 'fail').length,

criticalFailed: checkValues.filter(c => c.critical && c.status === 'fail').length,

};

// Priority cascade: fail > degraded > ok

const status = summary.criticalFailed > 0 ? 'fail'

: (summary.degraded > 0 || summary.fail > 0) ? 'degraded'

: 'ok';

return {

status,

timestamp: new Date().toISOString(),

uptimeSec: Number(process.uptime().toFixed(2)),

summary,

checks,

};

};

Step 4 — The Route Handler

export const buildHealthReport = async () => {

// Fire ALL checks simultaneously

const [app, database, clerk, cloudinaryCheck, ...rest] = await Promise.all([

runCheck('app', { critical: true }, checkApp),

runCheck('database', { critical: true, timeoutMs: 2000 }, checkDatabase),

runCheck('clerk', { critical: false, timeoutMs: 2000 }, checkClerk),

runCheck('cloudinary', { critical: false, timeoutMs: 2000 }, checkCloudinary),

// ... other non-critical checks

]);

const checks = { app, database, clerk, cloudinary: cloudinaryCheck };

const checkValues = Object.values(checks);

const summary = {

total: checkValues.length,

ok: checkValues.filter(c => c.status === 'ok').length,

degraded: checkValues.filter(c => c.status === 'degraded').length,

fail: checkValues.filter(c => c.status === 'fail').length,

criticalFailed: checkValues.filter(c => c.critical && c.status === 'fail').length,

};

// Priority cascade: fail > degraded > ok

const status = summary.criticalFailed > 0 ? 'fail'

: (summary.degraded > 0 || summary.fail > 0) ? 'degraded'

: 'ok';

return {

status,

timestamp: new Date().toISOString(),

uptimeSec: Number(process.uptime().toFixed(2)),

summary,

checks,

};

};

Why force-dynamic? Without it, Next.js may statically cache the route at build time. Your health check would return the same stale JSON forever — completely defeating the purpose.

Why runtime = 'nodejs'? The Edge runtime doesn't support Mongoose, Nodemailer, or many Node.js APIs. Since your checks depend on these, you need the full Node.js environment.

Deploy and test it:

curl https://yoursite.com/api/health | jq

You should get a clean JSON response in ~400ms or less.

Part 3: Setting Up cron-job.org for Free Monitoring

Now that your health endpoint is live, you need something to call it every minute and track results. cron-job.org does this completely free — no credit card, no trial period.

Step 1 — Create a Free Account

Sign up at console.cron-job.org. The free tier includes unlimited cronjobs running up to every minute, plus a status page feature.

Step 2 — Create Your Monitor Job

Click "Create cronjob"
Fill in the settings:

FieldValue
Title	`Health Monitor - yoursite.com`
URL	`https://yoursite.com/api/health`
Execution schedule	Every minute
Request method	GET
Expected HTTP status	`200`

Under Advanced → Notifications, enable email alerts for failures
Save the job

cron-job.org will now hit your health endpoint every 60 seconds and log the response time and status.

Step 3 — Create Your Status Page

Go to Status Pages in the sidebar
Click "Create status page"
Give it a name (e.g., "Basak Speaks Status")
Click "Add component" and select your monitor job
Label the component (e.g., "Blog API", "Database", etc.)
Under Custom Domain, enter: health.yoursite.com
Save

Step 4 — Wire Up Your DNS (Cloudflare)

In Cloudflare DNS for your domain, add one record:

TypeNameTargetProxy
`CNAME`	`health`	`status.cron-job.org`	DNS only (grey cloud) ⚠️

The proxy must be OFF (grey cloud). If Cloudflare proxies the request, it intercepts the SSL certificate issuance that cron-job.org needs to provision HTTPS for your subdomain. DNS-only mode lets cron-job.org handle TLS directly.

After DNS propagates (usually under 5 minutes with Cloudflare), visit health.yoursite.com. You'll have a live public status page showing:

Real-time uptime percentage
Response latency graph
Incident history
Current service status

All for free. Forever.

Part 4: What Your Stack Costs

For a typical free-tier Next.js project pinged every minute by cron-job.org:

ResourceMonthly UsageFree LimitStatus
Vercel function invocations	43,200	1,000,000	✅ 4% used
Vercel function duration (GB-hrs)	~4.2 GB-hrs	100 GB-hrs	✅ 4% used
Vercel CPU hours	~0.24 hrs	4 CPU-hrs	✅ 6% used
cron-job.org jobs	1	Unlimited	✅ Free
cron-job.org status page	1	Included	✅ Free
Cloudflare DNS	1 CNAME	Unlimited	✅ Free

Total monthly cost: $0.00. The health check API uses roughly 4% of Vercel Hobby's limits. You have plenty of headroom.

Bonus: Make Your `/api/health` Secure

Since your health endpoint reveals service names and configuration state, consider protecting it from public scraping while still allowing cron-job.org to access it:

// app/api/health/route.ts

export async function GET(req: Request) {

const token = req.headers.get('x-health-token');

if (process.env.HEALTH_SECRET && token !== process.env.HEALTH_SECRET) {

return Response.json({ error: 'Unauthorized' }, { status: 401 });

}

// ... rest of handler

}

Then in cron-job.org's job settings, add a custom request header:

x-health-token: your-secret-value

Set HEALTH_SECRET in your Vercel environment variables, and your endpoint is now authenticated — cron-job.org gets in, random internet users don't.

What You've Built

At the end of this guide, you have:

A production-grade health API that checks every dependency your app has
Sensitive data masked from public error messages
2-second timeouts preventing hung requests
Parallel checks for fast response times
A public status page at health.yoursite.com with SSL
Real-time uptime monitoring with email alerts on failure
Zero dollars spent, zero infrastructure managed

The next time your MongoDB Atlas free cluster hits its connection limit at 2 AM, you'll get an email before your users notice. That's the whole point.