Starting a QA-Board server

QA-Board's run-wrapper, qa, will sync with a central server that tracks and displays results.

Need a hosted version?

We're considering offering a hosted solution to help you get started. If you are interested, contact the maintainers.

Until then, please fill issues, chat or send an email to maintainers if you run into issues starting a server. We're responsive.

Create a directory to store results

QA-Board expects that all clients can access a shared storage to save and read results.

To get started quickly on a single server, create a local folder. Worry about sharing it later:

mkdir -p /mnt/qabaord
chmod -R 777 /mnt/qabaord

tip

If you want to use a different folder, find-and-replace /mnt/qaboard with your path in docker-compose.yml and services/nginx/conf.d/qaboard.conf.

Shared Storage?

Later, read how to setup NFS or Samba. If you need fine-tuning read about options for NFS volumes in docker-compose.yml.

Working in the cloud?

Use file-base storage like AWS EFS or GCP Filestore.

We plan on supporting blob-stores like AWS S3. Contact us or create an issue if it would help.

Starting the server

1. You need Linux, docker, docker-compose and git.
2. To start the QA-Board server:

git clone https://github.com/Samsung/qaboard.git
cd qaboard

docker-compose pull
docker-compose up -d
#=> the application is live at localhost:5151

# if you can't access the application, check the port is not blocked by a firewall
# cloud services often require you to add the ports you need to an allow-list.

To have the server restart automatically:

docker-compose -f docker-compose.yml -f production.yml up -d

note

Want to install from a Kubernetes helm chart, CloudFormation or Terraform plans? Get in touch.

(Optional) Environment variables

To configure your installation, you can either edit an .env file or services.backend.environment in one of the docker-compose files (docker-compose.yml, development.yml, production.yml...).

ENV Variable	Default	Usage
GITLAB_ACCESS_TOKEN	none	Optional for some extra features. Get it with a read_repository scope at https://$gitlab-server/profile/personal_access_tokens
GITLAB_HOST	none	e.g. https://gitlab.com or http://my-gitlab-srv/
QABOARD_PORT_HTTP	5151	Port mapped to the app on the host
QABOARD_DB_HOST	db	Connect the backend to a non-default database host (e.g. instead of dev'ing with prod dumps, connect directly to it)
QABOARD_DB_PORT	5432	Connect to a non-default database port
JENKINS_AUTH	none	Credentials used to trigger jenkins jobs on 1 or many jenkins servers. The format is a JSON string looking like {"hostname_1": {"user": "jenkinsuser", "token": "xxxxx", "crumb": "yyy"}} ([how-to-get-the-token-crumb?](/docs/triggering-
third-party-tools#example-jenkins-integration-via-webhooks))
QABOARD_LDAP_ENABLED	none	If set to true LDAP is enabled
QABOARD_LDAP_HOST	none	Server hostname (including port)
QABOARD_LDAP_PORT	389	Server port, usually 389 (or 636 if SSL is used / not supported yet!).
QABOARD_LDAP_USER_BASE	none	Search base for users.
QABOARD_LDAP_BIND_DN	none	The Distinguished Name to bind as, this user will be used to lookup information about other users.
QABOARD_LDAP_PASSWORD	none	The password to bind with for the lookup user.
QABOARD_LDAP_USER_FILTER	none	User lookup filter, the placeholder {login} will be replaced by the user supplied login. (e.g. `(&(objectClass=inetOrgPerson)(
QABOARD_LDAP_ATTRIBUTE_EMAIL	mail
QABOARD_LDAP_ATTRIBUTE_COMMON_NAME	cn
CANTALOUPE_MEM_START	1g	Starting memory for the image server
CANTALOUPE_MEM_MAX	2g	Max memory for the image server
UWSGI_PROCESSS	1	default: 1g
UWSGI_UID_CAN_SUDO	none	if set, the uwsgi user can sudo

note

In the future we plan to introduce a proper "secret" store, per user and per project.

Consult the Troubleshooting page for examples that show how to get logs from the various services composing QA-Board.

For development, consult the READMEs for the backend and the frontend.

(Optional) For "production"

Backups

In production.yml you can uncomment the cron-backup-db service to enable daily backups, and replace /WHERE/TO/SAVE/BACKUPS with a (backup'ed!)location on the host.

Using SSL / hosting behind a reverse proxy

What we do is directly change the nginx confix:

services/nginx/conf.d/qaboard.conf

server {
  # ...
  listen 443 ssl;
  ssl_certificate_key /ssl/cert.key;
  ssl_certificate /ssl/cert.pem;
  # ...
}

And mount keys with:

docker-compose.yml

proxy:
  volumes:
  - "somewhere/cert.key:/ssl/cert.key"
  - "somewhere/cert.pem:/ssl/cert.pem"

If you want to use your own reverse proxy, with nginx for instance you can set QABOARD_PORT_HTTP=8080 and:

server {
  listen 80;
  server_name default_server;
  location / {
    proxy_pass http://localhost:8080/;
  }
}

(Optional) Cleanup

We run those cron jobs:

# Weekly cleanup of old results
# https://samsung.github.io/qaboard/docs/deleting-old-data
59 1 1 * * cd qaboard && docker-compose exec -T backend qaboard_clean
# https://github.com/docker/compose/issues/3352

# Weekly removal of old docker images, helps to avoid filling the disk on the host
59 1 2 * * docker image prune --force

# Restart the image server, somehow after a while they need it (need research...)
0 4 * * * cd qaboard && docker-compose -f docker-compose.yml -f production.yml stop cantaloupe && docker-compose -f docker-compose.yml -f production.yml rm -v cantaloupe && docker-compose -f docker-compose.yml -f production.yml up -d cantaloupe

tip

Check qaboard_clean --help to implement complex cleanup strategies.