https://github.com/alphahydrae/scronpt

Run an arbitrary Bash script on a cron schedule, in a free Docker container 🍦
https://github.com/alphahydrae/scronpt

Last synced: 10 months ago
JSON representation

Run an arbitrary Bash script on a cron schedule, in a free Docker container 🍦

• Host: GitHub
• URL: https://github.com/alphahydrae/scronpt
• Owner: AlphaHydrae
• License: mit
• Created: 2025-08-16T10:51:24.000Z (11 months ago)
• Default Branch: main
• Last Pushed: 2025-08-16T10:56:28.000Z (11 months ago)
• Last Synced: 2025-08-16T12:58:10.803Z (11 months ago)
• Language: Shell
• Homepage:
• Size: 7.81 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

README

          
# scronpt

> Run an arbitrary [Bash][bash] script on a [cron][cron] schedule, in a free

> [Docker][docker] container 🍦

[![build](https://github.com/AlphaHydrae/scronpt/actions/workflows/build.yml/badge.svg)](https://github.com/AlphaHydrae/scronpt/actions/workflows/build.yml)

[![publish](https://github.com/AlphaHydrae/scronpt/actions/workflows/publish.yml/badge.svg)](https://github.com/AlphaHydrae/scronpt/actions/workflows/publish.yml)

[![MIT License](https://img.shields.io/static/v1?label=license&message=MIT&color=informational)](https://opensource.org/licenses/MIT)

## Usage

Scronpt will run the arbitrary script you provide on your schedule.

```bash

# Run a script hourly (default schedule)

docker run --rm --init \

       -v "/path/to/your/script:/usr/local/bin/script" \

       ghcr.io/alphahydrae/scronpt:1

# Run a script every day a quarter past midnight

docker run --rm --init -e "SCRONPT_CRON=15 0 * * *" \

       -v "/path/to/your/script:/usr/local/bin/script" \

       ghcr.io/alphahydrae/scronpt:1

# Run the default script that says hello, every minute

docker run --rm --init -e "SCRONPT_MINUTE=*" ghcr.io/alphahydrae/scronpt:1

```

> [!TIP]

> Your script runs in a temporary directory that is deleted once your script has

> finished executing, in case you need to work on some files.

## Configuration

| Environment variable       | Default value           | Description                                                                           |

| :------------------------- | :---------------------- | :------------------------------------------------------------------------------------ |

| `$SCRONPT_SCRIPT`          | `/usr/local/bin/script` | The script to run                                                                     |

| `$SCRONPT_MINUTE`          | `0`                     | Minute part of the cron schedule                                                      |

| `$SCRONPT_HOUR`            | `*`                     | Hour part of the cron schedule                                                        |

| `$SCRONPT_DAY`             | `*`                     | Day part of the cron schedule                                                         |

| `$SCRONPT_MONTH`           | `*`                     | Month part of the cron schedule                                                       |

| `$SCRONPT_DAY_OF_THE_WEEK` | `*`                     | Day of the week part of the cron schedule                                             |

| `$SCRONPT_CRON`            | `0 * * * *`             | The cron schedule to run the script on (built from the previous variables by default) |

| `$SCRONPT_UID`             | -                       | UID of the `scronpt` user that will run the script                                    |

| `$SCRONPT_GID`             | -                       | GID of the `scronpt` group of the user that will run the script                       |

## Exit codes

Scronpt will exit with the following codes when known errors occur:

| Code | Description                              |

| :--- | :--------------------------------------- |

| 1    | An unexpected error occurred.            |

| 10   | The script to execute cannot be found.   |

| 11   | The script to execute is not executable. |

[bash]: https://www.gnu.org/software/bash/

[cron]: https://en.wikipedia.org/wiki/Cron

[docker]: https://www.docker.com