Installation

Overview

VoicePact consists of two main components:

Backend (FastAPI) - API server handling contracts, voice processing, and Africa’s Talking integration
Client (Next.js) - Web dashboard for managing contracts and viewing real-time updates

This guide covers complete installation and configuration for both components.

For a faster getting started experience, see the Quickstart Guide.

System Requirements

Backend Requirements

Python: 3.11 or higher
Redis: Latest stable version (for caching and sessions)
Operating System: Linux, macOS, or Windows
Memory: Minimum 2GB RAM (4GB+ recommended for voice processing)
Storage: 500MB for application + space for audio files

Client Requirements

Node.js: 18 or higher
Package Manager: npm, yarn, or pnpm
Operating System: Linux, macOS, or Windows
Memory: Minimum 1GB RAM
Browser: Modern browser (Chrome, Firefox, Safari, Edge)

External Services

Africa’s Talking Account: Sign up here
- Voice API access
- SMS API access
- Payments API access (for escrow)
- USSD service code (optional)
ngrok or similar: For local webhook tunneling during development

Backend Installation

1. Clone Repository

git clone https://github.com/mutuiris/voicepact.git
cd voicepact/server

2. Python Environment Setup

Create and activate a virtual environment to isolate dependencies:

python3.11 -m venv venv
source venv/bin/activate

You should see (venv) prefix in your terminal prompt indicating the virtual environment is active.

3. Install Dependencies

Install all required Python packages from requirements.txt:

pip install --upgrade pip
pip install -r requirements.txt

View all installed packages

The requirements.txt includes:

africastalking==2.0           # Africa's Talking SDK
fastapi==0.116.1              # Web framework
uvicorn==0.35.0               # ASGI server
sqlalchemy==2.0.43            # Database ORM
redis==6.4.0                  # Cache client
pydantic==2.11.7              # Data validation
pydantic-settings==2.10.1     # Settings management
cryptography==45.0.6          # Ed25519 signatures
httpx==0.28.1                 # Async HTTP client
python-dotenv==1.1.1          # Environment variables
python-multipart==0.0.20      # File upload support
websockets==15.0.1            # WebSocket support

4. Database Setup

VoicePact uses SQLite for development and can be configured for PostgreSQL in production.

Development (SQLite)
Production (PostgreSQL)

SQLite is the default and requires no additional setup. The database file will be created automatically on first run.

.env

DATABASE_URL=sqlite:///./voicepact.db

The database is created with Write-Ahead Logging (WAL) mode for better concurrent access:

voicepact.db
voicepact.db-shm
voicepact.db-wal

For production deployments, use PostgreSQL:

Install PostgreSQL (version 13+)

Create a database:

CREATE DATABASE voicepact;
CREATE USER voicepact_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE voicepact TO voicepact_user;

Update .env:

DATABASE_URL=postgresql://voicepact_user:secure_password@localhost:5432/voicepact

5. Redis Installation

Redis is required for caching contract lookups and managing WebSocket sessions.

macOS (Homebrew)
Linux (Ubuntu/Debian)
Linux (CentOS/RHEL)
Windows
Docker (All Platforms)

brew install redis
brew services start redis

# Verify Redis is running
redis-cli ping  # Should return PONG

sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

# Verify Redis is running
redis-cli ping  # Should return PONG

sudo yum install redis
sudo systemctl start redis
sudo systemctl enable redis

# Verify Redis is running
redis-cli ping  # Should return PONG

Download Redis from GitHub releases
Extract and run:
```
redis-server.exe
```

Or use Docker:

docker run -d -p 6379:6379 --name redis redis:alpine

docker run -d \
  --name voicepact-redis \
  -p 6379:6379 \
  -v redis-data:/data \
  redis:alpine redis-server --appendonly yes

# Verify
docker exec voicepact-redis redis-cli ping

6. Environment Configuration

Create a .env file in the server directory with the following configuration:

.env

# ============================================
# Africa's Talking Configuration
# ============================================
AT_USERNAME=sandbox
AT_API_KEY=your_api_key_here
AT_VOICE_NUMBER=+254XXXXXXXXX
AT_PAYMENT_PRODUCT_NAME=VoicePact
AT_USSD_SERVICE_CODE=*483#

