Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Promethean Conduit is a full-stack application consisting of a FastAPI backend and a React frontend. This guide outlines the procedures for deploying the system to production environments, specifically focusing on PythonAnywhere for hosting and MongoDB Atlas or Supabase for data persistence.
The deployment process involves configuring environment variables for AI services (Together.ai), database connectivity, and administrative security. The architecture leverages a decoupled frontend-backend structure where the frontend is served as static files while the backend handles API requests, AI orchestration, and database management.
Sources: DEPLOYMENT_GUIDE.md:1-25, frontend/src/App.js:15-16
Environment Configuration
Configuration is managed through environment variables stored in .env files for both the backend and frontend. These variables control database connections, security headers, and API integrations.
Backend Environment Variables
| Variable | Description | Example/Value |
|---|---|---|
MONGO_URL | MongoDB Atlas connection string | mongodb+srv://user:pass@cluster... |
DATABASE_URL | PostgreSQL URL (if using Supabase) | postgresql://postgres:pass@db... |
DB_NAME | Name of the database | promethean_conduit |
TOGETHER_API_KEY | Key for DeepSeek-V3 AI chat | your-together-api-key |
CORS_ORIGINS | Allowed domains for web access | https://yourusername.pythonanywhere.com |
ADMIN_SECRET | Password for admin panel access | promethean-conduit-2025 |
SUPER_ADMIN_USER_ID | ID for escalated AI privileges | admin_alex |
Sources: DEPLOYMENT_GUIDE.md:19-35, KEYS_AND_CREDENTIALS.md:95-107
Frontend Environment Variables
| Variable | Description | Default/Example |
|---|---|---|
REACT_APP_BACKEND_URL | Base URL for API requests | https://yourusername.pythonanywhere.com |
REACT_APP_ENABLE_VISUAL_EDITS | Enables AST-based UI editing | false |
ENABLE_HEALTH_CHECK | Enables monitoring endpoints | false |
Sources: DEPLOYMENT_GUIDE.md:195-201, frontend/craco.config.js:5-9
PythonAnywhere Deployment Workflow
Deployment on PythonAnywhere requires a manual configuration using Python 3.10 and a virtual environment. The following diagram illustrates the deployment sequence:
The system uses a custom WSGI configuration to load environment variables via python-dotenv before initializing the FastAPI application.
import sys
import os
from dotenv import load_dotenv
project_home = '/home/yourusername/EVI2_0/backend'
if project_home not in sys.path:
sys.path.insert(0, project_home)
load_dotenv(os.path.join(project_home, '.env'))
from server import app as application
Sources: DEPLOYMENT_GUIDE.md:65-95, DEPLOYMENT_GUIDE.md:104-118
Static File Configuration
On PythonAnywhere, the frontend build directory must be mapped correctly in the Web tab:
/:/home/yourusername/EVI2\_0/frontend/build/static:/home/yourusername/EVI2\_0/frontend/build/static
Sources: DEPLOYMENT_GUIDE.md:143-154
Database Initialization
The Promethean Conduit supports MongoDB (default) and PostgreSQL via Supabase.
Supabase (PostgreSQL) Schema
If opting for Supabase, the following entity relationships must be established. The library system uses a hierarchical structure: Classes -> Subclasses -> Entries.
The following SQL script initializes the core library structure required for the Truth Library feature:
CREATE TABLE library_classes (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
description TEXT,
"order" INTEGER,
created_at TIMESTAMP DEFAULT NOW()
);
-- Additional tables: library_subclasses, library_entries, glossary
Sources: DEPLOYMENT_GUIDE.md:175-225, DEPLOYMENT_GUIDE.md:255-263
Dev Server and Health Monitoring
The application includes specialized middleware for health monitoring and visual editing, configured via craco.config.js.
Health Endpoints
When ENABLE_HEALTH_CHECK is true, the following endpoints are exposed:
GET /health: Detailed system and compilation status.GET /health/ready: Readiness check for load balancers.GET /health/live: Liveness check for Kubernetes.GET /health/stats: Compilation statistics.
Sources: frontend/plugins/health-check/health-endpoints.js:25-150, frontend/craco.config.js:80-97
Visual Editing Endpoint
The edit-file endpoint allows for real-time UI modifications by manipulating the Abstract Syntax Tree (AST). It requires a supervisor password for authentication, passed via the x-api-key header.
Troubleshooting Deployment Issues
| Issue | Root Cause | Resolution |
|---|---|---|
| 500 Internal Error | Missing dependencies or .env | Check PA logs; run pip install -r requirements.txt. |
| CORS Errors | Incorrect CORS_ORIGINS | Ensure PA domain is in backend .env. |
| Blank Page | REACT_APP_BACKEND_URL | Verify frontend .env and rebuild with yarn build. |
| Database Failure | Network restrictions | Set MongoDB Atlas IP access to 0.0.0.0/0. |
Sources: DEPLOYMENT_GUIDE.md:290-325
The deployment of Promethean Conduit is complete once the backend is served via WSGI, the frontend static assets are mapped, and the AI/Database environment variables are successfully verified through the system's internal health checks.