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.

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 website

Frontend

  1. Go to AWS S3 (opens in a new tab)
    1. Create a bucket named telemed-intake.YOUR_DOMAIN (for example telemed-intake.example.com). If you don't have a domain, you can choose any name.
    2. Uncheck Block all public access
    3. Acknowledge that the bucket will be public
    4. Under properties, scroll down to Static web hosting, click Edit, choose Enable, and set both Index document and Error document to index.html.
    5. Under permissions, 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. 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. Go on the Oystehr Console (opens in a new tab) and go to the Applications Service. Choose the application called Ottehr Urgent Care Intake and set each of the URLs to the domain name from step 2 and save it.
  4. Create a file in packages/telemed-intake/app/env called .env.development.
    1. Copy .env.local and change the following:
      VITE_APP_IS_LOCAL=false
      VITE_APP_PROJECT_API_URL='https://project-api.zapehr.com/v1'
    2. For each of the variable names ending in ZAMBDA_ID, replace it with the ID of the Zambda with that name -- if you haven't yet deployed your backend and want to, go to the next step. If you prefer to deploy the frontend without the backend working, you can but endpoints on the website will not function.
  5. Go to AWS IAM (opens in a new tab), Users, then select your user, Security credentials
    1. Click Create access key
    2. Click Command Line Interface (CLI) and create
    3. Create/update your AWS credentials at ~/.aws/credentials
    4. 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
    5. Save
  6. In packages/telemed-intake/app/package.json, make a few changes.
  7. Change s3://telemed-intake.user.com to the name from step 1
  8. Add the ID of your CloudFront instance from step 2 after CLOUDFRONT_ID=. Note that the ID is different from the domain name.
  9. In packages/telemed-intake/app do npm run ci-deploy:development
  10. Load the CloudFront domain name in the browser

Backend

  1. Create a file in packages/telemed-intake/zambdas/env called .env.development.
    1. Copy .env.local and change the following:
      "ENVIRONMENT": "development"
  2. In packages/telemed-intake/zambdas do npm run deploy-zambdas development
  3. In packages/telemed-intake/zambdas do npm run setup-zapehr-secrets development
  4. 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.

Staff website

Frontend

  1. Go to AWS S3 (opens in a new tab)
    1. Create a bucket named telemed-ehr.YOUR_DOMAIN (for example telemed-ehr.example.com). If you don't have a domain, you can choose any name.
    2. Uncheck Block all public access
    3. Acknowledge that the bucket will be public
    4. Under properties, scroll down to Static web hosting, click Edit, choose Enable, and set both Index document and Error document to index.html.
    5. Under permissions, 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. 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. Go on the Oystehr Console (opens in a new tab) and go to the Applications Service. Choose the application called Ottehr EHR and set each of the URLs to the domain name from step 2 and save it -- note the client ID.
  4. Create a file in packages/telemed-ehr/app/env called .env.development.
    1. Copy .env.local and change the following:
      VITE_APP_IS_LOCAL=false
      VITE_APP_PROJECT_API_URL='https://project-api.zapehr.com/v1'
    2. For each of the variable names ending in ZAMBDA_ID, replace it with the ID of the Zambda with that name -- if you haven't yet deployed your backend and want to, go to the next step. If you prefer to deploy the frontend without the backend working, you can but endpoints on the website will not function.
  5. If you haven't already set up access to AWS go to AWS IAM (opens in a new tab), Users, then select your user, Security credentials
    1. Click Create access key
    2. Click Command Line Interface (CLI) and create
    3. Create/update your AWS credentials at ~/.aws/credentials
    4. 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
    5. Save
  6. In packages/telemed-ehr/app/package.json, make a few changes.
  7. Change s3://telemed-ehr.user.com to the name from step 1
  8. Add the ID of your CloudFront instance from step 2 after CLOUDFRONT_ID=. Note that the ID is different from the domain name.
  9. In packages/telemed-ehr/app do npm run ci-deploy:development
  10. Load the CloudFront domain name in the browser

Backend

  1. Create a file in packages/telemed-ehr/zambdas/env called .env.development.

    1. Copy .env.local and change the following:
      "ENVIRONMENT": "development"
  2. In packages/telemed-ehr/zambdas do npm run deploy-zambdas development

  3. In packages/telemed-ehr/zambdas do npm run setup-zapehr-secrets development

  4. 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.