Self-Host Setup - Developers¶

Get ALwrity running on your local machine in just 2 hours. This guide will help you set up the development environment and understand the self-hosted architecture.

🎯 What You'll Accomplish¶

By the end of this guide, you'll have: - ✅ ALwrity running locally on your machine - ✅ Backend API server accessible at localhost:8000 - ✅ Frontend dashboard accessible at localhost:3000 - ✅ Configured API keys for AI services - ✅ Made your first API call to test the setup

⏱️ Time Required: 2 hours¶

🚀 Step-by-Step Setup¶

Step 1: Prerequisites Check (10 minutes)¶

Before we start, ensure you have the following installed:

Required Software¶

Python 3.8+: Download Python
Node.js 18+: Download Node.js
Git: Download Git

Verify Installation¶

# Check Python version
python --version
# Should show Python 3.8 or higher

# Check Node.js version
node --version
# Should show v18 or higher

# Check Git
git --version
# Should show Git version

Step 2: Clone ALwrity Repository (5 minutes)¶

Clone the repository:

git clone https://github.com/AJaySi/ALwrity.git
cd ALwrity

Verify the download: You should see folders: backend, frontend, docs, etc.

Check the structure:

ls -la
# Should show backend/, frontend/, docs/, etc.

Step 3: Backend Setup (30 minutes)¶

Install Python Dependencies¶

cd backend
pip install -r requirements.txt

Configure Environment Variables¶

Copy the template:
```
cp env_template.txt .env
```

Edit the .env file with your API keys:

# Required API Keys
GEMINI_API_KEY=your_gemini_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# Optional but recommended
TAVILY_API_KEY=your_tavily_api_key_here
SERPER_API_KEY=your_serper_api_key_here

# Database (default is fine)
DATABASE_URL=sqlite:///./alwrity.db

# Security
SECRET_KEY=your_secret_key_here

Get Your API Keys¶

Gemini API Key (Required): 1. Go to Google AI Studio 2. Create a new API key 3. Copy and paste into your .env file

OpenAI API Key (Required): 1. Go to OpenAI Platform 2. Create a new API key 3. Copy and paste into your .env file

Start the Backend Server¶

python start_alwrity_backend.py

You should see:

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000

Step 4: Make Your First API Call (10 minutes)¶

Option A: Using cURL¶

# Test API connection
curl -X GET "https://api.alwrity.com/v1/health" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Option B: Using Python¶

import requests

# Set up your API key
API_KEY = "your_api_key_here"
BASE_URL = "https://api.alwrity.com/v1"

# Test API connection
response = requests.get(
    f"{BASE_URL}/health",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
)

print(f"Status: {response.status_code}")
print(f"Response: {response.json()}")

Option C: Using JavaScript¶

// Set up your API key
const API_KEY = "your_api_key_here";
const BASE_URL = "https://api.alwrity.com/v1";

// Test API connection
fetch(`${BASE_URL}/health`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Step 5: Create Your First Content (8 minutes)¶

Generate a Blog Post¶

import requests

# Set up your API key
API_KEY = "your_api_key_here"
BASE_URL = "https://api.alwrity.com/v1"

# Create content request
content_request = {
    "type": "blog_post",
    "topic": "Getting Started with ALwrity API",
    "key_points": [
        "What is ALwrity API",
        "How to get started",
        "Basic API usage",
        "Next steps"
    ],
    "tone": "professional",
    "length": "medium",
    "seo_optimized": True
}

# Make API call
response = requests.post(
    f"{BASE_URL}/content/generate",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json=content_request
)

if response.status_code == 200:
    content = response.json()
    print("Generated content:")
    print(content["data"]["content"])
else:
    print(f"Error: {response.status_code}")
    print(response.json())

# Create social media content request
social_request = {
    "type": "social_media",
    "platform": "linkedin",
    "topic": "ALwrity API Launch",
    "tone": "professional",
    "include_hashtags": True,
    "include_cta": True
}

# Make API call
response = requests.post(
    f"{BASE_URL}/content/generate",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json=social_request
)

if response.status_code == 200:
    content = response.json()
    print("Generated social media content:")
    print(content["data"]["content"])
else:
    print(f"Error: {response.status_code}")
    print(response.json())

🔧 API Structure Overview¶

Base URL¶

https://api.alwrity.com/v1

Authentication¶

All API requests require authentication using your API key:

Authorization: Bearer YOUR_API_KEY

Common Endpoints¶

Content Generation¶

POST /content/generate
POST /content/generate/batch
GET /content/{content_id}
PUT /content/{content_id}
DELETE /content/{content_id}

Persona Management¶

GET /personas
POST /personas
GET /personas/{persona_id}
PUT /personas/{persona_id}
DELETE /personas/{persona_id}

Analytics¶

GET /analytics/usage
GET /analytics/performance
GET /analytics/content/{content_id}

Response Format¶

All API responses follow this format:

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "request_id": "req_1234567890",
    "timestamp": "2024-01-15T10:30:00Z",
    "rate_limit": {
      "limit": 1000,
      "remaining": 999,
      "reset": 1642248600
    }
  }
}

