Ofelia Job Scheduler

Ofelia supports four types of jobs using a scheduling format compatible with Go's cron implementation (e.g., @every 10s or 0 1 * * *).

Job Types:

• job-exec: Executes a command inside a running container.
• job-run: Runs a command inside a new container using a specific image.
• job-local: Runs the command inside the host running Ofelia.
• job-service-run: Runs the command inside a new "run-once" service (for Docker Swarm).

Note on version 0.3.x: For the current 0.3.x version, seconds configuration in the cron spec is required. In newer versions (0.4.x+), seconds are optional.

Ofelia supports three logging drivers: mail, save, and slack. These are configured in the [global] section of a config.ini file or via labels on the ofelia container.

Mail options:

• smtp-host: SMTP server address.
• smtp-port: SMTP server port.
• smtp-user: SMTP username.
• smtp-password: SMTP password.
• smtp-tls-skip-verify: If true, ignores certificate errors.
• email-to: Recipient email address.
• email-from: Sender email address.
• mail-only-on-error: If true, only sends mail on failure.

Save options:

• save-folder: Directory for reports (must exist).
• save-only-on-error: If true, only saves reports on failure.

Slack options:

• slack-webhook: Slack webhook URL.
• slack-only-on-error: If true, only sends Slack messages on failure.

To run Ofelia as a scheduler for Docker, use the daemon --docker command. This requires mounting the Docker socket (/var/run/docker.sock) into the container with read-only permissions so Ofelia can interact with the Docker API.

services:
  ofelia:
    command: daemon --docker
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Ofelia can dynamically discover and manage jobs by reading Docker container labels. When enabled, Ofelia watches the Docker event stream for container lifecycle changes (create, start, stop, etc.) and hot-reloads its configuration automatically.

To use this feature, you must enable the --docker flag in your Ofelia command-line invocation. You can also provide specific Docker filters to limit which containers Ofelia inspects.

You can define jobs in an INI-style configuration file and run Ofelia with the --config flag.

[job-exec "job-executed-on-running-container"]
schedule = @hourly
container = my-container
command = touch /tmp/example

[job-run "job-executed-on-new-container"]
schedule = @hourly
image = ubuntu:latest
command = touch /tmp/example

[job-local "job-executed-on-current-host"]
schedule = @hourly
command = touch /tmp/example

[job-service-run "service-executed-on-new-container"]
schedule = 0,20,40 * * * *
image = ubuntu
network = swarm_network
command =  touch /tmp/example

Use job-exec to execute a command inside a currently running container, similar to docker exec.

Required Parameters:

• schedule: Cron expression or @every format (e.g., @every 10s or 0 0 1 * * *). Note that the format starts with seconds.
• command: The command to run.
• container: The name of the target container.

Optional Parameters:

• user: User to execute the command as (default: root).
• tty: Allocate a pseudo-tty (default: false).
• environment: Environment variables (e.g., FOO=bar).
  • In INI files, use environment multiple times.
  • In Docker labels, use a JSON array: ["FOO=bar", "BAZ=qux"].
  • Note: environment in job-exec requires Docker API 1.25 or higher.

[job-exec "flush-nginx-logs"]
schedule = @hourly
container = nginx-proxy
command = /bin/bash /flush-logs.sh
user = www-data
tty = false

Use job-service-run to run a command inside a new "run-once" service, specifically designed for use within a Docker Swarm environment.

Parameters:

• schedule: Cron expression or @every format (Required).
• image: The image to use (Required).
• command: Command to run (defaults to container default).
• network: Connect to a specific network.
• delete: Delete the container after job finishes (default: true).
• user: User to execute as (default: root).
• tty: Allocate a pseudo-tty (default: false).

[job-service-run "service-executed-on-new-container"]
schedule = 0,20,40 * * * *
image = ubuntu
network = swarm_network
command =  touch /tmp/example

Use job-local to run commands directly on the host machine where Ofelia is running.

Important Note: If Ofelia is running inside a container, job-local executes the command inside the Ofelia container, not on the Docker host.

Parameters:

• schedule: Cron expression or @every format (Required).
• command: The command to execute (Required).
• dir: Base directory for execution (default: current directory).
• environment: Environment variables (e.g., FOO=bar).
  • In INI files, use environment multiple times.
  • In Docker labels, use a JSON array: ["FOO=bar", "BAZ=qux"].

[job-local "create-file"]
schedule = @every 15s
command = touch test.txt
dir = /tmp/

Ofelia connects to the Docker daemon via /var/run/docker.sock by default. You can override this using the following environment variables:

• DOCKER_HOST: The Docker host to connect to (e.g., tcp://docker-proxy:2375, unix:///custom/docker.sock).
• DOCKER_TLS_VERIFY: Enable TLS verification (set to 1 to enable).
• DOCKER_CERT_PATH: Path to TLS certificates directory.
• DOCKER_API_VERSION: Docker API version to use.