---
title: Getting Started
weight: 10
aliases: /medical-diagnosis/getting-started/
---

:toc:
:imagesdir: /images
:_content-type: ASSEMBLY
include::modules/comm-attributes.adoc[]

[id="deploying-med-pattern"]
== Deploying the {med-pattern}

.Prerequisites

* An OpenShift cluster
 ** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console].
 ** Select *OpenShift \-> Red Hat OpenShift Container Platform \-> Create cluster*.
 ** The cluster must have a dynamic `StorageClass` to provision `PersistentVolumes`. Verify that a dynamic `StorageClass` exists before creating one by running the following command: 
+
[source,terminal]
----
$ oc get storageclass -o custom-columns=NAME:.metadata.name,PROVISIONER:.provisioner,DEFAULT:.metadata.annotations."storageclass\.kubernetes\.io/is-default-class"
----
+
.Example output
+
[source,terminal]
----
NAME      PROVISIONER       DEFAULT
gp2-csi   ebs.csi.aws.com   <none>
gp3-csi   ebs.csi.aws.com   true
----
+
For more information about creating a dynamic `StorageClass`, see the https://docs.openshift.com/container-platform/latest/storage/dynamic-provisioning.html[Dynamic provisioning].
* A GitHub account and a token for it with repositories permissions, to read from and write to your forks.
* An S3-capable storage set up in your public or private cloud for the x-ray images
* The Helm binary, see link:https://helm.sh/docs/intro/install/[Installing Helm]
For installation tooling dependencies, see link:https://validatedpatterns.io/learn/quickstart/[Patterns quick start].

[NOTE]
====
The {med-pattern} does not have a dedicated hub or edge cluster.
====

[id="setting-up-an-s3-bucket-for-the-xray-images-getting-started"]
=== Setting up an S3 Bucket for the xray-images

An S3 bucket is required for image processing.
The link:https://github.com/validatedpatterns/utilities[utilities] repo and specifically the `aws-tools` directory contains some S3 tools and EC2 tools.

For the official documentation on creating the buckets on AWS and other cloud providers, see the following links:

* link:https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html[AWS S3]
* link:https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal[Azure Blob Storage]
* link:https://cloud.google.com/storage/docs/quickstart-console[GCP Cloud Storage]


[id="utilities"]
== Utilities
//AI: Update the use of community and VP post naming tier update

Follow this procedure to use the scripts provided in the link:https://github.com/validatedpatterns/utilities[utilities] repo to configure an S3 bucket in your AWS environment for the x-ray images.

.Procedure

. Fork the link:https://github.com/validatedpatterns/utilities[utilities] repository on GitHub. Forking the repository allows you to update the repository as part of the GitOps and DevOps processes.

. Clone the forked copy of this repository.
+
[source,terminal]
----
$ git clone git@github.com:validatedpatterns/utilities.git
----

. Go to your repository: Ensure you are in the root directory of your Git repository by using:
+
[source,terminal]
----
$ cd utilities
----

. Run the following command to set the upstream repository:
+
[source,terminal]
----
git remote add -f upstream git@github.com:validatedpatterns/utilities.git
----

. Change to the `aws-tools` directory:
+
[source,terminal]
----
$ cd aws-tools
----

. Run the following commands in your terminal to export environment variables for AWS authentication:
+
[source,terminal]
----
export AWS_ACCESS_KEY_ID=AKXXXXXXXXXXXXX
export AWS_SECRET_ACCESS_KEY=gkXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
----
+
[NOTE]
====
Ensure that you replace values with your keys
====

. Create the S3 bucket by running the following command:
+
[source,terminal]
----
$ python s3-create.py -b kevtest-bucket -r us-east-1 -p
----

. Copy over the data from the validated patterns public bucket to the created bucket for your demo. 
+
[source,terminal]
----
$ python s3-sync-buckets.py -s validated-patterns-md-xray -t kevtest-bucket -r us-east-1
----

Note the name of the bucket for further pattern configuration. Later you will update the `bucketSource` in the `values-global.yaml` file, where there is a section for `s3:`.

[id="preparing-for-deployment"]
== Preparing for deployment
.Procedure

. Fork the link:https://github.com/validatedpatterns/medical-diagnosis[medical-diagnosis] repository on GitHub. You must fork the repository because your fork will be updated as part of the GitOps and DevOps processes.

. Clone the forked copy of this repository.
+
[source,terminal]
----
$ git clone git@github.com:<your-username>/medical-diagnosis.git
----

. Go to your repository: Ensure you are in the root directory of your Git repository by using:
+
[source,terminal]
----
$ cd /path/to/your/repository
----

. Run the following command to set the upstream repository:
+
[source,terminal]
----
$ git remote add -f upstream git@github.com:validatedpatterns/medical-diagnosis.git
----

