Skip to content

Latest commit

 

History

History
132 lines (103 loc) · 7.43 KB

BUILD.md

File metadata and controls

132 lines (103 loc) · 7.43 KB
Raw

Official build

The official build should ideally be reproducible, so that independent parties can validate that we really deploy what we claim to deploy.

We try to achieve some level of reproducibility using a Dockerized build environment. The following steps should build the official Wasm image.

Install tools

Mac

  • Brew is a software installer for Mac. Please install it as per the official guide: 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • Bash is a popular shell that we use to execute scripts.
    • Check which version of bash you have installed: 
      bash --version
    • If you have version 5 or newer, your installation is up to date. If you have an old version, such as 3, please upgrade.
  • Git is a distributed version control tool. Please install it with: 
    brew install git
  • Docker is a container environment. It lets you build the nns-dapp code in a sandbox, fairly reliably, and without you having to install a lot of custom tools that you may not trust. Please use one of the official installers.
  • Docker buildx is an extension that makes it easier to compile under docker. buildx is included in the standard docker installer for Mac desktops. If you have installed docker for an os-x server, please follow the official guide.
  • Rosetta allows Mac M1 and M2 processors to run programs that use the AMD64 instruction set. If you have an M1 or M2 CPU, please:
    • Install Rosetta: 
      softwareupdate --install-rosetta
    • Restart your laptop.

Ubuntu Linux

  • Advanced Packaging Manager, also known as apt, is the recommended package manager for Ubuntu. Please ensure that the apt package index is up to date:

    apt-get update

  • Git is a distributed version control tool. Please install it with:

    apt-get install git

  • Docker is a container environment. It lets you build the nns-dapp code in a sandbox, fairly reliably, and without you having to install a lot of custom tools that you may not trust. Please use one of the official installers.

  • Docker buildx is an extension that makes it easier to compile under docker. buildx is included in recent docker releases. You can check whether it is installed with:

    $ docker build --help

Usage:  docker buildx build [OPTIONS] PATH | URL | -
...

    If you do not have buildx installed, please follow the official guide. In particular, to install version 0.10.4 on a x86-64 Linux machine:

    wget https://github.com/docker/buildx/releases/download/v0.10.4/buildx-v0.10.4.linux-amd64
mv buildx-v0.10.4.linux-amd64 docker-buildx
chmod +x docker-buildx
mkdir -p $HOME/.docker/cli-plugins/
mv docker-buildx $HOME/.docker/cli-plugins/

Build

When you have the tools installed, you can build the container with:

  • Get the code 
    git clone https://github.com/dfinity/nns-dapp.git && cd nns-dapp
  • If you would like to build a specific version, e.g. the commit for a specific proposal, please check it out: 
    git checkout THE_COMMIT
  • Verify that docker is running. If not, please start it.
    • Mac: Press cmd+space and enter docker
    • Ubuntu: pgrep docker || sudo systemctl start docker
  • Now you can build: 
    ./scripts/docker-build
  • You can verify that you have the same output as another user with: 
    sha256sum nns-dapp.wasm.gz

The resulting nns-dapp.wasm.gz is ready for deployment as qoctq-giaaa-aaaaa-aaaea-cai, which is the reserved principal for this service.

Our CI also performs these steps; you can compare the SHA256 with the output there, or download the artifact from a release.

TODO: When we make a proposal, we should have a corresponding release that voters can download. E.g. https://github.com/dfinity/nns-dapp/releases/tag/release-candidate exists but it doesn't have build artefacts.

Build flavors

The build creates several different nns-dapp and sns_aggregator Wasms. These builds target specific use cases:

Flavor Description
Production This is the production build deployed to https://nns.ic0.app
Dev This is a build for testing integration with third party canisters. If you wish to include nns-dapp or the sns_aggregator in your CI, this build is designed to make your testing easy and convenient.
Test This is a build for testing internal functionality. If you are changing nns-dapp or sns_aggregator functionality and need to access or modify the internal state of the nns-dapp to test, this is the build for you.
Noassets This is a build of the nns-dapp that does not include web assets. This reduces the size of the Wasm, which may be convenient in some test scenarios. Note that web assets can be uploaded to the nns-dapp after deployment by the canister controller.

TODO: Document how to make the sns_aggregator collect data quickly.

TODO: Document how to create accounts in the nns-dapp.

Development

Development relies on the presence of an environment that is setup with the II, governance, ledger, and cycle minting canisters. This is provided by dfx nns install, both in automated testing and for local development. Please note, however, that it takes some work to configure the NNS canisters. If you would like a test environment with all the NNS canisters configured suitably for use with the nns-dapp, please consider using the snsdemo tools.:

  • Make sure that you have a version of dfx that matches the snsdemo.
  • Create a state snapshot (about 20 minutes): snsdapp$ dfx-snapshot-stock-make --snapshot ~/stock-snsdemo-snapshot.tar.xz
  • Start the snapshot: nns-dapp$ ./scripts/dfx-snapshot-start --snapshot ~/stock-snsdemo-snapshot.tar.xz

You can now access the frontend using Chrome or Firefox (sorry, Safari doesn't support subdomains of localhost):

open "http://$(dfx canister id nns-dapp).localhost:8080"

To work on the UI locally, either use your IDE, or run the following:

cd frontend
npm ci
npm run dev