.env

# z3/.env

# z3/docker-compose.yml Environment Variables

# =============================================================================
# VARIABLE HIERARCHY QUICK REFERENCE
# =============================================================================
# For detailed explanation, see README.md "Understanding the Variable Hierarchy"
#
# Three-tier system to avoid collisions:
#   Z3_*        - Infrastructure (volumes, ports) - Docker Compose only
#   (no prefix) - Shared config (remapped per service)
#   ZEBRA_*     - Zebra app config (ZEBRA_SECTION__KEY format)
#   ZAINO_*     - Zaino app config
#   ZALLET_*    - Zallet app config
#
# =============================================================================
# Z3 Stack Infrastructure Configuration
# =============================================================================
# These Z3_* variables control Docker Compose volume mounts and are NEVER
# passed to containers. They avoid collision with service configs (ZEBRA_*,
# ZAINO_*, ZALLET_*).
#
# Default: Docker named volumes (recommended - managed by Docker, no permission issues)
# Advanced: Local directories (see README.md "Advanced: Local Directories" section)
#
# To use local directories:
#   1. Choose appropriate paths for your OS (see README for suggestions)
#   2. Create directories: mkdir -p /your/chosen/path
#   3. Fix permissions: ./fix-permissions.sh <service> /your/chosen/path
#   4. Update variables below with your paths
#
# Security Requirements:
#   - Zebra:  UID=10001, GID=10001, permissions=700
#   - Zaino:  UID=1000,  GID=1000,  permissions=700
#   - Zallet: UID=65532, GID=65532, permissions=700
#   - Cookie: Keep as Docker volume (recommended) to avoid cross-user issues
#
# WARNING: Never use 755 or 777 permissions - they expose your data!

# =============================================================================
# Docker Platform Configuration
# =============================================================================
# Controls which architecture Docker builds/runs containers for.
# Default: linux/amd64 (x86_64 architecture)
#
# ARM64 Users (Apple Silicon M1/M2/M3, ARM64 Linux):
#  Uncomment and set to linux/arm64 for NATIVE builds
# DOCKER_PLATFORM=linux/arm64

# Zebra blockchain state directory
# Default: zebra_data (Docker named volume)
Z3_ZEBRA_DATA_PATH=zebra_data

# Shared cookie authentication directory (used by Zebra and Zaino)
# Default: shared_cookie_volume (Docker named volume)
# NOTE: For local directories, Zebra (10001) writes and Zaino (1000) reads.
#       Consider using Docker volume (default) to avoid cross-user permission issues.
#       If using local dir, you'll need to set up ACLs or a shared group.
Z3_COOKIE_PATH=shared_cookie_volume

# Zaino indexer data directory
# Default: zaino_data (Docker named volume)
Z3_ZAINO_DATA_PATH=zaino_data

# Zallet wallet data directory
# Default: zallet_data (Docker named volume)
Z3_ZALLET_DATA_PATH=zallet_data

# =============================================================================
# Common Configuration
# =============================================================================
# Shared variables used by multiple services, mapped in docker-compose.yml:
#   NETWORK_NAME → ZEBRA_NETWORK__NETWORK, ZAINO_NETWORK
#   ENABLE_COOKIE_AUTH → ZEBRA_RPC__ENABLE_COOKIE_AUTH
#   COOKIE_AUTH_FILE_DIR → ZEBRA_RPC__COOKIE_DIR, ZAINO_VALIDATOR_SETTINGS__VALIDATOR_COOKIE_PATH

# Network name for all services (e.g., Mainnet, Testnet, Regtest)
NETWORK_NAME=Mainnet
# Globally enables RPC cookie authentication
ENABLE_COOKIE_AUTH=true
# In-container directory for the .cookie authentication file
COOKIE_AUTH_FILE_DIR=/var/run/auth

# =============================================================================
# Zebra Configuration
# =============================================================================
# Zebra logging (will be mapped to RUST_LOG in container)
Z3_ZEBRA_RUST_LOG=info
# Zebra tracing filter (config-rs format: ZEBRA_TRACING__FILTER)
ZEBRA_TRACING__FILTER=info
# Zebra RPC listen address (config-rs format: ZEBRA_RPC__LISTEN_ADDR)
ZEBRA_RPC__LISTEN_ADDR=0.0.0.0:18232
# Zebra state cache directory (config-rs format: ZEBRA_STATE__CACHE_DIR)
ZEBRA_STATE__CACHE_DIR=/home/zebra/.cache/zebra
# Zebra health endpoint configuration
ZEBRA_HEALTH__LISTEN_ADDR=0.0.0.0:8080
ZEBRA_HEALTH__MIN_CONNECTED_PEERS=1
ZEBRA_HEALTH__READY_MAX_BLOCKS_BEHIND=2
ZEBRA_HEALTH__ENFORCE_ON_TEST_NETWORKS=false
# Infrastructure: Zebra RPC port (used in Docker Compose port mappings and service discovery)
Z3_ZEBRA_RPC_PORT=18232
# Infrastructure: Zebra host RPC port (for external access to Zebra)
Z3_ZEBRA_HOST_RPC_PORT=18232
# Infrastructure: Zebra host health port (for external access to health endpoints)
Z3_ZEBRA_HOST_HEALTH_PORT=8080

