Skip to content
Klutch.sh Docs

Deploying Cronicle

Introduction

Cronicle is a powerful, open-source multi-server task scheduler and runner with a web-based front-end UI. It provides enterprise-grade job scheduling capabilities, handling both scheduled, repeating, and on-demand jobs with the ability to target any number of worker servers. Built with Node.js, Cronicle offers real-time statistics, live log viewing, and a user-friendly interface for managing complex automation workflows.

Key features of Cronicle include:

  • Multi-Server Architecture: Distribute jobs across multiple worker servers for improved performance and reliability
  • Web-Based UI: Intuitive dashboard for managing jobs, schedules, and monitoring execution
  • Flexible Scheduling: Support for cron-style schedules, repeating intervals, and manual triggering
  • Real-Time Monitoring: Live log viewer and statistics for tracking job execution
  • Plugin System: Extensible architecture supporting custom plugins for various automation tasks
  • Event Logging: Comprehensive audit trails and detailed event history
  • API Access: RESTful API for programmatic job management and integration

This comprehensive guide walks you through deploying Cronicle on Klutch.sh using Docker, including detailed installation steps, sample configurations, and production-ready best practices for persistent storage and job scheduling.

Prerequisites

Before you begin, ensure you have the following:

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Cronicle deployment project:

Terminal window
mkdir cronicle-klutch
cd cronicle-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your Cronicle container configuration:

FROM node:18-alpine


# Install dependencies
RUN apk add --no-cache bash curl git


# Set working directory
WORKDIR /opt/cronicle


# Clone Cronicle repository
RUN git clone https://github.com/jhuckaby/Cronicle.git . && \
    npm install && \
    node bin/build.js dist


# Create data directory for persistent storage
RUN mkdir -p /opt/cronicle/data


# Set environment variables
ENV CRONICLE_foreground=1
ENV CRONICLE_echo=1


# Expose the default Cronicle port
EXPOSE 3012


# Start Cronicle
CMD ["node", "bin/control.sh", "start"]

Note: This Dockerfile uses the official Node.js Alpine image for a lightweight deployment. The CRONICLE_foreground=1 environment variable keeps Cronicle running in the foreground, which is essential for Docker containers.

Step 3: (Optional) Create Custom Configuration

You can create a configuration file to customize Cronicle’s behavior. Create a file named config.json:

{
  "base_app_url": "http://example-app.klutch.sh:8000",
  "email_from": "cronicle@example.com",
  "secret_key": "YOUR_SECRET_KEY_HERE",
  "log_dir": "/opt/cronicle/data/logs",
  "queue_dir": "/opt/cronicle/data/queue",
  "pid_file": "/opt/cronicle/data/cronicle.pid",
  "log_filename": "/opt/cronicle/data/logs/cronicle.log",
  "debug_level": 9,
  "maintenance": 0,
  "list_row_max": 10000,
  "job_data_expire_days": 180,
  "child_kill_timeout": 10,
  "dead_job_timeout": 120,
  "master_ping_freq": 20,
  "master_ping_timeout": 60,
  "udp_broadcast_port": 3014,
  "scheduler_startup_grace": 10,
  "universal_web_hook": "",
  "track_manual_jobs": false,
  "server_comm_use_hostnames": 1,
  "web_direct_connect": 0,
  "web_socket_use_hostnames": 1,
  "socket_io_transports": ["polling", "websocket"]
}

To use this configuration, you’ll need to modify your Dockerfile to copy it during the build:

# Add this line after creating the data directory
COPY config.json /opt/cronicle/conf/config.json

Step 4: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Cronicle setup locally:

Terminal window
# Build the Docker image
docker build -t my-cronicle .


# Run the container with volume mount
docker run -d \
  --name cronicle-test \
  -p 3012:3012 \
  -v cronicle-data:/opt/cronicle/data \
  my-cronicle


# Check logs
docker logs -f cronicle-test


# Access Cronicle at http://localhost:3012
# Default credentials: admin / admin


# Stop and remove the test container when done
docker stop cronicle-test
docker rm cronicle-test

Step 5: Push to GitHub

Commit your Dockerfile and any configuration files to your GitHub repository:

Terminal window
git add Dockerfile config.json
git commit -m "Add Cronicle Dockerfile and configuration"
git remote add origin https://github.com/yourusername/cronicle-klutch.git
git push -u origin main

Accessing Cronicle

Once deployed, you can access the Cronicle web interface through your Klutch.sh app URL. Since Klutch.sh routes HTTP traffic to your application, you’ll access it via:

http://example-app.klutch.sh:8000

Default Credentials

When you first access Cronicle, use these default credentials:

  • Username: admin
  • Password: admin

Important: Change the default password immediately after your first login for security reasons.

Initial Setup