. Verify the setup of your remote repositories by running the following command:
+
[source,terminal]
----
$ git remote -v
----
+
.Example output
+
[source,terminal]
----
origin	git@github.com:kquinn/medical-diagnosis.git (fetch)
origin	git@github.com:kquinn/medical-diagnosis.git (push)
upstream	git@github.com:validatedpatterns/medical-diagnosis.git (fetch)
upstream	git@github.com:validatedpatterns/medical-diagnosis.git (push)
----

. Create a local copy of the Helm values file that can safely include credentials.
+
[WARNING]
====
Do not commit this file. You do not want to push personal credentials to GitHub.
====
+
Run the following commands:
+
[source,terminal]
----
$ cp values-secret.yaml.template ~/values-secret-medical-diagnosis.yaml
----
+
.Example `values-secret.yaml` file

[source,yaml]
----
version "2.0"
secrets:
  # NEVER COMMIT THESE VALUES TO GIT

  # Database login credentials and configuration
  - name: xraylab
    fields:
    - name: database-user
      value: xraylab
    - name: database-host
      value: xraylabdb
    - name: database-db
      value: xraylabdb
    - name: database-master-user
      value: xraylab
    - name: database-password
      onMissingValue: generate
      vaultPolicy: validatedPatternDefaultPolicy
    - name: database-root-password
      onMissingValue: generate
      vaultPolicy: validatedPatternDefaultPolicy
    - name: database-master-password
      onMissingValue: generate
      vaultPolicy: validatedPatternDefaultPolicy

  # Grafana Dashboard admin user/password
  - name: grafana
    fields:
      - name: GF_SECURITY_ADMIN_USER:
        value: root
      - name: GF_SECURITY_ADMIN_PASSWORD:
        onMissingValue: generate
        vaultPolicy: validatedPatternDefaultPolicy
----
+
By default, the Vault password policy generates the passwords for you. However, you can create your own passwords.

. If you want to create custom passwords for the database users you will need to edit this file:
+
[source,terminal]
----
$ vi ~/values-secret-medical-diagnosis.yaml
----
+
[NOTE]
====
When defining a custom password for the database users, avoid using the `$` special character as it gets interpreted by the shell and will ultimately set the incorrect desired password.
====

. Create and switch to a new branch named my-branch, by running the following command:
+
[source,terminal]
----
$ git checkout -b my-branch
----

. Edit the `values-global.yaml` updating the S3 and datacenter details. 
+
[source,terminal]
----
$ vi values-global.yaml
----
+
.Example edited `values-global.yaml` file
+
[source,yaml]
----
global:
  pattern: xray

  options:
    useCSV: False
    syncPolicy: Automatic
    installPlanApproval: Automatic

  datacenter:
    storageClassName: gp3-csi
    cloudProvider: aws
    region: us-east-1
    clustername: mytestcluster
    domain: aws.validatedpatterns.io

  xraylab:
    namespace: "xraylab-1"

    s3:
      # Values for S3 bucket access
      # bucketSource: "provide s3 bucket name where images are stored"
      bucketSource: kevtest-bucket
      # Bucket base name used for image-generator and image-server applications.
      bucketBaseName: "xray-source"

main:
  clusterGroupName: hub
  multiSourceConfig:
    enabled: true
    clusterGroupChartVersion: 0.9.*

# Example Configuration
  #datacenter:
  #  cloudProvider: aws
  #  storageClassName: gp2
  #  region: us-east-1
  #  clustername: example-sample
  #  domain: patterns.redhat.com
----

.  Add `values-global.yaml` to the staging area:
+
[source,terminal]
----
$ git add values-global.yaml
----

. Commit the staged changes with a message:
+
[source,terminal]
----
$ git commit -m "Update values-global.yaml"
----

. Push the changes to your forked repository:
+
[source,terminal]
----
$ git push origin my-branch
----

You can proceed to install the {med-pattern} pattern by using the web console or from command line by using the script `./pattern.sh` script. 

To install the {med-pattern} pattern by using the web console you must first install the Validated Patterns Operator. The Validated Patterns Operator installs and manages Validated Patterns. 

//Include Procedure module here
[id="installing-validated-patterns-operator_{context}"]
== Installing the {validated-patterns-op} using the web console

.Prerequisites
* Access to an {ocp} cluster by using an account with `cluster-admin` permissions.

.Procedure

. Navigate in the {hybrid-console-first} to the *Operators* → *OperatorHub* page.

. Scroll or type a keyword into the *Filter by keyword* box to find the Operator you want. For example, type `validated patterns` to find the {validated-patterns-op}.

. Select the Operator to display additional information.
+
[NOTE]
====
Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing.
====

. Read the information about the Operator and click *Install*.

. On the *Install Operator* page:

.. Select an *Update channel* (if more than one is available).

.. Select a *Version* (if more than one is available).

.. Select an *Installation mode*:
+
The only supported mode for this Operator is *All namespaces on the cluster (default)*. This installs the Operator in the default `openshift-operators` namespace to watch and be made available to all namespaces in the cluster. This option is not always available.

