Installation Guide¶

🎯 Overview¶

This guide helps you install and set up ALwrity on your system. You'll learn how to install the platform, configure it for your needs, and get started with your first content creation workflow.

🚀 What You'll Achieve¶

Complete Setup¶

Platform Installation: Install ALwrity on your preferred system
Configuration Setup: Configure the platform for your specific needs
Initial Testing: Test the installation and verify functionality
First Content: Create your first piece of content

System Requirements¶

Hardware Requirements: Meet minimum hardware specifications
Software Dependencies: Install required software dependencies
Network Configuration: Configure network and connectivity
Security Setup: Set up basic security configurations

📋 System Requirements¶

Minimum Requirements¶

Hardware: - CPU: 2+ cores, 2.0+ GHz - RAM: 4+ GB - Storage: 20+ GB available space - Network: Stable internet connection

Software: - Operating System: Windows 10+, macOS 10.15+, Ubuntu 18.04+ - Python: 3.9 or higher - Node.js: 16+ for frontend development - Docker: 20.10+ (optional but recommended)

Recommended Requirements¶

Hardware: - CPU: 4+ cores, 3.0+ GHz - RAM: 8+ GB - Storage: 50+ GB SSD - Network: 100+ Mbps connection

Software: - Operating System: Latest stable version - Python: 3.11+ (latest stable) - Node.js: 18+ (LTS version) - Docker: Latest stable version

🛠️ Installation Methods¶

Method 1: Docker Installation (Recommended)¶

Prerequisites¶

# Install Docker and Docker Compose
# Windows: Download from https://docker.com/products/docker-desktop
# macOS: Download from https://docker.com/products/docker-desktop
# Ubuntu: Follow official Docker installation guide

# Verify installation
docker --version
docker-compose --version

Installation Steps¶

# 1. Clone the repository
git clone https://github.com/your-org/alwrity.git
cd alwrity

# 2. Copy environment template
cp .env.template .env

# 3. Edit environment variables
nano .env
# Configure your database, API keys, and other settings

# 4. Build and start services
docker-compose up -d

# 5. Check service status
docker-compose ps

# 6. View logs
docker-compose logs -f

Environment Configuration¶

# .env file configuration
# Database Configuration
DATABASE_URL=postgresql://alwrity:password@db:5432/alwrity
POSTGRES_DB=alwrity
POSTGRES_USER=alwrity
POSTGRES_PASSWORD=your_secure_password

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false

# Security Configuration
SECRET_KEY=your-secret-key-here
JWT_SECRET=your-jwt-secret-here

# External Services
OPENAI_API_KEY=your-openai-api-key
STABILITY_API_KEY=your-stability-api-key
GOOGLE_SEARCH_API_KEY=your-google-search-api-key

# Frontend Configuration
REACT_APP_API_URL=http://localhost:8000
REACT_APP_ENVIRONMENT=development

Method 2: Manual Installation¶

Backend Installation¶

# 1. Create virtual environment
python -m venv venv

# 2. Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up database
# Install PostgreSQL and create database
createdb alwrity

# 5. Run database migrations
python -m alembic upgrade head

# 6. Start backend server
uvicorn app:app --reload --host 0.0.0.0 --port 8000

Frontend Installation¶

# 1. Navigate to frontend directory
cd frontend

# 2. Install dependencies
npm install

# 3. Create environment file
cp .env.template .env

# 4. Configure environment variables
# Edit .env file with your configuration

# 5. Start development server
npm start

Method 3: Cloud Installation¶

AWS Installation¶

# 1. Launch EC2 instance
# Use Ubuntu 20.04 LTS AMI
# Instance type: t3.medium or larger

# 2. Connect to instance
ssh -i your-key.pem ubuntu@your-instance-ip

# 3. Install Docker
sudo apt update
sudo apt install docker.io docker-compose
sudo usermod -aG docker ubuntu

# 4. Clone and run ALwrity
git clone https://github.com/your-org/alwrity.git
cd alwrity
docker-compose up -d

Google Cloud Installation¶

# 1. Create Compute Engine instance
# Use Ubuntu 20.04 LTS
# Machine type: e2-medium or larger

# 2. Connect to instance
gcloud compute ssh your-instance-name

# 3. Install Docker
sudo apt update
sudo apt install docker.io docker-compose
sudo usermod -aG docker $USER

# 4. Deploy ALwrity
git clone https://github.com/your-org/alwrity.git
cd alwrity
docker-compose up -d

📊 Configuration Setup¶

Database Configuration¶

PostgreSQL Setup:

-- Create database and user
CREATE DATABASE alwrity;
CREATE USER alwrity_user WITH ENCRYPTED PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE alwrity TO alwrity_user;

-- Configure connection pooling
-- Edit postgresql.conf
max_connections = 200
shared_buffers = 256MB
effective_cache_size = 1GB

Database Migration:

# Run initial migrations
python -m alembic upgrade head

# Create admin user
python scripts/create_admin.py

# Seed initial data
python scripts/seed_data.py

API Configuration¶

Environment Variables:

# Production Configuration
DEBUG=false
LOG_LEVEL=INFO
API_HOST=0.0.0.0
API_PORT=8000

# Security Settings
SECRET_KEY=your-production-secret-key
JWT_SECRET=your-production-jwt-secret
CORS_ORIGINS=https://yourdomain.com

# Rate Limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60

# External API Configuration
OPENAI_API_KEY=your-openai-key
OPENAI_MODEL=gpt-4
STABILITY_API_KEY=your-stability-key

Frontend Configuration¶

Environment Setup:

# Frontend Environment Variables
REACT_APP_API_URL=https://api.yourdomain.com
REACT_APP_ENVIRONMENT=production
REACT_APP_GOOGLE_ANALYTICS_ID=GA-XXXXXXXXX
REACT_APP_SENTRY_DSN=your-sentry-dsn

