Setup Guide

This guide describes two methods for setting up a Mazze node and miner: using Docker (recommended) or building from source. For the Zurich development phase, we recommend using Docker.

For reading logs, see our Viewing Mazze Logs guide. For CLI usage, RPC details, and mining operations, see Mazze CLI, RPC Guide, and Mining Guide.

1. Docker Setup

1.1 Compose-based Setup (Recommended)

The repository includes a ready-to-use docker-compose.yml. To run Mazze:

1. Edit run/hydra.toml:

   • Set public_address = "<your-public-ip>" (or leave empty to auto-detect).

   • Set mining_author = "<your-base32-mazze-address>" (or leave empty to disable mining on the node).

   • Ensure log_conf = "/app/config/log.yaml" is present (already set in this repo).

2. Optional: edit run/log.yaml for logging format/level. It is mounted into the container at /app/config/log.yaml and has refresh_rate: 30 seconds.

3. Start the services:

sudo docker compose up -d

To roll out a freshly published image tag, pull and recreate:

# Optional if using non-default tag suffixes:
# export MAZZE_IMAGE_TAG=<tag-suffix>
sudo docker compose pull
sudo docker compose up -d --force-recreate

Verify the deployed image revision:

sudo docker compose exec node cat /app/REVISION
sudo docker compose exec miner cat /app/REVISION

1. View logs:

sudo docker compose logs node | tail -n 200
sudo docker compose logs miner | tail -n 200

1. Retrieve your node ID (after node starts):

sudo docker compose logs node | grep "Self node id:" | tail -n 1

1. Apply config changes:

sudo docker compose up -d --force-recreate

1. Stop services:

sudo docker compose down

Notes:

• Logs are written under ./logs/node and ./logs/miner on the host.

• For persistent chain data on the host, you can add a volume to docker-compose.yml, for example:

  • - ./blockchain_data:/app/blockchain_data

1.2 Manual Docker Run (Optional)

If you prefer docker run, ensure ports are open and set the same mounts as in the compose file. Compose is recommended for simplicity.

2. Building from Source

For developers who want to build from source:

1. Clone the repository:

git clone https://github.com/MazzeLabs/mazze-rust-release.git
cd mazze-rust-release

1. Install dependencies:

sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev cmake hwloc libhwloc-dev libudev-dev
# Install Rust: https://www.rust-lang.org/tools/install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

1. Build the project:

cargo build --release

1. Configure the node:

   • Edit run/hydra.toml

   • Set your VM's IP address

   • Configure your mining author address

2. Start the node and miner:

./start-node.sh
./start-miner.sh

3. Dev Mode (Local)

Use dev mode for local testing (fast blocks, local RPC, shielded testing).

1. (Optional) Re-genesis with shielded keys (wipes dev chain data):

./run/regenesis-shielded.sh --dev

1. Build the dev node binary:

cargo build -p mazze

1. Start the dev node:

./run/start-node-dev.sh

1. If blocks are not advancing, build and start the miner:

cargo build --release -p mazze-miner
./run/start-miner.sh

1. Open the CLI:

./run/mazze-cli.sh

Logs:

• Dev node: run/logs/mazze-node-dev.log

• Miner: run/logs/mazze-miner.log

Stop everything:

./run/stop.sh

Dev data directory:

• run/blockchain_data_dev

Important Notes

Changing log level / config:

• Edit run/hydra.toml (log_level = "info" | "debug" | "warn" | "error") or adjust run/log.yaml.

• Then recreate containers:

sudo docker compose up -d --force-recreate

Container logging options are handled by Docker; compose already mounts run/log.yaml as /app/config/log.yaml with a refresh rate, so updates apply without rebuilding images.

Additional Notes

• Ensure Docker is installed and running on your system

• The automated setup creates a node_id.txt file containing your node's identifier

• Monitor the logs directory for debugging information

• For security reasons, consider configuring additional firewall rules

• Backup your mining author address securely

Soak Testing

For high-BPS soak runs and metrics-based GC/DB tuning, use the dedicated internal soak-testing runbook for your environment.