Sankofa/api/SETUP_INSTRUCTIONS.md

# Setup Instructions - Sovereign Stack Marketplace

## Prerequisites

1. **PostgreSQL Database** running and accessible
2. **Node.js 18+** and **pnpm** installed
3. **Environment Variables** configured

## Quick Setup

### Option 1: Automated (Recommended)

```bash
cd /home/intlc/projects/Sankofa/api
./scripts/setup-sovereign-stack.sh
```

The script will:
- Check for `.env` file and help create it if missing
- Run database migrations
- Seed all 9 Sovereign Stack services
- Verify the setup

### Option 2: Manual Steps

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

# 1. Create .env file
pnpm create-env
# Then edit .env and set DB_PASSWORD

# 2. Run migrations
pnpm db:migrate:up

# 3. Seed services
pnpm db:seed:sovereign-stack

# 4. Verify
pnpm verify:sovereign-stack
```

## Environment Configuration

### Create .env File

```bash
# Use helper script
pnpm create-env

# Or copy manually
cp .env.example .env
```

### Required Variables

Edit `.env` and set:

```env
# Database (REQUIRED)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=sankofa
DB_USER=postgres
DB_PASSWORD=your_secure_password_here  # ⚠ REQUIRED

# Application
NODE_ENV=development  # Set to 'development' for relaxed password requirements
PORT=4000
```

### Password Requirements

**Development Mode** (`NODE_ENV=development`):
- Minimum 8 characters
- Not in insecure secrets list

**Production Mode** (`NODE_ENV=production`):
- Minimum 32 characters
- Must contain: uppercase, lowercase, numbers, special characters

**Example Development Password**: `dev_sankofa_2024`

**Example Production Password**: `MySecureP@ssw0rd123!WithSpecialChars`

## Troubleshooting

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

**Fix**: Create `.env` file and set `DB_PASSWORD`:
```bash
pnpm create-env
# Edit .env and set DB_PASSWORD
```

### Error: "Secret uses an insecure default value"

**Fix**: Use a different password (not: password, admin, root, etc.)

### Error: "Secret must be at least 32 characters"

**Fix**: Either:
1. Set `NODE_ENV=development` in `.env` (relaxes to 8 chars)
2. Use a longer password (32+ chars with all requirements)

See [TROUBLESHOOTING.md](../docs/marketplace/sovereign-stack/TROUBLESHOOTING.md) for more help.

## Verification

After setup, verify services:

```bash
pnpm verify:sovereign-stack
```

Expected output:
```
✅ Phoenix publisher found: Phoenix Cloud Services
✅ Found 9 Phoenix services
✅ All 9 expected services found!
```

## Next Steps

1. ✅ Services are now registered in marketplace
2. ⏳ Access via GraphQL API or portal
3. ⏳ Subscribe to services as needed
4. ⏳ Implement full service logic (stubs are ready)

## Documentation

- **Quick Start**: `QUICK_START_SOVEREIGN_STACK.md`
- **Setup Guide**: `docs/marketplace/sovereign-stack/SETUP.md`
- **Troubleshooting**: `docs/marketplace/sovereign-stack/TROUBLESHOOTING.md`
- **Service Docs**: `docs/marketplace/sovereign-stack/*.md`