mdcx-docker: packaging MDCX for Linux with a browser or desktop interface

Two images, chosen by how much desktop you need

mdcx-docker runs MDCX in a Docker container, accessible and controllable via a web interface or remote desktop. The repository description is short and the top level shows the shape: gui-base/ and webtop-base/ directories, a build-mdcx/ directory, an install.sh, a prepare-src.sh, scripts/, docs/, a demo/ directory and a .env.sample.

The choice between the two images is the first decision, and the readme states it plainly. The gui image is the simplest version and you only see the application window. The webtop image has a fairly complete desktop environment, but it uses more resources.

That difference is more than cosmetic. The gui image exposes the application over a web port and over VNC, with the display geometry set through environment variables and the VNC password set through another. The webtop image instead exposes a web port and a web HTTPS port and gives you a full desktop with file management and a browser, according to the comparison table.

The table also records the empty cells. The gui image has neither file management nor a browser. If your workflow involves pointing the tool at a media library and then checking what it wrote, the gui image alone will not do it, and the webtop image is not optional but necessary.

Both images are published on Docker Hub under the stainless403 organisation, and the readme notes that the newest image tag is v2-latest. There is also a notice that the upstream source project has moved to Hazard804/mdcx, which is a detail that matters for anyone rebuilding the image from source.

The deploy script asks for a few parameters and does the work

The quick path is a script, and the readme describes it as copying a command into a terminal and answering a few prompts to complete the deployment.

With curl:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/northsea4/mdcx-docker/main/install.sh)"

With wget:

bash -c "$(wget https://raw.githubusercontent.com/northsea4/mdcx-docker/main/install.sh -O -)"

The manual path exists too, and the readme gives a full docker run for the gui image with a warning that only a simple run example is shown and that the deployment documentation should be consulted for the details.

docker run -d --name mdcx \
  -p 5800:5800 `#Web访问端口` \
  -p 5900:5900 \
  -v $(pwd)/data:/config `#容器系统数据` \
  -v $(pwd)/mdcx-config:/mdcx-config `#配置文件目录` \
  -v $(pwd)/mdcx-config/MDCx.config:/app/MDCx.config `#配置文件目录标记文件` \
  -v $(pwd)/logs:/app/Log `#日志目录` \
  -v /volume2:/volume2 `#影片目录` \
  -e TZ=Asia/Shanghai \
  -e DISPLAY_WIDTH=1200 \
  -e DISPLAY_HEIGHT=750 \

The volume list is the part that needs thought. Three host directories are mounted for the container's own data, the configuration directory and the log directory, and the marker file mdcx-config/MDCx.config points at /mdcx-config/config.v2.json so the program knows where its configuration lives. A separate mount, shown as /volume2 in the example, is the media library itself, and that path has to match wherever your library actually is.

The marker file is written by a shell command before the container starts, and the note beside it says the configuration file does not need to be created by hand because the program creates it.

That arrangement is the reason the config directory is mounted twice. The directory mount lets the program write its configuration, and the single file mount exposes the marker file at the exact path inside the container where the program expects it. It is a small piece of plumbing that would otherwise be very confusing to work out from the image alone.

The environment file pins the upstream source and version

The .env.sample in the repository root is the build configuration, and it is short.

# 时区
TZ=Asia/Shanghai
# 语言
LANG=zh_CN.UTF-8

APP_NAME=MDCx
APP_VERSION=20230206

# 上游源码仓库（owner/repo），用于构建时下载源码
MDCX_SRC_REPO=sqzw-x/mdcx
# 上游release tag；留空时按仓库自动选择（sqzw-x/mdcx -> daily_release，其他仓库 -> latest）
MDCX_SRC_TAG=latest

The two settings that matter are MDCX_SRC_REPO and MDCX_SRC_TAG. The first names the upstream repository that the source is downloaded from at build time, and the second pins which release tag to take. The comment on the tag line explains the default behaviour: when the tag is left empty the choice is made from the repository name, so the sqzw-x/mdcx repository resolves to daily_release while any other repository resolves to latest.

That is a sensible default for a project that tracks a moving upstream, and it is also the sharpest edge in the whole design. The application source is not vendored into this repository. It is fetched during the build, which means the content of a given image depends on a tag in someone else's repository at build time, and the readme's own notice that the upstream has moved to Hazard804/mdcx is a signal that this reference has already shifted once.

For a deployment where reproducibility matters, the practical consequence is to set MDCX_SRC_TAG explicitly rather than relying on the automatic resolution, and to rebuild deliberately rather than pulling a floating tag.

There is also a .env.versions file alongside .env.sample, which by its name holds the version pins for the build, and the APP_VERSION value in the sample is dated 20230206, which is the upstream application's own version scheme rather than this project's.

