TestOps logo
Try TestOps

Install Allure TestOps via Docker Compose

This article describes installation of Allure TestOps version 4.x. For the newer version 5.x, click here.

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

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

Preparation steps

  1. Install Docker and Docker Compose V2 plugin.

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

    docker compose version

  2. Deploy external storage servers:

    • two PostgreSQL databases (that could be single server, but two separate databases with different schema),
    • one MinIO or other S3-compatible storage server,
    • one RabbitMQ message server,
    • one Redis storage server.

    Installation without using external storage is also possible, as demonstrated in the testops-demo and testops-demo-ldap examples.

    However, this option is intended for evaluation purposes only and is not officially supported. Maintaining and upgrading such a configuration can involve considerable downtimes or data loss.

  3. 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 a username and a password for accessing Qameta's Docker repository.

  4. Get details for configuring authentication.

    The required details depend on which approach to user authentication you choose. There are two possible approaches.

    • Standard email-based authentication, implemented by Allure TestOps itself.

      This requires a working SMTP account, e.g., a Gmail account. A new user will be able to register by entering their email address, to which Allure TestOps will send a confirmation email.

    • 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.

Creating configuration files

On this step, you will create a directory with two files:

  • docker-compose.yml — the definition of the cluster architecture. This file is provided by Qameta.
  • .env — the environment variables that will be used by Docker Compose when running the cluster. Qameta provides templates for this file which you need to customize for your needs.

To prepare the configuration files:

  1. Visit one of the links below, 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-oidc for authentication via OpenID Connect (Keycloak, GitLab, Azure AD, Okta),

  1. Download the docker-compose.yml and env-example files into an empty directory.

  2. Rename the env-example file to .env (note the dot at the beginning!) and open it in a text editor.

    The file defines parameters that will affect behavior of your Allure TestOps instance. For the most typical setup, just do the following:

Choose TestOps release

In the ALLURE_VERSION parameter, specify the version of Allure TestOps you want to use.

Check out the Release notes section for the list of available versions. In general, it is recommended to use the latest release.

Set TestOps URL

Specify the parameters that affect how the users will access Allure TestOps: ALLURE_PROTO, ALLURE_HOST and ALLURE_INSTANCE_PORT.

In the example below, the parameters are set so that the Allure TestOps instance would be available at “http://testops.example.com/” (using port 80, which is the default port for HTTP).

ALLURE_PROTO=http
ALLURE_HOST=testops.example.com
ALLURE_INSTANCE_PORT=80

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

Set admin credentials

To be able to log into Allure TestOps for the first time, you need have an administrator account. Unlike all other accounts that are managed via the Members interface, the administrator account is managed via the configuration parameters directly.

In the ALLURE_ADMIN parameter, specify a login you want to use for the administrator account, e.g., “admin”.

In the ALLURE_ADMIN_PASS parameter, specify a password. Alternatively, you can leave this parameter empty, in which case a new password will be generated for the administrator account each time the allure-uaa service is restarted (see Managing services status). You will be able to find the generated password in the service logs.

See Configuration → Authentication for more details.

Configure authentication

A necessary step when deploying Allure TestOps is to configure how users will be registered and logged in. See Configuration → Authentication for more details.

Below are some configuration examples for various identity providers.

# please remember, this is an example, which won't work for you,
# you need to update your config with real SMTP server data.
ALLURE_MAIL_HOST=smtp.gmail.com
ALLURE_MAIL_PORT=465
ALLURE_MAIL_USERNAME=username
ALLURE_MAIL_PASSWORD=password
[email protected]
ALLURE_MAIL_SMTP_AUTH=true
ALLURE_MAIL_SMTP_STARTTLS_ENABLE=true
ALLURE_MAIL_SMTP_STARTTLS_REQUIRED=true
ALLURE_MAIL_SMTP_SSL_ENABLE=true
ALLURE_MAIL_SMTP_SSL_TRUST=smtp.gmail.com

LDAP_URL="ldaps://ldaps.space:636"
LDAP_USER_SEARCH_BASE="ou=People,dc=space"
LDAP_USER_SEARCH_FILTER="uid={0}"

LDAP_SYNC_ROLES=false
LDAP_GROUP_SEARCH_BASE="ou=group,dc=space"
LDAP_GROUP_SEARCH_FILTER="memberUid={1}"
LDAP_GROUP_ROLE_ATTRIBUTE=cn
LDAP_UID_ATTRIBUTE=uid

LDAP_MAPPING_ROLE_USERS=atousers,every_user_is_user
LDAP_MAPPING_ROLE_ADMINS=atoadmins,every_user_is_admin

# Default role, can be ROLE_GUEST/ROLE_USER/ROLE_ADMIN
LDAP_DEFAULT_ROLE=ROLE_GUEST

LDAP_LOGIN_SA="cn=admin,dc=space"
LDAP_LOGIN_SA_PASS=SeriviceAccountPassword_Here

this integration is not ready yet

