Environment Setup

Complete guide for setting up development, staging, and production environments for the AINative Studio.

Table of Contents

1. Development Environment
2. Staging Environment
3. Production Environment
4. Environment Variables Reference
5. Database Setup
6. Redis Setup
7. Local Testing
8. Docker Setup

---

Development Environment

Prerequisites

• Python 3.11 or higher
• PostgreSQL 15+
• Redis 7+
• Docker (optional but recommended)
• Git

Quick Start with Docker

The fastest way to get started:

# Clone repository
git clone https://github.com/AINative-Studio/core.git
cd core

# Start all services with Docker Compose
docker-compose -f docker-compose.mcp-bridge.yml up -d

# Check services are running
docker-compose -f docker-compose.mcp-bridge.yml ps

# View logs
docker-compose -f docker-compose.mcp-bridge.yml logs -f mcp-bridge

# Stop services
docker-compose -f docker-compose.mcp-bridge.yml down

Access the API at: http://localhost:8000

Manual Setup

1. Install Python Dependencies

cd src/backend

# Create virtual environment
python3.11 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

2. Install PostgreSQL

macOS (Homebrew):

brew install postgresql@15
brew services start postgresql@15

# Create database
createdb zerodb

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install postgresql-15 postgresql-contrib-15

# Start service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database
sudo -u postgres createdb zerodb

Windows: Download and install from PostgreSQL website

3. Install Redis

macOS (Homebrew):

brew install redis
brew services start redis

Ubuntu/Debian:

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

Windows: Use Memurai or Redis via WSL2

4. Configure Environment Variables

Create .env file in src/backend/:

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/zerodb

# Redis
REDIS_URL=redis://localhost:6379

# Security
SECRET_KEY=dev-secret-key-minimum-32-characters-long
JWT_SECRET_KEY=dev-jwt-secret-key-minimum-32-chars
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60

# Application
ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=DEBUG

# MCP Configuration
ZERODB_MCP_ENABLED=true
ZERODB_MCP_MAX_OPERATIONS=100
ZERODB_MCP_CACHE_TTL=3600

# Rate Limiting (lenient for dev)
RATE_LIMIT_PER_MINUTE=1000
RATE_LIMIT_PER_HOUR=10000

# CORS
BACKEND_CORS_ORIGINS=["http://localhost:3000","http://localhost:8000"]

5. Run Database Migrations

cd src/backend

# Run migrations
alembic upgrade head

# Verify migrations
alembic current

6. Start Development Server

# Standard mode
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# With auto-reload for development
uvicorn app.main:app --reload --log-level debug

7. Verify Installation

# Health check
curl http://localhost:8000/api/v1/public/zerodb/mcp/health

# List capabilities
curl http://localhost:8000/api/v1/public/zerodb/mcp/capabilities

---

Staging Environment

Railway Setup

1. Install Railway CLI

npm install -g @railway/cli
railway login

2. Link Project

cd /path/to/core
railway link

3. Configure Staging Environment

# Switch to staging environment
railway environment staging

# Set environment variables
railway variables set ENVIRONMENT=staging
railway variables set DEBUG=false
railway variables set LOG_LEVEL=INFO

4. Configure Database

# Railway provisions PostgreSQL automatically
# Get database URL
railway variables get DATABASE_URL

# Run migrations
railway run alembic upgrade head

5. Deploy to Staging

# Deploy
railway up --service mcp-bridge --environment staging

# Check status
railway status

# View logs
railway logs --service mcp-bridge

6. Configure Custom Domain

In Railway dashboard:

1. Go to Settings → Domains
2. Add custom domain: api-staging.ainative.studio
3. Configure DNS with provided CNAME

---

Production Environment

Production Setup Checklist

• Database configured with SSL
• Redis configured with authentication
• All secrets rotated
• Rate limiting configured
• Monitoring and alerts enabled
• Backup strategy implemented
• Blue-green deployment configured
• Custom domain configured
• SSL certificates configured
• Health checks configured

1. Configure Production Environment

# Switch to production
railway environment production

