diff --git a/README.md b/README.md index fc10b08..9e55888 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Use the following topics to make platform-level decisions about how MATLAB and S - [Run MATLAB in Containers](./containerization.md) ## Feedback and Support -If you have an enhancement request or other feedback, create an issue on the [Issues](https://github.mathworks.com/alihosey/platform-engineer/issues) page. +If you have an enhancement request or other feedback, create an issue on the [Issues](https://github.com/mathworks/devops-integration-guide/issues) page. For support, contact [MathWorks Technical Support](https://www.mathworks.com/support/contact_us.html). diff --git a/containerization.md b/containerization.md index cb8d905..5eb3eb5 100644 --- a/containerization.md +++ b/containerization.md @@ -14,10 +14,13 @@ The [Dockerfile](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/ma - The latest MATLAB release (without additional toolboxes) - The latest [`matlab-batch`](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md) executable -When creating your own container image, you can customize the Dockerfile to include additional products. For details, see [Customize the Image](https://github.com/mathworks-ref-arch/matlab-dockerfile/tree/main/alternates/non-interactive#customize-the-image). +To include additional products in your container image, customize the Dockerfile. For details, see [Customize the Image](https://github.com/mathworks-ref-arch/matlab-dockerfile/tree/main/alternates/non-interactive#customize-the-image). + +> [!TIP] +> To verify which products your container image includes, run `matlab -batch "ver"`. A missing product typically causes an `Undefined function 'functionName'` error rather than naming the missing product directly. ## License Products -To license MathWorks products in a containerized CI workflow, use a [MATLAB batch licensing token](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md#matlab-batch-licensing-token). These tokens allow MATLAB to start in noninteractive environments. Request a token by submitting the [MATLAB Batch Licensing Pilot](https://www.mathworks.com/support/batch-tokens.html) form. +To license MathWorks products in a containerized CI workflow, use a [MATLAB batch licensing token](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md#matlab-batch-licensing-token). These tokens enable MATLAB to start in noninteractive environments. Request a token by submitting the [MATLAB Batch Licensing Pilot](https://www.mathworks.com/support/batch-tokens.html) form. > [!NOTE] > Do not paste the token into the Dockerfile. Instead, store it as a secret in your CI environment and use that secret to set an environment variable named `MLM_LICENSE_TOKEN`. For an example, see [Use MATLAB Batch Licensing Token](https://github.com/matlab-actions#use-matlab-batch-licensing-token). @@ -41,7 +44,7 @@ The following examples show how to define a CI pipeline to run the `"test"` task ### GitHub Actions To run a MATLAB build in GitHub Actions, use the [`run-build`](https://github.com/matlab-actions/run-build) action. To use your custom container image and batch licensing token, use the `container`, `image`, and `env` keywords in the workflow definition. -For example, in your repository, create a YAML file in the `.github/workflows` directory to run a container from your custom image on a GitHub-hosted runner. Then, use the container to run the `"test"` task with the `run-build` action. In this example, `MyToken` is the [secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) that holds the MATLAB batch licensing token. +For example, to run a container from your custom image on a GitHub-hosted runner, create a YAML file in the `.github/workflows` folder in your repository. Then, use the container to run the `"test"` task with the `run-build` action. In this example, `MyToken` is the [secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) that holds the MATLAB batch licensing token. ```YAML name: CI diff --git a/invoking-matlab.md b/invoking-matlab.md index 26b883b..c06f6eb 100644 --- a/invoking-matlab.md +++ b/invoking-matlab.md @@ -29,27 +29,28 @@ To standardize your MATLAB builds and support incremental builds, you can combin For more information, see [Continuous Integration with MATLAB on CI Platforms](https://www.mathworks.com/help/matlab/matlab_prog/continuous-integration-with-matlab-on-ci-platforms.html). ## Command-Line MATLAB -You can use the [`matlab`](https://www.mathworks.com/help/matlab/ref/matlablinux.html) command with the `-batch` option in your CI pipeline configuration file to execute scripts, functions, and statements. +To execute scripts, functions, and statements, use the [`matlab`](https://www.mathworks.com/help/matlab/ref/matlablinux.html) command with the `-batch` option in your CI pipeline configuration file. For example, this command runs the code in a file named `myscript.m`: ```(shell) matlab -batch "myscript" ``` -MATLAB terminates automatically with the exit code `0` if the code executes successfully without generating an error. Otherwise, MATLAB terminates with a nonzero exit code. +If the code executes without generating an error, MATLAB terminates automatically with the exit code `0`. Otherwise, MATLAB terminates with a nonzero exit code. -Consider using `matlab -batch` when: +Consider using `matlab -batch` if: - Your CI platform does not have a CI platform integration for MATLAB. - You use custom runners. - You want to invoke MATLAB using a simple command-line call. +- You invoke MATLAB from a general-purpose build system such as Bazel, CMake/CTest, Make, or Gradle. As alternatives to using `matlab -batch`: - For scaled workflows, you can use the [`matlab-batch` executable](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md). -- You can call MATLAB from other languages in CI by using the associated [external language interface](https://www.mathworks.com/help/matlab/external-language-interfaces.html?s_tid=CRUX_lftnav), but these integrations typically require a specific licensing model and do not support MATLAB batch token licensing. +- You can call MATLAB from other languages in CI by using the associated [external language interface](https://www.mathworks.com/help/matlab/external-language-interfaces.html?s_tid=CRUX_lftnav). However, these integrations typically require a specific licensing model and do not support MATLAB batch token licensing. ## Packaged MATLAB Artifacts When you package MATLAB artifacts, you build once with MATLAB and then run the resulting artifacts without installing MATLAB. -Consider using a packaged MATLAB approach when: +Consider using a packaged MATLAB approach if: - You want minimal dependencies on your CI runners. - You run the same workflow repeatedly. @@ -65,9 +66,9 @@ You can build and distribute MATLAB code as deployable artifacts, including: For more information about creating deployable applications from MATLAB code using MATLAB Compiler, see [Standalone Applications](https://www.mathworks.com/help/compiler/standalone-applications.html). ## MATLAB Hosted on Server -You can run MATLAB outside of your CI platform by invoking MATLAB remotely and using CI to orchestrate execution. You can use MATLAB Production Server™ to expose MATLAB functionality using REST or gRPC APIs. +You can run MATLAB outside of your CI platform by invoking MATLAB remotely and using CI to orchestrate execution. To expose MATLAB functionality using REST or gRPC APIs, use MATLAB Production Server™. -Consider using MATLAB Production Server when: +Consider using MATLAB Production Server if: - You have multiple pipelines that share MATLAB workloads. - You need more control over scaling. - You have a platform team or service team that owns MATLAB execution separately from CI. @@ -94,7 +95,7 @@ For more information, see: - [GitLab CI/CD Integration Guide](https://www.mathworks.com/help/slcheck/padv/ug/integrate-process-into-gitlab-with-artifact-management.html) - [Jenkins Integration Guide](https://www.mathworks.com/help/slcheck/padv/ug/integrate-process-into-jenkins-with-artifact-management.html) -Alternatively, you can use `matlab -batch` to call the `runprocess` function as shown in [Other Platforms](https://www.mathworks.com/help/slcheck/padv/ug/approaches-to-pipeline-configuration.html#mw_09108865-8cf4-4ad5-b157-e5214eae5762). +Alternatively, to call the `runprocess` function, use `matlab -batch` as shown in [Other Platforms](https://www.mathworks.com/help/slcheck/padv/ug/approaches-to-pipeline-configuration.html#mw_09108865-8cf4-4ad5-b157-e5214eae5762). ## See Also - [Install MathWorks Products in CI Environments](./installation.md) diff --git a/licensing.md b/licensing.md index cdbf36d..97838b8 100644 --- a/licensing.md +++ b/licensing.md @@ -1,16 +1,28 @@ # License MathWorks Products in CI Environments -Product licensing for your continuous integration (CI) pipeline depends on your project visibility as well as the types of products the pipeline uses: +Product licensing for your continuous integration (CI) pipeline depends on your project visibility and the types of products the pipeline uses: - Public project — The CI platform integration for MATLAB® automatically licenses all products available to your account, except for transformation products, such as MATLAB Coder™ and MATLAB Compiler™. For a full list of transformation products, see “Transformation Programs” in the [Program Offering Guide](https://www.mathworks.com/help/pdf_doc/offering/offering.pdf). - Private project — The CI platform integration for MATLAB does not automatically license any products for you. To license products that are not automatically licensed, you can request a [MATLAB batch licensing token](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md#matlab-batch-licensing-token) by submitting the [MATLAB Batch Licensing Pilot form](https://www.mathworks.com/support/batch-tokens.html). Batch licensing tokens are strings that enable MATLAB to start in noninteractive environments. +## License Types for Containers and Ephemeral Environments + +Containers and cloud-hosted VMs regenerate host identifiers, such as MAC addresses and disk serial numbers, on every startup. Licensing mechanisms that validate against a stable host ID fail in these environments. Choose a licensing mechanism that is compatible with your execution environment. + +| Licensing Mechanism | Container Compatible | Notes | +|---|---|---| +| Batch licensing token | Yes | The token authenticates independently of the host ID. Use batch tokens for CI. | +| Network license manager (`port@host`) | Yes | The license server validates the license, not the local host. | +| Node-locked license | No | This license type locks to a specific host ID. Use node-locked licenses only on persistent, self-hosted runners. | + +For most CI workflows, use a batch licensing token. If your organization already has a network license server, you can use it in containers as well. Contact your license administrator for help choosing a licensing mechanism. + ## Considerations for Batch Token Licensing If you have products that are not automatically licensed, review the following considerations: - Batch token licensing is recommended for scalable CI workflows and is the focus of this guide. For other licensing options, contact your license administrator. -- Batch token licensing works well with containers and noninteractive workflows. For a sample Dockerfile that shows how to build and customize a MATLAB container using MATLAB batch token licensing and the MATLAB Package Manager (`mpm`), see [Create a MATLAB Container Image for Non-Interactive Workflows](https://github.com/mathworks-ref-arch/matlab-dockerfile/tree/main/alternates/non-interactive). +- Batch token licensing is compatible with containers (see [License Types for Containers and Ephemeral Environments](#license-types-for-containers-and-ephemeral-environments)). You can build and customize a MATLAB container using batch token licensing and the MATLAB Package Manager (`mpm`). For a sample Dockerfile, see [Create a MATLAB Container Image for Non-Interactive Workflows](https://github.com/mathworks-ref-arch/matlab-dockerfile/tree/main/alternates/non-interactive). - Batch token licensing does not support MATLAB Engine API for Python®. Most Python-based CI workflows require a different licensing option. Contact your license administrator for alternatives. - Polyspace® products require a dedicated license server that runs on a machine separate from the CI agent.