https://github.com/cirello-io/runner
Runner is a structured command executer that monitor file changes to trigger process restarts.
https://github.com/cirello-io/runner
orchestrator procfile runner
Last synced: about 1 month ago
JSON representation
Runner is a structured command executer that monitor file changes to trigger process restarts.
- Host: GitHub
- URL: https://github.com/cirello-io/runner
- Owner: cirello-io
- License: apache-2.0
- Created: 2018-07-08T11:21:32.000Z (almost 7 years ago)
- Default Branch: v3
- Last Pushed: 2025-05-06T20:27:31.000Z (about 1 month ago)
- Last Synced: 2025-05-06T21:33:04.081Z (about 1 month ago)
- Topics: orchestrator, procfile, runner
- Language: Go
- Homepage: https://pkg.go.dev/cirello.io/runner/v3
- Size: 1.47 MB
- Stars: 16
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Runner
[](https://pkg.go.dev/cirello.io/runner/v3)
[](https://choosealicense.com/licenses/apache-2.0/)
runner is a structured command executer for Unix systems that monitor file
changes to trigger process restarts.
Create a file name Procfile in the root of the project you want to run, and add
the following content:
workdir: $GOPATH/src/github.com/example/go-app
formation: web web-a web-b db optional-service=0
observe: *.go *.js
ignore: /vendor
build-server: make server
web: restart=fail waitfor=localhost:8888 ./server serve
web-a: restart=onbuild waitfor=localhost:8888 ./server serve alpha
web-b: restart=onbuild waitfor=localhost:8888 ./server serve bravo
db: restart=failure waitfor=web ./server db
optional-service: ./optional-service
Special process type names:
- workdir: the working directory. Environment variables are expanded. It follows
the same rules for exec.Command.Dir.
- observe: a space separated list of file patterns to scan for. It uses
filepath.Match internally. File patterns preceded with exclamation mark (!) will
not trigger builds.
- ignore: a space separated list of ignored directories relative to workdir,
typically vendor directories.
- formation: allows to control how many instances of a process type are
started, format: procTypeA:# procTypeB:# ... procTypeN:#. If `procType` is
absent, it is not started. Empty formations start one of each process.
- build*: process type name prefixed by "build" are always executed first and in
order of declaration. On failure, they halt the initialization.
- waitfor (in process type): target hostname and port that the runner will probe
before starting the process type.
- restart (in process type): "onbuild" will restart the process type at every
build; "fail" will restart the process type on failure; "loop" restart the
process when it naturally terminates; "temporary" runs the process only once.
## CLI parameters
```Shell
NAME:
runner - simple Procfile runner
USAGE:
runner [global options] command [command options] [arguments...]
VERSION:
v3 (881f4e039f4ea6342464d4dc6ee3df9d362f5712)
COMMANDS:
logs Follows logs from running processes
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--service-discovery value service discovery address (default: "localhost:64000")
--formation procTypeA:# procTypeB:# ... procTypeN:# formation allows to control how many instances of a process type are started, format: procTypeA:# procTypeB:# ... procTypeN:#. If `procType` is absent, it is not started. Empty formations start one of each process.
--env file environment file to be loaded for all processes, if the file is absent, then this parameter is ignored. (default: ".env")
--skip procTypeA procTypeB procTypeN does not run some of the process types, format: procTypeA procTypeB procTypeN
--only procTypeA procTypeB procTypeN only runs some of the process types, format: procTypeA procTypeB procTypeN
--optional procTypeA procTypeB procTypeN forcefully runs some of the process types, format: procTypeA procTypeB procTypeN
--help, -h show help
--version, -v print the version
```
`-env file` loads the environment file common to all process types. It must be
in the format below:
```
VARIABLENAME=VALUE
VARIABLENAME=VALUE
```
Note: one environment variable per line.
`--formation procTypeA:# procTypeB:# ... procTypeN:#` allows to control
how many instances of a process type are started, format: procTypeA:#
procTypeB:# ... procTypeN:#. If `procType` is absent, it is not started. Empty
formations start one of each process.
## Environment variables available to processes
Each process will have two environment variables available.
`PS` is the name which the runner has christened the process.
`DISCOVERY` is the HTTP service that returns a JSON describing each process
type port. This assumes the process has honored the `PORT` variable and bound
itself to the configured one.
## Support
`runner/v3` is only supported in Unix platforms.
## Installation
`go get cirello.io/runner/v3`
https://pkg.go.dev/cirello.io/runner/v3