HACKING.md

Hacking

This document explains how to build the Wasm module of the Internet Identity canister from scratch.

💡 Binary releases are available on the release page.

💡 The simplest way to build the code is to use the Docker build.

💡 Make sure to read up on the build features and flavors.

The build requires the following dependencies:

• dfx version 0.10.0 or later
• Rustup with target wasm32-unknown-unknown (see rustup instructions), which can be installed by running ./scripts/bootstrap
• CMake
• ic-wasm, which can be installed by running ./scripts/bootstrap
• Node.js v16+

NOTE! If you're only going to hack on the HTML and CSS code, see the showcase section.

Running Locally

To run the internet_identity canisters, proceed as follows after cloning the repository

npm ci
dfx start [--clean] [--background]

In a different terminal, run the following command to install the Internet Identity canister:

II_FETCH_ROOT_KEY=1 dfx deploy --no-wallet

Then the canister can be used as

$ dfx canister call internet_identity init_salt
()
$ echo $?
0

See dfx canister call --help and the documentation for more information.

The dfx executable can proxy queries to the canister. To view it, run the following and open the resulting link in your browser:

echo "http://localhost:4943?canisterId=$(dfx canister id internet_identity)"

Building the frontend

The fastest workflow to get the development environment running is to deploy once with

npm ci
dfx start [--clean] [--background]
II_FETCH_ROOT_KEY=1 dfx deploy --no-wallet

To serve the frontend locally (recommended during development), run the following:

npm run dev

Then open http://localhost:5173 in your browser. The page is reloaded whenever you save changes to files. To ensure your changes pass our formatting and linter checks, run the following command:

npm run format && npm run lint

Finally, to test workflows like authentication from a client application, you start the Selenium test app:

cd demos/selenium-test-app
npm ci
npm run dev

Then open http://localhost:8081 in your browser.

Make sure that the "Identity Provider" is set to "http://localhost:5173" if you serve the Internet Identity frontend locally.

NOTE on testing on LAN:

If you are testing on LAN -- for instance, connecting to an Internet Identity server running on your laptop from your smartphone over WiFi -- you may run into the following issues:

• The webpage may not be accessible on LAN. By default the development server will serve the content using the localhost host. Firewall rules for localhost are somewhat strict; if you cannot access the page from devices on your LAN try serving with npm run host.
• Internet Identity may tell you that your browser is not supported. The reason for this is that some security-focused features are only enabled on https and localhost pages. A workaround is to use ngrok to forward your local port over https.

Test suites

We have a set of Selenium tests that run through the various flows. To set up a local deployment follow the steps in docker-test-env/README.md. The tests can be executed by running:

npm run test:e2e

Or with a specific screen size e.g.:

npm run test:e2e-desktop

We autoformat our code using prettier. Running npm run format formats all files in the frontend. If you open a PR that isn't formatted according to prettier, CI will automatically add a formatting commit to your PR.

We use eslint to check the frontend code. You can run it with npm run lint, or set up your editor to do it for you.

Building the backend

The Internet Identity backend is a Wasm canister implemented in Rust and built from the internet_identity cargo package (src/internet_identity).

Run the following command in the root of the repository to execute the test suites of all the libraries:

cargo test

The backend canister is also used to serve the frontend assets. This creates a dependency between the frontend and the backend. So running the usual cargo build --target wasm32-unknown-unknown -p internet_identity might not work or include an outdated version of the frontend.

Use the following command to build the backend canister Wasm file instead:

dfx build internet_identity

This will produce ./internet_identity.wasm.gz.

Showcase

The simplest way to make visual changes (HTML & CSS, and non-flow JS) is to start the showcase:

npm run showcase

This will start a webserver showcasing most II pages & components. The showcase can also be built:

npm run build:showcase [--base 'some-base/']
npm run preview:showcase [--base 'some-base/']