diff --git a/deployments/compose/metrics.yml b/deployments/compose/metrics.yml deleted file mode 100644 index 9b2e391aee..0000000000 --- a/deployments/compose/metrics.yml +++ /dev/null @@ -1,29 +0,0 @@ ---- -# docker-compose file for running a sidecar metrics deployment. -# Requires a running fullnode, exposing metrics on http://localhost:8080 -# on the host machine. - -version: "3.7" -services: - # The Grafana service, which pulls data from Prometheus and serves a web UI. - grafana: - image: penumbra-grafana - build: - context: ../../ - dockerfile: deployments/containerfiles/Dockerfile-grafana - network_mode: host - user: "${UID:-1000}" - # Don't use ports, since ports conflicts with network_mode=host. - # We use network_mode=host so that metrics can talk to services bound - # to localhost. - # ports: - # - "3000:3000" - - # The Prometheus service, for scraping metrics from Penumbra's pd metrics port. - prom: - image: "docker.io/prom/prometheus" - network_mode: host - # ports: - # - "9090:9090" - volumes: - - "${PWD:?}/../config/prometheus.yml:/etc/prometheus/prometheus.yml:ro" diff --git a/deployments/compose/process-compose-metrics.yml b/deployments/compose/process-compose-metrics.yml new file mode 100644 index 0000000000..e2181989f6 --- /dev/null +++ b/deployments/compose/process-compose-metrics.yml @@ -0,0 +1,47 @@ +--- +# A process-compose configuration for running a Prometheus/Grafana metrics setup for Penumbra, +# scraping metrics endpoints for a localhost-based fullnode. +version: "0.5" +log_level: info +is_strict: true + +processes: + # Run Grafana for displaying metrics in a web UI: http://localhost:3000 + grafana: + command: |- + set -e + ./deployments/scripts/prep-grafana-env + export GF_PATHS_PROVISIONING=~/.penumbra/network_data/grafana/conf/provisioning + grafana server --homepath ~/.penumbra/network_data/grafana --config ./deployments/config/grafana/grafana.ini + readiness_probe: + http_get: + host: 127.0.0.1 + scheme: http + path: "/" + port: 3000 + initial_delay_seconds: 10 + period_seconds: 5 + failure_threshold: 3 + availability: + restart: exit_on_failure + depends_on: + prometheus: + condition: process_healthy + + # Run Prometheus for scraping local services: http://localhost:9090 + prometheus: + command: |- + set -e + mkdir -p ~/.penumbra/network_data/prometheus + prometheus --config.file ./deployments/config/prometheus/prometheus.yml --storage.tsdb.path ~/.penumbra/network_data/prometheus + readiness_probe: + http_get: + host: 127.0.0.1 + scheme: http + path: "/" + port: 9090 + initial_delay_seconds: 10 + period_seconds: 5 + failure_threshold: 3 + availability: + restart: exit_on_failure diff --git a/deployments/compose/process-compose-postgres.yml b/deployments/compose/process-compose-postgres.yml new file mode 100644 index 0000000000..b106a832c1 --- /dev/null +++ b/deployments/compose/process-compose-postgres.yml @@ -0,0 +1,76 @@ +--- +# A process-compose configuration for running a PostgreSQL database, +# specifically for indexing ABCI events as emitted by CometBFT for Penumbra. +version: "0.5" +log_level: info +is_strict: true + +processes: + # Run postgresql db process + postgresql: + command: |- + set -e + ./deployments/scripts/prep-postgres-env + postgres -k /tmp -D ~/.penumbra/network_data/postgresql/ + readiness_probe: + exec: + command: psql -h localhost -p 5432 -lqt + initial_delay_seconds: 5 + period_seconds: 5 + failure_threshold: 3 + shutdown: + # Send SIGINT rather than default SIGTERM to get faster postgres shutdown. + # More info: https://www.postgresql.org/docs/current/server-shutdown.html + # and `man 7 signal`. + signal: 2 + availability: + restart: exit_on_failure + + # Set up databases and initial schemas + postgresql-init: + command: |- + set -e + if psql -h localhost -p 5432 -lqt | grep penumbra_cometbft ; then + >&2 echo "Postgres DB already initialized, skipping schema/grants..." + exit 0 + fi + >&2 echo "Creating database schema for CometBFT..." + # Create database for CometBFT writes + createdb -h localhost -p 5432 penumbra_cometbft || true + createuser -h localhost -p 5432 penumbra + psql -h localhost -p 5432 -d penumbra_cometbft -f crates/util/cometindex/vendor/schema.sql + psql -h localhost -p 5432 -d penumbra_cometbft -c 'GRANT ALL PRIVILEGES ON DATABASE penumbra_cometbft TO penumbra;' + psql -h localhost -p 5432 -d penumbra_cometbft -c 'GRANT pg_read_all_data TO penumbra;' + psql -h localhost -p 5432 -d penumbra_cometbft -c 'GRANT pg_write_all_data TO penumbra;' + + # Create database for pindexer + >&2 echo "Creating database schema for pindexer..." + createuser -h localhost -p 5432 penumbra_ro + createdb -h localhost -p 5432 penumbra_pindexer || true + psql -h localhost -p 5432 -d penumbra_cometbft -c 'GRANT pg_read_all_data TO penumbra_ro;' + psql -h localhost -p 5432 -d penumbra_pindexer -c 'GRANT pg_write_all_data TO penumbra_ro;' + psql -h localhost -p 5432 -d penumbra_pindexer -c 'GRANT ALL PRIVILEGES ON DATABASE penumbra_pindexer TO penumbra_ro;' + availability: + restart: exit_on_failure + depends_on: + postgresql: + condition: process_healthy + + # Add rule for CometBFT to wait for db to be ready. + cometbft: + depends_on: + postgresql-init: + condition: process_completed_successfully + + # Add rule for CometBFT to wait for db to be ready. + pindexer: + environment: + - "RUST_LOG=debug" + command: |- + cargo run --release --bin pindexer -- \ + --src-database-url "postgresql://localhost:5432/penumbra_cometbft?sslmode=disable" \ + --dst-database-url "postgresql://localhost:5432/penumbra_pindexer?sslmode=disable" \ + --genesis-json ~/.penumbra/network_data/node0/cometbft/config/genesis.json + depends_on: + postgresql-init: + condition: process_completed_successfully diff --git a/deployments/compose/process-compose.yml b/deployments/compose/process-compose.yml new file mode 100644 index 0000000000..defd6e629e --- /dev/null +++ b/deployments/compose/process-compose.yml @@ -0,0 +1,45 @@ +--- +# A process-compose configuration for running a local Penumbra devnet. +# This isn't used in scripts anywhere (yet?) but serves as a reference point. +# Potentially could be integrated with e.g. https://www.jetify.com/devbox later on. +# +version: "0.5" + +# Env vars set here will be accessible to all processes. +environment: + - "RUST_LOG=info,network_integration=debug,pclientd=debug,pcli=info,pd=info,penumbra=info" + +log_level: info +is_strict: true +# Interleave logs from all services in single file, so it's greppable. +log_location: deployments/logs/dev-env-combined.log + +processes: + # Run pd validator based on generated network. + pd: + command: cargo run --release --bin pd -- start + readiness_probe: + http_get: + host: 127.0.0.1 + scheme: http + path: "/" + port: 8080 + failure_threshold: 2 + initial_delay_seconds: 5 + period_seconds: 5 + + # Run CometBFT for consensus driver. + cometbft: + command: cometbft --log_level=debug --home ~/.penumbra/network_data/node0/cometbft start + readiness_probe: + http_get: + host: 127.0.0.1 + scheme: http + path: "/" + port: 26657 + failure_threshold: 2 + initial_delay_seconds: 5 + period_seconds: 5 + depends_on: + pd: + condition: process_healthy diff --git a/deployments/config/grafana/dashboards/pd-performance.json b/deployments/config/grafana/dashboards/pd-performance.json index d6b39324ca..ee68bd60b1 100644 --- a/deployments/config/grafana/dashboards/pd-performance.json +++ b/deployments/config/grafana/dashboards/pd-performance.json @@ -478,7 +478,7 @@ ] }, "time": { - "from": "now-6h", + "from": "now-1h", "to": "now" }, "timepicker": {}, diff --git a/deployments/config/grafana/dashboards/sync.json b/deployments/config/grafana/dashboards/sync.json index feb308f511..e5997e6036 100644 --- a/deployments/config/grafana/dashboards/sync.json +++ b/deployments/config/grafana/dashboards/sync.json @@ -809,7 +809,7 @@ ] }, "time": { - "from": "now-7d", + "from": "now-1h", "to": "now" }, "timepicker": {}, diff --git a/deployments/config/grafana/grafana.ini b/deployments/config/grafana/grafana.ini index c44e394530..fe409db26e 100644 --- a/deployments/config/grafana/grafana.ini +++ b/deployments/config/grafana/grafana.ini @@ -1,15 +1,22 @@ +# Custom Grafana settings file. Compare with defaults at e.g. +# https://raw.githubusercontent.com/grafana/grafana/main/conf/defaults.ini + [paths] -provisioning = /etc/grafana/provisioning +# The filepaths are relative to the git repository, to prioritize +# dev envs. +# provisioning = /etc/grafana/provisioning +provisioning = ./deployments/config/grafana/provisioning + +[dashboards] +# default_home_dashboard_path = /var/lib/grafana/dashboards/pd performance.json +default_home_dashboard_path = ./deployments/config/grafana/dashboards/pd-performance.json -# grafana config for local development. don't enable accounts & auth, just let -# me look at the dashboards! +# Grafana config for local development. Removes all authentication, +# to make it easier for a developer to view the dashboards. +# Not appropriate for a production config! [auth] -# this doesn't seem to work but you can just navigate to other URLs... disable_login_form = true -[dashboards] -default_home_dashboard_path = /var/lib/grafana/dashboards/P2P.json - [auth.anonymous] # enable anonymous access enabled = true diff --git a/deployments/config/grafana/provisioning/dashboards/all.yml b/deployments/config/grafana/provisioning/dashboards/all.yml index e23a61d130..9498fef242 100644 --- a/deployments/config/grafana/provisioning/dashboards/all.yml +++ b/deployments/config/grafana/provisioning/dashboards/all.yml @@ -3,4 +3,4 @@ folder: '' type: 'file' options: - folder: '/var/lib/grafana/dashboards' \ No newline at end of file + folder: 'deployments/config/grafana/dashboards' diff --git a/deployments/config/prometheus.yml b/deployments/config/prometheus/prometheus.yml similarity index 100% rename from deployments/config/prometheus.yml rename to deployments/config/prometheus/prometheus.yml diff --git a/deployments/scripts/check-nix-shell b/deployments/scripts/check-nix-shell new file mode 100755 index 0000000000..1942f4f0a2 --- /dev/null +++ b/deployments/scripts/check-nix-shell @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# Helper script to detect whether a Nix environment is active: +# if not, warn the user to consult the dev docs for setting it up. +# Useful for running in developer scripts as a sanity check. +set -euo pipefail + + +if [[ -z "${IN_NIX_SHELL:-}" ]] ; then + >&2 echo "WARNING: nix environment not active, dependencies may be missing. Did you forget to run 'nix develop'?" + >&2 printf '\tSee developer docs at https://guide.penumbra.zone for more info\n' + # Sleep to ensure warning is visible; presumably we're calling this script in dev tooling, + # immediately preceding a TUI-grabbing app like process-compose. + sleep_duration_seconds="5" + for i in $(seq 0 "$sleep_duration_seconds") ; do + printf '\rResuming script in %s... ' "$(( sleep_duration_seconds - i ))" + sleep 1 + done + printf '\n' +fi diff --git a/deployments/scripts/prep-grafana-env b/deployments/scripts/prep-grafana-env new file mode 100755 index 0000000000..ca99c687e3 --- /dev/null +++ b/deployments/scripts/prep-grafana-env @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +# Helper script to prepare a localhost grafana instance, +# provisioned via nix, for displaying Penumbra metrics. +set -euo pipefail + + +# The Nix env will add the Grafana public directory to XDG_DATA_DIRS. +# Let's pluck that out of the dir listing env vars, so we can copy files out of it +# to a writable location. +grafana_share_dir="$(echo "$XDG_DATA_DIRS" | perl -npE 's/:/\n/g' | grep grafana | tail -n 1)" + +if [[ -z "${grafana_share_dir}" ]] ; then + >&2 "ERROR: could not find grafana dir in XDG_DATA_DIRS" + exit 1 +fi + +# Set up a write-friendly directory for grafana state from the local fullnode. +# The nix store is read-only by default, so add write capability to copy. +grafana_config_dir="$HOME/.penumbra/network_data/grafana" +# While debugging it may be useful to nuke the dir between runs. +# rm -rf "$grafana_config_dir" +rsync -a "${grafana_share_dir:?}/grafana/" "${grafana_config_dir}/" +chmod -R u+w "$grafana_config_dir" + +# Copy in Penumbra-specific dashboards +rsync -a --delete-after "${PWD}/deployments/config/grafana/dashboards" "${grafana_config_dir}/conf/dashboards/" +rsync -a --delete-after "${PWD}/deployments/config/grafana/provisioning/" "${grafana_config_dir}/conf/provisioning/" diff --git a/deployments/scripts/prep-postgres-env b/deployments/scripts/prep-postgres-env new file mode 100755 index 0000000000..40789b0091 --- /dev/null +++ b/deployments/scripts/prep-postgres-env @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# Helper script to prepare a localhost postgres instance, +# provisioned via nix, for ingesting ABCI events from CometBFT for Penumbra. +set -euo pipefail + + +# The Nix env will add the postgres share directory to XDG_DATA_DIRS. +# Let's pluck that out of the dir listing env vars, so we can copy files out of it +# to a writable location. +postgres_share_dir="$(echo "$XDG_DATA_DIRS" | perl -npE 's/:/\n/g' | grep postgresql | tail -n 1)" + +if [[ -z "${postgres_share_dir}" ]] ; then + >&2 "ERROR: could not find postgres dir in XDG_DATA_DIRS" + exit 1 +fi + +# Set up a write-friendly directory for postgres state. +# The nix store is read-only by default, so add write capability to copy. +postgres_config_dir="$HOME/.penumbra/network_data/postgresql" +# While debugging it may be useful to nuke the dir between runs. +# rm -rf "$postgres_config_dir" +mkdir -p "${postgres_config_dir}" + +# If PG_VERSION exists, then the initdb cmd has already been run. +if [[ -e "${postgres_config_dir}/PG_VERSION" ]] ; then + >&2 echo "Postgres database already configured in '${postgres_config_dir}', skipping initdb..." +else + pg_ctl initdb --pgdata "${postgres_config_dir}" +fi diff --git a/deployments/scripts/run-local-devnet.sh b/deployments/scripts/run-local-devnet.sh new file mode 100755 index 0000000000..187b9357b6 --- /dev/null +++ b/deployments/scripts/run-local-devnet.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# Dev tooling to spin up a localhost devnet for Penumbra. +set -euo pipefail + + +repo_root="$(git rev-parse --show-toplevel)" +# The process-compose file already respects local state and will reuse it. +# "${repo_root}/deployments/scripts/warn-about-pd-state" + +>&2 echo "Building binaries from latest code..." +cargo build --release --bin pd +# Also make sure to invoke via `cargo run` so that the process-compose +# spin-up doesn't block on more building/linking. +cargo --quiet run --release --bin pd -- --help > /dev/null + +# Generate network from latest code, only if network does not already exist. +if [[ -d ~/.penumbra/network_data ]] ; then + >&2 echo "network data exists locally, reusing it" +else + cargo run --release --bin pd -- network generate \ + --chain-id penumbra-local-devnet \ + --unbonding-delay 50 \ + --epoch-duration 50 \ + --proposal-voting-blocks 50 \ + --timeout-commit 1s + # opt in to cometbft abci indexing to postgres + postgresql_db_url="postgresql://penumbra:penumbra@localhost:5432/penumbra_cometbft?sslmode=disable" + sed -i -e "s#^indexer.*#indexer = \"psql\"\\npsql-conn = \"$postgresql_db_url\"#" ~/.penumbra/network_data/node0/cometbft/config/config.toml +fi + +# Run the core fullnode config, plus any additional params passed via `$@`. +process-compose up --no-server --config "${repo_root}/deployments/compose/process-compose.yml" --keep-tui "$@" diff --git a/deployments/scripts/warn-about-pd-state b/deployments/scripts/warn-about-pd-state new file mode 100755 index 0000000000..acc81bad90 --- /dev/null +++ b/deployments/scripts/warn-about-pd-state @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +# Utility script to check whether a Penumbra state dir exists, +# and exit non-zero if so. Useful to reuse throughout a variety +# of CI scripts for the Penumbra monorepo. +set -euo pipefail + + +# Fail fast if testnet dir exists, otherwise `cargo run ...` will block +# for a while, masking the error. +if [[ -d ~/.penumbra/network_data ]] ; then + >&2 echo "ERROR: network data directory exists at ~/.penumbra/network_data" + >&2 echo "Not removing this directory automatically; to remove, run: pd network unsafe-reset-all" + exit 1 +fi diff --git a/docs/guide/src/SUMMARY.md b/docs/guide/src/SUMMARY.md index 98fdfe4198..04ca3089ce 100644 --- a/docs/guide/src/SUMMARY.md +++ b/docs/guide/src/SUMMARY.md @@ -23,8 +23,8 @@ - [Making RPC requests](./node/pclientd/rpc.md) - [Building Transactions](./node/pclientd/build_transaction.md) - [Development](./dev.md) - - [Compiling from source](./dev/build.md) - - [Devnet Quickstart](./dev/devnet-quickstart.md) + - [Developer environment](./dev/dev-env.md) + - [Devnet quickstart](./dev/devnet-quickstart.md) - [Working with SQLite](./dev/sql.md) - [Building documentation](./dev/docs.md) - [Building protobuf](./dev/protobuf.md) @@ -32,6 +32,7 @@ - [Zero Knowledge Proofs](./dev/parameter_setup.md) - [RPC access](./dev/rpc.md) - [Testing IBC](./dev/ibc.md) + - [Compiling from source](./dev/build.md) - [Resources](./resources.md) - [Tutorials](./tutorials.md) - [Running a fullnode](./tutorials/running-node.md) diff --git a/docs/guide/src/dev.md b/docs/guide/src/dev.md index 2c0b6d6577..0c147030e7 100644 --- a/docs/guide/src/dev.md +++ b/docs/guide/src/dev.md @@ -1,3 +1,13 @@ # Development -This section is for developers working on Penumbra source code. +This section is for developers, either working on Penumbra source code itself, +or writing services that interact with Penumbra. + + diff --git a/docs/guide/src/dev/build.md b/docs/guide/src/dev/build.md index 35d95ad37a..1ebbacf6e0 100644 --- a/docs/guide/src/dev/build.md +++ b/docs/guide/src/dev/build.md @@ -1,10 +1,14 @@ # Compiling from source -Penumbra is written in Rust. To build it, you will need a recent +Penumbra is written in [Rust]. To build it, you will need a recent stable version of Rust, as well as a few OS-level dependencies. We don't support building on Windows. If you need to use Windows, consider using [WSL] instead. +This page aims to describe the steps necessary to work on Penumbra when +settings up the build environment manually, without using [Nix]. +If you want an easy-to-use setup, see the docs on [developer environments](./dev-env.md). + ### Installing the Rust toolchain This requires that you install a recent (>= 1.75) stable version @@ -132,6 +136,8 @@ SNAPPY_LIB_DIR=`pwd` Once you've built rocksdb and set the environment variable, the `librocksdb-sys` crate will search in that directory for the compiled `librocksdb.a` static library when it is rebuilt. +[Rust]: https://www.rust-lang.org/ [snappy-build]: https://github.com/google/snappy?tab=readme-ov-file#building [protoc-install]: https://grpc.io/docs/protoc-installation/ [WSL]: https://learn.microsoft.com/en-us/windows/wsl/install +[Nix]: https://nixos.org/ diff --git a/docs/guide/src/dev/dev-env.md b/docs/guide/src/dev/dev-env.md new file mode 100644 index 0000000000..b64b4c9c5c --- /dev/null +++ b/docs/guide/src/dev/dev-env.md @@ -0,0 +1,72 @@ +# Developer environment + +To get started working on Penumbra, you'll need a few dependencies on your workstation. +Running tests and local services is more involved. The project uses [Nix] to automate +the creation of developer environments with suitable tooling. If you'd prefer not to use +Nix, and instead configure your environment manually, see the docs on +[compiling from source](./build.md). + +## Installation OS-level packages +You'll need `git` and `git-lfs` to clone the Penumbra protocol repository. +Install these via your package manager of choice: + +```bash +# for macos +brew install git-lfs +# for linux debian/ubuntu +sudo apt install -y git-lfs +# for linux fedora +sudo dnf install -y git-lfs +``` + +Then, for all platforms, make sure to run `git lfs install`. Now you're ready to clone the +Penumbra protocol repo: + +``` +git clone https://github.com/penumbra-zone/penumbra +``` + +## Using `nix develop` for project dependencies + + + +Install [Nix]. After restarting your shell, create a config file to enable +Nix flakes: + +``` +mkdir -p ~/.config/nix +echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf +``` + +Now hop into the Penumbra directory and activate the env: + +``` +cd penumbra +nix develop +``` + +You'll have to wait a bit for packages to be built and installed. Once it finishes, +your active shell will have access to Penumbra project dependencies, like a compatible +version of `cometbft`, and other dev tooling, like `grpcurl` and `mdbook`. +You can run `exit` to return to your normal shell, without those tools, which have been installed to `/nix/store/`. + +## Using `direnv` + +If you use [direnv], you can copy the example `.envrc` file to automatically activate +the Penumbra nix environment when you cd to the repository: + +``` +cp .envrc.example .envrc +direnv allow +``` + +The `.envrc` path is intentionally git-ignored, so you can customize it as you see fit. +If you don't use `direnv`, you'll need to run `nix develop` in any terminal window +where you want access to the Penumbra dev env. Using `direnv` will make shell startup +a bit slower, so choose what's best for you. + +[Nix]: https://nixos.org/ +[direnv]: https://direnv.net/ diff --git a/docs/guide/src/dev/devnet-quickstart.md b/docs/guide/src/dev/devnet-quickstart.md index abd3e6f2f5..3c59ee4e6a 100644 --- a/docs/guide/src/dev/devnet-quickstart.md +++ b/docs/guide/src/dev/devnet-quickstart.md @@ -1,48 +1,37 @@ -# Devnet Quickstart +# Devnet quickstart -This page describes a quickstart method for running `pd`+`cometbft` to test -changes during development. +This page assumes you've set up a [Penumbra developer environment](./dev-env.md), +as it references several commands like `cometbft` in order to work. +It describes how to run a Penumbra fullnode on your local workstation, for building +and testing Penumbra and related services. -To start, you'll need to install a [specific version of CometBFT](../node/pd/install.md#installing-cometbft). +## Running a local devnet -## Generating configs - -To generate a clean set of configs, run - -```shell -cargo run --release --bin pd -- network generate -``` - -This will write configs to `~/.penumbra/network_data/`. - -## Running `pd` - -You'll probably want to set `RUST_LOG`. Here's one suggestion that's quite verbose: - -```shell -# Optional. Expect about 20GB/week of log data for pd with settings below. -export RUST_LOG="info,pd=debug,penumbra=debug,jmt=debug" -``` - -To run `pd`, run +To generate a devnet genesis and run a Penumbra fullnode locally, run: ```shell -cargo run --release --bin pd -- start +just dev ``` -This will start but won't do anything yet, because CometBFT isn't running. - -## Running `cometbft` +Running that command will: + + 1. build the local rust code from th elatest version on-disk + 2. generate a genesis file, writing configs to `~/.penumbra/network_data/` + 3. run the locally-built version of `pd` + 4. run `cometbft` alongside `pd`, communicating over ABCI + 5. run a prometheus/grafana [metrics setup](./metrics.md) -To run CometBFT, run - -```shell -cometbft --home ~/.penumbra/network_data/node0/cometbft/ start -``` - -in another terminal window. +You can use the [process-compose] interface to view logs from any individual service. +Use `ctrl+c` to halt the setup, and run `just dev` to start it again from the latest +local source code. ## Running `pcli` + To interact with the chain, configure a wallet pointing at the localhost node: @@ -68,7 +57,10 @@ edit the `genesis.json` to add your address. After making changes, you may want to reset and restart the devnet: ```shell -cargo run --release --bin pd -- testnet unsafe-reset-all +# stop the running node via process-compose: +ctrl+c +# destroy local network state: +cargo run --release --bin pd -- network unsafe-reset-all ``` You'll probably also want to reset your wallet state: @@ -78,14 +70,14 @@ cargo run --release --bin pcli -- --home ~/.local/share/pcli-localhost view rese ``` At this point you're ready to generate new configs, and restart both `pd` and -`cometbft`. The order they're started in doesn't particularly matter for -correctness, because `cometbft` will retry connecting to the ABCI server until -it succeeds. +`cometbft`, which you can do by running `just dev` again. Note that running `just dev` +will _reuse_ any existing state in `~/.penumbra/network_data/`. You must manually `unsafe-reset-all` +to purge that pre-existing config. -## Optional: running smoke-tests - -Once you have a working devnet running, you should be able to run the [smoke tests](https://en.wikipedia.org/wiki/Smoke_testing_(software)) successfully. This can be useful if you are looking to contribute to Penumbra, or if you need to check that your setup is correct. +## Running smoke tests (optional) +Once you have a working devnet running, you should be able to run the [smoke tests](https://en.wikipedia.org/wiki/Smoke_testing_(software)) +successfully. This can be useful if you are looking to contribute to Penumbra, or if you need to check that your setup is correct. To run the smoke tests: 1. Make sure you have a devnet running (see previous steps) @@ -94,8 +86,9 @@ To run the smoke tests: PENUMBRA_NODE_PD_URL=http://127.0.0.1:8080 PCLI_UNLEASH_DANGER=yes cargo test --package pcli -- --ignored --test-threads 1 ``` -Find the exact commands for each binary's smoke tests in `deployments/compose/process-compose-smoke-test.yml`. -You can also run the entire smoke test suite end-to-end via `just smoke`, including setup and teardown of the network. +You can also run the entire smoke test suite with an automatic fullnode. If you do so, +make sure to stop any fullnode running via `just dev`, as they'll conflict. Then run `just smoke`. If you want to execute the tests against an already-running devnet, however, use manual invocations like -the `cargo test` example above. You'll need to install [process-compose](https://github.com/F1bonacc1/process-compose/) -to use the automated setup. +the `cargo test` example above. + +[process-compose]: https://f1bonacc1.github.io/process-compose/launcher/ diff --git a/docs/guide/src/dev/metrics.md b/docs/guide/src/dev/metrics.md index 45597b327d..9d357744db 100644 --- a/docs/guide/src/dev/metrics.md +++ b/docs/guide/src/dev/metrics.md @@ -1,17 +1,7 @@ # Metrics Metrics are an important part of observability, allowing us to understand what -the Penumbra software is doing. Penumbra Labs runs Grafana instances for the public deployments: - - * https://grafana.testnet.penumbra.zone - * https://grafana.testnet-preview.penumbra.zone - -There's a more comprehensive WIP dashboard, gated by basic auth for PL team: - - * https://metrics.penumbra.zone - -Check the usual place for credentials. Eventually those views should be exported -as public references. +the Penumbra software is doing. ## Adding Metrics @@ -69,15 +59,7 @@ we use for maintaining our dashboards. ## Editing metrics locally -To facilitate working with metrics locally, first run a `pd` node on your machine with the metrics endpoint -exposed. Then, you can spin up a metrics sidecar deployment: - -```bash -just metrics -``` - -Note that this setup only works on Linux hosts, due to the use of host networking, so the metrics -containers can reach network ports on the host machine. +A minimal metrics setup will be automatically provisioned as part of the [devnet quickstart](./devnet-quickstart.md). -To add new Grafana visualizations, open http://localhost:3000 and edit the existing dashboards. -When you're happy with what you've got, follow the "Backing up Grafana" instructions above to save your work. +To add new Grafana visualizations, open [http://127.0.0.1:3000](http://127.0.0.1:3000) and edit the existing dashboards. +When you're happy with what you've got, follow the [Backing up Grafana](./metrics.md#backing-up-grafana) instructions above to save your work. diff --git a/flake.lock b/flake.lock index e5c70e0975..bb0806b107 100644 --- a/flake.lock +++ b/flake.lock @@ -7,11 +7,11 @@ ] }, "locked": { - "lastModified": 1714864355, - "narHash": "sha256-uXNW6bapWFfkYIkK1EagydSrFMqycOYEDSq75GmUpjk=", + "lastModified": 1721058578, + "narHash": "sha256-fs/PVa3H5dS1//4BjecWi3nitXm5fRObx0JxXIAo+JA=", "owner": "ipetkov", "repo": "crane", - "rev": "442a7a6152f49b907e73206dc8e1f46a61e8e873", + "rev": "17e5109bb1d9fb393d70fba80988f7d70d1ded1a", "type": "github" }, "original": { @@ -40,11 +40,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1714906307, - "narHash": "sha256-UlRZtrCnhPFSJlDQE7M0eyhgvuuHBTe1eJ9N9AQlJQ0=", + "lastModified": 1720957393, + "narHash": "sha256-oedh2RwpjEa+TNxhg5Je9Ch6d3W1NKi7DbRO1ziHemA=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "25865a40d14b3f9cf19f19b924e2ab4069b09588", + "rev": "693bc46d169f5af9c992095736e82c3488bf7dbb", "type": "github" }, "original": { @@ -64,19 +64,16 @@ }, "rust-overlay": { "inputs": { - "flake-utils": [ - "flake-utils" - ], "nixpkgs": [ "nixpkgs" ] }, "locked": { - "lastModified": 1715134005, - "narHash": "sha256-oujsCgNiQnZoQntNkkNkA7BhCmUvf9FLWj+2oGT2Jvc=", + "lastModified": 1721096425, + "narHash": "sha256-9/58mnoDCyBHsJZwTg3MfgX3kgVqP/SzGMy0WnnWII8=", "owner": "oxalica", "repo": "rust-overlay", - "rev": "a8bfc2569a1965c0da8711d289d973f0011b441a", + "rev": "1c95d396d7395829b5c06bea84fb1dd23169ca42", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index 429d30f421..55edf69204 100644 --- a/flake.nix +++ b/flake.nix @@ -8,7 +8,6 @@ url = "github:oxalica/rust-overlay"; inputs = { nixpkgs.follows = "nixpkgs"; - flake-utils.follows = "flake-utils"; }; }; crane = { @@ -55,12 +54,16 @@ }; filter = path: type: # Retain proving and verification parameters, and no-lfs marker file ... - (builtins.match ".*\.(no_lfs|param||bin)$" path != null) || + (builtins.match ".*\.(no_lfs|param|bin)$" path != null) || # ... as well as all the normal cargo source files: (craneLib.filterCargoSources path type); }; nativeBuildInputs = [ pkg-config ]; - buildInputs = [ clang openssl rocksdb ]; + buildInputs = if stdenv.hostPlatform.isDarwin then + with pkgs.darwin.apple_sdk.frameworks; [clang openssl rocksdb SystemConfiguration CoreServices] + else + [clang openssl rocksdb]; + inherit system PKG_CONFIG_PATH LIBCLANG_PATH ROCKSDB_LIB_DIR; cargoExtraArgs = "-p pd -p pcli -p pclientd"; meta = { @@ -110,12 +113,22 @@ packages = [ cargo-nextest cargo-watch + glibcLocales # for postgres initdb locale support cometbft + grafana + grpcurl just + mdbook + mdbook-katex + mdbook-mermaid + mdbook-linkcheck nix-prefetch-scripts postgresql + process-compose + prometheus protobuf rocksdb + rsync ]; shellHook = '' export LIBCLANG_PATH=${LIBCLANG_PATH} diff --git a/justfile b/justfile index 8ff587ec24..58b5ebafb0 100644 --- a/justfile +++ b/justfile @@ -2,31 +2,32 @@ default: @just --list +# Creates and runs a local devnet with solo validator. Includes ancillary services +# like metrics, postgres for storing ABCI events, and pindexer for munging those events. +dev: + ./deployments/scripts/check-nix-shell && \ + ./deployments/scripts/run-local-devnet.sh \ + --config ./deployments/compose/process-compose-postgres.yml \ + --config ./deployments/compose/process-compose-metrics.yml + # Formats the rust files in the project. fmt: cargo fmt --all +# Render livereload environment for editing the Dev Guide documentation. +guide: + # Access local docs at http://127.0.0.1:3001 + cd docs/guide && \ + mdbook serve -n 127.0.0.1 --port 3001 + # Generate code for Rust & Go from proto definitions. proto: ./deployments/scripts/protobuf-codegen -# Run a local prometheus/grafana setup, in containers, to scrape a local node. Linux only. +# Run a local prometheus/grafana setup, to scrape a local node. metrics: - cd ./deployments/compose/ \ - && docker-compose -f metrics.yml up --build --abort-on-container-exit --force-recreate --remove-orphans - -# Configures and runs a relayer instance between "preview" (latest main) and local devnet on current HEAD -relayer-local-devnet: - ./deployments/scripts/relayer-local-devnet - -local-devnet-generate: - cargo run --release --bin pd -- network generate --chain-id penumbra-devnet-local - -local-devnet-run: - ./deployments/scripts/run-local-devnet.sh - -local-devnet-reset-all: - cargo run --bin pd --release -- network unsafe-reset-all + ./deployments/scripts/check-nix-shell && \ + process-compose --no-server --config ./deployments/compose/process-compose-metrics.yml up --keep-tui # Rebuild Rust crate documentation rustdocs: @@ -34,6 +35,5 @@ rustdocs: # Run smoke test suite, via process-compose config. smoke: - # resetting network state - cargo run --release --bin pd -- network unsafe-reset-all || true + ./deployments/scripts/warn-about-pd-state ./deployments/scripts/smoke-test.sh