You can run MDriven Server and MDriven Turnkey in Linux Docker containers for local development or production deployment; this page helps developers and operators choose a prepared Docker Compose setup and manage its persistent configuration safely.

Choose a deployment path

Use the prepared Docker Compose configuration that matches where the application will run.

Scenario	Use this setup	What it includes
Local development on your own machine	Run MDriven locally with Docker	MDriven Server and MDriven Turnkey, exposed directly on local ports for iteration and debugging.
Public-facing Linux server	Deploy MDriven to production with Nginx	MDriven Server, MDriven Turnkey, and an Nginx reverse proxy for standard web entry points and domain-based deployment.
Custom multi-container configuration	Advanced Docker Compose configuration	A reference configuration with service dependency chains, health checks, persistent mounts, Nginx, and optional database services.

Do not use the local-development configuration as a substitute for the Nginx production configuration on a public-facing server.

Before you start

Docker packages an application and its runtime dependencies into a container. Docker Compose reads a compose.yaml file to start the related containers as one application.

1. Install Docker and ensure that it is configured to run Linux containers. MDriven Server and MDriven Turnkey run in Linux containers.
2. Obtain the prepared configuration for the deployment path you selected, then extract it into a working directory on the host.
3. Open a terminal in the directory that contains compose.yaml.
4. Check your Linux CPU architecture when selecting a package:

uname -m

x86_64 corresponds to AMD64 and aarch64 corresponds to ARM64.

On macOS Intel, see install Docker Desktop on macOS Intel. For an Ubuntu-container workflow on macOS, including build and start commands, see installing MDriven Server and Turnkey on Ubuntu containers.

Start and inspect a prepared Compose deployment

A prepared deployment is controlled from the folder containing compose.yaml.

1. Review compose.yaml and the settings/ directory before first start. Keep the settings directory with the deployment; it holds configuration that the containers mount at runtime.
2. Start the services in the background:

docker compose up -d

1. Confirm that the services are running:

docker compose ps

1. If a service does not start, inspect its output:

docker compose logs

1. For a local setup, open the endpoints specified by its compose.yaml. For the macOS Ubuntu-container example, Turnkey is available at http://localhost:5025 after the containers are running.

Use Docker Desktop when you want a graphical view of containers, logs, port mappings, images, and resource use. Docker Desktop is available for Windows and Linux as well as macOS.

What persists when containers are recreated

Stopping or removing a container does not necessarily remove its data. The prepared Compose files use persistent Docker volumes and host-directory bind mounts, so application state, logs, application files, and configuration can remain available after a container is recreated.

In particular, the MDriven Server administrator database file is persisted on the host at:

settings/mdriven-server/DatabaseVistaDB.vdb6

It is mounted in the MDriven Server container at:

/app/App_Data/DatabaseVistaDB.vdb6

Start with fresh data

To make a genuine fresh start, remove the persistent volumes used by the deployment as well as any persisted data you intend to discard. Stopping containers alone is not enough.

If you need to preserve the existing data while starting a separate environment, rename the relevant volume definitions in compose.yaml. For example, change MDSData to MDSDataV2 and MDTData to MDTDataV2. The new names create separate persistent storage; the prior volumes remain intact.

Warning: Removing volumes or deleting the persisted VistaDB file discards the data stored there. Back up data that you need before resetting an environment.

Configure the Compose deployment

Edit compose.yaml to change container environment variables and file bindings. Restart the affected containers after a change so that they read the updated settings.

Control the application version with UPDATE_APP

The UPDATE_APP environment variable controls which MDriven Server and Turnkey application files the containers use.

Value	Result	Example
true	Updates to the latest application files when the container starts.	UPDATE_APP=true
A date in yyyymmdd format	Selects that specific version. This can be used to upgrade or downgrade.	UPDATE_APP=20231024

Pin a date when you need a repeatable deployment version. Use true when the deployment is intended to follow the latest available application files.

Run with reduced container permissions

Set PUID=1000 and PGID=1000 in the Compose environment configuration to run the application processes with reduced permissions.

environment:
  PUID: 1000
  PGID: 1000

Use matching host permissions for the directories that the containers must write to. If the configured user cannot write to a mounted settings or data directory, the service can fail to create or update files.

Reset the password for user a

MDriven Turnkey uses the MDriven Server account named a to connect to MDriven Server. Reset both sides of this connection together.

1. Create PwdReset.txt containing the new password.
2. Place the file in settings/mdriven-server/.
3. Add a bind mount in compose.yaml that maps this host file to /pwdreset/PwdReset.txt in the MDriven Server container.
4. Open MDrivenServerOverride.xml in settings/mdriven-turnkey/ and change its password to the same new password.
5. Restart the containers. MDriven Server applies the password reset at the next container start.

Important: If you reset the MDriven Server password but do not update MDrivenServerOverride.xml, Turnkey continues trying the old password. This can lock account a again and leave Turnkey in an error state.

Linux container base images

Prepared configurations may use different Linux distributions. Choose the base image required by the configuration you are using; do not change it only to reduce image size.

Distribution	Characteristics	Suitable consideration
Alpine	Minimal and lightweight.	Use when the image and its required locale setup are already defined for Alpine.
Debian	Focuses on stability and compatibility; it is the upstream basis for Ubuntu.	A balanced choice for server environments.
Ubuntu	Includes a broader set of packages and tools, with a larger footprint.	Useful when the deployment needs its wider package and tooling set.

Alpine locale requirement for manual images

If you build your own Alpine-based image, install and configure locale support. MDriven Turnkey uses the operating-system locale to select its locale file. A missing or incorrectly configured locale can therefore cause locale-related errors.

The prepared packages handle their own image configuration. For a manual Compose and image design, use Advanced Docker Compose configuration for MDriven as the reference for service layout and dependencies.

Health checks and service networking

When you create or modify a Compose setup, keep the service startup order explicit.

• The MDriven Server must be available before Turnkey attempts to connect to it.
• When a database service is part of the Compose setup, wait for that database to be healthy before starting MDriven Server.
• Keep MDriven Server and MDriven Turnkey on a Docker network where they can communicate.
• Add a health check for MDriven Server. This allows Docker Compose to detect an unhealthy server and restart it, including cases where VistaDB has locked itself.

The advanced configuration demonstrates depends_on conditions based on service health so the expected startup order is database, MDriven Server, then Turnkey and related services.

Production notes

For a public-facing deployment, use the production package rather than exposing a local development configuration directly. The production package includes Nginx and settings directories for MDriven Server and Turnkey; database-specific packages can also include configuration for PostgreSQL, MySQL, or MSSQL.

The production guide covers these tasks:

• Set the Nginx server_name for your domain.
• Open only the required external ports, or use the documented single-domain subdirectory routing.
• Configure the database connection in the MDriven Server interface when you use a PostgreSQL, MySQL, or MSSQL package.
• Set the MDriven Server application path when routing it below /__MDrivenServer.

Follow Deploying MDriven to Production with Nginx for the complete production procedure.

See also

• Documentation:Running MDriven Locally with Docker
• Documentation:Deploying MDriven to Production with Nginx
• Documentation:Advanced Docker Compose Configuration for MDriven
• Documentation:Deployment
• Documentation:Docker on MacOS- Installing MDriven Server and MDriven Turnkey on Ubuntu Containers