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.
The support of the authentication using OpenID is available starting from Allure TestOps 5.6.4. OpenID, SAML2, LDAP are available for on-prem deployment for the time being. The support of external IdP providers in SaaS is planned in Q4 2024.
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:
- Create the new .env file for the newly developed Compose configurations based on your current configuration.
- Stop the existing instance.
- Merge the information from the UAA service database to the report service database.
- 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
Install Docker on the machine where you will run Allure TestOps.
See the installation guide on the Docker website.
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 versionDeploy additional services required for Allure TestOps to start:
- PostgreSQL service (version 15 or higher),
- Amazon S3, Google Cloud Storage, MinIO or another S3-compatible storage solution,
- RabbitMQ message queue service,
- Redis service.
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-democonfiguration 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.
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.
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 an external 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
Download the configuration files:
- When working on a Unix-like machine, use either
wgetorcurlto 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.
- When working on a Unix-like machine, use either
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-demodirectory contains a demo version of Allure TestOps. It is not suitable for a production environment.Move the docker-compose.yml and env-example files into an empty directory.
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.
Open the .env file in a text editor. For a typical configuration, follow these steps:
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 encryption key for sensitive data
As a security measure, Allure TestOps encrypts the most sensitive values in its database using a secret password. This way, if a malicious actor gets access to the PostgreSQL database but not to the configuration file, this will not compromise the other services' credentials used by the deployment.
To set the password, change the value of the TESTOPS_CRYPTO_PASSWORD parameter.
Note that if the value is lost or changed after the initial deployment, all previously configured integrations will stop working. In such a case, you will need to go to each projects' settings and re-enter valid credentials.
TESTOPS_CRYPTO_PASSWORD=ogheRiy7ooCh6Oocei6OdaD1iequooNa
Set first admin email
Starting from the version 5.5.0, valid SMTP credentials are mandatory in any configuration. Allure TestOps will use them for sending an invitation email to the administrator, regardless of the main authentication method. The administrator's email address must be specified in the FIRST_ADMIN_EMAIL parameter.
Below is an example of configuration parameters for a Gmail account. Note that Google requires to generate dedicated app passwords for SMTP. Other mail services may have similar requirements.
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=username
SMTP_PASSWORD=password
[email protected]
SMTP_AUTH=true
SMTP_STARTTLS_ENABLE=true
SMTP_STARTTLS_REQUIRED=true
SMTP_SSL_ENABLE=false
SMTP_SSL_TRUST=smtp.gmail.com
# ...
[email protected]
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
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.
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_EMAILvariable. - 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.
Open a terminal application.
Navigate to the Allure TestOps installation directory, for example:
cd ~/testopsLog 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 PASSWORDPull the images.
docker compose pullThis process may take a few minutes, depending on the internet connection on your server or virtual machine.
Starting the application
Open a terminal application.
Navigate to the Allure TestOps installation directory, for example:
cd ~/testopsStart the services by running the command:
docker compose up -dStarting all the services of Allure TestOps takes some time. Wait for a couple of minutes before proceeding to the next step.
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.
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.
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:
Open a terminal application.
Navigate to the Allure TestOps installation directory, for example:
cd ~/testopsStart the Docker compose configuration.
docker compose up -d
Stop services
To stop Allure TestOps:
Open a terminal application.
Navigate to the Allure TestOps installation directory, for example:
cd ~/testopsRun 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:
Open a terminal application.
Navigate to the Allure TestOps installation directory, for example:
cd ~/testopsRun 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.
In the directory of your installation, edit the .env file in a text editor.
- In the
RELEASE_TO_DEPLOYparameter, specify the version of Allure TestOps you want to upgrade to. - If necessary, modify other parameters according to the relevant release notes.
- In the
Open a terminal application.
Navigate to the Allure TestOps installation directory, for example:
cd ~/testopsMake sure Docker is connected to the Qameta repository by running this command:
docker login --username USERNAME --password PASSWORDwhere USERNAME and PASSWORD are the credentials provided to you by the Qameta sales team.
Upgrade Docker images:
docker compose pullThis process may take a few minutes, depending on the speed of your internet connection.
Restart Allure TestOps:
docker compose down; docker compose up -d
Uninstalling
To uninstall the Allure TestOps instance:
Open a terminal application.
Navigate to the Allure TestOps installation directory, for example:
cd ~/testopsRemove 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:
- describe the problem you are experiencing,
- list the versions of Allure TestOps and all extra components you are having problems with (allurectl, integration plugins, etc.),
- 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.
Open a terminal application.
Navigate to the Allure TestOps installation directory, for example:
cd ~/testopsRun the following command to see all the Allure TestOps' services that are currently running:
docker compose psThis 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/tcpChoose the
SERVICEfor which you want to save logs. For example,testopswill give you logs of the Allure TestOps application itself, whilerediswill 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⟩.logFor 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
