Chronos Scheduler Static Repository

The Chronos Scheduler is a backend service that provides a set of REST APIs for scheduling and managing cron jobs to automate Gluesync tasks, including starting/stopping entities and pipelines, as well as running snapshots.

Open Source This project is Open Source

Overview

Chronos provides a comprehensive set of REST APIs for creating, managing, and monitoring scheduled cron jobs that integrate with the Core Hub. It enables automation of routine tasks such as starting or stopping entities and pipelines, as well as scheduling recurring snapshots for data synchronization.

Chronos Scheduler - Core Hub Integration

Key Features

  • Comprehensive REST API

    • Full CRUD operations for scheduled jobs

    • Detailed job status monitoring

    • Error handling and reporting

  • Flexible Job Scheduling

    • User-friendly schedule format option

    • Standard cron expressions support

    • Multiple scheduling patterns

  • Multiple Task Types

    • Start/stop entities

    • Start/stop entire pipelines

    • Schedule snapshots for entities

    • Extensible framework for adding new task types

  • Job Management

    • View, create, update, disable/enable, and delete scheduled jobs

    • Job execution history tracking

  • Containerized Deployment

    • Docker support for easy deployment

    • Environment variable configuration

  • CoreHub Integration

    • Direct SDK integration with Gluesync CoreHub

    • Secure authentication and communication

    • Automatic discovery of CoreHub URL

Configuration

Chronos is configured primarily through environment variables:

Variable Description Default

CORE_HUB_URL

URL of the Gluesync Core Hub (dynamically updated from SDK discovery if available)

http://localhost:1717

HOST

Host to bind the API server

0.0.0.0

PORT

Port to bind the API server

1717

DEBUG

Enable debug mode

False

DB_URL

Database connection URL

sqlite:///./scheduler.db

DATA_DIR

Directory for storing application data

/app/data

ENTITY_START_TIMEOUT

Timeout in seconds for entity start operations

2

ALLOWED_ORIGINS

CORS allowed origins (comma-separated)

*

CRONTAB_USER

User for crontab operations (None for current user)

None

TIMEZONE

Timezone value to be used when storing/retrieving dates in IANA format (e.g., Europe/Rome, Asia/Singapore). This affects how scheduled jobs are interpreted and executed, ensuring they run at the correct local time regardless of server location.

UTC

Gluesync SDK Configuration

Additional environment variables for the Gluesync SDK integration:

Variable Description Default

GLUESYNC_LICENSE_FILE

Path to the Gluesync license file

gs-license.dat

SSL_ENABLED

Whether to use SSL for CoreHub connection

False

GLUESYNC_KEYSTORE_PATH

Path to JKS keystore file for SSL

None

GLUESYNC_KEYSTORE_PASSWORD

Password for JKS keystore

None
The module identifier (GLUESYNC_MODULE_TAG) is hardcoded as scheduler-module and cannot be changed externally.

Usage Examples

Scheduling Options

User-Friendly Schedule Format

Chronos supports a user-friendly schedule format that doesn’t require knowledge of cron expressions:

{
  "schedule": {
    "days_of_week": ["monday", "wednesday", "friday"],
    "hour": 8,
    "minute": 30
  }
}

Parameters:

  • days_of_week: Array of days when the job should run. Valid values are: "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday". An empty array means every day.

  • hour: Hour of the day (0-23)

  • minute: Minute of the hour (0-59)

Examples:

  • Every day at 8:30 AM: {"days_of_week": [], "hour": 8, "minute": 30}

  • Every Monday, Wednesday, and Friday at 8:30 AM: {"days_of_week": ["monday", "wednesday", "friday"], "hour": 8, "minute": 30}

  • Every weekend at midnight: {"days_of_week": ["saturday", "sunday"], "hour": 0, "minute": 0}

Cron Expression Format

Chronos also supports standard cron expressions for more advanced scheduling needs:

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

Examples:

  • 0 * * * * - Run once every hour

  • 0 0 * * * - Run once a day at midnight

  • 0 0 * * 0 - Run once a week on Sunday at midnight

  • 0 0 1 * * - Run once a month on the 1st at midnight

Creating a Scheduled Job

Jobs can be created via the REST API:

POST /api/jobs

{
  "name": "Monday-Wednesday-Friday Job",
  "description": "Runs on specific days at 8:30 AM",
  "task_type": "entity_snapshot",
  "schedule": {
    "days_of_week": ["monday", "wednesday", "friday"],
    "hour": 8,
    "minute": 30
  },
  "pipeline_id": "pipeline-123",
  "entity_id": "entity-456",
  "with_snapshot": true,
  "enabled": true
}

This will automatically be converted to the cron expression 30 8 * * 1,3,5 internally.

API Documentation

Once the application is running, you can access the Swagger UI documentation at:

http://localhost:1717/docs

API Endpoints

Endpoint Method Description

/api/jobs

GET

List all scheduled jobs

/api/jobs/{job_id}

GET

Get a specific job

/api/jobs

POST

Create a new scheduled job

/api/jobs/{job_id}

PUT

Update an existing job

/api/jobs/{job_id}

DELETE

Delete a job

Docker Compose Configuration

Chronos can be easily deployed using Docker Compose. Below is a standard service definition that can be included in your docker-compose.yml file:

