# Installation Guide

Complete installation instructions for Cortex Linux across all supported platforms.

---

## Table of Contents

1. [System Requirements](#system-requirements)
2. [VirtualBox Installation](#virtualbox-installation)
3. [VMware Installation](#vmware-installation)
4. [Bare Metal Installation](#bare-metal-installation)
5. [Cloud Deployment](#cloud-deployment)
6. [Post-Installation Setup](#post-installation-setup)
7. [Troubleshooting](#troubleshooting)

---

## System Requirements

### Minimum Requirements

- **CPU**: x86_64 or ARM64 architecture, 2 cores minimum
- **RAM**: 2GB (4GB recommended for optimal AI performance)
- **Storage**: 10GB free disk space (20GB recommended)
- **Network**: Optional (for package updates, not required for AI functionality)

### Recommended Requirements

- **CPU**: 4+ cores, modern architecture (Intel Skylake+, AMD Zen+, ARM Cortex-A78+)
- **RAM**: 8GB+ for production workloads
- **Storage**: 50GB+ SSD for better performance
- **Network**: Broadband connection for initial setup

### Supported Platforms

- **Virtualization**: VirtualBox 6.0+, VMware Workstation/Player 15+, QEMU/KVM
- **Cloud**: AWS EC2, DigitalOcean Droplets, Google Cloud Compute Engine, Azure VMs
- **Bare Metal**: Standard x86_64 and ARM64 hardware
- **Containers**: Docker (with limitations), Podman

---

## VirtualBox Installation

### Prerequisites

1. Download and install [VirtualBox](https://www.virtualbox.org/wiki/Downloads) (6.0 or later)
2. Download Cortex Linux ISO from [releases.cortexlinux.org](https://releases.cortexlinux.org)

### Step-by-Step Installation

#### 1. Create Virtual Machine

```bash
# Using VirtualBox CLI
VBoxManage createvm --name "Cortex Linux" --ostype "Linux_64" --register
VBoxManage modifyvm "Cortex Linux" --memory 4096 --cpus 2
VBoxManage modifyvm "Cortex Linux" --graphicscontroller vboxsvga
VBoxManage modifyvm "Cortex Linux" --audio none
VBoxManage createhd --filename "CortexLinux.vdi" --size 20000
VBoxManage storagectl "Cortex Linux" --name "SATA Controller" --add sata
VBoxManage storageattach "Cortex Linux" --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium "CortexLinux.vdi"
VBoxManage storageattach "Cortex Linux" --storagectl "SATA Controller" --port 1 --device 0 --type dvddrive --medium cortex-linux-1.0.0.iso
```

Or use the VirtualBox GUI:

1. Click "New" → Name: "Cortex Linux"
2. Type: Linux, Version: Other Linux (64-bit)
3. Memory: 4096 MB (or more)
4. Create virtual hard disk: 20GB+ (VDI, dynamically allocated)
5. Settings → Storage → Controller: IDE → Add optical drive → Select ISO

#### 2. Boot from ISO

1. Start the virtual machine
2. Select "Install Cortex Linux" from the boot menu
3. Follow the graphical installer

#### 3. Installation Process

The installer will guide you through:

- **Language Selection**: Choose your preferred language
- **Keyboard Layout**: Select keyboard mapping
- **Disk Partitioning**: 
  - Automatic (recommended for beginners)
  - Manual (for advanced users)
- **User Account**: Create root and user accounts
- **Network Configuration**: Optional network setup
- **AI Engine Configuration**: Initial Sapiens engine setup

#### 4. Complete Installation

After installation completes:

```bash
# Reboot into installed system
sudo reboot

# Remove installation media
# In VirtualBox: Settings → Storage → Remove ISO
```

---

## VMware Installation

### Prerequisites

- VMware Workstation Pro/Player 15+ or VMware Fusion 11+ (macOS)
- Cortex Linux ISO image

### Installation Steps

#### 1. Create New Virtual Machine

```bash
# Using VMware CLI (vmrun)
vmware-vmx --new-sn=CortexLinux.vmx
```

Or via GUI:

1. File → New Virtual Machine
2. Typical configuration
3. Install from disc image file → Select Cortex Linux ISO
4. Linux → Other Linux 5.x kernel 64-bit
5. Name: "Cortex Linux"
6. Disk size: 20GB+ (split into multiple files recommended)
7. Customize hardware:
   - Memory: 4096 MB+
   - Processors: 2+
   - Network: NAT or Bridged

#### 2. Install Operating System

1. Power on the virtual machine
2. Boot from ISO
3. Follow installation wizard (same as VirtualBox)
4. Complete installation and reboot

#### 3. Install VMware Tools (Optional)

```bash
# After installation
sudo apt update
sudo apt install open-vm-tools
sudo systemctl enable open-vm-tools
sudo systemctl start open-vm-tools
```

---

## Bare Metal Installation

### Creating Bootable Media

#### USB Drive (Linux/macOS)

```bash
# Identify USB device
lsblk  # or diskutil list on macOS

# Unmount USB drive
sudo umount /dev/sdX  # Replace X with your device

# Write ISO to USB
sudo dd if=cortex-linux-1.0.0.iso of=/dev/sdX bs=4M status=progress oflag=sync

# On macOS
sudo dd if=cortex-linux-1.0.0.iso of=/dev/rdiskX bs=1m
```

#### USB Drive (Windows)

1. Download [Rufus](https://rufus.ie/) or [Balena Etcher](https://www.balena.io/etcher/)
2. Select Cortex Linux ISO
3. Select USB drive
4. Click "Start" or "Flash"

### BIOS/UEFI Configuration

1. **Enter BIOS/UEFI**: Press F2, F10, F12, or Del during boot (varies by manufacturer)
2. **Disable Secure Boot**: Required for Cortex Linux installation
3. **Set Boot Priority**: USB drive first, then hard disk
4. **Enable UEFI Mode**: Recommended for modern systems
5. **Save and Exit**

### Installation Process

1. **Boot from USB**: Select USB drive from boot menu
2. **Select Installation Mode**:
   - Graphical installer (recommended)
   - Text-based installer (for headless systems)
3. **Partitioning Options**:
   - **Automatic**: Use entire disk (erases all data)
   - **Manual**: Custom partition layout
     - `/boot` (EFI): 512MB (UEFI) or 256MB (BIOS)
     - `/`: 20GB+ (root filesystem)
     - `/home`: Optional (user data)
     - `swap`: 2-4GB (or equal to RAM for hibernation)
4. **Complete Installation**: Follow prompts, reboot when finished

### Post-Installation Hardware Configuration

```bash
# Check hardware detection
sudo lshw -short

# Install proprietary drivers (if needed)
sudo apt update
sudo apt install linux-firmware

# Configure graphics (if needed)
sudo apt install nvidia-driver  # For NVIDIA GPUs
# or
sudo apt install mesa-vulkan-drivers  # For AMD/Intel GPUs
```

---

## Cloud Deployment

### AWS EC2

#### Launch Instance

```bash
# Using AWS CLI
aws ec2 run-instances \
  --image-id ami-xxxxx \
  --instance-type t3.medium \
  --key-name your-key-pair \
  --security-group-ids sg-xxxxx \
  --subnet-id subnet-xxxxx \
  --user-data file://cortex-init.sh
```

Or via AWS Console:

1. **EC2 Dashboard** → Launch Instance
2. **AMI**: Select Cortex Linux AMI (or upload custom)
3. **Instance Type**: t3.medium or larger (2 vCPU, 4GB RAM minimum)
4. **Key Pair**: Select or create SSH key pair
5. **Network**: Configure VPC, subnet, security groups
6. **Storage**: 20GB+ gp3 SSD
7. **Launch Instance**

#### Security Group Configuration

Required ports:
- **22**: SSH (TCP)
- **8080**: Cortex AI HTTP API (TCP, optional, restrict source IP)
- **80/443**: Web services (TCP, if applicable)

```bash
# Configure security group
aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxx \
  --protocol tcp \
  --port 22 \
  --cidr 0.0.0.0/0  # Restrict to your IP in production
```

#### Connect and Verify

```bash
# SSH into instance
ssh -i your-key.pem ec2-user@your-instance-ip

# Verify Cortex installation
cortex-ai --version
systemctl status cortex-ai
```

### DigitalOcean Droplet

#### Create Droplet

```bash
# Using doctl CLI
doctl compute droplet create cortex-linux \
  --image cortex-linux-1-0-0 \
  --size s-2vcpu-4gb \
  --region nyc1 \
  --ssh-keys your-ssh-key-id
```

Or via DigitalOcean Console:

1. **Create** → Droplets
2. **Image**: Cortex Linux (or upload custom image)
3. **Plan**: Basic, $24/month (4GB RAM, 2 vCPU) or larger
4. **Datacenter**: Select region
5. **Authentication**: SSH keys or password
6. **Create Droplet**

#### Post-Creation Setup

```bash
# SSH into droplet
ssh root@your-droplet-ip

# Update system
apt update && apt upgrade -y

# Verify AI engine
cortex-ai test
```

### Google Cloud Platform

#### Create VM Instance

```bash
# Using gcloud CLI
gcloud compute instances create cortex-linux \
  --image-family=cortex-linux \
  --image-project=cortex-linux-cloud \
  --machine-type=n1-standard-2 \
  --zone=us-central1-a \
  --boot-disk-size=20GB
```

Or via GCP Console:

1. **Compute Engine** → VM Instances → Create
2. **Name**: cortex-linux
3. **Machine Type**: n1-standard-2 (2 vCPU, 7.5GB RAM) or larger
4. **Boot Disk**: Cortex Linux image, 20GB+
5. **Firewall**: Allow HTTP/HTTPS traffic (if needed)
6. **Create**

#### Configure Firewall

```bash
# Allow SSH
gcloud compute firewall-rules create allow-ssh \
  --allow tcp:22 \
  --source-ranges 0.0.0.0/0 \
  --description "Allow SSH"

# Allow Cortex API (restrict source in production)
gcloud compute firewall-rules create allow-cortex-api \
  --allow tcp:8080 \
  --source-ranges 0.0.0.0/0 \
  --description "Allow Cortex AI API"
```

### Azure Virtual Machines

```bash
# Using Azure CLI
az vm create \
  --resource-group cortex-rg \
  --name cortex-linux \
  --image CortexLinux:cortex-linux:1.0.0:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys
```

---

## Post-Installation Setup

### Initial System Configuration

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

# Set timezone
sudo timedatectl set-timezone America/New_York

# Configure hostname
sudo hostnamectl set-hostname cortex-linux

# Verify AI engine status
sudo systemctl status cortex-ai
```

### Configure Cortex AI Service

```bash
# Check service status
systemctl status cortex-ai

# Enable on boot
sudo systemctl enable cortex-ai

# Start service
sudo systemctl start cortex-ai

# View logs
journalctl -u cortex-ai -f
```

### Configure HTTP API (Optional)

Edit `/etc/cortex-ai/config.yaml`:

```yaml
server:
  host: 0.0.0.0
  port: 8080
  enable_cors: true
  
security:
  api_key_required: false  # Set to true for production
  allowed_ips: []  # Restrict access if needed
  
ai:
  model_path: /usr/lib/cortex-ai/models/sapiens-0.27b
  max_memory_mb: 512
  num_threads: 4
```

Restart service:

```bash
sudo systemctl restart cortex-ai
```

### Test Installation

```bash
# Test CLI
cortex-ai reason "What is 2+2?"

# Test HTTP API
curl -X POST http://localhost:8080/reason \
  -H "Content-Type: application/json" \
  -d '{"query": "Test query"}'

# Check system resources
cortex-ai status
```

### Network Configuration

```bash
# Configure static IP (if needed)
sudo nano /etc/netplan/01-netcfg.yaml

# Example configuration
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: false
      addresses:
        - 192.168.1.100/24
      gateway4: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 8.8.4.4

# Apply changes
sudo netplan apply
```

### Firewall Configuration

```bash
# Install UFW (if not present)
sudo apt install ufw

# Allow SSH
sudo ufw allow 22/tcp

# Allow Cortex API (if exposing)
sudo ufw allow 8080/tcp

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status
```

---

## Troubleshooting

### Installation Issues

#### Boot Failure

**Symptoms**: System fails to boot from installation media

**Solutions**:
```bash
# Verify ISO integrity
sha256sum cortex-linux-1.0.0.iso
# Compare with published checksum

# Try different boot mode
# UEFI vs Legacy BIOS
# Disable Secure Boot

# Check USB drive
# Use different USB port
# Try different USB drive
```

#### Installation Hangs

**Symptoms**: Installer freezes during installation

**Solutions**:
```bash
# Check system resources
# Ensure sufficient RAM (4GB+)
# Verify disk space (20GB+)

# Try text-based installer
# Boot with: cortex text

# Check for hardware compatibility
# Review kernel logs: dmesg | tail -100
```

#### Partitioning Errors

**Symptoms**: Cannot create or format partitions

**Solutions**:
```bash
# Check disk for errors
sudo badblocks -v /dev/sda

# Verify partition table
sudo fdisk -l /dev/sda

# Use manual partitioning
# Create partitions manually in installer

# For dual-boot systems
# Ensure sufficient unallocated space
# Verify boot mode (UEFI/BIOS) matches existing OS
```

### Post-Installation Issues

#### AI Service Not Starting

**Symptoms**: `systemctl status cortex-ai` shows failed state

**Solutions**:
```bash
# Check service logs
journalctl -u cortex-ai -n 50

# Verify model files
ls -lh /usr/lib/cortex-ai/models/

# Check permissions
sudo chown -R cortex-ai:cortex-ai /usr/lib/cortex-ai/

# Verify system resources
free -h
df -h

# Reinstall AI engine
sudo apt remove cortex-ai
sudo apt install cortex-ai
```

#### HTTP API Not Responding

**Symptoms**: API endpoints return connection refused

**Solutions**:
```bash
# Check if service is running
systemctl status cortex-ai

# Verify port is listening
sudo netstat -tlnp | grep 8080
# or
sudo ss -tlnp | grep 8080

# Check firewall
sudo ufw status
sudo ufw allow 8080/tcp

# Verify configuration
cat /etc/cortex-ai/config.yaml

# Test locally
curl http://localhost:8080/health
```

#### Performance Issues

**Symptoms**: Slow AI responses, high CPU usage

**Solutions**:
```bash
# Check system resources
htop
# or
top

# Verify CPU affinity
taskset -p $(pgrep cortex-ai)

# Adjust thread count in config
# /etc/cortex-ai/config.yaml
# ai.num_threads: 2  # Reduce if CPU-bound

# Check memory usage
free -h
# Increase swap if needed
sudo swapon --show
```

### Cloud-Specific Issues

#### AWS: Instance Not Accessible

```bash
# Check security groups
aws ec2 describe-security-groups --group-ids sg-xxxxx

# Verify key pair
ssh -i your-key.pem -v ec2-user@instance-ip

# Check instance status
aws ec2 describe-instance-status --instance-ids i-xxxxx
```

#### DigitalOcean: Droplet Not Booting

```bash
# Check droplet status
doctl compute droplet get droplet-id

# Access console via web interface
# DigitalOcean → Droplets → Your Droplet → Access → Launch Console

# Verify image
doctl compute image list
```

### Getting Help

If you encounter issues not covered here:

1. **Check Logs**: `journalctl -xe` for system-wide issues
2. **Review Documentation**: [FAQ](FAQ.md), [Technical Specifications](Technical-Specifications.md)
3. **Community Support**: [GitHub Issues](https://github.com/cortexlinux/cortex/issues)
4. **Search Existing Issues**: Check if your problem has been reported

---

## Next Steps

After successful installation:

1. **Configure AI Integration**: [AI Integration Guide](AI-Integration.md)
2. **Explore Use Cases**: [Use Cases and Tutorials](Use-Cases-and-Tutorials.md)
3. **Review Security**: [Security and Compliance](Security-and-Compliance.md)
4. **Read Developer Docs**: [Developer Documentation](Developer-Documentation.md)

---

*Last updated: 2024*