Cronicle Documentation

Plugins in Cronicle are responsible for executing events and reporting status back to the Cronicle daemon. Because plugins are executed as command-line sub-processes, they can be written in any programming language.

To function as a plugin, the executable must be able to:

1. Read job information from standard input (stdin) in JSON format.
2. Write status updates and results to standard output (stdout) in JSON format.

Cronicle also provides a built-in Shell Plugin for users who wish to run simple shell commands without managing JSON input/output manually.

The Home tab is the default dashboard in the Cronicle Web UI. It provides a high-level overview of the system through three main sections:

1. General Stats: Summary of system-wide metrics including event counts, plugin counts, server counts, and resource usage (CPU/RAM).
2. Active Jobs: A real-time list of currently running jobs. You can click a Job ID to view live progress or use the Abort action to cancel a job.
3. Upcoming Events: A schedule of events set to run within the next 24 hours. You can click Edit Event to modify an event's configuration.

Cronicle uses a "cursor" system for scheduling rather than a traditional queue. Each event maintains an internal timestamp cursor (stored in RAM and persisted to disk).

• Catching up: If a job fails to launch (e.g., due to resource constraints), the cursor stays at the previous minute. When resources become available, the cursor moves forward as quickly as possible to "catch up" to current time.
• Run All Mode: For events with Run All Mode enabled, cursors may pause or move backward to ensure missed jobs are eventually processed.
• Manual Intervention: You can manually reset an event's cursor using the Time Machine feature in the Web UI to re-run past jobs or skip a backlog.

If you lose access to your admin account, you can create a temporary emergency administrator account on the primary server. This user will not appear in the UI user list but can be used to log in and restore access.

Note: This is for emergency use only. Once access is restored, create a permanent user via the UI and delete the emergency account.

/opt/cronicle/bin/control.sh admin USERNAME PASSWORD

The main Cronicle configuration is stored in a JSON file. You should edit this file directly to apply changes. The configuration file is not modified during upgrades, so your custom settings will persist. If you need to reference the default settings, a sample configuration is provided.

• Configuration file path: /opt/cronicle/conf/config.json
• Default sample path: /opt/cronicle/sample_conf/config.json

Cronicle uses plain text template files located in the conf/emails/ directory to send notifications (e.g., new user accounts, password changes, job success/failure, or event errors).

Customizing Templates

• File Location: Edit the .txt files in conf/emails/ to change the content.
• Placeholders: Use [/placeholder_name] to inject live data.
• Config Access: Access any property from conf/config.json using [/config/KEY].
• Environment Variables: Access environment variables using [/env/ENV_KEY] (e.g., [/env/NODE_ENV]).
• HTML Support: While default templates are plain text, you can send rich HTML emails by starting the email body (after the Subject line) with an HTML tag like <div>.

To create a custom plugin, provide a command-line executable that reads job information from STDIN and writes status updates/completion events to STDOUT using JSON.

Requirements:

• The plugin must be a real command-line executable with execute permissions (e.g., 0755).
• It must include a shebang line (e.g., #!/usr/bin/node) to indicate the interpreter.
• It must communicate via JSON over standard streams.

To enable redundant backups with auto-failover in a multi-server setup, you must use a shared filesystem (like NFS), Couchbase, or Amazon S3 instead of local disk.

To set up an NFS shared filesystem:

1. Configure the base_dir property in conf/config.json to point to your NFS mount location within the Storage.Filesystem object.
2. Ensure all backup servers have the NFS filesystem mounted at the exact same location.
3. Copy the conf/config.json file to all servers.
4. Run the setup script on the primary server. Do not run the setup script more than once.

{
	"Storage": {
		"engine": "Filesystem",
		"list_page_size": 50,
		"concurrency": 4,
		
		"Filesystem": {
			"base_dir": "/PATH/TO/YOUR/NFS/MOUNT",
			"key_namespaces": 1
		}
	}
}

In a Multi-Server Cluster, backup servers designated via Server Groups will automatically take over if the primary server fails.

• Election Logic: Servers negotiate the primary role based on an alphabetical sort of their hostnames. Higher-sorting hostnames are preferred as primary.
• Startup Delay: There is a ~60 second delay after startup to allow all cluster members to auto-discover each other.
• Unclean Shutdown Handling: If a primary server suffers a catastrophic failure (crash, power loss), active jobs are lost. If those jobs were in Run All Mode, they will not be auto-retried by the new primary. In these cases, you may need to use the Time Machine feature to manually re-run missed jobs.

User accounts are managed in the Users tab.

User Configuration:

• Username: Unique identifier (alphanumeric, periods, and dashes). Cannot be edited after creation.
• Account Status: Active or Disabled. Disabled accounts cannot log in.
• Email Address: Used for event and error notifications.
• Privileges: Defines the specific features the user can access within Cronicle.