Configure storage services

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

  • Connection to the Redis storage server

    • ALLURE_REDIS_HOST — server hostname.
    • ALLURE_REDIS_PORT — server port.
    • ALLURE_REDIS_PASS — password for connecting to the storage.

  • Connection to the PostgreSQL database for authentication data

    • ALLURE_UAA_DB_HOST — database server hostname.
    • ALLURE_UAA_DB_PORT — database server port.
    • ALLURE_UAA_DB_NAME — database name.
    • ALLURE_UAA_DB_USERNAME — username for connecting to the database.
    • ALLURE_UAA_DB_PASS — password for connecting to the database.

  • Connection to the PostgreSQL database for application data

    • ALLURE_REPORT_DB_HOST — database server hostname.
    • ALLURE_REPORT_DB_PORT — database server port.
    • ALLURE_REPORT_DB_NAME — database name.
    • ALLURE_REPORT_DB_USERNAME — username for connecting to the database.
    • ALLURE_REPORT_DB_PASS — password for connecting to the database.

  • Connection to the RabbitMQ server

    • ALLURE_RABBIT_HOST — server hostname.
    • ALLURE_RABBIT_PORT — server port.
    • ALLURE_RABBIT_USER — username for connecting to the message queue.
    • ALLURE_RABBIT_PASS — password for connecting to the message queue.

  • Connection to the S3-compatible storage server

    • ALLURE_S3_URL — server URL.
    • ALLURE_S3_BUCKET — S3 bucket name.
    • ALLURE_S3_REGION — S3 region name.
    • ALLURE_S3_ACCESS_KEY — access key for connecting to the bucket.
    • ALLURE_S3_SECRET_KEY — secret key for connecting to the bucket.

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 PostgreSQL, Redis, etc.

  1. Open a terminal application.

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

    cd ~/allure-testops

  3. Connect Docker to the Qameta repository 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 speed of your internet connection.

Activating license

When you run your Allure TestOps installation for the first time, you need to activate it by entering a license key.

  1. Open a terminal application.

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

    cd ~/allure-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. In a web browser, go to the URL that you configured on the Set TestOps URL step. An authentication form should appear.

    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 authentication form, enter the login and password that you configured on the Set admin credentials step.

    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 ~/allure-testops

  3. Start the Docker containers.

    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 ~/allure-testops

  3. Run the command:

    docker compose down

Restart services

To restart Allure TestOps:

  1. Open a terminal application.

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

    cd ~/allure-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 ALLURE_VERSION 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 ~/allure-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 ~/allure-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. Please include the following information in the ticket:

  1. Description of the problem you are experiencing.
  2. Versions of Allure TestOps and all extra components you are having problems with (allurectl, integration plugins, etc.).
  3. Logs from your system as attachments to the ticket (see the details below). Please only send us the logs described below and only as an attachment.

Getting the logs

You can get all the logs for your Allure TestOps instance by executing following command:

docker compose logs -f
  • this will continuously update the logs from all the services
  • this log is good for a quick analysis on your side, please do not provide this log to the technical support.

Logs of specific component

To get logs for a specific component you need to specify a service name for which you want to see the logs.

To get the name of services of your Docker Compose deployment you need either check your docker-compose.yml file or execute the following command in your terminal (your current directory must contain Docker Compose config files).

docker compose ps

this command will result into a similar output:

name@computer folder-name % docker compose ps
NAME                 COMMAND                  SERVICE                    STATUS               PORTS
allure-gateway       "/bin/sh -c /entrypo…"   allure-gateway             running (healthy)   0.0.0.0:10777->8080/tcp
allure-report        "/bin/sh -c /entrypo…"   allure-report              running (healthy)
allure-uaa           "/bin/sh -c /entrypo…"   allure-uaa                 running (healthy)
autoheal             "/docker-entrypoint …"   autoheal                   running (healthy)
minio-local          "/opt/bitnami/script…"   minio-local                running              0.0.0.0:9000->9000/tcp
minio-provisioning   "/bin/sh -c 'mc conf…"   minio-local-provisioning   exited (0)
rabbit               "/opt/bitnami/script…"   rabbitmq                   running              25672/tcp
redis                "/opt/bitnami/script…"   redis                      running (healthy)    6379/tcp
report-db            "docker-entrypoint.s…"   report-db                  running              5432/tcp
uaa-db               "docker-entrypoint.s…"   uaa-db                     running              5432/tcp

The column we need is SERVICE.

to get all logs of Allure TestOps services saved to separate files you need to execute the following command:

docker compose logs allure-report > report-logs.txt && \
docker compose logs allure-uaa > uaa-logs.txt && \
docker compose logs allure-gateway > gateway-logs.txt

What else is worth checking

Also check the following:

  1. Available memory for the artifacts storing df -h --total on your storage
  2. Available inodes for the artifacts storage df -i
  3. Available RAM free -h, top
  4. Other services logs.

Alternatively you can use this script to get the needed logs.

© Qameta Software Inc. All rights reserved.