self-host-sorucify-service.md

Self-Hosting Sourcify for Custom Chains

I initially followed the guide here: https://docs.sourcify.dev/docs/running-server.

I encountered some issues so I'm writing this guide based off-of the original one.

Prerequisites

• PostgreSQL 16+
• Node.js LTS
• Docker
• Chain RPC + Chain Configuration info

---

Step 1: Fork the Repository

# Fork https://github.com/argotorg/sourcify to your org
# Then clone your fork
git clone https://github.com/YOUR_ORG/sourcify.git
cd sourcify

# Initialize submodules (required for database schema)
git submodule update --init --recursive

---

Step 2: Configure Your Chain

2.1 Edit services/server/src/sourcify-chains.json

This file defines which chains your instance supports. Replace the contents with your chain(s):

{
  "YOUR_CHAIN_ID": {
    "sourcifyName": "Your Chain Name",
    "supported": true,
    "rpc": [
      {
        "type": "FetchRequest",
        "url": "https://your-rpc-endpoint.com",
        "headers": [
          {
            "headerName": "Authorization",
            "headerEnvName": "YOUR_CHAIN_RPC_AUTH"
          }
        ]
      }
    ]
  }
}

RPC Configuration Options:

// Simple RPC (no auth)
"rpc": ["https://public-rpc.example.com"]

// Authenticated RPC (header from env var)
"rpc": [
  {
    "type": "FetchRequest",
    "url": "https://private-rpc.example.com",
    "headers": [
      {
        "headerName": "Authorization",
        "headerEnvName": "MY_RPC_AUTH_ENV_VAR"
      }
    ]
  }
]

// Multiple RPCs (fallback)
"rpc": [
  "https://primary-rpc.example.com",
  "https://backup-rpc.example.com"
]

2.2 Edit services/server/src/chains.json

Add your chain's metadata:

[
  {
    "name": "Your Chain Name",
    "title": "Your Chain Name",
    "chain": "YOURCHAIN",
    "icon": "yourchain",
    "rpc": ["https://your-rpc-endpoint.com"],
    "faucets": [],
    "nativeCurrency": { "name": "ETH", "symbol": "ETH", "decimals": 18 },
    "infoURL": "https://yourchain.com",
    "shortName": "yourchain",
    "chainId": YOUR_CHAIN_ID,
    "networkId": YOUR_CHAIN_ID,
    "explorers": [
      {
        "name": "Your Explorer",
        "url": "https://explorer.yourchain.com",
        "standard": "EIP3091"
      }
    ]
  }
]

2.3 (Optional) Customize API Documentation

Edit services/server/src/openapi.yaml:

• Update info.title and info.description
• Update servers with your deployment URL
• Update info.contact with your org info

---

Step 3: Configure CORS (Optional)

Edit services/server/src/config/production.js to add your frontend domains:

corsAllowedOrigins: [
  /^https?:\/\/(?:.+\.)?yourdomain\.com$/,
  /^https?:\/\/.*\.your-platform\.app$/,
],

---

Step 4: Set Up PostgreSQL Database

4.1 Create Database

# Connect to PostgreSQL
psql -U postgres

# Create database and user
CREATE DATABASE sourcify;
CREATE USER sourcify WITH ENCRYPTED PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE sourcify TO sourcify;

# Connect to the new database and grant schema permissions
\c sourcify
GRANT ALL ON SCHEMA public TO sourcify;

4.2 Run Migrations

cd services/database

# Initialize git submodule for database schema
git submodule update --init

# Set DATABASE_URL and run migrations
export DATABASE_URL="postgresql://sourcify:your-password@your-db-host:5432/sourcify?sslmode=require"
npm install
npm run migrate:up

Migration Notes:

• Migrations must complete before the server starts
• The database-specs submodule contains the Verifier Alliance schema
• Sourcify-specific migrations are in services/database/migrations/

---

Step 5: Environment Variables

Create these environment variables in your deployment platform:

Required Variables

Variable	Description	Example
SOURCIFY_POSTGRES_HOST	Database hostname	db.example.com
SOURCIFY_POSTGRES_PORT	Database port	5432
SOURCIFY_POSTGRES_DB	Database name	sourcify
SOURCIFY_POSTGRES_USER	Database username	sourcify
SOURCIFY_POSTGRES_PASSWORD	Database password	your-secure-password
NODE_ENV	Environment	production
PORT	Server port	5555
SESSION_SECRET	Random string for sessions	generate-random-32-char-string

Optional Variables

