Barge Integration

Using Barge allows you to run all Ocean Protocol components locally for development and testing. This is recommended for advanced users who need full control over the development environment.

If you’re new to the AgrospAI Data Space Portal, we recommend starting with remote networks before setting up Barge. See the Local Development Setup guide first.

What is Barge?

Barge is a Docker Compose setup that runs all Ocean Protocol components locally:

Ganache - Local Ethereum network
Aquarius - Metadata cache and search
Provider - Data service provider
The Graph - Indexing and querying
Subgraph - Ocean Protocol subgraph

Prerequisites

Before setting up Barge, ensure you have:

Docker and Docker Compose installed
Git for cloning repositories
Node.js 20 (as specified in .nvmrc)
The AgrospAI portal repository cloned and dependencies installed

Barge requires significant system resources. Ensure you have at least 8GB RAM available for Docker.

Setup Instructions

Clone Barge Repository

Clone the Barge repository in a separate directory:

git clone [email protected]:oceanprotocol/barge.git
cd barge

Start Ocean Components

Start Barge with local Ganache and The Graph nodes:

./start_ocean.sh --with-thegraph

This will take several minutes as it:

Pulls Docker images
Starts all services
Deploys contracts to Ganache
Indexes the subgraph

Wait for the process to complete. You’ll see output indicating all services are running.

Import Contract Artifacts

After Barge completes deployment, import the contract addresses to your portal:

cd /path/to/market
npm run set-barge-env

This script:

Reads deployed contract addresses from Barge
Sets environment variables in your .env file
Configures endpoints for local services

Update Chain Configuration

Add Ganache’s chain ID to the supported chains list in app.config.js:

app.config.js

module.exports = {
  // ... other config
  chainIdsSupported: [
    1, // Ethereum Mainnet
    5, // Goerli
    8996, // Barge Ganache - Add this line
    // ... other chains
  ]
}

Start the Portal

Start the development server:

npm start

The portal will now connect to your local Barge components at http://localhost:8000.

macOS-Specific Configuration

On macOS, additional network configuration is required due to Docker networking constraints.

Provider URL Configuration

Update Provider URL for macOS

On macOS, replace Barge’s internal IP with 127.0.0.1 for provider access:Option 1: Environment Variable (Recommended)

.env

NEXT_PUBLIC_PROVIDER_URL="http://127.0.0.1:8030"

Option 2: Code ModificationIn src/@utils/provider.ts, update all methods that call ProviderInstance:

src/@utils/provider.ts

const providerUrl = '127.0.0.1:8030' // Override for macOS

// Apply to methods:
// - getEncryptedFiles
// - getFileDidInfo
// - downloadFile
// etc.

Also update:

src/@utils/nft.ts in setNFTMetadataAndTokenURI and setNftMetadata
src/components/Publish/index.tsx in the encrypt method

Service Endpoint Configuration

Update Subgraph and Metadata Cache URLs for macOS

Replace internal Docker IPs with localhost:

.env

# Subgraph - Use 127.0.0.1 instead of 172.15.0.15
NEXT_PUBLIC_SUBGRAPH_URI="http://127.0.0.1:9000/subgraphs/name/oceanprotocol/ocean-subgraph"

# Metadata Cache - Use 127.0.0.1 instead of 172.15.0.5
NEXT_PUBLIC_METADATACACHE_URI="http://127.0.0.1:5000"

# Provider
NEXT_PUBLIC_PROVIDER_URL="http://127.0.0.1:8030"

# RPC
NEXT_PUBLIC_RPC_URI="http://127.0.0.1:8545"

Environment Variables

After running npm run set-barge-env, your .env file will include:

.env

# Barge Development Configuration
NEXT_PUBLIC_MARKET_DEVELOPMENT='true'

# Contract Addresses (auto-generated from Barge)
NEXT_PUBLIC_NFT_FACTORY_ADDRESS='0x...'
NEXT_PUBLIC_OPF_COMMUNITY_FEE_COLECTOR='0x...'
NEXT_PUBLIC_FIXED_RATE_EXCHANGE_ADDRESS='0x...'
NEXT_PUBLIC_DISPENSER_ADDRESS='0x...'
NEXT_PUBLIC_OCEAN_TOKEN_ADDRESS='0x...'

# Local Service Endpoints
NEXT_PUBLIC_PROVIDER_URL="http://172.15.0.4:8030"
NEXT_PUBLIC_SUBGRAPH_URI="http://172.15.0.15:8000/subgraphs/name/oceanprotocol/ocean-subgraph"
NEXT_PUBLIC_METADATACACHE_URI="http://172.15.0.5:5000"
NEXT_PUBLIC_RPC_URI="http://127.0.0.1:8545"

On macOS, replace the internal Docker IPs (172.15.0.x) with 127.0.0.1 as described above.

MetaMask Integration

To interact with the local Ganache network through the portal:

Import Test Account

When Ganache starts, it prints private keys for test accounts. Each account has 100 test ETH.Example private key:

0xc594c6e5def4bab63ac29eed19a134c130388f74f019bc74b8f4389df2837a58

Import this into MetaMask:

Open MetaMask
Click account icon → Import Account
Paste private key
Click Import

Add Ganache Network

Add the local Ganache network to MetaMask:

Field	Value
Network Name	Ganache Local
RPC URL	http://127.0.0.1:8545
Chain ID	8996
Currency Symbol	ETH

Switch Network

Switch MetaMask to the Ganache Local network to interact with your local environment.

Never use Ganache private keys on real networks! These keys are public and for development only.

Common Barge Commands

# Start with all components
./start_ocean.sh --with-thegraph

# Stop all services
docker-compose down

