Skip to main content

Step-by-Step Guide for Experts

Step-by-Step Guide for Experts

Read this for general information, or for a refresh on the build process. For detailed instructions, see Detailed Instructions.

ICDP INTERNAL - This document describes how to build a new mDIS instance via a CI/CD pipeline.

The new instance will be populated with the standard datamodel, and a few test records. The new instance will be available as a persistent Docker image, which can be downloaded and run on a server.

The new instance gives you a good starting point for further customization and deployment.

Introduction

The build process of mDIS can be started via a web page on git.gfz.de, assuming familiarity with Gitlab CI/CD, Docker, and the mDIS codebase.

In a nutshell, the build process is as follows:

  1. Make a commit to a foundation-images- or blank-images branch, and push it to this repository,
  2. A build pipeline will start after each commit to any of those branches, assuming the pipeline is not disabled, and the runner is available,
  3. Your set of GitLab CI/CD variables determines how a new mDIS instance will be built,
  4. Finally, a new Docker image will be created and uploaded to the mDIS-foundation container registryopen in new window or the mDIS-blank container registryopen in new window on GFZ Gitlab.

Admin and Developer Access needed

To trigger the build pipelines, you need developer/commit access to this repo. For setting the repo CI/CD config variables, mDIS-configuration variables (e.g., .env files), and mDIS backend-database settings, you'll need admin access to the mDIS GitLab project.

You should also have "internal" access to the mdis-hub repoopen in new window. This repo serves as a Docker container registry, comprising several sub-repos, each with its own namespace. Some of these repos are public, while others are private.

Knowledge needed

A lot of GitLab CI/CD is needed. Additionally, you need developer knowledge about PHP, NodeJS, and some MySQL admin knowledge. Perhaps you need tweak the mDIS source code to make it work properly with PHP 8.3. mDIS was developed for PHP 7.4, and the port to PHP 8.3 is still ongoing as of 2025.

Workflow - Executing the pipeline - First Look

Adapting the CI/CD settings:

You need access to the mDIS GitLab repository and its CI/CD settings. Carefully check these settings.

  • GitLab Runner: See mDIS Build System: Runners
  • CI/CD Variables: Many CI/CD variables exist, determining instance names, GitLab repo branches, and more.

Important variables include:

  • MDIS_CUSTOM_INSTANCE_NAME: Instance name on the dashboard and reports, e.g., mdis-samplehub
  • MDIS_CUSTOM_PATH: URL path fragment for your instance, e.g., mdis/samplehub
  • And several others. See Detailed Instructions or List of CI/CD Variables.

Most CI/CD variables can be left as is or rarely need adaptation (e.g., database credentials, different PHP foundation image).

Then:

  1. Check your branch and the .gitlab-ci.yml file, which defines the build pipeline.
  2. Assess the pipeline's complexity and actions.
  3. Switch to a branch with the desired pipeline configuration. The master branch has a simple pipeline, while git-gfz--ci-cd branches are more complex.
Adapting the codebase:

First, clone the mDIS repository from the GFZ GitLab server.

Next, choose a branch:

  • Beginners: Use the master-gitlab-ci-cd branch for a raw, unadapted PHP-8-based mDIS instance.
  • Experts: Use the foundation-images und blank-images. branches for customized development builds. These branches are created manually after substantial changes in the main mDIS codebase. Merge new code from master into master-gitlab-ci-cd, then into the new foundation-images und blank-images. branches. Adapt this branch to new requirements and build a new mDIS image by changing a variable in the GitLab CI/CD settings.

To summarize: Leave the master branch alone, create a PHP8-based branches with a few adaptations, and create new those branches for new builds. Merge them as needed.

Starting the build pipeline:

See the GitLab CI variable "BRANCH_CUSTOM" for the branch to commit to. Make a trivial change (e.g., add a space) and commit it. Push the change to start the build pipeline, which will create a new mDIS instance as a Docker image. The image will be uploaded to Docker registryopen in new window with docker push. You can then download it with docker pull.

HOWEVER:

  • mDIS builds do not automatically deploy to production.
  • The pipeline does not create a new MySQL database or credentials; you must do this as a prerequisite. The build process can optionally populate the new database with minimal test data.

Continued at: