env.example

# NOTE: this file is docker compose's interpolation source, not a blanket
# container env file. A variable here only reaches a container when
# docker-compose.yml explicitly wires it through an `environment:` entry.

# --- Release channel ---------------------------------------------------------
# CHANNEL is the image tag the stack pulls. Leave it unset and you get `beta`
# -- a fresh clone with no .env at all runs beta.
#
# Both channels run Aglais, the live Quip test network (runtime spec 117).
# They differ only in how far ahead of the release line they sit:
#
#   stable  The released Aglais line.
#   beta    The Aglais prerelease line, ahead of stable. The default.
#
# The RETIRED testnet (runtime spec 116) no longer has a channel. An operator
# who has not migrated and does not want to must pin every QUIP_*_TAG to a
# v0.2 version by hand. A spec-116 stack cannot join Aglais, and a spec-117
# stack cannot join the retired network.
#
# CHANNEL drives every image, the validator included. Note that the validator
# publishes no non-rc v0.3 build yet, so its `stable` and `beta` resolve to
# the same Aglais image until one exists. `make show-channel` prints the
# reference. `docker image inspect` after a pull gives you the digest.
#
# Each image publishes both tags, so CHANNEL is substituted directly into the
# image reference. Set a QUIP_*_TAG below to pin one image to an exact version
# instead. An explicit pin always wins over CHANNEL. Run `make show-channel` to
# see exactly what you will pull.
# CHANNEL=beta

# D-Wave connection settings. Wired into the cpu/cuda miner containers only,
# and read only when a [qpu]/[dwave] backend is enabled in data/config.toml.
# These use the Ocean SDK's canonical names, because the miner lets the SDK
# resolve them. ~/.config/dwave/dwave.conf is the file-based alternative, and
# an empty value here resolves the same as leaving the variable unset.
#
# Budget keys (daily_budget and friends) are NOT set here. They belong in the
# [dwave] table of data/config.toml. Credentials are the reverse: they are not
# accepted in config.toml at all.
DWAVE_API_TOKEN=your-dwave-api-token-here

# Solver to run against. Leave empty and the SDK picks whatever your account
# defaults to, which may not be the Advantage2 system the chain topology
# targets. Set it explicitly on a QPU node, for example:
# DWAVE_API_SOLVER=Advantage2_system1.4
DWAVE_API_SOLVER=

# Leap region, for example na-west-1 or eu-central-1. Empty lets the SDK choose.
DWAVE_API_REGION=

# Deprecated spelling of DWAVE_API_TOKEN. Nothing reads this name: the miner
# and the Ocean SDK both read DWAVE_API_TOKEN. docker-compose.yml still maps it
# forward so an existing .env keeps working. Move the value to
# DWAVE_API_TOKEN above and delete this line.
# DWAVE_API_KEY=

# --- Node file ownership ----------------------------------------------------
# The node container runs as a non-root 'quip' user (uid 1000 by default)
# and chowns /data to match on first start. The setup step seeds these from
# your host uid/gid via `id -u` / `id -g`; override here if you need to
# run under a different user. PUID=0 keeps legacy root-mode.
# PUID=1000
# PGID=1000

# --- HTTP(S) front-door (Caddy) ---------------------------------------------
# Caddy listen address(es). Single value drives both port binding and TLS:
#
#   Dev (HTTP only, default):
#     QUIP_HOSTNAME=:20049
#
#   Production (auto-TLS on :443 + :20049, :80 auto-redirects to :443):
#     QUIP_HOSTNAME=cpu-1.nodes.quip.network, cpu-1.nodes.quip.network:20049
#
# In production the comma-separated form is required so the site serves on
# BOTH :443 (default HTTPS) and :20049 (the Quip API port). Caddy provisions
# one Let's Encrypt cert covering both; port 80 must be reachable from the
# internet for the ACME HTTP-01 challenge. Validator profiles require the
# production form so substrate RPC is served over TLS.
QUIP_HOSTNAME=:20049

# Email used by Caddy to register with the ACME issuer (Let's Encrypt by
# default, ZeroSSL as automatic fallback). Required when QUIP_HOSTNAME is a
# real DNS name; ignored otherwise. Leave commented out for dev / localhost
# so Caddy uses the placeholder default (hostmaster@localhost) — uncomment
# and set a real address before exposing the site over TLS.
# CERT_EMAIL=ops@example.com

# Optional: ZeroSSL API key from https://app.zerossl.com/developer. Only
# consulted if you uncomment the `cert_issuer zerossl` line in
# caddy/Caddyfile to switch ZeroSSL to the primary issuer. Leave unset
# to stick with Let's Encrypt (recommended default).
# ZEROSSL_API_KEY=

# --- Miner image ------------------------------------------------------------
# Image tag for the cpu and cuda miner. docker-compose.yml defaults to the tag
# CHANNEL names, not `latest`. Do not use `latest` for these two images: it is
# not maintained as a release pointer, it currently resolves to a prerelease
# build, and the cuda image publishes no `latest` tag at all. Because
# docker-compose.yml sets
# `pull_policy: always`, the tag is re-resolved on every `up`, so an operator
# who does not touch this always runs whatever the compose default currently
# names.
#
# Set this to override the compose default — a released version, a release
# candidate, or a commit SHA tag (:sha-XXXXXXXX) for a fully reproducible one:
#   QUIP_MINER_TAG=<tag>
# A value here always wins over the compose default, so a stale pin silently
# holds the stack on an old build. Remove the line rather than updating it.
#
# `make localdev` does not use the compose default. It asks the registry which
# tag is newest by publish time and uses that, which is how it picks up release
# candidates the compose default does not track yet. A pin set here still
# wins — localdev passes it through untouched. The same applies to the three
# tag variables below.
# QUIP_MINER_TAG=

# CPU cores visible to the cpu miner. Defaults to a single core ("0") so the
# upstream entrypoint's `num_cpus = $(nproc)` autodetect writes 1 on fresh
# installs instead of saturating colocated validator + dashboard hosts.
# Override with a cpuset list/range for dedicated miner boxes:
#   QUIP_MINER_CPUSET=0-15      # 16 cores
#   QUIP_MINER_CPUSET=0,2,4,6   # specific cores
# Only takes effect on container (re)create; existing data/config.toml is left
# alone by the entrypoint, so delete that file to pick up the new default.
QUIP_MINER_CPUSET=0

# Hard memory ceiling for the cpu miner. The miner's working set grows through
# a round and has been observed at 27.1 GiB on a 32 GiB host, where it tripped
# global OOM-kills that took the validator and dashboard down with it. The cap
# turns that into a single container restart instead. It is a v0.2 stopgap: the
# underlying growth is fixed in v0.3, and until then a periodic reboot (or
# `docker compose restart cpu`) between rounds is the recommended mitigation.
# The miner's 2 GiB /dev/shm ring is charged against this same limit, so 16g
# means ~14 GiB of heap. Leave headroom for the colocated validator, postgres
# and dashboard; only raise this on a dedicated miner host.
QUIP_MINER_MEM_LIMIT=16g

# --- Container logs ---------------------------------------------------------
# Size of Docker's local log cache per container, in the form 32m / 1g.
# Under the syslog driver this sizes the dual-logging ring buffer that backs
# `docker compose logs`. QUIP_LOG_MAX_SIZE × QUIP_LOG_MAX_FILE is the cache per
# service: 32 MiB × 5 = 160 MiB per service. A make testnet PROFILE=cpu stack
# runs five logging services (cpu, validator, dashboard, postgres, caddy), so
# roughly 800 MiB of cache in total. The collector (separate, json-file) uses
# 8 MiB × 2 = 16 MiB. The durable merged file (separate) uses 10 MB live plus
# roughly 50 MB across five rotated generations (10 MB × 5), about 60 MB
# total. Raise cache size when you need deeper history to chase an incident.
# Rotation applies on container (re)create.
QUIP_LOG_MAX_SIZE=32m
QUIP_LOG_MAX_FILE=5

# The durable merged log, data/logs/quip-node.log. Rotates at 10 MB and keeps
# 5 generations, matching the v0.1 miner. The collector checks the size every
# QUIP_LOG_CHECK_INTERVAL seconds, so the file can overshoot by one interval's
# worth of output before it rotates.
QUIP_LOG_MAX_BYTES=10485760
QUIP_LOG_KEEP=5
QUIP_LOG_CHECK_INTERVAL=30

# Host-side UDP port the collector listens on. The container side always
# stays 5514. Change this only if something else already holds 5514 on the
# host (check with `ss -lunp | grep 5514`) -- otherwise `docker compose up`
# fails to bind the collector's port and, because every logging service
# depends on it, the whole stack fails to start.
QUIP_LOG_PORT=5514

# Pinned collector image tag. Verify a new tag is pullable before raising
# this: `docker manifest inspect linuxserver/syslog-ng:<tag>`.
QUIP_SYSLOG_TAG=4.11.0

# --- CUDA / NVIDIA MPS (cuda profile only) ----------------------------------
# The cuda miner uses NVIDIA MPS (Multi-Process Service) for hardware SM
# sharing. MPS is a HOST facility: `make testnet PROFILE=cuda` starts the host
# control daemon (nvidia-cuda-mps-control -d, pipe dir /tmp/nvidia-mps) for
# you. Without it the miner logs "MPS not active in container" and falls back
# to software nonce reduction — degraded, not broken. Unsupported on WSL2 /
# Docker Desktop.
#
# Per-miner GPU SM share cap (CUDA_MPS_ACTIVE_THREAD_PERCENTAGE) when a host
# MPS daemon is up. Default 100 (whole GPU); for N miners sharing one GPU use
# 100/N.
# QUIP_GPU_UTILIZATION=100

# Miner behavior (validators, faucet, REST port, ...) is NOT configured
# here — the miner is config-driven as of the quip-miner v0.2.1-rc
# images. Edit data/config.toml (seeded on first run from
# config/quip-miner.<profile>.toml) and restart the container.

# --- Dashboard + Postgres (bundled with every node profile) -----------------
# Dashboard image tag. Leave commented out to track `latest`. Pin only for a
# reproducible deploy:
#   QUIP_DASHBOARD_TAG=<tag>
# QUIP_DASHBOARD_TAG=


# Postgres is only reachable inside the compose network (port 5432 is not
# published to the host), so the default password is fine for local use.
# Override for defense-in-depth on shared hosts:
# POSTGRES_PASSWORD=quip
# POSTGRES_DB=quip
# POSTGRES_USER=quip

# Substrate WS RPC the dashboard indexer polls — drives both the chain tab
# (epochs, finalized head, validator authorship, hardware descriptor
# backfill) and the miner REST surface that Caddy fronts on the same host.
# Defaults to the colocated validator (cpu and cuda profiles bundle one by
# default). Only override when running the miner on a host without its own
# validator — point at a remote full node's WS endpoint (comma-separated;
# the indexer rotates through the list on failure):
#   QUIP_VALIDATOR_RPC_URLS=wss://cpu-1.nodes.quip.network/rpc
# Leave unset to disable substrate-side indexing (chain tab stays empty).
# QUIP_VALIDATOR_RPC_URLS=ws://quip-validator:9944
#
# v0.1 → v0.2: this variable supersedes QUIP_NODE_URL and QUIP_NODE_TOKEN
# from the v0.1 dashboard config. If you're upgrading, remove those two
# lines from your existing .env — they're no longer consumed and will only
# confuse future readers.

# --- Validator (bundled into cpu / cuda profiles) ---------------------------
# Image tag for the substrate validator. Leave commented out to run the
# compose default, which is the tag CHANNEL names. `latest` still points at
# the pre-Aglais image, which cannot run this chain, and it is not maintained
# as a release pointer: do not name it.
# Pin a SHA tag like sha-13536ad2 for a reproducible deploy:
#   QUIP_VALIDATOR_TAG=<tag>
# QUIP_VALIDATOR_TAG=

# Chain spec the validator boots against. Defaults to Aglais, the Quip test
# network (chain-specs/aglais-network.json, name=AGLS (Quip Testnet),
# id=quip_testnet). Override to join a private network with its own spec.
# Local development does not use this: `make localdev` runs the image's
# built-in --chain=dev preset.
# QUIP_CHAIN_SPEC=./chain-specs/aglais-network.json

# Human-readable validator name surfaced on the substrate telemetry feed
# (used with --name). No consensus effect.
VALIDATOR_NAME=my-quip-validator

# Extra bootnodes: the Aglais spec embeds its bootnodes, so none are
# needed by default. To add more (e.g. a private network), append
# `--bootnodes=<multiaddr>` entries to the validator command via a
# docker-compose.override.yml — compose can't split an env var into
# multiple argv tokens, so there is no env knob for this.

# --- Faucet (faucet profile, optional) --------------------------------------
# Image tag for the standalone faucet bot
# (registry.gitlab.com/quip.network/faucet). Leave commented out to track the
# tag CHANNEL names. This image carries no version tags, only channel and
# commit-SHA tags, so `stable` and `beta` are the only readable names for it.
# The faucet sidecar is optional: the miner funds itself from the hosted
# faucet named by [miner].faucet_url in data/config.toml, and only an operator
# running --profile faucet needs this image at all.
# QUIP_FAUCET_TAG=

# Substrate node URL the faucet talks to. Defaults to the colocated validator.
# QUIP_FAUCET_NODE_URL=ws://quip-validator:9944

# Funder URI. Dev-only for now — must be one of //Alice, //Bob, //Alice//stash
# on hybrid chains. The funder must be funded at genesis on the active chain.
# QUIP_FAUCET_KEY=//Alice

# Seconds between requests per destination (anti-drain throttle).
# QUIP_FAUCET_RATE_LIMIT_SECONDS=60

# Set to 1 to bypass the dev-chain safety check. UNSAFE — only override when
# you've deliberately allocated the funder key on a non-dev chain.
# QUIP_FAUCET_ALLOW_ANY_CHAIN=0