Default passwords are documented, and the readme tells you to change them

The section on public internet access is short and to the point. If you need access from the public internet, set the access password yourself and do not use the default password.

The table records what the defaults are for each image. The gui image has an empty default, and the way to set one is the VNC_PASSWORD environment variable. The webtop image ships with abc for both user and password, and the readme gives two ways to change it: docker exec -it with the container name and passwd abc, or entering the desktop and running the same command in a terminal.

The AUTO_LOGIN environment variable appears in the webtop example with the value false, and the comment beside it says it controls whether web access uses the default password and logs in automatically.

So the two images differ in how the default credential works. In the gui image the VNC password is unset, so there is nothing to guess but also no password set until you set one. In the webtop image there is a known default password, and the container is likely reachable on a network, so a deployment that exposes port 3000 or 3001 to the internet without changing it is effectively open.

The readme puts the responsibility on the user, which is defensible for a self hosted tool, but it means the first thing to do after a deployment is set a password. The two ports published by the webtop image are the web interface and a web HTTPS interface, and the readme shows both being accessed from the browser.

One more detail about the media mount is worth noticing. The example mounts /volume2, which is a Synology style path rather than a generic one, suggesting the author's own deployment is a NAS. Nothing in the container requires that specific path, but it tells you the kind of environment the images are shaped around.

The licensing section adds terms on top of GPLv3

The licensing section of this project is unusual enough that it deserves reading carefully rather than skimming.

The repository licence field says GPL-3.0 and the LICENSE.md file is linked. But the licensing section states that the plugin project is distributed under GPLv3 and that, by using the project, the user additionally accepts a set of terms. The list restricts the project to learning and technical exchange, asks users not to promote the project on public social platforms, requires compliance with local laws, puts the legal and usage consequences on the user, and forbids any commercial use of the software.

There is also a separate disclaimer section, which the readme says takes effect when you read or download the source or binary. It says the project and its results are for technical, academic exchange and Docker testing only, that the contributors wrote it to learn about Docker and Python application packaging on Linux, that users should understand and follow local laws, and that if using the project violates local law, do not use it.

Adding a non-commercial restriction on top of GPLv3 does not produce a standard open source licence. The GPL grants the right to use the software for any purpose, so a restriction layered on top means the package as distributed is not what the GPL alone would give you. For an organisation considering this for anything beyond a personal NAS, that is the thing to raise, and the licence file and the readme section are the documents to read rather than the badge.

This is not legal advice. The practical point is that the licence terms and the commercial-use prohibition are stated clearly enough that nobody should be surprised, which is more than many projects manage, and anyone using this beyond a home lab should decide deliberately rather than by accident.

Where mdcx-docker is the wrong tool

Three limits, and the licensing one is the most consequential.

The non-commercial restriction rules it out for any business deployment, which is a hard stop rather than a matter of degree. Combined with the instruction not to promote the project on public social platforms, the project is positioned as a personal learning artefact, and that is a coherent choice for something whose stated purpose is learning Docker and Python packaging on Linux.

The second limit is that you are not running MDCX, you are running someone else's build of MDCX. The application source is downloaded at build time from an upstream repository whose location has already changed once, according to the readme notice. If the upstream moves again, the build breaks, and if the upstream tag resolves differently than expected, the image contents differ from what you reviewed. The tag pinning in .env.versions and the explicit MDCX_SRC_TAG setting are the tools for managing that, and the README's advice to consult the per-image deployment documentation rather than relying on the example is well placed.

The third is the choice between the two images. The gui image is lighter but gives you an application window with no file manager and no browser, which means the Webtop image's higher resource cost is the price of being able to administer the tool. A user who wants the lightest possible container has to accept that they will interact with the application and nothing else.

The alternative approaches differ in what you take on. Running MDCX natively on the host, which the project's own goals mention, gives you the application without the container overhead but requires a Python environment and a display for the GUI. Building your own image from the upstream source gives you full control over what goes in and removes the floating tag problem, at the cost of owning the build. And a headless deployment with no graphical interface at all, driving the tool through its configuration files rather than its window, removes the need for either image if your workflow allows it.

Editorial conclusion

mdcx-docker suits a NAS or home server user who wants MDCX running with a graphical interface without installing a desktop on the host, and the Webtop image is the practical choice when you need to move files around as well as run the tool. It does not suit a deployment that needs a commercial licence, because the licensing section adds a term forbidding commercial use on top of GPLv3, and it does not suit anyone who wants to modify the upstream application itself, since the source is downloaded at build time from another repository. Before deploying, set the access password rather than shipping the defaults, and read the installation instructions in the gui-base and webtop-base directories, because the readme gives only a starting example.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. northsea4/mdcx-docker on GitHub
4. README
5. Releases