Added Dockerfile and Dockerfile.upgrade.matlab-proxy for installing/upgrading matlab-proxy in docker images

Author: diningPhilosopher64

README.md

@@ -112,7 +112,8 @@ The following options are available in the status panel (some options are only a
 | Help | Open a help pop-up for a detailed description of the options.|
 
 ## Examples
-* For usage in a Docker container, see this [Dockerfile](./examples/Dockerfile) and its [README](./examples/README.md).
+* For installing/usage in a Docker container, see this [Dockerfile](./examples/Dockerfile) and its [README](./examples/README.md).
+* For upgrading **matlab-proxy** in an existing Docker image, see this [Dockerfile.upgrade.matlab-proxy](./examples/Dockerfile.upgrade.matlab-proxy) and its [README](./examples/README.md#upgrading-matlab-proxy-package-in-a-docker-image).*
 * For usage in a Jupyter environment, see [jupyter-matlab-proxy](https://github.com/mathworks/jupyter-matlab-proxy).
 
 ## Limitations

examples/Dockerfile

@@ -1,12 +1,21 @@
-# Copyright 2021 The MathWorks, Inc.
-# Enables access to the MATLAB Desktop from a web browser
+# Copyright 2021-2022 The MathWorks, Inc.
+# This Dockerfile showcases how to add matlab-proxy into an existing container image with MATLAB installed.
 
-# Based on the publicly available MATLAB image
-FROM mathworks/matlab:r2021b
+# matlab-proxy enables access to the MATLAB Desktop from a web browser
+
+# Sample build command:
+# docker build  --build-arg IMAGE_WITH_MATLAB=my_custom_image_with_matlab \
+#               -f Dockerfile -t my_custom_image_with_matlab_proxy .
+
+# Sample run command:
+# docker run --rm -it -p 8888:8888 --shm-shared=512M my_custom_image_with_matlab_proxy
+
+ARG IMAGE_WITH_MATLAB=mathworks/matlab:r2021b
+
+FROM ${IMAGE_WITH_MATLAB}
 
 USER root
 
-# The container already has python3 (v3.8.5) installed
 # Install dependencies for matlab-proxy
 RUN DEBIAN_FRONTEND=noninteractive && \
     apt-get update && apt-get install --no-install-recommends -y \
@@ -17,12 +26,12 @@ RUN DEBIAN_FRONTEND=noninteractive && \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
-RUN python -m pip install matlab-proxy
+RUN python3 -m pip install matlab-proxy
 
 # Set environment variables used by integration
 # MATLAB should then become accessible on http://localhost:8888/matlab/index.html
 ENV MWI_APP_PORT=8888
 ENV MWI_BASE_URL="/matlab"
 
 USER matlab
-ENTRYPOINT ["matlab-proxy-app"]
+ENTRYPOINT ["matlab-proxy-app"]

examples/Dockerfile.upgrade.matlab-proxy

@@ -0,0 +1,20 @@
+# Copyright 2021-2022 The MathWorks, Inc.
+# This Dockerfile showcases how to upgrade the matlab-proxy python package 
+# in an existing container image which has both MATLAB and matlab-proxy installed
+
+# Sample build command:
+# docker build  --build-arg IMAGE_WITH_MATLAB_PROXY=my_custom_image_with_matlab_proxy \
+#              -f Dockerfile.upgrade.matlab-proxy -t my_custom_image_with_matlab_proxy .
+
+# Sample run command:
+# docker run --rm -it -p 8888:8888 --shm-shared=512M my_custom_image_with_matlab_proxy 
+
+ARG IMAGE_WITH_MATLAB_PROXY=mathworks/matlab:r2022a
+
+FROM ${IMAGE_WITH_MATLAB_PROXY}
+
+USER root
+
+RUN python3 -m pip install --upgrade matlab-proxy
+
+USER matlab

examples/README.md

@@ -1,12 +1,73 @@
 # Building matlab-proxy for use in a Docker Container
 
-Builds a docker image based on `mathworks/matlab` with the **matlab-proxy** integrated.
+[Dockerfile](./Dockerfile) adds **matlab-proxy** package to an existing docker image with MATLAB
+
+Supply the name of your custom image with the docker build arg `IMAGE_WITH_MATLAB`. The default value for this build argument is `mathworks/matlab:r2021b`
+
+**NOTE:** Releases of MATLAB docker images starting from `r2022a` will have **matlab-proxy** integrated by default. 
+
+This [Dockerfile](./Dockerfile) can be used as a reference for integrating **matlab-proxy** into your custom images or older MATLAB docker images.
 
 ## Build image
 ```bash
-docker build -t <image_name> .
+ docker build  --build-arg IMAGE_WITH_MATLAB=my_custom_image_with_matlab_installed \
+               -f Dockerfile -t my_custom_image_with_matlab_proxy .
+```
+## Upgrading matlab-proxy package in a docker image
+
+To keep your docker images updated with the latest release of **matlab-proxy** package, you can either:
+* Update using a Dockerfile
+* Update using `docker commit` command
+
+**NOTE:** Updating the package using a Dockerfile is recommended as it helps in keeping track of the changes made to docker images.
+### Approach 1: Using a Dockerfile
+`Dockerfile.upgrade.matlab-proxy` showcases how to upgrade an existing installation of **matlab-proxy** package in a docker image.
+
+
+```bash
+ docker build  --build-arg IMAGE_WITH_MATLAB_PROXY=my_custom_image_with_matlab_proxy \
+               -f Dockerfile.upgrade.matlab-proxy -t my_custom_image_with_matlab_proxy .
+```
+
+### Approach 2: Using `docker commit` command
+Launch your container with `--entrypoint /bin/bash` flag 
+```bash
+$  docker run --rm -it --shm-size=512M --entrypoint /bin/bash my_custom_image_with_matlab_proxy:latest 
+```
+
+Once in the container, change to root user and upgrade the package
+```bash
+root@6624c4893071:/home/matlab/Documents/MATLAB: sudo su
+root@6624c4893071:/home/matlab/Documents/MATLAB: python3 -m pip install --upgrade matlab-proxy
 ```
-## Run image
+
+In a new terminal, grab the running container's ID and use the `docker ps` command
+```bash
+$ docker ps
+
+CONTAINER ID        IMAGE                                        COMMAND                CREATED             STATUS              PORTS                          NAMES
+6624c4893071        my_custom_image_with_matlab_proxy:latest     "/bin/run.sh -shell"   2 minutes ago       Up 2 minutes        5901/tcp, 6080/tcp, 8888/tcp   laughing_buck
+
+```
+In this case, the container ID is  `6624c4893071`. Now commit:
+```bash
+$ docker commit 6624c4893071 my_custom_image_with_matlab_proxy:latest
+```
+
+Stop the running container by exiting the shell
+```bash
+root@6624c4893071::/home/matlab/Documents/MATLAB: exit
+matlab@6624c4893071::/home/matlab/Documents/MATLAB: exit
+```
+
+## Run the docker container
+```bash
+docker run -it -p 8888:8888 --shm-shared=512M my_custom_image_with_matlab_proxy:latest 
+```
+
+For modifying the behaviour of **matlab-proxy**, you can pass environment variables at run time
 ```bash
-docker run -it -p 8888:8888 -t <image_name>
+docker run -it -p 8888:8888 -e MLM_LICENSE_FILE="port@hostname" \
+            --shm-shared=512M my_custom_image_with_matlab_proxy:latest 
 ```
+For a complete list of environment variables that can be passed, see [Advanced-Usage.md](../Advanced-Usage.md)