From 970ac0703e5d1858ccb3d4bc5cd7d365ef62a5ed Mon Sep 17 00:00:00 2001 From: Conor Schaefer Date: Tue, 23 Jul 2024 15:44:07 -0700 Subject: [PATCH] fix: use mdx-compatible version interpolation Not quite as smooth as what we had with `mdbook`, but the capability is definitely there: we should be able to write custom JS to do whatever we want with variable interpolation inside codeblocks. A JS pro I am not, however, so I'm punting on that for now. --- pages/dev/{build.md => build.mdx} | 9 ++++-- .../{chain-upgrade.md => chain-upgrade.mdx} | 4 +-- pages/node/pd/install.md | 31 ------------------- pages/node/pd/install.mdx | 12 +++---- pages/node/pd/requirements.md | 2 +- .../pd/{running-node.md => running-node.mdx} | 23 ++++++++------ pages/pcli/install.md | 2 +- penumbra_versions.js | 7 +++++ versions.js | 2 -- 9 files changed, 36 insertions(+), 56 deletions(-) rename pages/dev/{build.md => build.mdx} (93%) rename pages/node/pd/{chain-upgrade.md => chain-upgrade.mdx} (92%) delete mode 100644 pages/node/pd/install.md rename pages/node/pd/{running-node.md => running-node.mdx} (90%) create mode 100644 penumbra_versions.js delete mode 100644 versions.js diff --git a/pages/dev/build.md b/pages/dev/build.mdx similarity index 93% rename from pages/dev/build.md rename to pages/dev/build.mdx index 36fb36d..3dbc7cc 100644 --- a/pages/dev/build.md +++ b/pages/dev/build.mdx @@ -1,3 +1,5 @@ +import { PENUMBRA_VERSION } from '../../penumbra_versions.js'; + 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, @@ -64,11 +66,12 @@ git clone https://github.com/penumbra-zone/penumbra To build the versions of `pcli`, `pd`, etc. compatible with the current testnet, navigate to the `penumbra/` folder, fetch the latest from the repository, and check out the -latest tag for the current -[testnet](https://github.com/penumbra-zone/penumbra/releases): +latest tag from the [releases page](https://github.com/penumbra-zone/penumbra/releases). +Currently, that tag is {PENUMBRA_VERSION}. Substitute that value for `` +below: ```bash -cd penumbra && git fetch && git checkout {{ #include ../penumbra_version.md }} +cd penumbra && git fetch && git checkout ``` If you want to build the most recent version compatible with the "preview" environment, diff --git a/pages/node/pd/chain-upgrade.md b/pages/node/pd/chain-upgrade.mdx similarity index 92% rename from pages/node/pd/chain-upgrade.md rename to pages/node/pd/chain-upgrade.mdx index 0a5c5c1..61ed626 100644 --- a/pages/node/pd/chain-upgrade.md +++ b/pages/node/pd/chain-upgrade.mdx @@ -1,4 +1,4 @@ -# Performing chain upgrades +import {PENUMBRA_VERSION} from '../../../penumbra_versions.js'; When consensus-breaking changes are made to the Penumbra protocol, node operators must coordinate upgrading to the new version of the software @@ -27,7 +27,7 @@ Consider performing a backup as a preliminary step during the downtime, so that your node state is recoverable. 1. Stop both `pd` and `cometbft`. Depending on how you run Penumbra, this could mean `sudo systemctl stop penumbra cometbft`. -2. Download the latest version of `pd` and install it. Run `pd --version` and confirm you see `{{ #include ../../penumbra_version.md }}` before proceeding. +2. Download the latest version of `pd` and install it. Run `pd --version` and confirm you see "{PENUMBRA_VERSION}" before proceeding. 3. Optionally, use `pd export` to create a snapshot of the `pd` state. 4. Apply the migration with `pd migrate --home PD_HOME --comet-home COMETBFT_HOME`. If using the default home locations (from `pd testnet join`), you can omit the paths and just run `pd migrate`. diff --git a/pages/node/pd/install.md b/pages/node/pd/install.md deleted file mode 100644 index dd50472..0000000 --- a/pages/node/pd/install.md +++ /dev/null @@ -1,31 +0,0 @@ -# Installing pd -There are many ways to configure and run Penumbra. The easiest is to download -binaries for `pd` and `cometbft` on a Linux system. For alternatives, see -[deployment strategies](./requirements.md#deployment-strategies). -If you want a detailed guide, see the [tutorial on running a node](../../tutorials/running-node.md). - -## Quickstart -Download prebuilt binaries from the [Penumbra releases page on Github](https://github.com/penumbra-zone/penumbra/releases). -Make sure to use the most recent version available, as the version of `pd` must -match the software currently running on the network, to choose the correct platform for your machine. - -After downloading the `.tar.gz` file, extract it, and copy its contents to your `$PATH`. For example: - -``` -curl -sSfL -O https://github.com/penumbra-zone/penumbra/releases/download/{{ #include ../../penumbra_version.md }}/pd-x86_64-unknown-linux-gnu.tar.gz -tar -xf pd-x86_64-unknown-linux-gnu.tar.gz -sudo mv pd-x86_64-unknown-linux-gnu/pd /usr/local/bin/ - -# confirm the pd binary is installed by running: -pd --version -``` - -There's also a one-liner install script available on the release page, which will install `pd` to `$HOME/.cargo/bin/`. - -### Installing CometBFT - -You'll need to have [CometBFT installed](https://docs.cometbft.com/v0.37/guides/install) on your system to join your node to the testnet. -You must use a compatible version of CometBFT. Any version in the `v0.37.x` series will work, such as `{{ #include ../../cometbft_version.md }}`, -which you can download [from the CometBFT releases page](https://github.com/cometbft/cometbft/releases/tag/{{ #include ../../cometbft_version.md }}). -If you prefer to compile from source instead, make sure you are compiling the correct version by checking out its tag -in the CometBFT repo before building. diff --git a/pages/node/pd/install.mdx b/pages/node/pd/install.mdx index b7bd7b5..23c2403 100644 --- a/pages/node/pd/install.mdx +++ b/pages/node/pd/install.mdx @@ -1,4 +1,4 @@ -import { PENUMBRA_VERSION, COMETBFT_VERSION } from '../../../versions.js'; +import { PENUMBRA_VERSION, COMETBFT_VERSION } from '../../../penumbra_versions.js'; # Installing pd There are many ways to configure and run Penumbra. The easiest is to download @@ -13,21 +13,21 @@ match the software currently running on the network, to choose the correct platf After downloading the `.tar.gz` file, extract it, and copy its contents to your `$PATH`. For example: -``` -curl -sSfL -O https://github.com/penumbra-zone/penumbra/releases/download/v0.79.2/pd-x86_64-unknown-linux-gnu.tar.gz +```shell +curl -sSfL -O https://github.com/penumbra-zone/penumbra/releases/latest/download/pd-x86_64-unknown-linux-gnu.tar.gz tar -xf pd-x86_64-unknown-linux-gnu.tar.gz sudo mv pd-x86_64-unknown-linux-gnu/pd /usr/local/bin/ # confirm the pd binary is installed by running: pd --version ``` - +Make sure the version that's installed is at least {PENUMBRA_VERSION}. There's also a one-liner install script available on the release page, which will install `pd` to `$HOME/.cargo/bin/`. ### Installing CometBFT You'll need to have [CometBFT installed](https://docs.cometbft.com/v0.37/guides/install) on your system to join your node to the testnet. -You must use a compatible version of CometBFT. Any version in the `v0.37.x` series will work, such as `v0.37.9`, -which you can download [from the CometBFT releases page](https://github.com/cometbft/cometbft/releases/tag/v0.37.9). +You must use a compatible version of CometBFT. Any version in the `v0.37.x` series will work, such as {COMETBFT_VERSION}, +which you can download [from the CometBFT releases page](https://github.com/cometbft/cometbft/releases/). If you prefer to compile from source instead, make sure you are compiling the correct version by checking out its tag in the CometBFT repo before building. diff --git a/pages/node/pd/requirements.md b/pages/node/pd/requirements.md index be68bd9..00b2f5b 100644 --- a/pages/node/pd/requirements.md +++ b/pages/node/pd/requirements.md @@ -83,7 +83,7 @@ declaration. Node operators should set this value system-wide, by editing `/etc/ We expect node operators to manage the lifecycle of their Penumbra deployments. Some example configs for systemd can be found in the Penumbra repo's -[`deployments/`](https://github.com/penumbra-zone/penumbra/tree/{{ #include ../../penumbra_version.md }}/deployments) directory. +[`deployments/`](https://github.com/penumbra-zone/penumbra/tree/main/deployments) directory. Other community solutions include: * [Cosmos Operator] by [Strangelove] for Kubernetes diff --git a/pages/node/pd/running-node.md b/pages/node/pd/running-node.mdx similarity index 90% rename from pages/node/pd/running-node.md rename to pages/node/pd/running-node.mdx index 0aa2272..f57c262 100644 --- a/pages/node/pd/running-node.md +++ b/pages/node/pd/running-node.mdx @@ -1,3 +1,5 @@ +import {PENUMBRA_VERSION} from '../../../penumbra_versions.js'; + In order to interact with the Penumbra network, users must provide an RPC URL so that client software can read chain state and submit transactions. This is true of the [Prax wallet], and of [pcli], as well as any other client. @@ -17,7 +19,7 @@ then request a dedicated hardware server. While preparing the server request, you'll need to provide an SSH public key for the root user account. You can use this command to generate one if you don't have one already: -``` +```shell ssh-keygen -t ed25519 cat ~/.ssh/id_ed25519.pub ``` @@ -35,22 +37,23 @@ using the IP address displayed on the server page for Hetzner. Log into the server like so: -``` +```shell ssh -l root ``` If that command fails, you'll need to debug your access settings. -First, clone the git repository: +First, clone the git repository, and check out a specific tag: {PENUMBRA_VERSION}. +Replace `` in the command below with that version: -``` +```shell apt-get install -y git git-lfs -git clone --branch {{ #include ../penumbra_version.md }} https://github.com/penumbra-zone/penumbra +git clone --branch https://github.com/penumbra-zone/penumbra ``` Use that repo to copy the service configurations into place: -``` +```shell cd penumbra/deployments/systemd/ cp penumbra.service cometbft.service /etc/systemd/system/ # edit /etc/systemd/system/penumbra.service, @@ -59,18 +62,18 @@ systemctl daemon-reload ``` Follow the guide to [install pd and cometbft](../node/pd/install.md) from their respective -release pages. You should be able to run `pd --version` and see `{{ #include ../penumbra_version.md }}` +release pages. You should be able to run `pd --version` and see {PENUMBRA_VERSION} displayed. Next, create a user account for running the Penumbra software: -``` +```shell sudo useradd -m -d /home/penumbra penumbra -s /bin/bash ``` We'll use this account to configure the `pd` and `cometbft` data directories. -``` +```shell sudo su -l penumbra pd network join \ --moniker \ @@ -86,7 +89,7 @@ other peers on the network can initiate connections to it, to share blocks. ## Running the node Finally, start the services: -``` +```shell # return to root user exit systemctl restart penumbra cometbft diff --git a/pages/pcli/install.md b/pages/pcli/install.md index c1913fb..a971aca 100644 --- a/pages/pcli/install.md +++ b/pages/pcli/install.md @@ -5,7 +5,7 @@ match the software currently running on the network. Make sure choose the correct platform for your machine. Or, you can use a one-liner install script: ```shell -curl --proto '=https' --tlsv1.2 -LsSf https://github.com/penumbra-zone/penumbra/releases/download/{{ #include ../penumbra_version.md }}/pcli-installer.sh | sh +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/penumbra-zone/penumbra/releases/latest/download/pcli-installer.sh | sh # confirm the pcli binary is installed by running: pcli --version diff --git a/penumbra_versions.js b/penumbra_versions.js new file mode 100644 index 0000000..5f883d3 --- /dev/null +++ b/penumbra_versions.js @@ -0,0 +1,7 @@ +// Ideally we'd be able to import these constants and reuse them throughout the docs, +// similar to how we imported markdown snippets in mdbook. With MDX, importing +// works in normal prose, but fails in backticked-codeblocks. There's some discussion +// about how to do this better in https://github.com/orgs/mdx-js/discussions/2288. + +export const PENUMBRA_VERSION = 'v0.79.2'; +export const COMETBFT_VERSION = 'v0.37.9'; diff --git a/versions.js b/versions.js deleted file mode 100644 index 94db79c..0000000 --- a/versions.js +++ /dev/null @@ -1,2 +0,0 @@ -export const PENUMBRA_VERSION = 'v0.79.1'; -export const COMETBFT_VERSION = 'v0.37.9';