Skip to content

Latest commit

 

History

History
 
 

marlowe-dashboard-client

README.md

The Marlowe Dashboard is an online simulator for Marlowe Applications.

Getting started

The Marlowe Dashboard is written in PureScript and uses npm and spago for managing dependencies. It talks to the marlowe-dashboard-server which also needs to be up and running during development. The client build also depends on purescript files that are generated by the backend service using purescript-bridge.

Note: The workflow described here relies heavily on Nix. This means you should either be working inside a nix-shell environment or use tools such as lorri or nix-direnv or similar to provide a suitable environment.

Starting the backend server

The Marlowe Dashboard requires a running instance of the PAB to work. First you need to set up the database:

$ plutus-pab-migrate

Next, setup the Marlowe contracts:

$ npm run setup-contracts

This installs the necessary Marlowe contracts on the PAB, and creates a contracts/contracts.json file with links to their nix store paths. This is needed by the frontend application to start instances of these contracts.

Finally, start all the PAB servers:

$ plutus-pab-all-servers

The plutus-pab-migrate and plutus-pab-all-servers scripts are provided by the global shell.nix. The npm setup-contracts script also relies on local scripts provided by default.nix. If these commands are not available, make sure you are in a nix-shell session or that lorri is ready. For additional information on invoking the PAB please refer to its README.md.

Starting the frontend server

With the contracts installed and the PAB server running, you can get started using the npm start script:

$ npm run start

The start script will:

  • Install npm dependencies
  • Generate PureScript bridge code
  • Compile the PureScript code
  • Start the Webpack server

Once the start script completes you can access the frontend via http://localhost:8009.

Development Workflow

The following outlines some essentials for actually working on the marlowe dashboard code.

NPM Scripts

Apart from the start script introduced above there are a few scripts for the most frequent tasks during development. For example, in order to run a webpack server in development mode with automatic reloading use webpack:server:

$ npm run webpack:server

This is the final step of the start script described above, and is all you need to get up and running subsequently if you have already installed the npm modules and generated the PureScript bridge code.

Please refer to package.json for the full set of provided scripts.

Generating PureScript Code

The PureScript build depends on the presence of a ./generated folder with bridge code generated by the backend. This code can be generated by running marlowe-dashboard-generate-purs which is provided by the nix-shell environment.

Managing Dependencies

There are two relevant sources of dependencies that have to be handled and integrated with Nix separately: Javascript(/npm) dependencies and PureScript dependencies.

Managing NPM Dependencies

The Javascript dependencies are handled by npm in package.json (and package-lock.json which is updated by npm automatically).

The npm dependencies are integrated with Nix via npmlock2nix almost completely transparently. Any changes to the lockfile will be picked up npmlock2nix automatically during the nix build. No additional files have to be generated or maintained.

NodeJS GitHub dependencies

In general, npm dependencies are handled by npmlock2nix automatically and transparently. The one exception to this rule are GitHub dependencies. In order for these to work in restricted evaluation mode (which is what hydra uses) you have to specify the sha256 of the dependency you want to use in your buildNodeModules. For example:

buildNodeModules {
    projectDir = ./.;
    packageJson = ./package.json;
    packageLockJson = ./package-lock.json;
    githubSourceHashMap = {
      shmish111.nearley-webpack-loader."939360f9d1bafa9019b6ff8739495c6c9101c4a1" = "1brx669dgsryakf7my00m25xdv7a02snbwzhzgc9ylmys4p8c10x";
    };
}

You can add new dependencies with the sha256 set to "0000000000000000000000000000000000000000000000000000". This will yield an error message during the build with the actual hash value.

Managing PureScript Dependencies

The PureScript dependencies are handled by spago in packages.dhall.

The Nix integration is done using spago2nix. Any changes to the PureScript dependencies require an update of the Nix code generated by spago2nix:

$ spago2nix generate

This will parse the spago configuration and will generate an updated .nix file.

Note: If the spago2nix command is not available make sure you are inside a nix-shell environment or that your lorri session is up and running.

Nix

Building The Client With Nix

You can run the following command (from the repository root) to build the client and the backend server with Nix:

$ nix-build \
  --option trusted-public-keys "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=" \
  --option substituters https://hydra.iohk.io \
  -A marlowe-dashboard.client -A marlowe-dashboard.server-invoker

Note: When building the client make sure that the generated directory is removed completely or you will get Duplicate module errors.