TestOps logo
Try TestOps

Install Allure TestOps via Docker Compose

This section describes how to install and run Allure TestOps version 5 using Docker compose configuration managed by Qameta Software.

For reference, we kept the outdated installation manual for version 4.

The easiest way to run Allure TestOps is to use Docker Compose.

While not recommended for high-load use cases, this method is great for evaluating Allure TestOps or even deploying it for a small project with manual testing or with automated tests up to 3 000 test results per launch or 30 000 test results per day.

Migration from version 4

Allure TestOps version 5 cannot be deployed above the version 4. The upgrade process requires the data migration and switching to the new configuration.

The upgrade is possible only from the release 4.26.5. Using older releases for the upgrade process will brick the system and will lead to the data loss.

The upgrade to version 5 requires the following steps:

  1. Create the new .env file for the newly developed Compose configurations based on your current configuration.
  2. Stop the existing instance.
  3. Merge the information from the UAA service database to the report service database.
  4. Start the deployment using the new Compose configuration.

For more detailed information on upgrading your version of Allure TestOps to 5.x, follow the migration guide.

Preparation steps

  1. Install Docker on the machine where you will run Allure TestOps.

    See the installation guide on the Docker website.

  2. Install the Docker Compose V2 plugin.

    See the installation guide on the Docker website.

    To check if Docker Compose V2 is installed, run the command in a terminal:

    docker compose version

  3. Deploy additional services required for Allure TestOps to start:

    For performance reasons and for ease of maintenance, it is strongly recommended to deploy all these services separately, not on the same machine where you will run Allure TestOps. See Storage requirements for more details.

    Installation without dedicated external services is also possible, as demonstrated in the testops-demo configuration template.

    The demo option is intended for evaluation purposes only and is not supported for production deployment. Maintaining and upgrading such a configuration can involve considerable downtimes or data loss if performed by non-skilled personnel. We won't be able to assist with the troubleshooting and service restoration.

  4. Get a license for Allure TestOps.

    To receive the license key, fill out the form for a trial version or contact us at [email protected] for a commercial license.

    When you receive the license key, you will also get username and password for accessing Qameta's images repository.

  5. Get detailed information about configuring authentication within your organization.

    The data required for configuration depends on the authentication method you choose. Possible options:

    • Standard authentication by a username and a password, implemented by Allure TestOps itself.

      This option uses an SMTP server to send invitations to new users and does not require additional services.

    • Authentication via a third-party identity provider.

      The details required for this may vary depending on what type of identity provider you use. Usually, you will need to specify an external URL and a secret token generated by the identity provider.

    See Configuration → Authentication for more details.

Downloading and editing configuration files

  1. Download the configuration files:

    • When working on a Unix-like machine, use either wget or curl to download the configuration files:
    wget https://dl.qameta.io/artifactory/bin/docker-compose/testops-docker-compose.zip -O testops-compose.zip && unzip testops-compose.zip -d "testops"
    • Alternatively, open this page and download the ZIP archive with all available templates manually.

  2. Open the config depending on the type of authentication you want to use:

    • testops — for classic password-based authentication;
    • testops-ldap — for authentication via an LDAP server;
    • testops-saml — for authentication via SAML2 identity provider (Keycloak, GitLab, Azure AD, Okta);
    • testops-openid — for authentication via OpenID Connect (Keycloak, GitLab, Azure AD, Okta).

    The testops-demo directory contains a demo version of Allure TestOps. It is not suitable for a production environment.

  3. Move the docker-compose.yml and env-example files into an empty directory.

  4. Rename the env-example file to .env.

    You will need two files to run Allure TestOps:

    • docker-compose.yml (provided by Qameta Software, must not be edited) — the definition of the compose deployment architecture;
    • .env (must be edited to suit your needs) — the environment variables that will be used by Docker Compose when running the deployment.

    The contents of the files is different for different types of authentication you want to use for your Allure TestOps instance, though the workflow is the same regardless.

  5. Open the .env file in a text editor. For a typical configuration, follow these steps:

    1. Specify the Allure TestOps version.
    2. Provide the correct image registry and repository information.
    3. Set the Allure TestOps URL.
    4. Set security parameters.
    5. Set the email address for the first admin.
    6. Configure authentication.
    7. Set up storage services.

