vici
Your webhook robot 🎀
Named after vici ( Pronounced Vicky ) from Small Wonder TV series.
Install
via git
# with ssh git clone git@github.com:scriptnull/vici.git # with https git clone https://github.com/scriptnull/vici.git npm install npm start
via npm
npm install -g vici # start vici vici
via docker
docker run -p 4454:4454 -e VICI_SECRET="top_secret_key" scriptnull/vici:latest
Configure
vici
is a web server, that can execute scripts for the action you instruct.
Actions can be configured by giving a special file called vici.yml
.
actions: - name: echoHello script: "/scripts/echoHello.sh" - name: deploy-myapp script: "/scripts/deploy-myapp.sh"
The above vici.yml
will give you a POST /do/{action-name}
endpoint, which on requested will execute the script corresponding to that action.
All the action scripts receive 2 arguments.
payload
- The payload sent in the request body.query
- The query parameters as JSON value.
POST /do/echoHello?key=value
{ "hello" : "world" }
# echoHello.js echo "Hello world"echo "payload is $1" echo "query is $2"
Security
For now, all your requests to vici server must contain the VICI_SECRET as a query parameter or header.
- query -
POST /do/echoHello?secret=my_simple_vici_secret
- header -
X-VICI-SECRET : my_simple_vici_secret
Settings
vici settings can be changed by changing appropriate environment variables.
Env | Usage | Defaults |
---|---|---|
VICI_YML_PATH | path to find the vici yml file | vici.yml inside vici repository |
VICI_PORT | port to be used for vici server | 4454 |
VICI_SECRET | secret phrase to authenticate with vici | my_simple_vici_secret |
Advanced
Handling success and failures
vici can execute some other actions specified in the yml, in case of success or failure of one action.
success and failure is determined by the exit code of the script provided in the action.
actions: - name: notify-gitter script: "/scripts/notify-gitter.js" - name: echoHello script: "/scripts/echoHello.sh" on_success: - do: notify-gitter payload: url: "https://gitter.im/some-webhook-url" message: "Executed echoHello successfully" on_failure: - do: notify-gitter payload: url: "https://gitter.im/some-webhook-url" message: "Failed to execute echoHello"
BONUS : Script for notifying gitter
If echoHello
is success, it will trigger the actions in on_success
serially. In this case, only one action i.e. notify-gitter
do
tag instructs vici to send a HTTP request to vici server. payload
tag helps define payload to be sent in the HTTP request.
docker - cooking
scriptnull/vici
image is built on top of debian
installed with node.js
. So, you should be able to execute bash, python, node.js etc. scripts. If you are using docker
, this gets even more fun. You can cook the flavour of vici, you want.
Dockerfile for cooking flavour of vici, that could exceute ruby scripts looks like this
FROM scriptnull/vici:latest RUN apt-get install ruby-full -y
docker - mounting scripts
Mount volumes from host, to provide vici.yml and scripts.
docker run -p 4454:4454 -v /scripts:/scripts scriptnull/vici:latest
docker - mounting docker
Host's docker can be accessed from inside of vici, by mounting the docker sock.
docker run -p 4454:4454 -v /var/run/docker.sock:/var/run/docker.sock scriptnull/vici:latest
This is useful for cases, where vici is used to automate deployments via docker.
Contributing
Always welcome.
Thanks
Thanks for taking time to check vici
. It means a lot to the project.
Badge
If you are using vici in your stack, for automating deployments, remote execution etc. Support vici
project by adding a badge in your project.
[![vici](https://img.shields.io/badge/robot-vici-orange.svg)](https://github.com/scriptnull/vici)