Masp Indexer

✅ Masp-Indexer v1.4.7

⚠️ Testnet Only - Setup MASP Indexer with persistent PostgreSQL data.

📋 Prerequisites

System Requirements

- Ubuntu 20.04+
- 4GB+ RAM
- 30GB+ free disk

Install Packages

sudo apt-get update
sudo apt-get install -y curl ca-certificates git nano jq lz4

Install Docker & Docker Compose

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" \
  -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Logout and login

Verify

docker --version
docker-compose --version
git --version

✅ Fresh Installation

Step 1: Clone MASP Indexer

cd /var/www/
git clone https://github.com/namada-net/namada-masp-indexer.git masp-indexer
cd masp-indexer
git checkout v1.4.7

Step 2: Configure Environment

cp .env.template .env
nano .env

Edit .env:

# RPC Configuration
COMETBFT_URL=http://host.docker.internal:26657
# COMETBFT_URL=https://housefire.rpc.yourdomain.com

# PostgreSQL Configuration
DATABASE_URL=postgres://postgres:YOUR_STRONG_PASSWORD_HERE@postgres:5432/masp_indexer_local

# Webserver Configuration
INDEXER_PORT=5000
DEBUG=false
LOG_LEVEL=info

# External API
EXTERNAL_API=https://housefire.masp-indexer.yourdomain.com

Generate password:

openssl rand -base64 32

Step 3: Verify Docker Compose

nano docker-compose.yml

Check PostgreSQL config:

postgres:
  image: postgres:16-alpine
  command: [ "postgres", "-c", "max_connections=200" ]
  expose:
    - "5432"
  volumes:
    - postgres-data:/var/lib/postgresql/data
  environment:
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-YOUR_PASSWORD}
    POSTGRES_USER: postgres
    POSTGRES_DB: masp_indexer_local
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -d masp_indexer_local"]
    interval: 5s
    timeout: 10s
    retries: 5

volumes:
  postgres-data:  # Named volume for persistence

Step 4: Verify CometBFT RPC

