# IGNY8 Technology Stack & Infrastructure

**Last Updated:** 2025-01-XX  
**Purpose:** Complete technology stack, infrastructure setup, Docker deployment, and fresh installation guide for the IGNY8 platform.

---

## Table of Contents

1. [Executive Summary](#executive-summary)
2. [Technology Stack](#technology-stack)
3. [System Architecture](#system-architecture)
4. [Core Architecture Principles](#core-architecture-principles)
5. [Infrastructure Components](#infrastructure-components)
6. [External Service Integrations](#external-service-integrations)
7. [Deployment Architecture](#deployment-architecture)
8. [Complete Fresh Installation Guide](#complete-fresh-installation-guide)

---

## Executive Summary

**IGNY8** is a full-stack SaaS platform for SEO keyword management and AI-driven content generation. The system is built with modern technologies and follows a multi-tenant architecture with complete account isolation.

### Key Metrics

- **Architecture**: Multi-tenant SaaS with account isolation
- **Backend**: Django 5.2+ with Django REST Framework
- **Frontend**: React 19 with TypeScript
- **Database**: PostgreSQL 15
- **Task Queue**: Celery with Redis
- **Deployment**: Docker-based containerization
- **Reverse Proxy**: Caddy (HTTPS termination)
- **AI Functions**: 5 primary AI operations
- **Modules**: 5 core modules (Planner, Writer, Thinker, System, Billing)

---

## Technology Stack

### Backend Stack

| Component | Technology | Version | Purpose |
|-----------|------------|---------|---------|
| **Framework** | Django | 5.2.7+ | Web framework |
| **API Framework** | Django REST Framework | Latest | RESTful API |
| **Database** | PostgreSQL | 15 | Primary database |
| **Database Adapter** | psycopg2-binary | Latest | PostgreSQL Python adapter |
| **Task Queue** | Celery | 5.3.0+ | Asynchronous tasks |
| **Cache/Broker** | Redis | 7 | Celery broker & caching |
| **Authentication** | JWT | PyJWT 2.8.0+ | Token-based auth |
| **HTTP Client** | Requests | 2.31.0+ | External API calls |
| **WSGI Server** | Gunicorn | Latest | Production server |
| **Static Files** | WhiteNoise | Latest | Static file serving |
| **HTML Parsing** | BeautifulSoup4 | 4.12.0+ | HTML parsing & processing |
| **System Utils** | psutil | 5.9.0+ | System & process utilities |
| **Docker Client** | docker | 7.0.0+ | Docker API client |
| **Django Packages** | django-filter | Latest | Advanced filtering |
| **Django Packages** | django-cors-headers | Latest | CORS handling |

### Frontend Stack

| Component | Technology | Version | Purpose |
|-----------|------------|---------|---------|
| **Framework** | React | 19.0.0 | UI library |
| **Framework** | React DOM | 19.0.0 | DOM rendering |
| **Language** | TypeScript | 5.7.2 | Type safety |
| **Build Tool** | Vite | 6.1.0 | Build tool & dev server |
| **Styling** | Tailwind CSS | 4.0.8 | Utility-first CSS |
| **State Management** | Zustand | 5.0.8 | Lightweight state |
| **Routing** | React Router | v7.9.5 | Client-side routing |
| **HTTP Client** | Fetch API | Native | API communication |
| **SEO** | react-helmet-async | 2.0.5 | Dynamic head management |

### Frontend UI Libraries

| Library | Version | Purpose |
|---------|---------|---------|
| **Icons** | @heroicons/react | 2.2.0 | Icon library |
| **Charts** | apexcharts | 4.1.0 | Chart library |
| **Charts** | react-apexcharts | 1.7.0 | React wrapper for ApexCharts |
| **Calendar** | @fullcalendar/core | 6.1.15 | Calendar component |
| **Calendar** | @fullcalendar/react | 6.1.15 | React wrapper for FullCalendar |
| **Calendar** | @fullcalendar/daygrid | 6.1.15 | Day grid view |
| **Calendar** | @fullcalendar/timegrid | 6.1.15 | Time grid view |
| **Calendar** | @fullcalendar/interaction | 6.1.15 | Calendar interactions |
| **Calendar** | @fullcalendar/list | 6.1.15 | List view |
| **Maps** | @react-jvectormap/core | 1.0.4 | Vector map library |
| **Maps** | @react-jvectormap/world | 1.1.2 | World map component |
| **Carousel** | swiper | 11.2.3 | Carousel/slider component |
| **Date Picker** | flatpickr | 4.6.13 | Date/time picker |
| **Drag & Drop** | react-dnd | 16.0.1 | Drag and drop functionality |
| **Drag & Drop** | react-dnd-html5-backend | 16.0.1 | HTML5 drag & drop backend |
| **File Upload** | react-dropzone | 14.3.5 | File upload component |

### Frontend Utilities

| Library | Version | Purpose |
|---------|---------|---------|
| **Class Utils** | clsx | 2.1.1 | Conditional class names |
| **Tailwind Utils** | tailwind-merge | 3.0.1 | Merge Tailwind classes |

### Frontend Development Tools

| Tool | Version | Purpose |
|------|---------|---------|
| **Linter** | ESLint | 9.19.0 | Code linting |
| **TypeScript Linter** | typescript-eslint | 8.22.0 | TypeScript linting |
| **Vite Plugin** | @vitejs/plugin-react | 4.3.4 | React plugin for Vite |
| **SVG Plugin** | vite-plugin-svgr | 4.3.0 | SVG as React components |
| **PostCSS** | postcss | 8.5.2 | CSS processing |
| **Tailwind PostCSS** | @tailwindcss/postcss | 4.0.8 | Tailwind PostCSS plugin |

### Infrastructure Stack

| Component | Technology | Purpose |
|-----------|------------|---------|
| **Containerization** | Docker | Application containers |
| **Orchestration** | Docker Compose | Multi-container orchestration |
| **Reverse Proxy** | Caddy | HTTPS termination & routing |
| **Database Admin** | pgAdmin | PostgreSQL administration |
| **File Management** | FileBrowser | Web-based file management |
| **Container Management** | Portainer | Docker container management |

### External Services

| Service | Purpose | Integration |
|---------|---------|-------------|
| **OpenAI API** | Text generation (GPT models) | API integration |
| **OpenAI DALL-E** | Image generation | API integration |
| **Runware API** | Alternative image generation | API integration |
| **WordPress** | Content publishing | REST API integration |
| **Stripe** | Payment processing | Webhook integration (planned) |

---

## System Architecture

### High-Level Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Client Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Browser    │  │   Mobile     │  │   Admin      │     │
│  │   (React)    │  │   (Future)   │  │   Panel      │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
└─────────┼──────────────────┼──────────────────┼─────────────┘
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │
┌────────────────────────────┼──────────────────────────────┐
│                    Reverse Proxy Layer                     │
│                    ┌───────────────┐                       │
│                    │     Caddy     │                       │
│                    │  (HTTPS/443)  │                       │
│                    └───────┬───────┘                       │
└────────────────────────────┼──────────────────────────────┘
                             │
┌────────────────────────────┼──────────────────────────────┐
│                    Application Layer                       │
│  ┌──────────────┐              ┌──────────────┐          │
│  │   Frontend   │              │    Backend   │          │
│  │   (React)    │◄─────────────┤   (Django)   │          │
│  │   Port 8021  │   REST API   │   Port 8011  │          │
│  └──────────────┘              └──────┬───────┘          │
│                                       │                   │
│                              ┌────────┴────────┐         │
│                              │  Celery Worker  │         │
│                              │  (Async Tasks)  │         │
│                              └────────┬────────┘         │
└───────────────────────────────────────┼──────────────────┘
                                        │
┌───────────────────────────────────────┼──────────────────┐
│                    Data Layer                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  PostgreSQL  │  │    Redis     │  │   Storage    │  │
│  │   (Database) │  │ (Cache/Broker)│  │   (Files)    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└──────────────────────────────────────────────────────────┘
                                        │
┌───────────────────────────────────────┼──────────────────┐
│                  External Services                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   OpenAI     │  │   Runware    │  │  WordPress   │  │
│  │   (GPT/DALL-E)│  │  (Images)   │  │   (Publish)  │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└──────────────────────────────────────────────────────────┘
```

### Request Flow

```
1. User Request
   ↓
2. Browser (React Frontend)
   ↓
3. Caddy Reverse Proxy (HTTPS Termination)
   ↓
4. Django Backend (API Endpoint)
   ↓
5. AccountContextMiddleware (Account Isolation)
   ↓
6. ViewSet (Business Logic)
   ↓
7. Serializer (Validation)
   ↓
8. Model (Database)
   ↓
9. Response (JSON)
   ↓
10. Frontend (UI Update)
```

### AI Task Flow

```
1. User Action (e.g., "Auto Cluster Keywords")
   ↓
2. Frontend API Call
   ↓
3. Backend Endpoint (ViewSet Action)
   ↓
4. Celery Task Queued
   ↓
5. Task ID Returned to Frontend
   ↓
6. Frontend Polls Progress Endpoint
   ↓
7. Celery Worker Processes Task
   ↓
8. AIProcessor Makes API Calls
   ↓
9. Results Saved to Database
   ↓
10. Progress Updates Sent
   ↓
11. Frontend Displays Results
```

---

## Core Architecture Principles

### 1. Configuration-Driven Everything

**Principle**: Zero HTML/JSX duplication - All UI rendered from configuration.

**Implementation**:
- **Frontend**: Config files in `/config/pages/` and `/config/snippets/`
- **Backend**: DRF serializers and ViewSet actions
- **Templates**: 4 universal templates (Dashboard, Table, Form, System)

**Benefits**:
- Single source of truth
- Easy maintenance
- Consistent UI/UX
- Rapid feature development

### 2. Multi-Tenancy Foundation

**Principle**: Complete account isolation with automatic filtering.

**Implementation**:
- All models inherit `AccountBaseModel`
- All ViewSets inherit `AccountModelViewSet`
- Middleware injects account context from JWT
- Site > Sector hierarchy for content organization

**Benefits**:
- Data security
- Scalability
- Resource isolation
- Simplified access control

### 3. Template System (4 Universal Templates)

**Principle**: Reusable templates for all page types.

| Template | Purpose | Usage |
|----------|---------|-------|
| **DashboardTemplate** | Module home pages | KPIs, workflow steps, charts |
| **TablePageTemplate** | CRUD table pages | Keywords, Clusters, Tasks, etc. |
| **FormPageTemplate** | Settings/form pages | Settings, Integration, etc. |
| **SystemPageTemplate** | System/admin pages | Logs, Status, Monitoring |

### 4. Unified AI Processor

**Principle**: Single interface for all AI operations.

**Implementation**:
- Single `AIEngine` class orchestrates all AI operations
- All AI functions inherit from `BaseAIFunction`
- Manual and automated workflows use same functions
- Account-specific API keys and model configuration

**Benefits**:
- Code reusability
- Consistent error handling
- Unified logging
- Easy to extend

### 5. Module-Based Organization

**Principle**: Clear module boundaries with shared utilities.

**Modules**:
- **Planner**: Keywords, Clusters, Ideas
- **Writer**: Tasks, Content, Images
- **Thinker**: Prompts, Author Profiles, Strategies, Image Testing
- **System**: Settings, Integrations, AI Configuration
- **Billing**: Credits, Transactions, Usage
- **Auth**: Accounts, Users, Sites, Sectors

---

## Infrastructure Components

### Docker Architecture

The system uses a two-stack Docker architecture:

1. **Infrastructure Stack (`igny8-infra`)**: Shared services
2. **Application Stack (`igny8-app`)**: Application-specific services

### Infrastructure Stack Services

| Service | Container Name | Port | Purpose |
|---------|----------------|------|---------|
| **PostgreSQL** | `igny8_postgres` | 5432 (internal) | Database |
| **Redis** | `igny8_redis` | 6379 (internal) | Cache & Celery broker |
| **pgAdmin** | `igny8_pgadmin` | 5050:80 | Database administration |
| **FileBrowser** | `igny8_filebrowser` | 8080:80 | File management |
| **Caddy** | `igny8_caddy` | 80:80, 443:443 | Reverse proxy & HTTPS |
| **Setup Helper** | `setup-helper` | - | Utility container |

### Application Stack Services

| Service | Container Name | Port | Purpose |
|---------|----------------|------|---------|
| **Backend** | `igny8_backend` | 8011:8010 | Django REST API |
| **Frontend** | `igny8_frontend` | 8021:5173 | React application (main app) |
| **Marketing Dev** | `igny8_marketing_dev` | 8023:5174 | Marketing site (dev server) |
| **Celery Worker** | `igny8_celery_worker` | - | Async task processing |
| **Celery Beat** | `igny8_celery_beat` | - | Scheduled tasks |

### Network Configuration

- **Network Name**: `igny8_net`
- **Type**: External bridge network
- **Purpose**: Inter-container communication
- **Creation**: Must be created manually before starting stacks

### Volume Management

**Infrastructure Volumes**:
- `pgdata`: PostgreSQL database data
- `redisdata`: Redis data
- `pgadmin_data`: pgAdmin configuration
- `filebrowser_db`: FileBrowser database
- `caddy_data`: Caddy SSL certificates
- `caddy_config`: Caddy configuration

**Application Volumes**:
- Host mounts for application code
- Host mounts for logs
- Docker socket for container management

### Port Allocation

| Service | External Port | Internal Port | Access |
|---------|---------------|---------------|--------|
| **pgAdmin** | 5050 | 80 | http://localhost:5050 |
| **FileBrowser** | 8080 | 80 | http://localhost:8080 |
| **Caddy** | 80, 443 | 80, 443 | https://domain.com |
| **Backend** | 8011 | 8010 | http://localhost:8011 |
| **Frontend** | 8021 | 5173 | http://localhost:8021 |
| **Marketing Dev** | 8023 | 5174 | http://localhost:8023 |

---

## External Service Integrations

### OpenAI Integration

**Purpose**: Text generation and image generation

**Services Used**:
- GPT models for text generation
- DALL-E for image generation

**Configuration**:
- API key stored per account in `IntegrationSettings`
- Model selection per account
- Cost tracking per request

### Runware Integration

**Purpose**: Alternative image generation service

**Configuration**:
- API key stored per account
- Model selection (e.g., `runware:97@1`)
- Image type selection (realistic, artistic, cartoon)

### WordPress Integration

**Purpose**: Content publishing

**Configuration**:
- WordPress URL per site
- Username and password stored per site
- REST API integration for publishing

**Workflow**:
1. Content generated in IGNY8
2. Images attached
3. Content published to WordPress via REST API
4. Status updated in IGNY8

### Stripe Integration (Planned)

**Purpose**: Payment processing

**Status**: Planned for future implementation

**Features**:
- Subscription management
- Payment processing
- Webhook integration

---

## Deployment Architecture

### Deployment Model

**Container-Based**: All services run in Docker containers

**Stack Separation**:
- Infrastructure stack runs independently
- Application stack depends on infrastructure stack
- Both stacks share the same Docker network

### Environment Configuration

**Backend Environment Variables**:
- Database connection (PostgreSQL)
- Redis connection
- Django settings (DEBUG, SECRET_KEY, etc.)
- JWT settings
- Celery configuration

**Frontend Environment Variables**:
- Backend API URL
- Environment (development/production)

**Infrastructure Environment Variables**:
- PostgreSQL credentials
- pgAdmin credentials
- FileBrowser configuration

### Health Checks

**Backend Health Check**:
- Endpoint: `/api/v1/system/status/`
- Interval: 30 seconds
- Timeout: 10 seconds
- Retries: 3

**PostgreSQL Health Check**:
- Command: `pg_isready`
- Interval: 20 seconds
- Timeout: 3 seconds
- Retries: 5

**Redis Health Check**:
- Command: `redis-cli ping`
- Interval: 20 seconds
- Timeout: 3 seconds
- Retries: 5

### Scaling Considerations

**Horizontal Scaling**:
- Multiple Celery workers can be added
- Multiple backend instances can be added (with load balancer)
- Frontend can be scaled independently

**Vertical Scaling**:
- Database can be scaled with more resources
- Redis can be scaled with more memory
- Containers can be allocated more CPU/memory

### Backup & Recovery

**Database Backups**:
- PostgreSQL dumps stored in `/data/backups`
- Automated backup scripts
- Point-in-time recovery support

**Volume Backups**:
- Docker volume backups
- Application code backups
- Configuration backups

---

## Summary

The IGNY8 platform is built on a modern, scalable architecture using:

- **Django 5.2+** for the backend API
- **React 19** for the frontend
- **PostgreSQL 15** for data storage
- **Celery & Redis** for async processing
- **Docker** for containerization
- **Caddy** for reverse proxy and HTTPS

The architecture follows principles of:
- Configuration-driven development
- Multi-tenancy with account isolation
- Module-based organization
- Unified AI processing
- Template-based UI rendering

This architecture supports scalability, maintainability, and rapid feature development while ensuring data security and isolation.

---

## Complete Fresh Installation Guide

This guide covers installing IGNY8 on a fresh Ubuntu VPS from scratch, including all prerequisites, Docker, Portainer, and the complete IGNY8 application stack.

### Prerequisites

**System Requirements**:
- **OS**: Ubuntu 22.04 LTS or 24.04 LTS (recommended)
- **RAM**: Minimum 4GB (8GB+ recommended for production)
- **CPU**: 2+ cores (4+ cores recommended)
- **Storage**: 50GB+ free space
- **Network**: Static IP address or domain name
- **Access**: Root or sudo access

**Domain Setup** (Optional but recommended):
- Domain name pointing to server IP
- DNS records configured:
  - `igny8.com` → Server IP
  - `www.igny8.com` → Server IP
  - `app.igny8.com` → Server IP
  - `api.igny8.com` → Server IP

---

### Step 1: Initial Server Setup

#### 1.1 Update System

```bash
# Update package list
sudo apt update && sudo apt upgrade -y

# Install essential tools
sudo apt install -y curl wget git vim ufw software-properties-common apt-transport-https ca-certificates gnupg lsb-release
```

#### 1.2 Configure Firewall

```bash
# Enable UFW firewall
sudo ufw enable

# Allow SSH (adjust port if needed)
sudo ufw allow 22/tcp

# Allow HTTP and HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Allow Portainer (if accessing directly)
sudo ufw allow 9000/tcp

# Check firewall status
sudo ufw status
```

#### 1.3 Create Application User (Optional but Recommended)

```bash
# Create user for application
sudo adduser igny8
sudo usermod -aG sudo igny8

# Switch to application user
su - igny8
```

---

### Step 2: Install Docker

#### 2.1 Install Docker Engine

```bash
# Remove old Docker versions if any
sudo apt remove -y docker docker-engine docker.io containerd runc

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Set up Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verify Docker installation
sudo docker --version
sudo docker compose version
```

#### 2.2 Configure Docker (Optional)

```bash
# Add user to docker group (to run docker without sudo)
sudo usermod -aG docker $USER

# Apply group changes (logout/login or use newgrp)
newgrp docker

# Test Docker without sudo
docker run hello-world

# Configure Docker to start on boot
sudo systemctl enable docker
sudo systemctl start docker
```

---

### Step 3: Install Portainer

#### 3.1 Create Portainer Volume

```bash
# Create volume for Portainer data
docker volume create portainer_data
```

#### 3.2 Run Portainer Container

```bash
# Run Portainer Community Edition
docker run -d \
  -p 9000:9000 \
  --name=portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest
```

#### 3.3 Access Portainer

1. Open browser: `http://your-server-ip:9000`
2. Create admin account (first-time setup)
3. Select "Docker" environment
4. Portainer dashboard will load

**Note**: For production, configure Portainer behind Caddy reverse proxy with HTTPS.

---

### Step 4: Create Docker Network

```bash
# Create external network for IGNY8 services
docker network create igny8_net

# Verify network creation
docker network ls | grep igny8_net
```

**Important**: This network must exist before starting IGNY8 services.

---

### Step 5: Prepare Application Directories

#### 5.1 Create Directory Structure

```bash
# Create main application directory
sudo mkdir -p /data/app
sudo chown $USER:$USER /data/app

# Create subdirectories
mkdir -p /data/app/igny8
mkdir -p /data/app/logs
mkdir -p /data/backups
```

#### 5.2 Clone or Copy IGNY8 Repository

**Option A: Git Clone** (if repository is available):
```bash
cd /data/app
git clone <repository-url> igny8
cd igny8
```

**Option B: Copy Files** (if files are already available):
```bash
# Copy application files to /data/app/igny8
# Ensure all files are in place:
# - backend/
# - frontend/
# - docker-compose.yml (infrastructure)
# - docker-compose.app.yml (application)
```

---

### Step 6: Install Infrastructure Stack

#### 6.1 Navigate to Infrastructure Directory

```bash
cd /data/app
# Infrastructure docker-compose.yml should be here
```

#### 6.2 Configure Infrastructure

**Edit `docker-compose.yml`** (if needed):
- Update PostgreSQL credentials
- Update pgAdmin credentials
- Configure Caddy domain names
- Set volume paths

#### 6.3 Start Infrastructure Stack

```bash
# Start infrastructure services
docker compose -f docker-compose.yml -p igny8-infra up -d

# Verify services are running
docker compose -f docker-compose.yml -p igny8-infra ps

# Check logs
docker compose -f docker-compose.yml -p igny8-infra logs -f
```

**Infrastructure Services**:
- PostgreSQL (database)
- Redis (cache/broker)
- pgAdmin (database admin)
- FileBrowser (file management)
- Caddy (reverse proxy)

#### 6.4 Verify Infrastructure

```bash
# Check PostgreSQL
docker exec igny8_postgres pg_isready

# Check Redis
docker exec igny8_redis redis-cli ping

# Check all containers
docker ps | grep igny8
```

---

### Step 7: Build Application Images

#### 7.1 Build Backend Image

```bash
cd /data/app/igny8/backend

# Build backend Docker image
docker build -t igny8-backend:latest -f Dockerfile .

# Verify image
docker images | grep igny8-backend
```

#### 7.2 Build Frontend Images

```bash
cd /data/app/igny8/frontend

# Build main app dev image
docker build -t igny8-frontend-dev:latest -f Dockerfile.dev .

# Build marketing dev image
docker build -t igny8-marketing-dev:latest -f Dockerfile.marketing.dev .

# Verify images
docker images | grep igny8-frontend
docker images | grep igny8-marketing
```

**Note**: For production, also build production images:
```bash
# Production frontend image
docker build -t igny8-frontend:latest -f Dockerfile .

# Production marketing image
docker build -t igny8-marketing:latest -f Dockerfile.marketing .
```

---

### Step 8: Configure Application

#### 8.1 Configure Environment Variables

**Backend Environment** (in `docker-compose.app.yml` or `.env`):
```bash
# Database
DB_HOST=postgres
DB_NAME=igny8_db
DB_USER=igny8
DB_PASSWORD=your_secure_password

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Django
SECRET_KEY=your_django_secret_key
DEBUG=False
USE_SECURE_COOKIES=True
USE_SECURE_PROXY_HEADER=True

# JWT Settings (if needed)
JWT_SECRET_KEY=your_jwt_secret_key
```

**Frontend Environment**:
```bash
# In docker-compose.app.yml
VITE_BACKEND_URL=https://api.igny8.com/api
```

#### 8.2 Configure Caddy

**Edit Caddyfile** for domain routing:
- `igny8.com` → Marketing site
- `app.igny8.com` → Main application
- `api.igny8.com` → Backend API

---

### Step 9: Start Application Stack

#### 9.1 Navigate to Application Directory

```bash
cd /data/app/igny8
```

#### 9.2 Start Application Services

```bash
# Start application stack
docker compose -f docker-compose.app.yml -p igny8-app up -d

# Verify services
docker compose -f docker-compose.app.yml -p igny8-app ps

# Check logs
docker compose -f docker-compose.app.yml -p igny8-app logs -f
```

#### 9.3 Verify All Services

```bash
# Check all containers
docker ps

# Check network connectivity
docker network inspect igny8_net

# Test backend health
curl http://localhost:8011/api/v1/system/status/

# Test frontend
curl http://localhost:8021
```

---

### Step 10: Initialize Database

#### 10.1 Run Migrations

```bash
# Execute migrations
docker exec igny8_backend python manage.py migrate

# Create superuser (optional)
docker exec -it igny8_backend python manage.py createsuperuser
```

#### 10.2 Load Initial Data (if needed)

```bash
# Load default plans, industries, etc.
docker exec igny8_backend python manage.py loaddata initial_data.json
```

---

### Step 11: Configure Caddy for HTTPS

#### 11.1 Update Caddyfile

Ensure Caddyfile includes:
- Domain names
- SSL certificate auto-generation
- Reverse proxy rules

#### 11.2 Restart Caddy

```bash
# Restart Caddy container
docker compose -f docker-compose.yml -p igny8-infra restart igny8_caddy

# Check Caddy logs
docker logs igny8_caddy
```

---

### Step 12: Verify Installation

#### 12.1 Check Service Status

```bash
# Infrastructure services
docker compose -f docker-compose.yml -p igny8-infra ps

# Application services
docker compose -f docker-compose.app.yml -p igny8-app ps

# All services should show "Up" status
```

#### 12.2 Test Access

1. **Marketing Site**: `https://igny8.com` (or `http://your-ip:8023` for dev)
2. **Main App**: `https://app.igny8.com` (or `http://your-ip:8021` for dev)
3. **Backend API**: `https://api.igny8.com/api/v1/system/status/`
4. **Portainer**: `http://your-ip:9000`
5. **pgAdmin**: `http://your-ip:5050`

#### 12.3 Check Logs

```bash
# Backend logs
docker logs igny8_backend

# Frontend logs
docker logs igny8_frontend

# Marketing logs
docker logs igny8_marketing_dev

# Check for errors
docker logs igny8_backend 2>&1 | grep -i error
```

---

### Step 13: Post-Installation Configuration

#### 13.1 Configure Integration Settings

1. Access application: `https://app.igny8.com`
2. Sign up or log in
3. Navigate to Settings → Integration
4. Configure:
   - OpenAI API key
   - Runware API key (optional)
   - WordPress credentials (per site)

#### 13.2 Create First Site

1. Navigate to Settings → Sites
2. Create a new site
3. Configure WordPress integration (if needed)
4. Create sectors (1-5 per site)

#### 13.3 Set Up Monitoring (Optional)

- Configure health checks
- Set up log rotation
- Configure backup scripts
- Set up monitoring alerts

---

### Troubleshooting

#### Common Issues

**1. Port Already in Use**:
```bash
# Check what's using the port
sudo lsof -i :8011
sudo lsof -i :8021

# Stop conflicting services or change ports in docker-compose
```

**2. Network Not Found**:
```bash
# Recreate network
docker network rm igny8_net
docker network create igny8_net

# Restart services
docker compose -f docker-compose.app.yml -p igny8-app restart
```

**3. Database Connection Failed**:
```bash
# Check PostgreSQL is running
docker ps | grep postgres

# Check network connectivity
docker exec igny8_backend ping postgres

# Verify credentials in docker-compose
```

**4. Permission Denied**:
```bash
# Fix directory permissions
sudo chown -R $USER:$USER /data/app
sudo chmod -R 755 /data/app
```

**5. Caddy SSL Issues**:
```bash
# Check Caddy logs
docker logs igny8_caddy

# Verify domain DNS points to server
nslookup igny8.com

# Check firewall allows port 80/443
sudo ufw status
```

---

### Maintenance Commands

#### View Logs
```bash
# All services
docker compose -f docker-compose.app.yml -p igny8-app logs -f

# Specific service
docker logs -f igny8_backend
```

#### Restart Services
```bash
# Restart all app services
docker compose -f docker-compose.app.yml -p igny8-app restart

# Restart specific service
docker restart igny8_backend
```

#### Update Application
```bash
# Pull latest code
cd /data/app/igny8
git pull

# Rebuild images
docker build -t igny8-backend:latest -f backend/Dockerfile ./backend
docker build -t igny8-frontend-dev:latest -f frontend/Dockerfile.dev ./frontend

# Restart services
docker compose -f docker-compose.app.yml -p igny8-app up -d
```

#### Backup Database
```bash
# Create backup
docker exec igny8_postgres pg_dump -U igny8 igny8_db > /data/backups/backup_$(date +%Y%m%d_%H%M%S).sql
```

---

### Security Checklist

- [ ] Firewall configured (UFW)
- [ ] SSH key-based authentication enabled
- [ ] Strong passwords for all services
- [ ] Docker socket permissions secured
- [ ] Caddy HTTPS configured
- [ ] Environment variables secured
- [ ] Regular backups scheduled
- [ ] Log rotation configured
- [ ] Monitoring set up
- [ ] Security updates automated

---

### Next Steps

After installation:

1. **Configure Domain**: Update DNS records and Caddy configuration
2. **Set Up Backups**: Configure automated database backups
3. **Monitor Logs**: Set up log aggregation and monitoring
4. **Performance Tuning**: Optimize Docker resources and database
5. **Security Hardening**: Review security settings and access controls

---

## Summary

The complete installation process includes:

1. **Server Setup**: Ubuntu VPS preparation
2. **Docker Installation**: Docker Engine and Docker Compose
3. **Portainer Setup**: Container management UI
4. **Network Creation**: Docker network for services
5. **Infrastructure Stack**: PostgreSQL, Redis, Caddy, etc.
6. **Application Build**: Build Docker images
7. **Application Deployment**: Start application services
8. **Database Initialization**: Run migrations
9. **HTTPS Configuration**: Caddy SSL setup
10. **Verification**: Test all services

This installation guide provides a complete path from a fresh Ubuntu server to a fully operational IGNY8 platform.

