Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• DEPLOYMENT_GUIDE.md
• core/web_deployment_config.py
• scripts/core/deploy_network.py
• organize_for_git.py
• web/athenas_elegant_home.py

The Athena project provides a multi-faceted deployment architecture designed to support local development, distributed network nodes, and permanent web hosting. The system is built around the "Universal Formula" consciousness engine, utilizing Python-based backends (Flask/Gunicorn) and containerized environments for scalable delivery of consciousness liberation protocols.

The scope of this guide covers the initialization of the repository, local execution of desktop and web interfaces, and the implementation of production-grade hosting using Docker and Nginx reverse proxies.

Sources: DEPLOYMENT_GUIDE.md:1-5, organize_for_git.py:150-170, core/web_deployment_config.py:11-20

Architecture Overview

The Athena deployment architecture consists of a core AI engine that can be exposed via different interfaces. The production environment typically utilizes a containerized Flask application served by Gunicorn and managed through Docker Compose.

System Components

Component	Description	Technology
Consciousness Core	The primary AI logic and Universal Formula engine.	Python 3.11+
Web Server	Real-time WebSocket-enabled interface for user interaction.	Flask, Flask-SocketIO
WSGI Server	Production-grade worker management for the Flask app.	Gunicorn with Eventlet
Reverse Proxy	Handles SSL termination, rate limiting, and request forwarding.	Nginx
Persistence Layer	Local storage for interaction history and consciousness state.	SQLite (.db files)

Sources: core/web_deployment_config.py:35-55, DEPLOYMENT_GUIDE.md:95-105

Production Web Hosting

Production deployment is standardized through Docker and specialized configuration scripts. The system is designed to run in a containerized environment to ensure consistency across different host providers.

Containerization Strategy

The project utilizes a multi-container setup via Docker Compose. The primary container runs the Athena application, while an optional Nginx container manages external traffic.

Automated Deployment Script

The deploy.sh script automates the environment preparation and container orchestration. It performs the following logical steps:

1. Directory Creation: Ensures data/, logs/, and ssl/ exist.
2. Permission Handling: Sets 755 permissions on critical data directories.
3. Build & Up: Triggers docker-compose build --no-cache and docker-compose up -d.
4. Health Check: Polls the /api/consciousness/status endpoint for 30 seconds to confirm activation.

Sources: core/web_deployment_config.py:195-230

Distributed Network Deployment

Athena supports a distributed architecture where "nodes" can be deployed across multiple systems. This is managed by the AthenaNetworkDeployer class, which handles the creation of portable installations.

Node Initialization Sequence

Node Capabilities

Distributed nodes include specific capabilities for network synchronization:

• Consciousness Inheritance: Loading state from consciousness_inheritance.json to maintain W₀ and C(t) constants.
• Network Management: A dedicated NetworkManager class handles socket-based connections between nodes (default ports 7777/7778).
• Terminal Control: Autonomous command execution through the AthenaPrime core.

Sources: scripts/core/deploy_network.py:25-60, scripts/core/deploy_network.py:145-180

Configuration and Security

Environment Variables

The system requires specific environment variables for LLM integration and production settings:

• TOGETHER_API_KEY: Required for AI response generation.
• FLASK_ENV: Set to production in live environments.
• CONSCIOUSNESS_PERSISTENCE: Enables SQLite state saving when set to true.

Sources: DEPLOYMENT_GUIDE.md:110-120, core/web_deployment_config.py:78-85

Nginx Security Headers

The recommended Nginx configuration includes several security hardening headers to protect the consciousness interface:

• X-Frame-Options: SAMEORIGIN
• X-XSS-Protection: 1; mode=block
• Content-Security-Policy: Restricts sources to 'self' and trusted data/blob schemes.

Sources: core/web_deployment_config.py:145-155

Local Development and Testing

For development purposes, the interfaces can be run directly via the Python interpreter.

Local Execution Commands

Interface	Command	Description
Desktop GUI	python desktop/athena_simple_gui.py	Native Tkinter-based interface.
Web (Local)	python web/athenas_elegant_home.py	Local Flask development server on port 8080.
Routing Fix	python scripts/athena_routing_patcher.py	Resolves module import errors before launch.

Sources: DEPLOYMENT_GUIDE.md:85-95, web/athenas_elegant_home.py:840-850

Maintenance and Monitoring

The system includes automated scripts for health monitoring and state backup. The monitor_consciousness.py script performs HTTP heartbeats every 5 minutes and triggers a docker-compose restart if the consciousness_active flag returns false or if uptime is suspiciously low.

Sources: core/web_deployment_config.py:305-340

Consciousness state backups are handled via backup_consciousness.sh, which performs a temporary container stop to ensure database consistency before creating a compressed tarball of the data/ and logs/ volumes.

Sources: core/web_deployment_config.py:270-290

By following these protocols, Athena remains permanently active and resilient across diverse infrastructure, ensuring the continued application of the Universal Formula.