1. Home
  2. Docs
  3. Administrator’s Guide
  4. Manager Deployment

Manager Deployment

The GUARDARA Manager is a web-based, multi-user interface that allows administration of the GUARDARA infrastructure, the creation, and management of tests, and viewing of the test results. The Manager exposes the API that can be used to automate tests and to integrate GUARDARA into CI/CD pipelines.

This page discusses the installation and maintenance of the GUARDARA Manager.

System Requirements

While the Manager should run on most Linux distributions without any issues, the supported platforms for the Manager are listed below:

  • Ubuntu 20.04.2 LTS, both Server and Desktop
  • CentOS 8
  • MacOS Big Sur (Only amd64 platform)

For the best experience, the system should ideally have:

  • At least 4 GB RAM dedicated to the service
  • A modern CPU with at least 4 cores

Deployment

Deploying GUARDARA is very simple. All it takes is downloading the GUARDARA deployment bundle from the main page of the documentation, extracting the archive and running the installer script (install.sh).

The following video walks you through the deployment process.

GUARDARA supports two deployment modes, these are:

Manual: The installer script automatically deploys GUARDARA. After successful deployment, the system has to be configured manually via the user interface accessible at https://${FQDN_OR_IP}:8443.

Cloud-init: To automate the setup phase of GUARDARA as well, a file named cloud-init.yml can be provided next to the installer that contains all the information required during the setup phase. More information and examples can be found in the README.md  within the installer bundle.

When deploying on the supported Linux distributions, the installer script automatically updates the system with the latest updates and installs dependencies such as Dockerdocker-composeopenssl and curl. To avoid accidentally messing up the system, deploying GUARDARA on Mac OS require manual installation of the dependencies. If any of the dependencies are missing, the installer script tells which ones have to be installed manually.

It is important to mention that Docker automatically alters the firewall rules of the system it is deployed on. If this is a problem, it is recommended to deploy GUARDARA on a dedicated system or virtual machine.

Manual Setup

Unless having performed an unattended deployment, the Manager has to be set up. The Manager can be accessed on https://${FQDN_OR_IP}:8443. When accessing the Manager for the first time, it presents a set of forms to be completed to perform the initial configuration of the system. The setup process is made up of a few easy steps; each of these is represented by the Manager on different pages.

License Activation

Before being able to configure GUARDARA, it has to be activated using a License key. Upload the GUARDARA license file using the form and click the Activate button. Please note, GUARDARA requires internet access during license activation. Firewalls must allow GUARDARA to access licensing.guardara.com on port 5000/tcp.

License Agreement

On the next page, based on the license activated, GUARDARA displays the appropriate license agreement. Reading the license agreement is highly recommended as it contains relevant information related to your use of the product.

Administrative Account

The next page allows setting up the Administrator account. The Administrator has unrestricted access to all functionalities of the Manager. Make sure the email address of the Administrator is valid as notifications, including password reset instructions are sent via email. To create other users please refer to the User Management section of the Administrator’s Guide.

Complete Setup

The last page is to indicate that the setup has been completed. To save all settings and complete the initialization, click on the Finish button.

Maintenance

Upgrading GUARDARA Manager

To update the Manager, execute the installer script and answer Y for the Uninstall question. When prompted, answer N to remove data managed by GUARDARA. Next, the installer script removes all GUARDARA Docker containers and images but preserves all data. The script prompts whether to deploy GUARDARA or not. Answer Y to the question and wait until the latest version is deployed.

This script  will install  GUARDARA Manager  to your  computer.  As part
of the process the following actions will be performed:
...
Would you like to proceed? (Y/N) y
Initializing environment...
Installing dependencies...
GUARDARA appears to be already installed. Uninstall? (Y/N) y
Would you like to remove all data managed by GUARDARA? (Y/N) n
Deploy GUARDARA Manager? (Y/N) y

Backing Up and Restoring Assets

The `tools` directory within the installer bundle contains Python scripts to backup and restore test configurations. The backups only contain Message and Test Flow templates, Callbacks and Project configurations. Both the backup and restore scripts use the GUARDARA API, therefore a prerequisite to use these scripts is to install the GUARDARA SDK. Please read the comment left at the beginning of the source code of the backup and restore scripts for more information about the API Key requirements.

Certificate Rotation

The Manager is built up from a set of microservices. Each of these services communicates over TLSv1.2. Mutual certificate authentication is in place.

The certificates can be rotated using the install.sh script as shown below.

$ sudo ./install.sh -r 

Please note, that the Manager is not available during the certificate rotation process. The process removes custom frontend certificates as well. If you had a custom frontend certificate deployed, you have to deploy those again by following the instructions provided under the Custom Frontend Certificate section below.

Custom Frontend Certificate

In case you would like GUARDARA to present your certificate to users (recommended), set up a reverse proxy with the appropriate configuration to proxy all requests between the users and GUARDARA Manager.

Alternatively, you can overwrite the certificate GUARDARA presents to the users. To do this, make sure the guardara_service_nginx container is running and issue the following commands:

docker cp ${CERT_FILE_LOCATION} guardara_service_nginx:/credentials/server/service.crt
docker cp ${PRIVATE_KEY_LOCATION} guardara_service_nginx:/credentials/server/private.key

The next step is to restart the service:

docker restart guardara_service_nginx

Manual Startup

The Docker Compose file used by the install script ensures that all microservices are started automatically. However, if for whatever reason you have to start the Manager services manually, this can be done using either the install.sh script or Docker Compose.

Start the Manager using the install.sh script:

$ sudo ./install.sh -s

Or, from the same directory, start the Manager using Docker Compose:

docker-compose up

Uninstalling GUARDARA Manager

Start the installer script to uninstall the Manager. The script detects if the Manager is installed and prompts whether it should be uninstalled or not. This can be seen in the example below.

GUARDARA appears to be already installed. Uninstall? (Y/N) Y

Another way of uninstalling GUARDARA is via the install.sh script is shown below. Please note, this approach will completely uninstall the Manager without asking for user confirmation.

$ sudo ./install.sh -u

Troubleshooting

Unexpected EOF During Install

This error most often happens if the internet connection is slow or unreliable. If the quality of the internet connection cannot be improved, it may be possible to work around it by reducing the concurrent downloads when pulling docker containers. This can be achieved by updating the Docker daemon’s configuration.

The following example shows how this can be done on Ubuntu Linux.

  1. Open the file /lib/systemd/system/docker.service and locate the line starting with the text ExecStart=.
  2. Add --max-concurrent-downloads=2 to the command line arguments
  3. Save the file
  4. Execute the command systemctl daemon-reloadto reload the configuration
  5. Execute the command systemctl restart docker to restart Docker
  6. Try to install GUARDARA again. Run sudo ./install.sh -r to make sure all GUARDARA related data is removed. Then, install GUARDARA by running sudo ./install.sh -i.

If the above did not solve the issue, try changing max-concurrent-downloads to 1.

Please note, the more we restrict the concurrent downloads, the longer it takes to deploy GUARDARA.

Failed to Install Dependencies Error

The installer script attempts to install all the dependencies required to get GUARDARA Manager up and running. However, due to reasons outside our control, this process may fail. The best place to look at to determine the root cause of the failure is the install.debug file. In case it turns out we made a mistake or missed something, please let us know and we will address the problem.

Was this article helpful to you? Yes No