explorer-monorepo/docs/DATABASE_PASSWORD_FIX.md

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:

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:

# 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:

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:

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:

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:

# 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:

kill $(cat /tmp/explorer_backend.pid) 2>/dev/null
./scripts/start-backend-service.sh

Troubleshooting

PostgreSQL not running

sudo systemctl status postgresql
sudo systemctl start postgresql

User doesn't exist

sudo -u postgres psql -c "\du"  # List all users

Database doesn't exist

sudo -u postgres psql -c "\l"  # List all databases

Connection still failing

1. Check PostgreSQL is listening on port 5432:

   netstat -tlnp | grep 5432
   

2. Check PostgreSQL authentication configuration:

   sudo cat /etc/postgresql/*/main/pg_hba.conf | grep -v "^#"
   

3. Verify the password was actually changed:

   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