Choose Allure TestOps version

In the RELEASE_TO_DEPLOY parameter, specify the version of Allure TestOps you want to use. For example:

RELEASE_TO_DEPLOY=5.10.2

These installation instructions are relevant for any version starting with TestOps 5.4.0, but we recommend to use the latest version available. Check out the Release notes section for the list of available versions.

Registry and repository

To pull images from the images registry you need to define parameters as follows:

IMAGES_REGISTRY=docker.io
IMAGES_REPO=allure

Set Allure TestOps URL

Specify the parameters that describe how the users will access Allure TestOps: TESTOPS_PROTO, TESTOPS_INSTANCE_URL and TESTOPS_INSTANCE_PORT.

The example below assumes that the Allure TestOps instance would be available at “http://testops.example.com/” (using port 80, which is the default port for HTTP). It is important for the parameters to match the actual URL, otherwise Allure TestOps will pass broken links to external tools like CI servers.

TESTOPS_INSTANCE_URL=testops.example.com
TESTOPS_INSTANCE_PORT=80
TESTOPS_PROTO=http

To make Allure TestOps available via HTTPS, you need to configure a reverse proxy. See Network configuration for more details.

If you plan to integrate Allure TestOps with Jira, you need to use HTTPS and enable secure cookies, otherwise the integration will not work correctly. See Integration with Jira Data Center and Integration with Jira Software Cloud for more details.

TESTOPS_SECURE_COOKIE=true

Set security parameters

Encryption key

As a security measure, Allure TestOps encrypts all sensitive values in the database using the AES-256 algorithm. This way, if a malicious actor gets access to the PostgreSQL database but not to the configuration file, this will not compromise the credentials of the services used by the Allure TestOps instance.

To set the encryption key, create a passphrase and update the value of the TESTOPS_CRYPTO_PASSWORD parameter. We recommend storing the passphrase in a safe place so it can be recovered if needed.

TESTOPS_CRYPTO_PASSWORD=MolehillQuiverLatterSturdily

If you forget the TESTOPS_CRYPTO_PASSWORD value or change it after the initial deployment, all previously configured integrations will stop working. In this case, you will need to go to the settings of each project and re-enter valid credentials.

JWT secret

Allure TestOps uses the JSON Web Token standard for authenticating and authorizing requests. As part of the standard, you need to provide a secret that will be used to create JWT signatures.

To set the secret, update the value of the TESTOPS_JWT_SECRET parameter. The recommended length is between 8 and 16 characters. The longer the secret is, the more CPU resources will be required.

You can change the value over time, it won't affect the users.

TESTOPS_JWT_SECRET=123456789ABCDEF

Set first admin email

Allure TestOps uses SMTP credentials to send an invitation email to the first administrator. Regardless of the main authentication method, the first administrator must accept the invitation sent to their email. Only after that will they be able to create an account and activate the license for the Allure TestOps instance.

Starting from version 5.4.0, these settings are required when deploying a new Allure TestOps instance. Starting with version 5.6.0, the first launch of Allure TestOps is not possible without using a configured SMTP server.

To configure SMTP:

  1. In the FIRST_ADMIN_EMAIL parameter, specify the email address of the first administrator.

    Example:

    [email protected]

  2. Configure SMTP credentials according to the instruction.

Configure authentication

A necessary step when deploying Allure TestOps is to configure how users (other than the very first administrator) will be registered and logged in. See Configuration → Authentication for more details.

Below are some configuration examples for various identity providers.

