MDM Example Project on macOS

The following guide shows you how to install and run the latest MDM example project on macOS. The example project provides a preconfigured environment for working through MDM tutorials.

For Windows instructions, see mdm-example-project.adoc.

Prerequisites

Install and run Docker Desktop.
Make sure ports 8083 and 5432 are available on your machine.

To check if a port is in use, run lsof -i :<port_number> in Terminal. No output means the port is available.

Step 1: Download PostgreSQL and Keycloak Docker images

Use PostgreSQL and Keycloak Docker images to easily deploy the services needed for the MDM example project.

The Docker images are intended for demonstration purposes only and are not meant for production environments. By using these, you are accepting Keycloak and PostgreSQL licenses.

Keep in mind that the third-party software used in the Docker images might not be up-to-date and might therefore pose a security risk.

Download MDM Example Project Plugins from the Support Service Desk.

Step 2: Download and extract builds

Download the corresponding build packages of MDM Server and MDM Web Application (Linux variant), and ONE Desktop (macOS variant) from the Support Service Desk.

Extract packages

Install ONE Desktop. Double-click the downloaded ONE Desktop package and drag it to the Applications folder instead.
Create the required folders in the ONE Desktop installation directory:
```
cd "/Applications/ONE Desktop.app/Contents/Eclipse"
mkdir -p macos-example mdm mdm-server pginit
```
Replace macos-example with your preferred workspace folder name.
Extract the downloaded packages:
```
unzip path/to/mdm-assembly-xxxxx.zip -d mdm
unzip path/to/mdm-server-assembly-xxxxx.zip -d mdm-server
unzip path/to/pginit17.zip -d pginit
```
Replace path/to/ with the location of your downloaded files and xxxxx with the version number of your packages.
Verify the folder structure:
```
ls mdm mdm-server pginit
```
Your folder structure should match the following. This ensures the scripts in the example project Files > bin work without issues.

Details
Grant the necessary permissions:
```
cd "path/to/macos-example"
chmod -R 777 workspace
chmod -R +x mdm/bin mdm-server/bin
```
Replace path/to/macos-example with the absolute path to your folder (for example, /Applications/ONE Desktop.app/Contents/Eclipse/macos-example).

This sets full read, write, and execute permissions for all users on the folder contents. This is acceptable for a local demo environment but is not advisable in production.

Step 3: Start the Docker containers

Load and run the Keycloak and PostgreSQL Docker containers.

Navigate to the folder where you downloaded the Docker images and load them into your local Docker image store:
```
docker load -i kcMac.tar
docker load -i pg17Mac.tar
```
If loading was successful, the following output appears:
```
Loaded image: harbor.ataccama.dev/one/keycloak:26.2.0-14
Loaded image: postgres:17
```
Run the PostgreSQL container:
```
docker run -d --name pg \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=Testtest1 \
  -v "path/to/macos-example/pginit:/docker-entrypoint-initdb.d" \
  postgres:17
```
Replace path/to/macos-example with the absolute path to your folder (for example, /Applications/ONE Desktop.app/Contents/Eclipse/macos-example).

If the command was successful, the container ID is returned in response.

If you get a "mounts denied" error, you need to allow Docker to access the workspace folder. See Docker file sharing documentation for instructions.

Run the Keycloak container:

docker run -d --name kc \
  -p 8083:8080 \
  -e KC_CLIENTS_REDIRECT_URIS_WILDCARDED=true \
  -e KC_CLIENTS_WEB_ORIGINS_WILDCARDED=true \
  -e KC_TEST_USERS_INCLUDED=true \
  -e KC_SSL_REQUIRED=NONE \
  harbor.ataccama.dev/one/keycloak:26.2.0-14 \
  start --db=dev-file

Verify that both containers are running:

docker ps

The expected output is as follows:

CONTAINER ID   IMAGE                                            CREATED              STATUS                PORTS                                       NAMES
6bcffaf2c5e2   harbor.ataccama.dev/one/keycloak:26.2.0-14       10 seconds ago       Up 10 seconds         0.0.0.0:8083->8080/tcp                      kc
a3c16a14aecc   postgres:17                                      About a minute ago   Up About a minute     0.0.0.0:5432->5432/tcp                      pg

Step 4: Start the example project

Start ONE Desktop. Confirm that you want to run the application.

For detailed instructions, see Install ONE Desktop.
When prompted to select your workspace, point it to the folder you created earlier (for example, macos-example).
In the upper-right corner, switch to the ONE Desktop perspective.
In the Model Explorer, select New Model Project Wizard.
For the initial model, use the default template (General MDM project - CDI example) and select Finish.

If you choose a custom project name, avoid using spaces to simplify working with file paths. If your project name contains spaces, make sure to enclose paths in quotes.
Once the project loads in the Model Explorer, navigate to Files/bin.
Open start-mdm-server.sh in a text editor and replace the last line (the start command) with the following:
```
"/path/to/macos-example/mdm-server/bin/start.sh" -config="/path/to/macos-example/workspace/<project_name>/Files/etc/mdm.serverConfig" start
```
Replace path/to/macos-example with the absolute path to your workspace folder (for example, "/Applications/ONE Desktop.app/Contents/Eclipse/macos-example") and <project_name> with the name of your project folder (by default, General MDM project - CDI example).
Open start-mdm.sh in a text editor and replace the last line (the start command) with the following:
```
/path/to/macos-example/mdm/bin/start.sh
```
Replace path/to/macos-example with the absolute path to your workspace folder (for example, /Applications/ONE Desktop.app/Contents/Eclipse/macos-example).

Save and close both files before proceeding. If a file is still open in ONE Desktop, you cannot run it.
Start the MDM Server. Open a Terminal window and run:
```
bash "path/to/macos-example/workspace/<project_name>/Files/bin/start-mdm-server.sh"
```
Replace path/to/macos-example with the absolute path to your workspace folder and <project_name> with the name of your project folder.

The MDM Server is ready once the following message appears:
```
actionId=start-server-application-context status=FINISH duration=<number>>ms
```

Start the MDM Web Application. Open a new Terminal window and run:

bash "path/to/macos-example/workspace/<project_name>/Files/bin/start-mdm.sh"

Replace path/to/macos-example and <project_name> as before.

The MDM Web Application is ready once the following message appears:

Started MdaWebApplication in <number> seconds (process running for <number>)

You can also run the scripts from ONE Desktop by double-clicking them in Files/bin in the Model Explorer. However, as ONE Desktop displays one script at a time in the console, you can stop the running process using Ctrl+C or by finding and shutting it down (see Stop a process manually).

Once everything starts, open one of the following in your browser:
- http://localhost:8050 — MDM Web Application
- http://localhost:8051 — MDM Web App Admin Center
Log in with the following credentials:
- Username: admin
- Password: admin

Step 5: Stop the example project

When you are finished working with the MDM example project:

Stop the MDM Server and Web Application by closing their terminal windows.
Stop the Docker containers by running:
```
docker stop kc
docker stop pg
```

Tips and troubleshooting

Restart after the initial setup

If you have already completed the initial setup and just need to restart:

Start the Docker containers:
```
docker start pg
docker start kc
```
Start ONE Desktop, then run start-mdm-server.sh and start-mdm.sh as described in Step 4: Start the example project.

Stop a process manually

If you need to stop a running server, or if a server fails to start because a port is already in use, find and stop the process:

lsof -i :<port_number>
kill <PID>

Replace <port_number> with the port used by the server and <PID> with the process ID from the lsof output.

View logs

The default logging file path is defined using the DEFAULT_JVM_OPTS property in the /mdm/bin/start.sh file.

Was this page useful?