ALwrity/docs-site/docs/getting-started/installation.md

Installation Guide

This comprehensive guide will walk you through installing and setting up ALwrity on your system. Follow these steps to get your AI-powered content creation platform running.

Prerequisites

Before you begin, ensure you have the following installed on your system:

System Requirements

• Operating System: Windows 10/11, macOS 10.15+, or Linux (Ubuntu 18.04+)
• Python: Version 3.10 or higher
• Node.js: Version 18 or higher
• Git: Latest version for version control
• Memory: Minimum 4GB RAM (8GB recommended)
• Storage: At least 2GB free disk space

Required Software

1. Python 3.10+

# Check if Python is installed
python --version

# If not installed, download from: https://www.python.org/downloads/
# Or use package manager:
# Windows: choco install python
# macOS: brew install python
# Ubuntu: sudo apt install python3.10

2. Node.js 18+

# Check if Node.js is installed
node --version
npm --version

# If not installed, download from: https://nodejs.org/
# Or use package manager:
# Windows: choco install nodejs
# macOS: brew install node
# Ubuntu: curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

3. Git

# Check if Git is installed
git --version

# If not installed, download from: https://git-scm.com/
# Or use package manager:
# Windows: choco install git
# macOS: brew install git
# Ubuntu: sudo apt install git

Installation Steps

Step 1: Clone the Repository

# Clone the ALwrity repository
git clone https://github.com/AJaySi/ALwrity.git

# Navigate to the project directory
cd ALwrity

Step 2: Backend Setup

2.1 Install Python Dependencies

# Navigate to backend directory
cd backend

# Create virtual environment (recommended)
python -m venv venv

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

# Install dependencies
pip install -r requirements.txt

2.2 Environment Configuration

Create a .env file in the backend directory:

# Create environment file
touch .env  # Linux/macOS
# or
type nul > .env  # Windows

Add the following configuration to your .env file:

# AI Service API Keys (Required)
GEMINI_API_KEY=your_gemini_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Database Configuration
DATABASE_URL=sqlite:///./alwrity.db

# Security
SECRET_KEY=your_secret_key_here

# Optional: Additional AI Services
TAVILY_API_KEY=your_tavily_api_key_here
SERPER_API_KEY=your_serper_api_key_here
METAPHOR_API_KEY=your_metaphor_api_key_here
FIRECRAWL_API_KEY=your_firecrawl_api_key_here
STABILITY_API_KEY=your_stability_api_key_here

# Optional: Google Search Console
GSC_CLIENT_ID=your_gsc_client_id_here
GSC_CLIENT_SECRET=your_gsc_client_secret_here

# Optional: Clerk Authentication
CLERK_SECRET_KEY=your_clerk_secret_key_here

# Optional: CopilotKit
COPILOT_API_KEY=your_copilot_api_key_here

2.3 Initialize Database

# Initialize the database
python -c "from services.database import initialize_database; initialize_database()"

# Or run the initialization script
python scripts/init_alpha_subscription_tiers.py

2.4 Start Backend Server

# Start the backend server
python start_alwrity_backend.py

# The server will be available at: http://localhost:8000
# API documentation: http://localhost:8000/api/docs
# Health check: http://localhost:8000/health

Step 3: Frontend Setup

3.1 Install Node.js Dependencies

# Navigate to frontend directory (in a new terminal)
cd frontend

# Install dependencies
npm install

3.2 Frontend Environment Configuration

Create a .env file in the frontend directory:

# Create environment file
touch .env  # Linux/macOS
# or
type nul > .env  # Windows

Add the following configuration:

# Backend API URL
REACT_APP_API_URL=http://localhost:8000

# Clerk Authentication (Optional)
REACT_APP_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key_here

# CopilotKit (Optional)
REACT_APP_COPILOT_API_KEY=your_copilot_api_key_here

# Google Search Console (Optional)
REACT_APP_GSC_CLIENT_ID=your_gsc_client_id_here

# Environment
NODE_ENV=development

3.3 Start Frontend Development Server

# Start the frontend development server
npm start

# The application will be available at: http://localhost:3000

Verification

Backend Verification

1. Health Check: Visit http://localhost:8000/health

   • Should return: {"status": "healthy"}

2. API Documentation: Visit http://localhost:8000/api/docs

   • Should display interactive API documentation

3. Database Check: Verify database file exists

   ls -la backend/alwrity.db  # Linux/macOS
   dir backend\alwrity.db     # Windows
   

Frontend Verification

1. Application Load: Visit http://localhost:3000

   • Should display the ALwrity dashboard

2. API Connection: Check browser console for connection errors

   • Should show successful API connections

3. Authentication: Test login functionality (if configured)

API Keys Setup

Required API Keys

1. Google Gemini API

• Visit: Google AI Studio
• Create a new API key
• Add to GEMINI_API_KEY in backend .env

2. OpenAI API (Optional)

• Visit: OpenAI Platform
• Create a new API key
• Add to OPENAI_API_KEY in backend .env

3. Anthropic API (Optional)

• Visit: Anthropic Console
• Create a new API key
• Add to ANTHROPIC_API_KEY in backend .env

Optional API Keys

Research & SEO Services

• Tavily: Tavily API - Web search and research
• Serper: Serper API - Google search results
• Metaphor: Metaphor API - Content discovery
• Firecrawl: Firecrawl API - Web scraping

Content Generation

• Stability AI: Stability Platform - Image generation

Authentication & Integration

• Clerk: Clerk Dashboard - User authentication
• CopilotKit: CopilotKit - AI chat interface

Troubleshooting

Common Issues

Backend Issues

Port Already in Use

# Find process using port 8000
netstat -ano | findstr :8000  # Windows
lsof -i :8000                 # macOS/Linux

# Kill the process or use different port
python start_alwrity_backend.py --port 8001

Database Connection Error

# Reset database
rm backend/alwrity.db  # Linux/macOS
del backend\alwrity.db  # Windows

# Reinitialize
python -c "from services.database import initialize_database; initialize_database()"

Missing Dependencies

# Reinstall requirements
pip install -r requirements.txt --force-reinstall

Frontend Issues

Port Already in Use

# Use different port
npm start -- --port 3001

Build Errors

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

API Connection Issues

• Verify backend is running on http://localhost:8000
• Check REACT_APP_API_URL in frontend .env
• Ensure CORS is properly configured

Getting Help

If you encounter issues:

1. Check Logs: Review console output for error messages
2. Verify Configuration: Ensure all environment variables are set
3. Test API Keys: Verify API keys are valid and have sufficient credits
4. Check Dependencies: Ensure all required software is installed
5. Review Documentation: Check our troubleshooting guide

Next Steps

After successful installation:

1. Configuration Guide - Configure your API keys and settings
2. First Steps - Create your first content strategy
3. Quick Start - Get up and running quickly
4. Troubleshooting Guide - Common issues and solutions

Production Deployment

For production deployment, consider:

• Environment Variables: Use secure environment variable management
• Database: Consider PostgreSQL or MySQL for production
• SSL/TLS: Enable HTTPS for secure connections
• Monitoring: Set up logging and monitoring
• Backup: Implement regular database backups

---

Installation complete? Configure your settings to start creating amazing content with ALwrity!