Skip to content

Advanced Configuration

Jump to bottom Edit New page
Oliver Salzburg edited this page Jul 27, 2016 · 8 revisions

Advanced Strider Configuration

Strider will work as a great CI/CD solution out of the box, but if you really want to get the most out of Strider, you're going to want to deploy more advanced means of configuring it.

In this guide, we'll cover:

  • getting Strider to use Docker to process jobs
  • configuring your jobs with a strider.json file
  • tuning Strider performance

Docker

Strider comes with 2 runners. A runner is the module that processes your jobs.

By default, the simple runner is used. The simple runner will process a job on the server on which Strider runs. So it uses the active operating system and just runs all commands directly in the shell.

This is great, because it is easy to set up and understand. However, your jobs will be affected by the environment set up by your operating system and it can be hard to fully control your testing environment.

This is where Docker comes into play. Setting up Docker on your server is out of the scope of this guide. So we're going to assume that you've already managed to set it up.

Installation

To enable Docker support in Strider, go to Admin → Plugins and Install the Docker Runner plugin.

That's it.

Usage

You can now go into the settings for one of your projects, go to the Plugins section and change the runner to Docker. Then you can go to the Runner: Docker section and configure the runner.

The default settings will usually work fine if Docker is running on the same host as Strider and if your project works fine with the default Docker image provided by Strider.

In case the default image doesn't work for you, you're going to want to publish your own Docker image. For an image to work right with Strider, certain mechanics need to be implemented in the container. To get a working image that interacts fine with Strider, you should fork an existing image and work from there:

The strider.json file

Everything that you can set through the Strider web interface can also be controlled through a file named strider.json, which you put directly into your repository. This should be the preferred way to configure Strider, as it keeps CI/CD settings within the repository; giving you all the benefits of VCS and simplifying configuration.

If you're planning on using the strider.json approach, it is recommended to import new projects into Strider using the custom project type. This ensures that no default plugins are loaded, which would only interfere with your strider.json.

Let's look at a complete example first:

{
	"runner": {
		"id": "docker",
		"config": {
			"image": "fairmanager/strider-docker-slave"
		}
	},
	"merge_plugins": true,
	"plugins": [
		{
			"id": "node",
			"enabled": true,
			"showStatus": true,
			"config": {
				"test": "npm test",
				"caching": "none",
				"runtime": "whatever",
				"fork": ""
			}
		},
		{
			"id": "custom",
			"enabled": true,
			"config": {
				"shell": "bash",
				"prepare": ".scripts/prepare.sh --<%= ref.branch %>",
				"deploy": ".scripts/deploy.sh --<%= ref.branch %>"
			}
		}
	]
}

Now let's go through this step-by-step.

runner

The first section is the runner section. Here we tell Strider what job runner to use. We can pick the simple runner, where the id is simple-runner, or we can use Docker one (which we want) and set the id to docker.

Note: If you don't specify a runner section at all, Strider will default to the simple runner.

We can then provide additional configuration options to the runner. These are the options you would usually set on the Runner: Docker section of your project configuration. As seen in the example, this is the perfect place to set your Docker image.

Note: You might be inclined to attempt to use an image like node:4 to run your jobs. However, these official images will not work with Strider, as Strider requires a certain service to run inside the image, so that Strider can run arbitrary commands inside the container.

Note: If Strider is running on Windows, the default Docker host setting will not work for you, as Strider will attempt to connect to a UNIX socket to connect to Docker. It is advised to run Strider in an environment where DOCKER_HOST is set to tcp://localhost:2375. Setting the host in the strider.json should be discouraged.

merge_plugins

If you set this directive to false, the complete configuration made through the web UI is discarded and only the configuration set through the strider.json is respected.

You'll rarely want to do this, as certain configurations are best left in the web UI and you want those to be merged with those made through strider.json. A common use case would be setting secret environment variables through the Environment plugin in the web UI.

Regardless of if you want this to be true or false, it is recommended to explicitly set this in your strider.json, as a change in the default behavior might have a major impact on your jobs!

plugins

Here you'll list all the Strider plugins you're going to use in your jobs. Note that the order in which you define your plugins here, is the order in which Strider is going to process them when it processes a job.

id

Most importantly, you'll identify each plugin by the id value. This can be found in the plugin's package.json file. For example, in the strider section of strider-custom. Every Strider plugin has a strider section in their package.json. It's also important to note that any referenced plugin first needs to be installed manually through the web UI.

enabled

I really can't see any reason to set this to anything other than true, but make sure to do that.

showStatus

The author is not clear on the specifics of this directive. It is recommended to set it to true or leave it off completely.

The setting is related to the build-status section in the strider block in a plugin's package.json. This lets plugins render their own "status" somewhere in the UI. It is not clear where though. The only plugin that makes use of this feature is strider-node.

config

The configuration of each plugin is specific to the plugin itself and is highly unlikely to be documented, although the settings are defined in the plugins config schema, e.g. for strider-node it would be here.

In the example above, we see the important directives for 2 plugins: node and custom. Here is what the individual settings are for:

node
  • test Specifies the command to run during the testing phase in Strider. Set this to an empty string (or <none>) to disable testing.
  • caching How the node_modules should be cached. When building in a Docker container, this has no effect, so leave it as none.
    • none No caching will be performed.
    • loose Runs npm update and npm prune on every run.
    • strict Any changes to your package.json will result in a fresh npm install of all dependencies.
  • runtime What version of NodeJS should be used to run your tests? The node plugin uses n for version management. So any version string accepted by n, will work here. Set this to whatever to use the version provided by the operating system.
  • fork In case you want to use io.js you can set that here.
custom
  • shell The shell to use. If none is provided /bin/sh is used on UNIX-like operating systems and cmd on Windows.

    If you're running Docker on Windows and your container is running a UNIX-like operating system, make sure to set the shell to bash or another fixed shell, other than cmd.

  • environment, prepare, test, deploy, cleanup Commands to run during that specific phase of the job. Commands can be simple strings, which are invoked through the shell or they can be arrays of objects, where each object has a command and screen member. In the latter case, screen controls what is printed in the UI. Per default, the command itself is printed.
    If you want to run a single command that spans multiple lines, use a single string with \n to separate lines.

Defaults

Now let's look at a cleaner example, which makes use of defaults:

{
	"runner": {
		"id": "docker",
		"config": {
			"image": "fairmanager/strider-docker-slave"
		}
	},
	"merge_plugins": true,
	"plugins": [
		{
			"id": "node",
			"enabled": true
		},
		{
			"id": "custom",
			"enabled": true,
			"config": {
				"shell": "bash",
				"prepare": {
					"screen": "Preparing...",
					"command": ".scripts/prepare.sh --<%= ref.branch %>"
				},
				"deploy": {
					"screen": "Deploying...",
					"command": ".scripts/deploy.sh --<%= ref.branch %>"
				}
			}
		}
	]
}

This configuration would:

  • run in Docker
  • with NodeJS, whatever version is provided by the container
  • running npm test for testing
  • without caching node_modules
  • run 2 custom commands to invoke actions defined in the project code itself

Performance

Once you have a Docker-based build system going, you can set Strider to run multiple jobs concurrently. This can be problematic with the simple runner, as jobs might interfere with each other, especially when you consider caches.

All you want to do is set the environment variable CONCURRENT_JOBS to a value higher than 1. The number of available CPUs is usually a good value to start with.

Note that Strider will only run builds concurrently if they are for different projects or different branches. If you trigger two individual pushes to master, that would still cause the second job to be queued.

Add a custom footer
Add a custom sidebar
Clone this wiki locally