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

# Kill the job if it runs longer than this.
# 0 (default) means no timeout.
timeout = 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...]

[!NOTE] When a regular start daemon is running, run connects to it over a Unix socket and streams the job's stdout, stderr, and exit code back to your terminal. Ad hoc runs use the same queues and avoid duplication just like scheduled runs.

With no daemon running, run falls back to executing the job in its own process. Concurrent standalone invocations avoid conflict using a lock file in the state directory.

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. regular run also takes this lock when no daemon is running.
  • Logs for the latest job: ~/.local/state/regular/<job>/{stdout,stderr}.log. These logs and earlier logs are also stored in the database.

• Daemon socket: $XDG_RUNTIME_DIR/regular/socket (or, with no runtime dir, a per-user subdir under $TMPDIR). Set REGULAR_SOCK to override. The socket is created with mode 0600 and the client refuses to connect to one owned by another user.

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 unit file for running the scheduler automatically as your user. Installation requires replacing %USER% with your username.

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 completions 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.