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:

   cd /home/intlc/projects/Sankofa/api
   cp .env.example .env
   

2. Edit .env and set your database password:

   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:

NODE_ENV=development
DB_PASSWORD=your_8_char_min_password

Option 2: Use a longer, more complex password:

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:

   sudo systemctl status postgresql
   # or
   psql --version
   

2. Test connection manually:

   psql -h localhost -U postgres -d sankofa
   

3. Check .env file has correct credentials:

   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:

   pnpm db:migrate:up
   

2. Then run seed:

   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:

   pnpm verify:sovereign-stack
   

2. If services are missing, re-run seed:

   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:

   query {
     products(filter: { status: PUBLISHED }) {
       name
       publisher {
         name
       }
     }
   }
   

2. Check publisher name:

   query {
     publishers {
       name
       displayName
       products {
         name
       }
     }
   }
   

Environment Setup

Development Mode

For local development, set in .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:

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:

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

# 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

# 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