Z3 runs Zebra (full node), Zaino (indexer), and Zallet (wallet) together with Docker Compose, on mainnet, testnet, or a local regtest network.

Two kinds of people use Z3, and this README is split for them:

• Operators run the stack as infrastructure. Start at Choose your network; everything you need to run Z3 is in that half.
• Developers, testers, and researchers build or test against Z3, often running several networks at once. Start at Building and testing against Z3.

• Docker Engine with Docker Compose (v2.24.4+)
• rage for generating Zallet encryption keys (brew install rage on macOS, or download a release)
• Git, to clone this repository
• openssl, only for regtest (it hashes the regtest wallet RPC password); pre-installed on macOS and most Linux distros

Z3 runs as one of three independent Compose projects. Pick by what you are doing:

All three can run at once on one host; each gets its own ports and volumes. New to Z3? Start with regtest to watch the whole stack come up in seconds, then move to mainnet.

Each network has a one-time setup step and a start step.

Mainnet (production). Zebra must sync the whole chain before Zaino and Zallet can serve clients, so the boot is two-phase: start Zebra, wait for the sync, then start the rest.

git clone https://github.com/ZcashFoundation/z3 && cd z3

# 1. One-time setup: creates local config files and the Zallet wallet identity.
./scripts/setup-network.sh mainnet

# 2. Start Zebra and wait for it to sync. The poller exits when Zebra is ready.
docker compose --env-file .env.mainnet up -d zebra
./scripts/check-zebra-readiness.sh

# 3. Start Zaino + Zallet once Zebra is synced.
docker compose --env-file .env.mainnet up -d

Images are pulled automatically; no build step or source checkout is needed.

Your edits to the per-network config under config/<network>/ stay local and survive git pull.

Testnet (public test network). The same two-phase flow; pass the testnet health port to the poller:

./scripts/setup-network.sh testnet
docker compose --env-file .env.testnet up -d zebra
./scripts/check-zebra-readiness.sh 18080
docker compose --env-file .env.testnet up -d

Regtest (local practice and development). Regtest mines blocks on demand with no peers, so it boots in seconds. One command does setup, starts Zebra, and mines the activation blocks:

./scripts/regtest-init.sh
docker compose --env-file .env.regtest up -d

After the first run, the up -d line alone is enough. See docs/regtest.md for test commands and the full workflow.

Each network keeps its chain state in a Docker named volume called z3-<network>-chain, which lands under Docker's data root (on Linux, /var/lib/docker/volumes/). Mainnet is roughly 300 GB; size the disk before you start.

• Find the path: docker volume inspect z3-mainnet-chain -f '{{.Mountpoint}}'
• Put it on another disk: set Z3_CHAIN_DATA_PATH=/mnt/ssd/zebra-state and run ./scripts/fix-permissions.sh zebra /mnt/ssd/zebra-state before the first start.
• Back up the wallet: the only data worth backing up is the wallet, and it needs two pieces kept together: the z3-<network>-zallet volume and config/<network>/zallet_identity.txt (the age key the wallet database is encrypted with). One without the other cannot be restored. Chain state is re-syncable and the cookie is regenerated, so neither needs backup.
• Stop vs wipe: docker compose --env-file .env.<network> down stops the stack and keeps every volume; adding -v (down -v) deletes them, which means a full re-sync.

The volume table and bind-mount details are in the Reference section.

Z3 ships production-shaped defaults, but a few choices are yours to make before running mainnet for real:

• Pick where the chain lives. The default named volume sits under /var/lib/docker (~300 GB on mainnet). To use a dedicated disk, set Z3_CHAIN_DATA_PATH and run fix-permissions.sh before the first start (see Where your data lives).
• Plan the wallet backup. Keep the z3-<network>-zallet volume and config/<network>/zallet_identity.txt together; nothing else needs backup.
• Set a log rotation policy. Z3 does not pin a logging driver, so containers use your Docker daemon default. Add size limits in /etc/docker/daemon.json (see the FAQ); otherwise logs grow unbounded on a 24/7 node.
• Decide p2p exposure. Mainnet and testnet publish Zebra's p2p port for inbound peers. Behind NAT or a firewall, set ZEBRA_NETWORK__EXTERNAL_ADDR to the address peers should dial. Regtest is peerless and publishes no p2p.
• Tune the host network (Linux). On a busy mainnet node, default kernel TCP buffer and connection-backlog limits can cap Zebra's peer throughput. See Zebra's TCP tuning notes for the sysctl values worth raising.
• Bound resources on a shared host. No CPU or memory limits are set by default: right for a dedicated node, easy to get wrong on a shared box. Add deploy.resources.limits in an override file if you need them.

Z3 ships safe defaults: pinned image versions (no surprise upgrades), non-root containers with Linux capabilities dropped, health checks that hold the wallet back until the node is synced, and automatic restart. Upgrades stay deliberate: bump the version pin in a reviewed change, or set Z3_<SERVICE>_IMAGE.

Prometheus, Grafana, Jaeger, and AlertManager ship behind a Compose profile. Zebra's metrics are on by default at the in-network zebra:9999 scrape target.

docker compose --env-file .env.<network> --profile monitoring up -d

Default UI host ports are globally unique across the three networks (mainnet Grafana 3000, testnet 13000, regtest 23000, and so on). Each is overridable: Z3_GRAFANA_PORT, Z3_PROMETHEUS_PORT, Z3_ALERTMANAGER_PORT, Z3_JAEGER_UI_PORT.

docker compose --env-file .env.mainnet down       # stop containers, keep data
docker compose --env-file .env.mainnet down -v    # stop and delete all volumes (full reset)

You do not need this section to operate Z3. It covers running several networks for test scenarios, how the networks differ, the published service endpoints, and attaching your own services.

Operators usually run one network; testers often run several and need to know where they diverge from a deployment standpoint:

Mainnet pairs cleanly with either other network on one host. Testnet and regtest reuse Zebra's testnet container ports, so they differ only by published host port (the env files keep those unique). The rpc-router, a unified Zebra+Zallet JSON-RPC endpoint, runs only on regtest today.

graph LR
    subgraph Z3["Z3 (per network)"]
        Zebra["Zebra<br/>(full node)"]
        Zaino["Zaino<br/>(indexer)"]

        subgraph Zallet["Zallet (wallet)"]
            EmbeddedZaino["Embedded<br/>Zaino libs"]
        end
    end

    Zebra -->|JSON-RPC| Zaino
    Zebra -->|JSON-RPC| EmbeddedZaino
    Zaino -->|gRPC| LightClients["Light wallet<br/>clients"]

Zebra syncs and validates the Zcash blockchain. Zaino provides a lightwalletd-compatible gRPC interface for light wallet clients. Zallet embeds Zaino's indexer libraries internally and connects directly to Zebra's JSON-RPC; it does not use the standalone Zaino service.

Image pins live as ${VAR:-tag} defaults in docker-compose.yml; override any pin with Z3_ZEBRA_IMAGE, Z3_ZAINO_IMAGE, or Z3_ZALLET_IMAGE. Upstream sources: Zebra, Zaino, Zallet.

Published host ports are chosen per .env.<network> so all networks coexist on one host. The full per-network matrix lives in z3-contract.yaml.

Inside the network, services resolve by DNS name (zebra, zaino, zallet) on Zebra's per-network container ports.

Operators can skip this. It exists for downstream services, wallets, and tooling that attach to a running Z3 stack, and for agents that consume the API programmatically.

Z3 publishes a stable set of identifiers (network names, volume names, ports, and auth surfaces) so your service can attach by name and keep working across networks. A mainnet or testnet peer attaches over the external network and reads the RPC cookie from the shared volume:

networks:
  z3:
    external: true
    name: z3-testnet
volumes:
  z3-cookie:
    external: true
    name: z3-testnet-cookie
services:
  my-app:
    networks: [z3]
    volumes:
      - z3-cookie:/var/run/auth:ro
    environment:
      ZEBRA_RPC_URL: http://zebra:18232
      ZEBRA_COOKIE_PATH: /var/run/auth/.cookie

Regtest uses username/password instead of cookie auth; do not mount z3-regtest-cookie expecting a readable cookie. For the three attachment patterns (Compose peer, host-side pointer, lightwalletd client), see docs/integrations/. For the full identifier inventory and stability promise, see docs/contract.md and z3-contract.yaml.

scripts/vendor.sh
docker compose -f docker-compose.yml -f docker-compose.build.yml build

diff config/mainnet/zallet.toml config/mainnet/zallet.toml.example

scripts/vendor.sh zaino zallet
DOCKER_PLATFORM=linux/arm64 docker compose -f docker-compose.yml -f docker-compose.build.yml build zaino zallet
docker compose --env-file .env.mainnet up -d

# Per-service log levels
Z3_ZEBRA_RUST_LOG=debug
Z3_ZAINO_RUST_LOG=debug

# Pin a different image version
Z3_ZEBRA_IMAGE=zfnd/zebra:5.0.0

# Move chain state to an external SSD
Z3_CHAIN_DATA_PATH=/mnt/ssd/zebra-state

# Disable Zebra cookie auth (advanced; native Zebra config-rs var)
ZEBRA_RPC__ENABLE_COOKIE_AUTH=false

Z3_CHAIN_DATA_PATH=/mnt/ssd/zebra-state
Z3_ZAINO_DATA_PATH=/mnt/ssd/zaino-data
Z3_ZALLET_DATA_PATH=/mnt/ssd/zallet-data

./scripts/fix-permissions.sh zebra /mnt/ssd/zebra-state
./scripts/fix-permissions.sh zaino /mnt/ssd/zaino-data
./scripts/fix-permissions.sh zallet /mnt/ssd/zallet-data

Zebra (/ready: synced near tip)
  -> Cookie permissions (.cookie readable on cookie-auth networks)
  -> Zaino (gRPC port responding)
  -> Zallet (RPC responding)

curl http://localhost:8080/ready             # "ok" when synced
docker compose --env-file .env.mainnet logs -f zebra
./scripts/check-zebra-readiness.sh           # polls until synced, prints status every 30s

# How far behind tip /ready tolerates (raise during catch-up syncs)
ZEBRA_HEALTH__READY_MAX_BLOCKS_BEHIND=10

# Minimum peers required for /healthy (set 0 for regtest)
ZEBRA_HEALTH__MIN_CONNECTED_PEERS=3

# Make /ready always return 200 on testnet even during sync
ZEBRA_HEALTH__ENFORCE_ON_TEST_NETWORKS=true

• Operators: docs/faq.md (the "For operators" section)
• Developers and testers: docs/faq.md (the "For developers and testers" section), docs/regtest.md, docs/integrations/
• Integrators and agents: docs/contract.md, z3-contract.yaml
• Internals: docs/docker-architecture.md: Compose patterns, overlay merge rules, security hardening rationale
• Every env var: .env.example