# Feature Flags
REACT_APP_ENABLE_SEO_DASHBOARD=true
REACT_APP_ENABLE_BLOG_WRITER=true
REACT_APP_ENABLE_LINKEDIN_WRITER=true

🎯 Initial Setup¶

First-Time Configuration¶

Admin User Creation:

# Create admin user
python scripts/create_admin.py

# Input required information:
# - Email address
# - Password
# - Full name
# - Organization

Basic Configuration:

# backend/config/initial_setup.py
from backend.services.config_service import ConfigService

async def initial_setup():
    """Perform initial system setup."""
    config_service = ConfigService()

    # Set up default configurations
    await config_service.set_default_configs()

    # Create default content templates
    await config_service.create_default_templates()

    # Set up default user roles
    await config_service.setup_default_roles()

    print("Initial setup completed successfully!")

System Verification¶

Health Check:

# Check backend health
curl http://localhost:8000/health

# Expected response:
{
  "status": "healthy",
  "database": "healthy",
  "redis": "healthy",
  "timestamp": "2024-01-01T12:00:00Z"
}

Frontend Verification:

# Check frontend
curl http://localhost:3000

# Should return HTML page

🛠️ Post-Installation Setup¶

SSL/HTTPS Configuration¶

Nginx SSL Setup:

serv    } serv

href="#__codelineno-15-1"># /etc/nginx/sites-available/alwrity er { listen 80; server_name yourdomain.com; return 301 https://$server_name$request_uri; pan> er { listen 443 ssl; server_name yourdomain.com; ssl_certificate /etc/ssl/certs/yourdomain.crt; ssl_certificate_key /etc/ssl/private/yourdomain.key; location /api/ { proxy_pass http://localhost:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

Backup Configuration¶

Database Backup:

#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups"
DB_NAME="alwrity"

# Create backup
pg_dump $DB_NAME > $BACKUP_DIR/alwrity_backup_$DATE.sql

# Compress backup
gzip $BACKUP_DIR/alwrity_backup_$DATE.sql

# Remove old backups (keep last 30 days)
find $BACKUP_DIR -name "alwrity_backup_*.sql.gz" -mtime +30 -delete

echo "Backup completed: alwrity_backup_$DATE.sql.gz"

Automated Backup:

# Add to crontab
# Daily backup at 2 AM
0 2 * * * /path/to/backup.sh

# Weekly full backup
0 2 * * 0 /path/to/full_backup.sh

📈 Installation Verification¶

System Tests¶

API Endpoint Tests:

# test_installation.py
import requests
import json

def test_api_endpoints():
    """Test critical API endpoints."""
    base_url = "http://localhost:8000"

    # Test health endpoint
    response = requests.get(f"{base_url}/health")
    assert response.status_code == 200

    # Test API documentation
    response = requests.get(f"{base_url}/docs")
    assert response.status_code == 200

    # Test authentication
    response = requests.get(f"{base_url}/api/auth/me")
    assert response.status_code in [200, 401]  # 401 is expected without auth

    print("All API tests passed!")

if __name__ == "__main__":
    test_api_endpoints()

Frontend Tests:

// test_frontend.js
const puppeteer = require('puppeteer');

async function testFrontend() {
    const browser = await puppeteer.launch();
    const page = await browser.newPage();

    try {
        // Test homepage loads
        await page.goto('http://localhost:3000');
        await page.waitForSelector('body');

        // Test login page
        await page.goto('http://localhost:3000/login');
        await page.waitForSelector('form');

        console.log('Frontend tests passed!');
    } catch (error) {
        console.error('Frontend test failed:', error);
    } finally {
        await browser.close();
    }
}

testFrontend();

Performance Verification¶

Load Testing:

# Install Apache Bench
sudo apt install apache2-utils

# Test API performance
ab -n 1000 -c 10 http://localhost:8000/health

# Test frontend performance
ab -n 1000 -c 10 http://localhost:3000/

🎯 Troubleshooting¶

Common Installation Issues¶

Docker Issues¶

Container Won't Start:

# Check container logs
docker-compose logs backend

# Common solutions:
# 1. Check port conflicts
netstat -tulpn | grep :8000

# 2. Check disk space
df -h

# 3. Restart Docker service
sudo systemctl restart docker

Database Connection Issues:

# Check database container
docker-compose exec db psql -U alwrity -d alwrity -c "SELECT 1;"

# Check environment variables
docker-compose exec backend env | grep DATABASE

Manual Installation Issues¶

Python Dependencies:

# Update pip
pip install --upgrade pip

# Install dependencies with verbose output
pip install -r requirements.txt -v

# Check Python version
python --version

Node.js Issues:

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check Node.js version
node --version
npm --version

Performance Issues¶

Slow Startup:

# Check system resources
htop
free -h
df -h

# Optimize Docker
docker system prune -a

High Memory Usage:

# Monitor memory usage
docker stats

# Adjust container limits
# Edit docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 2G

🎯 Next Steps¶

Immediate Actions (This Week)¶

Complete Installation: Finish installation and configuration
Basic Testing: Test all core functionality
User Setup: Create user accounts and basic configuration
Documentation Review: Review user documentation and guides

Short-Term Planning (This Month)¶

Production Setup: Configure for production use
SSL Setup: Implement SSL/HTTPS for security
Backup Setup: Implement backup and recovery procedures
Monitoring Setup: Set up monitoring and alerting

Long-Term Strategy (Next Quarter)¶

Performance Optimization: Optimize system performance
Security Hardening: Implement security best practices
Scaling Preparation: Prepare for scaling and growth
Integration Setup: Set up external integrations

Installation complete? Check out our First Steps Guide to start creating content with ALwrity!