chore: consolidate documentation — delete status/fix/progress cruft
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:
@@ -1,188 +0,0 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user