Documentation:Docker on MacOS- Installing MDriven Server and MDriven Turnkey on Ubuntu Containers

Docker on MacOS- Installing MDriven Server and MDriven Turnkey on Ubuntu Containers

This page was created by Lydia on 2025-11-21. Last edited by Wikiadmin on 2026-09-11.

You can run MDriven Server and MDriven Turnkey locally on macOS in Ubuntu-based Docker containers for development and testing.

This guide uses MDriven's prepared local Docker setup. Docker runs the Linux applications inside containers, so you do not install the MDriven applications or a separate web server directly on macOS.

Choose the correct setup package

Download the Ubuntu local Docker package that matches your Mac processor:

Mac processor	Check in Terminal	Package to use
Intel Mac	`uname -m` returns `x86_64`	Ubuntu AMD64
Apple Silicon Mac (M1, M2, or M3)	`uname -m` returns `arm64` or `aarch64`	Ubuntu ARM64

Using an AMD64 package on an Apple Silicon Mac can cause the containers to stop with an exec format error.

For the available local packages and the general local-Docker workflow, see Documentation:Running MDriven Locally with Docker. For a Docker setup that includes production-oriented components such as Nginx and a database service, see Documentation:Deploying MDriven Server and Turnkey with Docker.

Prerequisites

Before starting, install and start Docker Desktop.

Install Docker Desktop for your Mac and open it.
Wait until Docker Desktop indicates that the Docker daemon is running.
Open Terminal and verify that Docker can communicate with the daemon:

docker --version
docker info

If either command cannot connect to Docker, start Docker Desktop and wait for it to finish starting. For Docker Desktop installation options on Intel Macs, see Documentation:Deployment: Two Ways To Install Docker Desktop on MacOS Intel.

Install Homebrew as a dependency for macOS development tools: Install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Verify the installation:

brew --version

Start MDriven in Ubuntu containers

Extract the downloaded Ubuntu Docker package to a working folder. For example:

mkdir -p ~/mdriven-local
== Extract the downloaded package into ~/mdriven-local ==
cd ~/mdriven-local

Confirm that the extracted folder contains the supplied Compose configuration, normally named compose.yaml or docker-compose.yml.
From that folder, start the services in the background:

docker compose up -d

Check that the containers are running:

docker compose ps

A Docker image is the packaged application template. A Docker container is a running instance of that image. The supplied Compose configuration defines the MDriven Server and Turnkey containers together, including their connection and host-port mappings.

Rebuild when you changed Docker build files

Use the following command only when your extracted setup includes Dockerfiles that you have changed, or when you need to rebuild the local images without Docker's build cache:

docker compose build --no-cache
docker compose up -d

For normal use of a prepared MDriven Compose setup, start with docker compose up -d.

Verify the services

The prepared local setup exposes these default endpoints. Check the actual port mappings in your Compose configuration if your package differs.

Service	Default local URL	What to check
MDriven Server	`http://localhost:5011`	The server responds in the browser.
MDriven Turnkey	`http://localhost:5012`	The Turnkey application responds in the browser.

Open http://localhost:5011 in a browser to verify MDriven Server.
Open http://localhost:5012 in a browser to verify MDriven Turnkey.
If a page does not respond, inspect the service logs:

docker compose logs
docker compose logs --follow

You can also select a container in Docker Desktop to view its logs, status, port mappings, and resource usage.

Use this matrix to confirm each service is responding correctly:

Application	URL	Verification Command
MDriven Server	http://localhost:5055	`curl -vk http://localhost:5055`
MDriven Turnkey	http://localhost:5025	`curl -vk http://localhost:5025`

Upload a model

After both containers are running, use MDriven Designer to upload a model to the local environment. A Turnkey process can be running correctly but continue loading until a model has been uploaded.

Use the Turnkey endpoint from your Compose configuration. In the prepared local setup, the browser endpoint is normally http://localhost:5012.

Complete the setup by uploading a model through these steps:

Open MDriven Designer
Connect to the Turnkey endpoint (http://localhost:5025)
Upload a model to complete end-to-end validation

Change ports when a port is already in use

If Docker reports an error such as Bind for 0.0.0.0:5011 failed, another process is already using that host port.

Open compose.yaml or docker-compose.yml in a text editor.
Find the mapping for the conflicting port.
Change the host-side port while retaining the container-side port. For example, change 5011:5011 to 5013:5011.
Restart the setup:

docker compose up -d

Browse to the new host port; in this example, http://localhost:5013.

Stop, restart, and preserve data

Use these commands from the folder containing the Compose configuration:

Task	Command
Stop services	`docker compose stop`
Start stopped services	`docker compose start`
Stop and remove containers	`docker compose down`
View running containers	`docker compose ps`

The supplied Docker setup uses persistent storage. Stopping or removing containers does not necessarily remove application data, logs, or settings because Docker volumes and host bind mounts remain. This is intentional: for example, the MDriven Server administrative VistaDB file can be stored under settings/mdriven-server on the host and mounted into the container.

Do not remove volumes when you want to retain your local application state. If you need a clean environment, follow the data-reset guidance in Documentation:Deploying MDriven Server and Turnkey with Docker.

Configuration and troubleshooting

The Compose configuration is the place to change container settings and mounts. MDriven's prepared configurations support settings such as application version selection through UPDATE_APP, lowered container permissions through PUID and PGID, and a password reset file for the MDriven Server connection user. Follow Documentation:Deploying MDriven Server and Turnkey with Docker before changing these settings.

For a larger Compose deployment and an explanation of startup ordering, health checks, and the supplied container entry points, see Documentation:Advanced Docker Compose Configuration for MDriven.

If you do not need containers, use the native macOS installation procedure instead: Documentation:MDriven Server & MDriven Turnkey On Native MacOs.

2. Download MDriven Server + Turnkey Docker Files

The extraction process creates a folder structure like this: Error creating thumbnail: File missing

After extraction, your working folder contains the following: Error creating thumbnail: File missing

Inspect the Extracted Files

Verify the compose.yaml file is present in your extracted folder: Error creating thumbnail: File missing

Check that the Docker build files are included: Error creating thumbnail: File missing

Confirm the services configuration is properly set up: Error creating thumbnail: File missing

Review the environment variables in the configuration: Error creating thumbnail: File missing

Inspect the complete folder structure to ensure all files are present: Error creating thumbnail: File missing

3. Build and Run the Containers

Use these commands to rebuild and start your containers: Open Terminal, navigate to the directory containing the docker-compose.yml and Dockerfiles, then rebuild the images from scratch:

docker compose build --no-cache

Start all services in detached mode:

docker compose up -d

Error creating thumbnail: File missing

Optional: Use Docker Desktop GUI

You can also monitor container startup from Docker Desktop: Error creating thumbnail: File missing

Expected Output

The containers should start successfully with this output: Error creating thumbnail: File missing

Once running, the services will be accessible at their configured endpoints: Error creating thumbnail: File missing

Contents