Configuration

Ocypod is configured from a single TOML file.

All sections and fields of the configuration are optional, and defaults shown will be used if not present.

The config file can be interpolated from the environment, see the environment variable interpolation section below for details.

Server section

General configuration for the ocypod-server itself, uses [server] as a section header.

Fields:

• host (string) - host address to listen on (default: "127.0.0.1")
• port (int) - port to listen on (default: 8023)
• threads (int) - number of HTTP worker threads (default: )
• max_body_size (string) - maximum body size for client POST/PUT requests as a human readable size (default: "256kB")
• shutdown_timeout (string) - graceful shutdown time for workers, triggered by SIGTERM signal (default: "30s")
• timeout_check_interval (string) - frequency of checks for jobs to time out, as a human readable duration (default: "30s")
• retry_check_interval (string) - frequency of checks for jobs to retry, as a human readable duration (default: "1m")
• expiry_check_interval (string) - frequency of checks for jobs to expire (i.e. remove from the queue system), as a human readable duration (default: "5m")
• next_job_delay (string) - artifical delay added to client responses when polling for new jobs (default: "0s")

Example:

[server]
host = "0.0.0.0"
port = 8023
threads = 2
max_body_size = "10MiB"
timeout_check_interval = "1m"
retry_check_interval = "30s"
expiry_check_interval = "1h"
next_job_delay = "5s"

Redis section

Configuration for connectivity to the Redis server used by Ocypod. Uses [redis] as a section header.

Fields:

• url (string) - Redis connection URI (default: "redis://127.0.0.1")
• key_namespace (string) - optional prefix to add to all Redis keys used by Ocypod(default: "")

The key_namespace can be set to avoid any key collisions when running separate Ocypod on a Redis server used by other applications. The namespace will be added as a prefix to all keys Ocypod creates (e.g. if key_namespace="abc", then a queue named "x" will be created with key abc:queue:x instead of queue:x).

Example:

[redis]
url = "redis://:my_password@example.com:6379/my_db"

Queue sections

Queues can be configured to be created when Ocypod starts by configuring them here, in order to simplify deployment without having to explicitly create queues via HTTP requests.

Configuring a queue here is the equivalent to calling the PUT /queue/{queue_name} endpoint.

Each queue section should be of the form:

[queue.{queue_name}]

Note: queues configured in this way will be created at Ocypod startup if they don't exist, or updated if they exist with different settings. Queues will never be deleted if removed from a configuration file, that will remain a manual task.

Fields:

• timeout (string)
• heartbeat_timeout (string)
• expires_after (string)
• retries (integer)
• retry_delays (list of string)

For details on these, see the queue settings section.

Any of the fields may be omitted, in which case default values will be used.

Example:

The configuration below will create 3 queues, named default, my_2nd_queue, and another-queue.

[queue.default]

[queue.my_2nd_queue]
retries = 5
retry_delays = ["10s", "1m", "5m"]

[queue.another-queue]
timeout = "5m"
heartbeat_timeout = "30s"
expires_after = "1d"

Environment variable interpolation

The TOML configuration file supports interpolation from environment variables, in order to simplify running Ocypod in different environments without having to modify the configuration file each time.

Interpolation can be done anywhere in the config file, and is of the form:

${VARIABLE_NAME}

If an environment variable is not set, then the service will fail to start with an error.

Defaults can also be specified to allow fallback values if an environment variable is not set:

${VARIABLE_NAME=default_value}

An empty default value can also be used as a default to allow an environment variable to be missing and default to an empty string, e.g.:

name = "${PREFIX=}name"

An example of a config file using these features might look as follows:

[server]
host = "${OCYPOD_HOST=localhost}"
port = ${OCYPOD_PORT=8023}
log_level = "${OCYPOD_LOG_LEVEL=info}"
timeout_check_interval = "5s"
retry_check_interval = "5s"
expiry_check_interval = "5s"

[redis]
url = "redis://${REDIS_HOST}:${REDIS_PORT}"

[queue.${QUEUE_PREFIX=}default}]
timeout = "1m"
retries = 2

[queue.${QUEUE_PREFIX=}queue2}]
timeout = "5m"

This would require the REDIS_HOST and REDIS_PORT environment variables to be set, and would fall back to defaults for the others.