DEV Community: Yunsoft

Run YunCMS with Docker Compose: MySQL 8.4 Included

Yunsoft — Sat, 12 Sep 2026 15:22:45 +0000

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:

Stop the service and create a verified backup with the current image.
Change YUNCMS_IMAGE in .env to the target version.
Pull the new image and run bootstrap once.
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

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.

Introducing YunCMS 0.1.14: a focused, programmable MySQL CMS/backend

Yunsoft — Fri, 04 Sep 2026 14:48:10 +0000

Disclosure: YunCMS is developed and maintained by Yunsoft Software. This post introduces our own open-source project. Version 0.1.14 belongs to the pre-stable 0.1.x series, so interfaces and behavior may change between releases.

Many projects need the same backend building blocks: configurable collections and fields, relational data, a usable administration interface, permissions, file handling, and a clean way to extend the system. We built YunCMS to provide those pieces in a small reusable platform, without trying to reproduce every feature of a much larger CMS.

YunCMS is an independent implementation inspired by the developer ergonomics of tools such as Directus. It is not a Directus fork and does not aim for compatibility for its own sake. The goal is a focused core that grows only when a real project needs a capability.

What is included today?

The current release includes:

dynamic MySQL collections, fields, and relations;
a schema-driven React Studio for content, files, data models, users, roles, and settings;
a documented REST API with filtering, sorting, pagination, field selection, and relation expansion;
explicit role-based access control with action, field, row-filter, and validation boundaries;
local and S3-compatible file storage;
trusted server extensions with endpoint and hook helpers;
an optional Studio AI assistant that works through the current user's permissions; and
an optional MCP endpoint that uses the same services and accountability model.

The MCP endpoint is disabled, authenticated, and read-only by default. Enabling a feature never turns a caller into an administrator: normal YunCMS permissions remain authoritative.

A deliberately straightforward stack

YunCMS V1 uses Node.js 24 LTS, JavaScript/ESM, Express 5, and MySQL through mysql2/promise. Studio uses React 19.2 and Vite 8. There is no ORM, GraphQL layer, or second database driver in the current contract.

HTTP routes stay thin while business behavior lives in services such as ItemsService, CollectionsService, FieldsService, RelationsService, UsersService, and FilesService. Extensions and internal code call these services directly instead of making local HTTP requests back into YunCMS.

Try it locally

You need Node.js 24 LTS, npm 11 or newer, and a MySQL 8-compatible server. Then run:

npx --yes @yunsoft/yuncms init
npx --yes @yunsoft/yuncms start

The same listener serves Studio and the REST API. The 15-minute getting-started guide covers database setup, the first administrator, a sample collection, permissions, and a first API request.

Current status and scope

YunCMS is open source under the MIT License and is actively developed. The current 0.1.x line should be treated as pre-stable. It is suitable for evaluation and feedback, but adopters should test against the exact release they use and review the documented operational checks before relying on it in production.

The current scope is intentionally specific: MySQL only for V1, REST only, and self-hosted deployment. YunCMS does not currently claim Docker support, a hosted SaaS edition, GraphQL, or general production stability.

I Started Testing Free SEO Tools on My Site, Early Results and What I’m Expecting

Yunsoft — Fri, 10 Apr 2026 16:57:58 +0000

I’ve been working on growing traffic for my software company website, and like most people, I kept hearing the same advice:

"Create free tools. They attract organic traffic."

So I decided to test it myself.

Instead of writing more blog posts or chasing backlinks all day, I launched a simple tools section on my website:
👉 https://yunsoft.com/tools

Nothing fancy. Just useful tools that people might actually search for and use.

Why Tools?

The logic is pretty simple:

People actively search for tools
Tools get bookmarked and reused
They have higher engagement than blog content
They can naturally attract backlinks over time

Compared to standard content, tools feel more “useful” and less like marketing.

Current Situation (Week 1)

Right now, the traffic is very small.

Around 10 daily clicks
Almost no backlinks yet
Very limited indexing

But honestly, that’s expected.

This is not a short-term strategy.

What I’m Testing

I’m focusing on a few things:

Indexing speed of tool pages
Whether tools rank faster than blog posts
If users actually stay and interact
Organic impressions growth over time

Also, I’m internally linking these tools from other pages to boost visibility.

Why I Think This Might Work

From what I’ve seen across multiple SEO case studies:

