Preparing for DX Cloud

Introduction

Moving to Magnolia’s DX Cloud is an exciting step, but there are key aspects to prepare before onboarding. This guide outlines what you need to have ready, how the onboarding process works, and what to expect at different stages of your DX Cloud journey.

Before onboarding

Before the onboarding meeting, Magnolia’s team ensures that:

  • Your subscription is set up in the Admin Cockpit.

  • You have received your shortname (your unique subscription name).

  • The Cockpit URL is functional.

  • Magnolia’s author and public instances are operational.

Understanding the DX Cloud architecture

paas architecture premium

Cluster setup

  • Initially, you receive a development (non-prod) cluster.

  • The production (prod) cluster is only provisioned when the project nears maturity.

  • Clusters run on AWS, Azure, Google Cloud Platform, or AliCloud.

  • Magnolia’s SRE team provisions the clusters with the chosen cloud provider.

Customer access

  • You have access to the customer Cockpit.

  • Customers do not have access to Rancher (Kubernetes management tool).

  • We provide an architecture diagram detailing components and configurations to ensure you have a high level understanding of how everything works together.

    See DX Cloud Architecture for more on this topic.

What Magnolia provides

Standard stack

  • GitLab (default for version control and CI/CD pipelines)

    See GitLab CI/CD for more on this topic.

  • Kubernetes orchestrator

    See Kubernetes fundamentals for more on this topic.

  • Docker Registry (default is GitLab-based, but you can bring your own)

  • Custom GitLab URL

GitLab & CI/CD configuration

If you choose our DX Cloud standard, you receive a dedicated GitLab URL. (e.g., gitlab.customer.magnolia-platform.com)

You can opt to use your own GitLab, Azure DevOps, GitHub, or BitBucket pipelines. You are always responsible for maintaining the pipeline. However, in this case, you are also responsible for setting up the pipeline.

Repository Structure

Using our stack

If you decide to use our DX Cloud repository setup, a base-dev repository is provided as a starting point. You should also create a new environment called dev where you use the base-dev repository as the template.

Using your own stack

If you want to use your own repository setup, we demonstrate during onboarding how everything works using our templates. However, you must then replicate that in your own GitLab CI/CD setup.

  • You can rename projects but must retain the shortname assigned at the contract stage.

  • You should called your production repository, prod and your development repository dev (instead of base-<environment>.)

  • Regional Magnolia repositories (regional-<region>) exist but are not customer-accessible.

Deployment Pipeline

The GitLab CI/CD pipeline includes:

  1. Build Stage: Triggers at every commit to build Magnolia.

  2. Push Stage: Pushes the Docker image to the registry.

  3. Deploy Stage: Uses Helm charts to deploy to the environment.

    • Deployment to the UAT, dev, and prod environments is manual (controlled via GitLab UI).

    • The values.yml file defines deployment variables and must match the registry secret (gitlab by default).

Maven & Nexus authentication

Understanding Magnolia’s authentication systems is critical for successful DX Cloud deployment and CI/CD pipeline operation.

Magnolia operates two distinct Single Sign-On (SSO) systems. These are separate authentication systems.

Your DX Cloud SSO credentials (used to access GitLab) are different from your Magnolia Services SSO credentials (used to access Nexus).

  1. DX Cloud SSO - for infrastructure services

    • Cockpit (Admin interface)

    • Rancher (Kubernetes management)

    • GitLab (Version control & CI/CD)

  2. Magnolia Services SSO - for development services

    • Nexus (Maven repository)

    • Academy (Training platform)

    • Partner Portal

Authentication migration: LDAP to SSO

Legacy LDAP authentication has been deprecated.

  • The migration was announced in December 2024.

  • The legacy LDAP system was fully shut down in June 2025.

  • Old "robot" Nexus accounts using LDAP credentials no longer work.

If your CI/CD pipelines suddenly fail with authentication errors when accessing Nexus, you likely need to migrate from LDAP credentials to SSO user tokens.

Obtain Nexus SSO user tokens

To configure your Maven credentials for pipeline builds, you’ll follow the instructions at Set up credentials in Maven settings.

Once you have your user tokens, you can update your GitLab CI/CD variables with the new values.

If you don’t want to use a personal account for your automation pipeline, send us a bot account email via a support ticket where we will grant it proper permissions for CI/CD usage.

Update pipeline credentials

Your CI/CD pipeline requires Maven credentials to download Magnolia modules from Nexus during the build process.

  1. In GitLab, go to Settings > CI/CD > Variables.

  2. Update the following variables:

    Variable Name Value Description

    MAVEN_USER

    Your user token name code

    The username portion of your Nexus SSO token

    MAVEN_USER_PWD

    Your user token pass code

    The password portion of your Nexus SSO token
    Variable scope recommendations

    • Create these variables at the group level to apply them to both frontend and backend repositories

    • Mark them as Masked to prevent exposure in build logs

    • Mark them as Protected if you only want them available on protected branches

Regenerate Nexus SSO user tokens

Your Nexus user tokens will need to be regenerated when:

  • Your SSO password changes or expires

  • You manually revoke the token in Nexus

  • Security requirements mandate token rotation

To regenerate your token, follow the same process outlined in Obtain Nexus SSO user tokens, then update your GitLab CI/CD variables with the new values.

