Cron Job Configuration Guide

Cron jobs are an essential part of automated operations, helping you regularly execute repetitive tasks such as data synchronization, cache updates, and report generation.

This guide will introduce how to configure cron jobs for a NEXTY.DEV project on the mainstream deployment platforms - Vercel, Dokploy and Coolify - enabling automated management for your SaaS.

Preparation

Before you begin configuring cron jobs, please ensure you complete the following preparation steps:

1. Generate CRON_SECRET

CRON_SECRET is a security key used to verify the legitimacy of cron job requests and prevent unauthorized access.

Generation Methods (choose one):

Method A: Use the NEXTY.DEV Cron Secret Generator (recommended)

1. Visit https://nexty.dev/tools/cron-secret-generator - free, runs entirely in your browser, nothing is sent to a server
2. Copy the generated secret

Method B: Use Another Online Tool

1. Visit https://generate-secret.vercel.app/32
2. Copy the generated random string

Method C: Use Command Line (Mac/Linux)

openssl rand -base64 32

After generation, add this string to your project's environment variable CRON_SECRET.

2. Complete Cron Job Endpoint Implementation

The working principle of cron jobs is: the system periodically sends HTTP requests to your application, triggering pre-written endpoints that contain specific task processing logic. Therefore, before configuring cron jobs, you need to:

• Create cron job endpoints in your project (e.g., /api/cron/task1)
• Implement specific business logic in the endpoints
• Add CRON_SECRET verification to ensure only legitimate requests can trigger tasks

The boilerplate ships with one cron job you must configure, /api/cron/credits — see the next section.

Built-in cron job: /api/cron/credits

Since v4.0.0 the boilerplate ships /api/cron/credits. Once you enable subscriptions or credits, this cron job is mandatory — without it, three things never happen:

• Monthly credit drip settlement for annual subscriptions: an annual plan grants month one immediately; the remaining 11 monthly grants depend on this job
• Reconciliation of overdue renewals: recovers lost renewal webhooks by replaying the latest invoice
• Reconciliation of pending PayPal captures: advances pending payments such as eCheck to success or failure

Endpoint contract:

Recommended frequency: once a minute (* * * * *). Each run has a 60-second budget and settles at most 100 drips, 20 renewal reconciliations and 20 pending captures per tick; a backlog drains automatically over the following ticks. There is no cross-tick lock — a slow tick overlapping the next one is harmless, because drip settlement serializes on the subscription row lock and re-checks under it, while reconciliation replays into the idempotent fulfillment layer.

Trigger it manually in local development:

curl -X POST -H "Authorization: Bearer $CRON_SECRET" \
  http://localhost:3000/api/cron/credits

Vercel Platform Configuration

Good to know

Vercel free accounts only support creating one cron job.

Vercel uses Vercel Cron Jobs functionality to run scheduled tasks. Configuration steps are as follows:

Create or edit the vercel.json file in your project root directory:

{
  "crons": [
    {
      "path": "/api/cron/task1",
      "schedule": "0 0 * * *"
    },
    {
      "path": "/api/cron/task2",
      "schedule": "0 2 * * 1"
    }
  ]
}

Cron Expression Explanation:

• 0 0 * * * - Every day at 0:00 AM (UTC time)
• 0 2 * * 1 - Every Monday at 2:00 AM (UTC time)

Timezone Note: Vercel Cron uses UTC time.

After deployment, you can view the configured cron jobs in your Vercel project's Settings > Cron Jobs.

Note: the built-in /api/cron/credits will not run on Vercel as-is

Vercel Cron only sends GET requests, and GET /api/cron/credits is just a health check. To use it on Vercel you have to add a proxy that turns the schedule into a POST carrying the Bearer header, or rewrite the endpoint's auth. A Vercel free account also cannot reach the recommended once-a-minute frequency. If your product sells annual subscriptions, prefer the Dokploy / Coolify setup below, or drive the POST from an external scheduler (GitHub Actions, cron-job.org, and so on).

Dokploy Platform Configuration

Dokploy provides a more flexible cron job configuration approach, supporting direct creation and management in the admin panel.

Configuration steps:

1. Enter the service management panel where you need to create cron jobs
2. Find the Schedules tab
3. Click to create a new cron job

Fill in the form as follows:

• Task Name: Custom task name
• Schedule: Cron expression, e.g., 0 0 * * * (execute daily at midnight)
• Shell Type: Select Sh
• Command: wget --header="Authorization: Bearer <CRON_SECRET generated in previous step>" --post-data="" -O- https://<your domain>/api/<cron job endpoint path>

For the built-in credits cron job, set Schedule to * * * * * and use the command below. It runs inside the app container, so localhost:3000 reaches this service directly and $CRON_SECRET is read from the container's own environment — the secret never leaves the container nor travels the public internet:

wget --header="Authorization: Bearer $CRON_SECRET" --post-data="" -qO- http://localhost:3000/api/cron/credits

After deploying the code, if you want to test the cron job, you can click the execute button on the panel to run it immediately.

Coolify

Coolify offers the equivalent feature under Scheduled Tasks on the application page. Fill in the same cron expression and the same wget command as above.

Cron Expression Reference

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday=0)
│ │ │ │ │
* * * * *

Examples:

• 0 2 * * * - Daily at 2:00 AM
• 0 2 * * 1 - Every Monday at 2:00 AM
• 0 */6 * * * - Every 6 hours
• 0 0 1 * * - 1st day of every month at 0:00 AM