When using built-in authentication feature, the end users will be invited to the system by the administrators and create their accounts by following links from the email messages. Then authentication of the users will be performed using the username and password created by the end users.


LDAP_URL="ldaps://ldaps.space:636"
LDAP_LOGIN_SA="cn=admin,dc=space"
LDAP_LOGIN_SA_PASS=SeriviceAccountPassword_Here
LDAP_DEFAULT_ROLE=ROLE_GUEST
LDAP_USER_SEARCH_BASE="ou=People,dc=space"
LDAP_USER_SEARCH_FILTER="uid={0}"
LDAP_UID_ATTRIBUTE=uid
LDAP_SYNC_ROLES=false
LDAP_GROUP_ROLE_ATTRIBUTE=cn
LDAP_GROUP_SEARCH_BASE="ou=group,dc=space"
LDAP_GROUP_SEARCH_FILTER="memberUid={1}"
LDAP_MAPPING_ROLE_USERS=atousers,every_user_is_user
LDAP_MAPPING_ROLE_ADMINS=atoadmins,every_user_is_admin

ALLURE_LOGIN_PRIMARY=saml

# ...

LOGIN_SAML2_ENABLED=true
REGISTRATION_DEFAULT_ROLE=ROLE_GUEST
LOGIN_SAML2_ID=KeyCloak
LOGIN_SAML2_ACS_URL=https://<your-domain>/api/login/saml2/sso/{registrationId}
LOGIN_SAML2_ENTITY_ID=https://<testops>/api/login/saml2/authenticate/{registrationId}
LOGIN_SAML2_METADATA_URL=https://path/to/metadata.xml
LOGIN_SAML2_FIRSTNAMEATTRIBUTE=firstNameAttribute
LOGIN_SAML2_LASTNAMEATTRIBUTE=lastNameAttribute
LOGIN_SAML2_EMAILATTRIBUTE=emailAttribute
LOGIN_SAML2_SYNCROLES=false
LOGIN_SAML2_GROUPROLEATTRIBUTE=groupRoleAttribute
LOGIN_SAML2_GROUPAUTHORITIES_ROLEUSERGROUPS=roleUserGroups
LOGIN_SAML2_GROUPAUTHORITIES_ROLEADMINGROUPS=roleAdminGroups

For the server version of Allure TestOps, authentication using OpenID is available starting with version 5.6.4.

TESTOPS_OPENID_CLIENTNAME=TestOps
TESTOPS_OPENID_CLIENTID=<YOUR_CLIENT_ID>
TESTOPS_OPENID_CLIENTSECRET=<YOUR_CLIENT_SECRET_HERE>
TESTOPS_OPENID_REDIRECTURI=https://<your-domain>/login/oauth2/code/openid
TESTOPS_OPENID_SCOPE=openid,email,profile
TESTOPS_OPENID_AUTHORIZATIONURI=http://<open_id_provider_url>/realms/<you_realm>/protocol/openid-connect/auth
TESTOPS_OPENID_USERINFOURI=http://<open_id_provider_url>/realms/<you_realm>/protocol/openid-connect/userinfo
TESTOPS_OPENID_ISSUERURI=http://<open_id_provider_url>/realms/<you_realm>
TESTOPS_OPENID_USERNAMEATTRIBUTE=preferred_username

TESTOPS_OPENID_DEFAULTROLE=ROLE_GUEST

TESTOPS_OPENID_SYNCROLES=false
TESTOPS_OPENID_GROUPROLEATTRIBUTE=group
TESTOPS_OPENID_GROUPAUTHORITIES_ROLEUSERGROUPS=roleUserGroups
TESTOPS_OPENID_GROUPAUTHORITIES_ROLEADMINGROUPS=roleAdminGroups

Configure storage services

