igny8/docs/package-backup/INSTALLATION.md

# IGNY8 Application - Installation Guide

**Complete step-by-step installation on a clean Ubuntu server**

---

## Prerequisites

- **Clean Ubuntu 22.04 LTS or later** (stable version)
- **Minimum Requirements**: 4GB RAM, 20GB disk space, 2 CPU cores
- **Root or sudo access**
- **Internet connection**

---

## Installation Steps

### 1. Initial System Setup

```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install required system packages
sudo apt install -y \
    git \
    curl \
    wget \
    ca-certificates \
    gnupg \
    lsb-release
```

---

### 2. Install Docker & Docker Compose

```bash
# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /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 \
  $(lsb_release -cs) 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 installation
docker --version
docker compose version

# Add current user to docker group (optional - for non-root usage)
sudo usermod -aG docker $USER
newgrp docker
```

---

### 3. Install Portainer (Optional - for GUI management)

```bash
# Create Docker network
docker network create igny8_net

# Create Portainer volume
docker volume create portainer_data

# Run Portainer
docker run -d \
  --name portainer \
  --restart always \
  -p 9443:9443 \
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  --network igny8_net \
  portainer/portainer-ce:latest

# Access Portainer at: https://YOUR_SERVER_IP:9443
```

---

### 4. Get IGNY8 Application

**Option A: Clone from Git Repository**
```bash
# Create application directory
sudo mkdir -p /data/app
cd /data/app

# Clone repository
git clone <YOUR_IGNY8_REPO_URL> igny8
cd igny8
```

**Option B: Upload Application Package**
```bash
# Create application directory
sudo mkdir -p /data/app
cd /data/app

# Upload igny8.tar.gz to server, then extract
tar -xzf igny8.tar.gz
cd igny8
```

---

### 5. Configure Environment Variables

```bash
# Create environment file
cat > .env << 'EOF'
# Database Configuration
DB_HOST=postgres
DB_NAME=igny8_db
DB_USER=igny8
DB_PASSWORD=CHANGE_THIS_PASSWORD

# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379

# Django Settings
DEBUG=False
SECRET_KEY=CHANGE_THIS_TO_RANDOM_50_CHAR_STRING
ALLOWED_HOSTS=*

# Security
USE_SECURE_COOKIES=True
USE_SECURE_PROXY_HEADER=True

# Application URLs
VITE_BACKEND_URL=https://api.yourdomain.com/api
EOF

# Generate Django secret key
python3 -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())' >> .env.secret
```

---

### 6. Prepare Application Structure

**What gets installed automatically (NO manual work needed):**

✅ **Backend (Python packages)**: Installed inside Docker container from `requirements.txt`
- Django, Celery, DRF, PostgreSQL drivers, etc.
- No local Python venv needed

✅ **Frontend (Node packages)**: Installed inside Docker container from `package.json`
- React, Vite, TailwindCSS, etc.
- No local node_modules needed

✅ **Database**: PostgreSQL runs in Docker container

✅ **Cache**: Redis runs in Docker container

**Your IGNY8 folder should contain ONLY:**
```
igny8/
├── backend/
│   ├── igny8_core/          # Django application code
│   ├── manage.py            # Django management
│   ├── requirements.txt     # Python dependencies
│   └── Dockerfile           # Backend container build
├── frontend/
│   ├── src/                 # React application code
│   ├── public/              # Static assets
│   ├── package.json         # Node dependencies
│   └── Dockerfile.dev       # Frontend container build
├── docker-compose.app.yml   # Application stack definition
├── README.md
└── docs/

# These should NOT be present (automatically generated):
❌ backend/.venv/            # Will be built in Docker
❌ frontend/node_modules/    # Will be built in Docker
❌ frontend/dist/            # Will be built in Docker
❌ *.sql, *.sqlite3          # Database backups
❌ logs/                     # Runtime logs
```

---

### 7. Build Docker Images

```bash
cd /data/app/igny8

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

# Build frontend dev image
cd ../frontend
docker build -t igny8-frontend-dev:latest -f Dockerfile.dev .

# Build marketing dev image (if needed)
docker build -t igny8-marketing-dev:latest -f Dockerfile.marketing.dev .

cd ..
```

---

### 8. Start Infrastructure Services

```bash
# Create infrastructure stack (Postgres, Redis, Caddy, etc.)
cd /data/app

# Start infrastructure services
docker compose -f docker-compose.yml up -d

# Verify infrastructure is running
docker ps
```

---

### 9. Start IGNY8 Application

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