gluesync-chronos:
    image: molo17/gluesync-chronos:latest
    volumes:
      - ../../../commons/gluesync/gs-license.dat:/opt/gluesync/data/gs-license.dat:ro
      - ../../../commons/gluesync/security-config.json:/opt/gluesync/data/security-config.json:ro
      - ../../../commons/gluesync/gluesync.com.jks:/opt/gluesync/data/gluesync.com.jks:ro
      - ./chronos-data:/app/data
      # - /etc/timezone:/etc/timezone:ro # optional pass host's timezone
    # ports:
    #   - "1717:1717"
    environment:
      - ENTITY_START_TIMEOUT=2
      - PORT=1717
      - GLUESYNC_LICENSE_FILE=/opt/gluesync/data/gs-license.dat
      - SSL_ENABLED=True
      - GLUESYNC_SECURITY_CONFIG=/opt/gluesync/data/security-config.json
      - SSL_SKIP_VERIFY=True
      - TIMEZONE=Asia/Singapore # optionally hardcode timezone value in IANA format (e.g., Europe/Rome)

Volume Mounts

  • gs-license.dat: Gluesync license file (read-only)

  • security-config.json: Security configuration for Gluesync (read-only)

  • gluesync.com.jks: Java KeyStore for SSL (read-only)

  • chronos-data: Directory for persistent data storage

  • /etc/timezone: Optional mount to use the host’s timezone (commented out by default)

Environment Variables

The Docker Compose configuration includes the essential environment variables needed for Chronos to operate. Refer to the Configuration section above for details on each variable.

The TIMEZONE environment variable allows you to explicitly set the timezone for the Chronos scheduler. This ensures that all scheduled jobs run at the correct local time according to the specified timezone, regardless of the server’s physical location. If not specified, UTC will be used as the default timezone.

Core Hub Integration

Chronos integrates directly with the Gluesync CoreHub using the official gluesync_sdk. The SDK provides:

  • Secure WebSocket connection to the CoreHub

  • Automatic handshake and authentication

  • JWT token management for API calls

  • Proper error handling for connection issues

The integration uses only the SDK-provided authentication token for all Core Hub API calls, eliminating the need for manual authentication with username/password and making the module more secure and streamlined.

The module automatically retrieves the Core Hub URL from the SDK after discovery, ensuring that the correct URL is used even when the Core Hub is discovered dynamically through UDP broadcast.

Use Chronos from the UI

You can also use Chronos from the Gluesync UI. Go to the "Scheduler" section from the left menu and click on "Add new schedule" to create a new job.

Deployment

Prerequisites

  • Python 3.8+

  • Access to crontab (for Unix-based systems)

  • Gluesync Core Hub instance

Docker Deployment

# Build the Docker image
docker build -t gluesync-scheduler-module:latest .

# Run the container
docker run -p 1717:1717 -e CORE_HUB_URL=http://your-core-hub:1717 gluesync-scheduler-module:latest

Environment Configuration

Create a .env file in the root of your project directory with the following content:

GLUESYNC_LICENSE_FILE=gs-license.dat
GLUESYNC_MODULE_TAG=scheduler-module
SSL_ENABLED=False
GLUESYNC_SECURITY_CONFIG=/path/to/security-config.json
DB_URL=sqlite:///./data/test_scheduler.db
DEBUG=True
CORE_HUB_URL=http://localhost:8080
CRONTAB_USER=$USER
HOST=0.0.0.0

Installation

Local Development

# Clone the repository
git clone https://gitlab.com/molo17-public/gluesync/gluesync-scheduler-module.git
cd gluesync-scheduler-module

# Create a virtual environment and activate it
python -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

# Install dependencies
pip install -r requirements.txt

# Initialize the database
python init_db.py

# Run the application
uvicorn app:app --reload

Best Practices

  • Use descriptive job names that clearly indicate their purpose

  • Schedule resource-intensive jobs during off-peak hours

  • Use the user-friendly schedule format for simple scheduling needs

  • Use standard cron expressions for more complex scheduling requirements

  • Implement proper error handling for critical jobs

  • Monitor job execution history for failures

  • Set appropriate retry mechanisms for jobs that interact with external systems

  • Regularly backup the scheduler database

Troubleshooting

Common Issues

Issue Possible Cause Resolution

Jobs not executing

Scheduler service not running or incorrect cron expression

Verify service status and check cron expression format

Authentication failures

Invalid or expired token

Generate a new authentication token

CoreHub connectivity issues

Network configuration or firewall problems

Check network settings and firewall rules

Database errors

SQLite database corruption or permission issues

Check database permissions and consider using a more robust database for production

Testing with Postman

You can test the API endpoints using Postman:

  1. Open Postman and create a new request

  2. Set the request URL to http://localhost:1717/api/jobs

  3. Choose the appropriate HTTP method and set required headers/body data

  4. Send the request and check the response

  5. Verify logs in the terminal to ensure proper operation

License

This project is dual-licensed under the following licenses:

  1. GNU Affero General Public License (AGPL) v3

    • This is a free, copyleft license that allows you to use, modify, and distribute this software.

    • If you choose this option, any derivative works must also be licensed under AGPL v3.

  2. MOLO17 Commercial License

    • For those who want to use this software in proprietary applications without the copyleft requirements of AGPL.

    • This option includes a warranty and permits proprietary use.

    • Contact MOLO17 at info@molo17.com for licensing terms and conditions.

References