Specify the details for connecting to the storage services required for Allure TestOps.

  • Connection to the Redis storage service

    • REDIS_HOST — server hostname.
    • REDIS_PORT — server port.
    • REDIS_PASS — password for connecting to the storage.

  • Connection to the PostgreSQL database for application data

    • TESTOPS_DB_HOST — database service hostname.
    • TESTOPS_DB_PORT — database service port.
    • TESTOPS_DB_NAME — database name.
    • TESTOPS_DB_USERNAME — username for connecting to the database.
    • TESTOPS_DB_PASS — password for connecting to the database.

  • Connection to the RabbitMQ service

    • RABBIT_HOST — service hostname.
    • RABBIT_PORT — service port.
    • RABBIT_USER — username for connecting to the message queue.
    • RABBIT_PASS — password for connecting to the message queue.

  • Connection to the S3-compatible storage service

    • TESTOPS_S3_URL — service URL.
    • TESTOPS_S3_BUCKET — S3 bucket name.
    • TESTOPS_S3_REGION — S3 region name.
    • TESTOPS_S3_ACCESS_KEY — access key for connecting to the bucket.
    • TESTOPS_S3_SECRET_KEY — secret key for connecting to the bucket.

    For details on configuring access to external S3 storage, such as Amazon S3 and Google Cloud Storage, refer to this article.

Some additional settings can be modified to fine-tune the performance or support non-standard configurations of the storage services. Check the comments in the .env file and consult the Qameta support team if necessary.

First start

When started, Allure TestOps will check all the settings and try to connect to all configured services:

  • If everything is configured correctly, Allure TestOps will send the email invitation to the first admin's email configured via FIRST_ADMIN_EMAIL variable.
  • If there are services that Allure TestOps cannot connect to or configuration parameters are provided incorrectly, application will fail and provide failure details to its log.

Downloading Docker images

Before starting Allure TestOps, you need to download (or “pull”) the required Docker images. This will include the images of Allure TestOps services themselves, as well as some third-party Docker images, such as Redis, MinIO, etc.

The exact list of images that will be pulled depends on the configuration template that you selected — for example, the “demo” configuration (which is not suitable for production) includes a PostgreSQL service, while other configurations do not. In general, you should not rely on any storage services provided by default. Instead, we recommend to deploy all services separately and specify their credentials in the Allure TestOps configuration file.

  1. Open a terminal application.

  2. Navigate to the Allure TestOps installation directory, for example:

    cd ~/testops

  3. Log into the Qameta images registry by running the command below.

    Before executing the command, replace USERNAME and PASSWORD with the credentials provided to you by the Qameta sales team. These credentials will be used when pulling the images of Allure TestOps services.

    docker login --username USERNAME --password PASSWORD

  4. Pull the images.

    docker compose pull

    This process may take a few minutes, depending on the internet connection on your server or virtual machine.

Starting the application

  1. Open a terminal application.

  2. Navigate to the Allure TestOps installation directory, for example:

    cd ~/testops

  3. Start the services by running the command:

    docker compose up -d

    Starting all the services of Allure TestOps takes some time. Wait for a couple of minutes before proceeding to the next step.

  4. Soon after startup, Allure TestOps will send an invitation email to the address that you specified in FIRST_ADMIN_EMAIL. Check the inbox and click the Accept invite link in the email.

    If you get an “Unable to connect” or “This site can't be reached” error in the browser, it may indicate that some services are still initializing. Normally, the initialization takes no more than a couple of minutes.

    If the web browser still cannot open the page after five minutes, see the Troubleshooting section.

  5. In the invitation accept form, fill in the administrator's full name and the credentials that will be used in the login form: Username and Password. The Username must be unique within the Allure TestOps instance.

    Click Continue.

  6. In the activation form, enter the license key that you got from Qameta sales team. Make sure to paste the key without any extra spaces or other characters.

    Click Activate license.

Managing services status

Start services

To launch Allure TestOps:

  1. Open a terminal application.

  2. Navigate to the Allure TestOps installation directory, for example:

    cd ~/testops

  3. Start the Docker compose configuration.

    docker compose up -d