# Set critical variables
railway variables set ENVIRONMENT=production
railway variables set DEBUG=false
railway variables set LOG_LEVEL=INFO
railway variables set SECRET_KEY="$(openssl rand -base64 64)"
railway variables set JWT_SECRET_KEY="$(openssl rand -base64 64)"

2. Database Configuration

# Use PostgreSQL with SSL
railway variables set DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"

# Set connection pool
railway variables set DB_POOL_SIZE=20
railway variables set DB_MAX_OVERFLOW=10

# Run migrations
railway run alembic upgrade head

3. Redis Configuration

# Use Redis with authentication
railway variables set REDIS_URL="redis://:password@host:6379"

# Set Redis TTL
railway variables set REDIS_CACHE_TTL=3600

4. Security Configuration

# Rate limiting (strict for production)
railway variables set RATE_LIMIT_PER_MINUTE=60
railway variables set RATE_LIMIT_PER_HOUR=1000

# CORS (restrict to production domains)
railway variables set BACKEND_CORS_ORIGINS='["https://app.ainative.studio"]'

# API keys
railway variables set ZERODB_API_KEY="$(openssl rand -hex 32)"

5. Monitoring Configuration

# Sentry
railway variables set SENTRY_DSN="your-sentry-dsn"

# Logging
railway variables set LOG_LEVEL=INFO
railway variables set LOG_FORMAT=json

6. Deploy to Production

# Deploy using CD pipeline
# Create a release tag
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# Or manual deploy
railway up --service mcp-bridge --environment production

---

Environment Variables Reference

Database Configuration

Variable	Description	Development	Staging	Production
DATABASE_URL	PostgreSQL connection string	postgresql://localhost/zerodb	Railway provided	Railway provided + SSL
DB_POOL_SIZE	Connection pool size	5	10	20
DB_MAX_OVERFLOW	Max overflow connections	5	10	10
DB_POOL_RECYCLE	Connection recycle time (seconds)	3600	1800	1800

Redis Configuration

Variable	Description	Development	Staging	Production
REDIS_URL	Redis connection string	redis://localhost:6379	Railway provided	Railway provided + auth
REDIS_CACHE_TTL	Default cache TTL (seconds)	300	1800	3600
REDIS_MAX_CONNECTIONS	Max Redis connections	10	20	50

Security Configuration

Variable	Description	Development	Staging	Production
SECRET_KEY	Application secret key	Dev key	Secure random	Secure random (rotated)
JWT_SECRET_KEY	JWT signing key	Dev key	Secure random	Secure random (rotated)
JWT_ALGORITHM	JWT algorithm	HS256	HS256	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Token expiry	60	60	30

Application Configuration

Variable	Description	Development	Staging	Production
ENVIRONMENT	Environment name	development	staging	production
DEBUG	Debug mode	true	false	false
LOG_LEVEL	Logging level	DEBUG	INFO	INFO
LOG_FORMAT	Log format	text	json	json

MCP Configuration

Variable	Description	Development	Staging	Production
ZERODB_MCP_ENABLED	Enable MCP bridge	true	true	true
ZERODB_MCP_MAX_OPERATIONS	Max operations	100	100	100
ZERODB_MCP_CACHE_TTL	MCP cache TTL	300	1800	3600
ZERODB_MCP_RATE_LIMIT	MCP rate limit	1000	100	60

Rate Limiting

Variable	Description	Development	Staging	Production
RATE_LIMIT_PER_MINUTE	Requests per minute	1000	100	60
RATE_LIMIT_PER_HOUR	Requests per hour	10000	1000	1000
RATE_LIMIT_ENABLED	Enable rate limiting	false	true	true

CORS Configuration

Variable	Description	Development	Staging	Production
BACKEND_CORS_ORIGINS	Allowed origins (JSON array)	["http://localhost:3000"]	["https://staging.app.com"]	["https://app.ainative.studio"]
CORS_ALLOW_CREDENTIALS	Allow credentials	true	true	true

---

Database Setup

Initialize Database

# Create database
createdb zerodb

# Run migrations
cd src/backend
alembic upgrade head

Create Migration

