Docker Compose

Deployment of Allure TestOps using docker-compose

With docker-compose you can easily configure, install, and upgrade your Docker based Allure TestOps installation.

It’s a good option for a trial period or a small team with not big amount of tests running.

For production deployments, we strongly recommend using the detailed installation instructions utilising external PostgreSQL, RabbitMQ, and object storage services.

This section covers following information:

Prerequisites

  1. You need to obtain security token to login to hub.docker.com. from our sales team .
  2. You need to obtain the license key. Please contact our sales team to get the license key.
  3. You need to have docker and docker-compose installed on your target machine.

Configuration

Starting from Allure TestOps release 3.181.5 licensing information is stored in the uaa database, you don’t need to provide license into configuration files.

Configuration file .env contains required settings for the deployment with docker-compose:

VERSION=<check release notes>     # application version e.g. 3.177.1
SERVER_PORT=8080                  # application port
ADMIN_USERNAME=admin              # admin username
ADMIN_PASSWORD=admin              # admin password
REGISTRATION_AUTOAPPROVE=false    # allow/forbif users registration in active state
JWT_SECRET=secret-text            # JWT secret text
<snip>

Super user (admin) log-in information

Allure TestOps requires a super user account to be created and kept in the system. This super user’s name and password are defined in the configuration file (see admin above) and it will be restored to the state described in the configuration to ensure you won’t lose the access to your Allure TestOps instance, this means if you disable this user in the UI, remove their roles and change the password, during the next start of Allure TestOps, it will recreate the user again with all set of available rights, with the password defined in the configuration file.

Please consider changing the admin’s password in the configuration before the deployment or remove it to have a new password each time system restarts.

If you omit provisioning of initial admin’s password, then default user admin will be created and admin’s strong password will be generated by the system, and then the generated password will be sent to the logs of uaa service.

Each time Allure TestOps is restarted, the super user account is restored to its initial state.

jwtSecret is a random string, you can generate it by using this command:

openssl rand -base64 16

Installation

Login to docker hub

Do not use Docker desktop application for the log-in. It won’t work.

On a machine where you are going to deploy Allure TestOps log in to the Docker registry: using username - qametaaccess.

This is to be done in via command line of a terminal application as follows:

$ docker login --username qametaaccess

then docker will request you to provide the password. Please use the security token you’ve received from our sales team - refer to the item 1 in prerequisites.

Download docker-compose files

Download and unpack allure-testops.zip with following files:

+ allure-testops
  - .env             # configuration
  - docker-compose.yml   # docker compose file

Update docker-compose files

  1. Check our release notes and update VERSION line of .env file.
  2. Update JWT_SECRET line with the output of the following command: openssl rand -base64 16

Start Allure TestOps

Once you have all of your configuration options completed, you can get all dependencies and run configuration with docker-compose:

docker-compose pull       # will download all necessary images
docker-compose up -d      # will start the configuration

Initialization usually takes up to 5 minutes. You can check system’s readiness by executing the following command in the terminal

docker-compose logs | grep "Application 'allure-ee-"

if you see the following output, i.e. all three lines, then the application is ready and you can log-in to the URL you’ve selected for the deployment with default admin user and password defined in the configuration files.

report_1     |  Application 'allure-ee-report' is running! Access URLs:
gateway_1    |  Application 'allure-ee-gateway' is running! Access URLs:
uaa_1        |  Application 'allure-ee-uaa' is running! Access URLs:

Accessing Web interface

Allure TestOps web UI is available at <http://<%your-hostname-here%>:port

Port is defined in the configuration files.

Initial login

Log in to Allure TestOps using username and password from your configuration file.

Provide the license for your Allure TestOps instance

Next thing you see will be the modal window to which you will need to provide the license you acquired.

if you see this write to support.qameta.io

After the correct license is provided, you’ll be able to start your work.

If you aren’t able to log-in more than 10 minutes after the up -d command, please check the troubleshooting section for logs generation and create a support ticket with the logs.

Update

If your release of Allure TestOps is lower than 3.177.2, please refer to special update procedure to 3.177.2 and next ones.

Once your Allure TestOps started, configuration changes and images updates should be done using the following set of commands:

Update version in the file .env then run the commands:

docker-compose pull
docker-compose down

Wait until all the services have stopped and run Allure TestOps via docker-compose:

docker-compose up -d

Troubleshooting

Showing all logs

docker-compose logs -f --tail=20

Logs of specific component

docker-compose logs -f --tail=20 uaa
docker-compose logs -f --tail=20 report
docker-compose logs -f --tail=20 gateway

Service status

Show service status in consul (replace 127.0.0.1 by your consul IP address):

curl  http://127.0.0.1:8500/v1/health/service/allure-ee-gateway?ns=default
curl  http://127.0.0.1:8500/v1/health/service/allure-ee-uaa?ns=default
curl  http://127.0.0.1:8500/v1/health/service/allure-ee-report?ns=default

Uninstall

To uninstall the Allure TestOps, run the following:

docker-compose down -v --rmi local

Using alternative infrastructure

This section is for you if you’re going to use resources from your existing infrastructure like

  • Standalone database (outside of a container)
  • Consul service
  • RabbitMQ service
  • Redis

All the settings to connect external service are made in the docker-compose.yml file

Docker-compose.yml file settings structure

Generally the structure of the settings to run applications via docker-compose looks like follows:

services:    
    <service-name>: # Name of the service in this area
        ...
        environment:
				# data about the environement to be passed to the service <service-name>

All the settings are transferred to Allure TestOps services as the environment data, so they need to be placed to the environment section of a service:

services:
    <service-name>: # Name of the service in this area
        ...
        environment:
            VAR1: "var1_value"
            VAR2: "var2_value"

Next sections will describe the settings for the integration with certain services like database, RabbitMQ, Redis and S3 storage.

Mandatory Allure TestOps services

The mandatory Allure TestOps services must always remain in docker-compose.yml, these are the following:

  • uaa
  • report
  • gateway

Connecting external standalone database for uaa and report

Standalone database is highly recommended for production environment as the performance of database running inside a container is very limited and will become a bottle neck with the growth of your test cases quantity.

Connecting the external database contains following steps:

  1. Creating the databases for services uaa and report using recommended Postgres DB.
  2. Migration of data from existing database to the standalone one. This step is to be skipped if you’re deploying Allure TestOps from scratch.
  3. Updating the settings to connect uaa and report services to stand alone database.

Creating the databases

Using your Postgres DBE you need to create 2 databases - for the services 1. uaa and 2. report.

  1. The uaa database stores all the data related to the users’ profiles and licensing.
  2. The report database stores tests’ data.
Creating uaa database

Following script will create empty database and during the first start uaa service will execute a series of SQL update scripts to create actual database structure.

CREATE DATABASE uaa TEMPLATE template0 ENCODING 'utf8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';
CREATE USER uaa with encrypted password '[email protected]';
GRANT ALL PRIVILEGES ON database uaa to uaa;

Creating report database

Following script will create empty database and during the first start report service will execute a series of SQL update scripts to create actual database structure.

CREATE DATABASE report TEMPLATE template0 ENCODING 'utf8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';
CREATE USER report with encrypted password '[email protected]';
GRANT ALL PRIVILEGES ON database report to report;

Migration from the DB in a container to standalone DB

The migration of the existing data to the standalone database is described in FaQ section.

You need to create a dump from uaa and report databases and then restore the database dumps to appropriate database. The date restoration to a wrong database will ultimately corrupt the data as the databases of uaa and report services have different scripts to get these to the actual database structure.

Updating the settings of services

You need to configure following variables to connect uaa and report services to their databases:

  • SPRING_DATASOURCE_URL - URL of the DBE serving your database
  • SPRING_DATASOURCE_USERNAME - username to connect to a database
  • SPRING_DATASOURCE_PASSWORD - password to connect to a database
SPRING_DATASOURCE_URL

SPRING_DATASOURCE_URL is the URL of your database engine to which you might want to connect your uaa and report services.

SPRING_DATASOURCE_URL has the following format:

