Installation choices and acceptance checks

This page uses the stable v4.2.5 release as its verified baseline (2026-10-14). Select the platform and purpose, then pin versions. Acceptance requires a working connection, reads/writes, and retained data after restart, not just a running process or container.

Choose an installation path

Purpose and platform

Entry point

Check

Local Linux/macOS evaluation

Docker; Docker Desktop/Linux containers on macOS

Published image CPU platforms, host resources, persistent paths

Native Linux runtime

Binary package

Published x86_64/arm64 asset, libc compatibility, checksum

Kernel changes or a custom build

Linux source or macOS source

Source tag/commit, Go, C/C++ toolchain, build dependencies

Production cluster

Cluster deployment

Operator/CRDs, storage, resources, network, backup, failure drills

v4.2.5 publishes only Linux x86_64 and arm64 ZIPs, with no musl or native macOS binary. Do not construct unpublished download URLs. Source go.mod requires Go 1.26.4; historical 1.22.x examples are unsuitable for building v4.2.5. Check each other version’s own go.mod.

Pin and verify versions

  • Record the MatrixOne release/tag/commit. For containers, record tag, platform, and pulled digest; floating latest or nightly images are not reproducible stable pins.

  • Select assets from the official release and compare SHA-256 with published release metadata. Download completion and integrity checks differ. This review did not download and run both ZIP platforms again.

  • Record the mo_ctl version or installer commit separately from the database version. A configured Go precheck version does not install that Go toolchain.

  • Binary libc requirements and Linux kernel versions differ. Inspect uname -m, getconf GNU_LIBC_VERSION, and the actual error. A kernel below 5.0 does not establish that a musl asset is needed or exists.

A persistent Docker experiment

Run only locally, with the mo-install-lab name and port 16011 unused. The 4 GiB/2 CPU limit is a lightweight test allocation, not a production sizing or minimum-hardware certification. Bind SQL only to localhost and do not publish the debug port.

mkdir -p "$PWD/mo-install-data"
docker pull matrixorigin/matrixone:4.2.7
docker run -d --name mo-install-lab   --publish 127.0.0.1:16011:6001   --mount type=bind,src="$PWD/mo-install-data",dst=/mo-data   --memory 4g --cpus 2 matrixorigin/matrixone:4.2.7
docker inspect mo-install-lab --format '{{json .Mounts}}'
docker logs --tail 100 mo-install-lab
mysql -h 127.0.0.1 -P 16011 -u root -p

The initial local test password is 111. Retry connection/readiness checks rather than assuming that a fixed 20-second delay means readiness. Execute this SQL only in the newly created test instance:

SELECT VERSION();
-- Expected-Value: 1
SELECT 1;
CREATE DATABASE mo_install_lab;
USE mo_install_lab;
CREATE TABLE ledger(id INT PRIMARY KEY, amount INT);
INSERT INTO ledger VALUES(1,42);
-- Expected-Values: 1, 42
SELECT id,amount FROM ledger;

The reported version must match the pin. Exit the client, run docker restart mo-install-lab, reconnect, and query mo_install_lab.ledger; expect (1,42). In this experiment, you can then stop and remove only this container, recreate it with the same image, fixed hostname, and mount, and check the row again. Keep the data directory and do not run two processes against it. Persistence across recreation is not a backup.

Preserve Logservice identity

Docker’s default hostname changes with the container ID; reusing a container name does not preserve its hostname. v4.2.5 Logservice/Raft paths include hostname. Retaining only /mo-data while changing hostname caused shard not bootstrapped; preserving the original hostname recovered startup and the original row. Pin --hostname at creation and retain it together with UUIDs, configuration, and data paths. For existing instances, first record docker inspect --format '{{.Config.Hostname}}' <container_name>. Do not clear directories, edit Raft files, or create a new node identity as a repair. This local recreation workflow is not an unverified cluster-migration procedure.

Data and configuration boundaries

The default entry point is /mo-service -debug-http=:12345 -launch /etc/quickstart/launch.toml; that launch file references service configuration under /etc/launch. Ensure all actual data paths are persistent. Copy custom configuration from the same image version and check its references; see Docker mounts.

Initialize each new instance in an independent empty directory. Retain existing data for same-version restarts/recreation. Backend changes, upgrades, and path migrations require separate verification; do not reinitialize or overwrite the original data. Independent instances must not share one local data directory.

The v4.2.5 Linux/amd64 probe starts, reads/writes, restarts, and recreates without --privileged. Diagnose runtime incompatibilities rather than treating privileged mode as a generic fix. Validate UUIDs, relative paths, and storage backends before reusing old source/configuration examples.

Acceptance and common failures

Check

Pass condition

First evidence to inspect

Version/architecture

Runtime matches the chosen asset

Image platform, CPU, dynamic libraries, startup logs

TCP/account

Authentication succeeds from the intended client

Bind address, port, firewall, password, account

SQL writes

Test writes read back correctly

SQL error, privileges, storage access, memory/disk

Persistence

Restart and test-container recreation retain data

Mounts, working directory, configured data paths

Production preparation

Separate identities/storage, backup and recovery drills established

Production planning

Default credentials are for the initial local evaluation. Before application use, follow password management, create application identities, and configure access and TLS. A running evaluation instance is not evidence of production HA.

Verified on 2026-10-14 with official v4.2.5 Linux/amd64, single CN, 4 GiB/2 CPU: unprivileged startup, SQL reads/writes, restart, and same-mount/same-hostname recreation. Recreation without a stable hostname failed in the probe. Native macOS/arm64, full source builds, and production cluster sizing were not verified.

The source/Docker guides pin and checksum the installer entry. It can still fetch other components: record the installed mo_ctl commit, dependencies, and image digest. An installer checksum does not pin the entire toolchain.