Variable	Description	Example
SOURCIFY_POSTGRES_SSL	Enable SSL	true
SOURCIFY_POSTGRES_SSL_REJECT_UNAUTHORIZED	Reject self-signed certs	false
YOUR_CHAIN_RPC_AUTH	RPC auth header (matches headerEnvName)	Basic base64creds
NODE_LOG_LEVEL	Logging level	info or debug
SERVER_URL	Public URL of your server	https://sourcify.yourcompany.com
RPC_TIMEOUT	RPC request timeout (ms)	10000

---

Step 6: Build and Deploy

Option A: Docker Deployment (Recommended)

# Build from repository root
docker build -f services/server/Dockerfile -t your-registry/sourcify-server:latest .

# Push to your registry
docker push your-registry/sourcify-server:latest

Docker Run Command:

docker run -d \
  -p 5555:5555 \
  -e SOURCIFY_POSTGRES_HOST=your-db-host \
  -e SOURCIFY_POSTGRES_PORT=5432 \
  -e SOURCIFY_POSTGRES_DB=sourcify \
  -e SOURCIFY_POSTGRES_USER=sourcify \
  -e SOURCIFY_POSTGRES_PASSWORD=your-password \
  -e NODE_ENV=production \
  -e PORT=5555 \
  -e SESSION_SECRET=your-session-secret \
  -e YOUR_CHAIN_RPC_AUTH="Basic your-auth-header" \
  your-registry/sourcify-server:latest

Option B: Direct Node.js Deployment

# Install dependencies
npm ci

# Build all packages
npx lerna run build

# Start server
cd services/server
npm start

---

Step 7: Health Check and Verification

7.1 Verify Server is Running

curl https://your-sourcify-url/health
# Expected: "Alive and kicking!"

curl https://your-sourcify-url/chains
# Expected: JSON array with your chain(s)

7.2 Test Contract Verification

# Using v2 API (recommended)
curl -X POST "https://your-sourcify-url/v2/verify/YOUR_CHAIN_ID/0xYourContractAddress" \
  -F "[email protected]" \
  -F "compilerVersion=0.8.20+commit.a1b79de6"

Important: The compilerVersion must include the full commit hash. Get the exact version from:

curl https://binaries.soliditylang.org/bin/list.json | jq '.releases'

---

Troubleshooting

Database Connection Errors

Error: Database connection lost

• Verify all SOURCIFY_POSTGRES_* env vars are set
• Check database is accessible from server (firewall rules, VPC, etc.)
• For cloud databases, ensure SSL settings match (SOURCIFY_POSTGRES_SSL)

Compiler Download Issues

Compilers are downloaded on-demand to /tmp/solc-bin/. Ensure:

• Server has internet access to https://binaries.soliditylang.org/
• /tmp has sufficient disk space (each compiler is ~10-15MB)

Build Failures

If git rev-parse HEAD fails in CI/CD:

• The prebuild script has a fallback, but ensure your build copies .git or the fallback works

---

API Reference

V2 API (Recommended)

Endpoint	Method	Description
/v2/verify/{chainId}/{address}	POST	Verify a contract
/v2/verify/{verificationId}	GET	Check verification status
/v2/contract/{chainId}/{address}	GET	Get verified contract
/v2/contracts/{chainId}	GET	List verified contracts

V1 API (Legacy)

Endpoint	Method	Description
/verify	POST	Verify a contract
/files/{chain}/{address}	GET	Get source files
/check-by-addresses	GET	Check verification status

Full API documentation available at /api-docs after deployment.

---

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Sourcify Server                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   API v1    │  │   API v2    │  │  Verification       │  │
│  │  (Legacy)   │  │(Recommended)│  │  Worker Pool        │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│                          │                    │             │
│                          ▼                    ▼             │
│                 ┌─────────────────────────────────┐         │
│                 │      Storage Service            │         │
│                 │  (PostgreSQL + optional S3)     │         │
│                 └─────────────────────────────────┘         │
└─────────────────────────────────────────────────────────────┘
           │                              │
           ▼                              ▼
    ┌─────────────┐               ┌─────────────┐
    │ PostgreSQL  │               │  Your RPC   │
    │  Database   │               │  Endpoint   │
    └─────────────┘               └─────────────┘

Loading

---

Maintenance

Updating Sourcify

# Fetch upstream changes
git fetch upstream
git merge upstream/main

# Update submodules
git submodule update --init --recursive

# Run new migrations
cd services/database
npm run migrate:up

# Rebuild and redeploy

---