.. Select *Automatic* or *Manual* approval strategy.

. Click *Install* to make the Operator available to the selected namespaces on this {ocp} cluster.

.Verification
To confirm that the installation is successful:

. Navigate to the *Operators* → *Installed Operators* page.

. Check that the Operator is installed in the selected namespace and its status is `Succeeded`.

//Include Procedure module here
[id="create-pattern-instance_{context}"]
== Creating the Medical Diagnosis GitOps instance

.Prerequisites
The {med-pattern} is successfully installed in the relevant namespace.

.Procedure

. Navigate to the *Operators* → *Installed Operators* page.

. Click the installed *{validated-patterns-op}*.

. Under the *Details* tab, in the *Provided APIs* section, in the
*Pattern* box, click *Create instance* that displays the *Create Pattern* page.

. On the *Create Pattern* page, select *Form view* and enter information in the following fields:

** *Name* - A name for the pattern deployment that is used in the projects that you created.
** *Labels* - Apply any other labels you might need for deploying this pattern.
** *Cluster Group Name* - Select a cluster group name to identify the type of cluster where this pattern is being deployed. For the {med-pattern}, `hub` is correct unless you updated it in `values-global.yaml` above.
+
To know the cluster group name for the patterns that you want to deploy, check the relevant pattern-specific requirements.
. Expand the *Git Config* section to reveal the options and enter the required information.
. Leave *In Cluster Git Server* unchanged. 
.. Change the *Target Repo* URL to your forked repository URL. For example, change `+https://github.com/validatedpatterns/<pattern_name>+` to `+https://github.com/<your-git-username>/<pattern-name>+`
.. Optional: You might need to change the *Target Revision* field. The default value is `HEAD`. However, you can also provide a value for a branch, tag, or commit that you want to deploy. For example, `v2.1`, `main`, or a branch that you created, `my-branch`.
. Click *Create*.
+
[NOTE]
====
A pop-up error with the message "Oh no! Something went wrong." might appear during the process. This error can be safely disregarded as it does not impact the installation of the {med-pattern}. Use the Hub ArgoCD UI, accessible through the nines menu, to check the status of ArgoCD instances, which will display states such as progressing, healthy, and so on, for each managed application. The Cluster ArgoCD provides detailed status on each application, as defined in the clustergroup values file.
====

The {rh-gitops} Operator displays in list of *Installed Operators*. The {rh-gitops} Operator installs the remaining assets and artifacts for this pattern. To view the installation of these assets and artifacts, such as {rh-rhacm-first}, ensure that you switch to *Project:All Projects*.

Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu. The `xraylab-database` project  appears stuck in a `Degraded` state. This is the expected behavior when installing using the OpenShift Container Platform console.

* To resolve this you need to run the following to load the secrets into the vault:
+
[source,terminal]
----
$ ./pattern.sh make load-secrets
----
+
[NOTE]
====
You must have created a local copy of the secret values file by running the following command:

[source,terminal]
----
$ cp values-secret.yaml.template ~/values-secret-medical-diagnosis.yaml
----
====

The deployment will not take long but it should deploy successfully.

Alternatively you can deploy the {med-pattern} pattern by using the command line script `pattern.sh`. 

[id="deploying-cluster-using-patternsh-file"]
== Deploying the cluster by using the pattern.sh file

To deploy the cluster by using the `pattern.sh` file, complete the following steps:

. Log in to your cluster by running the following command:
+
[source,terminal]
----
$ oc login
----
+
Optional: Set the `KUBECONFIG` variable for the `kubeconfig` file path:
+
[source,terminal]
----
$ export KUBECONFIG=~/<path_to_kubeconfig>
----

. Deploy the pattern to your cluster. Run the following command:
+
[source,terminal]
----
$ ./pattern.sh make install
----

. Verify that the Operators have been installed.
 .. To verify, in the OpenShift Container Platform web console, navigate to *Operators → Installed Operators* page.
 .. Check that the *Red Hat OpenShift GitOps Operator* is installed in the `openshift-operators` namespace and its status is `Succeeded`.
. Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu. 
+
image::../../images/medical-edge/medical-diags-overview.png[link="/images/medical-edge/medical-diags-overview.png"]

As part of installing by using the script `pattern.sh` pattern, HashiCorp Vault is installed. Running `./pattern.sh make install` also calls the `load-secrets` makefile target. This `load-secrets` target looks for a YAML file describing the secrets to be loaded into vault and in case it cannot find one it will use the `values-secret.yaml.template` file in the git repository to try to generate random secrets.

For more information, see section on https://validatedpatterns.io/secrets/vault/[Vault].

.Verification 

To check the various applications that are being deployed, you can view the progress of the {rh-gitops-short} Operator.

[IMPORTANT]
====
Examine the `medical-diagnosis-hub` ArgoCD instance. You can track all the applications for the pattern in this instance.
====

. Check that all applications are synchronized. There are thirteen different ArgoCD `applications` that are deployed as part of this pattern.