Before we can get a basic
stampede system setup, there are several dependencies that we need to make available.
There are many ways to install
node.js, so go to the official site: nodejs.org and install for the platform you want to run
stampede on. You will need at least version 8 installed, but newer versions should work as well.
An instance of
redis needs to be running for the
stampede components to use. You can run
redis in many different ways, but 2 common methods are to use
docker, or to use a cloud based redis such as redislabs.com. Once you have an instance of
redis running, you will need to know the IP address (or name) of the host, and the port that
redis is running on (the default port is 6379). Optionally you might need a password, depending on the authentication method used to run the server.
Installing Stampede Server
To install the server component, use the following command:
npm install -g stampede-server
To configure the server, you can do this by creating a
.stampederc file in your user home directory. At
the least, the config file should contain the redis connection information you collected above:
redisHost=<host name> redisPort=<port> redisPassword=<optional password>
Configuring GitHub connection to the server
Connecting the server to GitHub requires creating an
app in GitHub, obtaining an app id and downloading a PEM certificate. Configuring these items are also done in the
githubAppID=<id> githubAppPEMPath=<path to pem file>
Finally the GitHub app needs to have its Webhook URL configured to connect to the server. If you are running your server on the internet, you can connect directly to the server using the default port of 7766. You can change the port using the
Running the server
You can run the server just by executing the
stampede-server command directly. Another option is to use
pm2 to manage the server. You can install
pm2 by using the command:
npm install -g pm2. Then starting the server in
pm2 is as simple as:
pm2 start stampede-server.
Configuring your first task
Configuring tasks is done by creating a YAML file that represents the details for the task, then using the
stampede-cli app to upload the details into the redis cache. At a minimum, you will need the following details: a task identifier, a title, the queue that will be used to request execution, the list of parameters and the command for the worker to use to execute the task. A sample task config file would look like this:
id: first-task title: The first task queue: tasks config: - key: task-parameter worker: taskCommand: task-script.sh
This config will enable a task with an id
first-task with a single parameter
task-parameter and when it is executed by the worker, the worker will execute the
task-script.sh command to perform the work.
To load this task into the system, we can use the
stampede-cli command line admin app. Install it using
npm install -g stampede-cli. If you have configured the
stampede-server using a
.stampederc file in your home folder, you don’t need to do anything else to configure
stampede-cli. Just execute
stampede-cli on the command line and you will be loaded into the cli. At the
stampede> prompt, you can type
help to see the list of commands that the cli supports. For loading the task, we will use the
setTask command. It simply takes in a path to the YAML file you created above. Once you have loaded the task you can verify it with the
tasks command which will list out all the configured tasks.
Installing Stampede Worker
Now that we have configured a task, we need to run a worker to handle any requests to execute that task. Note that our example task above specified the queue with a name of
tasks. Note that each task and each worker instance only can be configured for a single queue. But you can have as many tasks use the same queue as you like, and you can have as many workers serving a single queue as you like. For our first worker we are going to configure it to execute from the
First to install the worker, use
npm again. Just execute
npm install -g stampede-worker. For the worker it is best to create a separate config file for each instance you want to run. So create a
.workerrc and at least add the following items to the file:
redisHost=<host name> redisPort=<port> redisPassword=<optional password> taskQueue=tasks stampedeScriptPath=<path to script files> workspaceRoot=<path to workspace root folder> nodeName=<node name> workerName=<worker name>
The worker will only execute scripts that are located in the path specified in the
stampedeScriptPath config. For our test task, be sure to create a
test-script.sh file and put it into the path that you specify in
workspaceRoot is a temp folder where the worker will clone repositories to execute commands in.
workerName are just strings that identify the worker when using some of the monitoring tools.
Executing the worker
Once we have our
.workerrc file, we can start the worker using the following command:
stampede-worker --config .workerrc
Now the worker is ready to receive requests and execute tasks.
Setting up a repository to execute the task
Now that we have a server and worker running, we will want to test it out. For GitHub integrations, you need to configure the stampede GitHub app so it has access to the repository you want to test with. Once that has been configured, the
stampede-server will start to receive events whenever pull requests, branch pushes or releases happen in the repository. Until the repository contains a
.stampede.yaml file, however, no tasks will be requested.
For our first task, create a
.stampede.yaml file in the repository with the following structure:
pullrequests: tasks: - id: first-task config: task-parameter: avalue
This will trigger the
first-task to be executed whenever we create a pull request in the repository. If all goes well, you should see a check show up when the pull request is created.