# =============================================================================
# Zaino Configuration
# =============================================================================
# Zaino Rust log level
ZAINO_RUST_LOG=info,reqwest=warn,hyper_util=warn
# Zaino's internal gRPC port. Zallet connects to this port on the 'zaino' service hostname.
ZAINO_GRPC_PORT=8137
# Enable/disable Zaino's JSON-RPC service
ZAINO_JSON_RPC_ENABLE=false
# Zaino internal JSON-RPC port
ZAINO_JSON_RPC_PORT=8237
# Zaino gRPC TLS (true/false)
ZAINO_GRPC_TLS_ENABLE=true # Set to true to enforce security policies
# Zaino host gRPC port (for external access to Zaino gRPC)
ZAINO_HOST_GRPC_PORT=8137
# Zaino host JSON-RPC port (for external access to Zaino JSON-RPC)
ZAINO_HOST_JSONRPC_PORT=8237
# In-container FHS-compliant paths for Zaino TLS configs
# These are the paths Zaino application expects for its cert and key
ZAINO_GRPC_TLS_CERT_PATH=/var/run/zaino/tls/zaino.crt
ZAINO_GRPC_TLS_KEY_PATH=/var/run/zaino/tls/zaino.key
# For Zaino healthcheck with TLS (adjust curl_opt as needed for your cert)
ZAINO_GRPC_TLS_ENABLE_SCHEME_SUFFIX=s
ZAINO_GRPC_TLS_ENABLE_CURL_OPT=-k # -k allows insecure for self-signed, use --cacert for prod
# Option to disable Zaino's local DB features (skips FinalisedState sync)
ZAINO_NO_DB=true
# Zaino validator username for Zebra RPC
ZAINO_VALIDATOR_USER=__cookie__
# Zaino Rust backtrace setting
ZAINO_RUST_BACKTRACE=full
# Zaino application internal config path
ZAINO_CONF_PATH=/home/zaino/.config/zaino/zindexer.toml
# Zaino application internal data directory
ZAINO_DATA_DIR=/home/zaino/.cache/zaino

# =============================================================================
# Zallet Configuration
# =============================================================================
# Zallet Rust log level
ZALLET_RUST_LOG=info,hyper_util=warn,reqwest=warn
# Zallet internal RPC port
ZALLET_RPC_PORT=28232
# Zallet host RPC port (for external access to Zallet RPC)
ZALLET_HOST_RPC_PORT=28232
# Zallet application internal config path
ZALLET_CONF_PATH=/etc/zallet/zallet.toml
# Zallet application internal data directory
ZALLET_DATA_DIR=/home/zallet/.data
# Example path for a CA certificate file that Zallet might use to trust Zaino's gRPC TLS certificate.
# If Zaino uses a self-signed certificate or a certificate from a private CA, Zallet would need to be
# configured to trust it. The actual environment variable name and mechanism depend on Zallet's implementation.
# ZALLET_INDEXER_CA_PATH=/path/to/trusted/zaino_ca.crt

# =============================================================================
# Monitoring Configuration (--profile monitoring)
# =============================================================================
# Enable monitoring with: docker compose --profile monitoring up -d
#
# To enable Zebra metrics, uncomment this variable:
ZEBRA_METRICS__ENDPOINT_ADDR=0.0.0.0:9999
#
# To enable OpenTelemetry tracing (Jaeger), build Zebra with OTel support:
#   docker compose build --build-arg FEATURES="default-release-binaries opentelemetry" zebra
# Then set the tracing endpoint:
# ZEBRA_TRACING__OPENTELEMETRY_ENDPOINT=http://jaeger:4318
# ZEBRA_TRACING__OPENTELEMETRY_SERVICE_NAME=zebra
# ZEBRA_TRACING__OPENTELEMETRY_SAMPLE_PERCENT=100
#
# Service ports (defaults shown, customize if needed):
# GRAFANA_PORT=3000
# PROMETHEUS_PORT=9094
# JAEGER_UI_PORT=16686
# ALERTMANAGER_PORT=9093
#
# Grafana admin password (default: admin, prompted to change on first login):
# GRAFANA_ADMIN_PASSWORD=your_secure_password