#for uaa service
jdbc:postgresql://<database_url>:5432/uaa
#for report service
jdbc:postgresql://<database_url>:5432/report

where

  • <database_url> is the URL address of your external database engine to which your report or uaa service are to connect
  • uaa is the name of the database to which your uaa service needs to be connected
  • report is the name of the database to which your report service needs to be connected
  • 5432 is the port used by the application (DBE), it can be different, but the one used in the example is the default one. Consult with your DBA.

Alternatively, you can use .env file to keep all the variables values in one place and then refer to these variables in the settings.

# this is content of .env file
# report database
REPORT_POSTGRES_URL=jdbc:postgresql://<database_url>:5432/report # update with new connection details
REPORT_POSTGRES_USERNAME=report # keep as it is
REPORT_POSTGRES_PASSWORD=[email protected] # update if you created new password

then in the docker-compose.yml file the settings for report service database will look like follows:

  report:
    image: allure/allure-report:${VERSION} # this comes from .env
    environment:
      ALLURE_ENDPOINT: ${ENDPOINT} # this comes from .env
      # database
      SPRING_DATASOURCE_URL: ${REPORT_POSTGRES_URL} # this comes from .env
      SPRING_DATASOURCE_USERNAME: ${REPORT_POSTGRES_USERNAME} # this comes from .env
      SPRING_DATASOURCE_PASSWORD: ${REPORT_POSTGRES_PASSWORD} # this comes from .env

External S3 storage for artifacts

S3 storage type is more reliable in terms of processing of the collisions when saving and deleting the data during the batch operations with files so it is recommended at least using min.io instead of the direct usage of a file system storages.

If you are going to connect S3 storage for the test cases and test results artifacts (which is recommended for the production) you need to add the following parameters to report service:

  • ALLURE_BLOBSTORAGE_TYPE - should be S3 for S3 bucket or for min.io
  • ALLURE_BLOBSTORAGE_S3_ENDPOINT - the URL of your S3 management endpoint
  • ALLURE_BLOBSTORAGE_S3_BUCKET - name of your S3 bucket
  • ALLURE_BLOBSTORAGE_S3_REGION - the region of S3 bucket (see the S3 details during the creation)
  • ALLURE_BLOBSTORAGE_S3_ACCESSKEY - the access key ID created to access the S3 bucket
  • ALLURE_BLOBSTORAGE_S3_SECRETKEY - the secret key linked to the access key
  • ALLURE_BLOBSTORAGE_S3_PATHSTYLEACCESS - parameter setting the link styles, should be true

Starting from the release 3.179.2 Allure TestOps uses min.io service to handle the test cases’ and test results’ artifacts; this service works as S3 storage. Here is an example on how you make the settings for S3 in case of min.io is used.

  report:
    <snip>
    environment:
      # storage
      ALLURE_BLOBSTORAGE_TYPE: "S3"
      ALLURE_BLOBSTORAGE_S3_ENDPOINT: "http://report-s3:9000"
      ALLURE_BLOBSTORAGE_S3_BUCKET: "allure-report"
      ALLURE_BLOBSTORAGE_S3_REGION: "us-east-1"
      ALLURE_BLOBSTORAGE_S3_ACCESSKEY: "allure-access-key"
      ALLURE_BLOBSTORAGE_S3_SECRETKEY: "allure-secret-key"
      ALLURE_BLOBSTORAGE_S3_PATHSTYLEACCESS: "true"

Connecting S3 storage

The integration with external storage is being performed using the environment variables.

If you’re using the deployment via container the connection to S3 storage is being performed by adding of environment variables to report container as follows:

For AWS’ S3


      ALLURE_BLOBSTORAGE_TYPE: "S3"
      ALLURE_BLOBSTORAGE_S3_ENDPOINT: "s3.amazonaws.com" # leave as it is here
      ALLURE_BLOBSTORAGE_S3_REGION: "us-east-1" # region, update to real region you are using
      ALLURE_BLOBSTORAGE_S3_BUCKET: "<your-bucket-name>" # replace string in <> with your bucket's name 
      ALLURE_BLOBSTORAGE_S3_ACCESSKEY: "<ACCESS-KEY>" # replace string in <> with your Access key ID 
      ALLURE_BLOBSTORAGE_S3_SECRETKEY: "<SecretKey>" # replace string in <> with your Secret access key 
      ALLURE_BLOBSTORAGE_S3_PATHSTYLEACCESS: "true"

