Documentation:Running MDriven Locally with Docker

Running MDriven Locally with Docker

This page was created by Charles on 2026-01-29. Last edited by Wikiadmin on 2026-07-29.

You can run MDriven Server and MDriven Turnkey in Linux Docker containers on your local Windows, Linux, or macOS machine for local development and testing.

This setup uses Docker Compose, a tool that starts the related containers defined in one compose.yaml file. Docker runs MDriven in Linux containers; the host operating system can be Windows, Linux, or macOS.

Before you start

Install Docker and make sure the Docker daemon is running before starting the setup. On macOS, use Docker Desktop installation guidance. For an Ubuntu-container walkthrough on macOS, see Documentation:Docker on MacOS- Installing MDriven Server and MDriven Turnkey on Ubuntu Containers.

You need:

Docker with Docker Compose available in your terminal.
A downloaded MDriven local-development Docker package that matches the Linux distribution and processor architecture you will run.
A terminal: PowerShell on Windows, or Terminal on macOS and Linux.

To confirm that Docker is available, run:

docker --version
docker compose version

Choose the correct package

Choose the package by processor architecture first, then by Linux distribution. On Linux and macOS, run the following command to identify the architecture:

uname -m

Reported architecture	Choose this package architecture	Typical host
`x86_64`	AMD64	Standard Intel- or AMD-based Windows, Linux, and Mac computers
`aarch64`	ARM64	Apple Silicon Macs, including M1, M2, and M3

The local packages are available for the following combinations:

Linux distribution	AMD64	ARM64	When to choose it
Ubuntu	Available	Available	Recommended general-purpose choice.
Debian	Available	Available	Choose when you want the Debian distribution.
Alpine	Available	Not listed for this local setup.	Choose for a minimal, lightweight footprint.

If you use an Apple Silicon Mac, select an ARM64 package. Running an AMD64 container package on that host can fail with an exec format error.

For a broader explanation of the available Docker setups, Linux distributions, and persistent volumes, see Documentation:Deploying MDriven Server and Turnkey with Docker.

Start MDriven locally

Download the package that matches your selected distribution and architecture.
Extract the ZIP file to a working folder. For example, use mdriven-local.
Open a terminal in that folder. The folder must contain the supplied compose.yaml file.
Start the services in the background:

docker compose up -d

Docker Compose reads compose.yaml, creates or starts the required containers, and returns control of the terminal after the services are started.

Confirm that the containers are running

Run:

docker compose ps

Inspect startup output if a service is not running or is repeatedly restarting:

docker compose logs

To follow new log entries while the services start, run:

docker compose logs -f

Press Ctrl+C to stop following the logs; this does not stop the containers.

Open the local services

After the containers have started, open the published local endpoints in a browser:

Service	Default local address	What to expect
MDriven Server	`http://localhost:5011`	The MDriven Server startup page after initialization.
MDriven Turnkey	`http://localhost:5012`	The MDriven Turnkey startup interface.

Treat compose.yaml as the authority for the ports in your downloaded setup. For example, if its port mapping exposes host port 5013 for the MDriven Server container port 5011, browse to http://localhost:5013 instead.

When both endpoints respond, you can use MDriven Designer to connect to the local Turnkey endpoint and upload a model for end-to-end testing.

Stop and restart the environment

Use these commands from the folder containing compose.yaml:

Task	Command
Stop the services while retaining containers and data	`docker compose stop`
Start previously stopped services	`docker compose start`
Stop and remove the Compose containers and network	`docker compose down`
Show running Compose services	`docker compose ps`

The supplied Compose configuration can use mounted folders or volumes for persistent data. Do not remove persistent data unless you intend to reset the local environment. Read the volume guidance in Documentation:Deploying MDriven Server and Turnkey with Docker before changing or deleting bindings.

Change local configuration

Edit compose.yaml when you need to change settings such as published host ports, application-update behavior, or container user permissions. The standard MDriven Docker setup supports configuration through Compose settings, including:

UPDATE_APP for application version control.
PUID and PGID for running the applications with reduced privileges rather than as root.
A mounted PwdReset.txt file to reset the password for user a.

For the required folder structure, configuration files, service dependencies, and exact configuration patterns, use Documentation:Advanced Docker Compose Configuration for MDriven. That page describes an advanced setup and should be used when you need MySQL, Nginx, web-based Code Server access, or detailed override files.

Troubleshooting

A port is already in use

If Docker reports an error similar to Bind for 0.0.0.0:5011 failed, another process already uses that host port.

Open compose.yaml.
Find the port mapping for the affected service.
Change the host-side port while keeping the container-side port unchanged. For example, change 5011:5011 to 5013:5011.
Run docker compose up -d again.
Open the revised host address, such as http://localhost:5013.

The container fails with an architecture error

An exec format error commonly indicates that the package architecture does not match the host. Check uname -m, download the matching AMD64 or ARM64 package, then start the setup again.

A service does not become available

Run docker compose ps to identify the affected service.
Run docker compose logs to review its startup output.
Verify that Docker is running and that the local port is free.
Check the port mappings in compose.yaml and use the address defined there.

Contents