Skip to content

Commit c1af423

Browse files
author
Prabhakar Kumar
committed
V1.0 doc
1 parent 564467e commit c1af423

File tree

2 files changed

+51
-53
lines changed

2 files changed

+51
-53
lines changed

‎Advanced-Usage.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Advanced Usage
2+
3+
This page lists some of the advanced manuevers that may be of specific interest to help configure the package for use in your environment.
4+
5+
## Environment Variables
6+
7+
To control the behavior of the MATLAB integration for Jupyter, you can optionally specify the environment variables described in this section. You must specify these variables before starting your Jupyter environment. For example, a network license server can be specified when you start the Jupyter notebook using the command below:
8+
9+
```bash
10+
env MLM_LICENSE_FILE="[email protected]" jupyter notebook
11+
```
12+
13+
The following table describes all the environment variables that you can set to customize the behavior of this integration.
14+
15+
| Name | Type | Example Value | Description |
16+
| ---- | ---- | ------------- | ----------- |
17+
| **MLM_LICENSE_FILE** | string | `"[email protected]"` | When you want to use either a license file or a network license manager to license MATLAB, specify this variable.</br> For example, specify the location of the network license manager to be `123@hostname`.|
18+
| **MWI_BASE_URL** | string | `"/matlab"` | Set to control the base URL of the app. MWI_BASE_URL should start with `/` or be `empty`. |
19+
| **MWI_APP_PORT** | integer | `8080` | Specify the port for the HTTP server to listen on. |
20+
| **MWI_LOG_LEVEL** | string | `"CRITICAL"` | Specify the Python log level to be one of the following `NOTSET`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `CRITICAL`. For more information on Python log levels, see [Logging Levels](https://docs.python.org/3/library/logging.html#logging-levels) .<br />The default value is `INFO`. |
21+
| **MWI_LOG_FILE** | string | `"/tmp/logs.txt"` | Specify the full path to the file where you want the logs to be written. |
22+
| **MWI_WEB_LOGGING_ENABLED** | string | `"True"` | Set this value to `"true"` to see additional web server logs. |
23+
| **MWI_CUSTOM_HTTP_HEADERS** | string |`'{"Content-Security-Policy": "frame-ancestors *.example.com:*"}'`<br /> OR <br />`"/path/to/your/custom/http-headers.json"` |Specify valid HTTP headers as JSON data in a string format. <br /> Alternatively, specify the full path to the JSON file containing valid HTTP headers instead. These headers are injected into the HTTP response sent to the browser. </br> For more information, see the [Custom HTTP Headers](#custom_http_headers) section.|
24+
25+
26+
### Custom HTTP Headers
27+
If the web browser renders the MATLAB Integration for Jupyter with some other content, then the browser could block the integration because of mismatch of `Content-Security-Policy` header in the response headers from the integration.
28+
To avoid this, provide custom HTTP headers. This allows browsers to load the content.
29+
30+
For example, if this integration is rendered along with some other content on the domain `www.example.com`, to allow the browser to load the content, create a JSON file of the following form:
31+
32+
```json
33+
{
34+
"Content-Security-Policy": "frame-ancestors *.example.com:* https://www.example.com:*;"
35+
}
36+
```
37+
Specify the full path to this sample file in the environment variable `MWI_CUSTOM_HTTP_HEADERS`.
38+
Alternatively, if you want to specify the custom HTTP headers as a string in the environment variable, in a bash shell type a command of the form below:
39+
40+
```bash
41+
export MWI_CUSTOM_HTTP_HEADERS='{"Content-Security-Policy": "frame-ancestors *.example.com:* https://www.example.com:*;"}'
42+
```
43+
44+
If you add the `frame-ancestors` directive, the browser does not block the content of this integration hosted on the domain `www.example.com`.
45+
46+
47+
For more information about `Content-Security-Policy` header, check the [Mozilla developer docs for Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy).
48+
49+
**NOTE**: Setting custom HTTP headers is an advanced operation, only use this functionality if you are familiar with HTTP headers.

‎README.md

Lines changed: 2 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
The `jupyter-matlab-proxy` Python® package allows you to integrate MATLAB® with Jupyter®. The MATLAB integration for Jupyter enables you to open a MATLAB desktop in a web browser tab, directly from your Jupyter environment. This is not a kernel integration.
44

5-
The MATLAB Integration for Jupyter is under active development and you might find issues with the MATLAB graphical user interface. For support or to report issues, see the [Feedback](#Feedback) section.
5+
The MATLAB Integration for Jupyter is under active development and you might find issues with the MATLAB graphical user interface. For support or to report issues, see the [Feedback](#feedback) section.
66

77

88
## Use the MATLAB Integration for Jupyter
@@ -86,57 +86,6 @@ This package supports the same subset of MATLAB features and commands as MATLAB
8686

8787
If you want to use this integration with JupyterHub®, then you must install the `jupyter-matlab-proxy` Python package in the Jupyter environment launched by your JupyterHub platform. For example, if your JupyterHub platform launches Docker containers, then install this package in the Docker image used to launch them. You can find a reference architecture that installs the `jupyter-matlab-proxy` Python package in a Docker image in the repository [Use MATLAB Integration for Jupyter in a Docker Container](https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter/tree/main/matlab).
8888

89-
## Advanced
90-
91-
### Environment Variables
92-
93-
To control the behavior of the MATLAB integration for Jupyter, you can optionally specify the environment variables described in this section. You must specify these variables before starting your Jupyter environment. For example, specify the variable `MWI_APP_PORT` to be equal to 8888 when you start the Jupyter notebook using the command below:
94-
95-
```bash
96-
env MWI_APP_PORT=8888 jupyter notebook
97-
```
98-
**MARKDOWN TABLE**
99-
100-
These values are preset for you when you access the integration from the Jupyter console.
101-
| Name | Type | Example Value | Description |
102-
| ---- | ---- | ------------- | ----------- |
103-
| **MLM_LICENSE_FILE** | string | `"[email protected]"` | When you want to use either a license file or a network license manager to license MATLAB, specify this variable.</br> For example, specify the location of the network license manager to be `123@hostname`|
104-
| **MWI_LOG_LEVEL** | string | `"CRITICAL"` | Specify the Python log level to be one of the following `NOTSET`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `CRITICAL`. For more information on Python log levels, see [Logging Levels](https://docs.python.org/3/library/logging.html#logging-levels) .<br />The default value is `INFO`. |
105-
| **MWI_LOG_FILE** | string | `"/tmp/logs.txt"` | Specify the full path to the file where you want the logs to be written. |
106-
| **MWI_BASE_URL** | string | `"/matlab"` | Set to control the base URL of the app. MWI_BASE_URL should start with `/` or be `empty`. |
107-
| **MWI_APP_PORT** | integer | `8080` | Specify the port for the HTTP server to listen on. |
108-
| **MWI_CUSTOM_HTTP_HEADERS** | string |`'{"Content-Security-Policy": "frame-ancestors *.example.com:*"}'`<br /> OR <br />`"/path/to/your/custom/http-headers.json"` |Specify valid HTTP headers as JSON data in a string format<br />OR <br /> Specify the full path to the JSON file containing (valid) HTTP headers. These headers would be injected into the HTTP response sent to the browser. </br> For more information, see the MWI_CUSTOM_HTTP_HEADERS sub-section in the Advanced Usage section. |
109-
110-
11189
## Feedback
11290

113-
We encourage you to try this repository with your environment and provide feedback – the technical team is monitoring this repository. If you encounter a technical issue or have an enhancement request, send an email to `[email protected]`.
114-
115-
116-
## Advanced Usage
117-
118-
#### MWI_CUSTOM_HTTP_HEADERS:
119-
If the browser renders the MATLAB Integration for Jupyter with some other content, then web browsers could block the integration because of mismatch of `Content-Security-Policy` header in the response headers from the integration.
120-
121-
To avoid this, providing custom HTTP headers allow browsers to load the content.
122-
123-
For example:
124-
If this integration is rendered along with some other content on the domain `www.example.com`, sample `http-headers.json` file could be something like:
125-
126-
```json
127-
{
128-
"Content-Security-Policy": "frame-ancestors *.example.com:* https://www.example.com:*;"
129-
}
130-
```
131-
or if you are passing the custom http headers as a string in the environment variable. In bash shell, it could look like :
132-
133-
```bash
134-
export MWI_CUSTOM_HTTP_HEADERS='{"Content-Security-Policy": "frame-ancestors *.example.com:* https://www.example.com:*;"}'
135-
```
136-
137-
If you add the `frame-ancestors` directive, the browser does not block the content of this integration hosted on the domain `www.example.com`
138-
139-
140-
For more information about `Content-Security-Policy` header, check Mozilla developer docs for [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
141-
142-
**NOTE**: Setting custom HTTP headers is an advanced manoeuver, only use this functionality if you are familiar with HTTP headers.
91+
We encourage you to try this repository with your environment and provide feedback – the technical team is monitoring this repository. If you encounter a technical issue or have an enhancement request, send an email to `[email protected]`.

0 commit comments

Comments
 (0)