# Create new migration
alembic revision --autogenerate -m "Description of changes"

# Review migration file
# Edit if needed: src/backend/alembic/versions/xxx_description.py

# Apply migration
alembic upgrade head

Rollback Migration

# Rollback one version
alembic downgrade -1

# Rollback to specific revision
alembic downgrade <revision-id>

# Show history
alembic history

Database Backup

# Backup
pg_dump -Fc zerodb > backup.dump

# Restore
pg_restore -d zerodb backup.dump

---

Redis Setup

Verify Redis

# Connect to Redis
redis-cli

# Test connection
ping
# Should return: PONG

# Set test key
SET test "hello"
GET test

# Monitor Redis
redis-cli MONITOR

Redis Configuration

Edit /usr/local/etc/redis.conf (macOS) or /etc/redis/redis.conf (Linux):

# Set max memory
maxmemory 256mb
maxmemory-policy allkeys-lru

# Enable persistence
save 900 1
save 300 10
save 60 10000

# Set password (production)
requirepass your-secure-password

---

Local Testing

Run Unit Tests

cd src/backend

# Run all tests
pytest

# Run specific test file
pytest app/zerodb/tests/test_mcp_bridge_enhanced.py

# Run with coverage
pytest --cov=app.zerodb.services --cov-report=html

# View coverage report
open htmlcov/index.html

Run Integration Tests

# Run integration tests
pytest -m integration

# Run with verbose output
pytest -v -m integration

Run Smoke Tests

# Start local server
uvicorn app.main:app --reload &

# Run smoke tests
python scripts/smoke_tests.py --env staging

Run Load Tests

# Install Locust
pip install locust

# Run load tests
cd scripts/load_tests
locust -f locustfile.py --host http://localhost:8000

---

Docker Setup

Build Image

# Build for development
docker build -f src/backend/Dockerfile.mcp-bridge \
  --target application \
  -t mcp-bridge:dev \
  src/backend

# Build for production
docker build -f src/backend/Dockerfile.mcp-bridge \
  --target production \
  -t mcp-bridge:latest \
  --build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --build-arg VCS_REF=$(git rev-parse --short HEAD) \
  --build-arg VERSION=1.0.0 \
  src/backend

Run Container

# Run development container
docker run -d \
  --name mcp-bridge \
  -p 8000:8000 \
  -e DATABASE_URL="postgresql://postgres:postgres@host.docker.internal:5432/zerodb" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  mcp-bridge:dev

# View logs
docker logs -f mcp-bridge

# Execute commands in container
docker exec -it mcp-bridge bash

# Stop container
docker stop mcp-bridge
docker rm mcp-bridge

Docker Compose

# Start all services
docker-compose -f docker-compose.mcp-bridge.yml up -d

# Start with monitoring
docker-compose -f docker-compose.mcp-bridge.yml --profile monitoring up -d

# Scale services
docker-compose -f docker-compose.mcp-bridge.yml up -d --scale mcp-bridge=3

# View logs
docker-compose -f docker-compose.mcp-bridge.yml logs -f

# Stop services
docker-compose -f docker-compose.mcp-bridge.yml down

# Stop and remove volumes
docker-compose -f docker-compose.mcp-bridge.yml down -v

---

Troubleshooting

Database Connection Issues

# Check PostgreSQL is running
pg_isready

# Check connection
psql -d zerodb -c "SELECT 1;"

# Check DATABASE_URL
echo $DATABASE_URL

# Test connection from Python
python -c "from app.db.session import engine; print(engine.connect())"

Redis Connection Issues

# Check Redis is running
redis-cli ping

# Check REDIS_URL
echo $REDIS_URL

# Test connection
redis-cli -u $REDIS_URL ping

Port Already in Use

# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>

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

Import Errors

# Ensure virtual environment is activated
which python

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

# Check Python path
python -c "import sys; print(sys.path)"

---

Additional Resources

• Python Virtual Environments
• PostgreSQL Documentation
• Redis Documentation
• Docker Documentation
• Railway Documentation
• FastAPI Documentation

---

Last Updated: 2025-10-14 Version: 1.0.0