Experiment Configuration¶

In order for LabTest to create an experiment, it needs a little bit of information about your project. LabTest requires very little configuration, but allows for lots of customization.

Automatic configuration files¶

Most code repositories have enough configuration files, and we didn’t want to add another configuration file. Lab Test will automatically look for its configuration information in several files already in your repository, under a labtest section:

.labtest.yml
setup.cfg
package.json

Alternate configuration files¶

You can alternatively pass the configuration file to Lab Test at the command line with the --config option. Lab Test supports .ini, .yml/.yaml, and .json formats.

Example .ini configuration¶

[labtest]
app_name = testing
host = 10.2.3.4
use_ssh_config = true
code_repo_url = git@github.com:CityOfBoston/testdemo.git
app_build_image = drydock/u16nodall
app_build_command = ./bin/app-build
test_domain = test.example.com
environment = FOO=bar,TEST=true,DEBUG=true,MY_HOST=$VIRTUAL_HOST

Example .yaml configuration¶

labtest:
  app_name: testing
  host: 10.2.3.4
  use_ssh_config: true
  code_repo_url: git@github.com:CityOfBoston/testdemo.git
  test_domain: test.example.com
  environment:
    - FOO=bar
    - TEST=true
    - DEBUG=true
    - MY_HOST=$VIRTUAL_HOST

Example .json configuration¶

{
    "labtest": {
        "app_name": "testing",
        "host": "10.2.3.4",
        "use_ssh_config": true,
        "code_repo_url": "git@github.com:CityOfBoston/testdemo.git",
        "test_domain": "test.example.com",
        "app_build_image": "drydock/u16nodall",
        "app_build_command": "./bin/app-build",
        "environment": [
            "FOO=bar",
            "TEST=true",
            "DEBUG=true",
            "MY_HOST=$VIRTUAL_HOST"
        ]
    }
}

Required configuration options¶

There are several options that are required in order for Lab Test to work correctly.

`host`¶

Default:	`None`
Required:	`True`
Acceptable values:	String or IP Address

The DNS name, IP address or SSH config Host of the test server. You need this to connect to the laboratory.

`test_domain`¶

Default:	`None`
Required:	`True`
Acceptable values:	String

The DNS subdomain in which the test server lives. This is the wildcard DNS name without the *., like test.example.com. This is used with host_name_pattern to create the virtual host name.

`app_build_command`¶

Default:	`None`
Required:	`False`
Acceptable values:	Strings

The script or command to run to build the app within the Docker image. This is required if you want to build the application on the test server. Also set the app_build_image option.

This command is executed from within the container and in the project’s directory.

For example:

app_build_command: npm run build

If you require several commands, you will need to create a script in your repository that we can run:

app_build_command: ./bin/build_my_app

If the execute bit is not set you must include the name of the program to execute the script, for example:

app_build_command: python ./config/build.py

or:

app_build_command: bash bin/build_my_app

`app_build_image`¶

Default:	`None`
Required:	`False`
Acceptable values:	String

The Docker image to use to build the app. Shippable has some great images publicly available. Here is their docker page. This is required if you want to build the application on the test server. Also set the app_build_command option.

`app_name`¶

Default:	The name of the project directory
Required:	`False`
Acceptable values:	Strings

The name of the application. Ideally this should be a URL-friendly value. In order to get the default value, the labtest command must be made from within a Git repository.

`before_start_command`¶

Default:	`None`
Required:	`False`
Acceptable values:	Strings

The script or command to run from within the newly-built Docker image before the service is started.

This command is executed from within the container as the experiment will run; you will have access to all backing services. Its working directory will depend on your project’s Dockerfile and its WORKDIR setting.

Warning

Any scripts you need to call must be in the container. The project directory from the host will not be mounted.

For example:

before_start_command: ./manage.py migrate

If you require several commands, you will need to create a script in your repository that we can run:

before_start_command: ./bin/update_database

If the execute bit is not set you must include the name of the program to execute the script, for example:

before_start_command: python ./config/migrate.py

or:

before_start_command: bash bin/update_my_app

`build_provider`¶

Default:	`local`
Required:	`False`
Acceptable values:	`local`

This is how your application and Docker image are built. Currently only local is supported.

You must also set code_repo_url, app_build_image, app_build_command. If the default for container_build_command doesn’t work for your project, set that too.

`code_repo_url`¶

Default:	`None`
Required:	`False`
Acceptable values:	URL

The URL of the code repository to check out.

`container_build_command`¶

Default:	(reformatted for clarity) docker build \ -t $APP/$INSTANCE \ --build-arg RELEASE=$RELEASE \ --build-arg APP_NAME=$APP \ --build-arg BRANCH_NAME=$BRANCH \ --build-arg INSTANCE_NAME=$INSTANCE \ .
Required:	`False`
Acceptable values:	Docker build command

This is the command to use to build the container for your app.

Lab Test appends this command to a script that sets the following variables: $APP_NAME, $INSTANCE_NAME, $BRANCH_NAME, and $RELEASE.

If you override the docker build command, you must still tag it with $APP/$INSTANCE or the remaining commands will fail.

Note

If your Dockerfile doesn’t use the default --build-args passed, they are ignored.

`container_provider`¶

Default:	`local`
Required:	`False`
Acceptable values:	`local` or `aws`

This is to extend how Lab Test can talk to different Docker container repositories. Currently only local and aws are supported.

`docker_image_pattern`¶

Default:	`%(APP_NAME)s/%(INSTANCE_NAME)s:latest`
Required:	`False`
Acceptable values:	String with placeholders

The string pattern to use when dynamically determining which image to use to build the container. Allows Python string interpolation formatting, with APP_NAME and INSTANCE_NAME in the context.

The value of this option depends on how your Docker images are built. (See docker pull documentation for more information about specifying images) If they are built using the built-in Lab Test method (the default), then the images will be local to the test server and can use a simple name. If the Docker images are built using an external process and in a private repo, the name will look like a URL, without the https://.

`environment`¶

Default:	`[]`
Required:	`False`
Acceptable values:	A sequence of strings

A list of environment variable strings to include in the Docker container.

Example in YAML¶

labtest:
  environment:
    - FOO=bar
    - TEST=true
    - DEBUG=true

Example in JSON¶

{
  "labtest": {
    "environment": [
      "FOO=bar",
      "TEST=true",
      "DEBUG=true"
    ]
  }
}

Example in INI¶

[labtest]
environment = FOO=bar,TEST=true,DEBUG=true

`host_name_pattern`¶

Default:	`%(APP_NAME)s-%(INSTANCE_NAME)s`
Required:	`False`
Acceptable values:	String with placeholders suitable for a URL

The pattern to use to generate the host part of the DNS address. This is used with test_domain to generate the virtual host name.

This pattern may contain Python string interpolation formatting. The context passed to this includes:

APP_NAME
INSTANCE_NAME
BRANCH_NAME

`use_ssh_config`¶

Default:	`False`
Required:	`False`
Acceptable values:	`True` or `False`

Use your local SSH config when connecting. For example, if you set this option to True and add these items (changing the various User and Hostname values) to your ~/.ssh/config:

Host bastion
Hostname 111.222.111.222
Port 22
User monty.python.at.boston.gov
IdentityFile ~/.ssh/id_rsa

Host test
Hostname 10.20.10.5
User monty.python.at.boston.gov
Port 22
ProxyCommand ssh -A -T bastion nc %h %p
IdentityFile ~/.ssh/id_rsa

You can now set the host configuration to test and it will route everything through the SSH bastion in the test environment. You can even ssh test from the command line.