Run YunCMS with Docker Compose: MySQL 8.4 Included

Disclosure: YunCMS is developed and maintained by Yunsoft Software. This guide covers our own open-source project. It was verified against yunsoftofficial/yuncms:0.1.22 on September 12, 2026. The YunCMS 0.1.x line is pre-stable, so interfaces and behavior may change between releases.

You may not want to prepare the right Node.js version, npm and a separate MySQL server just to evaluate a CMS/backend. The YunCMS Docker Compose path shortens that first step: a constrained YunCMS container, MySQL 8.4 and persistent volumes arrive in one maintained project definition.

This guide takes the official Compose files from an empty directory to a working YunCMS Studio. It also explains which data persists, why production deployments should pin an image version and how to approach updates safely.

Docker and npm distributions run the same YunCMS Studio and REST API.

What does the Compose stack include?

The official stack creates two services and two persistent volumes:

• MySQL 8.4: stores YunCMS metadata and project collections.
• YunCMS: runs the CLI, REST API and built React Studio from the same image.
• mysql-data: keeps MySQL tables independent of container lifetime.
• yuncms-data: stores the project environment, local Files, extensions, AI settings key and local backups.

The YunCMS image also includes the MySQL client tools required by the backup and restore commands. It supports linux/amd64 and linux/arm64, so the same workflow can run on common servers and ARM-based development machines.

1. Check the requirements

For local use, you only need Docker Engine with the Compose plugin or Docker Desktop. An internet-facing production deployment additionally needs persistent storage suitable for its database and Files plus a reverse proxy that terminates TLS.

docker --version
docker compose version

The Docker path does not require a separate Node.js or npm installation on the host; the required runtime is already inside the YunCMS image.

2. Download the official Compose files

Create an empty deployment directory and download the maintained configuration:

mkdir my-yuncms
cd my-yuncms
curl -fsSLO https://raw.githubusercontent.com/Yunsoft-Software/yuncms/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/Yunsoft-Software/yuncms/main/docker.env.example -o .env

Open .env and replace these two example values with different strong passwords:

YUNCMS_DB_PASSWORD=replace-with-a-strong-database-password
YUNCMS_DB_ROOT_PASSWORD=replace-with-a-different-strong-root-password

Never commit the .env file. It contains database passwords and deployment configuration and should be readable only by people and processes that need it.

For production, pin YUNCMS_IMAGE to a specific version you have verified:

YUNCMS_IMAGE=yunsoftofficial/yuncms:0.1.22

latest is convenient for evaluation, but it is not an unattended production update policy.

3. Start MySQL first

docker compose up -d mysql
docker compose ps

The stack does not consider YunCMS ready before MySQL becomes healthy. Wait for the MySQL service to report healthy in docker compose ps.

The official configuration does not publish the MySQL port to the host. Keep that boundary in an internet-facing deployment; YunCMS only needs database access over the private Compose network.

4. Initialize YunCMS once

Run the interactive init command for the first schema preparation and Administrator account:

docker compose run --rm yuncms init

Use these Compose values for the database prompts:

Prompt	Value
MySQL host	mysql
MySQL port	3306
MySQL database	yuncms
MySQL user	yuncms
MySQL password	the YUNCMS_DB_PASSWORD value from .env
Use MySQL TLS	false for the private Compose network

Then enter the first Administrator email and a strong password. init applies the required migrations and prepares the project environment inside the yuncms-data volume.

5. Start YunCMS and verify readiness

docker compose up -d yuncms
docker compose ps
curl http://localhost:3008/health
curl http://localhost:3008/ready

Open http://localhost:3008 in a browser. Studio and the REST API share the same port. /health confirms that the HTTP process is alive; /ready confirms that the application can reach MySQL and the required shared state and is ready to accept work.

The image health check uses /ready, so Compose marks the YunCMS container healthy only when the real dependencies are available.

6. Removing a container is not the same as removing data

Stopping containers or running a normal docker compose down does not remove named volumes. MySQL and the YunCMS project state remain available when the stack starts again.

Be careful: docker compose down -v removes both volumes. That can irreversibly destroy the database, uploaded local Files, extensions and local YunCMS state. Use it only when you intentionally want to discard the complete installation.

If you use S3-compatible storage, its objects are not inside either Compose volume. Configure provider-side versioning, snapshots or backups separately.

7. Create a backup before real content arrives

Stop the normal YunCMS service before maintenance:

docker compose stop yuncms
docker compose run --rm yuncms backup

Copy the completed backup out of the volume and store it independently:

docker compose cp yuncms:/data/.yuncms/backups ./backups

A single backup inside the same host or volume is not independent protection against host or volume loss. Test the MySQL and storage recovery plan separately for production.

8. Update a container installation safely

Container deployments update by replacing the pinned image, not by running yuncms update inside an immutable image:

1. Stop the service and create a verified backup with the current image.
2. Change YUNCMS_IMAGE in .env to the target version.
3. Pull the new image and run bootstrap once.
4. Start the service and verify /ready, Administrator login, representative permissions and Files.

docker compose stop yuncms
docker compose run --rm yuncms backup
# Pin YUNCMS_IMAGE in .env to the target version
docker compose pull yuncms
docker compose run --rm yuncms bootstrap
docker compose up -d yuncms
curl http://localhost:3008/ready

Remember that YunCMS is still in the 0.1.x line. Read the target release notes, test in staging and do not update production without a verified recovery path.

9. Before exposing the installation to the internet

• Set YUNCMS_PUBLIC_URL to the real HTTPS origin.
• Match YUNCMS_TRUST_PROXY_HOPS to the actual reverse-proxy chain.
• Do not publish the MySQL port.
• Replace every example Administrator and database password.
• Design the Public role from a deny-by-default starting point.
• Test Files, backup/restore, permissions and sessions with representative users.

The official Compose stack runs the YunCMS container read-only, drops Linux capabilities and uses no-new-privileges. These are useful starting boundaries; they do not replace application permissions, proxy/TLS, secret management or monitoring.

Where do AI and MCP fit?

The optional AI workspace inside Studio can connect to an OpenAI-compatible provider. Schema and content operations run under the signed-in user’s current role, field and row permissions; AI does not receive an Administrator bypass.

The optional MCP endpoint for external AI tools uses the same service and RBAC layer. MCP starts disabled, authenticated and read-only by default. This gives an AI tool a defined backend contract instead of asking it to recreate authentication, CRUD and permission code for every project.

Docker or npm?

Docker Compose is the shortest path when you want a repeatable self-hosted stack that includes MySQL. If you need YunCMS inside an existing Node.js deployment model, want to manage it in package.json or prefer the npm-based managed update flow, follow the npm getting-started guide.

Links

• YunCMS on Docker Hub
• Official Docker guide
• YunCMS source code and issue tracker
• Production readiness checklist

Try the stack with a real project and report any blocked step as a reproducible GitHub issue. We will continue shaping YunCMS around concrete use cases rather than an abstract feature checklist.