You can use this advanced Docker Compose layout to run MDriven Server and MDriven Turnkey with MySQL, Nginx, and an optional browser-based file workspace; it is for administrators who are adapting an MDriven-provided production deployment package.
This page explains the structure and operating model of the advanced MySQL-based package. Start with the prepared package from Documentation:Deploying MDriven Server and Turnkey with Docker rather than creating a Compose file from the descriptions on this page. For a public-facing deployment, follow Documentation:Deploying MDriven to Production with Nginx.
What the deployment contains
Docker Compose defines and starts the containers that make up the deployment. The advanced layout uses the following services:
| Service | Purpose | Persistent or mounted content |
|---|---|---|
mysql
|
Runs MySQL 8.0 for an included MySQL database deployment. | Database files are stored in the host-side mysql-data directory. Initialization files are read from databases/mysql/init when the database is first created.
|
server-core
|
Runs MDriven Server, which manages the running model and application data. | Server configuration and the VistaDB administration database are mounted from settings/mdriven-server.
|
turnkey-core
|
Runs MDriven Turnkey, the web application that connects to MDriven Server. | Turnkey configuration is mounted from settings/mdriven-turnkey.
|
scm
|
Runs Code Server, a browser-based Visual Studio Code environment, when included in the supplied configuration. | The workspace can expose the MDriven Server and Turnkey data locations so that you can inspect files and logs. |
nginx
|
Runs Nginx as the reverse proxy in front of the other web services. | Its routing configuration is mounted from settings/nginx-proxy.conf.
|
The containers communicate over the Compose network. In particular, MDriven Turnkey connects to MDriven Server by its internal service address, while Nginx routes incoming requests to the appropriate service. Do not expose the database publicly unless you have separately designed and secured that access.
Prepare the deployment folder
Keep the downloaded folder structure intact. The Compose bind mounts refer to these relative locations.
Apps/
├── compose.yaml
├── databases/
│ └── mysql/
│ ├── mysql.env
│ └── init/
├── settings/
│ ├── nginx-proxy.conf
│ ├── mdriven-server/
│ │ ├── CommandLineOverride.xml
│ │ ├── DatabaseVistaDB.vdb6
│ │ └── PwdReset.txt (optional)
│ ├── mdriven-turnkey/
│ │ ├── CommandLineOverride.xml
│ │ ├── HardServerUrl.xml
│ │ ├── MDrivenServerOverride.xml
│ │ └── TurnkeySettingsOverride.xml
│ └── vscode/ (optional)
└── mysql-data/ (created or used for persisted MySQL data)
mysql.env holds the MySQL credentials used by the database service. The init directory holds the SQL initialization scripts. Configure the database and connect MDriven Server to it as described in Documentation:Configuring Production Databases PostgreSQL MySQL MSSQL.
Understand the mounted MDriven configuration
| File | Used by | Purpose |
|---|---|---|
settings/mdriven-server/CommandLineOverride.xml
|
MDriven Server | Supplies server startup overrides, such as host, port, or a path to an application subdirectory. |
settings/mdriven-server/DatabaseVistaDB.vdb6
|
MDriven Server | Stores the MDriven Server administration database on the host so it survives container recreation. |
settings/mdriven-server/PwdReset.txt
|
MDriven Server | Optional password-reset input for user a. The Compose configuration must mount it at /pwdreset/PwdReset.txt in the container.
|
settings/mdriven-turnkey/CommandLineOverride.xml
|
MDriven Turnkey | Supplies Turnkey startup overrides. |
settings/mdriven-turnkey/HardServerUrl.xml
|
MDriven Turnkey | Defines the external URL and port used to access Turnkey. |
settings/mdriven-turnkey/MDrivenServerOverride.xml
|
MDriven Turnkey | Defines Turnkey's internal MDriven Server connection, including the internal service URL and credentials for user a.
|
settings/mdriven-turnkey/TurnkeySettingsOverride.xml
|
MDriven Turnkey | Overrides Turnkey behavior and enables or disables Turnkey features. |
settings/nginx-proxy.conf
|
Nginx | Defines reverse-proxy routing. For a domain deployment, set its server_name to your domain as described in Documentation:Deploying MDriven to Production with Nginx.
|
Start the services
- Install and start Docker Desktop, or use a Docker environment that supports Linux containers.
- Open a terminal in the folder that contains
compose.yaml. - Review the mounted configuration files and the MySQL credentials before the first start.
- Start the stack:
docker compose up -d
The supplied configuration uses health-based dependencies. MySQL must be healthy before MDriven Server starts, and MDriven Server must be healthy before dependent services such as Turnkey start. This order prevents Turnkey from attempting to connect while its server or database dependency is not ready.
Use Docker Compose to inspect the service state and startup output:
docker compose ps
docker compose logs
For local-only development, use Documentation:Running MDriven Locally with Docker instead of exposing this advanced layout beyond your machine.
Access the services
The supplied advanced configuration exposes MDriven Server, MDriven Turnkey, and the Code Server workspace through the ports defined in compose.yaml. The package described by this page uses ports 5011, 5012, and 8080; confirm the published host ports in your own compose.yaml before opening a browser.
| Service | Typical local address | Use |
|---|---|---|
| MDriven Server | http://localhost:5011
|
Check server availability and configure the running model. |
| MDriven Turnkey | http://localhost:5012
|
Open the deployed Turnkey application. |
| Code Server | http://localhost:8080
|
Inspect mounted files and logs in the browser-based workspace when the scm service is enabled.
|
Treat Code Server as administrative access. Before making it available outside a trusted network, review its authentication settings and the Nginx routing configuration. Do not rely on a package default as an Internet-facing credential.
Configure MySQL persistence and initialization
On the first database start, MySQL uses the files in databases/mysql/init to create its schema. The MySQL service keeps its data in mysql-data on the host. Container removal or restart does not by itself remove that host-side data.
This has two practical consequences:
- Change MySQL credentials in
databases/mysql/mysql.envbefore initializing a new database. - Do not expect modified initialization scripts to rebuild an already initialized database automatically. Plan a controlled database reset or migration when you need a new schema state.
To connect MDriven Server to the database after the stack is running, configure the connection in the MDriven Server interface. The exact procedure and connection-string guidance are in Documentation:Configuring Production Databases PostgreSQL MySQL MSSQL.
Maintain application versions
The supplied MDriven container entrypoint supports the UPDATE_APP environment variable:
| Value | Result on container start or restart |
|---|---|
UPDATE_APP=true
|
Updates the application files to the latest available version. |
A value in yyyymmdd format, for example 20231024
|
Selects that specific application version, allowing an upgrade or downgrade. |
Set the value in the relevant service environment configuration, then restart the affected service or stack. Test a version change before applying it to a production deployment. The Docker images are maintained in distribution variants for AMD64 and ARM64, and Ubuntu, Debian, and Alpine; use the package that matches your host architecture and intended Linux distribution. For architecture selection guidance, see Documentation:Deploying MDriven Server and Turnkey with Docker.
Run application processes with reduced privileges
The supplied configuration can run MDriven Server and Turnkey with reduced container privileges by setting both PUID=1000 and PGID=1000. This prevents the application processes from running as root inside the container.
When you change these values, ensure that the selected user and group can read and write every mounted host directory that the service needs. For example, the server must be able to update its mounted administration database and application data. A permissions mismatch can prevent a container from starting or from writing logs and data.
Reset the password for user a
User a is used by MDriven Turnkey to connect to MDriven Server. Reset both sides of that connection together.
- Create
settings/mdriven-server/PwdReset.txtcontaining the new password. - Confirm that
compose.yamlmounts this file to/pwdreset/PwdReset.txtin the MDriven Server container. - Update the password in
settings/mdriven-turnkey/MDrivenServerOverride.xmlto the same value. - Restart the containers.
The MDriven Server updates the password on the next start or restart. If you reset the MDriven Server password but do not update MDrivenServerOverride.xml, Turnkey continues to try the old password. The account can then be locked and Turnkey can enter an error state.
Customize routing with Nginx
Nginx provides the external entry point and routes requests using settings/nginx-proxy.conf. For a domain deployment, update the server_name directive to the domain you will use. The production Nginx guide also describes subdirectory routing when you want one domain to route to multiple services rather than opening separate external ports: Documentation:Deploying MDriven to Production with Nginx.
Keep the internal MDriven Server address used by Turnkey separate from the external URL used by browsers. For example, MDrivenServerOverride.xml can use the internal service address http://server-core:5010, while HardServerUrl.xml identifies the externally reachable Turnkey URL.
Troubleshooting
| Symptom | Check |
|---|---|
| Turnkey does not start or reports a server connection error. | Check docker compose ps and docker compose logs. Verify that MySQL and MDriven Server are healthy, then verify the internal server URL and user a password in MDrivenServerOverride.xml.
|
| A port cannot be published. | Another process is using the host port. Change the host-side port mapping in compose.yaml, then use the changed port in the browser URL.
|
| Database changes or logs remain after containers are recreated. | This is expected for bind-mounted directories and Docker volumes. Review the host data directories before removing data. |
A container cannot write files after adding PUID and PGID.
|
Correct ownership and permissions on the corresponding host-side mounted directories, or use values that can access those directories. |
An ARM-based machine reports an exec format error.
|
Use a deployment package and image architecture that match the host, such as ARM64 for Apple Silicon. |
When to use another Docker guide
- Use Documentation:Running MDriven Locally with Docker for a quick development environment with direct localhost access.
- Use Documentation:Deploying MDriven to Production with Nginx to deploy a public-facing server behind Nginx.
- Use Documentation:Configuring Production Databases PostgreSQL MySQL MSSQL to initialize and connect an included MySQL, PostgreSQL, or MSSQL database.
- Use Documentation:Docker on MacOS- Installing MDriven Server and MDriven Turnkey on Ubuntu Containers for the macOS Ubuntu-container workflow.