Stop services

To stop Allure TestOps:

  1. Open a terminal application.

  2. Navigate to the Allure TestOps installation directory, for example:

    cd ~/testops

  3. Run the command:

    docker compose down

This command should be always used in case you need to apply new configuration parameters. Other commands do not re-read configuration files and down will require docker compose up -d thus forcing docker compose to read the updated config again.

Restart services

To restart Allure TestOps:

  1. Open a terminal application.

  2. Navigate to the Allure TestOps installation directory, for example:

    cd ~/testops

  3. Run the command:

    docker compose down; docker compose up -d

Upgrading

Before you begin, make sure to read the release notes for the Allure TestOps version you are upgrading to. The release notes may contain crucial information on how to adapt your configuration files or migrate your data to the new version of Allure TestOps. In case you are skipping one or more versions, read the release notes for the skipped versions, too.

  1. In the directory of your installation, edit the .env file in a text editor.

    • In the RELEASE_TO_DEPLOY parameter, specify the version of Allure TestOps you want to upgrade to.
    • If necessary, modify other parameters according to the relevant release notes.

  2. Open a terminal application.

  3. Navigate to the Allure TestOps installation directory, for example:

    cd ~/testops

  4. Make sure Docker is connected to the Qameta repository by running this command:

    docker login --username USERNAME --password PASSWORD

    where USERNAME and PASSWORD are the credentials provided to you by the Qameta sales team.

  5. Upgrade Docker images:

    docker compose pull

    This process may take a few minutes, depending on the speed of your internet connection.

  6. Restart Allure TestOps:

    docker compose down; docker compose up -d

Uninstalling

To uninstall the Allure TestOps instance:

  1. Open a terminal application.

  2. Navigate to the Allure TestOps installation directory, for example:

    cd ~/testops

  3. Remove the Docker containers and all related data:

    docker compose down -v --rmi local

Troubleshooting

If you run into any issues, please check our FAQ page.

Also, in case of any troubles, do not immediately bring Allure TestOps down and up. We need the log files of each component to understand what has happened.

If you encounter an issue not covered in the FAQ, feel free to create a support ticket using your corporate email address. In the ticket, make sure to:

  1. describe the problem you are experiencing,
  2. list the versions of Allure TestOps and all extra components you are having problems with (allurectl, integration plugins, etc.),
  3. attach logs from your system (see below).

Get logs of a specific component

The Allure TestOps deployment consists of multiple components (the main one is named testops), and you need to get logs of each component separately.

  1. Open a terminal application.

  2. Navigate to the Allure TestOps installation directory, for example:

    cd ~/testops

  3. Run the following command to see all the Allure TestOps' services that are currently running:

    docker compose ps

    This command will result into a similar output:

    name@computer folder-name % docker compose ps
NAME             IMAGE                         COMMAND              SERVICE          CREATED    STATUS    PORTS
testops          allure/testops:5.6.4    "...entrypoint.sh"   testops   hour ago   healthy   7777->8080/tcp
rabbitmq         rabbitmq:3.9                  "...entrypoint.sh"   rabbitmq         hour ago   healthy   5671-5672/tcp
redis            redis:6.2                     "...entrypoint.sh"   redis            hour ago   healthy   6379/tcp

  4. Choose the SERVICE for which you want to save logs. For example, testops will give you logs of the Allure TestOps application itself, while redis will give you logs for the Redis instance deployed by Docker Compose (if you use it).

    Use the name in the following command:

    docker compose logs ⟨SERVICE⟩ > ⟨SERVICE⟩.log

    For example:

    docker compose logs testops > testops.log

What else is worth checking

Also check the following:

  • Available memory for the artifacts storage: df -h --total
  • Available inodes for the artifacts storage: df -i
  • Available RAM: free -h, top
© Qameta Software Inc. All rights reserved.