# sprinkler (s7r)
Sprinkler is a easy to use job runner. It runs individual tasks inside of docker containers on a single host machine.
Currently sprinkler supports both python and nodejs (yarn and npm) runtimes.
Sprinkler works best when integrated with a git repository.
# Prerequisites
- Python3 >= 3.6
- redis
- docker
# Quickstart
After installing the prerequisites you can install sprinkler via pip.
```bash
pip3 install s7r
```
The sprinkler tool is now available on the command line via the `sprinkler` keyword.
```bash
sprinkler version
```
There are three sprinkler services that all perform different functions.
- task-manager
- webserver
- scheduler
When setting up sprinkler in a production environment, we recommend using
systemd to orchestrate these services.
In order to enable all sprinkler functionality, run all three of these services.
To enable secrets encryption and secure sessions make sure that the `SPRINKLER_SECRET`
environment variable is set. If this variable changes, then sprinkler will be unable to
decrypt secrets, and all sessions will be invalidated.
When run, sprinkler will create a `.sprinkler` directory in your home directory.
Inside of this, the sqlite database which stores run history, config values, secrets,
and api keys is held, as well as sub-directories for local logs, and the sprinkler generated ssh key.
After starting the services, the rest of the setup is easiest to complete through the UI
although it can all be completed from the CLI as well.
You must point sprinkler to the targets directory by setting the `TARGETS_DIRECTORY` config.
To set up sprinkler with a remote git repo in the sprinkler directory,
then use the `sprinkler git init ~/.sprinkler/ git@github.com:<...>` command.
This will clone the given remote into a subdirectory within the `.sprinkler` directory.
This will automatically set the `TARGETS_DIRECTORY` to the root directory inside of the repo that you cloned.
With all of the services running, and the `TARGETS_DIRECTORY` set, you can utilize the UI or CLI to configure sprinkler and trigger tasks.
# Sprinkler-Utils
Sprinkler provides a utils package for use within sprinkler tasks. The package provides the following functions:
## get_request_body
This function will return the request body if one exists. This enables content to be passed
into the task when it is triggered by a webhook. If the task is triggered by a schedule
then this will return None.
## get_secret
This function will return the value of a secret. If the secret doesn't exist, then a default value can be provided.
## send_response
This function can be used to send a response to a request. This function should only be invoked once per task.
The response will be sent upon completion of the entire task. Additionally the task must be setup as a `call-and-response`
type task for the response to be sent. Otherwise sprinkler will reply with a `task started`
message immediately upon receiving a trigger. This type of task can be used as a simple webserver,
however it is important to realize that this will not be as performant as other webservers as each request
is handled within a separate docker container.
# sprinkler_config.yaml
Each target is required to have a `sprinkler_config.yaml` file. This file defines the runtime for the target,
as well as the tasks within the target.
## Schema
```yaml
runtime: python | node-npm | node-yarn # The runtime.
version: string # The version of the runtime to use.
os: Optional[string] # The os for the image to use.
# The runtime, version, and os will be combined together to pick the base image to utilize.
# {runtime}{version}-{os} EX: python3.11-slim-buster
failure_task: Optional
target: string # The target containing the task to trigger when a task within this target fails.
task: string # The task to trigger when a task within this target fails.
tasks:
- task: string # The name of the task.
entrypoint: string # The file to execute when running this task
schedule: Optional[string[chron expression]] # A schedule to run this task on.
timeout: Optional[int] # The number of seconds to let this task run before killing it. If it is not set, then the task will run indefinitely.
failure_task:
target: string # The target containing the task to trigger when a task within this target fails.
task: string # The task to trigger when a task within this target fails.
type: call-and-response | fire-and-forget # The default task type is `fire-and-forget`.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/henryivesjones/sprinkler",
"name": "s7r",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "scheduler,task runner,task,job",
"author": "Henry Jones",
"author_email": "Henry Jones <henryivesjones@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f7/8d/144289ef840e20bcb40dc4c7367be76e10092b629fb2e1c0177a758ad706/s7r-0.1.9.tar.gz",
"platform": null,
"description": "# sprinkler (s7r)\nSprinkler is a easy to use job runner. It runs individual tasks inside of docker containers on a single host machine.\nCurrently sprinkler supports both python and nodejs (yarn and npm) runtimes.\n\nSprinkler works best when integrated with a git repository.\n\n# Prerequisites\n - Python3 >= 3.6\n - redis\n - docker\n\n\n# Quickstart\nAfter installing the prerequisites you can install sprinkler via pip.\n```bash\npip3 install s7r\n```\n\nThe sprinkler tool is now available on the command line via the `sprinkler` keyword.\n```bash\nsprinkler version\n```\n\nThere are three sprinkler services that all perform different functions.\n - task-manager\n - webserver\n - scheduler\nWhen setting up sprinkler in a production environment, we recommend using\nsystemd to orchestrate these services.\n\nIn order to enable all sprinkler functionality, run all three of these services.\nTo enable secrets encryption and secure sessions make sure that the `SPRINKLER_SECRET`\nenvironment variable is set. If this variable changes, then sprinkler will be unable to\ndecrypt secrets, and all sessions will be invalidated.\n\nWhen run, sprinkler will create a `.sprinkler` directory in your home directory.\nInside of this, the sqlite database which stores run history, config values, secrets,\nand api keys is held, as well as sub-directories for local logs, and the sprinkler generated ssh key.\n\nAfter starting the services, the rest of the setup is easiest to complete through the UI\nalthough it can all be completed from the CLI as well.\n\nYou must point sprinkler to the targets directory by setting the `TARGETS_DIRECTORY` config.\n\nTo set up sprinkler with a remote git repo in the sprinkler directory,\nthen use the `sprinkler git init ~/.sprinkler/ git@github.com:<...>` command.\nThis will clone the given remote into a subdirectory within the `.sprinkler` directory.\nThis will automatically set the `TARGETS_DIRECTORY` to the root directory inside of the repo that you cloned.\n\nWith all of the services running, and the `TARGETS_DIRECTORY` set, you can utilize the UI or CLI to configure sprinkler and trigger tasks.\n\n# Sprinkler-Utils\nSprinkler provides a utils package for use within sprinkler tasks. The package provides the following functions:\n\n## get_request_body\nThis function will return the request body if one exists. This enables content to be passed\ninto the task when it is triggered by a webhook. If the task is triggered by a schedule\nthen this will return None.\n\n## get_secret\nThis function will return the value of a secret. If the secret doesn't exist, then a default value can be provided.\n\n## send_response\nThis function can be used to send a response to a request. This function should only be invoked once per task.\nThe response will be sent upon completion of the entire task. Additionally the task must be setup as a `call-and-response`\ntype task for the response to be sent. Otherwise sprinkler will reply with a `task started`\nmessage immediately upon receiving a trigger. This type of task can be used as a simple webserver,\nhowever it is important to realize that this will not be as performant as other webservers as each request\nis handled within a separate docker container.\n\n\n# sprinkler_config.yaml\nEach target is required to have a `sprinkler_config.yaml` file. This file defines the runtime for the target,\nas well as the tasks within the target.\n## Schema\n```yaml\nruntime: python | node-npm | node-yarn # The runtime.\nversion: string # The version of the runtime to use.\nos: Optional[string] # The os for the image to use.\n# The runtime, version, and os will be combined together to pick the base image to utilize.\n# {runtime}{version}-{os} EX: python3.11-slim-buster\nfailure_task: Optional\n target: string # The target containing the task to trigger when a task within this target fails.\n task: string # The task to trigger when a task within this target fails.\n\n\ntasks:\n - task: string # The name of the task.\n entrypoint: string # The file to execute when running this task\n schedule: Optional[string[chron expression]] # A schedule to run this task on.\n timeout: Optional[int] # The number of seconds to let this task run before killing it. If it is not set, then the task will run indefinitely.\n failure_task:\n target: string # The target containing the task to trigger when a task within this target fails.\n task: string # The task to trigger when a task within this target fails.\n type: call-and-response | fire-and-forget # The default task type is `fire-and-forget`.\n\n```\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "An easy to use job runner.",
"version": "0.1.9",
"project_urls": {
"Homepage": "https://github.com/henryivesjones/sprinkler"
},
"split_keywords": [
"scheduler",
"task runner",
"task",
"job"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a84c573753d584e1ff8825ffe4768acae7d8b868a3c01c65fdb319b60e381ad2",
"md5": "19f2bbbe5ea7d8be23d2541234b6cfd0",
"sha256": "b51d46876b0e3551d4e00c9f6edec015889957819f23fd845b27f38d176841c0"
},
"downloads": -1,
"filename": "s7r-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "19f2bbbe5ea7d8be23d2541234b6cfd0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 120021,
"upload_time": "2023-05-04T16:18:55",
"upload_time_iso_8601": "2023-05-04T16:18:55.721404Z",
"url": "https://files.pythonhosted.org/packages/a8/4c/573753d584e1ff8825ffe4768acae7d8b868a3c01c65fdb319b60e381ad2/s7r-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f78d144289ef840e20bcb40dc4c7367be76e10092b629fb2e1c0177a758ad706",
"md5": "75ba9de2f0f1fc1ac73f87ac08c14b01",
"sha256": "4bdcf78c5cd4c7230fb9e8268e44e84fd4a997609e8730eafbc01186fda6c412"
},
"downloads": -1,
"filename": "s7r-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "75ba9de2f0f1fc1ac73f87ac08c14b01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 112105,
"upload_time": "2023-05-04T16:18:57",
"upload_time_iso_8601": "2023-05-04T16:18:57.906036Z",
"url": "https://files.pythonhosted.org/packages/f7/8d/144289ef840e20bcb40dc4c7367be76e10092b629fb2e1c0177a758ad706/s7r-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-04 16:18:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "henryivesjones",
"github_project": "sprinkler",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "s7r"
}
JSON
