docs: add quickstart docs for dev env

Adds a nix config so that tooling like `pnpm` is available immediately.
Fleshes out the documentation around connecting to managed database
instances, since merge of #56.

.gitignore

@@ -39,4 +39,7 @@ yarn-error.log*
 /dist
 .vercel
 
-tsconfig.tsbuildinfo
+tsconfig.tsbuildinfo
+
+# ignore database CA certificate, required for some db backends
+ca-cert.pem

README.md

@@ -4,26 +4,40 @@ A DEX explorer for [Penumbra](https://penumbra.zone/).
 
 ## Getting Started
 
-TK. Although the docs at https://github.com/penumbra-zone/cuiloa may be useful.
+The application is written in [NextJS], and uses [pnpm] for package management.
+The fastest way to get started on the development environment is to use [Nix]:
 
-### Penumbra node setup
+```shell
+sh <(curl -L https://nixos.org/nix/install)
+nix develop
+just dev
+```
+
+However, you still need a database to connect to.
 
-You need to have a full node setup with penumbra (including `cometbft`) as detailed [here for testnets](https://guide.penumbra.zone/main/pd/join-testnet.html#joining-a-testnet).
-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.
+## Connecting to a database
 
-`config.toml` should be found under `$HOME/.penumbra/testnet_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:
+The DEX explorer application requires a PostgreSQL database containing ABCI event information
+[as emitted by a Penumbra node](https://guide.penumbra.zone/node/pd/indexing-events).
+You can set up a local devnet by following the [Penumbra devnet quickstart guide](https://guide.penumbra.zone/dev/devnet-quickstart),
+or plug in credentials for an already running database via environment variables:
 
-```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.
+# add these to e.g. `.envrc`:
+export PENUMBRA_GRPC_ENDPOINT="https://testnet.plinfra.net"
+export PENUMBRA_INDEXER_ENDPOINT="postgresql://<PGUSER>:<PGPASS>@<PGHOST>:<PGPORT>/<PGDATABASE>?sslmode=require""
+export NEXT_PUBLIC_CHAIN_ID="penumbra-testnet-phobos-2"
+# optional: if you see "self-signed certificate in certificate chain" errors,
+# you'll likely need to export a `ca-cert.pem` file for the DB TLS.
+# export PENUMBRA_INDEXER_CA_CERT="$(cat ca-cert.pem)"
+```
+
+If you see an error `self-signed certificate in certificate chain`, then you'll need to:
 
+  1. obtain the CA certificate file for the backend database you're connecting to, and export it as `PENUMBRA_INDEXER_CA_CERT`.
+  2. _remove_ the `sslmode=require` string on the `PENUMBRA_INDEXER_ENDPOINT` var.
+
+See context in #55. After configuring that information, run `just dev` again in the nix shell, and you should have events visible.
 
 ## Deployment
 
@@ -42,6 +56,9 @@ you'll want to set are:
 
 It'd be nice to have a cool name for the DEX explorer. We don't have one yet.
 
-
 ## Proto Generation
 Using https://buf.build/penumbra-zone/penumbra/sdks/main
+
+[NextJS]: https://nextjs.org/
+[pnpm]: https://pnpm.io/
+[Nix]: https://nixos.org/download/

flake.nix

@@ -0,0 +1,24 @@
+{
+  description = "Dev shell for Penumbra DEX explorer web application";
+  # inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+  inputs.flake-utils.url = "github:numtide/flake-utils";
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let pkgs = nixpkgs.legacyPackages.${system}; in
+      {
+        devShells.default = pkgs.mkShell {
+          name = "devShell";
+          nativeBuildInputs = [ pkgs.bashInteractive ];
+          buildInputs = with pkgs; [
+            fd
+            file
+            jq
+            just
+            pnpm
+            postgresql
+          ];
+        };
+      });
+}

justfile

@@ -1,6 +1,11 @@
 # A justfile for dex-explorer development.
 # Documents common tasks for local dev.
 
+# run the app locally with live reload, via pnpm
+dev:
+  pnpm install
+  pnpm dev
+
 # build container image
 container:
   podman build -f Containerfile .