# ============================================
# Database Configuration
# ============================================
DATABASE_URL=sqlite:///./voicepact.db
DATABASE_ECHO=false

# ============================================
# Redis Configuration
# ============================================
REDIS_URL=redis://localhost:6379/0
REDIS_MAX_CONNECTIONS=20
REDIS_SOCKET_TIMEOUT=30

# ============================================
# Security Configuration
# ============================================
SECRET_KEY=your_secret_key_here
SIGNATURE_PRIVATE_KEY=your_ed25519_private_key_here
PASSWORD_SALT=your_password_salt_here
WEBHOOK_SECRET=your_webhook_secret_here

# ============================================
# Webhook Configuration
# ============================================
WEBHOOK_BASE_URL=https://your-ngrok-url.ngrok.io

# ============================================
# Application Settings
# ============================================
APP_NAME=VoicePact
APP_VERSION=1.0.0
ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=INFO
API_V1_PREFIX=/api/v1

# ============================================
# Voice Processing Configuration
# ============================================
WHISPER_MODEL_SIZE=small
MAX_AUDIO_DURATION=1200
MAX_AUDIO_FILE_SIZE=52428800
SUPPORTED_AUDIO_FORMATS=wav,mp3,m4a,ogg,flac

# ============================================
# HTTP Client Configuration
# ============================================
HTTP_TIMEOUT=30
HTTP_MAX_CONNECTIONS=100
HTTP_MAX_KEEPALIVE=20

# ============================================
# Performance Configuration
# ============================================
CACHE_TTL=3600
MAX_WORKERS=4
REQUEST_TIMEOUT=30

# ============================================
# CORS Configuration
# ============================================
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
CORS_CREDENTIALS=true
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_HEADERS=*

# ============================================
# Contract Configuration
# ============================================
CONTRACT_HASH_ALGORITHM=blake2b
CONTRACT_SIGNATURE_ALGORITHM=ed25519
MAX_CONTRACT_DURATION=31536000
CONTRACT_CONFIRMATION_TIMEOUT=86400

# ============================================
# Payment Configuration
# ============================================
ESCROW_TIMEOUT=604800
PAYMENT_RETRY_ATTEMPTS=3
PAYMENT_RETRY_DELAY=300
MIN_PAYMENT_AMOUNT=100
MAX_PAYMENT_AMOUNT=1000000

Security Best Practices:

Generate strong random values for all secret keys
Never commit the .env file to version control
Use different secrets for development and production
Rotate keys periodically in production

Generate secure keys

Generate cryptographically secure keys using Python:

python -c "import secrets; print('SECRET_KEY=' + secrets.token_urlsafe(32))"
python -c "import secrets; print('SIGNATURE_PRIVATE_KEY=' + secrets.token_urlsafe(64))"
python -c "import secrets; print('PASSWORD_SALT=' + secrets.token_urlsafe(32))"
python -c "import secrets; print('WEBHOOK_SECRET=' + secrets.token_urlsafe(32))"

7. Africa’s Talking Setup

Create an account

Access sandbox

Navigate to the Sandbox in your dashboard.

Get API credentials

Username: sandbox (for sandbox environment)
API Key: Found in Settings > API Key (click to reveal)

Add these to your .env file:

AT_USERNAME=sandbox
AT_API_KEY=your_actual_api_key_here

Add test phone numbers

In sandbox mode, you can only send SMS/calls to registered numbers:

Go to Sandbox > Settings
Add test phone numbers in international format (+254…)
These numbers will receive actual SMS during testing

Get a voice number

Request a voice number from the Voice section:

AT_VOICE_NUMBER=+254XXXXXXXXX

Configure payment product (optional)

For escrow functionality:

Create a payment product in the Payments section
Use your product name:
```
AT_PAYMENT_PRODUCT_NAME=VoicePact
```

8. Webhook Setup (Development)

During development, use ngrok to expose your local server to Africa’s Talking webhooks:

Install ngrok

Download from ngrok.com or install via package manager:

brew install ngrok

Start ngrok tunnel

