Docker: improve instructions for testing the backend with docker (#10953

)

- fix syntax of docker compose command
- WSL note
- Running the 'app.jar' image
- Docker Desktop tip
- put WSL note in main readme
- fix links
- make "docker build" steps more prominent on main readme

---------

Co-authored-by: Denis Papp <[email protected]>

README.md

@@ -16,14 +16,36 @@ See [LICENSE](./LICENSE)
 cBioPortal consists of several components, please read the [Architecture docs](https://docs.cbioportal.org/architecture-overview/) to figure out what repo would be relevant to edit. If you e.g. only want to make frontend changes, one can directly edit [the frontend repo](https://github.com/cbioportal/cbioportal-frontend) instead. Read the instructions in that repo for more info on how to do frontend development. This repo only contains the backend part. Before editing the backend, it's good to read the [backend code organization](docs/Backend-Code-Organization.md).
 
 ### Local Development
+
+This section provides a summary. For Quick Start instructions, or for more additional information, please see [Deploy with Docker](https://docs.cbioportal.org/deployment/docker/)
+
 #### What MySQL database to use
-We recommend to set up a MySQL database using [Docker Compose](https://github.com/cBioPortal/cbioportal-docker-compose). It's useful to know how to do this as it allows you to import any dataset of your choice. For debugging production issues, we also have a database available with all the data on https://cbioportal.org that one can connect to directly. Please reach out on slack to get the credentials.
+We recommend to set up a MySQL database automatically using [Docker Compose](https://github.com/cBioPortal/cbioportal-docker-compose). It's useful to know how to do this as it allows you to import any dataset of your choice. For debugging production issues, we also have a database available with all the data on https://cbioportal.org that one can connect to directly. Please reach out on slack to get the credentials.
+
+#### Deploy your development image inside Docker Compose
+The easiest option is to deploy your development image directly into the [docker-compose](https://github.com/cBioPortal/cbioportal-docker-compose/blob/5da068f0eb9b4f42db52ab5e91321b26a1826d7a/docker-compose.yml#L6) file. 
+
+1. From the cbioportal repo, build the image:
+```
+docker build -t cbioportal/cbioportal:my-dev-cbioportal-image -f docker/web-and-data/Dockerfile .
+```
+2. From the cbioportal-docker-compose repo, change the [env file](https://github.com/cBioPortal/cbioportal-docker-compose/blob/master/.env) to use your image (e.g. **cbioportal/cbioportal:my-dev-cbioportal-image**).
+
+3. Run the containers.
+```
+docker compose up
+```
+
+4. The app will be visible at http://localhost:8080.
+
+For more information, please see [Deploy with Docker](https://docs.cbioportal.org/deployment/docker/#building-cbioportal).
 
 #### Command Line
-If you want to run the cBioPortal web app from the command line please follow these instructions. First, we want to make sure that all ports are open for the services set up through [docker compose](https://github.com/cBioPortal/cbioportal-docker-compose) (i.e. not just accessible to other containers within the same Docker Compose file). To do so, in the [docker compose repo](https://github.com/cBioPortal/cbioportal-docker-compose) run:
+
+If you want to instead run the cBioPortal web app from the command line please follow these instructions. First, we want to make sure that all ports are open for the services set up through [docker compose](https://github.com/cBioPortal/cbioportal-docker-compose) (i.e. not just accessible to other containers within the same Docker Compose file). To do so, in the [docker compose repo](https://github.com/cBioPortal/cbioportal-docker-compose) run:
 
 ```
-docker compose -f docker-compose.yml -f open-ports.yml up
+docker compose -f docker-compose.yml -f dev/open-ports.yml up
 ```
 This should open the ports. Now we are ready to run the cBioPortal web app locally. You can compile the backend code with:
 
@@ -48,17 +70,7 @@ java -Xms2g -Xmx4g \
 
 The app should now show up at http://localhost:8080.
 
-#### Deploy your development image inside Docker Compose
-Another option is to deploy your development image directly into the [docker-compose](https://github.com/cBioPortal/cbioportal-docker-compose/blob/5da068f0eb9b4f42db52ab5e91321b26a1826d7a/docker-compose.yml#L6) file. First build the image like this
-
-```
-docker build -t cbioportal/cbioportal:my-dev-cbioportal-image -f docker/web-and-data/Dockerfile .
-```
-
-Then change the [env file](https://github.com/cBioPortal/cbioportal-docker-compose/blob/master/.env) to use `cbioportal/cbioportal:my-dev-cbioportal-image`.
-
-### Local Development
-
+### Dev Database
 
 Note: internally we have a dev database available with the public data set that one can connect to directly. Please reach out on slack to get the credentials. It is usually best to use a small test dataset, but if a copy of the production database is necessary for e.g. fixing a bug specific to production data that can be useful.
 

docs/deployment/docker/README.md

@@ -3,10 +3,12 @@
 ## Prerequisites
 
 Docker provides a way to run applications securely isolated in a container, packaged with all its dependencies and libraries.
-To learn more on Docker, kindly refer here: [Docker overview](https://docs.docker.com/engine/docker-overview/).
+To learn more on Docker, please see [Docker overview](https://docs.docker.com/engine/docker-overview/).
 
 Make sure that you have the latest version of Docker installed on your machine. [Get latest version](https://www.docker.com/products/overview#/install_the_platform)
 
+> **WSL**: Make sure to use [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/). Installing Docker in Ubuntu will not work.
+
 [Notes for non-Linux systems](notes-for-non-linux.md)
 
 ## Usage instructions
@@ -91,6 +93,15 @@ You can list all containers running on your system with
 docker ps -a
 ```
 
+To shut down the containers:
+
+```
+docker compose down
+```
+
+> **Tip:** If you are using [Docker Desktop](https://www.docker.com/products/docker-desktop/), detached mode is
+the preferred way to run as it provides a UI for listing the containers and interfacing with them.
+
 #### Step 2 - Import Studies
 To import studies you can run:
 
@@ -142,6 +153,39 @@ For more uses of the cBioPortal image, see [this file](example_commands.md)
 To Dockerize a Keycloak authentication service alongside cBioPortal,
 see [this file](using-keycloak.md).
 
+## Building cBioPortal 
+
+If you need to build the cBioPortal backend to a docker image, you can use the following command from the cbioportal repo. 
+
+```
+docker build -t cbioportal/cbioportal:my-dev-cbioportal-image -f docker/web-and-data/Dockerfile .
+```
+
+Change the [env file](https://github.com/cBioPortal/cbioportal-docker-compose/blob/master/.env) in the cbioportal-docker-compose repo to reference your image.
+
+```
+DOCKER_IMAGE_CBIOPORTAL=cbioportal/cbioportal:my-dev-cbioportal-image
+```
+
+Note that the above command will deploy the repo as loose files. If you would like to build to a single executable app.jar, you can use the **web** configuration:
+
+```
+docker build -t cbioportal/cbioportal:my-dev-cbioportal-image -f docker/web/Dockerfile .
+```
+
+In this case, the default [docker-compose.yml](https://github.com/cBioPortal/cbioportal-docker-compose/blob/master/docker-compose.yml) may not work. If you get an error about missing _PortalApplication_, it must be configured to launch the app.jar instead. 
+
+```
+java -Xms2g -Xmx4g -jar /cbioportal-webapp/app.jar -spring...
+```
+
+There may be a [docker-compose.web.yml](https://github.com/cBioPortal/cbioportal-docker-compose/blob/master/docker-compose.web.yml) you can use instead of modifying the above.
+
+```
+docker compose -f docker-compose.web.yml up -d
+```
+
+
 ## Uninstalling cBioPortal ##
 ```
 docker compose down -v --rmi all