Skip to main content

Running Sourcify Locally


  • Node.js v16


First clone the repository

git clone && cd sourcify

Install and Build

Install dependencies

npm install

This will install dependencies for the server (root folder) as well as the UI (ui/ folder) and other packages/ with lerna.

Then build with

npx lerna run build

which will build each of the packages.

Create .env

Make a copy of the environments/ and rename it to environments/.env.

Running the Server

Set Environment Variables

Set the variables below for the file paths. You can also change the other optional environment variables.

REPOSITORY_PATH= # Path on host where verified contracts will be saved e.g. /home/user/sourcify/repository
SOLC_REPO= # Path where Solidity compiler binaries will be saved. e.g. /home/user/solc/linux-amd64
SOLJSON_REPO= # Path where Solidity JS (solc-js) compilers are saved e.g. /home/user/solc/js

You also need to provide either Alchemy API keys or your own JSON-RPC node URL for Ethereum networks. If both provided, it will first query the NODE_URL_{chain} and fall back to Alchemy.

# Custom nodes

For other networks with Alchemy support such as Polygon, Optimism, Arbitrum etc., you also need to provide an API key. You can check those networks in the services/core/src/sourcify-chains.ts. For the chains without an rpc field in sourcify-chains.ts, the default RPCs from in services/core/src/chains.json will be used.

Infura is needed only for the Palm Network and not used for Ethereum, Arbitrum, Optimism, Polygon etc.



Start the server

npm run server:start

Running the UI

Set Environment Variables

Create a copy of ui/.env.development and name it to ui/.env.development.local. Set the environment variables accordingly


REACT_APP_AUTH0 variables are needed for authenticating CREATE2 verification. You can create an account in and enter credentials with the correct callback.


cd ui/
npm start

Running the Repository

The repository ( is a simple web UI on top of the file directory of the verified contracts. It runs a fork of h5ai and is a submodule under the folder /h5ai-nginx in the Sourcify git repo. The origin is at sourcifyeth/h5ai-nginx.

The easiest way to run the contract repository is to directly run the docker container using the docker-compose file environments/repository.yaml.

First, set the environment variables in environments/.env for the container:

# Repository path in the host machine

Make sure the folder exists with mkdir -p /path/to/repo

docker-compose -f environments/repository.yaml up

This will pull and run the ethereum/source-verify:repository-${TAG} docker container from our Docker hub on port REPOSITORY_SERVER_EXTERNAL_PORT.

You can also build your own container by changing the image of the container to a local container build context:

However you need to pull the /h5ai-nginx submodule as the folder will be initially empty:

git submodule update --init --recursive
# environments/repository.yaml
<<: *project-base
# Comment/remove this line
# image: ethereum/source-verify:repository-${TAG}
# Add build fields like below.
context: ../h5ai-nginx # Point to the /h5ai-nginx folder
dockerfile: Dockerfile
container_name: repository-${TAG}

Running the Monitor

To run the monitor:

npm run monitor:start