🎯 Common Use Cases¶

1. Automated Blog Post Generation¶

def generate_blog_post(topic, key_points):
    request_data = {
        "type": "blog_post",
        "topic": topic,
        "key_points": key_points,
        "tone": "professional",
        "length": "long",
        "seo_optimized": True,
        "include_research": True
    }

    response = requests.post(
        f"{BASE_URL}/content/generate",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=request_data
    )

    return response.json()["data"]["content"]

def generate_social_content(platform, topic):
    request_data = {
        "type": "social_media",
        "platform": platform,
        "topic": topic,
        "tone": "engaging",
        "include_hashtags": True,
        "include_cta": True
    }

    response = requests.post(
        f"{BASE_URL}/content/generate",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=request_data
    )

    return response.json()["data"]["content"]

3. Batch Content Generation¶

def generate_multiple_posts(topics):
    request_data = {
        "type": "blog_post",
        "topics": topics,
        "tone": "professional",
        "length": "medium",
        "seo_optimized": True
    }

    response = requests.post(
        f"{BASE_URL}/content/generate/batch",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=request_data
    )

    return response.json()["data"]["content"]

🚨 Error Handling¶

Common Error Codes¶

def handle_api_response(response):
    if response.status_code == 200:
        return response.json()["data"]
    elif response.status_code == 401:
        raise Exception("Invalid API key")
    elif response.status_code == 429:
        raise Exception("Rate limit exceeded")
    elif response.status_code == 400:
        raise Exception(f"Bad request: {response.json()['error']}")
    elif response.status_code == 500:
        raise Exception("Internal server error")
    else:
        raise Exception(f"Unexpected error: {response.status_code}")

Rate Limiting¶

ALwrity API has rate limits to ensure fair usage:

Free tier: 100 requests per hour
Pro tier: 1,000 requests per hour
Enterprise: Custom limits

import time

def make_api_call_with_retry(request_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            f"{BASE_URL}/content/generate",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json=request_data
        )

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            # Rate limited, wait and retry
            time.sleep(60)
            continue
        else:
            raise Exception(f"API error: {response.status_code}")

    raise Exception("Max retries exceeded")

🎉 Congratulations!¶

You've successfully: - ✅ Set up your developer account - ✅ Obtained your API keys - ✅ Made your first API call - ✅ Generated content via API - ✅ Understood the API structure

🚀 Next Steps¶

Immediate Actions (Today)¶

Build your first integration - Create a complete integration
Test different content types - Try blog posts, social media, emails
Explore advanced features - Use personas, analytics, webhooks
Join the developer community - Connect with other developers

This Week¶

Implement advanced features - Use webhooks and real-time updates
Build error handling - Implement robust error handling
Add monitoring - Track API usage and performance
Test in staging - Deploy to a staging environment

This Month¶

Deploy to production - Deploy your integration
Optimize performance - Improve speed and efficiency
Scale your integration - Handle more users and content
Contribute to the community - Share your integrations

🆘 Need Help?¶

Common Questions¶

Q: How do I handle API errors? A: Check the status code and error message. Implement retry logic for rate limits and temporary errors.

Q: What's the difference between development and production API keys? A: Development keys have lower rate limits and are for testing. Production keys are for live applications.

Q: How do I monitor my API usage? A: Use the /analytics/usage endpoint to track your API usage and remaining quota.

Q: Can I use webhooks for real-time updates? A: Yes! ALwrity supports webhooks for real-time notifications about content generation and updates.

Getting Support¶

API Documentation - Complete API reference
Code Examples - Sample integrations
Developer Community - Ask questions and get help
Email Support - Get personalized help

🎯 Success Tips¶

For Best Results¶

Use appropriate rate limiting - Don't exceed your quota
Implement error handling - Handle all possible error cases
Cache responses - Cache content to reduce API calls
Monitor usage - Track your API usage and costs

Common Mistakes to Avoid¶

Don't hardcode API keys - Use environment variables
Don't ignore rate limits - Implement proper rate limiting
Don't skip error handling - Always handle API errors
Don't forget to test - Test your integration thoroughly

🎉 Ready for More?¶

Build your first integration →

Questions? Join our developer community or contact developer support!