Server Configuration¶

Initial Setup¶

When the server first comes up, browsing to it will take you to an initial setup screen. The screen will prompt you for the following details:

Admin email/password: This will specify the local admin account

used to manage Backslash
Default Email Domain: For users logging in with their user names, expecting the email domain to be automatically added upon authentication, you can set this optional field to be your organization domain.
Enable Google OAuth2: Once checked, you will be able to enter the client ID and client secret as obtained from the Google Credentials console, enabling users to log in via the Google federated login mechanism
Enable LDAP: If checked, will ask for LDAP URI and base DN, enabling you to log in users via your organization’s LDAP service.

Optional Configuration¶

Backslash uses an internal Docker volume for storing configuration files, some of which enable specific behaviors at runtime.

In order to customize these files, you’ll have to do the following on a new instance of Backslash:

In the Docker compose file, change the locations referring to the conf volume, and set them to point at where you want to store the config files. For example, change conf:/conf to /my/backslash/config/files:/conf. This needs to be done in several places in the configuration file
Start Backslash. You’ll see files created in that directory, especially a file named 000-private.yml. You can now add YAML files to this directory, and they will be read and loaded when the server starts.

Note

The configuration directory is secret and should not be shared or opened for access by anyone except for administrators.

Create a file which will be used for your specific settings, e.g. 001-deployment.yml – we will use this file to specify more options.

HTTPS¶

Backslash supports serving via HTTPS, in which case it prefers secure connections over insecure ones.

To activate SSL, set the BACKSLASH_HOSTNAME environment variable in your compose file, set BACKSLASH_USE_SSL to yes, and place your certificate and key file in your config directory, under the names certificate.crt and server.key respectively.

Display Names¶

By default, Backslash calls test subjects “Subjects” and related entities “Related”. If you want to change these names when displayed, you can do this via the display_names config in your 001-deployment.yml mentioned above:

...
display_names:
  subject: microwave
  related: plate

This will make subjects be called “microwaves” in all relevant contexts, and related entities be called “plates”.

Metadata Links¶

In some cases you may have test metadata items which are actually links/URIs pointing at external resources. This could be Jenkins builds, logs collected, or any other external resource related to the test. If you want to allow quick access to those items from the test page, you can specify it via the test_metadata_links variable:

...
test_metadata_links:
   - name: Jenkins build
     key: jenkins_url
     icon: http://url/for/jenkins/icon.png

The above will add a link to the test page pointing at the Jenkins build whenever a “jenkins_url” metadata key is found for a test

Metadata Details¶

Similar to metadata links, you can choose specific metadata keys to be displayed as informational values for tests and/or sessionsL:

...
test_metadata_display_items:
   - key: my_metadata_key
     name: My Metadata Key

Or:

...
session_metadata_display_items:
   - key: my_metadata_key
     name: My Metadata Key

Deployment Customization¶

Auxiliary Services¶

In some extreme cases you might want specific APIs or routes served by external containers running customized code. This can be done through customizing the docker-compose configuration.

First, create an empty docker-compose file acting as your override (we will be using it as an additional -f argument to docker-compose):

# compose-override.yml
version: '3'

Now, create your custom container running your own extension, e.g. a customized Flask app serving /api/your_custom_api:

# compose-override.yml
version: '3'
services:
  my_custom_service:
     image: your-server/image-name
     command: "your-command-here"

Now we can use the BACKSLASH_ADDITIONAL_ROUTES environment variable to the nginx container to make it forward your new API to your custom container:

# compose-override.yml
version: '3'
services:
   ...
   nginx:
     environment:
     - "BACKSLASH_ADDITIONAL_ROUTES=/api/your_custom_api:http://my_custom_service:8000"

Data Replication¶

ElasticSearch¶

Backslash supports replicating data to ElasticSearch. To configure it, click “Replication” under the “Admin menu”. This functionality is only accessible to admin users.