ngrok http 8000

You’ll see output like:

Forwarding  https://abc123.ngrok.io -> http://localhost:8000

Update webhook URL

Copy the HTTPS URL and update your .env:

WEBHOOK_BASE_URL=https://abc123.ngrok.io

Configure callback URLs in Africa's Talking

Update these in your Africa’s Talking dashboard:

Voice Callback: https://abc123.ngrok.io/api/v1/voice/webhook
SMS Callback: https://abc123.ngrok.io/api/v1/sms/webhook
Payment Callback: https://abc123.ngrok.io/api/v1/payments/webhook

9. Start the Backend Server

With everything configured, start the FastAPI server:

uvicorn main:app --reload --port 8000

For production, use more workers and disable reload:

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

Alternative: Run with Python directly

The main.py includes a built-in runner:

python main.py

This uses the configuration from server/app/core/config.py:main.py:137-147.

10. Verify Installation

Test that everything is working:

Health Check
API Info
API Documentation

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "services": {
    "database": "healthy",
    "redis": "healthy"
  },
  "timestamp": 1234567890.123
}

curl http://localhost:8000/info

Expected response:

{
  "app_name": "VoicePact",
  "version": "1.0.0",
  "environment": "development",
  "debug": true,
  "features": {
    "voice_processing": true,
    "sms_integration": true,
    "payment_escrow": true,
    "ussd_support": true,
    "contract_generation": true,
    "crypto_signatures": true
  }
}

Client Installation

The Next.js client provides a web dashboard for contract management.

The client is currently in active development (alpha stage). Core backend workflows are stable, but the frontend is rapidly evolving.

1. Navigate to Client Directory

cd ../client

2. Install Dependencies

Choose your preferred package manager:

npm install

View key dependencies

From client/package.json:

{
  "dependencies": {
    "next": "15.5.2",
    "react": "19.1.0",
    "react-dom": "19.1.0",
    "axios": "^1.11.0",
    "socket.io-client": "^4.8.1",
    "zustand": "^5.0.8",
    "react-hook-form": "^7.62.0",
    "zod": "^4.1.3",
    "recharts": "^3.1.2",
    "wavesurfer.js": "^7.10.1",
    "lucide-react": "^0.542.0",
    "tailwindcss": "^4"
  }
}

3. Configure Environment

Create .env.local in the client directory:

.env.local

# ============================================
# API Configuration
# ============================================
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_WEBSOCKET_BASE=ws://localhost:8000

# ============================================
# Feature Flags
# ============================================
NEXT_PUBLIC_FEATURE_LOW_DATA_MODE=true
NEXT_PUBLIC_FEATURE_ESCROW_TIMELINE=true
NEXT_PUBLIC_FEATURE_ROLE_AWARE_DASHBOARD=false
NEXT_PUBLIC_FEATURE_I18N=false

# ============================================
# Analytics & Monitoring (Optional)
# ============================================
NEXT_PUBLIC_SENTRY_DSN=

All NEXT_PUBLIC_* variables are exposed to the browser. Never put sensitive secrets here.

4. Start Development Server

npm run dev

The client will start on http://localhost:3000.

5. Build for Production

npm run build
npm start

Production Deployment

Backend Deployment Checklist

Set production environment

ENVIRONMENT=production
DEBUG=false

Use PostgreSQL

DATABASE_URL=postgresql://user:pass@host:5432/voicepact

Secure Redis

REDIS_URL=redis://:password@host:6379/0

Use managed Redis

Consider using:

AWS ElastiCache
Redis Cloud
Digital Ocean Managed Redis

Set strong secrets

Generate new production secrets (don’t reuse development keys).

Configure CORS

Set specific allowed origins:

CORS_ORIGINS=https://app.yourdomain.com,https://yourdomain.com

Set up SSL/TLS

Use a reverse proxy (nginx/Caddy) with Let’s Encrypt:

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Use process manager

Run with systemd, supervisor, or PM2:

systemd service

[Unit]
Description=VoicePact API
After=network.target

[Service]
User=voicepact
WorkingDirectory=/opt/voicepact/server
Environment="PATH=/opt/voicepact/server/venv/bin"
ExecStart=/opt/voicepact/server/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
Restart=always