Tool pages often rank easier for long-tail keywords
They can scale better than blog content
Once they start ranking, they bring consistent traffic

And most importantly:
They don’t feel like content spam.

Plan Going Forward

I’m not expecting immediate results.

This is more like a 30–60 day experiment.

If things go well, I’ll:

Add more tools
Improve UX
Push them through communities (Reddit, forums, etc.)

Final Thoughts

Right now, it’s too early to say anything definitive.

But I’ll keep this experiment running and share updates after a month.

If you're also struggling with traffic, this might be worth testing instead of writing another 50 blog posts.

What is Clawwork (hkuds)? The Browser Agent That Finally Understands the Web

Yunsoft — Mon, 09 Mar 2026 10:14:19 +0000

I hate Selenium. There, I said it.

I spent last Saturday night debugging a scraper that had been running perfectly for six months. The target website didn't even do a major redesign. They just changed a single CSS class name on their login button. One tiny change, and my entire script exploded.

If you write automation scripts, you know this feeling. It is the absolute worst part of the job. We have been building bots that are "blind" for years. We tell them to click coordinate X or find ID Y. They do exactly what they are told, which is usually the problem.

That is why I stopped scrolling when I saw a repository called hkuds/clawwork popping up all over my GitHub feed recently. It promised to fix the one thing that makes browser automation a nightmare: fragility.

I decided to dig into it because I kept seeing people search for "what is Clawwork" or specifically looking for the hkuds version. I pulled the repo, burned through a bunch of API credits, and gave it a spin.

Here is the honest breakdown of what this thing actually is and if it is worth your time.

Why We Are All Tired of "Dumb" Bots

The problem with tools like Puppeteer or Playwright isn't that they are bad tools. They are amazing. The problem is that they rely on the DOM.

You are basically playing a game of "Where's Waldo" with HTML tags. You write a script that says "Find the blue button." But tomorrow, the button might be green. Or it might be inside a strictly positioned div that blocks the click.

Traditional bots crash when things change. They have no intuition.

Clawwork is different. It is part of this new wave of "Agentic AI." Instead of looking at the code, it uses Large Language Models and computer vision to look at the actual pixels. It sees the page like you do.

So, What is Clawwork (hkuds)?

Okay, let's get technical for a second. Clawwork is an open-source browser automation agent. There are a bunch of versions floating around, but the hkuds/clawwork repo is the one everyone is talking about right now because it is clean and it actually works.

Think of it as a wrapper around Playwright. But instead of you writing the steps, you hook it up to a brain like GPT-4o or Claude 3.5 Sonnet.

You don't write: await page.click('#submit-btn');

You write: "Go to Amazon, search for a mechanical keyboard under $100, and add the one with the best reviews to the cart."

The agent takes a screenshot. It sends that image to the AI. The AI looks at it and says, "Okay, the search bar is at the top. I need to click there."

It is weirdly human. It calculates coordinates based on what it sees, not just what is in the code.

Why the "hkuds" Repo Specifically?

I was wondering this too. Why this specific fork?

It comes down to control. Most "AI Agent" tools right now are expensive SaaS products. You have to pay a monthly fee and you don't really know what they are doing with your data.

The hkuds version is open source. You can clone it. You can run it on your own laptop. You bring your own API keys. It handles the messy stuff like managing the browser context and the vision processing so you don't have to build that from scratch.

I Tried to Break It (And It Kinda Surprised Me)

I didn't want to give it an easy test. I sent it to a travel booking site. You know the kind. Popups everywhere, dynamic date pickers, weird overlays.

My prompt was simple: "Find a non-stop flight from New York to London for next Tuesday."

I watched the browser open on my second monitor.

It sat there for a few seconds. That is the "thinking" phase. Then the mouse moved. It didn't jump instantly like a robot usually does. It slid over to the "One Way" toggle. Clicked it. Then it opened the calendar.,

Clawwork Hkuds Vision Grid Terminal Logs Example

This is the part where my Selenium scripts usually die. The calendar date for "next Tuesday" changes every week. You can't hard code it easily.

Clawwork looked at the calendar, figured out what today's date was, calculated next Tuesday, and clicked the right number. It was slow, sure. But it worked. It felt a little ghostly seeing the mouse move by itself based on visual cues.

Under the Hood

If you are a dev, you probably want to know how the sausage is made. The architecture in the hkuds repo is actually pretty smart.

It has three main layers:

Clawwork architecture diagram driver perception reasoning layer AI workflow

