Skip to main content

Running Sourcify Locally


  • Node.js v16


First clone the repository

git clone && cd sourcify

Install and Build

Install server dependencies

npm install

Install all modules with lerna

npx lerna bootstrap

And build

npx lerna run build

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 custom JSON-RPC and fall back to Alchemy.

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 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.


For Ethereum chains JSON-RPC URLs:

# Custom nodes


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



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.

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:

# 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}

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

git submodule update --init --recursive

Running the Monitor

To run the monitor:

npm run monitor:start