Timezone-Aware Scheduling#

Overview#

Dokploy supports per-schedule timezone configuration for cron jobs. Each schedule stores an optional timezone field (an IANA timezone string); when absent, the runtime defaults to UTC. The server-side clock display (TimeBadge) surfaces the host server's current time and timezone offset so operators can reason about when scheduled jobs will fire.

Data Model#

The schedules table includes a nullable timezone text column 1. The four schedule types (application, compose, server, dokploy-server) all share this column 2. The Zod insert/update schemas are auto-derived via drizzle-zod, so timezone is optional in both 3.

Runtime: Scheduling with Timezone#

scheduleJob in packages/server/src/utils/schedules/utils.ts is the entry point for activating a schedule in self-hosted deployments. It reads schedule.timezone, falls back to "UTC" if absent, and passes both { tz, rule: cronExpression } to node-schedule 4. This makes the cron expression interpreted in the configured timezone, not the OS timezone of the host.

On Cloud, the schedule() helper from the backup utils is used instead, and timezone is forwarded the same way 5.

When a schedule is created or updated via the tRPC router:

• Self-hosted: scheduleJob(newSchedule) is called after DB insert; on update, the old job is cancelled via removeScheduleJob before re-registering with the new config 6.
• Cloud: when updating an enabled schedule, updateJob({ ... timezone }) is called. This function looks up the currently registered repeatable job pattern via getJobRepeatable, removes it (including the timezone parameter to match the BullMQ repeat key), then re-adds it with the new cron/timezone configuration. On disable or delete, removeJob({ ... timezone }) is called; the timezone parameter is required to correctly match the BullMQ repeat key (name:jobId:endDate:tz:pattern) since the job was registered with tz: job.timezone || "UTC".

UI: Timezone Picker#

The schedule create/edit form (handle-schedules.tsx) exposes an optional timezone field rendered as a searchable popover 8. Timezone options are drawn from a curated TIMEZONES object of 459 IANA timezone entries grouped by region (Africa, America, Asia, Europe, Pacific, etc.) defined in timezones.ts 9. A tooltip on the field communicates that UTC is used by default when no timezone is selected 10. The getTimezoneLabel() helper returns "UTC (default)" when the field is empty 11.

UI: Server Time Display (TimeBadge)#

TimeBadge is a client component that shows the host server's current time alongside its IANA timezone name and UTC offset. It works as follows:

1. Fetches { time, timezone } from api.server.getServerTime on mount 12.
2. Ticks locally with setInterval(+1s) so the display stays live without polling 13.
3. Formats the time using Intl.DateTimeFormat in the server's timezone 14.
4. Computes the UTC offset via locale-string arithmetic 15 and renders e.g. America/New_York | UTC-05:00.
5. Returns null (renders nothing) if either time or timezone is missing — i.e., on Cloud 16.

The getServerTime tRPC procedure returns null on Cloud and otherwise returns new Date() plus Intl.DateTimeFormat().resolvedOptions().timeZone (the Node.js process timezone) 17.

TimeBadge is placed in the shared sidebar/breadcrumb layout, giving users ambient awareness of server time when configuring cron schedules.

Key Source Files#