Getting Started • Deployment and Usage• Testing & Static Analysis • Contributing • Maintainers • Credits and Acknowledgements • License
Rosalution assists researchers and physicians collaborating on studying genetic variation 🧬 in patients 🧑🏾🤝🧑🏼 to generate definitive diagnoses and aid in the understanding of pathogenic mechanisms. It also guides the development of accurate predictive models and refine existing or suggest new therapeutic approaches. The application facilitates researchers streamlining the selection of candidate animal models 🐀🐁🐠:worm: to replicate the patient variation to further research to derive, diagnose, and provide therapies for ultra-rare diseases.
Rosalution is the open-source web application maintained and developed by the University of Alabama at Birmingham (UAB) Center for Computational Genomics and Data Science (CGDS) to support not only the current UAB Center for Precision Animal Modeling (C-PAM) process, but also data collection, quality control, standardization, and integration. It enriches the analysis, guiding and collecting the decisions made during case and variant consideration. This effort to consolidate both the process and the data is critical; this shift is needed to reduce the costs and increase the throughput of precision modeling projects in general.
Rosalution facilitates three aspects of the collaborative case review process.
- ⌨️ augmenting and standardizing case and variant/gene intake and annotation with configurable automated annotation from publicly available data sources
- ✨ supporting expert curation by clinical and research experts via a web-based interface
- 🌐 supporting synchronous and asynchronous collaborative review by interdisciplinary teams via a web-based interface
Watch Rosalution's demonstration video here!
The following pre-requisites are required to be installed in the target *NIX environment for deploying and testing Rosalution. Install environment dependencies below using the respective installation instructions for your target environment.
- Node.JS 20.8+ & Classic Yarn
- Python 3.11+ - Install
pip3to install the required packages for development within a virtual environmentpython venvSome system installations of Python 3+ do not include python virtual environments that were added in Python 3.3+. Additional installation and setup may be necessary if using Python packaged with an OS (such as Ubuntu).
- Git
- Setup with your favorite git client. Here is a GitHub Guide for different platforms.
- Docker 17.12.0+ with
docker-composeCLI ordocker composefrom Docker Desktop - Install- Docker Compose is used for local deployments of the application. The
docker-composetool is fully integrated within the Docker Desktop suite now. For new users of Docker it is easier to get started with Docker Desktop. From the official Docker documentation, "[docker compose] is expected to be a drop-in replacement fordocker-compose". - Installing and running Docker requires sudo/admin privileges in the target environment
- Docker Compose is used for local deployments of the application. The
- sudo/Admin environment privileges and write privileges to the /etc/hosts file
- The
setup.shscript requires sudo/admin privileges in the target development environment to update the/etc/hostsfile to setup localhost redirection for a Rosalution deployment to redirect localhost to local.rosalution.cgds
- The
- mkcert
- Tool to generate and install self-signed locally-trusted development certificates
- Used to make certificates for Traefik to manage HTTPS enabled services
- The
setup.shscript requires sudo/admin privileges in the target development envrionment to install the generated certificates in the respective browser trusts so browsers know they're valid and won't throw an insecure warning- Default certificate location:
./etc/certificates
- Default certificate location:
- Note: Local deployment will still work without self-signed certificates. The browser will just throw an insecure warning, the application can still be used.
| Chrome | Firefox |
|---|---|
| 64+ | 86+ |
Clone the Git repository from GitHub locally.
git clone https://github.com/uab-cgds-worthey/rosalution.git
cd rosalutionsetup.sh provisions your local environment for developing Rosalution.
The script will
yarn installwithin each subdirectory- Updates your local
/etc/hoststo support the local DNS redirect of localhost to 'local.rosalution.cgds'. - Creates a Python virtual environment for called "rosalution_env" within the backend directory
- Installs Python dependencies within the virtual environment
- Checks if
mkcertis installed, if so generates self-signed certificates in./etc/certificates- Generates two files, one .pem key file and one .pem cert file
./setup.shFor Windows Subsystem Linux users updating their /etc/hosts in WSL2
The
/etc/hostsfile must manually update on the Windows side located inC:\Windows\System32\drivers\etcas an administrator. Then restart the Linux Subsystem by running the following in PowerShell as an administrator
Restart-Service LxssManager*- Deploying with Docker Compose
- Login and Access
- Adding Users
- Database
- Production
- Common Deployment Troubleshooting
Deploy Rosalution from the project's root directory using docker compose in
your terminal. Be sure that ./setup.sh has been run recently for any
recent dependency updates to be installed in all of the subdirectories.
After following one the deployment commands in the below in the terminal,
- Visit http://local.rosalution.cgds/rosalution/ for the main rosalution Application
- Visit http://local.rosalution.cgds/rosalution/api/docs for accessing the API
For deployment troubleshooting, visit Common Deployment Troubleshooting.
# deploy rosalution services within this session
docker compose up
# deploy services in the background using the `-d` option
docker compose up --build -d
# force docker images to re-build using the `--build` option
docker compose up --buildTo log in to the system once it has been locally deployed, enter a username in the designated field and click the "Login" button as seen in the figure below.
The method of authentication for the Rosalution system may vary depending on the deployment environment. In a local development environment, the system utilizes OAuth2 for issuing login tokens. This allows for a streamlined development experience and faster iteration.
In contrast, in a production environment, the system utilizes CAS (Central Authentication Service) for authentication. This means that in order to log in to the production environment, a valid username must be provided, and an OAuth2 token will be issued if the username is valid in the system.
A list of all users in the system is available in etc/fixtures/initial-seed/users.json.
User permissions according to a type of user is planned to become available in an upcoming update.
👩💻 The following table lists some of the usernames and their corresponding user types:
| Username | Scope | Type of User |
|---|---|---|
| developer | write | Developer user |
| researcher | read | Researcher user |
| vrr-prep | write | Researcher who prepares analyses |
Users can create new cases on Rosalution by clicking on the '+' card to add a new case, as shown in the below figures. Doing so prompts an upload dialog to import files to create a new Rosalution case. These files must be in .json format. Once uploaded, a 'Successful import' dialog displays. Refresh the page to see the newly imported case on the Rosalution dashboard.
To refer how to format your .json files to upload as new cases, refer to the example cases .json files in ./etc/fixtures/import/.
To add a new user to the system, you must first define the user in the same format as the users in the
example-adding-users.json file in the etc/fixtures directory.
Then, you must run the following command from the root directory of the project:
docker-compose exec -T rosalution-db mongosh /tmp/fixtures/add-user.jsUsage information on optional arguments for the add-user.js script is available by running the following command:
docker-compose exec -T rosalution-db mongosh --eval "var help=true;" /tmp/fixtures/add-user.jsRosalution uses MongoDB to store the state of the application.
MongoDB database fixtures are located in the <project-root>/etc/fixtures directory.
The initial-db-seed.sh script and ./etc/fixtures/ directory are mounted as
volumes into the database container for use to seed the database.
rosalution-db:
image: mongo:5.0.9
volumes:
- ./etc/fixtures/initial-seed/initial-db-seed.sh:/docker-entrypoint-initdb.d/initial-db-seed.sh
- ./etc/fixtures/:/tmp/fixturesThe MongoDB DB is initially seeded at the time of container startup using the
/docker-entrypoint-initdb.d/initial-db-seed.sh script.
Visit MongoDB Initializing a fresh instance for more information on
/docker-entrypoint-initdb.dexecuting scripts at the time of startup.
When automated testing, Cypress re-seeds the database using the ./etc/fixtures/seed.js script to
reset Rosalution's state. The script is executed within the MongoDB database
container with docker compose exec.
docker compose exec rosalution-db mongosh /tmp/fixtures/seed.jsUse the following command to view the database within the MongoDB container.
docker exec -it rosalution_rosalution-db_1 mongosh rosalution_dbEach Rosalution service prepares docker images for production deployments. Both
docker-compose.production.yml and
docker-compose.local-production.yml compose
yml files allow you to build those production images locally.
These images ensure that each service builds and bundles each one for production that strips development code that streamlines development of Rosalution.
The frontend uses a rollup plugin configured to be used during bundling to strip a developer login to Rosalution.
The backend utilizes the environment variable ROSALUTION_ENV set to production when
deploying using the entrypoint-init.sh to startup the backend service.
This alters how the application behaves in certain ways, one of which is that the backend service will run Python with
the -O flag which will strip code conditional on the
value of __debug__.
When deploying the Rosalution system in a production environment, it is important to ensure that the build is optimized
for security. This can be achieved by using the build.sh script.
The build.sh script is a command-line tool that can be used to build the Rosalution system for a production
environment. The script accepts various command-line arguments that can be used to customize the build process.
The script also includes several functions that are used to parse the build configuration file, construct build arguments, and build the necessary images. It also includes a function to push the built images to their respective repositories.
Note: The Docker images built by the build.sh script can only be published by Rosalution maintainers to our private
registry.
For additional information on the build.sh script, refer to the build.sh script documentation within the
script itself.
The local production docker compose yaml must be updated if you would like to test the docker images created from the
build.sh script. Modify the docker-compose.local-production.yml by:
- Commenting out the build configuration designated within the compose yaml.
#build:
#context: ./frontend/
#target: production-stage
#dockerfile: Dockerfile
#args:
#VERSION_BUILD_TAG: "local-production@latest"- Uncommenting the docker image tags for the
frontendandbackendservices
image: ghcr.io/uab-cgds-worthey/rosalution/frontend:${ROSALUTION_VERSION}- Setting the ROSALUTION_VERSION environment variable to be the 'build tag' used with the
build.shscript.
export ROSALUTION_VERSION=0.6.0- Deploy the Rosalution Build as indicated in the following section
docker-compose -f docker-compose.local-production.yml up --buildTo deploy a production build locally, the following command can be uses.
docker-compose -f docker-compose.local-production.yml up --buildThis command uses the docker-compose tool to build and run the necessary containers for the production
environment, as specified in the docker-compose.local-production.yml file. The -f flag is used to specify the
compose file to use, in this case docker-compose.local-production.yml and --build flag is used to force Docker
Compose to rebuild the images.
To access the locally deployed Rosalution application after running docker compose up,
visit the http://local.rosalution.cgds/rosalution/ URL in your browser.
When I navigate to localhost:80 in the browser I see a 404 error page.
The local application deployment relies on the reverse proxy routing localhost
requests from the base URL http://local.rosalution.cgds/rosalution.
./setup.sh must also have been run in advance to properly setup the
routing.
When I navigate to local.rosalution.cgds/rosalution in the browser I see a 404 error page.
There could be two issues when this is happening. First, verify the frontend
and reverse proxy docker containers by running docker ps in your terminal.
If both containers are running, then re-run the .setup.sh script in the
project's root directory to verify no errors are occur while running.
Rosalution's entire stack is supported with thorough testing. Review the following important notes below before getting started with running and developing tests.
- ✔️ Dependencies in your environment must be installed as listed in #Getting Started##Prerequisites
- ✔️ Your local environment must successfully setup with setup.sh in order to run testing
- 📁 Tests must be executed within their respective sub-directories
- 🐍 Python unit tests and linting must run within the activated python virtual environment.
(For details, refer Backend Local Development)
source backend/rosalution_env/bin/activate
Refer to the following READMEs for details on running tests and code coverage for the Rosalution's backend and frontend.
System testing requires the entire stack of the application to be successfully deployed to your local development environment. The environment must be setup and the application deployed with docker compose. Refer to the following for a quick start with System Testing done by Cypress.
Our system testing requires that Chrome is available as a browser on the system. This makes it extremely difficult to setup/run within Windows Subsystem Linux, so running system testing in WSL2 is not supported.
# Run System Testing with report displayed in terminal
cd system-tests
yarn test:e2e# Run System Testing with Cypress UI to visualize and run system testing
cd system-tests
yarn test:e2e:openWe use linting tools for JavaScript, Python, Docker, Markdown, and Shell scripts for static analysis.
To see the commands and how to run linting, refer to Linting and Static Analysis in the Contributing Guidelines.
We welcome contributions from the community! Please read our 🎇Contributing Guidelines to learn how you can help improve the project.
We expect all contributors to adhere to our 📋code of conduct. Please read it before contributing to the project.
To report a bug, refer to 🐞Reporting Issues in the 🎇Contributing Guidelines.
Elizabeth Worthey, Ph.D.
Principal Investigator, Director,
Center for Computational Genomics and Data Science (CGDS)
Co-Director,
Center for Precision Animal Modeling - Bioinformatics Section
Heersink School of Medicine, The University of Alabama at Birmingham, Birmingham, AL
Center for Computational Genomics and Data Science (CGDS)
Department of Genetics
Heersink School of Medicine, The University of Alabama at Birmingham, Birmingham, AL
Center for Precision Animal Modeling (C-PAM)
The University of Alabama at Birmingham, Birmingham, AL
Bioinformatics Section(BIS) in the Center for Precision Animal Modeling (C-PAM)
The University of Alabama at Birmingham, Birmingham, AL
Donna Brown 🌐 • Aleksandra Foksinska 🌐
• Manavalan Gajapathy, Ph.D. 
🌐 •
Elizabeth J. Wilk 🌐 • Brittany Lasseigne, Ph.D. 🌐Lasseigne Lab
Rosalution is licensed under the GNU General Public License v3.0.