Deploying Leaf on Docker

[artgoldberg]

I am working on deploying Leaf on Docker on my laptop. Are the files on the docker-new branch that refer to Docker but were last updated in 2019 still current? They are:

leaf/scripts/resetdb.sh
leaf/docs/docker.md
leaf/docs/.env.example
leaf/docs/leafdb.md
leaf/docker-compose.yml
leaf/src/ui-client/README.md

Thanks
Arthur

Mount Sinai

[ndobb]

Hi @artgoldberg thanks for your question. The docker-new branch is still a work in progress but fortunately you only should need to work with a single file, containerize-leaf.sh, which is designed to automatically deploy the Leaf API along with a test SQL Server container with dummy data (which you can subsequently replace).

As an aside, we are not using docker-compose because recent versions of the SQL Server image are preventing the loading of data in SQL scripts during the docker build process, and we have not been able to find a proper workaround. The containerize-leaf.sh script accomplishes the same thing but with shell commands.

To run Leaf using that script:

1. git clone the Leaf repo
2. Create your JWT signing key and certificate https://leafdocs.rit.uw.edu/installation/installation_steps/3_jwt/
3. Configure your environment variables (any method to do so is fine; the containers just need to read them in). https://leafdocs.rit.uw.edu/installation/installation_steps/7_env/
4. Review the variables in the first few lines of containerize_leaf.sh:
   Set SA_PASSWORD to whatever password you'd like to use. This must match the password you use in your LEAF_APP_DB and LEAF_CLIN_DB variables.
5. Run ./containerize_leaf.sh from the Leaf root directory. This will setup the databases and Leaf API.
6. The last step is to run the client. To do so from/leaf/src/ui-client run npm start.

[artgoldberg]

Hello Nic and colleagues

I have a few related questions about the Leaf Docker deployment.

I'm confused by the difference between the Docker deployment in containerize-leaf.sh and step 8A of the bare metal deployment.

Let's just consider Linux. The official architecture includes Apache, the Leaf API, the App (Leaf) DB and a Clinical DB. But the Docker deployment does not include Apache. I also note that the API appears to use .NET core to handle the SAML authentication which the architecture diagram indicates passes through Apache. Is Apache simply serving as a caching proxy? And does the Docker deployment assume that an Apache server runs outside of it? If so, would it make sense to also deploy Apache in a Docker container and use Docker compose to assemble the Leaf API and Apache? Apache images are available on Docker hub.

Thanks
Arthur

[ndobb]

Hi @artgoldberg,

Regarding containerize-leaf.sh, I should have been more clear that we envision that script only being for development / testing, essentially as a fast means of standing Leaf up to see how it works. The script makes many assumptions that don't make sense in a production deployment.

Regarding SAML2, Apache, .NET Core, and authentication, we do leverage .NET Core and what we call the access token to validate user calls to the API using middleware (see example here). We use this to facilitate federated Leaf deployments, as otherwise Apache would prevent users from different sites from using one another's Leaf APIs.

So at a high level you generally have 2 options:

1. Use Apache to protect the entire API surface, so users requesting the Leaf client from their browser (e.g. https://leaf.<your_site>.org) and users actively using Leaf (with API calls to https://leaf.<your_site>.org/api/) would all need to be "let in the door" by Apache.

   In this scenario, both Apache and the Leaf API will validate user requests, so you have some redundant security (in a good sense). This should however not be done in a federated deployment.

   We use this method at UW for our main Leaf instance, as it is not federated, and protecting the entire API surface is fairly straightforward.

2. Use Apache to protect only https://leaf.<your_site>.org and https://leaf.<your_site>.org/api/user. This is the recommended deployment in a federated scenario, as each user's home Leaf instance will grant the user an access token, which is subsequently used for API calls to federated Leaf instances - which would be validated by .NET Core / the Leaf API, rather than Apache.

   In the 2nd scenario, Apache does indeed act mostly as a caching proxy once users are in the door.

   We use this method at UW for several federated Leaf instances we maintain (not querying our EDW, but other disparate data sources)

We document these cases at https://leafdocs.rit.uw.edu/installation/installation_steps/9_saml2/#route-protection-setup.

Regarding deploying Apache in a Docker container, I'd lean on @jprosser and @mh2727 to weight in on that. My understanding is that we don't do so at UW, though I can't speak to the reasons why.

[artgoldberg]

Thanks @ndobb , that's very helpful.

Regards @artgoldberg

[mh2727]

Hi @artgoldberg.

We generally don't use Docker in our infrastructure and so we have not installed Apache to run in it. If your infrastructure runs in a Docker container system, then by all means, feel free to use it.

--
Mehadi Hassan

[artgoldberg]

Thanks @mh2727 . Talk to you later.