Deploying Ottehr

Deploying Ottehr involves four main steps:

  • deploying the frontend of the patient website
  • deploying the backend of the patient website
  • deploying the frontend of the staff website
  • deploying the backend of the staff website

You can do these deployments in any order. We recommend deploying the patient website backend first, because the frontend relies on the backend.

This guide shares how to deploy the frontend using Amazon Web Services (S3). If you prefer to use another host you can.

ℹ️
Please read the guide Developing and Building Apps before storing patient health information on Oystehr

Environments

If you just want to experiment with Ottehr and don't need to deploy it, you can do that. Follow the steps in the Ottehr readme to set it up on your computer.

If you are ready to deploy Ottehr we recommend having a few different environments with each having a separate Oystehr Project. For each environment, you may prefer to have different deployments. You can create new projects in the Oystehr developer console.

For example, you may want to have different intake websites on development.ottehr-intake.example.com and testing.ottehr-intake.example.com and each will have its own Oystehr Project so the resources from one project are not connected to another.

In this guide we will set up a development environment. The process for setting up other environments is similar.

CLI deployments

To begin, we recommend deploying using a command-line interface (CLI). You can also set up deployments using services, and we have documentation on deploying with GitHub Actions.

Patient Portal / Website

Frontend

  1. Set up AWS S3 Bucket for hosting the front end
    • Go to AWS S3 (opens in a new tab)
    • Create a bucket named patient.YOUR_DOMAIN (for example patient.example.com). If you don't have a domain, you can choose any name.
    • Uncheck Block all public access
    • Acknowledge that the bucket will be public
    • Click Create Bucket button
    • Once bucket is created, in Properties tab, scroll down to Static web hosting, click Edit, choose Enable, and set both Index document and Error document to index.html.
    • In Permissions tab, scroll down to Bucket policy, click Edit, and set the following bucket policy, note the one change: 
      {
  "Version": "2012-10-17",
  "Statement": [
      {
          "Sid": "PublicReadGetObject",
          "Effect": "Allow",
          "Principal": "*",
          "Action": "s3:GetObject",
          "Resource": "arn:aws:s3:::YOUR_INTAKE_BUCKET_NAME/*"
      }
  ]
}
  2. Set up an AWS CloudFront website distribution endpoint
    • Go to AWS CloudFront (opens in a new tab) and create a distribution.
    • In the origin domain input select the bucket you created in step 1.
    • Select use website endpoint. Set the policy to Redirect HTTP to HTTPS.
    • Click Create Distribution. Note the distribution domain name, for example EXAMPLE.cloudfront.net, and the ID.
  3. Configure application redirect URLs
    • In the Oystehr Console (opens in a new tab), from Service menu, select App service.
    • Choose the application called Ottehr Urgent Care Intake
    • Set each of the URLs to the domain name from step 2 and save it.
  4. Update configuration for your application
    • Create a file in packages/telemed-intake/app/env called .env.development.
    • Copy .env.local and change the following changes:
      • Set the VITE_APP_IS_LOCAL env variable to false
      • Ensure that VITE_APP_PROJECT_API_URL is pointing to production, rather than local URL (for envoking zambdas)
      VITE_APP_IS_LOCAL=false
...
...
VITE_APP_PROJECT_API_URL='https://project-api.zapehr.com/v1'
    • This part can only be completed after backend is deployed: for each of the zambda references (variable names ending in ZAMBDA_ID), replace the zambda name with the zambda ID from Backend deployment. Note: until backend is deployed and this step is completed, the site will not function
  5. Create AWS CLI credentials to run the deploy scripts
    • Go to AWS IAM (opens in a new tab), Users, then select your user, Security credentials
    • Click Create access key
    • Click Command Line Interface (CLI) and create
    • Create/update your AWS credentials at ~/.aws/credentials
    • Add the following lines with the response from the above step 
      [ottehr]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_ACCESS_KEY_SECRET
    • Save
      • Note: if you have multiple AWS profiles in your local environment, an AWS_PROFILE environment variable will indicate the default profile you would be using.
  6. Update the deployment scripts (packages/telemed-intake/app/package.json) and deploy
    • In packages/telemed-intake/app/package.json, make a few changes.
    • Change s3://telemed.user.com to the use the S3 bucket name from step above
    • Add the ID of your CloudFront instance, from distribution config above, CLOUDFRONT_ID=. Note that the ID is different from the domain name.
    • In packages/telemed-intake/app do npm run ci-deploy:development
    • Load the CloudFront domain name in the browser

