Deployment

Deployment Guide for the PHYLOViZ Web Platform

Welcome to the Deployment Guide for the PHYLOViZ Web Platform! This guide will provide you with step-by-step instructions on how to deploy the platform in your own environment. By following this guide, you'll be able to set up and configure the PHYLOViZ Web Platform to meet your specific requirements.

Prerequisites

Before proceeding with the deployment, ensure that you have the following prerequisites in place.

• ⚠️ Operating System Requirements:

  • Primary support: Ubuntu 24.04 (⚠️ only version confirmed to work 100% ⚠️)
  • Minimum requirement: Ubuntu 22.04
  • Windows support ❌ [NOT working] ❌: Available through WSL (use the wsl branch) - scripts and commands must be executed entirely through a WSL terminal

• Required Software:

  • Docker (installed and running)

• Storage Requirements:

  • An accessible S3-compatible storage bucket
    • We've tested with AWS S3, but any S3-compatible storage service will work
    • You'll need the following credentials and information to later set up in some configuration files:
      • Access key ID (e.g., AKIAIOSFODNN7EXAMPLE)
      • Secret access key (e.g., wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY)
      • Bucket name (e.g., phyloviz-web-platform)
      • Region (e.g., eu-west-3)
      • Endpoint URL (e.g., https://s3.eu-west-3.amazonaws.com)

Deployment Steps

First, clone the PHYLOViZ Web Platform repository:

git clone https://github.com/phyloviz/phyloviz-web-platform.git

If using wsl branch ❌ [NOT working] ❌:

bash git clone --branch wsl https://github.com/phyloviz/phyloviz-web-platform.git

Then, inside the repository (e.g. cd phyloviz-web-platform), follow the steps below to deploy the application in a production environment:

1. cd scripts

2. ./phylodb_setup.sh

   We are using the PhyloDB fork: https://github.com/devandrepascoa/phyloDB.git

3. ./flowviz_setup.sh (don't forget to do the manual steps [wsl version] that flowviz_setup.sh demands during execution)

   We are using the FLOWViZ fork: https://github.com/devandrepascoa/FLOWViZ.git

4. Go to the repository's root folder (where a docker-compose-yml is located).

5. docker compose up keycloak -d

6. Start with the configuration of the access management system (Keycloak) as described in the section Authentication > Configuration.

7. Modify the configuration files:

   • Keycloak client secret - After the last step, following the keycloak configuration tutorial, the client secret is already configured in the correct files.
   • AWS S3 credentials (a prerequisite was to have an s3-compatible bucket available):
     1. In src/backend/microservices/shared/src/main/resources/application-shared.yml:

        s3:
          access-key-id: AKIAIOSFODNN7EXAMPLE
          secret-access-key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
          bucket: phyloviz-web-platform
          region: eu-west-3
          endpoint: https://s3.eu-west-3.amazonaws.com

     2. In src/backend/tools/aws_credentials:

        [default]
        aws_access_key_id = AKIAIOSFODNN7EXAMPLE
        aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
        

8. ./start.sh

9. Open localhost:8083, and follow the demo (https://www.youtube.com/watch?v=761A27KgHIY).

   • Make sure to register before sign in.
   • As a demonstration, you can use the typing and isolate data files present in the data folder.

By following this deployment process, you will be able to set up and run our application in a production environment successfully. Make sure to carefully execute each step and address any configuration requirements specific to your deployment environment.

Conclusion

Congratulations! You have successfully deployed the PHYLOViZ Web Platform in your environment. By following the deployment guide and completing the necessary steps, you now have a functioning instance of the platform that you can utilize for genetic or epidemiological data analysis.

Remember to regularly update the platform with new releases and security patches to ensure the latest features and bug fixes are incorporated into your deployment.

If you encounter any difficulties during the deployment process or have further questions, don't hesitate to consult the platform's documentation or seek support from the development team.

Happy deploying and analyzing with the PHYLOViZ Web Platform!