regular

Regular

[!WARNING] This project is in early development.
It is not ready for others to use.

Regular is a job scheduler like cron and anacron.

Features

• Configuration using Starlark, a small configuration language based on Python. You can use expressions like hour in [9, 18] and minute == 0 to define when a job will run.
• Flexible scheduling based on current time and the last completed job
• Jitter to mitigate the thundering herd problem
• Job queues to configure what jobs run sequentially and in parallel
• Built-in logging and status reporting
• Built-in email notifications on localhost
• Hot reloading of job configuration on file change

Installation

You will need Go 1.22 or later:

go install dbohdan.com/regular@latest

Configuration

Jobs are defined in Starlark files named config.star in subdirectories of the config directory. For example:

# Run if at least a day has passed since the last run
# and it isn't the weekend.
def should_run(finished, timestamp, dow, **_):
    return dow not in [0, 6] and timestamp - finished >= one_day

# Random delay of up to 1 hour.
jitter = one_hour

# Command to run.
command = [
    "sh",
    "-c",
    "backup.sh ~/docs /backup/docs",
]

# Queue name (the default is the name of the job directory).
queue = "backup"

# Write output to log files (default).
log = True

# When to send notifications: "always", "on-failure" (default), "never".
notify = "always"

# Allow multiple instances in queue (default).
duplicate = False

# Enable/disable the job (default).
enable = True

Each job directory can also have an optional job.env file with environment variables:

PATH=${PATH}:${HOME}/bin
BACKUP_OPTS=--compress

Usage

General

• regular [flags] command
  • -h, --help Print help
  • -V, --version Print version number and exit
  • -c, --config-dir Path to config directory
  • -s, --state-dir Path to state directory

Commands

Start the scheduler:

• regular start

Run specific jobs once:

• regular run [--force] [job-names...]

Check job status:

• regular status [-l lines] [job-names...]

View application log:

• regular log [-l lines]

List available jobs:

• regular list

File locations

Default paths (override with -c and -s):

• Config: ~/.config/regular/

  • Global environment: ~/.config/regular/global.env
  • Job config: ~/.config/regular/<job>/config.star
  • Job environment: ~/.config/regular/<job>/job.env
  • Job executable (script): ~/.config/regular/<job>/job

• State: ~/.local/state/regular/

  • App log: ~/.local/state/regular/app.log
  • Database: ~/.local/state/regular/state.sqlite3
  • Lock file: ~/.local/state/regular/app.lock. When in use, this file prevents multiple instances of regular start from running at the same time.
  • Logs for the latest job: ~/.local/state/regular/<job>/{stdout,stderr}.log. These logs and earlier logs are also stored in the database.

The config and state directory are created automatically when you run regular start or regular run.

Job logs are truncated at 256 KiB. There is currently no built-in way to remove old logs from the database. You can use the sqlite3 command shell to remove logs manually.

All files and directories are created with 0600 and 0700 permissions respectively.

systemd service

Regular's repository includes a systemd user-service template for running the scheduler automatically.

To install and enable the service, clone the repository, then run:

cd systemd/
# Run this as your user, not as root.
./install.sh

This will:

• Create a service file in ~/.config/systemd/user/
• Enable the service to start automatically
• Start the service immediately

To check the service status:

systemctl --user status regular

To view logs:

journalctl --user -u regular -f

Shell completions

Regular includes shell completions for the fish shell.

fish shell

To install completion for the fish shell, clone the repository, then run:

cd completions/
./install.fish

This will copy the completion file to your fish configuration directory.

License

MIT. See the file LICENSE.