Access rights settings for S3 bucket

For the S3 integration to work smoothly with Allure TestOps following access rights to be configured for S3 bucket.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "S3assets",
            "Effect": "Allow",
            "Action": [
                "s3:PutObjectAcl",
                "s3:PutObject",
                "s3:ListMultipartUploadParts",
                "s3:ListBucketMultipartUploads",
                "s3:ListBucket",
                "s3:GetObjectAcl",
                "s3:GetObject",
                "s3:GetBucketLocation",
                "s3:GetBucketAcl",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::<ALLURE_S3_BUCKET_NAME>/*",
                "arn:aws:s3:::<ALLURE_S3_BUCKET_NAME>"]
        }
    ]
}

For Google’s S3


      ALLURE_BLOBSTORAGE_TYPE: "S3"
      ALLURE_BLOBSTORAGE_S3_ENDPOINT: "https://storage.googleapis.com" # leave as it is here
      ALLURE_BLOBSTORAGE_S3_REGION: "europe-west3" # region, update accordingly your real region
      ALLURE_BLOBSTORAGE_S3_BUCKET: "<your-bucket-name>" # replace string in <> with your bucket's name 
      ALLURE_BLOBSTORAGE_S3_ACCESSKEY: "<ACCESS-KEY>" # replace string in <> with your Access key ID 
      ALLURE_BLOBSTORAGE_S3_SECRETKEY: "<SecretKey>" # replace string in <> with your Secret access key 
      ALLURE_BLOBSTORAGE_S3_PATHSTYLEACCESS: "true"

For Google S3 you need to use fine-granted access control and settings for public access Subject to object ACLs, this is needed for interoperability with AWS SDK, otherwise files in S3 bucket won’t be fully accessible by Allure TestOps and report service will fail to start.

If you have any doubts, please consult our Support

Connecting external Redis service

Connecting the external redis installed in your infrastructure require the setting of the following variables for Redis service in the environment section of the gateway service.

  • SPRING_SESSION_STORE_TYPE: REDIS should be always included in the configuration as Redis is to be used in any case.

  • SPRING_REDIS_HOST - is the URL for Redis host

  • SPRING_REDIS_PORT - is the port of Redis application

  • SPRING_REDIS_SSL - the mark if SSL to be used.

  • SPRING_REDIS_PASSWORD - password to use when connecting to redis.

  • ALLURE_REDIS_NAMESPACE - reference to the Redis’ namespace designated to Allure TestOps.

Connecting external RabbitMQ service

Connecting the external RabbitMQ installed in your infrastructure require the setting of the following variables for RabbitMQ service in the environment section of the report service.

  • SPRING_RABBITMQ_HOST - the URL of the host where RabbitMQ application is running
  • SPRING_RABBITMQ_PORT - port of RabbitMQ application
  • SPRING_RABBITMQ_USERNAME - the username set to use with Allure TestOps
  • SPRING_RABBITMQ_PASSWORD - the password set to use with Allure TestOps
  • SPRING_RABBITMQ_SSL_ENABLED - mark if SSL to be used
  • SPRING_RABBITMQ_VIRTUAL_HOST - the virtual host reference created for the usage with Allure TestOps

Connecting external consul service

Connecting the external consul installed in your infrastructure requires the setting of the following variables for consul service in the environment section each Allure TestOps service (report, uaa, gateway).

  • SPRING_CLOUD_CONSUL_HOST is the URL address of Consul application
  • SPRING_CLOUD_CONSUL_PORT is the non-default port assigned to Consul application. You can omit the parameter if the default port is used.

Preparation for the production deployment

Before putting your system to the production, please refer to the recommendations here.

If you have any doubts, please consult our Support

Back to installation