The Driver (The Hands) This is standard Playwright. It handles the actual clicking, typing, and scrolling. Nothing new here.
The Perception (The Eyes) This is the cool part. It captures the viewport state. Early agents tried to turn the HTML into text, which was messy. This version leans on Vision. It overlays a grid or numeric tags on interactive elements. So the AI sees a button labeled "42" and just tells the driver "Click 42."
The Brain ( The Wallet) This is where your API key comes in. The agent sends the state to OpenAI or Anthropic. The model decides what to do next. "I see a popup, I should close it."

The Real Talk: Pros and Cons

I am not going to sell you a dream here. This tech is new and it has some rough edges.

The Good Stuff It heals itself. If the website moves the login button to the left, Clawwork sees it and clicks it anyway. You don't have to update your code. That is huge. It handles logic that is hard to code, like "Choose the best looking option."

The Pain Points It is not cheap. Every single step is an API call with image data. If you are scraping ten thousand pages, you are going to burn through your wallet fast. It is also slow. The "Observe -> Think -> Act" loop takes a few seconds. You are not going to use this for high-frequency trading.

When Should You Use It?

Don't use this to scrape Wikipedia. That is overkill.

Use it for the stuff that makes you want to pull your hair out. Use it for QA testing where you need to simulate a confused user. Use it for complex workflows that involve multi-step forms. Use it for legacy internal tools that have terrible code structures.

Getting It Running

I am not going to lie, the setup can be a bit tricky if you haven't messed with Node or Docker environments before. You need to get your environment variables right or the browser will just close immediately.

I spent a few hours banging my head against the wall getting the Docker container to play nice with my local network.

Clawwork installation guide step by step tutorial setup success terminal

Since I already went through that pain, I wrote a specific guide just for the installation.

Click here to read my full ClawWork Installation Guide

I break down exactly how to configure the .env file and how to avoid the common errors I ran into.

The web is changing. We are moving away from rigid scripts to autonomous agents. hkuds/clawwork is one of the first tools that actually makes this accessible to normal developers. It is messy, it is fun, and honestly, it is probably the future.

Check out the repo, but definitely grab my guide first so you don't waste your evening debugging config files like I did.

Stop Treating Clawdbot (OpenClaw) Like a Plug-and-Play Solution

Yunsoft — Wed, 25 Feb 2026 09:09:17 +0000

Clawdbot (now OpenClaw) isn’t exactly the type of tool that tip-toes into the room. It tends to crash the party all at once. One day it’s a mention in a random thread, the next it’s a blog post link, and suddenly there’s a 30-second “how-to” video making it look like child’s play.

Before anyone actually understands the mechanics, it feels like everyone is already using it. And that’s the problem: expectations usually outpace reality.

From what I’ve seen, Clawdbot sits in a tricky middle ground. It’s powerful enough to be useful, but limited enough to frustrate anyone expecting it to solve problems it was never built for.

What’s Actually Happening Under the Hood?
Strip away the marketing, and at its core, Clawdbot is a scraping bot. It hits a page, reads the structure, and grabs data based on the rules you set. Simple enough on paper, right? In practice, it’s rarely that clean.

The thing is, Clawdbot doesn’t “understand” intent. It doesn’t know which data point is the gold mine and which is just noise. It just follows a pattern. If that pattern shifts even slightly, your output breaks. Period.

A Finished Product or Just a Gear in the Machine?
Most people get disappointed because they treat Clawdbot like a “plug-and-play” solution. Clawdbot shines when it’s treated as one part of a larger ecosystem, not the whole show. It needs to be wrapped in:

Validation layers (is the data actually correct?)

Storage logic (where does it go?)

Monitoring (is the site down or did our logic break?)

Where Expectations Usually Break Down
Scraping projects usually fail for the same boring reasons:

The Stability Myth: Websites are living things. There is no such thing as “set it and forget it.”

The “Garbage In, Garbage Out” Rule: No tool can magically fix a broken data structure without extra logic.

The Scaling Wall: Once you move past small tests, rate limits and error handling start to matter. A lot.

The Bottom Line
Clawdbot starts to make sense the moment you stop looking for a shortcut and start looking at it as infrastructure. If you approach it with a plan and a bit of skepticism, it’s a massive leverage point.

Let's Connect
I share regular notes on automation, data systems, and the reality of implementation here:

X (Twitter): Yunsoft
LinkedIn: Yunsoft