diff --git a/content/en/docs/private-platform/_index.md b/content/en/docs/private-platform/_index.md index 846b7223b71..09941515608 100644 --- a/content/en/docs/private-platform/_index.md +++ b/content/en/docs/private-platform/_index.md @@ -35,7 +35,7 @@ The integration with Studio Pro does not currently support using the [Integratio * Mendix developer experience hosted entirely within any virtual private cloud * Support for SSO authentication for Private Mendix Platform and Studio Pro through your own identity provider (IdP) * A private version of the Mendix Marketplace, with all contents hosted entirely within your Private Mendix Platform, accessible in-browser and directly from Studio Pro -* SCM repository support for GitLab, GitHub, Bitbucket and Azure DevOps Services, to be used as source code repository for your projects +* SCM repository support for GitLab, GitHub, Bitbucket, Azure DevOps Services and Azure DevOps Server, to be used as source code repository for your projects * CI/CD capabilities out-of-the-box, with additional support for integrations with Jenkins, Kubernetes, and Azure DevOps; leverage our predefined templates or implement your own custom templates * Operational capabilities such as basic log browsing and metrics through integrations with Loki and Grafana * Governance features like application landscape management, marketplace administration, user group management, as well as various developer platform feature settings and action logs diff --git a/content/en/docs/private-platform/configuration/pmp-configure-azure.md b/content/en/docs/private-platform/configuration/pmp-configure-azure.md index ca100116bf9..c57d88b80a6 100644 --- a/content/en/docs/private-platform/configuration/pmp-configure-azure.md +++ b/content/en/docs/private-platform/configuration/pmp-configure-azure.md @@ -15,7 +15,10 @@ This document explains the configuration options available when configuring a Co To configure the CI/CD pipeline, prepare the following: -* An Azure organization where you want to build your Mendix app. +* An Azure DevOps Services organization where you want to build your Mendix app. The Azure DevOps CI build utility runs on Microsoft-hosted agents and works with Azure DevOps Services only. + + Building is not supported for the Azure DevOps Server (on-premises). Instead, use the Kubernetes build method. For more information, see [Azure DevOps Server Builds](/private-mendix-platform/configure-k8s/#azure-devops-server). + * An Azure blob or an AWS S3 endpoint where you can store the built MDA files. ## Configuring the CI/CD Pipeline diff --git a/content/en/docs/private-platform/configuration/pmp-configure-k8s.md b/content/en/docs/private-platform/configuration/pmp-configure-k8s.md index 1c9f61c9b65..0ad434a6cff 100644 --- a/content/en/docs/private-platform/configuration/pmp-configure-k8s.md +++ b/content/en/docs/private-platform/configuration/pmp-configure-k8s.md @@ -58,9 +58,9 @@ If you have already configured a custom CA certificate, you must only add your n The settings in this section configure the Kubernetes cluster. -* **API Server** - Your Kubernetes API server. -* **Namespace** - The namespace used to create the Kubernetes pod. -* **Token** - You must create a service account, role, and role binding in the above namespace, and then get the service account's token. For reference, see the following shell script: +* **API Server** – Your Kubernetes API server. +* **Namespace** – The namespace used to create the Kubernetes pod. +* **Token** – You must create a service account, role, and role binding in the above namespace, and then get the service account's token. For reference, see the following shell script: ```text # create ServiceAccount, Role, and RoleBinding @@ -123,26 +123,26 @@ kubectl get secret mxplatform-cicd -n$NAMESPACE -o jsonpath='{.metadata.annotati The settings in this section configure the images. -* **Keep Build Pod** - Select this checkbox to keep the build pod after the build is completed. This is useful for troubleshooting if the build failed due to pod creation failure or build failure. You can describe the pod to see its status, or check the logs of the pod. -* **Run As User** - The default value is *1001110000*. For an OpenShift cluster, you must check the user ID range by using the below command, and check the annotations. For example, for `openshift.io/sa.scc.uid-range: 1001190000/10000`, you can choose one ID from the *1001190000 - 1001199999* range. +* **Keep Build Pod** – Select this checkbox to keep the build pod after the build is completed. This is useful for troubleshooting if the build failed due to pod creation failure or build failure. You can describe the pod to see its status, or check the logs of the pod. +* **Run As User** – The default value is *1001110000*. For an OpenShift cluster, you must check the user ID range by using the below command, and check the annotations. For example, for `openshift.io/sa.scc.uid-range: 1001190000/10000`, you can choose one ID from the *1001190000 - 1001199999* range. ```text export NAMESPACE=default kubectl get ns $NAMESPACE -oyaml ``` -* **Build Image** - The default value is `private-cloud.registry.mendix.com/privateplatform/pmp-pipeline-tools`. This image is used to build MDA package and OCI image. -* **Build Package Source** - Select the download source for the *mxbuild* package. The following values are supported: +* **Build Image** – The default value is `private-cloud.registry.mendix.com/privateplatform/pmp-pipeline-tools`. This image is used to build MDA package and OCI image. +* **Build Package Source** – Select the download source for the *mxbuild* package. The following values are supported: - * **File Server** - This option allows anonymous access without any authentication. - * **S3 Bucket** - This option requires an access key ID and secret access key for authentication. - * **Azure Blob** - This option requires the Azure Workload identity authentication. The default service account is used in the build pod for downloading the *mxbuild* package. To configure the managed identity and service account, perform the following steps: + * **File Server** – This option allows anonymous access without any authentication. + * **S3 Bucket** – This option requires an access key ID and secret access key for authentication. + * **Azure Blob** – This option requires the Azure Workload identity authentication. The default service account is used in the build pod for downloading the *mxbuild* package. To configure the managed identity and service account, perform the following steps: 1. Create a managed identity in the Azure portal 2. Configure federated credentials for the Kubernetes service account. 3. In the **Managed Identity** section, add a role assignment with the following role: - * **Storage Blob Data Contributor** - This role permits Private Mendix Platform to read and write MDA blobs (upload deployment packages, read package metadata and SBOM contents). Private Mendix Platform requires the role to upload deployment packages. Read only access is not sufficient. As a best practice, for increased security, this role should be scoped at the container level, although scoping it to the storage account is also permitted. + * **Storage Blob Data Contributor** – This role permits Private Mendix Platform to read and write MDA blobs (upload deployment packages, read package metadata and SBOM contents). Private Mendix Platform requires the role to upload deployment packages. Read-only access is not sufficient. As a best practice, for increased security, this role should be scoped at the container level, although scoping it to the storage account is also permitted. 4. Add an annotation to the service account, as in the following example: @@ -155,14 +155,14 @@ The settings in this section configure the images. azure.workload.identity/client-id: {client-id-build} ``` -* **Build Package Path** - This setting is required for the **File Server** build package source. The default value is `https://cdn.mendix.com/runtime`. If you have your own file server, you must download the package from the Mendix Content Delivery Network, and then upload it to your file server. The file name format is *mxbuild-9.24.1.4658.tar.gz*. -* **S3 Endpoint**, **S3 Bucket Name**, **Region**, **Access Key ID**, **Secret Access Key** - These settings are required for the **S3 Bucket** build package source. -* **Storage Account**, **Container** - These settings are required for the **Azure Blob** build package source. -* **Build OCI Image** - Select this check box to build the OCI image besides the MDA file. Only OCI image can be used for deployment if this is checked. This option can be used to avoid configuring anonymous access to your S3 bucket or Azure Blob container. -* **Registry Type** - This setting is only applicable if you selected the **Build OCI Image check box.** The following values are supported: +* **Build Package Path** – This setting is required for the **File Server** build package source. The default value is `https://cdn.mendix.com/runtime`. If you have your own file server, you must download the package from the Mendix Content Delivery Network, and then upload it to your file server. The file name format is *mxbuild-9.24.1.4658.tar.gz*. +* **S3 Endpoint**, **S3 Bucket Name**, **Region**, **Access Key ID**, **Secret Access Key** – These settings are required for the **S3 Bucket** build package source. +* **Storage Account**, **Container** – These settings are required for the **Azure Blob** build package source. +* **Build OCI Image** – Select this checkbox to build the OCI image besides the MDA file. Only OCI image can be used for deployment if this is checked. This option can be used to avoid configuring anonymous access to your S3 bucket or Azure Blob container. +* **Registry Type** – This setting is only applicable if you selected the **Build OCI Image checkbox.** The following values are supported: - * **Generic** - Supports user and password authentication - * **AWS ECR** - Supports IRSA authentication; add the following policy to the IAM role: + * **Generic** – Supports user and password authentication + * **AWS ECR** – Supports IRSA authentication; add the following policy to the IAM role: ```text { @@ -195,26 +195,26 @@ The settings in this section configure the images. } ``` - * **Azure ACR** - Supports Workload Identity authentication; add the **AcrPush** role to the build managed identity. + * **Azure ACR** – Supports Workload Identity authentication; add the **AcrPush** role to the build managed identity. -* **Runtime Base Image** - This setting is only applicable if you selected the **Build OCI Image** check box. The default value is `private-cloud.registry.mendix.com/app-building-blocks`. If you are in an air gap environment, sync tag `ubi9-1-jre{XX}-entrypoint` and `runtime-{YYYYY}`, where `{XX}` is java version in your app, and `{YYYYY}` is your app runtime version. For example: `app-building-blocks:ubi9-1-jre21-entrypoint` and `app-building-blocks:runtime-10.12.1.39914`. -* **Allow Anonymous Access** - Select this checkbox if above Runtime Base Image is accessible without authentication. -* **Runtime Base Registry User** - This setting is only applicable if you did not select the **Allow Anonymous Access** check box. User name for the registry authentication. -* **Runtime Base Registry Password** - This setting is only applicable if you did not select the **Allow Anonymous Access** check box. Password for the registry authentication. -* **OCI Registry** - This setting is only applicable if you selected the **Build OCI Image** check box. This registry is used to store OCI image, also repository name should be appended to the registry, quay.io/pmp as an example. -* **OCI Registry User** - This setting is only applicable if you selected the **Build OCI Image** check box. User name for the registry authentication. -* **OCI Registry Password** - This setting is only applicable if you selected the **Build OCI Image** check box. Password for the registry authentication. +* **Runtime Base Image** – This setting is only applicable if you selected the **Build OCI Image** checkbox. The default value is `private-cloud.registry.mendix.com/app-building-blocks`. If you are in an air gap environment, sync tag `ubi9-1-jre{XX}-entrypoint` and `runtime-{YYYYY}`, where `{XX}` is the Java version in your app, and `{YYYYY}` is your app runtime version. For example: `app-building-blocks:ubi9-1-jre21-entrypoint` and `app-building-blocks:runtime-10.12.1.39914`. +* **Allow Anonymous Access** – Select this checkbox if above Runtime Base Image is accessible without authentication. +* **Runtime Base Registry User** – This setting is only applicable if you did not select the **Allow Anonymous Access** checkbox. User name for the registry authentication. +* **Runtime Base Registry Password** – This setting is only applicable if you did not select the **Allow Anonymous Access** checkbox. Password for the registry authentication. +* **OCI Registry** – This setting is only applicable if you selected the **Build OCI Image** checkbox. This registry is used to store OCI image, also repository name should be appended to the registry, quay.io/pmp as an example. +* **OCI Registry User** – This setting is only applicable if you selected the **Build OCI Image** checkbox. User name for the registry authentication. +* **OCI Registry Password** – This setting is only applicable if you selected the **Build OCI Image** checkbox. Password for the registry authentication. ### Configuring MDA Storage Setting {#mda-storage} The settings in this section configure the storage for build output artifacts. -* **Mda Storage Option** - Configure where to store the build output artifacts. The supported values are S3 Bucket and Azure Blob. This option requires the Azure Workload identity authentication. The default service account is used in the build pod for uploading the build artifacts. To configure the managed identity and service account, perform the following steps: +* **Mda Storage Option** – Configure where to store the build output artifacts. The supported values are S3 Bucket and Azure Blob. This option requires the Azure Workload identity authentication. The default service account is used in the build pod for uploading the build artifacts. To configure the managed identity and service account, perform the following steps: 1. Create or reuse a managed identity on Azure portal, and configure federated credentials for the Kubernetes service account. 2. In the **Managed Identity**, add a role assignment with the following role: - * **Storage Blob Data Contributor** - This role permits Private Mendix Platform to read and write MDA blobs (upload deployment packages, read package metadata and SBOM contents). Private Mendix Platform requires the role to upload deployment packages. Read only access is not sufficient. As a best practice, for increased security, this role should be scoped at the container level, although scoping it to the storage account is also permitted. + * **Storage Blob Data Contributor** – This role permits Private Mendix Platform to read and write MDA blobs (upload deployment packages, read package metadata and SBOM contents). Private Mendix Platform requires the role to upload deployment packages. Read-only access is not sufficient. As a best practice, for increased security, this role should be scoped at the container level, although scoping it to the storage account is also permitted. 3. Optional: Add annotations for the build pod and Private Mendix Platform to the service account, as in the following example: @@ -231,8 +231,8 @@ The settings in this section configure the storage for build output artifacts. 4. Add the following role assignments to the Private Mendix Platform Managed Identity: - * **Storage Blob Data Contributor** - This role permits Private Mendix Platform to read and write MDA blobs (upload deployment packages, read package metadata and SBOM contents). Private Mendix Platform requires the role to upload deployment packages. Read only access is not sufficient. As a best practice, for increased security, this role should be scoped at the container level, although scoping it to the storage account is also permitted. - * **Storage Blob Delegator** - This role permits Private Mendix Platform to delegate access to blobs by generating presigned (user delegation SAS) download URLs. It grants no data access of its own. MDA downloads may fail even when a blob data role is correctly assigned if Delegator is missing. This role must be scoped to the storage account. + * **Storage Blob Data Contributor** – This role permits Private Mendix Platform to read and write MDA blobs (upload deployment packages, read package metadata and SBOM contents). Private Mendix Platform requires the role to upload deployment packages. Read-only access is not sufficient. As a best practice, for increased security, this role should be scoped at the container level, although scoping it to the storage account is also permitted. + * **Storage Blob Delegator** – This role permits Private Mendix Platform to delegate access to blobs by generating presigned (user delegation SAS) download URLs. It grants no data access of its own. MDA downloads may fail even when a blob data role is correctly assigned if Delegator is missing. This role must be scoped to the storage account. 5. Optional: Add **customPodLabels** to the Mendix Operator to label the Private Mendix Platform pod with the proper configuration. This configuration allows Private Mendix Platform to get build artifacts from Azure Storage Blob. @@ -251,22 +251,22 @@ The settings in this section configure the storage for build output artifacts. 6. Restart Private Mendix Platform to ensure that the labels are applied. -* **S3 Endpoint** - For example, `https://s3.ap-southeast-1.amazonaws.com`. -* **No Verify SSL** - Select this checkbox if you use your own bucket server, and its certificate is self-signed. Selecting this option adds *--no-verify-ssl* to the AWS CLI command to avoid failure. -* **S3 Bucket Name** - Your S3 bucket name, for example, *mybucket*. -* **Mda Location** - Your S3 bucket name's domain, for example, `https://mybucket.s3.ap-southeast-1.amazonaws.com`. This URL is used to access build artifacts, the whole path is: `Mda Location + Appid + Mda/Meta file`. Make sure that the S3 bucket is configured to allow anonymous access. -* **Region** - For example, `ap-southeast-1`. -* **Use K8S Secret** - Select whether you want to input the **Access Key ID** and **Secret Access Key**, or set them in a Kubernetes secret. Enable this setting to avoid showing sensitive credentials in a build pod. -* **Secret Name** - This setting is only applicable if you selected the **Use K8S Secret** check box. This is the secret name where you want to store the **Access Key ID** and **Secret Access Key**. Use the following command to create this secret, where your-namespace is the namespace that you specified in **Build Cluster Setting** > **Namespace**. +* **S3 Endpoint** – For example, `https://s3.ap-southeast-1.amazonaws.com`. +* **No Verify SSL** – Select this checkbox if you use your own bucket server, and its certificate is self-signed. Selecting this option adds *--no-verify-ssl* to the AWS CLI command to avoid failure. +* **S3 Bucket Name** – Your S3 bucket name, for example, *mybucket*. +* **Mda Location** – Your S3 bucket name's domain, for example, `https://mybucket.s3.ap-southeast-1.amazonaws.com`. This URL is used to access build artifacts, the whole path is: `Mda Location + Appid + Mda/Meta file`. Make sure that the S3 bucket is configured to allow anonymous access. +* **Region** – For example, `ap-southeast-1`. +* **Use K8S Secret** – Select whether you want to input the **Access Key ID** and **Secret Access Key**, or set them in a Kubernetes secret. Enable this setting to avoid showing sensitive credentials in a build pod. +* **Secret Name** – This setting is only applicable if you selected the **Use K8S Secret** checkbox. This is the secret name where you want to store the **Access Key ID** and **Secret Access Key**. Use the following command to create this secret, where your-namespace is the namespace that you specified in **Build Cluster Setting** > **Namespace**. ```text kubectl create secret generic mxplatform-awssecret -n your-namespace --from-literal=aws_access_key_id=your-aws-access-key-id --from-literal=aws_secret_access_key=your-aws-secret-access-key ``` -* **Access Key ID** - This setting is only applicable if you did not select the **Use K8S Secret** check box. This value is used to access the S3 bucket. -* **Secret Access Key** - This setting is only applicable if you did not select the **Use K8S Secret** check box. This value is used to access the S3 bucket. -* **Storage Account, Container** - This setting is used to configure Azure Blob when the **Mda Storage Option** is set to **Azure Blob**. -* **Mda Location** - Your Azure Blob container's domain, for example, `https://your-storage-account.blob.core.windows.net/your-container`. This setting is only applicable if **Build OCI Image** is not selected. Make sure that the container's anonymous access level is set to **Blob**. +* **Access Key ID** – This setting is only applicable if you did not select the **Use K8S Secret** checkbox. This value is used to access the S3 bucket. +* **Secret Access Key** – This setting is only applicable if you did not select the **Use K8S Secret** checkbox. This value is used to access the S3 bucket. +* **Storage Account, Container** – This setting is used to configure Azure Blob when the **Mda Storage Option** is set to **Azure Blob**. +* **Mda Location** – Your Azure Blob container's domain, for example, `https://your-storage-account.blob.core.windows.net/your-container`. This setting is only applicable if **Build OCI Image** is not selected. Make sure that the container's anonymous access level is set to **Blob**. ### Registering a Kubernetes Cluster {#register-cluster} @@ -275,9 +275,9 @@ Before creating any environments, you must register your Kubernetes clusters by 1. Click **Register New Cluster**. 2. Configure the following values: - * **Cluster Name** - Specify a name for the cluster. - * **API Server** - Specify your Kubernetes API server. - * **Token** - You must first create a service account, cluster role, and cluster role binding in the cluster, and then get the service account's token. For reference, see the following shell script: + * **Cluster Name** – Specify a name for the cluster. + * **API Server** – Specify your Kubernetes API server. + * **Token** – You must first create a service account, cluster role, and cluster role binding in the cluster, and then get the service account's token. For reference, see the following shell script: ```text # create ServiceAccount, ClusterRole, and ClusterRoleBinding @@ -441,6 +441,52 @@ Before creating any environments, you must register your Kubernetes clusters by 6. After the cluster is registered, create environments with the cluster, namespace and plans. +### Azure DevOps Server Builds {#azure-devops-server} + +When the version control system is Azure DevOps Server (on-premises), the build pods clone the app from your server with the PAT of the user who starts the build. They need the following: + +1. **DNS** – The build cluster resolves the server host name. A hosts entry on a single machine is not visible to the cluster. +2. **Network** – TCP 443 (or the server port) is open from the cluster's outbound addresses to the server. +3. **Build image** – pmp-pipeline-tools 0.11.1 or above. Earlier images fail with *Authentication failed* when the server offers Windows authentication (NTLM), which is the default for Azure DevOps Server. +4. **Certificate trust** – If the server certificate is not issued by a public CA, use a build image that trusts your CA (see below). Do not use **Skip SSL Verification** in production: it also switches off the certificate checks for the storage and registry calls. +5. **Secrets** – The build pod receives the user's Git token. Restrict read access to the build namespace. + +#### Building an Image That Trusts Your CA + +The build image trusts public CAs only and ignores `CACertificates` and the Operator custom CA secret. Build a derived image that adds your CA to its system trust store. You need one image per CA, and you rebuild it for every pmp-pipeline-tools release and every CA change. To build the image, follow these steps: + +1. Find the image in **Admin Mode** > **Settings** > **Build** > **Build Utility** > **Build Pipeline Image** and pin a version tag. +2. Create a Dockerfile next to `customer-ca.crt`: + + ```text + ARG BASE=private-cloud.registry.mendix.com/privateplatform/pmp-pipeline-tools: + FROM ${BASE} + USER root + COPY customer-ca.crt /etc/pki/ca-trust/source/anchors/customer-ca.crt + RUN update-ca-trust extract + USER mendix + ``` + +3. Build and test it: + + ```text + docker build -t /pmp-pipeline-tools-ca: . + docker run --rm --entrypoint sh /pmp-pipeline-tools-ca: -c 'git ls-remote https://///_git/ 2>&1 | head -3' + ``` + + The output must not contain *unable to get local issuer certificate*; an authentication message is fine here. + +4. Push the image. If the registry needs credentials, create an image pull secret in the build namespace and enter it as **Pull Secret**. +5. In **Build Utility**, set **Build Pipeline Image** to the new image and **Skip SSL Verification** to off. +6. Run a build. The Git step must clone without a certificate error. + +| Build Log | Cause | +| --- | --- | +| *Could not resolve host* | DNS | +| *unable to get local issuer certificate* | The image does not trust the CA, or the old image is still selected | +| *certificate is valid for ..., not ...* | The server certificate has no SAN for the host name | +| *Authentication failed* | Build image older than 0.11.1, or an invalid PAT | + ## Architecture of the CI/CD Pipeline The diagram in this section presents the architecture and components of the pipeline. For more information, see [Build Images Setting](#build-images) above. diff --git a/content/en/docs/private-platform/configuration/pmp-version-control.md b/content/en/docs/private-platform/configuration/pmp-version-control.md index 1d5596438d1..1f6828c43c1 100644 --- a/content/en/docs/private-platform/configuration/pmp-version-control.md +++ b/content/en/docs/private-platform/configuration/pmp-version-control.md @@ -15,7 +15,8 @@ Private Mendix Platform supports the following types of Git repositories as the * GitHub Enterprise Server * GitHub Enterprise Cloud * Bitbucket -* Azure DevOps Services (cloud, `dev.azure.com`). Azure DevOps Server (on-premises) is not supported. +* Azure DevOps Services (cloud, `dev.azure.com`) +* Azure DevOps Server (on-premises), version 2022.1 or above To select the repository type, perform the following steps: @@ -38,18 +39,18 @@ Before configuring GitLab for Private Mendix Platform, ensure that you fulfill t ### Configuration -* **Host URL** - This is the host URL of your GitLab server. The format should be `https://`. There is no slash in the end. For example, if your GitLab server host name is `mygitlab.example.com`, you should input `https://mygitlab.example.com` here. -* **Group ID** - All the apps on Private Mendix Platform are created under a GitLab group. You need to create a group in GitLab and then input the *Group ID* in this field. -* **Group owner PAT** - This is the PAT from the above group owner. When generating the access token for group owner, select all scopes and set expiration date to **never**. -* **Automatic Access Provisioning** - If you use a self-managed GitLab server, you can enable this feature to automatically create GitLab user and PAT for private platform users. During logging in the platform, user email is used as unique key to search in GitLab server. If this email name is not registered in GitLab, Private Mendix Platform creates a GitLab user with this email. A PAT is then generated for this user. -* **Admin PAT** - This is the PAT of the GitLab administrator, which is the root user access token with all scopes selected. +* **Host URL** – This is the host URL of your GitLab server. The format should be `https://`. There is no slash in the end. For example, if your GitLab server host name is `mygitlab.example.com`, you should input `https://mygitlab.example.com` here. +* **Group ID** – All the apps on Private Mendix Platform are created under a GitLab group. You need to create a group in GitLab and then input the *Group ID* in this field. +* **Group owner PAT** – This is the PAT from the above group owner. When generating the access token for group owner, select all scopes and set expiration date to **never**. +* **Automatic Access Provisioning** – If you use a self-managed GitLab server, you can enable this feature to automatically create GitLab user and PAT for private platform users. During logging in the platform, user email is used as unique key to search in GitLab server. If this email name is not registered in GitLab, Private Mendix Platform creates a GitLab user with this email. A PAT is then generated for this user. +* **Admin PAT** – This is the PAT of the GitLab administrator, which is the root user access token with all scopes selected. ### Normal User Credentials When the **Automatic Access Provisioning** is disabled, private platform users need to manually input the GitLab user id and PAT at first login. -* **User ID** - The user ID (integer number) of this GitLab user. It is not the user name. You can obtain the value from the user profile page. -* **Personal Access Token** - The access token of this GitLab user. +* **User ID** – The user ID (integer number) of this GitLab user. It is not the user name. You can obtain the value from the user profile page. +* **Personal Access Token** – The access token of this GitLab user. ### Supported Predefined Push Rules @@ -87,14 +88,14 @@ Before configuring GitHub for Private Mendix Platform, ensure that you fulfill t The following configuration applies to all GitHub server types, unless stated otherwise. -* **Organization Name** - All the apps on Private Mendix Platform are created under an organization. You need to create an organization to host all the Mendix apps. Type the organization name into this field. -* **Organization Owner PAT** - This is the Personal Access Token (PAT) of the organization owner. The PAT must have sufficient permissions to manage repositories and organization access. It is recommended to use a classic PAT with the required scopes selected and the expiration date set to **No Expiration**. +* **Organization Name** – All the apps on Private Mendix Platform are created under an organization. You need to create an organization to host all the Mendix apps. Type the organization name into this field. +* **Organization Owner PAT** – This is the Personal Access Token (PAT) of the organization owner. The PAT must have sufficient permissions to manage repositories and organization access. It is recommended to use a classic PAT with the required scopes selected and the expiration date set to **No Expiration**. ### GitHub Enterprise Server -* **Host URL** - This is the host URL of your GitHub server. The format should be `https://`. There is no slash in the end. For example, if your GitHub server host name is `mygithub.example.com`, you should input `https://mygithub.example.com` here. -* **Automatic Access Provisioning** - If you are running a self-managed GitHub enterprise server, you can enable this feature to automatically create GitHub users and Personal Access Tokens for Private Mendix Platform users. When logging in to the platform, the user email is used as unique key to search in GitHub server. If this email name is not registered in GitHub, Private Mendix Platform creates a GitHub user with this email. A PAT is then generated for this user. -* **AdminPAT** - This is the PAT of the GitHub Enterprise Server administrator. The token must be generated with sufficient privileges to manage users and access permissions. +* **Host URL** – This is the host URL of your GitHub server. The format should be `https://`. There is no slash in the end. For example, if your GitHub server host name is `mygithub.example.com`, you should input `https://mygithub.example.com` here. +* **Automatic Access Provisioning** – If you are running a self-managed GitHub enterprise server, you can enable this feature to automatically create GitHub users and Personal Access Tokens for Private Mendix Platform users. When logging in to the platform, the user email is used as unique key to search in GitHub server. If this email name is not registered in GitHub, Private Mendix Platform creates a GitHub user with this email. A PAT is then generated for this user. +* **AdminPAT** – This is the PAT of the GitHub Enterprise Server administrator. The token must be generated with sufficient privileges to manage users and access permissions. {{< figure src="/attachments/private-platform/pmp-vc2.png" alt="Version Control Settings for GitHub Enterprise Server" class="no-border" >}} @@ -104,7 +105,7 @@ The following configuration applies to all GitHub server types, unless stated ot Automatic access provisioning is not supported for GitHub Enterprise Cloud. {{% /alert %}} -* **Data Residency** - When toggled **off**, you only need to configure the [common settings](#common-config). When toggled **on**, OAuth‑based authentication is required. +* **Data Residency** – When toggled **off**, you only need to configure the [common settings](#common-config). When toggled **on**, OAuth‑based authentication is required. * **Dedicated Host URL** – This is the dedicated GitHub Enterprise Cloud host URL associated with the data residency configuration for your organization. * **OAuth App Configuration** – You must create an OAuth App in GitHub with the **Authorization Callback URL** set to the callback URL provided by the Private Mendix Platform. @@ -135,9 +136,9 @@ Before configuring Bitbucket for Private Mendix Platform, ensure that you fulfil ## Configuration -* **Host URL** - This is the host URL of your Bitbucket enterprise server. The format should be `https://`. There is no slash in the end. For example, if your Bitbucket enterprise server host name is `mybitbucket.example.com`, you should input `https://mybitbucket.example.com` here. -* **Project Key** - All the Mendix apps on the Private Mendix Platform are created under a Bitbucket project. You must create an project to host all the Mendix apps and input the project key in this field. You can view the project key at `https://mybitbucket.example.com/projects`. -* **Project Admin PAT** - This is the Personal Access Token of a Bitbucket project administrator user. +* **Host URL** – This is the host URL of your Bitbucket enterprise server. The format should be `https://`. There is no slash in the end. For example, if your Bitbucket enterprise server host name is `mybitbucket.example.com`, you should input `https://mybitbucket.example.com` here. +* **Project Key** – All the Mendix apps on the Private Mendix Platform are created under a Bitbucket project. You must create an project to host all the Mendix apps and input the project key in this field. You can view the project key at `https://mybitbucket.example.com/projects`. +* **Project Admin PAT** – This is the Personal Access Token of a Bitbucket project administrator user. ### Automatic Access Provisioning @@ -156,29 +157,37 @@ When the Automatic Access Provisioning is disabled, Private Mendix Platform user This user needs to be invited into the project with the **Create repository** permission. You can add users and grant permissions at `https://mybitbucket.example.com/projects//permissions`. -* **User Name** - The Bitbucket login name of this user. -* **Personal Access Token** - The Personal Access Token of this Bitbucket user. The permission level must be at least **Project Admin**, and the expiration date should be set to **No Expiration**. +* **User Name** – The Bitbucket login name of this user. +* **Personal Access Token** – The Personal Access Token of this Bitbucket user. The permission level must be at least **Project Admin**, and the expiration date should be set to **No Expiration**. {{< figure src="/attachments/private-platform/pmp-vc4.png" alt="Version Control Settings for Bitbucket" class="no-border" >}} -## AzureDevOps +## Azure DevOps -This section describes the configuration of an Azure DevOps repository for use with the Private Mendix Platform. +This section describes the configuration of an Azure DevOps repository for use with the Private Mendix Platform. Private Mendix Platform supports two deployment types: -### Prerequisites +| Deployment Type | Use For | Authentication | +| --- | --- | --- | +| **Azure DevOps Services (cloud)** | `dev.azure.com` | Microsoft Entra ID OAuth, which creates the users' Personal Access Tokens (PATs), plus an organization admin PAT | +| **Azure DevOps Server (on-premises)** | Your own Azure DevOps Server, version 2022.1 or above | PATs only. Private Mendix Platform does not call Microsoft Entra ID or `dev.azure.com` | + +Select the type in **Settings** > **Version Control** > **Azure DevOps** > **Deployment Type**. Existing configurations and settings exports from earlier versions use **Azure DevOps Services (cloud)**. + +### Azure DevOps Services (Cloud) -Before configuring Azure DevOps for Private Mendix Platform, ensure that you fulfill the following prerequisites: +#### Prerequisites + +Before configuring Azure DevOps Services for Private Mendix Platform, ensure that you fulfill the following prerequisites: -* You use Azure DevOps Services (cloud). Azure DevOps Server (on-premises) is not supported, because Private Mendix Platform requires the Azure DevOps cloud PAT API to generate your Azure PAT. * You have access to an Azure DevOps organization. * An Azure DevOps project exists to host applications created by the Private Mendix Platform. * You can generate Personal Access Tokens (PATs) in Azure DevOps. * A Microsoft Entra ID (Azure AD) application can be registered. * Your Azure DevOps organization must be connected to the same Microsoft Entra ID tenant as the app registration used for Azure OAuth. -### Microsoft Entra ID Configuration +#### Microsoft Entra ID Configuration -To use AzureDevOps as the repository, you must first register an application in [Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application), and take note of the following information: +To use Azure DevOps Services as the repository, you must first register an application in [Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application), and take note of the following information: * Application ID (client ID) * Directory ID (tenant ID) @@ -188,7 +197,7 @@ For the API permissions, select **user_impersonation**. For the web callback URL, enter a URL in the following format: `YOUR_APP_ROOT/oauth-callback/`. -### Azure DevOps Configuration +#### Azure DevOps Configuration In Azure DevOps, perform the following tasks: @@ -197,27 +206,28 @@ In Azure DevOps, perform the following tasks: 3. Create users who will work with Private Mendix Platform. 4. Assign those users the Basic access level. -### Private Mendix Platform Configuration +#### Private Mendix Platform Configuration -* **Host URL** - The Azure DevOps Services URL, `https://dev.azure.com`. Azure DevOps Server (on-premises) is not supported. +* **Deployment Type** – Select **Azure DevOps Services (cloud)**. +* **Host URL** – The Azure DevOps Services URL, `https://dev.azure.com`. * **Organization** – Enter the name of the Azure DevOps organization that you created. * **Organization Admin PAT** – Enter the Personal Access Token of the Azure DevOps organization admin user. -#### Azure OAuth Config +##### Azure OAuth Config 1. Click **New**. 2. Fill out the following information: - * **Name** - Enter a meaningful name for the OAuth configuration. - * **Client ID** - Enter the Application ID that you obtained from Microsoft Entra ID. - * **Tenant ID** - Enter the Directory ID that you obtained from Microsoft Entra ID. - * **Client Secret** - Enter the Client Secret that you obtained from Microsoft Entra ID. - * **Resource** - Enter the following value: `499b84ac-1321-427f-aa17-267ca6975798/.default`. - * **Single OAuth Account** - Set to **No**. - * **Default config** - Set to **Yes**. - * **Active** - Set to **Yes**. + * **Name** – Enter a meaningful name for the OAuth configuration. + * **Client ID** – Enter the Application ID that you obtained from Microsoft Entra ID. + * **Tenant ID** – Enter the Directory ID that you obtained from Microsoft Entra ID. + * **Client Secret** – Enter the Client Secret that you obtained from Microsoft Entra ID. + * **Resource** – Enter the following value: `499b84ac-1321-427f-aa17-267ca6975798/.default`. + * **Single OAuth Account** – Set to **No**. + * **Default config** – Set to **Yes**. + * **Active** – Set to **Yes**. -#### Normal User Credentials +##### Normal User Credentials Users must generate their own PAT to work with Azure DevOps by doing the following steps: @@ -227,4 +237,191 @@ Users must generate their own PAT to work with Azure DevOps by doing the followi 4. On the Microsoft login screen, input you Azure user credentials to verify and authorize the app. 5. Wait for the PAT and Azure user email to be displayed on the **Service Credentials** page in Private Mendix Platform. -{{< figure src="/attachments/private-platform/pmp-vc5.png" alt="Version Control Settings for Azure DevOps" class="no-border" >}} +{{< figure src="/attachments/private-platform/pmp-vc5.png" alt="Version Control Settings for Azure DevOps Services" class="no-border" >}} + +### Azure DevOps Server (On-Premises) {#azure-devops-server} + +With Azure DevOps Server, Private Mendix Platform creates one project with one Git repository for every app in a project collection of your server, manages the members of that project, shows branches and commits, and builds apps with the Kubernetes build method. All calls use PATs over HTTPS and go to your server only. + +#### Prerequisites + +Before configuring Azure DevOps Server for Private Mendix Platform, ensure that you fulfill the following prerequisites: + +* Azure DevOps Server 2022.1 or above (REST API 7.1). Versions 2022.1 and 2022.2 are tested. Earlier versions are not supported. +* A project collection that hosts the apps created by Private Mendix Platform. Each app gets its own project. +* A dedicated service account (not a personal account) that is a member of **Project Collection Administrators** of that collection, with a PAT (see [Personal Access Tokens](#ado-server-pats)). +* Private Mendix Platform can reach the server over HTTPS. The server certificate contains the host name of the Host URL in its Subject Alternative Name (SAN). +* If the server certificate is not issued by a public certificate authority (CA): the issuing CA certificate in PEM format (see [Certificates](#ado-server-certificates)). +* For Kubernetes builds: the requirements in [Azure DevOps Server Builds](/private-mendix-platform/configure-k8s/#azure-devops-server). + +#### Private Mendix Platform Configuration + +* **Deployment Type** – Select **Azure DevOps Server (on-premises)**. +* **Host URL** – The server URL without the collection, in the format `https://`, optionally with a port and a virtual directory, for example `https://ado.example.com` or `https://ado.example.com/tfs`. There is no slash at the end. +* **Collection** – The name of the project collection, for example `DefaultCollection`. +* **Organization Admin PAT** – The PAT of the service account. You can also store it in an external secret store (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault). + +When you save, Private Mendix Platform checks the connection, the server type and the PAT, and shows an error code if the check fails (see [Troubleshooting](#ado-server-troubleshooting)). The **Azure OAuth Config** section is not used for Azure DevOps Server and is hidden. + +{{% alert color="warning" %}} +Use HTTPS. An `http://` Host URL is accepted, but the PATs are then sent unencrypted; Private Mendix Platform logs a warning. +{{% /alert %}} + +{{< figure src="/attachments/private-platform/pmp-vc6.png" alt="Version Control Settings for Azure DevOps Server" class="no-border" >}} + +#### Personal Access Tokens {#ado-server-pats} + +| PAT | Owner | Scopes | +| --- | --- | --- | +| Organization Admin PAT | The service account | Project and Team (Read, write & manage); Code (Read, write & manage); Identity (Read & manage) | +| Users' PAT | Each user, their own account | Code (Read & write); Project and Team (Read) | + +A PAT works only in the collection where it was created. A PAT is checked when it is saved; if it expires or is revoked later, Git actions and builds fail with an authentication error (AZ003) until a new PAT is entered. + +Recommended PAT policy: + +* Create the Organization Admin PAT for a dedicated service account that is a member of **Project Collection Administrators** only. Grant exactly the scopes in the table, never full access. Choose the longest lifetime your policy allows, at most one year, and replace the PAT in Private Mendix Platform before it expires. Azure DevOps adds the account that creates a project to that project's default team, so this account appears as a member of every app project that Private Mendix Platform creates; with a personal account, that person appears in every project and the PAT stops working when they leave. +* Users' PATs need the scopes Code (Read & write) and Project and Team (Read) only. When a user's PAT expires, Git actions and builds of that user fail with AZ003 until the user enters a new PAT. +* Private Mendix Platform never exports PATs and never writes them to logs. + +#### Normal User Credentials + +Each user creates a PAT of their own account in Azure DevOps Server (**User settings** > **Personal access tokens**, on the collection used by Private Mendix Platform) and enters it in Private Mendix Platform: + +1. Log in to Private Mendix Platform. On the first login, enter the PAT on the welcome page; later, click **Manage My Account** > **Service Credentials** > **Register New Credentials** > **Azure DevOps**. +2. Enter the **Personal Access Token** and save. + +Private Mendix Platform validates the PAT and stores the account name that the server reports for it. This account name is what Private Mendix Platform adds to the project groups when the user gets a role on an app. The **Get My Azure PAT** button is not available for Azure DevOps Server. + +#### Certificates {#ado-server-certificates} + +If the server certificate is issued by a private or internal CA, add the CA certificate to the trust of Private Mendix Platform, using the Mendix runtime setting `CACertificates` or the Mendix Operator custom CA secret. The certificate must contain the host name of the Host URL in its SAN. Without trust, saving fails with AZ005. + +On Kubernetes with the Mendix Operator, follow these steps: + +1. Save the CA certificate (PEM) of the Azure DevOps Server as `ado-ca.crt`. +2. If a custom CA secret is already configured (`spec.trust.customCASecretName` in the Operator configuration), append the new certificate to the existing bundle, so that the CAs already in it stay trusted. Replace `NAMESPACE` with the namespace of Private Mendix Platform, and the secret name if yours differs: + + ```text + kubectl -n NAMESPACE get secret mendix-custom-ca -o jsonpath='{.data.custom\.crt}' | base64 -d > bundle.crt + printf '\n' >> bundle.crt + cat ado-ca.crt >> bundle.crt + kubectl -n NAMESPACE create secret generic mendix-custom-ca --from-file=custom.crt=bundle.crt --dry-run=client -o yaml | kubectl -n NAMESPACE apply -f - + ``` + +3. If no custom CA is configured yet, create the secret and set `spec.trust.customCASecretName` as described in [Obtaining and Configuring the CA Certificate](/private-mendix-platform/configure-k8s/#ca-certificate). +4. Restart Private Mendix Platform (`kubectl -n NAMESPACE rollout restart deployment/mxplatform-master`) and save the Version Control settings again. + +The build pods do not read this secret; see [Azure DevOps Server Builds](/private-mendix-platform/configure-k8s/#azure-devops-server). + +#### Studio Pro and Windows Authentication {#ado-server-studio-pro} + +Developers open an app with **Edit in Studio Pro**. Private Mendix Platform gives Studio Pro the repository URL and the user's PAT; Studio Pro then does all Git work itself, directly against Azure DevOps Server. Studio Pro uses two Git clients, LibGit2Sharp (inside Studio Pro) and Git for Windows. Both must trust the server certificate, and both follow the setting **Edit** > **Preferences** > **Version control** > **Git** > **Enable Current Windows User Authentication for Git**. The setting is off by default and must match what your server offers. + +To find out what your server offers, request the collection URL without credentials and read the `WWW-Authenticate` header: + +```text +curl.exe -k -sS -o NUL -D - https://YOUR-SERVER/YOUR-COLLECTION/_apis/projects | findstr /i www-authenticate +``` + +| The Server Offers | Enable Current Windows User Authentication for Git | Git Setting on the Windows Machine | What Signs In to Git | +| --- | --- | --- | --- | +| Negotiate and NTLM (Windows authentication on, the default) | **On** | `git config --global http.emptyAuth true` | The signed-in Windows user. The machine must be joined to the domain, and the Windows account must be the account of the PAT saved in Private Mendix Platform. The PAT is not sent to the server. | +| Bearer and Basic only (Windows authentication off) | **Off** | None | The PAT from the user's Private Mendix Platform profile | + +{{< figure src="/attachments/private-platform/pmp-vc7.png" alt="Studio Pro preferences, Version control, Git" class="no-border" >}} + +To set up a Windows machine (once per Windows user, or by group policy), follow these steps: + +1. Trust the server certificate in Windows. Skip this step if the certificate is from a public CA or your company CA is distributed by group policy. Otherwise, import the CA certificate (or the self-signed server certificate) into **Trusted Root Certification Authorities** of the current user; no administrator rights are needed: + + ```text + Import-Certificate -FilePath .\ado-ca.cer -CertStoreLocation Cert:\CurrentUser\Root + ``` + +2. Let Git for Windows use the Windows certificate store. Git for Windows has its own CA list and rejects your CA even after step 1: + + ```text + git config --global http.sslBackend schannel + ``` + +3. For Windows authentication only: let Git use the signed-in Windows user, and select the **Enable Current Windows User Authentication for Git** checkbox in Studio Pro. Studio Pro gives Git no credential in this mode; without this setting Git asks its credential helper, which cannot prompt inside Studio Pro, and fails with exit code 128: + + ```text + git config --global http.emptyAuth true + ``` + +4. For Basic only: leave the checkbox cleared and do not set `http.emptyAuth`. +5. Restart Studio Pro and open an app from the app list. + +{{< figure src="/attachments/private-platform/pmp-vc8.png" alt="Studio Pro setting per server type and the messages for mismatches" class="no-border" >}} + +If opening the app fails, check the following messages. The Git output of Studio Pro is in `%LOCALAPPDATA%\Mendix\log\\git\git.log.txt`. + +| Message | Cause | What to Do | +| --- | --- | --- | +| *user canceled certificate check* | Windows does not trust the server certificate | Step 1 | +| *SSL certificate problem: self-signed certificate* (in the Git log) | Git for Windows uses its own CA list | Step 2 | +| *Git command line client has exited with code 128*, with *terminal prompts disabled* in the Git log | Git got a 401 and no credential | Windows authentication server: step 3. Basic-only server: clear the checkbox | +| *too many redirects or authentication replays* | The checkbox is cleared and the server offers NTLM, so the PAT was answered with NTLM | Select the checkbox and set `http.emptyAuth true` | +| *Git command line client has exited with code 128*, with *couldn't find remote ref refs/notes/mx_metadata* in the Git log | The repository was pushed with plain Git and has no Studio Pro notes yet; not an authentication error | Commit and push once from Studio Pro | +| 401 or 403 after a successful connection | The Windows account is not the account of the PAT saved in Private Mendix Platform, or the user has no role with Git access on the app | Save a PAT of the Windows account; check the app role | + +{{% alert color="info" %}} +A PAT cannot be used against a server that offers NTLM: Studio Pro's Git library answers NTLM and the PAT fails. Use Windows authentication in that case. Windows authentication uses Kerberos when the client can obtain a ticket and NTLM otherwise; the settings above are the same for both. Kerberos needs a service principal name (SPN) for the host name that users type, registered for the identity of the Azure DevOps application pool. +{{% /alert %}} + +For the Azure DevOps Server administrator: Windows authentication is a setting of the IIS site and, on servers with the `/tfs` virtual directory, also of that application; the application setting wins. If you change it, check both levels and confirm the result with the `curl` command above. Private Mendix Platform itself does not need Windows authentication; it signs in with PATs. + +#### Repository Membership + +Private Mendix Platform manages access to each app's project with the Organization Admin PAT: + +* Access follows the app roles in Private Mendix Platform. A user gets repository access through a role that includes Git access, either given directly on the app (creator, invite, ownership transfer) or inherited from the group that owns the app when that group has auto-invite enabled. Group changes are synchronized in the background. +* An app Owner or a company administrator becomes a member of **Project Administrators**; every other role with Git access becomes a member of **Contributors**. **Readers** is not used. Changing the role moves the user to the new group and removes the old one. +* Removing a member removes the user from these groups and from the project's default team. Access that the user gets through other groups you set up in Azure DevOps stays. +* To open and push in Studio Pro, a user needs Read and Contribute on the repository, which **Contributors** gives. No project or collection administrator role is needed. +* Only Mendix app projects are changed: projects that Private Mendix Platform created, and existing projects that hold exactly one repository with an `.mpr` file (apps added with Import Apps). Other projects are never changed. +* Azure DevOps Server can only find users it already knows, that is, users who signed in or used a PAT before, or who are members of a group in the collection (for example an Active Directory group). For other users, Private Mendix Platform logs a warning and changes nothing; a direct invite is canceled. +* A user must have saved their own PAT in Private Mendix Platform before they can be added to a project, because the saved PAT provides the account name. The account forms `DOMAIN\user`, the plain account name and the email address are accepted; a name that matches more than one person is refused. + +To manage project access only in Azure DevOps, set the constant `AzureDevopsIntegration.ServerManageMembership` to `false`. Private Mendix Platform then changes no groups and logs each skipped change. + +#### Settings Export and Import + +The settings export contains the deployment type, the Host URL and the collection. PATs are never exported; enter them again after the import. + +#### Advanced Settings + +| Constant | Default | Use | +| --- | --- | --- | +| `AzureDevopsIntegration.HttpConnectTimeoutMs` | 10000 | Time to open a connection to the server, in milliseconds (at most 600000) | +| `AzureDevopsIntegration.HttpRequestTimeoutMs` | 30000 | Time to wait for an answer, in milliseconds (at most 600000) | +| `AzureDevopsIntegration.ServerManageMembership` | true | `false` = do not change project groups (see Repository Membership) | + +##### Outbound Proxy + +Only the Java proxy properties (`https.proxyHost`, `https.proxyPort`, `http.nonProxyHosts`) are used; proxy authentication is not supported. Redirects are not followed; use the final URL as the Host URL. + +#### Troubleshooting {#ado-server-troubleshooting} + +| Code | Meaning | What to Do | +| --- | --- | --- | +| AZ003 | Authentication failed | Check that the PAT is valid, not expired, created on this collection, and has the required scopes | +| AZ004 | Server unreachable or no answer in time | Check the Host URL, port, firewall and proxy; raise the timeouts for a slow server. The first request after a server restart can be slow; retry once | +| AZ005 | Certificate not trusted | Add the issuing CA (see [Certificates](#ado-server-certificates)); check the SAN | +| AZ006 | The URL is Azure DevOps Services, but Azure DevOps Server is selected | Select the matching deployment type | +| AZ007 | The server answered with a redirect | Use the final URL (for example `https`) as the Host URL | +| AZ008 | Collection, project or repository not found | Check the Host URL and the collection | +| AZ009 | Request not supported | Use Azure DevOps Server 2022.1 or above | +| AZ010 | Server error, or the configuration could not be read | Check the server and the Private Mendix Platform log, then retry | +| AZ011 | Invalid value | Check the Host URL and the collection | + +#### Limitations + +* The **Azure DevOps** CI build utility is not supported with Azure DevOps Server; use the Kubernetes build method (see [Azure DevOps Server Builds](/private-mendix-platform/configure-k8s/#azure-devops-server)). +* An outbound proxy that requires authentication is not supported. +* Studio Pro cannot use a PAT against a server that offers NTLM; use Windows authentication. +* As with the other version control systems, repository access is not removed when a Private Mendix Platform user is deactivated, blocked or deleted, or when an identity provider group claim is removed. Remove the user from the app or group in Private Mendix Platform first, or remove the user from the Azure DevOps project by hand. +* Kubernetes builds clone the repository with the PAT of the user who starts the build (Basic authentication); that user needs read access to the repository. +* One Azure DevOps configuration per Private Mendix Platform instance. All apps of the instance use the same server and collection. \ No newline at end of file diff --git a/content/en/docs/private-platform/pmp-prerequisites.md b/content/en/docs/private-platform/pmp-prerequisites.md index 1875123a39e..4c86862416a 100644 --- a/content/en/docs/private-platform/pmp-prerequisites.md +++ b/content/en/docs/private-platform/pmp-prerequisites.md @@ -396,6 +396,7 @@ Private Mendix Platform must connect to services within your premises. Mandatory | Version control | GitHub Enterprise Server | 3.6 or higher | Required for projects and collaboration | | Version control | Bitbucket | Latest | Required for projects and collaboration | | Version control | Azure DevOps Services | Cloud | Required for projects and collaboration | +| Version control | Azure DevOps Server (on-premises) | 2022.1 or higher | Required for projects and collaboration | | CI/CD | Kubernetes | See See [Supported Cluster Types](#supported-clusters) | Default for CI/CD | | CI/CD | Jenkins | 2.346.1 or newer, with support for the Docker agent | Required for CI/CD | | CI/CD | Azure DevOps | Latest | Required for CI/CD | diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index 9bed8b3e3e5..f2c729001af 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -614,7 +614,12 @@ When configuring secret management, keep in mind the following key points: roleArn: "arn:aws:iam::123456789012:role/component-role" # Step 2: Configure Secret Provider Class secretProviderclass: - enable: true + enable: false + # Set to false to bring your own SecretProviderClass. The chart then skips rendering it and all provider parameters below are ignored. Your SecretProviderClass must be named after the MendixApp (, or -test when testApp is true), live in the same namespace and carry the annotation privatecloud.mendix.com/environment-class: "true" + create: true + database: + # When true, the chart doesn't request database-password from the secret store. The database is reached through the pod's identity (Azure Workload Identity or AWS IRSA) + passwordless: false provider: "azure" # azure | aws | vault # For Azure Key Vault azureparameters: diff --git a/content/en/docs/private-platform/reference/_index.md b/content/en/docs/private-platform/reference/_index.md index 36a58e3e825..dcdb533a0cc 100644 --- a/content/en/docs/private-platform/reference/_index.md +++ b/content/en/docs/private-platform/reference/_index.md @@ -4,6 +4,8 @@ linktitle: "Administrator Guide" url: /private-mendix-platform/reference-guide/admin/ description: "Provides details on the features and functionality of the Private Mendix Platform that are available to administrators." weight: 10 +no_list: false +description_list: true aliases: - /private-mendix-platform-administration/ - /private-mendix-platform/administration/ @@ -28,3 +30,5 @@ Private Mendix Platform distinguishes between the following types of administrat * Systems admin - This role primarily manages key settings which must be configured during the initial implementation, and which are rarely modified during normal operation. Settings relevant for systems admins are available in the [Settings](/private-mendix-platform/reference-guide/admin/system/#settings) section of the admin navigation menu. {{< figure src="/attachments/private-platform/pmp-admin4.png" class="no-border" >}} + +## Read More diff --git a/content/en/docs/private-platform/reference/manage/_index.md b/content/en/docs/private-platform/reference/manage/_index.md new file mode 100644 index 00000000000..0390b65941e --- /dev/null +++ b/content/en/docs/private-platform/reference/manage/_index.md @@ -0,0 +1,26 @@ +--- +title: "Private Mendix Platform Functionalities - Company Administrators" +linktitle: "Company Administrators" +url: /private-mendix-platform/reference-guide/admin/company/ +description: "Provides details on the features and functionality of the Private Mendix Platform that are available to company administrators." +weight: 10 +no_list: false +description_list: true +--- + +## Introduction + +In Private Mendix Platform, company administrators primarily manage business-as-usual tasks, for example inviting new users to an app, or approving Marketplace contents. Settings relevant for company admins are available in the [Manage](#manage) section of the admin navigation menu. + +### Manage {#manage} + +The **Manage** section of the administrator navigation menu contains settings relevant to your day-to-day tasks as a company admin. You can use it to manage your company apps, users and groups, Marketplace contents, and deployment clusters. + +## Accessing the Configuration Settings + +As a user with company administrator access rights, you can access the Private Mendix Platform configuration settings by performing the following steps: + +1. Switch to Admin Mode by clicking the profile picture in the top right corner of the screen and selecting **Switch to Admin Mode**. +2. In the left navigation menu, open the **Manage** section. + +## Read More diff --git a/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-deployment.md b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-deployment.md new file mode 100644 index 00000000000..171f41f6a6f --- /dev/null +++ b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-deployment.md @@ -0,0 +1,43 @@ +--- +title: "Company Administrator Settings - Deployment" +linktitle: "Deployment" +url: /private-mendix-platform/admin-company/deployment/ +description: "Provides details on the deployment settings that are available to company administrators." +weight: 30 +--- + +## Introduction + +In the **Deployment** section, administrators can manage existing clusters and register new ones. + +## Cluster Manager + +The **Cluster Manager** page allows administrators to configure clusters to be used in their devOps CI/CD pipelines. To configure a cluster, perform the following steps: + +1. In **Switch to Admin Mode** > **Manage** > **Cluster Manager**, click **Register New Cluster**. +2. Configure the following values: + + * **Cluster Name** – Specify a name for the cluster. + * **Cluster type** – Select the cluster type. **Kubernetes** is recommended. + * **API Server** – Specify your API server. + * **Token** – You must first create a service account, cluster role, and cluster role binding in the cluster, and then get the service account's token. For an example, see [Configuring Build Cluster Setting](/private-mendix-platform/configure-k8s/#build-cluster). + * **Enable Logging and Monitoring** – Specify whether Grafana and Prometheus monitoring should be enabled for this cluster. + * **Package Type** – For Kubernetes and Manual Production Deployment, select the type of package that will be uploaded to environments in this cluster. + * **S3 Endpoint** – For Kubernetes and Manual Production Deployment, specify the S3 endpoint, for example, `Cloud Object Storage - Amazon S3 - AWS`. + * **S3 Bucket Name** – For Kubernetes and Manual Production Deployment, specify the S3 bucket name, for example, `mybucket`. + * **Region** – For Kubernetes and Manual Production Deployment, specify the region, for example, `ap-southeast-1`. + * **Access Key ID** – For Kubernetes and Manual Production Deployment, this ID value is used to access the S3 bucket. + * **Secret Access Key** – For Kubernetes and Manual Production Deployment, this secret key value is used to access the S3 bucket. + +3. Click **Save**. +4. Click the newly created cluster and expand it, and then click **Retrieve Namespace(s)** to retrieve all the namespace and storage plans, or **Manually Register Namespace**. + + Namespaces without any storage plan are skipped. This step requires the Mendix Operator to be installed and configured. You can repeat this step as required to retrieve additional namespaces. + +5. After the cluster is registered, create environments with the cluster, namespace and plans. + +### Configuring CI/CD Pipelines with Manual Approval {#manual-deployment} + +If your production and development environments must be fully air-gapped and separated from each other, and you want to limit the ability to deploy packages to either selected users or an automated pipeline with manual approval, you can configure your cluster type to be **Manual Production Deployment**. + +Selecting this option allows you to specify an S3 bucket. This bucket is then used as the destination where the deployment package is uploaded at the end of the pipeline, instead of being deployed to the production environment. Designated approvers can then retrieve the package from the S3 bucket and manually deploy it to the target environment. diff --git a/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-marketplace.md b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-marketplace.md new file mode 100644 index 00000000000..1d8531fcb18 --- /dev/null +++ b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-marketplace.md @@ -0,0 +1,88 @@ +--- +title: "Company Administrator Settings - Marketplace" +linktitle: "Marketplace" +url: /private-mendix-platform/admin-company/marketplace/ +description: "Provides details on the Marketplace configuration settings that are available to company administrators." +weight: 20 +--- + +## Introduction + +In the **Marketplace** section, administrators can manage various settings related to the content available on the Private Platform Marketplace. The Private Platform Marketplace is a local version of [Mendix Marketplace](/appstore/), enclosed entirely within the Private Platform. Developers in your organization can also create their own modules, connectors, and sample apps, and share them on the Private Platform Marketplace to make them available to other users. + +As the administrator, you can perform the following actions: + +## Content Management {#content} + +In the **Content Management** tab, you can view the Marketplace content that your users have already published, as well as any items which are pending approval, or which have been rejected. + +{{< figure src="/attachments/private-platform/pmp-admin7.png" class="no-border" >}} + +You can click on an item to view more information about it, download, approve, or delete it. + +## Taxonomy Management + +In the **Taxonomy Management** tab, you can configure the supported Studio Pro versions and sub-categories that your users can select when creating Marketplace content. You can also view and edit the available licenses. + +{{< figure src="/attachments/private-platform/pmp-admin8.png" class="no-border" >}} + +### Supported Versions + +The versions listed on the **Supported Versions** page indicate the Mendix Studio Pro versions that a Marketplace content item is compatible with. Users can select these versions from a list when uploading new Marketplace content. + +### Licenses + +The **Licenses** tab allows administrators to specify the licenses that are available to their apps. To add a new license, click **New License** and specify the following values: + +* **Name** – Name of the license +* **URL** – URL at which the license can be accessed +* **Contents** – Optional additional information about the license. + +### App Categories + +In the **App Categories** tab, you can view the predefined categories that users can specify for their Marketplace content items. You can also add custom categories, for example, for Marketplace contents related to a specific project. + +Predefined app categories cannot be edited or deleted. To edit or delete a custom category, click the **Action** menu, and then select one of the available options. + +## Import Content + +You can populate your private Marketplace with contents by importing a zip file that contains the content packages along with a *package.json* file. You can upload the file from a Content Delivery Network, or manually from your local machine. + +{{< figure src="/attachments/private-platform/pmp-admin9.png" class="no-border" >}} + +## Upload Marketplace Bundle {#manual-upload} + +To manually upload a content bundle from your own computer, perform the following steps: + +1. Download the Marketplace Bundle with contents available in a zip file. If you do not have access to the bundle, contact your Mendix point of contact. +2. In the **Import Content** > **Upload Marketplace Bundle** tab, drag and drop the file that you want to upload. + + * The file must be in *zip* format. + * The file must not be larger than 2048 MB. + * Your infrastructure must support the upload of large files (up to 2048MB). + * You should also have at least 40 GB available disk space to account for temporary files. + +3. Click **Import Marketplace Bundle components**. + + {{< figure src="/attachments/private-platform/pmp-config1.png" class="no-border" >}} + +4. To view the progress of your upload, click **View Task Queue**. + +{{% alert color="info" %}} +If you are experiencing high latency during manual uploads, you can increase the timeouts. For example, for nginx, you can perform the following commands: + +```text +nginx.ingress.kubernetes.io/client-header-timeout: "300" +nginx.ingress.kubernetes.io/proxy-connect-timeout: "300" +nginx.ingress.kubernetes.io/proxy-read-timeout: "300" +nginx.ingress.kubernetes.io/proxy-send-timeout: "300" +``` + +{{% /alert %}} + +## Import from CDN + +To import content from a Content Delivery Network, follow these steps: + +1. Ensure that your system administrator has [configured the Marketplace import bundle URL](/private-mendix-platform/reference-guide/admin/system/#configure-import). +2. In the **Import Content** > **Import from CDN** tab, view and download the available content items. diff --git a/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-platform.md b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-platform.md new file mode 100644 index 00000000000..d68ae5110b0 --- /dev/null +++ b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-platform.md @@ -0,0 +1,275 @@ +--- +title: "Company Administrator Settings - Platform" +linktitle: "Platform" +url: /private-mendix-platform/admin-company/platform/ +description: "Provides details on the Platform configuration settings that are available to company administrators." +weight: 50 +--- + +## Introduction + +In the **Platform** section, administrators can view and manage statistics, activity logs, webhooks, and licenses. + +## Platform Statistics + +In the **Platform Statistics** section, you can access statistics such as the number of users and apps, daily user login times and numbers, or most active users. + +## Activity Logs + +For auditing purposes, you can view a log of the most recent actions taken by users of the platform. + +Private Mendix Platform activity logs track actions that impact the state or configuration of the platform and its managed resources. This includes the following activities: + +* Creation – When a new resource or configuration is initiated. +* Update or modification – When an existing resource or configuration is changed. +* Deletion – When a resource or configuration is removed. +* State Changes – Significant transitions in the lifecycle of a resource (for example, publishing, retiring, archiving). +* Authentication – User login attempts. + +### Recent Actions + +The **Recent Actions** tab contains a list of the recent actions, logged for the time period specified in the **Log Settings** tab. It serves as a real-time monitoring tool for administrators to quickly view detailed information about each log entry, including the action performed, the user who performed it, the timestamp, and affected resources. + +The following actions are logged: + +* User management – Activities related to user accounts and their access within Private Mendix Platform: + + * User creation – New user accounts created + * User deletion – User accounts removed + * User profile updates – Changes to user details (for example, name, contact information) + * User role settings updates – Modifications to a user's assigned roles and permissions + * User login – Successful and failed login attempts + +* Role management – Activities related to the definition and modification of access roles: + + * Role creation – New custom roles defined + * Role deletion – Existing custom roles removed + * Role permissions updates – Changes to the permissions granted by a role across various scopes (Platform, group, project, environment, cluster, build, deploy, Marketplace contents) + +* Group management – Activities related to user groups and their association with resources: + + * Group creation – New user groups created + * Group deletion – Existing user groups removed + * Group settings updates – Modifications to group associations and permissions within projects, environments, clusters, build and deploy processes, and Marketplace contents + +* Project management – Activities related to the lifecycle and configuration of projects: + + * Project creation – New projects initiated + * Project archival and unarchival – Projects moved to or from an archived state + * Project deletion – Projects permanently removed + * Project settings updates – Changes to project configurations, owner, team members, or sharing settings + * Build and Deploy actions – Initiating builds or deployments of project applications + +* App package management – Activities related to app packages within projects: + + * App package build – Initiation and completion of application package builds + * App package lock or unlock – Changing the lock status of an app package. + * App package deletion – Removal of application packages + +* Environment management – Activities concerning the creation and configuration of deployment environments: + + * Environment creation – New deployment environments provisioned + * Environment deletion – Existing deployment environments removed + * Environment settings and configuration updates – Modifications to environment-specific settings (for example, variables, scaling, network configurations) + +* Marketplace management – Activities related to content within the Private Mendix Platform Marketplace: + + * Marketplace content creation – New Marketplace items (such as templates or components) added. + * Marketplace content deletion – Existing Marketplace items removed + * Marketplace version creation – New versions of Marketplace content published + * Marketplace content updates – Changes to content details, owner, group, or sharing settings + * Content state changes – Approval, decline, publishing, retiring, or unretiring of Marketplace content + +* Cluster management – Activities related to Kubernetes clusters and their configurations: + + * Cluster creation – New Kubernetes clusters provisioned + * Cluster deletion – Existing Kubernetes clusters decommissioned + * Namespace creation and deletion – Management of namespaces within clusters + * Plan creation and deletion – Management of cluster plans + * Updates to cluster, namespace, and plan settings and configuration – Modifications to cluster, namespace, or plan-specific settings + +* Pipeline management – Activities related to Continuous Integration/Continuous Delivery (CI/CD) pipelines: + + * Build pipeline template creation and deletion – Management of Build pipeline templates + * Deploy pipeline template creation and deletion – Management of Deployment pipeline templates. + * Pipeline step settings and configuration updates – Modifications to individual steps or configurations within Build and Deploy pipelines + +* General platform settings – Activities related to overarching platform capabilities and features: + + * Platform settings updates – Modifications to core platform capabilities and integrations + * Feature flag management – Toggling platform features **on** or **off**. + +You can use the **Search** field to search for a specific action by name. + +#### Generating Reports + +Private Mendix Platform administrators can generate time-bounded audit reports in multiple formats for review, submission to auditors, or integration with external SIEM systems. + +{{< figure src="/attachments/private-platform/pmp-manage-recent-logs.png" >}} + +To generate the report, perform the following steps: + +1. Click **Create Custom Report**. +2. In the **Create Custom Report** dialog, specify the following parameters: + + * **User action log level** – Select **Event**, **Summary**, or **Complete** + * **User action archive file type** – Select **PDF**, **Doc2007**, **JSON**, or **XML**. + * **Start date** and **End date** for the report. + +### Archived Actions + +To manage the volume of activity data, Private Mendix Platform automatically archives older logs. The **Archived Actions** tab allows users to access and download these historical records. + +Logs are archived at a period specified in the **Log Settings** tab. Users can download archived logs for offline review, auditing, or long-term storage. This ensures that a comprehensive historical record is always available. + +### Log Settings {#log-settings} + +The **Log Settings** tab provides granular control over how activity logs are managed and stored within Private Mendix Platform. Administrators can configure the following parameters to suit their organizational needs and compliance requirements: + +* **Number of days to retain user action logs backups** – Defines the duration (in days) for which user action log backups are retained within the system before being permanently deleted or moved to long-term storage. For example, a setting of 30 days means that backups are kept for one month. +* **Expose database entries from the logs as MXApp Log Nodes** – A toggle to determine whether raw database entries from the activity logs should be exposed or made available as MXApp Log Nodes, potentially for integration with Mendix application logging or advanced debugging. +* **User log timestamp output in preferred time zone** – Allows administrators to select the time zone for timestamps displayed in the user activity logs, ensuring that logs are presented in a locally relevant or standardized time zone. +* **User action log time unit** – Specifies the precision of the timestamps recorded for user actions. +* **User action log level** – Controls the verbosity or completeness of the information captured in the user action logs. +* **User action archive file type** – Defines the format in which archived user action logs are saved. +* **External backup target** – Allows administrators to configure an external system or location where activity log backups can be sent for additional redundancy or compliance. The following options are available: + + * **S3** – You must specify the endpoint, region, bucket, access key ID, and secret access key. + * **Azure Blob Storage** – Supports authentication with Azure Blob Managed Identity (AZWI), or with static credentials. + +* **External database target** – Provides an option to configure an external database where activity log data can be replicated or stored, potentially for advanced analytics or long-term data warehousing. +* **Send email when any audit logging fail** – A toggle to enable email notifications to administrators if there are any failures in the audit logging process, ensuring immediate awareness of potential data loss or compliance issues. + +#### External Backup Target Configuration for Azure Blob (AZWI) + +With Azure Blob (AZWI), Private Mendix Platform writes the logs to an external backup target with the managed identity of the Private Mendix Platform pod. The Mendix Operator creates this identity. Do not create another identity for this option. + +Before you save the Azure Blob (AZWI) settings, assign the following role: + +| Property | Value | +| --- | --- | +| Role | Storage Blob Data Contributor | +| Principal | Managed identity of the Private Mendix Platform pod | +| Scope | The container selected for Azure Blob (AZWI) | +| Granted by | Your infrastructure team | + +To find the Managed identity of the Private Mendix Platform pod, perform the following steps: + +1. Read the client ID from the platform ServiceAccount. The default name is `mxplatform`. If you set a different AppName during installation, use that name. + + ```text + kubectl -n get serviceaccount mxplatform -o jsonpath='{.metadata.annotations.azure\.workload\.identity/client-id}' + ``` + +2. In the Azure portal, open the storage account, and then the container. +3. Go to **Access Control (IAM) > Add role assignment**. +4. Select **Storage Blob Data Contributor**, assign it to the managed identity with that client ID, and set the scope to this container. + +## Webhooks {#webhooks} + +In the **Webhooks** tab, you can view and manage your webhooks. + +Webhooks allow you to send information about your licensed Mendix app deployed to Private Mendix Platform to an external app or workflow. You can use them to trigger a step in an automated [Build](/private-mendix-platform/reference-guide/admin/system/#build-steps) or [Deployment](/private-mendix-platform/reference-guide/admin/system/#deploy-steps) pipeline. + +Mendix provides webhooks to send project information about the following events: + +* App events: + + * App archived + * App created + * App deleted + * App info edited + * App logo edited + * App member added + * App member removed + * App owner edited + * App shared + * App unarchived + +* CI/CD events: + + * Package built + * Package deleted + * Package deployed + * Environment created + +* Marketplace events: + + * Item approved + * Item created + * Item declined + * Item edited + * Item imported + * Item owner edited + * Item shared + * Item version added + * Item version edited + +* User events: + + * Group admin updated + * Group created + * Group info edited + * Group member added + * Group member removed + * User blocked + * User created + * User info edited + * User unblocked + +The webhooks contain a retry mechanism if an error response is received from the endpoint. This helps ensure that the trigger reaches the endpoint. + +### Creating a New Webhook {#setting-up} + +To set up a webhook, do the following: + +1. In the **Platform Webhooks** tab of the **Webhooks** page, click **New Webhook**. +2. Enter the following information: + + * **Webhook Name** – This is a name which you can use to identify the webhook. + * **URL** – This is the endpoint that will receive the payload when one of the event types selected in **Available Events** occurs. + * **Validation Secret** – This is a secret that is shared with the endpoint to verify that it has been triggered by this webhook. If you leave this blank, a secret is generated automatically. You can see the generated value any time you return to edit the webhook. + * **Available Events** – This is the event (or events) that triggers the webhook to send information to the endpoint. You can activate or deactivate specific event types in the **Event Management** tab of the **Webhooks** page. + * **Custom Headers** – This is a key-value pair that is sent as an HTTP header to the endpoint. You can configure a predefined custom header in the **Preset Headers** tab of the **Webhooks** page. You cannot add custom HTTP headers through custom runtime settings. + +You can edit or delete an existing webhook by clicking **More Options** ({{% icon name="three-dots-menu-horizontal" %}}) in the **Action** column for the webhook you want to change, and then selecting **Edit** or **Delete**. + +### Webhook Headers + +Every `POST` payload contains the following delivery information as part of the header: + +* **connection** – `close`, indicating that there is no further information for the HTTP request +* **content-length** – the size of the HTTP request in bytes (for example, `475`) +* **webhook-signature** – the signature of the webhook in the format `,` (for example, `v1,Ay2spGBdE7i6OzNkFgTDnGfqgZT0WonCFoBMt8V3YiQ=`) +* **webhook-id** – a unique identifier for this webhook trigger (for example, `msg_2M605iBQRge9hTgpYg7fKXQubaw`) +* **user-agent** – the user agent used to process this trigger +* **webhook-timestamp** – the time the webhook was triggered (for example, `1677072542`) +* **content-type** – `application/json` +* **accept** – `*/*` +* **host** – the host part of the endpoint URL (for example, `gitlab.com`) + +You can also add your own custom headers. For more information, see [Configuring a Webhook](#setting-up). + +{{% alert color="info" %}} +The order of these headers is not guaranteed. +{{% /alert %}} + +## Licensing + +On this page, you can view the status of your Private Mendix Platform license, and upload a new license bundle if necessary. + +[Private Cloud License Manager](/developerportal/deploy/private-cloud/private-cloud-license-manager/) must be used to manage the Private Mendix Platform license. It can also be used to manage and provision your own app licenses. + +Private Mendix Platform licenses are either **valid** or **not found**; when not found, the Platform operates in developer mode, where access to some features and capabilities is restricted. + +{{< figure src="/attachments/private-platform/pmp-wizard2.png" class="no-border" >}} + +When valid, licenses can have the following statuses: + +* Active (shown in green) +* About to expire (shown in yellow) +* Expired (shown in red) + +## Maia + +On this page, you can connect Mendix AI Assistance (Maia) to your own Large Language Model (LLM). It enables Maia to use your custom LLM for processing and generating responses. For more information, see [Maia in Private Mendix Platform](/private-mendix-platform/maia/). diff --git a/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-users.md b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-users.md new file mode 100644 index 00000000000..e2fa579e65e --- /dev/null +++ b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage-users.md @@ -0,0 +1,89 @@ +--- +title: "Company Administrator Settings - Users" +linktitle: "Users" +url: /private-mendix-platform/admin-company/users/ +description: "Provides details on the user configuration settings that are available to company administrators." +weight: 40 +--- + +## Introduction + +In the **User Management** section, administrators can manage user accounts and user groups. + +{{< figure src="/attachments/private-platform/pmp-admin3.png" class="no-border" >}} + +As the administrator, you can perform the following actions: + +## User Management + +In the **User Management** tab, you can create and edit accounts for your local users and API users (that is, accounts that are used by an API service to access your Private Mendix Platform). By clicking **More Actions** ({{% icon name="three-dots-menu-horizontal" %}}) by an account, you can quickly perform a number of actions: + + * Edit a user's name and email + * Assign or remove user roles (local users only) + * Block a user + * Change a user's password + * Configure the language and time zone settings for a user (local users only) + * Log out a user (local users only) + * Delete a user account + +In the **Actions** tab, you can also log out all users currently logged in to your app. + +## Group Management + +In the **Group Management** tab, you can create and edit user groups. These groups typically reflect your organization's structure. You can also use the **Automation Settings** option to automatically assign users to groups based on their profile attributes. + +For more information about group management in Private Mendix Platform version 2.0 and newer, see [Dynamic Role Management in Private Mendix Platform](/private-mendix-platform/dynamic-role-management/). + +### Groups List + +The **Groups** section shows the group hierarchy in your organization. The section shows the root group, as well as any nested groups. Administrators can create and delete groups, view and edit group details, and adjust the group hierarchy. + +#### Creating a Group + +To create a new group, perform the following steps: + +1. In the **Group Management** page, click **Create a Group**. +2. Fill out the following information: + + * **Group Name** – Enter a unique name for this group. + * **Group Description** – Provide details about the group's purpose. + * **Parent Group** – Select the higher-level group this belongs to. + + When selecting the parent group, keep in mind that members of the parent group and all its parent groups automatically receive access rights to the new group, with the same role they hold in the parent. + + * **Group Admin** – Assign the user responsible for managing this group. + +3. Click **Create**. + +#### Viewing, Editing, or Deleting a Group + +To see more information about a group, click on its name in the group hierarchy. + +To delete a group, click **Delete Group** in the top right corner of the screen. The root group of the hierarchy cannot be deleted. + +To edit a group, click **Edit Group Details** and modify the group name, description, parent, or admin. For the root group of the hierarchy, you cannot change the parent group. + +The **Group Resources > Members** section shows a list of users who have access roles granted by this group. Access roles can be granted in the following ways: + +* Directly – For users who are members of this group. +* Indirectly – For users who are members of a parent group to which this group belongs. +* As a combination of both – For users who have both direct and indirect roles in this group. In this case, the roles are combined, and permissions apply cumulatively. + +The **Group Resources > Resource** section shows a list of apps, components, and namespaces owned by this group, or by its child groups. Apps and components inherited from child groups are indicated by the **Inherited** label. + +#### Editing the Group Hierarchy + +To edit the group hierarchy, click **Edit Group Hierarchy**, and then drag and drop the group cards as required. The root group of the hierarchy cannot be moved. + +#### Automating Group Assignments + +If you have enabled SSO access through an identity provider such as OIDC, you can configure Private Mendix Platform to automatically create and assign groups for SSO users. + +1. In the **Settings > Identity > Identity and Access** section of the Admin menu, configure an Identity Provider (IdP). + + For more information, see [Identity and Access](/private-mendix-platform/admin-system/integrations/#identity). + +2. In the **Group Management** page, click **Group Automation Settings**. +3. Select which user profile attributes to use when creating or assigning groups for users logging in through SSO. + + For example, you can automatically assign users from the same team to a specific group. \ No newline at end of file diff --git a/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage.md b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage.md new file mode 100644 index 00000000000..a83f4c7bff4 --- /dev/null +++ b/content/en/docs/private-platform/reference/manage/pmp-ref-admin-manage.md @@ -0,0 +1,155 @@ +--- +title: "Company Administrator Settings - Apps" +linktitle: "Apps" +url: /private-mendix-platform/admin-company/apps/ +description: "Provides details on the apps configuration settings that are available to company administrators." +weight: 10 +--- + +## Introduction + +The **Apps** section of the navigation menu lets administrators manage their apps. + +## App Management + +On the **App Management** page, you can view a summary of your apps. + +{{< figure src="/attachments/private-platform/pmp-admin1.png" class="no-border" >}} + +By clicking **More Actions** ({{% icon name="three-dots-menu-horizontal" %}}) in the **Action** column, you can quickly perform a number of actions: + +* [Edit app details](#app-details) +* [Assign the app to a new owner](#ownership) +* [Share the app with groups](#share) +* [Archive the app](#archive) +* [Delete the app](#delete) + +### Editing App Details {#app-details} + +Company admins can edit app details such as the app branding or ownership, team membership, and others. + +1. In the **App Management** page, in the **Action** column, click **More Actions** > **Edit**. +2. Configure any of the following settings: + +* **App Details** – Configure the following basic app details: + * **App ID** – An automatically assigned internal ID. This value cannot be adjusted. + * **Name** – The name of your app. This value should be meaningful, so that users can easily identify the app. + * **Description** – An optional description of the application. + * **App Logo** – A browser logo for your app. This value can only be adjusted by the app owner. +* **Team Membership** – Invite users to join your app, or remove them from the app. Before you can invite a user, you must first configure their account on the [User Management](#users) page. + + When adding a member, the dialog displays any roles inherited from groups. If the user is not a member of any groups, the dialog shows **NONE**. + +* **Git Server** – View the revisions per branch for this app. +* **Ownership and Sharing** – Select the user and optionally the group that owns this app. If an app is owned by a specific group, the owner must be a user who belongs to that group. + +### Assigning the App to a New Owner {#ownership} + +Each app is owned by a specific user, who can change settings such as the application branding (logo). By default, the owner is the user who created the app. To transfer the ownership to another user, on the **App Management** page, in the **Action** column, click **More Actions** > **Transfer Ownership**. Alternatively, you can access the same option in the **Ownership and Sharing** tab of the [App Details](#app-details) page. + +In addition to specifying the owner, you can also assign ownership of the app to a specific group. If an app is owned by a group, the owner must be a user who belongs to that group. + +{{% alert color="info" %}} +Ownership of Private Mendix Platform apps created through Studio Pro is automatically given to the `Mendix` root user group. If required, you can transfer the ownership to another group after creation. +{{% /alert %}} + +### Sharing the App with Selected User Groups {#share} + +You can share your app with any user groups by selecting the **More Actions** > **Share with Groups** option from the **App Management** page. Sharing makes the app visible to groups that otherwise may not be able to see or access your app. Members of the group with which you have shared the app do not have automatic access. Instead, they can request access from the app's owner. + +### Archiving the App {#archive} + +If an app is not needed for a time, you can archive it. An archived app is no longer available to users, but its data is still stored, and it can be quickly un-archived if required. + +To archive an app, on the **App Management** page, in the **Action** column, click **More Actions** > **Archive App**. To reactivate an archived app, select **Unarchive App** from the same menu. Alternatively, you can access the same options on the [App Details](#app-details) page. The app is archived or unarchived immediately. + +### Deleting the App {#delete} + +If the app is no longer needed and you do not want to store its data, you can delete it. Deleting an app removes its repository, so that it cannot be restored afterwards. To delete an app, click **Delete App** on the [App Details](#app-details) page. + +You will be warned of the consequences and asked for confirmation before the app is deleted. + +## Software Composition {#software-composition} + +The **Software Composition** page provides visibility into the component dependencies in each app environment. The components displayed here are based on the [Software Bill of Materials (SBOM)](/refguide/sbom-generation/). + +### Overview + +On the **Overview** tab, you can see a list of all the deployed apps and their environments, if applicable. You can also see the number of findings for each severity level. + +The **Insights** cards display the number of findings across all environments, broken down by severity level. For example, if a build package contains one critical finding and is deployed to the test and production environments, two findings are added to **Insights**. + +Each card also displays a rolling average of how the number of findings has evolved over the past 30 days, expressed as a percentage. + +The app list contains the following information: + +* **App Name** – The name of the app. Clicking this opens the **Application Environment Summary** page, if it is available. +* **Environment** – The name of the environment. +* **Purpose** – The purpose of the environment (Development, Test, Acceptance, or Production). +* **Runtime** – The Mendix Runtime version. Unsupported versions of the Mendix Runtime display a warning. +* **Owner** – The owner of the app. +* **Cluster** – The type of cluster where the environment is deployed. +* **Findings** – The number of findings of each type. +* Column customization ({{% icon name="view" %}}) – You can customize the columns in the list by clicking the {{% icon name="view" %}} icon and selecting or deselecting options. + +### Components + +The **Components** tab gives an overview of all the unique components used across your app landscape. + +The component list contains the following information: + +* **Component** – The name of the component. Clicking this opens the **Component Details** page. +* **Type** – The type of component, which can be one of the following: + + * **Module** – Standard module imported from the Marketplace, such as [Community Commons](https://marketplace.mendix.com/link/component/170), or a module created by the developer. + * **Widget** – User interface elements downloaded from the Marketplace, such as [Charts](https://marketplace.mendix.com/link/component/105695), or a widget created by the developer. + * **Framework** – The Mendix Runtime version, for example 10.12.0 + * **Jar** – Java libraries imported into your app using [Managed Dependencies](/refguide/managed-dependencies/), or those manually added in the **userlib** folder depending on the Studio Pro version used, such as `org.apache.commons.io`. + * **npms** – `npm` libraries that are used in your [JavaScript actions](/refguide/javascript-actions/). + * **Unknown** – When the type of the component is none of the above and hence undetermined. + +* **Support** – The support type of the Marketplace component. This can be **Mendix**, **Partner**, or **Community**. +* **Version** – The version of the component that is being used. +* **Findings** – The number of findings of each type, color-coded according to severity level. +* **Apps using component** – The number of apps where the component is used. +* **License** – For components derived from the Mendix Marketplace, this is the end-user license for the component. +* Column customization ({{% icon name="view" %}}) – You can customize the columns of the list by clicking the {{% icon name="view" %}} icon and selecting or deselecting options. + +### Findings + +The **Findings** tab allows you to view a list of all the findings discovered in your apps. A finding represents an issue identified in the components of an app. + +The findings are divided into the following types: + +* Vulnerable – A finding is generated when a component is published on the [Security Advisories](/releasenotes/security-advisories/) page, and is assigned a specific CVSS score. CVSS scores are based on the [NVD Vulnerability Metrics](https://nvd.nist.gov/vuln-metrics) framework, and cannot be orverriden. +* Outdated – A finding is generated when a component becomes outdated, meaning when a new runtime compatible version is published. +* Deprecated – A finding is generated when a component has been labeled as deprecated in the Private Marketplace. + +These are the severity levels of a finding: + +* **Critical** +* **High** +* **Medium** +* **Low** + +### Scoring Criteria + +The **Scoring Criteria** tab allows you to adjust the conditions and severity for each type of finding. Scoring criteria reflect your company's risk preference. + +The settings on this tab determine how each such vulnerability is calculated for apps, environments, and components. + +The types of findings that you can adjust for are **Outdated** and **Deprecated**. For outdated components, you can adjust all severity levels. For deprecated components, you can choose which severity level to assign. + +## Import Apps + +On the **Import Apps** page, administrators can import existing Mendix apps that are in their version control host but not yet in Private Mendix Platform. The import currently supports the following hosts: + +* GitLab +* GitHub +* Bitbucket +* Azure DevOps Services (cloud, `dev.azure.com`) +* Azure DevOps Server (on-premises). A project is listed when it has exactly one repository (the default repository, named like the project) with an `.mpr` file in its root, that your Personal Access Token can read, and that is not yet linked to an app. After the import, the app behaves like an app created in Private Mendix Platform; deleting the app deletes the Azure DevOps project. + +{{< figure src="/attachments/private-platform/pmp-admin6.png" class="no-border" >}} + +The list of apps on the page is not refreshed automatically. To refresh it, click the **Scan for Apps** button. diff --git a/content/en/docs/private-platform/reference/pmp-ref-admin-manage.md b/content/en/docs/private-platform/reference/pmp-ref-admin-manage.md deleted file mode 100644 index 6dc06702274..00000000000 --- a/content/en/docs/private-platform/reference/pmp-ref-admin-manage.md +++ /dev/null @@ -1,459 +0,0 @@ ---- -title: "Private Mendix Platform Functionalities - Company Administrators" -linktitle: "Company Administrators" -url: /private-mendix-platform/reference-guide/admin/company/ -description: "Provides details on the features and functionality of the Private Mendix Platform that are available to company administrators." -weight: 10 ---- - -## Introduction - -In Private Mendix Platform, company administrators primarily manage business-as-usual tasks, for example inviting new users to an app, or approving Marketplace contents. Settings relevant for company admins are available in the [Manage](#manage) section of the admin navigation menu. - -## Accessing the Configuration Settings - -As a user with company administrator access rights, you can access the Private Mendix Platform configuration settings by performing the following steps: - -1. Switch to Admin Mode by clicking the profile picture in the top right corner of the screen and selecting **Switch to Admin Mode**. -2. In the left navigation menu, open the **Manage** section. - -## Manage {#manage} - -The **Manage** section of the administrator navigation menu contains setting relevant to your day-to-day tasks as a company admin. You can use it to manage your company apps, users and groups, Marketplace contents, and deployment clusters. - -### Apps - -The **Apps** section of the navigation menu lets administrators manage their apps. - -#### App Management - -On the **App Management** page, you can view a summary of your apps. - -{{< figure src="/attachments/private-platform/pmp-admin1.png" class="no-border" >}} - -By clicking **More Actions** ({{% icon name="three-dots-menu-horizontal" %}}) in the **Action** column, you can quickly perform a number of actions: - -* [Edit app details](#app-details) -* [Assign the app to a new owner](#ownership) -* [Share the app with groups](#share) -* [Archive the app](#archive) -* [Delete the app](#delete) - -##### Editing App Details {#app-details} - -Company admins can edit app details such as the app branding or ownership, team membership, and others. - -1. In the **App Management** page, in the **Action** column, click **More Actions** > **Edit**. -2. Configure any of the following settings: - -* **App Details** - Configure the following basic app details: - * **App ID** - An automatically assigned internal ID. This value cannot be adjusted. - * **Name** - The name of your app. This value should be meaningful, so that users can easily identify the app. - * **Description** - An optional description of the application. - * **App Logo** - A browser logo for your app. This value can only be adjusted by the app owner. -* **Team Membership** - Invite users to join your app, or remove them from the app. Before you can invite a user, you must first configure their account on the [User Management](#users) page. - - When adding a member, the dialog displays any roles inherited from groups. If the user is not a member of any groups, the dialog shows **NONE**. - -* **Git Server** - View the revisions per branch for this app. -* **Ownership and Sharing** - Select the user and optionally the group that owns this app. If an app is owned by a specific group, the owner must be a user who belongs to that group. - -##### Assigning the App to a New Owner {#ownership} - -Each app is owned by a specific user, who can change settings such as the application branding (logo). By default, the owner is the user who created the app. To transfer the ownership to another user, on the **App Management** page, in the **Action** column, click **More Actions** > **Transfer Ownership**. Alternatively, you can access the same option in the **Ownership and Sharing** tab of the [App Details](#app-details) page. - -In addition to specifying the owner, you can also assign ownership of the app to a specific group. If an app is owned by a group, the owner must be a user who belongs to that group. - -{{% alert color="info" %}} -Ownership of Private Mendix Platform apps created through Studio Pro is automatically given to the `Mendix` root user group. If required, you can transfer the ownership to another group after creation. -{{% /alert %}} - -##### Sharing the App with Selected User Groups {#share} - -You can share your app with any user groups by selecting the **More Actions** > **Share with Groups** option from the **App Management** page. Sharing makes the app visible to groups that otherwise may not be able to see or access your app. Members of the group with which you have shared the app do not have automatic access. Instead, they can request access from the app's owner. - -##### Archiving the App {#archive} - -If an app is not needed for a time, you can archive it. An archived app is no longer available to users, but its data is still stored, and it can be quickly un-archived if required. - -To archive an app, on the **App Management** page, in the **Action** column, click **More Actions** > **Archive App**. To reactivate an archived app, select **Unarchive App** from the same menu. Alternatively, you can access the same options on the [App Details](#app-details) page. The app is archived or unarchived immediately. - -##### Deleting the App {#delete} - -If the app is no longer needed and you do not want to store its data, you can delete it. Deleting an app removes its repository, so that it cannot be restored afterwards. To delete an app, click **Delete App** on the [App Details](#app-details) page. - -You will be warned of the consequences and asked for confirmation before the app is deleted. - -#### Software Composition {#software-composition} - -The **Software Composition** page provides visibility into the component dependencies in each app environment. The components displayed here are based on the [Software Bill of Materials (SBOM)](/refguide/sbom-generation/). - -##### Overview - -On the **Overview** tab, you can see a list of all the deployed apps and their environments, if applicable. You can also see the number of findings for each severity level. - -The **Insights** cards display the number of findings across all environments, broken down by severity level. For example, if a build package contains one critical finding and is deployed to the test and production environments, two findings are added to **Insights**. - -Each card also displays a rolling average of how the number of findings has evolved over the past 30 days, expressed as a percentage. - -The app list contains the following information: - -* **App Name** – The name of the app. Clicking this opens the **Application Environment Summary** page, if it is available. -* **Environment** – The name of the environment. -* **Purpose** - The purpose of the environment (Development, Test, Acceptance, or Production). -* **Runtime** – The Mendix Runtime version. Unsupported versions of the Mendix Runtime display a warning. -* **Owner** – The owner of the app. -* **Cluster** – The type of cluster where the environment is deployed. -* **Findings** – The number of findings of each type. -* Column customization ({{% icon name="view" %}}) – You can customize the columns in the list by clicking the {{% icon name="view" %}} icon and selecting or deselecting options. - -##### Components - -The **Components** tab gives an overview of all the unique components used across your app landscape. - -The component list contains the following information: - -* **Component** – The name of the component. Clicking this opens the **Component Details** page. -* **Type** – The type of component, which can be one of the following: - - * **Module** – Standard module imported from the Marketplace, such as [Community Commons](https://marketplace.mendix.com/link/component/170), or a module created by the developer. - * **Widget** – User interface elements downloaded from the Marketplace, such as [Charts](https://marketplace.mendix.com/link/component/105695), or a widget created by the developer. - * **Framework** – The Mendix Runtime version, for example 10.12.0 - * **Jar** – Java libraries imported into your app using [Managed Dependencies](/refguide/managed-dependencies/), or those manually added in the **userlib** folder depending on the Studio Pro version used, such as `org.apache.commons.io`. - * **npms** – `npm` libraries that are used in your [JavaScript actions](/refguide/javascript-actions/). - * **Unknown** – When the type of the component is none of the above and hence undetermined. - -* **Support** – The support type of the Marketplace component. This can be **Mendix**, **Partner**, or **Community**. -* **Version** – The version of the component that is being used. -* **Findings** – The number of findings of each type, color-coded according to severity level. -* **Apps using component** – The number of apps where the component is used. -* **License** – For components derived from the Mendix Marketplace, this is the end-user license for the component. -* Column customization ({{% icon name="view" %}}) – You can customize the columns of the list by clicking the {{% icon name="view" %}} icon and selecting or deselecting options. - -##### Findings - -The **Findings** tab allows you to view a list of all the findings discovered in your apps. A finding represents an issue identified in the components of an app. - -The findings are divided into the following types: - -* Vulnerable - A finding is generated when a component is published on the [Security Advisories](/releasenotes/security-advisories/) page, and is assigned a specific CVSS score. CVSS scores are based on the [NVD Vulnerability Metrics](https://nvd.nist.gov/vuln-metrics) framework, and cannot be orverriden. -* Outdated - A finding is generated when a component becomes outdated, meaning when a new runtime compatible version is published. -* Deprecated - A finding is generated when a component has been labeled as deprecated in the Private Marketplace. - -These are the severity levels of a finding: - -* **Critical** -* **High** -* **Medium** -* **Low** - -##### Scoring Criteria - -The **Scoring Criteria** tab allows you to adjust the conditions and severity for each type of finding. Scoring criteria reflect your company's risk preference. - -The settings on this tab determine how each such vulnerability is calculated for apps, environments, and components. - -The types of findings that you can adjust for are **Outdated** and **Deprecated**. For outdated components, you can adjust all severity levels. For deprecated components, you can choose which severity level to assign. - -#### Import Apps - -On the **Import Apps** page, administrators can import existing Mendix apps that are in their version control host but not yet in Private Mendix Platform. The import currently supports the following hosts: - -* GitLab -* GitHub -* Bitbucket -* Azure DevOps Services (cloud, `dev.azure.com`). Azure DevOps Server (on-premises) is not supported. - -{{< figure src="/attachments/private-platform/pmp-admin6.png" class="no-border" >}} - -The list of apps on the page is not refreshed automatically. To refresh it, click the **Scan for Apps** button. - -### Marketplace - -In the **Marketplace** section, administrators can manage various settings related to the content available on the Private Platform Marketplace. The Private Platform Marketplace is a local version of [Mendix Marketplace](/appstore/), enclosed entirely within the Private Platform. Developers in your organization can also create their own modules, connectors, and sample apps, and share them on the Private Platform Marketplace to make them available to other users. - -As the administrator, you can perform the following actions: - -#### Content Management {#content} - -In the **Content Management** tab, you can view the Marketplace content that your users have already published, as well as any items which are pending approval, or which have been rejected. - -{{< figure src="/attachments/private-platform/pmp-admin7.png" class="no-border" >}} - -You can click on an item to view more information about it, download, approve, or delete it. - -#### Taxonomy Management - -In the **Taxonomy Management** tab, you can configure the supported Studio Pro versions and sub-categories that your users can select when creating Marketplace content. You can also view and edit the available licenses. - -{{< figure src="/attachments/private-platform/pmp-admin8.png" class="no-border" >}} - -##### Supported Versions - -The versions listed on the **Supported Versions** page indicate the Mendix Studio Pro versions that a Marketplace content item is compatible with. Users can select these versions from a list when uploading new Marketplace content. - -##### Licenses - -The **Licenses** tab allows administrators to specify the licenses that are available to their apps. To add a new license, click **New License** and specify the following values: - -* **Name** - Name of the license -* **URL** - URL at which the license can be accessed -* **Contents** - Optional additional information about the license. - -##### App Categories - -In the **App Categories** tab, you can view the predefined categories that users can specify for their Marketplace content items. You can also add custom categories, for example, for Marketplace contents related to a specific project. - -Predefined app categories cannot be edited or deleted. To edit or delete a custom category, click the **Action** menu, and then select one of the available options. - -#### Import Content - -You can populate your private Marketplace with contents by importing a zip file that contains the content packages along with a *package.json* file. You can upload the file from a Content Delivery Network, or manually from your local machine. - -{{< figure src="/attachments/private-platform/pmp-admin9.png" class="no-border" >}} - -#### Upload Marketplace Bundle {#manual-upload} - -To manually upload a content bundle from your own computer, perform the following steps: - -1. Download the Marketplace Bundle with contents available in a zip file. If you do not have access to the bundle, contact your Mendix point of contact. -2. In the **Import Content** > **Upload Marketplace Bundle** tab, drag and drop the file that you want to upload. - - * The file must be in *zip* format. - * The file must not be larger than 2048 MB. - * Your infrastructure must support the upload of large files (up to 2048MB). - * You should also have at least 40 GB available disk space to account for temporary files. - -3. Click **Import Marketplace Bundle components**. - - {{< figure src="/attachments/private-platform/pmp-config1.png" class="no-border" >}} - -4. To view the progress of your upload, click **View Task Queue**. - -{{% alert color="info" %}} -If you are experiencing high latency during manual uploads, you can increase the timeouts. For example, for nginx, you can perform the following commands: - -```text -nginx.ingress.kubernetes.io/client-header-timeout: "300" -nginx.ingress.kubernetes.io/proxy-connect-timeout: "300" -nginx.ingress.kubernetes.io/proxy-read-timeout: "300" -nginx.ingress.kubernetes.io/proxy-send-timeout: "300" -``` - -{{% /alert %}} - -#### Import from CDN - -To import content from a Content Delivery Network, follow these steps: - -1. Ensure that your system administrator has [configured the Marketplace import bundle URL](/private-mendix-platform/reference-guide/admin/system/#configure-import). -2. In the **Import Content** > **Import from CDN** tab, view and download the available content items. - -### Deployment - -In the **Deployment** section, administrators can manage existing clusters and register new ones. - -#### Cluster Manager - -The **Cluster Manager** page allows administrators to configure clusters to be used in their devOps CI/CD pipelines. To configure a cluster, perform the following steps: - -1. In **Switch to Admin Mode** > **Manage** > **Cluster Manager**, click **Register New Cluster**. -2. Configure the following values: - - * **Cluster Name** - Specify a name for the cluster. - * **Cluster type** - Select the cluster type. **Kubernetes** is recommended. - * **API Server** - Specify your API server. - * **Token** - You must first create a service account, cluster role, and cluster role binding in the cluster, and then get the service account's token. For an example, see [Configuring Build Cluster Setting](/private-mendix-platform/configure-k8s/#build-cluster). - * **Enable Logging and Monitoring** - Specify whether Grafana and Prometheus monitoring should be enabled for this cluster. - * **Package Type** - For Kubernetes and Manual Production Deployment, select the type of package that will be uploaded to environments in this cluster. - * **S3 Endpoint** - For Kubernetes and Manual Production Deployment, specify the S3 endpoint, for example, `Cloud Object Storage - Amazon S3 - AWS`. - * **S3 Bucket Name** - For Kubernetes and Manual Production Deployment, specify the S3 bucket name, for example, `mybucket`. - * **Region** - For Kubernetes and Manual Production Deployment, specify the region, for example, `ap-southeast-1`. - * **Access Key ID** - For Kubernetes and Manual Production Deployment, this ID value is used to access the S3 bucket. - * **Secret Access Key** - For Kubernetes and Manual Production Deployment, this secret key value is used to access the S3 bucket. - -3. Click **Save**. -4. Click the newly created cluster and expand it, and then click **Retrieve Namespace(s)** to retrieve all the namespace and storage plans, or **Manually Register Namespace**. - - Namespaces without any storage plan are skipped. This step requires the Mendix Operator to be installed and configured. You can repeat this step as required to retrieve additional namespaces. - -5. After the cluster is registered, create environments with the cluster, namespace and plans. - -##### Configuring CI/CD Pipelines with Manual Approval {#manual-deployment} - -If your production and development environments must be fully air-gapped and separated from each other, and you want to limit the ability to deploy packages to either selected users or an automated pipeline with manual approval, you can configure your cluster type to be **Manual Production Deployment**. - -Selecting this option allows you to specify an S3 bucket. This bucket is then used as the destination where the deployment package is uploaded at the end of the pipeline, instead of being deployed to the production environment. Designated approvers can then retrieve the package from the S3 bucket and manually deploy it to the target environment. - -### Users {#users} - -In the **User Management** section, administrators can manage user accounts and user groups. - -{{< figure src="/attachments/private-platform/pmp-admin3.png" class="no-border" >}} - -As the administrator, you can perform the following actions: - -#### User Management - -In the **User Management** tab, you can create and edit accounts for your local users and API users (that is, accounts that are used by an API service to access your Private Mendix Platform). By clicking **More Actions** ({{% icon name="three-dots-menu-horizontal" %}}) by an account, you can quickly perform a number of actions: - - * Edit a user's name and email - * Assign or remove user roles (local users only) - * Block a user - * Change a user's password - * Configure the language and time zone settings for a user (local users only) - * Log out a user (local users only) - * Delete a user account - -In the **Actions** tab, you can also log out all users currently logged in to your app. - -#### Group Management - -In the **Group Management** tab, you can create and edit user groups. These groups typically reflect your organization's structure. You can also use the **Automation Settings** option to automatically assign users to groups based on their profile attributes. - -For more information about group management in Private Mendix Platform version 2.0 and newer, see [Dynamic Role Management in Private Mendix Platform](/private-mendix-platform/dynamic-role-management/). - -### Platform - -In the **Deployment** section, administrators can view and manage statistics, activity logs, webhooks, and licenses. - -As the administrator, you can perform the following actions: - -* In the **Webhooks** tab, you can view and manage your [Webhooks](#webhooks). -* In the **Licensing** tab, you can check the status of your licenses, or upload a new Private Mendix Platform license bundle. - -#### Platform Statistics - -In the **Platform Statistics** section, you can access statistics such as the number of users and apps, daily user login times and numbers, or most active users. - -#### Activity Logs - -For auditing purposes, you can view a log of the most recent actions taken by users of the platform. - -##### Recent Actions - -This tab contains a list of the recent actions, logged for the time period specified in the **Log Settings** tab. The following actions are logged: - -* Creating and editing user accounts -* Creating and deleting apps -* Creating app packages -* Changing platform settings - -You can use the **Search** field to search for a specific action by name. - -##### Archived Actions - -This tab contains a list of actions that were archived after the period specified in the **Log Settings** tab has expired. You can download the archive if required for auditing purposes. - -##### Log Settings - -You can select how long the actions are kept in the logs, in days. The minimum number of days is 1, and the maximum is 365. You can also specify the logging level, from no logging to complete logging. - -#### Webhooks {#webhooks} - -In the **Webhooks** tab, you can view and manage your webhooks. - -Webhooks allow you to send information about your licensed Mendix app deployed to Private Mendix Platform to an external app or workflow. You can use them to trigger a step in an automated [Build](/private-mendix-platform/reference-guide/admin/system/#build-steps) or [Deployment](/private-mendix-platform/reference-guide/admin/system/#deploy-steps) pipeline. - -Mendix provides webhooks to send project information about the following events: - -* App events: - - * App archived - * App created - * App deleted - * App info edited - * App logo edited - * App member added - * App member removed - * App owner edited - * App shared - * App unarchived - -* CI/CD events: - - * Package built - * Package deleted - * Package deployed - * Environment created - -* Marketplace events: - - * Item approved - * Item created - * Item declined - * Item edited - * Item imported - * Item owner edited - * Item shared - * Item version added - * Item version edited - -* User events: - - * Group admin updated - * Group created - * Group info edited - * Group member added - * Group member removed - * User blocked - * User created - * User info edited - * User unblocked - -The webhooks contain a retry mechanism if an error response is received from the endpoint. This helps ensure that the trigger reaches the endpoint. - -##### Creating a New Webhook {#setting-up} - -To set up a webhook, do the following: - -1. In the **Platform Webhooks** tab of the **Webhooks** page, click **New Webhook**. -2. Enter the following information: - - * **Webhook Name** – This is a name which you can use to identify the webhook. - * **URL** – This is the endpoint that will receive the payload when one of the event types selected in **Available Events** occurs. - * **Validation Secret** – This is a secret that is shared with the endpoint to verify that it has been triggered by this webhook. If you leave this blank, a secret is generated automatically. You can see the generated value any time you return to edit the webhook. - * **Available Events** – This is the event (or events) that triggers the webhook to send information to the endpoint. You can activate or deactivate specific event types in the **Event Management** tab of the **Webhooks** page. - * **Custom Headers** – This is a key-value pair that is sent as an HTTP header to the endpoint. You can configure a predefined custom header in the **Preset Headers** tab of the **Webhooks** page. - -You can edit or delete an existing webhook by clicking **More Options** ({{% icon name="three-dots-menu-horizontal" %}}) in the **Action** column for the webhook you want to change, and then selecting **Edit** or **Delete**. - -##### Webhook Headers - -Every `POST` payload contains the following delivery information as part of the header: - -* **connection** – `close`, indicating that there is no further information for the HTTP request -* **content-length** – the size of the HTTP request in bytes (for example, `475`) -* **webhook-signature** – the signature of the webhook in the format `,` (for example, `v1,Ay2spGBdE7i6OzNkFgTDnGfqgZT0WonCFoBMt8V3YiQ=`) -* **webhook-id** – a unique identifier for this webhook trigger (for example, `msg_2M605iBQRge9hTgpYg7fKXQubaw`) -* **user-agent** – the user agent used to process this trigger -* **webhook-timestamp** – the time the webhook was triggered (for example, `1677072542`) -* **content-type** – `application/json` -* **accept** – `*/*` -* **host** – the host part of the endpoint URL (for example, `gitlab.com`) - -You can also add your own custom headers. For more information, see [Configuring a Webhook](#setting-up). - -{{% alert color="info" %}} -The order of these headers is not guaranteed. -{{% /alert %}} - -#### Licensing - -On this page, you can view the status of your Private Mendix Platform license, and upload a new license bundle if necessary. - -[Private Cloud License Manager](/developerportal/deploy/private-cloud/private-cloud-license-manager/) must be used to manage the Private Mendix Platform license. It can also be used to manage and provision your own app licenses. - -Private Mendix Platform licenses are either **valid** or **not found**; when not found, the Platform operates in developer mode, where access to some features and capabilities is restricted. - -{{< figure src="/attachments/private-platform/pmp-wizard2.png" class="no-border" >}} - -When valid, licenses can have the following statuses: - -* Active (shown in green) -* About to expire (shown in yellow) -* Expired (shown in red) - -#### Maia - -On this page, you can connect Mendix AI Assistance (Maia) to your own Large Language Model (LLM). It enables Maia to use your custom LLM for processing and generating responses. For more information, see [Maia in Private Mendix Platform](/private-mendix-platform/maia/). diff --git a/content/en/docs/private-platform/reference/system/_index.md b/content/en/docs/private-platform/reference/system/_index.md new file mode 100644 index 00000000000..8aea5a5a17c --- /dev/null +++ b/content/en/docs/private-platform/reference/system/_index.md @@ -0,0 +1,28 @@ +--- +title: "Private Mendix Platform Functionalities - System Administrators" +linktitle: "System Administrators" +url: /private-mendix-platform/reference-guide/admin/system/ +description: "Provides details on the features and functionality of the Private Mendix Platform that are available to system administrators." +weight: 20 +no_list: false +description_list: true +--- + +## Introduction + +In Private Mendix Platform, system administrators primarily manage key settings which must be configured during the initial implementation, and which are rarely modified during normal operation. Settings relevant for systems admins are available in the [Settings](#settings) section of the admin navigation menu. + +## Settings {#settings} + +The **Settings** section of the administrator navigation menu contains setting relevant to your day-to-day tasks as a system admin. You can use it to manage your branding, license, Marketplace settings, and version control settings. + +Some of the settings that you configure here are initially set by the [Private Platform Configuration Wizard](/private-mendix-platform/configuration-wizard/). System administrators can also update them at any time after the initial configuration. + +## Accessing the Configuration Settings + +As a user with system administrator access rights, you can access the Private Mendix Platform configuration settings by performing the following steps: + +1. Switch to Admin Mode by clicking the profile picture in the top right corner of the screen and selecting **Switch to Admin Mode**. +2. In the left navigation menu, open the **Settings** section. + +## Read More diff --git a/content/en/docs/private-platform/reference/system/pmp-ref-admin-system-advanced.md b/content/en/docs/private-platform/reference/system/pmp-ref-admin-system-advanced.md new file mode 100644 index 00000000000..4a20a49abf7 --- /dev/null +++ b/content/en/docs/private-platform/reference/system/pmp-ref-admin-system-advanced.md @@ -0,0 +1,37 @@ +--- +title: "System Administrator Settings - Advanced" +linktitle: "Advanced" +url: /private-mendix-platform/admin-system/advanced/ +description: "Provides details on the advanced settings that are available to system administrators." +weight: 30 +--- + +## Introduction + +In this section, you can adjust the advanced configuration settings of your Private Mendix Platform. + +## Capabilities + +The settings in this section allow you to configure the basic aspects of your Private Mendix Platform: + +* **Enable App Projects?** – Recommended. Enables you to create and manage your app projects. Enables app projects and related settings across the portal. Must be enabled for CI/CD capabilities. +* **Enable Marketplace?** – Recommended. Enables you to use the Private Platform's Marketplace capabilities to upload, import and manage Marketplace contents. The Marketplace enabled here is hosted entirely within your Private Mendix Platform. +* **Enable Build and Deploy** – Recommended. Enables you to use the Private Platform's CI/CD capabilities to build and deploy apps. Enables the Build and Deploy pipeline, environments, metrics, logging, and related settings. +* **Enable Identity & Access Integration?** – Optional. Enable users to log in using SSO by configuring your IdP integration. +* **Allow sign up?** – Optional. Enable users to log in with a local user account, instead of or in addition to SSO. +* **Enable Webhooks?** – Optional. Webhooks allow to send information between platform and external systems, and can be triggered by events around Apps, Users, Groups, Marketplace and CI/CD. +* **Enable License Management?** – Recommended. Upload your license bundle to automatically provision app licenses through Private Cloud License Manager. For more information, see Private Cloud License Manager. + +## Operational + +In this section, you can access the list of scheduled events and the Mx Model Reflection tool. + +### Scheduled Event + +This tab shows a list of all the scheduled tasks and actions in the system, together with start time, end time, and status. + +{{< figure src="/attachments/private-platform/pmp-wizard6.png" class="no-border" >}} + +### Mx Model Reflection + +For more information about this platform-supported module, refer to [Mx Model Reflection](/appstore/modules/model-reflection/). diff --git a/content/en/docs/private-platform/reference/pmp-ref-admin-system.md b/content/en/docs/private-platform/reference/system/pmp-ref-admin-system-integration.md similarity index 53% rename from content/en/docs/private-platform/reference/pmp-ref-admin-system.md rename to content/en/docs/private-platform/reference/system/pmp-ref-admin-system-integration.md index 165bda2d0d9..2fc00745995 100644 --- a/content/en/docs/private-platform/reference/pmp-ref-admin-system.md +++ b/content/en/docs/private-platform/reference/system/pmp-ref-admin-system-integration.md @@ -1,140 +1,34 @@ --- -title: "Private Mendix Platform Functionalities - System Administrators" -linktitle: "System Administrators" -url: /private-mendix-platform/reference-guide/admin/system/ -description: "Provides details on the features and functionality of the Private Mendix Platform that are available to system administrators." +title: "System Administrator Settings - Integrations" +linktitle: "Integrations" +url: /private-mendix-platform/admin-system/integrations/ +description: "Provides details on the integration settings that are available to system administrators." weight: 20 --- ## Introduction -In Private Mendix Platform, system administrators primarily manage key settings which must be configured during the initial implementation, and which are rarely modified during normal operation. Settings relevant for systems admins are available in the [Settings](#settings) section of the admin navigation menu. - -## Accessing the Configuration Settings - -As a user with system administrator access rights, you can access the Private Mendix Platform configuration settings by performing the following steps: - -1. Switch to Admin Mode by clicking the profile picture in the top right corner of the screen and selecting **Switch to Admin Mode**. -2. In the left navigation menu, open the **Settings** section. - -## Settings {#settings} - -The **Settings** section of the administrator navigation menu contains setting relevant to your day-to-day tasks as a system admin. You can use it to manage your branding, license, Marketplace settings, and version control settings. - -Some of the settings that you configure here are initially set by the [Private Platform Configuration Wizard](/private-mendix-platform/configuration-wizard/). System administrators can also update them at any time after the initial configuration. - -### Preferences - -General configuration settings allow you to manage the basic aspects of your Private Mendix Platform, such as the platform name and branding, toggling certain capabilities on or off, and version support settings. The settings in this section are largely configured when you run the initial configuration wizard, but you can still review and adjust them later during the implementation process. - -#### General - -The **General** tab allows you to configure information about your organization, and optionally also the Certified Mendix Partner that is working with you on implementing Private Mendix Platform. You can also use it to configure your locale settings. - -{{% alert color="info" %}} -Changing your locale sets locale-dependent formats, such as date and time, to the preferred format of the selected locale. The settings are applied to the Private Mendix Platform (for example, in the Marketplace or Mendix Portal), not in the apps created through the Platform. -{{% /alert %}} - -##### Branding - -The settings in this section allow you to configure custom branding for your Private Mendix Platform. You can customize the title of the Platform as shown in the top bar, upload your logo, or change the image on the login page. You can also configure an access banner that users will see before, during, or after the login page of your app, for example, to display any information about privacy or security that you want to communicate to your users. - -##### Support - -In this section, you can provide your own help and support instructions for users of your Private Mendix Platform. - -{{< figure src="/attachments/private-platform/pmp-wizard1.png" class="no-border" >}} - -Users can then see these instructions on the **Logs and Events** page for their app. - -##### Export Settings - -You can export your Private Mendix Platform settings to a JSON configuration file as backup, or to speed up the implementation of new Private Mendix Platform instances. - -Settings can only be imported during the initial configuration of the platform. To ensure data integrity and platform stability, you cannot import them into an instance that is already configured and running. - -#### Notifications - -Notification settings allow you to manage the notifications generated by Private Mendix Platform. These settings are necessary to ensure that your system can send out notifications. - -##### General - -In the current release of Private Mendix Platform, notifications are shown in the Platform itself. In future versions, you will also be able to enable email and push notifications. - -##### Administrative Tasks - -In this tab, you can trigger cleaning the scheduled event queue. - -#### Marketplace - -For Private Mendix Platform, the Marketplace is also private and hosted entirely within the platform itself. The settings in this section allow you to configure the administrative settings for publishing and downloading content to and from the private Marketplace. - -##### Content Approvals - -In this tab, you can configure whether contents that users publish to the private Marketplace requires administrator approval before publishing. To view all [pending, published, and rejected content items](/private-mendix-platform/reference-guide/admin/company/#content), click **Go to Marketplace Management**. - -##### Content Import {#import} - -You can populate your private Marketplace with contents by importing a zip file that contains the content packages along with a *package.json* file. You can upload the file from a Content Delivery Network, or manually from your local machine. - -{{< figure src="/attachments/private-platform/pmp-admin9.png" class="no-border" >}} - -###### Manually Importing Marketplace Content - -To manually upload a content bundle from your own computer, perform the following steps: - -1. Download the Marketplace Bundle with contents available in a zip file. If you do not have access to the bundle, contact your Mendix point of contact. -2. Click **Upload Marketplace Bundle** to go to the **Import Content** > **Upload Marketplace Bundle** tab. -3. Follow the steps described in [Company Administrators](/private-mendix-platform/reference-guide/admin/company/#manual-upload). - -###### Importing Marketplace Content from a CDN {#configure-import} - -To enable content import from a Content Delivery Network, follow these steps: - -1. Download the Marketplace Bundle with contents available in a zip file. If you do not have access to the bundle, contact your Mendix point of contact. -2. Unzip the files to an internal location which Private Mendix Platform can access via HTTP or HTTPS. Do not change the directory structure. -3. If using a self-signed certificate for your internal locations, configure Mendix Operator to trust your private Certificate Authorities. For more information, see [Obtaining and Configuring the CA Certificate](/private-mendix-platform/configure-k8s/#ca-certificate). -4. In the **Content Import** tab, in the **Marketplace import bundle URL** field, enter the root URL of the *package.json* file included in the Marketplace download. - - For example, if the *package.json* can be accessed at the URL `https:///release/marketplace/Marketplace-1.0/package.json`, enter the following URL: `https:///release/marketplace/Marketplace-1.0/`. - - {{< figure src="/attachments/private-platform/pmp-config3.png" class="no-border" >}} - -5. Set the **Authentication** toggle to **ON**, and then specify the user name and password required to download the bundle. -6. Click **Save** to enable content import from this bundle. -7. Click **Go to Marketplace Import** to view the available downloads in the **Import Content** > **Import from CDN** tab. - -#### Version Settings {#version-settings} - -In this section, you can perform the following tasks: - -* View or disable the versions of Mendix Studio Pro that your users are allowed to download. -* Disable the option to download Studio Pro and patch content from the home page, **My Apps** page, and **Get Studio Pro** page. -* Enter instructions for your users on how to request a Studio Pro download. - -### Integrations - In the **Integrations** section of the administrator menu, you can configure settings related to identity and access, version control, CI/CD, and others. -#### Identity & Access +## Identity & Access {#identity} In this section, you can configure SSO authentication for your users logging in to Private Mendix Platform. OIDC and SAML are supported as protocols. -##### IdP Integration (OIDC) +### IdP Integration (OIDC) You can configure SSO authentication with the OIDC protocol. For more information, see [Runtime Configuration of Your IdP at Your App](/appstore/modules/oidc/#runtime-idp-app). -##### IdP Integration (SAML) +### IdP Integration (SAML) To [configure SSO authentication with the SAML protocol](/appstore/modules/saml/), first configure the service provider in the **SP Configuration** tab, and then create the IdP-specific settings in the **IdP Configuration** tab. To debug the configuration, you can view the log files in the **Log** tab. -##### OIDC Provider +### OIDC Provider The settings under this tab control the connection between Studio Pro and the platform. They should not be changed without advanced knowledge of the platform. Stop and restart the Private Platform portal if you are having trouble logging in with Studio Pro. -##### SCIM Provisioning +### SCIM Provisioning System for Cross-Domain Identity Management (SCIM) is a protocol that simplifies user access management for applications. Private Mendix Platform uses the SCIM standard to pre-provision selected users onto your Platform without the users having to manually log in through SSO first. @@ -148,7 +42,7 @@ To enable SCIM provisioning, perform the following steps: 6. In the **IDP Configuration Page** dialogue, enter a name for the connection, and obtain the token for your identity provider by clicking **Copy**. 7. Enter the token in the configuration panel of your identity provider and verify that the connection is working. -##### MxAdmin Settings +### MxAdmin Settings By default, the platform has a default system administrator account called MxAdmin. You can disable the account by setting the **Disable MxAdmin** toggle to **Yes**. @@ -156,7 +50,7 @@ By default, the platform has a default system administrator account called MxAdm Ensure that you have at least one other user with the System Administrator role assigned before disabling MxAdmin. {{% /alert %}} -##### Preferences +### Preferences You can configure the following preferences for login sessions in Private Mendix Platform: @@ -167,7 +61,7 @@ You can configure the following preferences for login sessions in Private Mendix By default, all of these options are disabled (that is, set to a *0* value). To enable any of them, enter a number greater than zero into the corresponding field. -#### Project Management +## Project Management You can integrate your Private Mendix Platform with [Jira by Atlassian](https://www.atlassian.com/software/jira) to manage your sprints and roadmap. Enabling the integration links your commits from Mendix Studio Pro directly to your user stories in Jira. The integration requires an active Jira license and a user with admin rights. @@ -178,19 +72,19 @@ To enable the connection, click **Connect Jira**, and then provide the following * User name of a Jira admin user * [API token of a Jira admin user](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) -#### Version Control +## Version Control -To create applications and collaborate, configure the connection to your version control repository. GitHub, GitLab, Azure DevOps Services, and Bitbucket are supported as version control systems. For more information, see [Configuring the Version Control System for Private Mendix Platform](/private-mendix-platform-version-control/). +To create applications and collaborate, configure the connection to your version control repository. GitHub, GitLab, Azure DevOps Services, Azure DevOps Server, and Bitbucket are supported as version control systems. For more information, see [Configuring the Version Control System for Private Mendix Platform](/private-mendix-platform/version-control/). -#### Build +## Build Settings in this section allow you to configure your CI/CD capabilities and Build pipeline. -##### Build Utility +### Build Utility Configure CI/CD capabilities for your app. If you enable this option, you must also specify your CI system, configure the necessary settings, and register a Kubernetes cluster. Jenkins, [AzureDevops](/private-mendix-platform/configure-azure/) and [Kubernetes](/private-mendix-platform-configure-k8s/) are supported. You can also configure a [custom template](/private-mendix-platform/reference-guide/admin/company/#manual-deployment) for your CI/CD capabilities. -##### Build Steps {#build-steps} +### Build Steps {#build-steps} In the **Build Steps** tab, you can configure the steps that constitute the pipeline. @@ -202,7 +96,7 @@ For Kubernetes CI, you can configure the pipeline to include additional steps af The **Pipeline Type** section allows you to designate a pipeline as a main pipeline for all your apps, as well as create draft pipelines which you can use to test or run specific applications. If you designate a pipeline as **Draft**, you can specify the applications which should use the pipeline. For more information about configuring the pipelines, see [Configuring the Pipeline Type](#configuring-pipeline-type). -##### Configuring the Pipeline Type {#configuring-pipeline-type} +### Configuring the Pipeline Type {#configuring-pipeline-type} Build and Deploy pipelines can be marked as Main or Draft. This lets you test pipeline changes on a single app without disrupting builds and deployments for everything else. @@ -245,18 +139,18 @@ Only one main Build and one main Deploy pipeline must exist at any time. When yo You can duplicate your pipelines. All configured steps of a duplicated pipeline are copied into a new pipeline that always starts as a draft, with an empty name, no app association, and the placeholder name **New Pipeline**. You must specify a name before you can save your changes. -#### Deployment {#deployment} +## Deployment {#deployment} Settings in this section allow you to configure your Deployment pipelines. -##### Deployment Method +### Deployment Method Private Mendix Platform supports the following deployment methods: * Kubernetes Interactor-Agent Mode * Kubernetes Standalone Mode -##### Deployment Steps {#deploy-steps} +### Deployment Steps {#deploy-steps} In the **Deployment Steps** tab, you can configure the steps that constitute the pipeline. @@ -270,40 +164,10 @@ You can also configure the pipeline to take into consideration the type of chang The **Pipeline Type** section allows you to designate a pipeline as a main pipeline for all your apps, as well as create draft pipelines which you can use to test or run specific applications. If you designate a pipeline as **Draft**, you can specify the applications which should use the pipeline, as well as the DTAP purpose (that is, whether it is used for Acceptance, Deployment, or Testing). For more information about configuring the pipelines, see [Configuring the Pipeline Type](#configuring-pipeline-type). -##### Security +### Security To help fulfill compliance requirements related to account control, Private Mendix Platform now supports disabling the default MxAdmin account for apps at deployment. This setting effectively removes the ability to access the app using the default system admin account, and is only recommended when combined with default use of an SSO module to avoid lockout. -##### Settings +### Settings In the **Settings** tab, you can customize the resource presets by specifying each preset's request and limit values for CPU and memory. - -### Advanced - -In this section, you can adjust the advanced configuration settings of your Private Mendix Platform. - -#### Capabilities - -The settings in this section allow you to configure the basic aspects of your Private Mendix Platform: - -* **Enable App Projects?** - Recommended. Enables you to create and manage your app projects. Enables app projects and related settings across the portal. Must be enabled for CI/CD capabilities. -* **Enable Marketplace?** - Recommended. Enables you to use the Private Platform's Marketplace capabilities to upload, import and manage Marketplace contents. The Marketplace enabled here is hosted entirely within your Private Mendix Platform. -* **Enable Build and Deploy** - Recommended. Enables you to use the Private Platform's CI/CD capabilities to build and deploy apps. Enables the Build and Deploy pipeline, environments, metrics, logging, and related settings. -* **Enable Identity & Access Integration?** - Optional. Enable users to log in using SSO by configuring your IdP integration. -* **Allow sign up?** - Optional. Enable users to log in with a local user account, instead of or in addition to SSO. -* **Enable Webhooks?** - Optional. Webhooks allow to send information between platform and external systems, and can be triggered by events around Apps, Users, Groups, Marketplace and CI/CD. -* **Enable License Management?** - Recommended. Upload your license bundle to automatically provision app licenses through Private Cloud License Manager. For more information, see Private Cloud License Manager. - -#### Operational - -In this section, you can access the list of scheduled events and the Mx Model Reflection tool. - -##### Scheduled Event - -This tab shows a list of all the scheduled tasks and actions in the system, together with start time, end time, and status. - -{{< figure src="/attachments/private-platform/pmp-wizard6.png" class="no-border" >}} - -##### Mx Model Reflection - -For more information about this platform-supported module, refer to [Mx Model Reflection](/appstore/modules/model-reflection/). diff --git a/content/en/docs/private-platform/reference/system/pmp-ref-admin-system.md b/content/en/docs/private-platform/reference/system/pmp-ref-admin-system.md new file mode 100644 index 00000000000..52f1d3f26fa --- /dev/null +++ b/content/en/docs/private-platform/reference/system/pmp-ref-admin-system.md @@ -0,0 +1,96 @@ +--- +title: "System Administrator Settings - Preferences" +linktitle: "Preferences" +url: /private-mendix-platform/admin-system/preferences/ +description: "Provides details on the general configuration settings that are available to system administrators." +weight: 10 +--- + +## Introduction + +General configuration settings allow you to manage the basic aspects of your Private Mendix Platform, such as the platform name and branding, toggling certain capabilities on or off, and version support settings. The settings in this section are largely configured when you run the initial configuration wizard, but you can still review and adjust them later during the implementation process. + +## General + +The **General** tab allows you to configure information about your organization, and optionally also the Certified Mendix Partner that is working with you on implementing Private Mendix Platform. You can also use it to configure your locale settings. + +{{% alert color="info" %}} +Changing your locale sets locale-dependent formats, such as date and time, to the preferred format of the selected locale. The settings are applied to the Private Mendix Platform (for example, in the Marketplace or Mendix Portal), not in the apps created through the Platform. +{{% /alert %}} + +### Branding + +The settings in this section allow you to configure custom branding for your Private Mendix Platform. You can customize the title of the Platform as shown in the top bar, upload your logo, or change the image on the login page. You can also configure an access banner that users will see before, during, or after the login page of your app, for example, to display any information about privacy or security that you want to communicate to your users. + +### Support + +In this section, you can provide your own help and support instructions for users of your Private Mendix Platform. + +{{< figure src="/attachments/private-platform/pmp-wizard1.png" class="no-border" >}} + +Users can then see these instructions on the **Logs and Events** page for their app. + +### Export Settings + +You can export your Private Mendix Platform settings to a JSON configuration file as backup, or to speed up the implementation of new Private Mendix Platform instances. + +Settings can only be imported during the initial configuration of the platform. To ensure data integrity and platform stability, you cannot import them into an instance that is already configured and running. + +## Notifications + +Notification settings allow you to manage the notifications generated by Private Mendix Platform. These settings are necessary to ensure that your system can send out notifications. + +### General + +In the current release of Private Mendix Platform, notifications are shown in the Platform itself. In future versions, you will also be able to enable email and push notifications. + +### Administrative Tasks + +In this tab, you can trigger cleaning the scheduled event queue. + +## Marketplace + +For Private Mendix Platform, the Marketplace is also private and hosted entirely within the platform itself. The settings in this section allow you to configure the administrative settings for publishing and downloading content to and from the private Marketplace. + +### Content Approvals + +In this tab, you can configure whether contents that users publish to the private Marketplace requires administrator approval before publishing. To view all [pending, published, and rejected content items](/private-mendix-platform/reference-guide/admin/company/#content), click **Go to Marketplace Management**. + +### Content Import {#import} + +You can populate your private Marketplace with contents by importing a zip file that contains the content packages along with a *package.json* file. You can upload the file from a Content Delivery Network, or manually from your local machine. + +{{< figure src="/attachments/private-platform/pmp-admin9.png" class="no-border" >}} + +#### Manually Importing Marketplace Content + +To manually upload a content bundle from your own computer, perform the following steps: + +1. Download the Marketplace Bundle with contents available in a zip file. If you do not have access to the bundle, contact your Mendix point of contact. +2. Click **Upload Marketplace Bundle** to go to the **Import Content** > **Upload Marketplace Bundle** tab. +3. Follow the steps described in [Company Administrators](/private-mendix-platform/reference-guide/admin/company/#manual-upload). + +#### Importing Marketplace Content from a CDN {#configure-import} + +To enable content import from a Content Delivery Network, follow these steps: + +1. Download the Marketplace Bundle with contents available in a zip file. If you do not have access to the bundle, contact your Mendix point of contact. +2. Unzip the files to an internal location which Private Mendix Platform can access via HTTP or HTTPS. Do not change the directory structure. +3. If using a self-signed certificate for your internal locations, configure Mendix Operator to trust your private Certificate Authorities. For more information, see [Obtaining and Configuring the CA Certificate](/private-mendix-platform/configure-k8s/#ca-certificate). +4. In the **Content Import** tab, in the **Marketplace import bundle URL** field, enter the root URL of the *package.json* file included in the Marketplace download. + + For example, if the *package.json* can be accessed at the URL `https:///release/marketplace/Marketplace-1.0/package.json`, enter the following URL: `https:///release/marketplace/Marketplace-1.0/`. + + {{< figure src="/attachments/private-platform/pmp-config3.png" class="no-border" >}} + +5. Set the **Authentication** toggle to **ON**, and then specify the user name and password required to download the bundle. +6. Click **Save** to enable content import from this bundle. +7. Click **Go to Marketplace Import** to view the available downloads in the **Import Content** > **Import from CDN** tab. + +### Version Settings {#version-settings} + +In this section, you can perform the following tasks: + +* View or disable the versions of Mendix Studio Pro that your users are allowed to download. +* Disable the option to download Studio Pro and patch content from the home page, **My Apps** page, and **Get Studio Pro** page. +* Enter instructions for your users on how to request a Studio Pro download. \ No newline at end of file diff --git a/content/en/docs/private-platform/user-guide/pmp-user-guide.md b/content/en/docs/private-platform/user-guide/pmp-user-guide.md index 8a5407d6890..4a276364bd6 100644 --- a/content/en/docs/private-platform/user-guide/pmp-user-guide.md +++ b/content/en/docs/private-platform/user-guide/pmp-user-guide.md @@ -65,7 +65,7 @@ To delete a PAT, click **Actions > Delete**. This will prevent anyone who has ob On the **Service Credentials** page, you can view and manage the credentials for various external systems that Private Mendix Platform can connect with. These services include GitHub, GitLab, Bitbucket, and AzureDevOps, used for managing your app projects. Depending on settings configured by the admin, they can automatically provisioned through the integrations or manually configured for the user account. -To create or work on app projects in Private Mendix Platform, you must create an access token in GitHub, GitLab, AzureDevOps, or Bitbucket, and then add it on the **Register Credentials** screen. The token must have read and write access to a repository where the app project is stored. +To create or work on app projects in Private Mendix Platform, you must create an access token in GitHub, GitLab, AzureDevOps, or Bitbucket, and then add it on the **Register Credentials** screen. The token must have read and write access to a repository where the app project is stored. For Azure DevOps Server, the token is a Personal Access Token of your own account with the scopes Code (Read and Write) and Project and Team (Read). The **Get My Azure PAT** button is available for Azure DevOps Services only. ## Notifications {#notifications} diff --git a/content/en/docs/releasenotes/private-platform/2/2.8.md b/content/en/docs/releasenotes/private-platform/2/2.8.md index dc9ab307365..92233497ff6 100644 --- a/content/en/docs/releasenotes/private-platform/2/2.8.md +++ b/content/en/docs/releasenotes/private-platform/2/2.8.md @@ -12,6 +12,129 @@ These release notes cover changes made to the [Private Mendix Platform](/private This is the [LTS](/releasenotes/studio-pro/lts-mts/#lts) version release. Customers are encouraged to upgrade to this version. [Previous MTS versions](/releasenotes/private-platform/1-13/) of Private Mendix Platform are no longer supported. {{% /alert %}} +## 2.8.2 + +### Release date: November 20, 2026 + +Version 2.8.2 of Private Mendix Platform introduces a number of new features, improvements, and fixes. + +#### New Features + +##### Azure DevOps Server (On-Premises) Support + +You can now use Azure DevOps Server 2022.1 or newer as the version control system. Azure DevOps Services (cloud) works as before, with one change: a failed project delete is now reported and the app is kept, as with GitHub and Bitbucket. For more information, see [Azure DevOps Server (On-Premises)](/private-mendix-platform/version-control/#azure-devops-server). + +#### Improvements + +##### Marketplace Enhancements + +Marketplace content can now be managed by a team rather than a single content owner. Marketplace content management is now included in the existing Dynamic Role Management functionality. You can use group membership and resource roles to grant granular permissions for editing component settings and uploading new items. + +##### Inherited Resources Labeled in Group Management + +The **Group Management** page now displays labels to clearly indicate which apps and Marketplace content items were inherited from a child group. + +##### Platform and Resource Role Assignment for OIDC Users + +We have added the option to dynamically assign Platform Roles and Resource Roles to users based on OIDC token claims, enabling zero-touch user provisioning without manual role assignment after SSO login. + +##### Logout Confirmation Message + +To comply with AWS ISV attestation requirements, when logging out of Private Mendix Platform, users now see a message confirming that they have logged out. + +##### Activity Log Enhancements + +On the [Log Settings](/private-mendix-platform/reference-guide/admin/company/#log-settings) page, you can now select Azure Blob Storage as an external backup target. Azure Blob Storage supports both managed identity and static credentials. + +#### Updates + +##### Studio Pro Updates + +* Studio Pro 9.24 LTS latest patch version updated to [9.24.44](/releasenotes/studio-pro/9.24/#92444) +* Studio Pro 10.24 LTS latest patch version updated to [10.24.28](/releasenotes/studio-pro/10.24/#102428) +* Studio Pro 11.6 MTS latest patch version updated to [11.6.10](/releasenotes/studio-pro/11.6/#11610) +* Studio Pro 11.12 MTS latest patch version updated to [11.12.6](/releasenotes/studio-pro/11.12/#11126) + +##### Other Platform Components {#example} + +* Mendix Operator version [2.29.0](/releasenotes/developer-portal/mendix-for-private-cloud/#2.29.0) +* Private Cloud License Manager (PCLM) version 0.11.3 +* Interactor v1.25.8 +* Interactor Bridge v1.24.8 +* Collector v1.23.10 +* Authenticator v1.19.6 +* Maia Appgen 0.39.5 +* Maia LLM Gateway 0.15.6 +* PDF Docgen v1.0.5 + +#### Fixes + +* (API) When creating an environment through API, you can now specify the required environment ID. (Ticket 291228) +* (API) We have fixed an issue where the app owner and their Owner role could be removed through API. (Ticket 283910) +* (API) We have resolved some User API validation issues. +* (API) We have fixed an issue where Deploy pipelines with manual approval steps would not run correctly when triggered through API. +* (API) We have fixed an issue where some API requests would result in incorrect response codes. +* (API) We have fixed an issue with the Group API, where updating the parent group through the API did not work correctly. +* (Marketplace) We have fixed an issue where it was possible to select an empty group when transferring a content item. +* (Marketplace) We have fixed an issue where downloading a widget through the inline version download link would save the widget to a user's local *Downloads* folder instead of the *widgets* folder. +* (Marketplace) We have fixed an issue where downloading a new version of an existing component uploaded through a Marketplace bundle would throw an error. It is now possible to download a new version of the same component. (Ticket 286141) +* (General) We have updated the supported versions of Grafana and Loki. (Ticket 291148) +* (General) We have improved the UI to make it clear that the secret store cannot be enabled for custom environment variables, custom JVM options, and custom Jetty options. (Ticket 291073) +* (General) We have fixed an issue where constant values were not saved in the Key Vault. (Ticket 290997) +* (General) We have clarified some messages displayed in the UI when updating constant values with a secret store enabled. (Ticket 290482) +* (General) We have fixed an issue where a blank option was displayed in the **Secret Store Type** dropdown. (Ticket 290090) +* (General) We have fixed an issue where the Debugger password was encoded twice. (Tickets 289313, 289613) +* (General) We have fixed an issue where randomly-generated Debugger passwords sometimes did not fulfill the requirements. (Ticket 285508) +* (General) We have fixed an issue where it was possible to submit an Admin password change more than once. (Ticket 283650) +* (General) We have fixed an issue where the **Resource Role** dropdown was incorrectly labeled **Platform Role**. (Ticket 287020) +* (General) We have fixed an issue where inviting users with Git access roles (for example, Developer) to a project failed with the error *Group not found* because of incorrect naming of ADO groups in the code. (Ticket 290571) +* (General) The option to select **Automatic (Azure Key Vault Only)** in the **Secret Store Type** dropdown is now disabled for cluster types other than **AKS**. +* (General) We have fixed an issue where no error message was shown when saving a secret without the `Key Vault write` permission. +* (General) Selecting the **Store to Secret Manager** option now prevents the creation Constant and Runtime Setting names with characters that are not accepted by the Secret Manager. +* (General) We have fixed an issue where it was possible to copy the Debugger password more than once. +* (General) We have fixed an issue where claim values were not validated correctly. +* (General) We have fixed an issue with OIDC claim mapping, where users were not added to groups correctly. +* (General) We have resolved an issue where the UI did not show that a pod was restarting after an admin password change. +* (General) We have resolved an issue where importing an app with the **Import App** function would show an error about group ownership. +* (General) We have resolved an issue where an app imported with the **Import App** function would not appear in the **My Apps > Direct access** section of the home page. +* (General) We have resolved an issue where logs and events were not visible with Azure Monitor selected as a data source for logs. +* (General) We have fixed an issue where the Build pod `git` step would fail on Azure DevOps Servers. +* (General) We have fixed an issue where a trailing slash in the Grafana URL would cause the auto-generated **View Log** URLs to become malformed. +* (General) We have fixed an issue where masked hidden constant values could be included in an export to a .yaml file. +* (General) We have fixed an issue where the graph on the **Platform Statistics** page was zoomed in. +* (General) In order to the improve security score ratings for container images, we have updated Private Mendix Platform and its components to their latest dependency versions. + +#### Known Issues + +##### Versioned Widget Files Require Cleanup + +After upgrading to Private Mendix Platform 2.8.2, environments with versioned widget files (for example, *Widget4_0_0.mpk*, *Widget3_9_9.mpk*) need manual cleanup. You must perform the following steps: + +1. Remove old versioned widgets from the *widgets* folder, manually rename them by removing version from the widget name. +2. Re-download the widget from Private Mendix Platform if needed. The widget will now use the correct naming, for example, Widget.mpk. + +##### Issue with Managed Identity Registration for Automatic Secret Store through API + +Registering a customer-provided Azure Managed Identity for the Automatic Secret Store feature is not yet supported through the `Deploy/ApplyConfig` API when the identity was created outside of Private Mendix Platform. This applies specifically to environments running on namespaces configured with non-Azure Workload Identity storage plans, where the Automatic Secret Store feature is being enabled using a self-managed identity. + +This configuration step is fully supported through the Private Mendix Platform GUI. All other environment configuration operations continue to work as expected through API before and after this step. Support for registering externally-created managed identities through the API is planned for a future release. + +##### Updates to Resource Limits Not Applied in Connected Mode + +In Connected mode, after changing the deployment resources for CPU and memory requests and limits, the changes are not applied when creating a new environment. + +##### Mendix Version Not Displayed + +For apps created in Studio Pro, the Mendix version is shown as N/A in the Private Mendix Platform UI. The issue does not affect apps created in Private Mendix Platform. + +##### OIDC Claim Group Mapping Allows Duplicates + +The **OIDC Client Configuration UI** allows creating duplicate **Claim Group Mapping** entries with identical configurations. This may result in problems when users log in, if Private Mendix Platform cannot determine which mapping to apply. + +##### SAML Users Are Not Assigned a Default Role + +Users logging in through SAML SSO are not assigned a default role when their accounts are created. + ## 2.8.1 ### Release date: September 25, 2026 diff --git a/static/attachments/private-platform/pmp-manage-recent-logs.png b/static/attachments/private-platform/pmp-manage-recent-logs.png new file mode 100644 index 00000000000..5a5b31873b5 Binary files /dev/null and b/static/attachments/private-platform/pmp-manage-recent-logs.png differ diff --git a/static/attachments/private-platform/pmp-vc6.png b/static/attachments/private-platform/pmp-vc6.png new file mode 100644 index 00000000000..7745dbae4ad Binary files /dev/null and b/static/attachments/private-platform/pmp-vc6.png differ diff --git a/static/attachments/private-platform/pmp-vc7.png b/static/attachments/private-platform/pmp-vc7.png new file mode 100644 index 00000000000..1e6762b5902 Binary files /dev/null and b/static/attachments/private-platform/pmp-vc7.png differ diff --git a/static/attachments/private-platform/pmp-vc8.png b/static/attachments/private-platform/pmp-vc8.png new file mode 100644 index 00000000000..7224b91b7b7 Binary files /dev/null and b/static/attachments/private-platform/pmp-vc8.png differ