A Comprehensive Guide to Installing Cronicle Task Scheduler with Nginx Proxy

Cronicle is a Node.js application. However, many Linux repositories include older versions of Node.js by default. Installation instructions for Node.js on Debian-like distributions are available here, and instructions for RedHat-like distributions can be found here.

Cronicle installation

Running Cronicle as a standalone Node.js application is possible, but it’s recommended to use a reverse proxy for TLS and security handling. It should be noted that Cronicle uses WebSockets which require precise configuration to function correctly.

Firstly, you’ll need to set up some packages on your Linux or Windows Subsystem for Linux environment. In the following examples, Ubuntu is used. However, you should be able to adapt these instructions to any Linux distribution. The packages required include Node.js, its NPM package manager, cURL for script download, and Nginx to serve as your reverse proxy.

One thing to be mindful of is that the default LTS repositories for Ubuntu carry an older version of Node.js. Unfortunately, this version is incompatible with Cronicle.

To begin, ensure that your system is up-to-date, including the latest kernel:

sudo apt-get update && sudo apt-get upgrade
sudo apt-get dist-upgrade

If you have numerous packages, particularly those in the kernel, networking, or systemd, to update, rebooting your system is advisable after accomplishing this phase.

sudo apt-get install -y ca-certificates curl gnupg

This command installs the crucial packages, like ca-certificates, curl, and GnuPG, which are necessary to keep the Root Certificate Authorities up-to-date and to download and securely install software packages.

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

This line downloads the GPG key for the NodeSource repository and then uses gpg to format and save it as /etc/apt/keyrings/nodesource.gpg. GPG keys are used to verify the authenticity of software packages and protect you against future supply chain attacks.

NODE_MAJOR=20

The following command sets the variable to specify the Node.js major version for later use. If a newer version of Node.js is released, you can update the variable to get the latest versions.

echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

This block of code adds a new entry into the APT package manager’s sources list. Through this, the NodeSource repository URL for the Node.js version controlled by the NODE MAJOR variable is specified.

sudo apt-get update && sudo apt-get install nodejs -y

The instruction here is for the updating of the package lists for APT and installing of Node.js afterwards. The -y flag is used to automatically confirm and answer yes to any prompts that may come up during the installation process.

The next command installs the Nginx web server.

sudo apt -y install nginx

We have to create a Cronicle folder:

sudo mkdir /opt/cronicle

Once everything is done, verify that the NodeJS binaries are installed appropriately and that the current version is available.

which node
node -v

Now we download and install Cronicle (by default, this will be in /opt/cronicle)

curl https://raw.githubusercontent.com/jhuckaby/Cronicle/master/bin/install.js | sudo node

Cronicle configuration

As the output of the above installers says, you should make sure to configure your settings. Use nano, vi, or your favorite JSON editor to edit the /opt/cronicle/conf/config.json file.

You must change the secret_key to any random sequence of letters and numbers. You can also configure your SMTP (mail) server settings if you wish to receive notifications.

Now run the setup command as suggested to initialize storage and start the service.

sudo /opt/cronicle/bin/control.sh setup
sudo /opt/cronicle/bin/control.sh start

Cronicle is now running on port 3012

Within about 60 seconds, you should be able to connect to your Cronicle instance on the server it runs at http://localhost:3012 and log in with admin as the username and admin as the password. I suggest changing the admin password as soon as you enter the web interface.

To automatically start the Cronicle server on startup, most Linux distributions use systemd. Here’s a service file you can place in /etc/systemd/system/chronicle.service.

# Service for starting cronicle web GUI
[Unit]
Description=Cronicle Backend Service
After=network-online.target
Wants=network-online.target
[Service]
Type=forking
Environment=HOSTNAME=primary.mydomain.int
PIDFile=/opt/cronicle/logs/cronicled.pid
ExecStart=/opt/cronicle/bin/control.sh start
ExecStop=/opt/cronicle/bin/control.sh stop
[Install]
WantedBy=multi-user.target

The HOSTNAME environment variable is helpful if you use a DNS alias (CNAME) for your customers.

Now reload your systemd configuration and enable Cronicle to start at boot.

systemctl daemon-reload
systemctl enable cronicle

Nginx configuration

Nginx’s default configuration file is located at /etc/nginx/sites-enabled/default, assuming Cronicle is the only site running on this server. If you want to run multiple sites or services on the same server, you must adapt your configuration accordingly. Nginx configuration is outside the scope of this article, but WebSockets would only work with a few of the examples I found online.

Here is the modification I made to a typical Nginx configuration:

upstream cronicle {
    server localhost:3012;
}
# other configs
location / {
    root /opt/cronicle/htdocs;
    index index.html index.html.gz;
    try_files $uri $uri/ @cronicle;
}
location @cronicle {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://cronicle;
}

The upstream and location instructions determine the location of Cronicle’s web resources. Any static resources that are on disk, such as images, CSS, and JavaScript files, will be directly served by Nginx. Any dynamic resources will be passed to the NodeJS application using the @cronicle directive. The @cronicle section sets the Proxy headers to forward to the application to log the accurate IP address of the connection. This Nginx configuration can now be used with WebSockets, thanks to the proxy_set_header Upgrade and Connection instructions. Without these, Cronicle will operate, but live log streaming and other features may not function correctly.

At this stage, you should be able to restart your Nginx setup. If there is an issue with restarting, it could likely be a configuration or permissions issue. More information can be found in the Nginx log files.

systemctl restart nginx
systemctl status nginx

If the Nginx status is good, but you still can’t get a login page, please check your network and firewall configurations to ensure both ports 80 and 443 are open on the server. If you get an HTTP 504 Gateway Timeout error, your Cronicle application is not running. You can troubleshoot that by checking its logs. The application will still be available on port 3012 on the server itself. Please ensure you have a firewall enabled so clients on the network cannot directly access the underlying NodeJS application.

Scheduling Cronicle events

Cronicle displays a unique characteristic in comparison with the usual cron job scheduler in Unix-like frameworks. In Cronicle’s case, upon scheduling a task, it can execute under the account that the Cronicle server process uses (root, in this case). Provided that the account has sudoers permissions, each task can be organized to execute as a different user.

Additionally, Cronicle exists as a multi-server scheme, which means it can operate on a single or several servers (tasks can execute simultaneously, sequentially, or using branch-based (if/then) logic). As a result, it’s feasible to set it up so it doesn’t necessarily operate on the account or server you use to access the Cronicle web interface.

This entire setup is adjusted in a variety of task and server configurations. In the subsequent article, we plan to establish the primary Cronicle server as a task runner and arrange a few basic jobs to verify that jobs are scheduled and performed. For further details, visit their GitHub page.

Conclusion

This article shows how to set up the Cronicle web application with Nginx as a reverse proxy. By default, Cronicle will run any executable on your system. If you want more granular progress information, you can also write your own plugins using any programming or scripting language as specified in the Cronicle documentation.