Skip to main content

​
Overview

This template provides a production‑ready MySQL instance as a Monk runnable. You can:
  • Run it directly to get a managed MySQL container with sensible defaults
  • Inherit it in your own runnable to seamlessly add a relational database to your stack
It exposes MySQL on port 3306, persists data to a host volume, and can optionally create an application user and database on first start.

​
What this template manages

  • MySQL container (mysql image, configurable tag)
  • Network service on port 3306
  • Persistent volumes for data storage
  • Optional initialization of database, user, and passwords

​
Quick start (run directly)

  1. Load templates
monk load MANIFEST
  1. Run MySQL with defaults
monk run mysql/mysql
  1. Customize credentials (recommended via inheritance)
Running directly uses the defaults defined in this template’s variables. Secrets added with monk secrets add will not affect this runnable unless you inherit it and reference those secrets.
  • Preferred: inherit and replace variables with secret("...") as shown below.
  • Alternative: fork/clone and edit the variables in mysql/mysql.yml, then monk load MANIFEST and run.
Once started, connect to localhost:3306 (or the runnable hostname inside Monk networks) using the configured credentials.

​
Configuration

Key variables you can customize in this template: 
variables:
  mysql-image-tag: "latest"           # container image tag
  mysql-root-password: "..."          # ROOT password (env: MYSQL_ROOT_PASSWORD)
  mysql-database: "mydb"              # optional app DB to create (env: MYSQL_DATABASE)
  mysql-user: "myuser"                # optional app user (env: MYSQL_USER)
  mysql-password: "..."               # optional app user password (env: MYSQL_PASSWORD)
Data is persisted under ${monk-volume-path}/mysql on the host. Inherit the MySQL runnable in your application and declare a connection. Example: 
namespace: myapp
db:
  defines: runnable
  inherits: mysql/mysql
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: mysql
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-user:
      value: <- secret("mysql-user")
    database-password:
      value: <- secret("mysql-password")
    database-name:
      value: <- secret("mysql-database")
Then set the secrets once and run your app group: 
monk secrets add -g mysql-user="appuser"
monk secrets add -g mysql-password="STRONG_USER_PASSWORD"
monk secrets add -g mysql-database="appdb"
monk secrets add -g mysql-root-password="STRONG_ROOT_PASSWORD"
monk run myapp/api

​
Ports and connectivity

  • Service: mysql on TCP port 3306
  • From other runnables in the same process group, use connection-hostname("\<connection-name>") to resolve the DB host.

​
Persistence

  • Data path: ${monk-volume-path}/mysql:/var/lib/mysql
  • MySQL stores all databases and tables in this directory
  • High‑availability setup: see the mysql-leader-follower/ template in this repository for a leader-follower replication setup.
  • Load balancing: see the mysql-leader-follower-proxysql/ template for leader-follower replication with ProxySQL.

​
Troubleshooting

  • If you changed mysql-root-password but the container has existing data, authentication may fail. Either reset the data volume or update the password inside the DB to match.
  • Ensure the host volumes are writable by the container user.
  • Check logs:
monk logs -l 500 -f local/mysql/mysql