Scheduled Tasks

Overview

Dokploy’s scheduling feature enables you to run automated tasks on applications, compose services, and servers using cron expressions. Perfect for backups, cleanups, health checks, and periodic maintenance.

Understanding Schedules

Schedules in Dokploy consist of:

Cron Expression: When the task runs
Command/Script: What gets executed
Target: Where it runs (application, compose, server)
Shell Type: bash or sh
Timezone: Execution timezone
Status: Enabled or disabled

Schedules are managed by a job scheduler that respects timezones and handles failures gracefully.

Schedule Types

Application

Run commands inside application containers.

Compose

Execute tasks in compose services.

Server

Run commands directly on remote servers.

Dokploy Server

Execute tasks on the Dokploy host.

Creating Schedules

Navigate to target

Open the application, compose service, or server where you want to schedule a task.

Access schedules

Click on the Schedules tab.

Add schedule

Click Add Schedule and configure:

Name: Descriptive name for the task
Cron Expression: When to run (e.g., 0 2 * * * for 2 AM daily)
Command: Command to execute
Shell Type: bash or sh
Timezone: Execution timezone (e.g., America/New_York)
Enabled: Toggle to activate

Test manually

Click Run Now to test the schedule before saving.

Cron Expressions

Cron expressions define when tasks run using 5 or 6 fields:

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

Common Patterns

* * * * *

Runs every minute. Use for testing only.

0 * * * *

Runs at the start of every hour.

0 2 * * *

Runs daily at 2:00 AM.

30 14 * * *

Runs daily at 2:30 PM.

0 3 * * 0

Runs every Sunday at 3:00 AM.

0 9 * * 1

Runs every Monday at 9:00 AM.

0 1 1 * *

Runs on the 1st of every month at 1:00 AM.

0 0 15 * *

Runs on the 15th of every month at midnight.

*/15 * * * *

Every 15 minutes.

0 */6 * * *

Every 6 hours.

0 9-17 * * 1-5

Every hour from 9 AM to 5 PM, Monday through Friday.

Special Characters

Character	Meaning	Example
`*`	Any value	`* * * * *` (every minute)
`,`	Value list	`0 1,13 * * *` (1 AM and 1 PM)
`-`	Range	`0 9-17 * * *` (9 AM to 5 PM)
`/`	Step values	`/10 * * *` (every 10 minutes)

Cron expressions are evaluated in the configured timezone, not UTC. Ensure timezone matches your expectations.

Schedule Configuration

Application Schedule
Compose Schedule
Server Schedule
Dokploy Server

Run commands inside application containers:

{
  name: "Database Backup",
  scheduleType: "application",
  applicationId: "app-123",
  cronExpression: "0 2 * * *",
  command: "npm run backup",
  shellType: "bash",
  timezone: "America/New_York",
  enabled: true
}

Use cases:

Database backups
Cache clearing
Report generation
Health checks

Execute tasks in specific compose services:

{
  name: "Cleanup Old Logs",
  scheduleType: "compose",
  composeId: "compose-456",
  serviceName: "app",
  cronExpression: "0 0 * * 0",
  command: "find /var/log -mtime +30 -delete",
  shellType: "sh",
  timezone: "UTC",
  enabled: true
}

Service Name: Required to target specific service in compose stack

Run commands on remote servers:

{
  name: "System Update",
  scheduleType: "server",
  serverId: "server-789",
  cronExpression: "0 3 * * 0",
  command: "apt update && apt upgrade -y",
  shellType: "bash",
  timezone: "Europe/London",
  enabled: true
}

Use cases:

System updates
Log rotation
Disk cleanup
Monitoring scripts

Execute on the Dokploy host:

{
  name: "Docker Cleanup",
  scheduleType: "dokploy-server",
  userId: "user-abc",
  cronExpression: "0 4 * * *",
  command: "docker system prune -af --volumes",
  shellType: "bash",
  timezone: "UTC",
  enabled: true
}

Shell Types

Dokploy supports two shell interpreters:

bash
sh

Bash (Bourne Again Shell)

{
  shellType: "bash",
  command: "echo 'Hello from bash'"
}

Features:

Advanced scripting
Arrays and functions
Command substitution: $(command)
Process substitution: <(command)

Use when: Running complex scripts or modern Linux distributions

sh (POSIX Shell)

{
  shellType: "sh",
  command: "echo 'Hello from sh'"
}

Features:

POSIX compliant
Available on all systems
Lightweight

Use when: Maximum compatibility or Alpine Linux containers

Using Scripts

For complex tasks, use the script field instead of a single command:

{
  name: "Multi-Step Backup",
  cronExpression: "0 2 * * *",
  script: `
#!/bin/bash
set -e

# Variables
BACKUP_DIR="/backups/$(date +%Y-%m-%d)"
DATABASE="myapp"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Dump database
pg_dump -U postgres "$DATABASE" > "$BACKUP_DIR/db.sql"

# Compress backup
gzip "$BACKUP_DIR/db.sql"

# Upload to S3
aws s3 cp "$BACKUP_DIR/db.sql.gz" "s3://backups/$(date +%Y/%m/%d)/"

# Clean old backups (keep 7 days)
find /backups -type f -mtime +7 -delete

echo "Backup completed successfully"
`,
  shellType: "bash",
  enabled: true
}

Scripts have access to all environment variables configured for the service.

Timezone Configuration

Schedules respect the configured timezone:

// Run at 2 AM Eastern Time
{
  cronExpression: "0 2 * * *",
  timezone: "America/New_York"
}

// Run at 2 AM GMT
{
  cronExpression: "0 2 * * *",
  timezone: "Europe/London"
}

// Run at 2 AM Tokyo time
{
  cronExpression: "0 2 * * *",
  timezone: "Asia/Tokyo"
}

Common Timezones

Region	Timezone String
US Eastern	`America/New_York`
US Pacific	`America/Los_Angeles`
UK	`Europe/London`
Central Europe	`Europe/Paris`
India	`Asia/Kolkata`
Japan	`Asia/Tokyo`
Australia	`Australia/Sydney`
UTC	`UTC`

Use IANA timezone names (e.g., America/New_York), not abbreviations (e.g., EST).

Manual Execution

Test schedules without waiting for cron:

Navigate to schedule

Open the schedule details page.

Click Run Now

Executes the schedule immediately, ignoring the cron expression.

View output

Check the deployment logs for command output and errors.

// API: Run schedule manually
POST /api/trpc/schedule.runManually
{
  scheduleId: "schedule-123"
}

Viewing Execution History

Schedule executions are logged as deployments:

// List schedule executions
POST /api/trpc/schedule.list
{
  id: "app-123",
  scheduleType: "application"
}

// Returns schedules with deployment history
{
  scheduleId: "schedule-456",
  name: "Daily Backup",
  cronExpression: "0 2 * * *",
  enabled: true,
  deployments: [
    {
      deploymentId: "deploy-789",
      createdAt: "2026-02-28T02:00:00Z",
      status: "success"
    },
    {
      deploymentId: "deploy-788",
      createdAt: "2026-02-27T02:00:00Z",
      status: "success"
    }
  ]
}

Common Use Cases

Database Backups

{
  name: "PostgreSQL Backup",
  cronExpression: "0 1 * * *", // 1 AM daily
  script: `
pg_dump -U postgres mydb > /backups/db-$(date +%Y%m%d).sql
gzip /backups/db-$(date +%Y%m%d).sql
find /backups -name "*.sql.gz" -mtime +7 -delete
`,
  shellType: "bash"
}

Cache Warming

{
  name: "Warm Cache",
  cronExpression: "*/30 * * * *", // Every 30 minutes
  command: "curl http://localhost:3000/api/warm-cache",
  shellType: "sh"
}

Log Rotation

{
  name: "Rotate Logs",
  cronExpression: "0 0 * * *", // Midnight daily
  script: `
find /var/log/app -name "*.log" -size +100M -exec gzip {} \;
find /var/log/app -name "*.log.gz" -mtime +30 -delete
`,
  shellType: "bash"
}

Health Checks

{
  name: "Health Check",
  cronExpression: "*/5 * * * *", // Every 5 minutes
  command: "curl -f http://localhost:3000/health || exit 1",
  shellType: "sh"
}

Report Generation

