CodeProof Usage Guide — Quick Start with Docker / TUI#

Engula CodeProof is a Docker-runnable verification toolkit for running Engula's compatibility, client, performance, stability, migration, platform, and high-availability verification on a local test machine, generating auditable HTML reports.

This official site guide only covers the Docker image + interactive TUI workflow. Source builds, bare-metal installation, command-line arguments, automation integration, and remote-server mode are maintained in the open-source project documentation.

Security note: You only need to mount the host Docker socket into the CodeProof container when you select tests in the TUI that themselves need to launch Docker containers, such as client or platform. This allows the container to call the host Docker daemon, so use it only on controlled test machines.

Table of Contents#

1. What Is CodeProof
2. Before You Run
3. Pull the Docker Image
4. Launch the TUI
5. TUI Interface and Controls
6. Which Tests to Choose
7. View Results and Reports
8. FAQ

1. What Is CodeProof#

CodeProof is Engula's complete verification suite. It organizes the official Redis test set, community client tests, performance benchmarks, and operations scenarios into multiple suites. Every run writes logs and reports to the results/ directory.

2. Before You Run#

The official-site edition runs from a Docker image, so you do not need to install Go, the Redis source, memtier_benchmark, JDK, Node.js, or Python dependencies on the host. The image already bundles the main runtime components:

All you need to prepare is:

If you select client or platform, the test process will additionally pull community or platform images. Hosts in mainland China may wait longer due to slow image download speeds.

3. Pull the Docker Image#

The prebuilt image is published with the latest tag. Docker automatically pulls the image matching the host platform, so there is no need to manually distinguish between x86, Arm, or different operating systems:

1docker pull registry.ap-southeast-1.aliyuncs.com/montplex/engula-code-proof:latest

4. Launch the TUI#

Run from any working directory:

1mkdir -p results
2
3docker run --rm -it \
4  -v "$(pwd)/results:/work/results" \
5  registry.ap-southeast-1.aliyuncs.com/montplex/engula-code-proof:latest \
6  proof tui

This command enters the interactive terminal interface. When the run finishes, reports are written to results/ in the current directory on the host.

If you plan to run client or platform in the TUI, use the startup command below so the CodeProof container can access the host Docker:

1mkdir -p results
2
3docker run --rm -it --net host \
4  -v /var/run/docker.sock:/var/run/docker.sock \
5  -v /tmp:/tmp \
6  -v "$(pwd)/results:/work/results" \
7  registry.ap-southeast-1.aliyuncs.com/montplex/engula-code-proof:latest \
8  proof tui

--net host lets the CodeProof container and the child containers it launches communicate over the network; /var/run/docker.sock lets the CodeProof container call the host Docker daemon; /tmp:/tmp makes temporary files written by client sub-items (such as the sentinel.conf from the 2.4 node-redis sentinel test) visible to the host Docker daemon. When running only compat, perf, stability, migration, or ha, these three options are usually not needed.

5. TUI Interface and Controls#

5.1 Suite and Sub-item Selection#

After launching, you first enter the selection screen:

1engula-code-proof
2
3 Suite                         Sub-item
4 ┌──────────────────────┐      ┌──────────────────────────────┐
5 │▶ #1 compat      [16] │      │  All sub-items in #1 compat  │
6 │  #2 client       [4] │      │  1.1  runtest                │
7 │  #3 ha           [6] │      │  1.2  coverage               │
8 │  #4 migration    [6] │      │  1.3  protocol               │
9 │  #5 perf         [8] │      │  1.4  lua                    │
10 │  #6 platform     [4] │      │  ...                         │
11 │  #7 stability   [10] │      └──────────────────────────────┘
12 │  ★ All suites   [54] │
13 └──────────────────────┘
14
15 engula-bin: ~/.proof/bin/engula-server   results: /work/results
16 ↑↓ move  →  pick suite  ←  back  Enter  run  q  quit

Common controls:

If you stay on a suite and press Enter directly, all of that suite's sub-items run. If you switch to the right column, select a sub-item, and then press Enter, only that sub-item runs.

5.2 Run Dashboard#

After pressing Enter, you enter the run dashboard:

1Running: #1 compat — All sub-items   elapsed 03:42
2
3 Queue (3/16)                     Current: 1.4 lua
4 ✓ 1.1 runtest        02:18 PASS
5 ✓ 1.2 coverage       00:06 PASS    █████████░░░░░░░░░░░░░░
6 ▶ 1.3 protocol       00:11 …
7   1.4 lua                         Live metrics
8   1.5 transaction                   ops/sec   —
9   ...                               vcore%    —
10                                     used_mem  —
11
12 Output
13 [10:30:01] === Compat E2E started ===
14 [10:30:02] Binary: /root/.proof/bin/engula-server
15 [10:30:08] PASS protocol_resp2_inline
16
17 c  cancel batch   l  full log   q  quit

The dashboard has three sections:

During a run you can press l to view the full log and Esc to return to the dashboard; press c to cancel the current run.

5.3 Completion Page#

Once all sub-items finish, you reach the completion page:

1#1 compat — DONE in 05:23
2
3 ✓  15 / 16 PASS
4
5 Press Enter to open /work/results/unknown/20260520T103000/index.html in $BROWSER.
6
7 Output
8 [10:35:00] === Summary ===
9 [10:35:00] Total: 16  Passed: 15  Failed: 1
10
11 Enter open in browser   o  re-open   b  back   q  quit

The container usually has no graphical browser configured, so Enter may not open the page directly. You can open the generated HTML files under results/ on the host instead.

6. Which Tests to Choose#

For your first run, we recommend starting small:

We do not recommend choosing All suites on your first run. A full run takes longer and depends more on machine resources and network environment.

7. View Results and Reports#

After a run finishes, a results/ directory appears in the current directory on the host:

1results/
2├── compat-1.2-coverage-logs/
3│   └── 20260520T103000/
4│       ├── main.log
5│       └── report.html
6└── unknown/
7    └── 20260520T103500/
8        ├── report.json
9        └── index.html

Common files:

Open report.html or index.html directly in a browser to view the results. The reports are static HTML and require no server.

8. FAQ#

The TUI exits immediately on launch, reporting that a TTY is required#

Make sure docker run includes -it. The TUI needs a real terminal and cannot run in a plain pipe or a non-interactive terminal.

A Docker daemon connection failure when running client or platform#

These tests launch additional containers inside the CodeProof container. Use the startup method with the Docker socket:

1docker run --rm -it --net host \
2  -v /var/run/docker.sock:/var/run/docker.sock \
3  -v /tmp:/tmp \
4  -v "$(pwd)/results:/work/results" \
5  registry.ap-southeast-1.aliyuncs.com/montplex/engula-code-proof:latest \
6  proof tui

client or platform waits for a long time#

These tests may need to pull community or platform images from docker.io. On hosts with slow image download speeds in mainland China, the first run waits longer. We recommend starting with suites such as compat, perf, or ha that do not pull extra images.

Reports do not appear in the host directory#

Confirm that you mounted the results directory at launch:

1-v "$(pwd)/results:/work/results"

The TUI's default results directory is /work/results. If this directory is not mounted, reports stay inside the container and are not retained after the container exits.