d-bis/explorer-monorepo
4
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

chore: consolidate documentation — delete status/fix/progress cruft

Browse Source 
Before: 335 tracked .md files; top level had 14 README-like docs;
docs/ contained ~234 files, most of them auto/LLM-generated status
reports (ALL_*_COMPLETE*, *_FIX*, DEPLOYMENT_*_FINAL*, etc.).

After: 132 tracked .md files. Repo now has exactly five top-level
docs: README.md, QUICKSTART.md, RUNBOOK.md, CONTRIBUTING.md,
CHANGELOG.md (moved up from docs/).

Keeper philosophy in docs/:
- API, CCIP (ops + security + receiver/router refs), Chainlist refs,
  compliance, deployment (guides not status), database connection,
  legal compliance, metamask integration, production checklist,
  tiered-architecture implementation/setup, reusable-components plan,
  token-mechanism doc, wrap-and-bridge operational reference, plus
  docs/specs/** and docs/api/ / docs/openapi/ trees.

Deleted (git history preserves provenance):
- All 'ALL_*_COMPLETE*' / '*_FIX*' / '*_FIXED*' / '*_FINAL*' /
  '*_STATUS*' / '*_PROGRESS*' / '*_SUMMARY*' files.
- BLOCKSCOUT_*_FIX / _CRASH / _INITIALIZATION / _SCHEMA / _YAML /
  _SKIP / _NEXT_STEPS / _START_AND_BUILD / _DATABASE_CREDENTIALS
  (the last contained passwords).
- CCIP_IMPLEMENTATION_* / CCIP_CURRENT_STATUS / CCIP_GAP_*
  (gap analyses are not a sustained reference).
- NPMPLUS_CREDENTIALS_GUIDE.md (contained creds).
- LETSENCRYPT_CONFIGURATION_GUIDE.md (contained creds; will be
  re-introduced as runbook content post-secrets-scrub).
- docs/diagnostic-reports/, docs/feature-flags/ (run-time artifacts).

README.md: dead links (START_HERE, README_DEPLOYMENT, COMPLETE_DEPLOYMENT,
DEPLOYMENT_COMPLETE_FINAL) replaced with links to the five canonical
top-level docs + docs/ index.
This commit is contained in:
Devin
2026-04-18 18:56:17 +00:00
parent e1c3b40cb0
commit 40c9af678f
205 changed files with 8 additions and 37633 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
docs/BLOCKSCOUT_CRASH_FIX.md
View File

@@ -1,236 +0,0 @@
# Fix Blockscout Container Crash
## Problem
Blockscout container starts but immediately stops (crashes). This is indicated by:
- Container shows as "Exited" after `docker start`
- Exit code is non-zero
- Container logs show errors or the process terminates
## Diagnosis
### Quick Diagnosis Commands
```bash
# From VMID 5000
# 1. Check container status and exit code
BLOCKSCOUT_CONTAINER=$(docker ps -a | grep blockscout | grep -v postgres | awk '{print $1}' | head -1)
docker inspect --format='Exit Code: {{.State.ExitCode}}' $BLOCKSCOUT_CONTAINER
# 2. Check recent logs
docker logs $BLOCKSCOUT_CONTAINER 2>&1 | tail -50
# 3. Check for errors
docker logs $BLOCKSCOUT_CONTAINER 2>&1 | grep -i "error\|fatal\|exception" | tail -20
# 4. Check startup command
docker inspect --format='{{.Config.Cmd}}' $BLOCKSCOUT_CONTAINER
docker inspect --format='{{.Config.Entrypoint}}' $BLOCKSCOUT_CONTAINER
```
### Automated Diagnosis
```bash
# From Proxmox host
cd /home/intlc/projects/proxmox/explorer-monorepo
./scripts/diagnose-blockscout-crash.sh
```
## Common Causes and Fixes
### 1. Missing Startup Command
**Symptom**: Container starts but exits immediately with code 0 or 1
**Fix**: Add startup command to docker-compose.yml
```bash
cd /opt/blockscout
# Check current configuration
grep -A 10 "blockscout:" docker-compose.yml
# Add startup command if missing
if ! grep -q "command:.*blockscout start" docker-compose.yml; then
# Backup
cp docker-compose.yml docker-compose.yml.backup
# Add command after blockscout: line
sed -i '/blockscout:/a\ command: bin/blockscout start' docker-compose.yml
# Or edit manually
# nano docker-compose.yml
# Add: command: bin/blockscout start
fi
# Restart with new configuration
docker compose down blockscout
docker compose up -d blockscout
```
### 2. Database Connection Failed
**Symptom**: Logs show database connection errors
**Fix**: Verify database is accessible
```bash
# Check postgres container
docker ps | grep postgres
# Test database connection
docker exec blockscout-postgres psql -U blockscout -d blockscout -c "SELECT 1;"
# Check DATABASE_URL in Blockscout container
docker inspect blockscout | grep -A 5 DATABASE_URL
```
### 3. Port Conflict
**Symptom**: Port 4000 already in use
**Fix**: Check and resolve port conflict
```bash
# Check what's using port 4000
netstat -tlnp | grep 4000
# Or
lsof -i :4000
# Stop conflicting service or change Blockscout port in docker-compose.yml
```
### 4. Missing Environment Variables
**Symptom**: Logs show missing configuration errors
**Fix**: Check and set required environment variables
```bash
# Check docker-compose.yml environment section
grep -A 20 "blockscout:" /opt/blockscout/docker-compose.yml | grep -E "environment:|DATABASE|SECRET"
# Check .env file
cat /opt/blockscout/.env 2>/dev/null || echo ".env file not found"
# Required variables typically include:
# - DATABASE_URL
# - SECRET_KEY_BASE
# - ETHEREUM_JSONRPC_HTTP_URL
# - ETHEREUM_JSONRPC_WS_URL
# - CHAIN_ID
```
### 5. Resource Limits
**Symptom**: Container runs out of memory or CPU
**Fix**: Check and increase resource limits
```bash
# Check current limits
docker inspect blockscout | grep -A 5 "Memory\|Cpu"
# Check system resources
free -h
df -h
# Increase limits in docker-compose.yml if needed
```
## Complete Fix Procedure
### Step 1: Diagnose the Issue
```bash
# Check logs
BLOCKSCOUT_CONTAINER=$(docker ps -a | grep blockscout | grep -v postgres | awk '{print $1}' | head -1)
docker logs $BLOCKSCOUT_CONTAINER 2>&1 | tail -50
```
### Step 2: Fix Based on Diagnosis
**If missing startup command:**
```bash
cd /opt/blockscout
sed -i '/blockscout:/a\ command: bin/blockscout start' docker-compose.yml
docker compose up -d blockscout
```
**If database connection issue:**
```bash
# Verify database
docker exec blockscout-postgres psql -U blockscout -d blockscout -c "SELECT 1;"
# Check DATABASE_URL
grep DATABASE_URL /opt/blockscout/docker-compose.yml
```
**If port conflict:**
```bash
# Find what's using port 4000
lsof -i :4000
# Stop it or change Blockscout port
```
### Step 3: Restart and Verify
```bash
# Restart with fixes
cd /opt/blockscout
docker compose restart blockscout
# Or
docker compose down blockscout && docker compose up -d blockscout
# Wait and check
sleep 30
docker ps | grep blockscout
docker logs blockscout 2>&1 | tail -30
```
## Manual Container Start (If Docker Compose Fails)
If docker-compose doesn't work, start manually:
```bash
# Get environment from docker-compose
cd /opt/blockscout
docker compose config | grep -A 30 "blockscout:" > /tmp/blockscout-config.txt
# Start manually with correct command
docker run -d \
--name blockscout \
--env-file .env \
-p 4000:4000 \
--link blockscout-postgres:postgres \
blockscout/blockscout:latest \
bin/blockscout start
```
## Verification
After applying fixes:
```bash
# 1. Check container is running
docker ps | grep blockscout
# 2. Check logs for errors
docker logs blockscout 2>&1 | tail -30
# 3. Test API
curl -s http://localhost:4000/api/v2/stats | head -20
# 4. Check process
docker exec blockscout pgrep -f "beam.smp" && echo "✅ Blockscout process running"
```
## Next Steps
Once container stays running:
1. ✅ Build static assets: `docker exec -it blockscout mix phx.digest`
2. ✅ Verify assets: `docker exec -it blockscout test -f priv/static/cache_manifest.json`
3. ✅ Test API: `curl http://localhost:4000/api/v2/stats`