Running Mach5 One from a Docker Image

This is a guide to run Mach5 One Docker image (as a .tar file or a registry reference) locally.

Throughout this doc, replace <MACH5_ONE_IMAGE> with the image reference you were given (e.g. mach5-one:latest, or a full registry path like registry.example.com/mach5-one:1.2.3).

Prerequisites

• Docker installed and running (docker version should succeed).
• The Mach5 One image, either:
  • loaded from a file: docker load -i mach5-one-image.tar, or
  • pulled from a registry you have access to: docker pull <MACH5_ONE_IMAGE>

Verify the image is present:

docker images | grep mach5-one

1. Choose a data directory

Mach5 One persists its data (indices, config) to a directory on the host, mounted into the container. Pick a location and create it:

mkdir -p ~/.mach5-one

Data written here survives container restarts and re-creation.

2. Run the container

docker run --name mach5-one --rm -d \
  -v ~/.mach5-one:/mach5-one \
  -p 8080:8080 \
  -p 5432:5432 \
  <MACH5_ONE_IMAGE>

Flags explained:

• --name mach5-one — a fixed name so you can reference it in later commands.
• --rm — removes the container automatically when it stops (data still persists on the host via the volume mount).
• -d — runs detached, in the background.
• -v ~/.mach5-one:/mach5-one — mounts your host data directory into the container’s expected data path.
• -p 8080:8080 — HTTP API, Web UI, and MCP endpoint.
• -p 5432:5432 — Postgres wire protocol gateway.

Mach5 One only listens on two ports inside the container: 8080 (all HTTP traffic) and 5432 (Postgres wire protocol). You don’t need to publish any other ports.

If your image requires running as a specific host user (permission errors on the mounted volume are a sign of this), add -u $(id -u):$(id -g) to the docker run command above.

Password secrets

When running in Docker, Mach5 One uses local Mach5 One secrets for passwords. These are not Kubernetes secrets.

Mach5 One resolves password secrets in this order:

1. Inline TOML secrets.
2. JSON files under <data_dir>/data/secrets/.

With the volume mount shown above:

-v ~/.mach5-one:/mach5-one

the host directory ~/.mach5-one is the container’s data directory. To add a file-backed password secret, create the secrets directory on the host:

mkdir -p ~/.mach5-one/data/secrets

Then create ~/.mach5-one/data/secrets/creds.json with the password value:

{
  "password": "PASSWORD"
}

For this file, the credential secret name is creds and the password key is password. Use those values when configuring credentials for Mach5 entities.

3. Verify it started

docker logs mach5-one 2>&1 | grep "HTTP server listening"
# Expected: HTTP server listening addr=0.0.0.0:8080

Or check the version endpoint:

curl http://localhost:8080/version.txt

If the container isn’t running, check docker ps -a and docker logs mach5-one for errors.

4. Access it

• Web UI: http://localhost:8080/
  • This is a client-side-routed single-page app. Always start at / and navigate by clicking through the UI — loading a deep link directly (e.g. http://localhost:8080/dashboards) will 404.
• MCP endpoint (for AI agents/clients): http://localhost:8080/mcp
• REST APIs: http://localhost:8080/apis
• OpenSearch-compatible API: http://localhost:8080/warehouse/default/default/opensearch
  • Always use this full warehouse-prefixed path — bare paths like /_bulk or /_search directly on port 8080 are not recognized and return 405 Method Not Allowed.
• KQL/MDX API: http://localhost:8080/warehouse/default/default/kql
• Postgres wire protocol: localhost:5432, e.g.

  postgresql://localhost:5432/default?options=-cwarehouse=default
  

  The ?options=-cwarehouse=default part is required — without it, SQL queries fail with “missing warehouse”.

5. Stopping and restarting

docker stop mach5-one

Because the container was started with --rm, stopping it also removes it. Your data in ~/.mach5-one is untouched. To start again with the same data:

docker run --name mach5-one --rm -d \
  -v ~/.mach5-one:/mach5-one \
  -p 8080:8080 \
  -p 5432:5432 \
  <MACH5_ONE_IMAGE>

Container name already in use

If you see:

Conflict. The container name "/mach5-one" is already in use

An old container is still around. Remove it first:

docker stop mach5-one
docker rm -f mach5-one

Resetting all data

To wipe all indexed data and start fresh:

docker rm -f mach5-one
rm -rf ~/.mach5-one
mkdir -p ~/.mach5-one

Then re-run the docker run command from step 2.

6. Configuration

Mach5 One reads a config file at ~/.mach5-one/mach5-one.toml (i.e. /mach5-one/mach5-one.toml inside the container) if present. Create it before starting the container to customize settings, for example:

[server]
http_port = 8080
pg_port = 5432
max_request_body_size = 16777216  # 16 MB — raise this if large bulk ingests get 413 errors

By default, HTTP request bodies over ~2 MB are rejected with 413 Payload Too Large. If you’re ingesting large batches of documents, set max_request_body_size as shown above.

Troubleshooting

For issue reports, collect: the image tag/version, your docker run command (with any secrets removed), docker logs mach5-one output, and the exact error message.