{
  name: "Weekly Report",
  cronExpression: "0 9 * * 1", // Monday 9 AM
  command: "npm run generate-report && npm run email-report",
  shellType: "bash"
}

Cleanup Tasks

{
  name: "Docker Cleanup",
  cronExpression: "0 3 * * 0", // Sunday 3 AM
  script: `
docker system prune -f
docker volume prune -f
docker image prune -a -f --filter "until=168h"
`,
  shellType: "bash"
}

Best Practices

Use Absolute Paths

Always use full paths in scripts:

# Good
/usr/bin/node /app/script.js

# Bad
node script.js

Handle Errors

Exit with non-zero on failure:

set -e  # Exit on error
command || { echo "Failed"; exit 1; }

Log Everything

Capture output for debugging:

script.sh >> /var/log/schedule.log 2>&1

Avoid Overlaps

Ensure schedules complete before next run:

# Use flock for mutual exclusion
flock -n /tmp/backup.lock backup.sh

Troubleshooting

Schedule Not Running

Check:

Schedule is enabled
Cron expression is valid
Timezone is correct
Service is running

Test:

# Validate cron expression
# Use online cron calculators

# Run manually to verify command works

Command Fails in Schedule

Common causes:

Missing environment variables
Different user/permissions
PATH not set correctly

Solution:

# Add explicit PATH
export PATH=/usr/local/bin:/usr/bin:/bin

# Source environment
source /app/.env

# Run command
/usr/bin/node /app/script.js

Missed Executions

Possible causes:

Server was down
Container was restarting
Cron overlap

Prevention:

Add monitoring/alerting
Use idempotent scripts
Implement catch-up logic

Timezone Issues

Symptoms: Running at wrong timeVerify:

# Check container timezone
docker exec <container> date

# Check system timezone
timedatectl

Fix: Update schedule timezone setting

API Reference

Manage schedules programmatically:

// Create schedule
POST /api/trpc/schedule.create
{
  name: "Daily Backup",
  cronExpression: "0 2 * * *",
  command: "npm run backup",
  shellType: "bash",
  timezone: "America/New_York",
  scheduleType: "application",
  applicationId: "app-123",
  enabled: true
}

// Update schedule
POST /api/trpc/schedule.update
{
  scheduleId: "schedule-456",
  cronExpression: "0 3 * * *",
  enabled: false
}

// Delete schedule
POST /api/trpc/schedule.delete
{
  scheduleId: "schedule-456"
}

// List schedules
POST /api/trpc/schedule.list
{
  id: "app-123",
  scheduleType: "application"
}

// Run manually
POST /api/trpc/schedule.runManually
{
  scheduleId: "schedule-456"
}

Schedule changes take effect immediately. No restart required.

Getting Started

Deployment

Databases

Infrastructure

Advanced

Scheduled Tasks

Overview

Understanding Schedules

Schedule Types

Application

Compose

Server

Dokploy Server

Creating Schedules

Cron Expressions

Common Patterns

Special Characters

Schedule Configuration

Shell Types

Using Scripts

Timezone Configuration

Common Timezones

Manual Execution

Viewing Execution History

Common Use Cases

Best Practices

Use Absolute Paths

Handle Errors

Log Everything

Avoid Overlaps

Troubleshooting

API Reference

Getting Started

Deployment

Databases

Infrastructure

Advanced

Documentation Index

​Overview

​Understanding Schedules

​Schedule Types

Application

Compose

Server

Dokploy Server

​Creating Schedules

​Cron Expressions

​Common Patterns

​Special Characters

​Schedule Configuration

​Shell Types

​Using Scripts

​Timezone Configuration

​Common Timezones

​Manual Execution

​Viewing Execution History

​Common Use Cases

​Best Practices

Use Absolute Paths

Handle Errors

Log Everything

Avoid Overlaps

​Troubleshooting

​API Reference

Overview

Understanding Schedules

Schedule Types

Creating Schedules

Cron Expressions

Common Patterns

Special Characters

Schedule Configuration

Shell Types

Using Scripts

Timezone Configuration

Common Timezones

Manual Execution

Viewing Execution History

Common Use Cases

Best Practices

Troubleshooting

API Reference