cat ~/.local/share/namada/*/cometbft/config/config.toml | grep -A 2 "\[rpc\]"

Should show:

[rpc]
laddr = "tcp://0.0.0.0:26657"

Step 5: Build and Start

cd /var/www/masp-indexer
docker-compose build --no-cache
docker-compose up -d

Step 6: Verify Installation

# Check containers
docker-compose ps

# Check health
curl http://localhost:5000/health

# Check block height
curl -s http://localhost:5000/api/v1/height | jq -r '.block_height'

Step 7: Monitor Logs

# All logs
docker-compose logs -f --tail=50

# Specific services
docker logs masp-indexer-webserver-1 --tail=50
docker logs masp-indexer-crawler-1 --tail=50 -f

# Watch blocks syncing
watch -n 2 'curl -s http://localhost:5000/api/v1/height | jq -r .block_height'

✅ Upgrade from v1.x.x to v1.4.7

Step 1: Backup

cd /var/www/masp-indexer
docker-compose down
cp .env .env.backup
cd /var/www/
cp -r masp-indexer masp-indexer-backup

Step 2: Update

cd /var/www/masp-indexer
git fetch --all --tags
git checkout v1.4.7
git describe --tags

Step 3: Update Configuration

nano .env
nano docker-compose.yml  # Update password if needed

Step 4: Rebuild

docker-compose build --no-cache
docker-compose up -d

Step 5: Verify

docker-compose logs -f --tail=100
watch -n 2 'curl -s http://localhost:5000/api/v1/height | jq -r .block_height'
docker-compose ps

✅ Database Backup & Restore

Data Persistence

Data location:

/var/lib/docker/volumes/masp-indexer_postgres-data/_data

Verify volume:

docker volume ls | grep postgres-data
docker volume inspect masp-indexer_postgres-data
sudo ls -lh /var/lib/docker/volumes/masp-indexer_postgres-data/_data

Data Safety Rules

Data is SAFE during:

• ✅ docker-compose down

• ✅ docker-compose restart

• ✅ docker-compose build --no-cache

• ✅ Version upgrades

Data is DELETED when:

• ❌ docker-compose down --volumes

• ❌ docker volume rm masp-indexer_postgres-data

Golden Rule: NEVER use --volumes flag!

Manual Backup (Volume)

mkdir -p /var/backups/masp-indexer

docker run --rm \
  -v masp-indexer_postgres-data:/data \
  -v /var/backups/masp-indexer:/backup \
  alpine tar czf /backup/masp-postgres-backup-$(date +%Y%m%d-%H%M%S).tar.gz -C /data .

ls -lh /var/backups/masp-indexer/

SQL Dump Backup

docker exec -t masp-indexer-postgres-1 pg_dump -U postgres masp_indexer_local > \
  /var/backups/masp-indexer/masp-backup-$(date +%Y%m%d-%H%M%S).sql

ls -lh /var/backups/masp-indexer/

Restore from Volume Backup

cd /var/www/masp-indexer
docker-compose down

docker run --rm \
  -v masp-indexer_postgres-data:/data \
  -v /var/backups/masp-indexer:/backup \
  alpine sh -c "cd /data && tar xzf /backup/masp-postgres-backup-YYYYMMDD-HHMMSS.tar.gz"

docker-compose up -d

Restore from SQL Dump

cd /var/www/masp-indexer
docker-compose up -d postgres
sleep 10

docker exec -i masp-indexer-postgres-1 psql -U postgres masp_indexer_local < \
  /var/backups/masp-indexer/masp-backup-YYYYMMDD-HHMMSS.sql

docker-compose up -d

✅ Troubleshooting

Quick Commands

# Check status
docker-compose ps
docker-compose logs -f

# Restart services
docker-compose restart webserver
docker-compose restart crawler
docker-compose restart postgres

# Health check
curl http://localhost:5000/health

# Block height
curl -s http://localhost:5000/api/v1/height | jq -r '.block_height'

Full Reset (Destroys Data!)

cd /var/www/masp-indexer
docker-compose down --volumes  # ⚠️ DELETES ALL DATA!
docker volume prune -f
docker-compose up -d --build

Safe Restart

cd /var/www/masp-indexer
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Check Database Connection

# Enter postgres container
docker exec -it masp-indexer-postgres-1 psql -U postgres -d masp_indexer_local

# List tables
\dt

# Check counts
SELECT COUNT(*) FROM shielded_transactions;

# Exit
\q

Check RPC Connection

docker exec -it masp-indexer-crawler-1 curl -s http://host.docker.internal:26657/status | jq

Crawler Issues

# Check logs
docker logs masp-indexer-crawler-1 --tail=100 -f

# Restart crawler
docker-compose restart crawler

# Watch progress
watch -n 2 'curl -s http://localhost:5000/api/v1/height | jq -r .block_height'

✅ Monitoring

Status Checks

# Health
curl -sf http://localhost:5000/health && echo "✅ Healthy" || echo "❌ Unhealthy"

# Block height
curl -s http://localhost:5000/api/v1/height | jq -r '.block_height'

# Compare with RPC
curl -s http://localhost:26657/status | jq -r '.result.sync_info.latest_block_height'

# Container stats
docker stats --no-stream

Watch Sync Progress

watch -n 2 'curl -s http://localhost:5000/api/v1/height | jq -r .block_height'

✅ API Documentation

Full docs: https://anoma.github.io/namada-masp-indexer/

Endpoints:

• /health - Health check

• /api/v1/height - Current block height

• /api/v1/shielded - Shielded transactions

✅ Integration with Namadillo

nano /var/www/namadillo/apps/namadillo/public/config.toml

Add:

indexer_url = "https://housefire.indexer.yourdomain.com"
rpc_url = "https://housefire.rpc.yourdomain.com"
masp_indexer_url = "https://housefire.masp-indexer.yourdomain.com"
localnet_enabled = false

✅ Quick Reference

# Start
docker-compose up -d

# Stop
docker-compose down

# Restart
docker-compose restart

# Logs
docker-compose logs -f --tail=50

# Health
curl http://localhost:5000/health

# Block height
curl -s http://localhost:5000/api/v1/height | jq -r '.block_height'

# Rebuild
docker-compose build --no-cache && docker-compose up -d

# Backup
docker run --rm -v masp-indexer_postgres-data:/data \
  -v /var/backups/masp-indexer:/backup \
  alpine tar czf /backup/masp-postgres-backup-$(date +%Y%m%d-%H%M%S).tar.gz -C /data .

# Watch sync
watch -n 2 'curl -s http://localhost:5000/api/v1/height | jq -r .block_height'