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.
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.yamlordocker-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:5011in a browser to verify MDriven Server. - Open
http://localhost:5012in 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.
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.
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.yamlordocker-compose.ymlin 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:5011to5013: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.