# Stop and remove volumes (clean slate)
docker-compose down -v

# View logs for all services
docker-compose logs -f

# View logs for specific service
docker-compose logs -f aquarius

# Restart a specific service
docker-compose restart provider

Switching Back to Remote Networks

When you want to connect to remote networks again:

Comment Out Barge Variables

Edit your .env file and comment out or remove the Barge-specific variables:

.env

# Comment out these lines:
# NEXT_PUBLIC_MARKET_DEVELOPMENT='true'
# NEXT_PUBLIC_NFT_FACTORY_ADDRESS='0x...'
# NEXT_PUBLIC_PROVIDER_URL="http://..."
# etc.

Restart Development Server

npm start

The portal will now connect to remote Ocean Protocol networks.

Troubleshooting

Docker containers won't start

Clean Docker system and retry:

# Warning: This removes ALL Docker images and volumes
docker system prune --all --volumes

# Then restart Barge
cd barge
./start_ocean.sh --with-thegraph

This removes all Docker data, not just Barge. Use with caution.

Contract deployment fails

Ensure Docker has enough resources:

Open Docker Desktop
Go to Settings → Resources
Allocate at least 8GB RAM
Restart Docker
Retry Barge startup

Subgraph not syncing

Check The Graph node logs:

docker-compose logs -f graph-node

If stuck, restart the graph node:

docker-compose restart graph-node

MetaMask transaction errors

Common issues:Wrong network: Ensure MetaMask is on Ganache (Chain ID 8996)Nonce issues: Reset MetaMask account:

Settings → Advanced → Reset Account

Insufficient gas: Ganache has gas limits. Try lower gas amounts.

Portal can't connect to Barge services

Verify services are running:

docker-compose ps

All services should show “Up”. Check specific service:

# Test Aquarius
curl http://localhost:5000/api/aquarius/health

# Test Provider
curl http://localhost:8030/api/services/health

# Test Subgraph
curl http://localhost:9000/subgraphs/name/oceanprotocol/ocean-subgraph

set-barge-env script fails

Ensure Barge is fully deployed before running:

# Check Barge logs for "Deployment complete"
cd barge
docker-compose logs | grep -i "complete\|ready"

# Then retry
cd /path/to/market
npm run set-barge-env

Service Endpoints Reference

When Barge is running, these services are available:

Service	Default URL	macOS URL	Purpose
Ganache	http://127.0.0.1:8545	(same)	Local blockchain
Aquarius	http://172.15.0.5:5000	http://127.0.0.1:5000	Metadata cache
Provider	http://172.15.0.4:8030	http://127.0.0.1:8030	Data service
Subgraph	http://172.15.0.15:8000	http://127.0.0.1:9000	GraphQL API
Graph Node	http://127.0.0.1:8020	(same)	Indexing service
IPFS	http://127.0.0.1:5001	(same)	File storage

Advanced Configuration

Custom Barge Configuration

You can customize Barge behavior by editing docker-compose.yml in the Barge directory:

docker-compose.yml

# Example: Change Provider port
services:
  provider:
    ports:
      - "8031:8030"  # Host:Container

Testing Smart Contracts

With Barge running, you can deploy and test custom smart contracts:

# Connect to Ganache
export RPC_URL=http://127.0.0.1:8545

# Deploy using your preferred tool (Hardhat, Truffle, etc.)

Best Practices

Resource Management

Stop Barge when not needed to free resources
Use docker-compose down -v for clean restarts
Monitor Docker Desktop for resource usage

Development Workflow

Use Barge for feature development and testing
Test with remote networks before production
Keep Barge updated with latest images

Data Persistence

Barge data is ephemeral by default
Use volumes for persistent data if needed
Back up test data before cleaning Docker

Network Isolation

Keep Barge accounts separate from real accounts
Never use Ganache keys on mainnet
Test thoroughly before deploying to production

Next Steps

Testing Guide

Learn how to write and run tests with your local setup

Architecture

Understand the system architecture

Data Sources

Learn about Aquarius, Subgraph, and Provider

Local Development

Return to local development guide

Setup

Technical Reference

Deployment

What is Barge?

Prerequisites

Setup Instructions

macOS-Specific Configuration

Provider URL Configuration

Service Endpoint Configuration

Environment Variables

MetaMask Integration

Common Barge Commands

Switching Back to Remote Networks

Troubleshooting

Service Endpoints Reference

Advanced Configuration

Custom Barge Configuration

Testing Smart Contracts

Best Practices

Resource Management

Development Workflow

Data Persistence

Network Isolation

Next Steps

Testing Guide

Architecture

Data Sources

Local Development

Build docs developers (and LLMs) love

Setup

Technical Reference

Deployment

​What is Barge?

​Prerequisites

​Setup Instructions

​macOS-Specific Configuration

​Provider URL Configuration

​Service Endpoint Configuration

​Environment Variables

​MetaMask Integration

​Common Barge Commands

​Switching Back to Remote Networks

​Troubleshooting

​Service Endpoints Reference

​Advanced Configuration

​Custom Barge Configuration

​Testing Smart Contracts

​Best Practices

Resource Management

Development Workflow

Data Persistence

Network Isolation

​Next Steps

Testing Guide

Architecture

Data Sources

Local Development

Build docs developers (and LLMs) love

What is Barge?

Prerequisites

Setup Instructions

macOS-Specific Configuration

Provider URL Configuration

Service Endpoint Configuration

Environment Variables

MetaMask Integration

Common Barge Commands

Switching Back to Remote Networks

Troubleshooting

Service Endpoints Reference

Advanced Configuration

Custom Barge Configuration

Testing Smart Contracts

Best Practices

Next Steps