Basilica Localnet Debug

Basilica Localnet Debugging

Architecture Reference

Services

Database Architecture

IMPORTANT: Validator and Miner use SQLite, NOT PostgreSQL.

Docker Compose Profiles

Config Files

Wallet Locations

• Local wallets: scripts/localnet/wallets/
• Validator wallet: scripts/localnet/wallets/validator/
• Miner wallet: scripts/localnet/wallets/miner_1/
• Alice (funder): scripts/localnet/wallets/alice/

Scripts Reference

start.sh Profiles

./start.sh network     # Subtensor only
./start.sh validator   # Subtensor + Validator
./start.sh miner       # Above + Miner
./start.sh monitoring  # All + Prometheus + Grafana
./start.sh all         # Everything (default)
./start.sh --build     # Rebuild images before starting

stop.sh Options

./stop.sh              # Stop containers, preserve data
./stop.sh --clean      # Remove containers, volumes, and network for fresh start (wallets in scripts/localnet/wallets/ are preserved)

Docker Compose Commands

Run these from scripts/localnet/ directory.

View Logs

# All services
docker compose logs

# Specific service
docker compose logs validator
docker compose logs miner
docker compose logs subtensor

# Follow logs in real-time
docker compose logs -f validator

# Tail last N lines
docker compose logs --tail=100 validator

# Filter for errors/warnings
docker compose logs validator 2>&1 | grep -iE "error|warn|fail"

# Combine follow + filter
docker compose logs -f validator 2>&1 | grep -iE "error|warn"

Service Management

# Restart a service
docker compose restart validator

# Stop single service
docker compose stop validator

# Start single service
docker compose up -d validator

# Rebuild single service (no cache)
docker compose build --no-cache validator

# Rebuild and restart
docker compose up -d --build validator

Container Access

# Shell into container
docker exec -it basilica-validator /bin/sh
docker exec -it basilica-miner /bin/sh

# Run command in container
docker exec basilica-validator cat /app/validator.toml
docker exec basilica-validator ls -la /opt/basilica/data/  # Check validator data

Volume Management

# List volumes
docker volume ls | grep localnet

# Inspect volume
docker volume inspect localnet_validator-data

# Remove all project volumes (destructive)
docker compose down -v

Debugging Workflows

Service Won't Start

1. Check if container exists:

   docker compose ps -a
   

2. Check logs for errors:

   docker compose logs validator 2>&1 | tail -50
   

3. Check dependencies are running:

   docker compose ps subtensor  # Validator depends on this
   docker compose ps validator  # Miner depends on this being healthy
   

4. Check health endpoint:

   curl -s http://localhost:8080/health  # Validator
   curl -s http://localhost:9091/metrics  # Miner
   curl -s http://localhost:9944/health  # Subtensor
   

Quick Rebuild Cycle

docker compose stop validator && \
docker compose build --no-cache validator && \
docker compose up -d validator && \
docker compose logs -f validator

Database Issues (SQLite)

Validator and miner use SQLite databases stored in their data volumes.

# Check validator database exists
docker exec basilica-validator ls -la /opt/basilica/data/validator.db

# Check miner database exists
docker exec basilica-miner ls -la /var/lib/basilica/miner/data/miner.db

# Reset validator database (will be recreated on startup)
docker compose stop validator
docker volume rm localnet_validator-data
docker compose up -d validator

# Reset miner database
docker compose stop miner
docker volume rm localnet_miner-data
docker compose up -d miner

Network Connectivity

# Check if services can reach each other
docker exec basilica-validator curl -s http://subtensor:9944/health
docker exec basilica-miner curl -s http://validator:8080/health

# Check network exists
docker network ls | grep basilica

# Inspect network
docker network inspect localnet_basilica-localnet

Wallet Issues

# Check wallets exist
ls -la scripts/localnet/wallets/

# Check wallet balance
uvx --from bittensor-cli btcli wallet balance \
    --wallet-path scripts/localnet/wallets \
    --wallet-name validator \
    --network local

# Re-initialize wallets (requires subtensor running)
./init-subnet.sh

Full Reset

./stop.sh --clean    # Removes containers, volumes, and network (scripts/localnet/wallets/ is preserved)
./start.sh miner     # Fresh start with wallet re-registration

Common Error Patterns

Endpoints Reference

Files Reference

Docker Volumes

Config File Mounts

Converted and distributed by TomeVault — claim your Tome and manage your conversions.