Backend

  1. Update the app configuration
    • Create a file in packages/telemed-intake/zambdas/env called .env.development.
    • Copy .env.local and change the following: 
      "ENVIRONMENT": "development"
  2. Run the zambdas deployment
    • In packages/telemed-intake/zambdas do npm run deploy-zambdas development
      • Note: rember to note the zambda id values of all deployed zambdas and update the front end deployment step with proper values
      • If you use Windows Subsystem for Linux (WSL) or Ubuntu, you may encounter an error when running above command: zip|unzip command not found. If so, run apt-get install zip unzip.
    • In packages/telemed-intake/zambdas do npm run setup-zapehr-secrets development
  3. Test the backend with 
    curl 'https://project-api.zapehr.com/v1/zambda/YOUR_GET_LOCATION_ZAMBDA_ID/execute-public' \
--data-raw '{"locationSlug": "testing"}'
    You should get a response with information.

EHR / Staff Website

Frontend

  1. Set up AWS S3 Bucket for hosting the front end
    • Go to AWS S3 (opens in a new tab)
    • Create a bucket named patient.YOUR_DOMAIN (for example patient.example.com). If you don't have a domain, you can choose any name.
    • Uncheck Block all public access
    • Acknowledge that the bucket will be public
    • Click Create Bucket button
    • Once bucket is created, in Properties tab, scroll down to Static web hosting, click Edit, choose Enable, and set both Index document and Error document to index.html.
    • In Permissions tab, scroll down to Bucket policy, click Edit, and set the following bucket policy, note the one change: 
      {
  "Version": "2012-10-17",
  "Statement": [
      {
          "Sid": "PublicReadGetObject",
          "Effect": "Allow",
          "Principal": "*",
          "Action": "s3:GetObject",
          "Resource": "arn:aws:s3:::YOUR_EHR_BUCKET_NAME/*"
      }
  ]
}
  2. Set up an AWS CloudFront website distribution endpoint
    • Go to AWS CloudFront (opens in a new tab) and create a distribution.
    • In the origin domain input select the bucket you created in step 1.
    • Select use website endpoint. Set the policy to Redirect HTTP to HTTPS.
    • Click Create Distribution. Note the distribution domain name, for example EXAMPLE.cloudfront.net, and the ID.
  3. Configure application redirect URLs
    • In the Oystehr Console (opens in a new tab), from Service menu, select App service.
    • Choose the application called Ottehr Urgent Care Intake
    • Set each of the URLs to the domain name from step 2 and save it.
  4. Update configuration for your application
    • Create a file in packages/telemed-ehr/app/env called .env.development.
      • Copy .env.local and change the following:
      VITE_APP_IS_LOCAL=false
VITE_APP_PROJECT_API_URL='https://project-api.zapehr.com/v1'
    • This part can only be completed after backend is deployed: for each of the zambda references (variable names ending in ZAMBDA_ID), replace the zambda name with the zambda ID from Backend deployment. Note: until backend is deployed and this step is completed, the site will not function
  5. Ensure your AWS Credentials are setup as decribed in the step above
  6. Update the deployment scripts (packages/telemed-intake/app/package.json) and deploy
    • Change s3://ehr.user.com to the name of the bucket from S3 config above
    • Add the ID of your CloudFront instance, from config above, after CLOUDFRONT_ID=. Note that the ID is different from the domain name.
    • In packages/telemed-ehr/app do npm run ci-deploy:development
    • Load your CloudFront domain name in the browser

Backend

  1. Update the app configuration

    • Create a file in packages/telemed-ehr/zambdas/env called .env.development.
    • Copy .env.local and change the following: 
      "ENVIRONMENT": "development"

  2. Run the zambdas deployment

    • In packages/telemed-ehr/zambdas do npm run deploy-zambdas development
    • In packages/telemed-ehr/zambdas do npm run setup-zapehr-secrets development
    • Test the backend with
    curl 'https://project-api.zapehr.com/v1/zambda/YOUR_GET_APPOINTMENTS_ZAMBDA_ID/execute' \
--data-raw '{"locationSlug": "testing"}'

    • You should get a 403 response because this is an authenticated zambda and you called it without a token.

    • Try calling it again with a token and a project ID from the developer console (opens in a new tab):

      curl 'https://project-api.zapehr.com/v1/zambda/YOUR_GET_APPOINTMENTS_ZAMBDA_ID/execute' \
-H "x-zapehr-project-id": "YOUR_OYSTEHR_PROJECT_ID"
-H "Authorization: Bearer YOUR_OYSTEHR_PROJECT_TOKEN" \
--data-raw '{"locationSlug": "testing"}'

    You should get back a list of appointments. If you haven't made any appointments, the list will be empty.

GitHub deployments

Once this setup is complete, you can deploy your project using GitHub Actions. This will make the deployment process simpler.

We are still working on our documentation for deploying with GitHub.

Customizing PaperworkStoring SOAP Notes