Run YunCMS with Docker Compose: MySQL 8.4 Included

Run YunCMS with Docker Compose: MySQL 8.4 Included

Disclosure

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.

What You Need to Know

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.

The Compose Stack

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.

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.

Download the Official Compose Files

1. 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
   

2. 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.

Starting YunCMS

1. 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.

2. Initialize YunCMS once:

   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.

3. 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.

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.

Creating a Backup

1. Stop the normal YunCMS service before maintenance:

   docker compose stop yuncms
   

2. Create a backup:

   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
   

Updating a Container Installation Safely

1. Stop the service and create a verified backup with the current image:

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

2. Change YUNCMS_IMAGE in .env to the target version.
3. Pull the new image and run bootstrap once:

   docker compose pull yuncms
   docker compose run --rm yuncms bootstrap
   

4. Start the service and verify /ready, Administrator login, representative permissions and Files:

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

Before Exposing the Installation to the Internet

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