Accessing Kubernetes

  • You do not interact directly with Kubernetes.

  • Deployment authentication is handled via GitLab CI/CD settings using three key variables:

    Variable Description

    KUBE_CONFIG

    Kubernetes configuration file for cluster access. Provided by Magnolia’s SRE team upon request.

    MAVEN_USER

    Your Nexus SSO user token name code. Required for downloading Magnolia modules during the build stage.

    See Maven & Nexus authentication for how to obtain this.

    MAVEN_USER_PWD

    Your Nexus SSO user token pass code. Required for downloading Magnolia modules during the build stage.

    See Maven & Nexus authentication for how to obtain this.

  • Magnolia’s SRE team provides the KubeConfig file upon request via support ticket.

Support

You must open a support ticket to:

  • Request a Kubernetes service account

  • Obtain your KUBE_CONFIG file

  • Store required secrets in Rancher

Secrets & Authentication

  • A GitLab access token is required for orchestrator-to-registry communication.

  • If using a custom registry, you must provide the registry domain in your support ticket.

By default, the Kubernetes secrets name is gitlab and contains the required credentials. You can name it what you want; however, it must match the image.pullSecrets.name value in the Helm value: Images. If you do change it, you must inform us so we can create the equivalent name in Kubernetes.

Troubleshooting

Pipeline fails with Maven authentication errors

Symptoms:

  • Build stage fails with "401 Unauthorized" errors

  • Error messages reference nexus.magnolia-cms.com

  • Dependencies cannot be downloaded from Magnolia repositories

Causes and solutions:

Cause Solution

Using legacy LDAP credentials

Migrate to SSO user tokens. See Maven & Nexus authentication.

MAVEN_USER or MAVEN_USER_PWD variables not set

Configure these variables in GitLab CI/CD settings. See Update pipeline credentials.

Variables set at project level instead of group level

Move variables to group level to ensure they apply to all repositories.

Tokens expired after password change

Regenerate your Nexus user tokens and update the GitLab variables. See Regenerate Nexus SSO user tokens.

Using wrong Nexus regional URL

Verify your pom.xml references the correct regional Nexus URL:

  • EU: https://nexus.magnolia-cms.com

  • US: https://nexus.us.magnolia-cms.com

  • APAC: https://nexus.ap.magnolia-cms.com

Old "robot" Nexus account stopped working

Symptoms:

  • Previously working pipeline suddenly fails

  • Using a service account created before December 2024

  • Account username suggests LDAP format (e.g., robot-*)

Solution:

Legacy LDAP authentication was deprecated in December 2024 and shut down in June 2025. You must migrate to SSO user tokens:

  1. Log into Nexus using SSO (not legacy login)

  2. Generate new user tokens

  3. Update your GitLab CI/CD variables with the new tokens

See Maven & Nexus authentication for complete instructions.

Pipeline succeeds but deployment fails

Symptoms:

  • Build and push stages complete successfully

  • Deploy stage fails with authentication or permission errors

  • Error messages reference Kubernetes or Helm

Causes and solutions:

Cause Solution

Missing or invalid KUBE_CONFIG

Request the KubeConfig file from Magnolia’s SRE team via support ticket. See [Accessing Kubernetes].

Registry secret misconfigured

Verify the secret name in your values.yml matches the Kubernetes secret name. By default, this should be gitlab. See Secrets & Authentication.

Insufficient Kubernetes permissions

Open a support ticket to verify your service account has the necessary permissions.

Cannot access GitLab or Nexus after password change

Symptoms:

  • GitLab login still works (PaaS SSO)

  • Nexus authentication fails (Services SSO)

  • Pipeline breaks after password change

Solution:

Remember that DX Cloud SSO and Magnolia Services SSO are separate systems:

  • GitLab/Cockpit/Rancher: Uses DX Cloud SSO - your password change is automatically reflected

  • Nexus/Academy/Partner Portal: Uses Services SSO - you must regenerate user tokens

After changing your Services SSO password:

  1. Log into Nexus with your new password

  2. Generate new user tokens

  3. Update MAVEN_USER_PWD in GitLab CI/CD variables

How to verify Maven credentials locally

If you want to test your Nexus credentials before updating the pipeline:

  1. Create or update your local ~/.m2/settings.xml:

    <settings>
  <servers>
    <server>
      <id>magnolia.nexus.enterprise</id>
      <username>YOUR_USER_TOKEN_NAME_CODE</username>
      <password>YOUR_USER_TOKEN_PASS_CODE</password>
    </server>
  </servers>
</settings>

  2. Run a test Maven command:

    mvn dependency:get \
  -DremoteRepositories=https://nexus.magnolia-cms.com/repository/enterprise \
  -DgroupId=info.magnolia \
  -DartifactId=magnolia-core \
  -Dversion=6.3.0

  3. If successful, your credentials are valid and can be used in GitLab CI/CD.

    For complete Maven configuration details, see: Maven setup documentation.

Still having issues?

If none of these solutions resolve your issue:

  1. Check GitLab CI/CD for CI/CD pipeline specifics

  2. Review DX Cloud Architecture for a system overview

  3. Contact your Technical Account Manager (TAM) or open a support ticket.

Include the following information in your support request:

  • Full error message from the failed pipeline stage

  • GitLab project/group path

  • Confirmation that CI/CD variables are configured at the correct scope

  • Whether the issue started after a recent change (password reset, configuration update, etc.)

Why is this all important?

By preparing the necessary accounts, credentials, and configurations ahead of time, you ensure a smooth and efficient DX Cloud onboarding experience. If you have any questions, reach out to your Technical Account Manager (TAM) or Magnolia Support.

Feedback

PaaS

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Cloud docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules