diff --git a/pages/frontend/cuiloa.mdx b/pages/frontend/cuiloa.mdx index 1123206..315035e 100644 --- a/pages/frontend/cuiloa.mdx +++ b/pages/frontend/cuiloa.mdx @@ -1,7 +1,87 @@ -import { Callout, Steps } from 'nextra/components' - # Cuiloa - -This section is incomplete. You can help by expanding it! - +[Cuiloa] is a block explorer for navigating and inspecting data on [Penumbra]. While Penumbra is a fully private +proof-of-stake network, Cuiloa allows you to explore the *public* facets of the Penumbra chain. Beyond just blocks and +transactions, Cuiloa lets you explore staking, governance, and DEX activity along with Penumbra's cross-chain +interactions via the Inter-Blockchain Communication (IBC) interoperability protocol, including established IBC clients +running on Penumbra and recent IBC packets. + +## Deployment + +Assuming you have cloned and entered the repository... + +### Docker + +For a dev instance of Cuiloa, a docker compose file is provided. Simply run: + +```sh +docker compose up +``` + +Then navigate to http://localhost:3000 to view a development instance of the app. + +Cuiloa will soon have a production ready image that can be deploy in a standard docker (or podman) workflow. Until +then, please checkout manual configuration below. + +### Manual Deployment + +In addition to a local Penumbra Node and configured CometBFT indexer (more on that below), you will need to have +recent version of `node`, `npm`, and `postgresql` installed on the machine you are building and running Cuiloa. + +#### PostgreSQL + +With a modern version of PostgreSQL, create a database and initialize it with the schema file provided by `cometbft` +[here](https://github.com/cometbft/cometbft/blob/main/state/indexer/sink/psql/schema.sql). Assuming you've created +a database `$DB_NAME` and you have user permissions for the database, You can load a schema file using `psql` with the +following command: + +```sh +psql -d $DB_NAME -f schema.sql +``` + +This will be our indexer that the block explorer uses for accessing information on blocks, events, and transactions +that occur on the chain. + +With the database initialized, create an .env file with the database's URI, i.e.: +```sh .env +DATABASE_URL="postgresql://DB_USER:DB_PASSWORD@localhost:DB_PORT/DB_NAME?sslmode=disable" +``` + +You will also need this information for the `config.toml` file that `cometbft` will be initialized with when creating +your own full node. More on that below. + +#### Penumbra + +You need to have a full node setup with penumbra (including `cometbft`) as detailed +[here](https://guide.penumbra.zone/node/pd/join-network). Alternatively, you can configure a full node on a devnet as +explained [here](https://guide.penumbra.zone/main/dev/devnet-quickstart.html). **In either case**, you need to modify +the `config.toml` file that is created by `pd` after generating your configuration files. + +`config.toml` should be found under `$HOME/.penumbra/network_data/node0/cometbft/config/`. In this file, there is a +heading `[tx_index]` with the configuration variable of `indexer = "kv"`. Using the URI of the database you created +with PostgreSQL from the previous section, you need to update the section under `[tx_index]` to the following: + +```toml +[tx_index] +indexer = "psql" +psql-conn = "$YOUR_DB_URI_HERE" +``` +After you have updated this file, you should start the full node as instructed by the Penumbra guide. If everything was +configured correctly, you should be able to open the database and inspect for Block and Transaction events. If there is +no data, check the logs for `cometbft` for any errors with inserting data into the indexer. + +#### Building Cuiloa + +If you are only interested in running a development version of Cuiloa, you can simply run `npm run dev` at this point +and head to `localhost:3000` to view the application. + +For a production build, ensure that the `output` option in `next.config.js` is either commented out or deleted +**unless** you are building Cuiloa for an optimized image. If you are planning on running Cuiloa as an image, you need +to follow NextJS's [instructions](https://nextjs.org/docs/pages/api-reference/next-config-js/output#automatically-copying-traced-files) +for correctly building and copying over its dependencies. + +Assuming you are using a normal build on your machine, you can now run `npm run build && npm run start`. If everything +has been configured correctly, you can visit `localhost:3000` to view your local production release of Cuiloa. + +[Cuiloa]: https://github.com/penumbra-zone/cuiloa +[Penumbra]: https://penumbra.zone