[Install]
WantedBy=multi-user.target

Configure logging

LOG_LEVEL=INFO
LOG_FILE=/var/log/voicepact/app.log

Set up monitoring

Application health checks
Redis connection monitoring
Database connection pool metrics
Africa’s Talking API latency tracking

Client Deployment

The Next.js client can be deployed to:

Vercel (recommended): Zero-config deployment
Netlify: Static export or SSR
AWS Amplify: Full-stack deployment
Self-hosted: Node.js server with PM2/Docker

Vercel
Docker

npm i -g vercel
vercel

Set environment variables in Vercel dashboard.

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t voicepact-client .
docker run -p 3000:3000 --env-file .env.local voicepact-client

Troubleshooting

Import errors after pip install

Ensure your virtual environment is activated:

source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

Redis connection refused

Check Redis is running:

redis-cli ping

If not running, start it using the instructions in Step 5.

Africa's Talking API errors

Common issues:

401 Unauthorized: Check your API key is correct
403 Forbidden: Verify phone numbers are registered in sandbox
Webhook timeout: Ensure ngrok is running and webhook URL is correct

Database locked errors (SQLite)

SQLite uses WAL mode for better concurrency. If you still get locked errors:

Ensure only one server instance is running
Check file permissions on the database
Consider upgrading to PostgreSQL for production

Port already in use

Kill existing process or use a different port:

# Find process using port 8000
lsof -i :8000

# Kill it
kill -9 <PID>

# Or use different port
uvicorn main:app --port 8001

Client can't connect to backend

Verify backend is running: curl http://localhost:8000/health
Check CORS settings include client URL
Ensure NEXT_PUBLIC_API_BASE_URL is correct in .env.local

Next Steps

Now that you have VoicePact installed:

Quickstart Guide

Create your first contract in 10 minutes

API Reference

Explore all API endpoints

Configuration

Learn about advanced configuration options

Architecture

Understand the system architecture

Get Started

Core Concepts

Features

Integrations

Analytics

Overview

System Requirements

Backend Requirements

Client Requirements

External Services

Backend Installation

1. Clone Repository

2. Python Environment Setup

3. Install Dependencies

4. Database Setup

5. Redis Installation

6. Environment Configuration

7. Africa’s Talking Setup

8. Webhook Setup (Development)

9. Start the Backend Server

10. Verify Installation

Client Installation

1. Navigate to Client Directory

2. Install Dependencies

3. Configure Environment

4. Start Development Server

5. Build for Production

Production Deployment

Backend Deployment Checklist

Client Deployment

Troubleshooting

Next Steps

Quickstart Guide

API Reference

Configuration

Architecture

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Integrations

Analytics

​Overview

​System Requirements

​Backend Requirements

​Client Requirements

​External Services

​Backend Installation

​1. Clone Repository

​2. Python Environment Setup

​3. Install Dependencies

​4. Database Setup

​5. Redis Installation

​6. Environment Configuration

​7. Africa’s Talking Setup

​8. Webhook Setup (Development)

​9. Start the Backend Server

​10. Verify Installation

​Client Installation

​1. Navigate to Client Directory

​2. Install Dependencies

​3. Configure Environment

​4. Start Development Server

​5. Build for Production

​Production Deployment

​Backend Deployment Checklist

​Client Deployment

​Troubleshooting

​Next Steps

Quickstart Guide

API Reference

Configuration

Architecture

Build docs developers (and LLMs) love

Overview

System Requirements

Backend Requirements

Client Requirements

External Services

Backend Installation

1. Clone Repository

2. Python Environment Setup

3. Install Dependencies

4. Database Setup

5. Redis Installation

6. Environment Configuration

7. Africa’s Talking Setup

8. Webhook Setup (Development)

9. Start the Backend Server

10. Verify Installation

Client Installation

1. Navigate to Client Directory

2. Install Dependencies

3. Configure Environment

4. Start Development Server

5. Build for Production

Production Deployment

Backend Deployment Checklist

Client Deployment

Troubleshooting

Next Steps