Introducing MATLAB Feature for DevContainers

mathworks · Jul 19, 2024 · 7da374c · 7da374c
commit 7da374c
Show file tree

Hide file tree

Showing 20 changed files with 1,493 additions and 0 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -0,0 +1,25 @@
+{
+    "image": "mcr.microsoft.com/devcontainers/javascript-node:1-18-bullseye",
+    "customizations": {
+        "vscode": {
+            "settings": {
+                "json.schemas": [
+                    {
+                        "fileMatch": [
+                            "*/devcontainer-feature.json"
+                        ],
+                        "url": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainerFeature.schema.json"
+                    }
+                ]
+            },
+            "extensions": [
+                "mads-hartmann.bash-ide-vscode"
+            ]
+        }
+    },
+    "features": {
+        "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+    },
+    "remoteUser": "node",
+    "updateContentCommand": "npm install -g @devcontainers/cli"
+}
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -0,0 +1,47 @@
+name: "Release dev container features & Generate Documentation"
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      packages: write
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: "Publish Features"
+        uses: devcontainers/action@v1
+        with:
+          publish-features: "true"
+          base-path-to-features: "./src"
+          generate-docs: "true"
+
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create PR for Documentation
+        id: push_image_info
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          echo "Start."
+          # Configure git and Push updates
+          git config --global user.email github-actions[bot]@users.noreply.github.com
+          git config --global user.name github-actions[bot]
+          git config pull.rebase false
+          branch=automated-documentation-update-$GITHUB_RUN_ID
+          git checkout -b $branch
+          message='Automated documentation update'
+          # Add / update and commit
+          git add */**/README.md
+          git commit -m 'Automated documentation update [skip ci]' || export NO_UPDATES=true
+          # Push
+          if [ "$NO_UPDATES" != "true" ] ; then
+              git push origin "$branch"
+              gh pr create --title "$message" --body "$message"
+          fi
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -0,0 +1,56 @@
+name: "CI - Test Features"
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test-autogenerated:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      matrix:
+        features:
+          - matlab
+        baseImage:
+          - debian:latest
+          - ubuntu:latest
+          - mcr.microsoft.com/devcontainers/base:ubuntu
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: "Install latest devcontainer CLI"
+        run: npm install -g @devcontainers/cli
+
+      - name: "Generating tests for '${{ matrix.features }}' against '${{ matrix.baseImage }}'"
+        run: devcontainer features test --skip-scenarios -f ${{ matrix.features }} -i ${{ matrix.baseImage }} .
+
+  test-scenarios:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      matrix:
+        features:
+          - matlab
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: "Install latest devcontainer CLI"
+        run: npm install -g @devcontainers/cli
+
+      - name: "Generating tests for '${{ matrix.features }}' scenarios"
+        run: devcontainer features test -f ${{ matrix.features }} --skip-autogenerated --skip-duplicated .
+
+  test-global:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: "Install latest devcontainer CLI"
+        run: npm install -g @devcontainers/cli
+
+      - name: "Testing global scenarios"
+        run: devcontainer features test --global-scenarios-only .
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -0,0 +1,16 @@
+name: "Validate devcontainer-feature.json files"
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: "Validate devcontainer-feature.json files"
+        uses: devcontainers/action@v1
+        with:
+          validate-only: "true"
+          base-path-to-features: "./src"
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,16 @@
+MATHWORKS CLOUD REFERENCE ARCHITECTURE LICENSE
+
+The files in this GitHub repository refer to commercial software products and services, virtual machine images, and related materials of The MathWorks, Inc. (“MathWorks Programs”). MathWorks Programs are separately licensed under the MathWorks Software License Agreement, available in the desktop installation of the MathWorks Programs or in the virtual machine image. The files in this GitHub repository may also refer to third-party software licensed under separate terms provided by such third parties.
+
+The following license terms apply only to the files in this GitHub repository, including files in this folder and its subfolders, and do not apply to MathWorks Programs. References to “software” and “code” in the following license terms refer to the files in this GitHub repository.
+
+Copyright (c) 2024, The MathWorks, Inc.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+In all cases, the software is, and all modifications and derivatives of the software shall be, licensed to you solely for use in conjunction with MathWorks products and service offerings.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
@@ -0,0 +1,64 @@
+# MATLAB Feature for Development Containers
+
+
+Use the [MATLAB Feature](./src/matlab/README.md) in this repository to add MATLAB&reg;, Simulink&reg;, and other MathWorks&trade; products to your development containers. 
+
+For more information about running MATLAB in dev containers, see 
+[Run MATLAB in GitHub&trade; Codespaces](https://github.com/mathworks-ref-arch/matlab-codespaces). 
+
+
+## Get Started
+
+A development container [Feature (GitHub)](https://github.com/devcontainers/features/) is self-contained code you can use to add functionality to your development container. You can add a feature to your development container by modifying `devcontainer.json`, the configuration file of the container. For instructions on creating a development container and adding a feature, see [Create a Dev Container (VS Code Docs)](https://code.visualstudio.com/docs/devcontainers/create-dev-container).
+
+
+Use the [MATLAB Feature](./src/matlab/README.md) to:
+
+* Install the [system dependencies](https://github.com/mathworks-ref-arch/container-images/tree/main/matlab-deps) required to run MATLAB and other MathWorks products.
+* Install MATLAB and other MathWorks products using [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md).
+* Add MATLAB to the system PATH.
+* Install Python packages such as the [MATLAB Engine for Python](https://github.com/mathworks/matlab-engine-for-python), [MATLAB Proxy](https://github.com/mathworks/matlab-proxy), and [MATLAB Integration for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy).
+
+### Usage
+
+To use the MATLAB Feature, include it in your dev container by specifying the `devcontainer.json` configuration file with your desired MATLAB Feature [Options](./src/matlab/README.md#options).
+
+For example, to install MATLAB `R2024a` with Symbolic Math Toolbox in a `ubuntu` base image, use this `devcontainer.json` configuration:
+
+```json
+{
+    "image": "ubuntu:latest",
+    "features": {
+        "ghcr.io/mathworks/devcontainer-features/matlab:0": {
+            "release": "r2024a",
+            "products": "MATLAB Symbolic_Math_Toolbox"
+        }
+    }
+}
+```
+This configuration installs MATLAB R2024a in your dev container and adds the `matlab` executable to your PATH.
+
+
+## Related Links
+
+Codespaces:
+* [Run MATLAB in GitHub Codespaces (GitHub)](https://github.com/mathworks-ref-arch/matlab-codespaces)
+* [Overview of Codespaces (GitHub)](https://docs.github.com/en/codespaces/overview)
+
+Dev Containers:
+* [Create a Dev Container (VS Code Docs)](https://code.visualstudio.com/docs/devcontainers/create-dev-container)
+* [Dev Container Metadata Reference](https://containers.dev/implementors/json_reference/)
+
+Dev Container Features:
+* [Dev Container Features (GitHub)](https://github.com/devcontainers/features/)
+* [Dev Container Features Specification](https://containers.dev/implementors/features/)
+* [Dev Container Feature JSON Properties](https://containers.dev/implementors/features/#devcontainer-json-properties)
+
+
+
+
+----
+
+Copyright 2024 The MathWorks, Inc.
+
+----
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,4 @@
+# Reporting Security Vulnerabilities 
+
+If you believe you have discovered a security vulnerability, please report it to 
+[[email protected]](mailto:[email protected]). For more information, see [MathWorks Vulnerability Disclosure Policy for Security Researchers](https://www.mathworks.com/company/aboutus/policies_statements/vulnerability-disclosure-policy.html).  
diff --git a/src/matlab/README.md b/src/matlab/README.md
@@ -0,0 +1,40 @@
+
+# MATLAB (matlab)
+
+Installs MATLAB, supporting packages and tools.
+
+## Example Usage
+
+```json
+"features": {
+    "ghcr.io/mathworks/devcontainer-features/matlab:0": {}
+}
+```
+
+## Options
+
+| Options Id | Description | Type | Default Value |
+|-----|-----|-----|-----|
+| release | MATLAB Release to install. | string | r2024a |
+| products | Products to install, specified as a list of product names separated by spaces.</br> See [MPM.md](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md#product-installation-options) for more information on product specification and availability.  | string | MATLAB |
+| doc | Flag to install documentation and examples. (R2022b and earlier releases) | boolean | false |
+| installGpu | Skips installation of GPU libraries when you install Parallel Computing Toolbox. (R2023a and later releases) | boolean | false |
+| destination | Full path to the installation destination folder. | string | /opt/matlab/$RELEASE |
+| installMatlabProxy | Installs matlab-proxy and its dependencies. (R2020b and later releases) | boolean | false |
+| installJupyterMatlabProxy | Installs jupyter-matlab-proxy and its dependencies. (R2020b and later releases) | boolean | false |
+| installMatlabEngineForPython | Installs the MATLAB Engine for Python if the destination option is set correctly. | boolean | false |
+| startInDesktop | Starts matlab-proxy on container start. | string | false |
+| networkLicenseManager | MATLAB will use the specified Network License Manager. | string | - |
+| skipMATLABInstall | Set to true if you dont want to install MATLAB. Useful if you only want to install the proxy products. | boolean | false |
+
+## Customizations
+
+### VS Code Extensions
+
+- `MathWorks.language-matlab`
+
+
+
+---
+
+_Note: This file was auto-generated from the [devcontainer-feature.json](https://github.com/mathworks/devcontainer-features/blob/main/src/matlab/devcontainer-feature.json).  Add additional notes to a `NOTES.md`._
diff --git a/src/matlab/devcontainer-feature.json b/src/matlab/devcontainer-feature.json
@@ -0,0 +1,107 @@
+{
+    "name": "MATLAB",
+    "id": "matlab",
+    "version": "0.0.7",
+    "description": "Installs MATLAB with supporting packages and tools.",
+    "documentationURL": "https://github.com/mathworks/devcontainer-features",
+    "options": {
+        "release": {
+            "type": "string",
+            "proposals": [
+                "r2024a",
+                "r2023b",
+                "r2023a",
+                "r2022b",
+                "r2022a",
+                "r2021b",
+                "r2021a",
+                "r2020b",
+                "r2020a",
+                "r2019b",
+                "r2019a"
+            ],
+            "default": "r2024a",
+            "description": "MATLAB Release to install."
+        },
+        "products": {
+            "type": "string",
+            "proposals": [
+                "MATLAB",
+                "MATLAB Simulink Signal_Processing_Toolbox"
+            ],
+            "default": "MATLAB",
+            "description": "Products to install, specified as a list of space-separated product names.</br> For details of products, see [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md#product-installation-options)."
+        },
+        "doc": {
+            "type": "boolean",
+            "default": false,
+            "description": "Flag to install documentation and examples (R2022b and earlier releases)."
+        },
+        "installGpu": {
+            "type": "boolean",
+            "default": false,
+            "description": "Skips installation of GPU libraries when you install Parallel Computing Toolbox (R2023a and later releases)."
+        },
+        "destination": {
+            "type": "string",
+            "default": "/opt/matlab/$RELEASE",
+            "description": "Full path to the installation destination folder."
+        },
+        "installMatlabProxy": {
+            "default": false,
+            "description": "Installs matlab-proxy and its dependencies (R2020b and later releases).",
+            "type": "boolean"
+        },
+        "installJupyterMatlabProxy": {
+            "default": false,
+            "description": "Installs jupyter-matlab-proxy and its dependencies (R2020b and later releases).",
+            "type": "boolean"
+        },
+        "installMatlabEngineForPython": {
+            "default": false,
+            "description": "Installs the MATLAB Engine for Python if the destination option is set correctly.",
+            "type": "boolean"
+        },
+        "startInDesktop": {
+            "default": "false",
+            "description": "Starts matlab-proxy when container starts.",
+            "type": "string",
+            "enum": [
+                "true",
+                "false",
+                "test"
+            ]
+        },
+        "networkLicenseManager": {
+            "type": "string",
+            "proposals": [
+                "port@hostname"
+            ],
+            "default": "",
+            "description": "MATLAB will use the specified Network License Manager."
+        },
+        "skipMATLABInstall": {
+            "type": "boolean",
+            "default": false,
+            "description": "Set to true if you do not want to install MATLAB, for example if you only want to install `matlab-proxy` or `jupyter-matlab-proxy`."
+        }
+    },
+    "postStartCommand": "( ls ~/.startmatlabdesktop >> /dev/null 2>&1 && env MWI_APP_PORT=8888 matlab-proxy-app 2>/dev/null ) || echo 'Will not start matlab-proxy-app...'",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "MathWorks.language-matlab"
+            ],
+            "settings": {
+                "MATLAB.indexWorkspace": true,
+                "MATLAB.installPath": "/usr/local/bin/matlab",
+                "MATLAB.matlabConnectionTiming": "never",
+                "MATLAB.telemetry": true
+            }
+        }
+    },
+    "installsAfter": [
+        "ghcr.io/devcontainers/features/common-utils",
+        "ghcr.io/devcontainers/features/python"
+    ]
+}