--- title: "Environment Setup" description: "Set up your development environment for AINative Studio" canonical: "https://docs.ainative.studio/docs/getting-started/environment-setup" last-updated: "2026-09-23T01:51:08.820Z" --- # Environment Setup Source: https://docs.ainative.studio/docs/getting-started/environment-setup > Set up your development environment for AINative Studio Complete guide for setting up development, staging, and production environments for the AINative Studio. ## Table of Contents 1. [Development Environment](#development-environment) 2. [Staging Environment](#staging-environment) 3. [Production Environment](#production-environment) 4. [Environment Variables Reference](#environment-variables-reference) 5. [Database Setup](#database-setup) 6. [Redis Setup](#redis-setup) 7. [Local Testing](#local-testing) 8. [Docker Setup](#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: ```bash ## 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 ```bash 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)**: ```bash brew install postgresql@15 brew services start postgresql@15 ## Create database createdb zerodb ``` **Ubuntu/Debian**: ```bash 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](https://www.postgresql.org/download/windows/) #### 3. Install Redis **macOS (Homebrew)**: ```bash brew install redis brew services start redis ``` **Ubuntu/Debian**: ```bash sudo apt-get install redis-server sudo systemctl start redis sudo systemctl enable redis ``` **Windows**: Use [Memurai](https://www.memurai.com/) or Redis via WSL2 #### 4. Configure Environment Variables Create `.env` file in `src/backend/`: ```bash ## 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 ```bash cd src/backend ## Run migrations alembic upgrade head ## Verify migrations alembic current ``` #### 6. Start Development Server ```bash ## 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 ```bash ## 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 ```bash npm install -g @railway/cli railway login ``` #### 2. Link Project ```bash cd /path/to/core railway link ``` #### 3. Configure Staging Environment ```bash ## 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 ```bash ## Railway provisions PostgreSQL automatically ## Get database URL railway variables get DATABASE_URL ## Run migrations railway run alembic upgrade head ``` #### 5. Deploy to Staging ```bash ## 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 ```bash ## 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 ```bash ## 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 ```bash ## 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 ```bash ## 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 ```bash ## 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 ```bash ## 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 ```bash ## Create database createdb zerodb ## Run migrations cd src/backend alembic upgrade head ``` ### Create Migration ```bash ## 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 ```bash ## Rollback one version alembic downgrade -1 ## Rollback to specific revision alembic downgrade ## Show history alembic history ``` ### Database Backup ```bash ## Backup pg_dump -Fc zerodb > backup.dump ## Restore pg_restore -d zerodb backup.dump ``` --- ## Redis Setup ### Verify Redis ```bash ## 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 ```bash 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 ```bash ## Run integration tests pytest -m integration ## Run with verbose output pytest -v -m integration ``` ### Run Smoke Tests ```bash ## Start local server uvicorn app.main:app --reload & ## Run smoke tests python scripts/smoke_tests.py --env staging ``` ### Run Load Tests ```bash ## Install Locust pip install locust ## Run load tests cd scripts/load_tests locust -f locustfile.py --host http://localhost:8000 ``` --- ## Docker Setup ### Build Image ```bash ## 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 ```bash ## 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 ```bash ## 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 ```bash ## 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 ```bash ## 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 ```bash ## Find process using port 8000 lsof -i :8000 ## Kill process kill -9 ## Or use different port uvicorn app.main:app --port 8001 ``` ### Import Errors ```bash ## 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](https://docs.python.org/3/tutorial/venv.html) - [PostgreSQL Documentation](https://www.postgresql.org/docs/) - [Redis Documentation](https://redis.io/documentation) - [Docker Documentation](https://docs.docker.com/) - [Railway Documentation](https://docs.railway.app/) - [FastAPI Documentation](https://fastapi.tiangolo.com/) --- **Last Updated**: 2025-10-14 **Version**: 1.0.0