After logging in for the first time:

  1. Change Admin Password: Navigate to My Account → Change Password
  2. Configure Server: Go to Settings → Server Settings and update your base URL
  3. Setup Email: Configure email settings for notifications (if needed)
  4. Create Categories: Organize your jobs into logical categories
  5. Add Plugins: Install any required plugins for your automation tasks

Deploying to Klutch.sh

Now that your Cronicle project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage for job data, logs, and configuration.

Deployment Steps

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “Cronicle Task Scheduler”).

    3. Create a New App

      Navigate to Create App and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (Cronicle provides a web interface accessible via HTTP)
      • Internal Port: Set to 3012 (the default Cronicle web interface port that your container listens on)

    6. Set Environment Variables

      Add the following environment variables for your Cronicle configuration:

      • CRONICLE_foreground: Set to 1 (keeps Cronicle running in foreground for Docker)
      • CRONICLE_echo: Set to 1 (enables console output for logging)
      • CRONICLE_secret_key: Set to a strong random string for API authentication
      • CRONICLE_base_app_url: Set to your app URL (e.g., http://example-app.klutch.sh:8000)
      • CRONICLE_web_direct_connect: Set to 0 (recommended for proxy setups)

      Optional environment variables for email notifications:

      • CRONICLE_email_from: Your sender email address
      • CRONICLE_smtp_hostname: Your SMTP server hostname
      • CRONICLE_smtp_port: SMTP server port (usually 587 or 465)

      Security Note: Always use strong, unique secret keys for production deployments.

    7. Attach a Persistent Volume

      This is critical for ensuring your job data, logs, and configuration persist across deployments and restarts:

      • In the Volumes section, click “Add Volume”
      • Mount Path: Enter /opt/cronicle/data (this is where Cronicle stores all persistent data)
      • Size: Choose an appropriate size based on your expected job logs and data volume (e.g., 5GB, 10GB, etc.)

      Important: Cronicle requires persistent storage to maintain job schedules, execution history, and logs between container restarts. Without this volume, you’ll lose all data when the container restarts.

    8. Configure Additional Settings

      • Region: Select the region closest to your users for optimal latency
      • Compute Resources: Choose CPU and memory based on your workload (minimum 512MB RAM recommended, 1GB or more for production)
      • Instances: Start with 1 instance (Cronicle’s master server should run as a single instance)

    9. Deploy Your Scheduler

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image
      • Attach the persistent volume
      • Start your Cronicle container
      • Assign a URL for web access

    10. Access Your Cronicle Dashboard

      Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Access your Cronicle web interface at:

      http://example-app.klutch.sh:8000

      Log in with the default credentials (admin / admin) and change the password immediately.

Creating and Scheduling Jobs

Once your Cronicle instance is deployed and running, you can start creating and scheduling jobs.

Creating Your First Job

  1. Navigate to Schedule: Click on the “Schedule” tab in the Cronicle dashboard
  2. Add Event: Click “Add Event” to create a new scheduled job
  3. Configure Job Details:
    • Event Name: Give your job a descriptive name
    • Category: Select or create a category
    • Plugin: Choose the appropriate plugin (Shell Script, HTTP Request, etc.)
    • Target: Select which server(s) should run the job
  4. Set Schedule: Configure when the job should run:
    • Cron Pattern: Use cron syntax (e.g., 0 2 * * * for daily at 2 AM)
    • Time Zone: Select your preferred timezone
  5. Configure Parameters: Set any plugin-specific parameters
  6. Enable: Toggle the “Enabled” switch to activate the schedule

Example: Shell Script Job

Here’s an example configuration for a simple backup job:

{
  "title": "Daily Database Backup",
  "category": "maintenance",
  "plugin": "shellplug",
  "target": "main",
  "timing": {
    "minutes": [0],
    "hours": [2]
  },
  "params": {
    "script": "#!/bin/bash\n# Database backup script\nbackup_dir=/opt/cronicle/data/backups\nmkdir -p $backup_dir\ndate=$(date +%Y%m%d_%H%M%S)\necho \"Starting backup at $date\"\n# Your backup commands here\necho \"Backup completed\""
  }
}

Example: HTTP Request Job

You can also create jobs that make HTTP requests:

{
  "title": "Health Check Ping",
  "category": "monitoring",
  "plugin": "httpreq",
  "target": "main",
  "timing": {
    "minutes": [0, 15, 30, 45]
  },
  "params": {
    "method": "GET",
    "url": "https://api.example.com/health",
    "timeout": 30
  }
}

Using the Cronicle API

Cronicle provides a comprehensive RESTful API for programmatic job management.

Authentication

First, obtain an API key from the Cronicle dashboard:

  1. Log in to Cronicle
  2. Go to My Account → API Keys
  3. Create a new API key

Example API Requests

Trigger a Job Manually (Node.js):

const axios = require('axios');


const cronicleUrl = 'http://example-app.klutch.sh:8000';
const apiKey = 'YOUR_API_KEY';


async function triggerJob(eventId) {
  try {
    const response = await axios.post(`${cronicleUrl}/api/app/run_event/v1`, {
      id: eventId,
      now: 1
    }, {
      headers: {
        'X-API-Key': apiKey
      }
    });


    console.log('Job triggered:', response.data);
  } catch (error) {
    console.error('Error triggering job:', error.message);
  }
}


triggerJob('evt12345');

Get Job Status (Python):

import requests


cronicle_url = 'http://example-app.klutch.sh:8000'
api_key = 'YOUR_API_KEY'


def get_job_status(job_id):
    headers = {
        'X-API-Key': api_key
    }


    response = requests.get(
        f'{cronicle_url}/api/app/get_job_status/v1',
        params={'id': job_id},
        headers=headers
    )


    if response.status_code == 200:
        return response.json()
    else:
        print(f'Error: {response.status_code}')
        return None


status = get_job_status('j12345')
print(status)

List All Scheduled Events (cURL):

Terminal window
curl -X GET \
  "http://example-app.klutch.sh:8000/api/app/get_schedule/v1" \
  -H "X-API-Key: YOUR_API_KEY"

Production Best Practices

Security Recommendations

  • Change Default Credentials: Immediately change the default admin password after first login
  • Use Strong API Keys: Generate strong, random API keys and rotate them regularly
  • Environment Variables: Store sensitive credentials as environment variables in Klutch.sh, never in your Dockerfile
  • Access Control: Create user accounts with appropriate permissions instead of sharing the admin account
  • HTTPS Setup: Consider placing Cronicle behind a reverse proxy with SSL/TLS for production use
  • Regular Updates: Keep Cronicle updated to the latest version for security patches

Performance Optimization

  • Resource Allocation: Monitor your job execution patterns and adjust compute resources as needed
  • Job Limits: Configure appropriate timeouts and resource limits for jobs to prevent runaway processes
  • Log Rotation: Configure log retention policies to prevent disk space issues
  • Concurrent Jobs: Limit the number of concurrent jobs based on your server resources
  • Plugin Selection: Choose efficient plugins and optimize scripts for better performance

Monitoring and Maintenance

Monitor your Cronicle instance for:

  • Job Success/Failure Rates: Track job completion statistics
  • Execution Times: Monitor for jobs taking longer than expected
  • Resource Usage: Watch CPU, memory, and disk utilization
  • Log Growth: Keep track of log file sizes and implement rotation
  • Queue Depth: Monitor the job queue for backlogs

Backup Strategy

Implement a comprehensive backup strategy:

  1. Persistent Volume Backups: Regularly backup your /opt/cronicle/data volume
  2. Configuration Export: Export job schedules and configurations periodically
  3. Database Backups: Cronicle uses a local JSON database stored in the data directory
  4. Testing Restores: Regularly test your backup restoration process

Scaling Considerations

For high-volume job scheduling:

  • Worker Servers: Deploy additional Cronicle worker servers to distribute job execution
  • Resource Allocation: Increase CPU and memory based on job complexity and concurrency
  • Database Optimization: Monitor and optimize the internal database performance
  • Network Latency: Deploy in regions close to your job targets

Troubleshooting

Cannot Access Web Interface

  • Verify that your app is running in Klutch.sh
  • Ensure the internal port is set to 3012 in your app configuration
  • Check that HTTP traffic type is selected
  • Verify the container logs for any startup errors

Jobs Not Executing

  • Check that jobs are enabled in the schedule
  • Verify the target server is online and accessible
  • Review job logs for error messages
  • Ensure proper permissions for scripts and executables

Data Loss After Restart

  • Verify that the persistent volume is correctly attached at /opt/cronicle/data
  • Check that the volume has sufficient space allocated
  • Review container logs for any file system errors

Performance Issues

  • Monitor resource utilization (CPU, memory) in Klutch.sh dashboard
  • Review job execution times and optimize long-running jobs
  • Consider increasing compute resources
  • Check for disk I/O bottlenecks

Authentication Errors

  • Verify API keys are correctly configured
  • Check that the secret key environment variable is set
  • Ensure you’re using the correct credentials

Additional Resources

Conclusion

Deploying Cronicle to Klutch.sh with Docker provides a robust, scalable task scheduling solution with persistent storage for your automation needs. By following this guide, you’ve set up a production-ready Cronicle instance with proper data persistence, security configurations, and access capabilities. Your scheduler is now ready to handle complex job workflows, providing reliable automation for your applications and infrastructure.

Whether you’re scheduling simple maintenance tasks or orchestrating complex multi-server workflows, Cronicle on Klutch.sh offers the flexibility and reliability you need for enterprise-grade job scheduling.