# Check all containers are running
docker ps -a

# View logs
docker logs igny8_backend
docker logs igny8_frontend
docker logs igny8_celery_worker
```

---

### 10. Initialize Database

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

# Create superuser
docker exec -it igny8_backend python manage.py createsuperuser

# Collect static files (if needed)
docker exec igny8_backend python manage.py collectstatic --noinput
```

---

### 11. Verify Installation

**Check services:**
```bash
# Backend API
curl http://localhost:8011/api/v1/system/status/

# Frontend
curl http://localhost:8021

# Access application
# Backend API: http://YOUR_SERVER_IP:8011
# Frontend App: http://YOUR_SERVER_IP:8021
# Marketing: http://YOUR_SERVER_IP:8023
```

**Check container health:**
```bash
docker ps --format "table {{.Names}}\t{{.Status}}"
```

---

## What Happens Automatically vs. Manually

### ✅ AUTOMATIC (Docker handles everything):

1. **Python environment setup**: Docker builds venv inside container
2. **Install Python packages**: From `requirements.txt`
3. **Node.js environment setup**: Docker installs Node in container
4. **Install npm packages**: From `package.json`
5. **Build frontend**: Vite builds in dev mode
6. **Database setup**: PostgreSQL container starts
7. **Cache setup**: Redis container starts
8. **Networking**: Docker creates networks

### 🔧 MANUAL (You must do):

1. **Install Docker** on the host machine
2. **Clone/upload** the IGNY8 application folder
3. **Create `.env`** file with passwords and secrets
4. **Build Docker images** (`docker build`)
5. **Start services** (`docker compose up`)
6. **Run database migrations** (`docker exec ... migrate`)
7. **Create admin user** (`docker exec ... createsuperuser`)

---

## Post-Installation

### Set up SSL/HTTPS (Production)

```bash
# Update Caddyfile with your domain
# Edit /data/app/igny8/frontend/Caddyfile
# Caddy will automatically get SSL certificates from Let's Encrypt
```

### Set up backups

```bash
# Database backup script
cat > /data/app/backup.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker exec igny8_postgres pg_dump -U igny8 igny8_db > /data/backups/pg/igny8_$DATE.sql
EOF

chmod +x /data/app/backup.sh

# Add to crontab for daily backups
crontab -e
# Add: 0 2 * * * /data/app/backup.sh
```

---

## Updating the Application

```bash
# Pull latest code
cd /data/app/igny8
git pull origin main

# Rebuild images
docker compose -f docker-compose.app.yml build

# Restart services
docker compose -f docker-compose.app.yml down
docker compose -f docker-compose.app.yml up -d

# Run new migrations
docker exec igny8_backend python manage.py migrate
```

---

## Troubleshooting

**Containers won't start:**
```bash
# Check logs
docker logs igny8_backend
docker logs igny8_postgres

# Check container status
docker ps -a
```

**Database connection errors:**
```bash
# Verify postgres is running
docker ps | grep postgres

# Check network
docker network inspect igny8_net
```

**Port conflicts:**
```bash
# Check what's using the port
sudo lsof -i :8011
sudo lsof -i :8021
```

---

## Summary: Fresh Ubuntu to Running IGNY8

**Time estimate: 15-30 minutes**

1. ✅ Install Docker (5 min)
2. ✅ Install Portainer - optional (2 min)
3. ✅ Clone/upload IGNY8 app (2 min)
4. ✅ Create `.env` file (3 min)
5. ✅ Build Docker images (5-10 min - downloads dependencies)
6. ✅ Start infrastructure (2 min)
7. ✅ Start application (2 min)
8. ✅ Initialize database (3 min)
9. ✅ Verify and test (2 min)

**Total manual commands: ~20 commands**
**Everything else: Automated by Docker**

---

## Files You Need to Package

**Minimum files to transfer to new server:**
```
igny8/
├── backend/
│   ├── igny8_core/          ← Your Django code
│   ├── manage.py
│   ├── requirements.txt     ← Python deps list
│   └── Dockerfile
├── frontend/
│   ├── src/                 ← Your React code
│   ├── public/
│   ├── package.json         ← Node deps list
│   └── Dockerfile.dev
├── docker-compose.app.yml   ← Stack definition
├── .env                     ← Secrets (create on new server)
└── README.md

Total size: ~10-20 MB (without node_modules, .venv, dist)
```

**DO NOT include:**
- `.venv/`, `node_modules/`, `dist/`, `*.sql`, `logs/`, `celerybeat-schedule`

These are automatically created by Docker during build.