Public | Automated Build

Last pushed: a year ago
Short Description
A system to manage and monitor cron jobs.
Full Description


minicron aims to complement cron by making it easier to manage and monitor cron jobs, it can largely be
thought of as two components that interact together, the CLI and the Hub. The CLI is what is installed on your
server(s) and executes your cron command and reports the status back to the Hub. The Hub is the central point
where data from one or many instances of the CLI is received and stored in a database. The Hub also provides
a web interface to the data and makes it easy to manage your cron jobs.


<img src="" height="175"/>
<img src="" height="175"/>
<img src="" height="175"/>
<img src="" height="175"/>


After thinking a lot about the future of minicron and it's long overdue 1.0 release I've decided to focus it solely on
monitoring cron jobs and doing that really well and leave the management side to
other tools. As such I'm removing the features related to SSH
based magement of jobs, it's possible that in future versions I may revist this but for now I want to focus solely
on monitoring. All development on this effort will be happening in the
1.0-dev branch.


I initially developed minicron as part of my dissertation at university. The inspiration for developing minicron comes
largely from my experience and frustrations using cron, in particular my time spent working at Miniclip
(which is where the name comes from, miniclip.. minicron, get it?) where the management and monitoring of cron jobs at times proved
to be tricky!


  • Web UI
    • CRUD for cron jobs using ssh
    • GUI for cron schedule create/read/update
    • View realtime output/status as jobs run
    • Historical data for all job executions
  • Alerts when jobs executions are missed or fail via:

Lots more is planned for the future, see open issues or if
you don't see the feature you want there add it!



Should run on OSX and any Linux/BSD based OS.



  • SQLite

Also Supported

  • MySQL
  • PostgreSQL

Web Server / Reverse Proxy


A simple example config for nginx is provided.


If you're using apache as your reverse proxy you need to ensure you have the following modules installed:

  • libapache2-mod-proxy-html
  • apache2-utils

Run the following to enable them and then restart apache a2enmod proxy proxy_html proxy_http xml2enc.

A simple example config for apache is provided.


minicron is currently under heavy development and I make no gurantees about stability while it remains pre 1.0, as such
I would not recommend that you use this in production but I encourage you to give it a try in a non critical environment
and help me to improve it and work towards the first stable release.

minicron used to be available to install via Ruby Gems, all future releases (>= 0.8)
will no longer be published there and made available as ZIP file releases


  1. First check you meet the requirements

  2. Use the handy install script or grab the latest zip/tarball
    for your OS and install manually.

    bash -c "$(curl -sSL"
  3. Set your database configuration options in /etc/minicron.toml, you can use the
    minicron.toml as a guide on what options
    are configurable


    the step below will drop any existing tables in the configured database and create new ones i.e:

  4. You can then minicron db setup to create the database schema and run any pending migrations.

  5. Done! See the usage section below for more details on how to use minicron now you have it installed


You can also run minicron in a docker container, see below for instructions how:

docker pull jamesrwhite/minicron:v0.9.7
minicron_container_id=$(docker run -d -p -i -t jamesrwhite/minicron:v0.9.7)
docker exec $minicron_container_id minicron db setup
docker exec $minicron_container_id minicron server start


Run a command

minicron run 'mysqldump db > backup.sql'

The global --verbose option can also be passed to the run argument like so

minicron run --verbose ls

You can also run a command in 'dry run' mode to test if it works without sending the output to the server.

minicron run --dry-run 'zip -r website'

for further information see minicron help run.

Get help

Running minicron with no arguments is an alias to running minicron help, minicron -h or minicron --help.
You can also use the help argument to get information on any command as shown above in the run a command section
or alternatively you can pass the -h or --help options like so minicron run -h.


To launch the server (aka the Hub) run

minicron server start

by default it will bind to port 9292 on the host but this can be configured by the command line
arguments --host --port and --path or in the config file.

By default the server will run as a daemon with its process id stored in /tmp/
you can also use the stop, restart and status commands to control the server.

To run the server in debug mode, so you can see its output and any errors you can pass the --debug

See nginx.conf for an example of
how to run minicron behind a reverse proxy.

Connecting to a host via SSH

To be able to perform CRUD operations on the crontab minicron needs to connect via SSH to the host.
When you set up a host minicron automatically creates a public/private key pair for you and stores it
in ~/.ssh on the host the minicron server is being run on using the naming schema minicron_host_*HOST_ID*_rsa(.pub).
You will then to add the public key into the remote hosts authorized_keys file.


Like many command line programs minicron will show its version number when the global options -v
or --version are passed to the CLI.


Some configuration options can be passed in manually but the recommend way to configure minicron is through the use
of a config file. You can specify the path to the file using the --config global option. The file is expected
to be in the toml format. The default options are specified in the
file and minicron will parse a config located in /etc/minicron.toml if it exists. Options specified via
the command line will take precedence over those taken from a config file.


As mentioned previously minicron is still under development and as such is missing some essential features as far as
security is concerned. For example authentication still needs to be added.

It is not recommended that you allow your minicron host to be accessible via the public internet!

Obviously without authentication anyone who knew the address of your minicron host would be able to set up
a potentially malicious job on one of your servers! Future versions may be secure enough to expose publicly but personally
I still would not recommend it, minicron is designed to be an internal tool and should be behind a firewall that only allows
connections from an internal network and/or a VPN.


All stable releases will follow the semantic versioning guidelines. Until 1.0 hits I will try
to document any breaking changes in the release descriptions but you should proceed with caution before relying
on anything etc etc

Releases will be numbered with the following format:


Based on the following guidelines:

  • A new major release indicates a large change where backwards compatibility is broken.
  • A new minor release indicates a normal change that maintains backwards compatibility.
  • A new patch release indicates a bugfix or small change which does not affect compatibility.


Feedback and pull requests are welcome, please see
for more info.

Areas that I would love some help with:

  • Any of the unassigned issues here.
  • General testing of the system, let me know what you think and create issues for any bugs you find!
  • Tests!!
  • Validation and error handling improvements
  • Documentation improvements.
  • Look for 'TODO:' notices littered around the code,
    I'm trying to convert them all to issues but there are a lot..
  • Code refactoring, I had a deadline to meet for the initial versions so some parts are a tad rushed
  • UI improvements


Where possible I will try and provide support for minicron but I offer no gurantees etc.

Feel free to open an issue and I'll do my best to help.


minicron makes use of a lot of awesome open source projects that have saved me a lot of time in its development.
I started out trying to list all of them but it was taking way too much time so check out the dependencies in
minicron.gemspec and


minicron is licensed under the GPL v3, see here for the full license

Docker Pull Command
Source Repository