Sankofa/docs/marketplace/sovereign-stack/TROUBLESHOOTING.md

# Troubleshooting Guide - Sovereign Stack Marketplace

## Common Issues and Solutions

### Issue: "DB_PASSWORD is required but not provided"

**Problem**: The `.env` file is missing or doesn't contain `DB_PASSWORD`.

**Solution**:
1. Create `.env` file in `api/` directory:
   ```bash
   cd /home/intlc/projects/Sankofa/api
   cp .env.example .env
   ```

2. Edit `.env` and set your database password:
   ```env
   DB_PASSWORD=your_secure_password_here
   ```

3. **Development Requirements** (minimum):
   - At least 8 characters long
   - Not in the insecure secrets list (password, admin, etc.)

4. **Production Requirements** (strict):
   - At least 32 characters long
   - Must contain uppercase letters
   - Must contain lowercase letters
   - Must contain numbers
   - Must contain special characters

### Issue: "Secret 'DB_PASSWORD' uses an insecure default value"

**Problem**: The password is in the insecure secrets list.

**Solution**: Use a different password. Avoid:
- `password`, `admin`, `root`, `postgres`
- `123456`, `password123`
- `test`, `dev`, `development`
- Any single word from the dictionary

**Example secure passwords**:
- Development: `dev_password_123` (8+ chars, not in blacklist)
- Production: `MySecureP@ssw0rd123!WithSpecialChars` (32+ chars with all requirements)

### Issue: "Secret 'DB_PASSWORD' must be at least 32 characters long"

**Problem**: Running in production mode with a password that's too short.

**Solutions**:

**Option 1**: Set `NODE_ENV=development` in `.env`:
```env
NODE_ENV=development
DB_PASSWORD=your_8_char_min_password
```

**Option 2**: Use a longer, more complex password:
```env
DB_PASSWORD=MySecureP@ssw0rd123!WithSpecialCharsAndMore
```

### Issue: Migration Fails with Database Connection Error

**Problem**: Database is not running or credentials are incorrect.

**Solution**:
1. Verify PostgreSQL is running:
   ```bash
   sudo systemctl status postgresql
   # or
   psql --version
   ```

2. Test connection manually:
   ```bash
   psql -h localhost -U postgres -d sankofa
   ```

3. Check `.env` file has correct credentials:
   ```env
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=sankofa
   DB_USER=postgres
   DB_PASSWORD=your_password
   ```

### Issue: "Phoenix publisher not found" during seeding

**Problem**: Migration 025 hasn't run yet.

**Solution**:
1. Run migrations first:
   ```bash
   pnpm db:migrate:up
   ```

2. Then run seed:
   ```bash
   pnpm db:seed:sovereign-stack
   ```

### Issue: Services Not Appearing in Marketplace

**Problem**: Seed script didn't run or failed silently.

**Solution**:
1. Check if services exist in database:
   ```bash
   pnpm verify:sovereign-stack
   ```

2. If services are missing, re-run seed:
   ```bash
   pnpm db:seed:sovereign-stack
   ```

3. Check for errors in the output

### Issue: GraphQL Query Returns Empty Results

**Problem**: Services might not be published or filter is incorrect.

**Solution**:
1. Verify services are published:
   ```graphql
   query {
     products(filter: { status: PUBLISHED }) {
       name
       publisher {
         name
       }
     }
   }
   ```

2. Check publisher name:
   ```graphql
   query {
     publishers {
       name
       displayName
       products {
         name
       }
     }
   }
   ```

## Environment Setup

### Development Mode

For local development, set in `.env`:
```env
NODE_ENV=development
DB_PASSWORD=dev_password_123  # Minimum 8 characters
```

This relaxes password requirements:
- Minimum 8 characters (instead of 32)
- No complexity requirements (uppercase, lowercase, numbers, special chars)

### Production Mode

For production, ensure:
```env
NODE_ENV=production
DB_PASSWORD=VerySecureP@ssw0rd123!WithAllRequirements  # Minimum 32 characters
```

Strict requirements apply:
- Minimum 32 characters
- Must have uppercase, lowercase, numbers, and special characters

## Quick Fixes

### Reset Everything

If you need to start fresh:

```bash
cd /home/intlc/projects/Sankofa/api

# 1. Create/update .env
cp .env.example .env
# Edit .env with your password

# 2. Run setup
./scripts/setup-sovereign-stack.sh
```

### Check Current Status

```bash
# Check migration status
pnpm db:migrate:status

# Verify services
pnpm verify:sovereign-stack

# Check database connection
psql -h localhost -U postgres -d sankofa -c "SELECT 1;"
```

## Getting Help

If issues persist:

1. **Check Logs**: Review error messages carefully
2. **Verify Environment**: Ensure `.env` is correct
3. **Database Status**: Verify PostgreSQL is running
4. **Migration Status**: Check which migrations have run
5. **Contact Support**: support@sankofa.nexus

## Example .env for Development

```env
# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=sankofa
DB_USER=postgres
DB_PASSWORD=dev_sankofa_2024

# Application
NODE_ENV=development
PORT=4000

# Keycloak (optional for development)
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=master
KEYCLOAK_CLIENT_ID=sankofa-api
KEYCLOAK_CLIENT_SECRET=dev_secret

# JWT (optional for development)
JWT_SECRET=dev_jwt_secret_minimum_8_chars

# Logging
LOG_LEVEL=debug
```