Skip to content

Latest commit

 

History

History
155 lines (112 loc) · 6.65 KB

deploy.md

File metadata and controls

155 lines (112 loc) · 6.65 KB
Raw

How To Deploy a Federated Access Playground

This document is the quick-start guide for deploying Federated Access components in a test environment and getting comfortable with how the system works. This is referred to as a "playground" environment for trying out the use of passports and access policies with test personas.

Note: This environment is only for testing with synthetic and public datasets. For more information on best practices for production environments, see Productionization Best Practices.

Before you start

To deploy federated access you must create a Google Cloud project. This project will include the following:

  • A sample dataset hosted as a file in a GCS bucket
  • An instantiation of the IC and DAM services
  • A playground passport broker that issues test passports to predefined personas
  • An IC login test page ("icdemo") and DAM resource request test page ("damdemo")

IMPORTANT: The playground Data Access Manager (DAM) will have control over services within this project, and anyone using the playground can act as an administrator. Therefore, make sure the Google Cloud project being used for the playground is only used for this purpose and does not have access to any other production data or services.

Install Google Cloud SDK

If you haven't already done so on your machine, you will need to install the Google Cloud SDK to use the deploy.bash scripts.

To install the Google Cloud SDK, in your GCP project, run the following command:

gcloud auth application-default login
gcloud auth login

export GCP_USERNAME=<project-admin-account, e.g. [email protected]>
gcloud config set account ${GCP_USERNAME?}

For more information, see the SDK documentation.

Install the latest release from GitHub

If you haven't already done so, install git and related tools as per the Github's Set up Git documentation.

If this is your first time installing Federated Access components, you will need to clone the repository as follows:

git clone https://github.com/GoogleCloudPlatform/healthcare-federated-access-services.git

Tip: If you are less familiar with git, then Git Basics is a good starting point to understanding the command line interface.

Then checkout the latest release:

cd healthcare-federated-access-services
git pull
export FA_VERSION=$(git describe --tags)
git checkout ${FA_VERSION?}

Important: It is recommended to checkout git's release tags (as per FA_VERSION above) instead of master as releases have typically gone through additional testing processes.

Create a test Google Cloud deployment of Federated Access services

To create a Google Cloud project, do the following:

  1. Create a GCP project using the GCP Developer Console.

  2. To prepare the new project with all the service dependencies that Federated Access components need, execute the following:

    ./prepare_project.bash -p <gcp-project-id>

    Note: Learn about Project Preparation here.

  3. Run the following setup script to deploy components with default settings that can be tested:

    ```
export PROJECT=<gcp-project-id>
./deploy.bash
```

    Note: You can run ./deploy.bash -i the first time to have the script pause between steps where you can look for recent errors and break the script (CTRL-C) if you do not wish to proceed.

    This script configures the following:

For more information on deploying federated access services, see deploy.bash and run deploy.bash -h for help.

Configuration details are also contained within the following files:

Test with test client

After installing the test Google Cloud deployment as documented above, you can use the test playground features to try the IC and DAM components.

In a browser, open https://icdemo-dot-${YOUR_PROJECT_ID}.appspot.com/test and https://damdemo-dot-${YOUR_PROJECT_ID}.appspot.com/dam/test.

Note: if you supplied an environment namespace via deploy.bash -e <environment>, then you will need to visit these pages instead: https://icdemo-${ENVIRONMENT}-dot-${YOUR_PROJECT_ID}.appspot.com/test and https://damdemo-${ENVIRONMENT}-dot-${YOUR_PROJECT_ID}.appspot.com/dam/test.

For example, deploy.bash -e staging -p my-project would create an icdemo page of: https://icdemo-staging-dot-my-project.appspot.com/test.

Environment variables for the deploy script

It may be useful to create a wrapper script to control some settings to deploy.bash. Here is an example my_deploy.bash:

export PROJECT=<my-gcp-project>
export DAM_CONFIG=${CUSTOM_CONFIG_DIR?}/dam
export IC_CONFIG=${CUSTOM_CONFIG_DIR?}/ic

./deploy.bash "$@"

Note: You can still pass flags and parameters through this script to deploy.bash, and -p <project> can still override the PROJECT environment variable.