explorer-monorepo/docs/BLOCKSCOUT_START_AND_BUILD.md

# Start Blockscout Container and Build Assets

## Problem

The Blockscout container is not running, so we can't build assets or access it.

## Solution

### Quick Fix Commands (From VMID 5000)

```bash
# Step 1: Find and start the container
BLOCKSCOUT_CONTAINER=$(docker ps -a | grep blockscout | grep -v postgres | awk '{print $1}' | head -1)
docker start $BLOCKSCOUT_CONTAINER

# Step 2: Wait for container to initialize (30-60 seconds)
echo "Waiting for Blockscout to start..."
sleep 30

# Step 3: Build static assets
docker exec -it $BLOCKSCOUT_CONTAINER mix phx.digest

# Step 4: Verify assets were built
docker exec -it $BLOCKSCOUT_CONTAINER test -f priv/static/cache_manifest.json && \
  echo "✅ Assets built" || echo "❌ Assets still missing"
```

### Alternative: Use Docker Compose

If Blockscout is managed via docker-compose:

```bash
cd /opt/blockscout

# Start Blockscout
docker compose up -d blockscout

# Wait for startup
sleep 30

# Build assets
BLOCKSCOUT_CONTAINER=$(docker ps | grep blockscout | grep -v postgres | awk '{print $1}' | head -1)
docker exec -it $BLOCKSCOUT_CONTAINER mix phx.digest
```

### Automated Script

Run the automated script:

```bash
# From Proxmox host
cd /home/intlc/projects/proxmox/explorer-monorepo
./scripts/start-blockscout-and-build-assets.sh
```

Or from inside VMID 5000:

```bash
cd /home/intlc/projects/proxmox/explorer-monorepo
./scripts/start-blockscout-and-build-assets.sh
```

## Troubleshooting

### Container Won't Start

**Check why it's not starting:**
```bash
docker logs $BLOCKSCOUT_CONTAINER 2>&1 | tail -50
```

**Common issues:**
1. **Database connection failed** - Check if postgres container is running:
   ```bash
   docker ps | grep postgres
   ```

2. **Port conflict** - Check if port 4000 is in use:
   ```bash
   netstat -tlnp | grep 4000
   ```

3. **Missing environment variables** - Check docker-compose.yml or .env file

### Assets Build Fails

**If `mix phx.digest` fails:**

1. **Try alternative method:**
   ```bash
   docker exec -it $BLOCKSCOUT_CONTAINER npm run deploy
   ```

2. **Check if dependencies are installed:**
   ```bash
   docker exec -it $BLOCKSCOUT_CONTAINER mix deps.get
   docker exec -it $BLOCKSCOUT_CONTAINER npm install --prefix apps/block_scout_web/assets
   ```

3. **Build manually inside container:**
   ```bash
   docker exec -it $BLOCKSCOUT_CONTAINER bash
   # Inside container:
   cd apps/block_scout_web/assets
   npm install
   npm run deploy
   mix phx.digest
   ```

### Container Starts Then Stops

**Check logs for errors:**
```bash
docker logs $BLOCKSCOUT_CONTAINER 2>&1 | grep -i error | tail -20
```

**Common causes:**
- Database migrations not run (but we verified they are)
- Missing environment variables
- Port conflicts
- Memory/resource limits

**Fix:**
```bash
# Check docker-compose resource limits
grep -A 10 "blockscout:" /opt/blockscout/docker-compose.yml | grep -E "(memory|cpus)"

# Increase if needed or check system resources
free -h
```

## Verification

After starting and building assets:

```bash
# 1. Check container is running
docker ps | grep blockscout

# 2. Check assets exist
BLOCKSCOUT_CONTAINER=$(docker ps | grep blockscout | grep -v postgres | awk '{print $1}' | head -1)
docker exec -it $BLOCKSCOUT_CONTAINER ls -la priv/static/cache_manifest.json

# 3. Check Blockscout is responding
curl -s http://localhost:4000/api/v2/stats | head -20

# 4. Check logs for errors
docker logs $BLOCKSCOUT_CONTAINER 2>&1 | tail -30
```

## Complete Fix Sequence

```bash
# From VMID 5000 - Complete fix sequence

# 1. Start container
BLOCKSCOUT_CONTAINER=$(docker ps -a | grep blockscout | grep -v postgres | awk '{print $1}' | head -1)
docker start $BLOCKSCOUT_CONTAINER

# 2. Wait for startup
echo "Waiting 30 seconds for Blockscout to initialize..."
sleep 30

# 3. Build assets
docker exec -it $BLOCKSCOUT_CONTAINER mix phx.digest

# 4. Verify assets
docker exec -it $BLOCKSCOUT_CONTAINER test -f priv/static/cache_manifest.json && \
  echo "✅ Assets built successfully" || echo "❌ Assets still missing"

# 5. Check if Blockscout is responding
curl -s http://localhost:4000/api/v2/stats && \
  echo "✅ Blockscout API working" || echo "⚠️  API not responding yet"

# 6. Check logs
docker logs $BLOCKSCOUT_CONTAINER 2>&1 | tail -20
```

## Next Steps

After starting the container and building assets:

1. ✅ Verify container is running: `docker ps | grep blockscout`
2. ✅ Verify assets exist: `docker exec -it blockscout test -f priv/static/cache_manifest.json`
3. ✅ Verify API responds: `curl http://localhost:4000/api/v2/stats`
4. ✅ Check docker-compose startup command is correct
5. ✅ Ensure container stays running (check logs for crashes)