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:
2026-04-18 18:56:17 +00:00
parent e1c3b40cb0
commit 40c9af678f
205 changed files with 8 additions and 37633 deletions

View File

@@ -1,138 +0,0 @@
# Database Password Fix Guide
## Problem
The backend API is returning HTTP 503 with a "degraded" status because it cannot connect to the PostgreSQL database. The error message indicates:
```
password authentication failed for user "explorer" (SQLSTATE 28P01)
```
## Solution
The database password needs to be reset to match the backend configuration. The backend expects:
- **User**: `explorer`
- **Password**: `changeme`
- **Database**: `explorer`
### Option 1: Automated Fix (Recommended)
Run the fix script with sudo:
```bash
cd /home/intlc/projects/proxmox/explorer-monorepo
sudo ./scripts/fix-database-password-manual.sh
```
This script will:
1. Create or update the `explorer` PostgreSQL user with password `changeme`
2. Create the `explorer` database if it doesn't exist
3. Grant all privileges to the explorer user
4. Test the connection
### Option 2: Manual Fix
If you prefer to fix it manually, run these commands:
```bash
# Connect to PostgreSQL as the postgres superuser
sudo -u postgres psql
# In the PostgreSQL prompt, run:
CREATE USER explorer WITH PASSWORD 'changeme';
CREATE DATABASE explorer OWNER explorer;
GRANT ALL PRIVILEGES ON DATABASE explorer TO explorer;
\q
```
Or if the user already exists:
```bash
sudo -u postgres psql -c "ALTER USER explorer WITH PASSWORD 'changeme';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE explorer TO explorer;"
```
### Option 3: Use Different Password
If you want to use a different password, you have two options:
**A. Update the backend to use the existing password:**
```bash
export DB_PASSWORD="your_actual_password"
kill $(cat /tmp/explorer_backend.pid) 2>/dev/null
./scripts/start-backend-service.sh
```
**B. Change the database password to match backend:**
```bash
sudo -u postgres psql -c "ALTER USER explorer WITH PASSWORD 'your_new_password';"
export DB_PASSWORD="your_new_password"
kill $(cat /tmp/explorer_backend.pid) 2>/dev/null
./scripts/start-backend-service.sh
```
## Verification
After fixing the password, verify the connection:
```bash
# Test database connection
PGPASSWORD=changeme psql -h localhost -U explorer -d explorer -c "SELECT 1;"
# Check backend health
curl http://localhost:8080/health
# Expected response should show:
# "database": "ok" (instead of "error: ...")
# "status": "ok" (instead of "degraded")
```
## Restart Backend
After fixing the password, restart the backend:
```bash
kill $(cat /tmp/explorer_backend.pid) 2>/dev/null
./scripts/start-backend-service.sh
```
## Troubleshooting
### PostgreSQL not running
```bash
sudo systemctl status postgresql
sudo systemctl start postgresql
```
### User doesn't exist
```bash
sudo -u postgres psql -c "\du" # List all users
```
### Database doesn't exist
```bash
sudo -u postgres psql -c "\l" # List all databases
```
### Connection still failing
1. Check PostgreSQL is listening on port 5432:
```bash
netstat -tlnp | grep 5432
```
2. Check PostgreSQL authentication configuration:
```bash
sudo cat /etc/postgresql/*/main/pg_hba.conf | grep -v "^#"
```
3. Verify the password was actually changed:
```bash
PGPASSWORD=changeme psql -h localhost -U explorer -d explorer -c "SELECT current_user;"
```
## Notes
- The default password `changeme` is used for development. **Change it in production!**
- The backend reads the password from the `DB_PASSWORD` environment variable
- If using Docker Compose, the password is set via the `DB_PASSWORD` environment variable in `deployment/docker-compose.yml`