Skip to content

Configuration Guide

This guide will help you configure ALwrity with your API keys, settings, and preferences to get the most out of your AI-powered content creation platform.

Overview

ALwrity requires configuration of several components to function optimally:

  • AI Service API Keys: Core AI capabilities
  • Research & SEO Services: Enhanced content research
  • Authentication: User management and security
  • Database: Data storage and management
  • Frontend Settings: User interface configuration

Backend Configuration

Environment Variables

The backend configuration is managed through environment variables in the .env file located in the backend/ directory.

Core AI Services (Required)

# Google Gemini API - Primary AI service
GEMINI_API_KEY=your_gemini_api_key_here

# OpenAI API - Alternative AI service
OPENAI_API_KEY=your_openai_api_key_here

# Anthropic API - Claude AI service
ANTHROPIC_API_KEY=your_anthropic_api_key_here

Database Configuration

# Database URL - SQLite for development, PostgreSQL for production
DATABASE_URL=sqlite:///./alwrity.db

# For PostgreSQL production setup:
# DATABASE_URL=postgresql://username:password@localhost:5432/alwrity

Security Settings

# Secret key for JWT tokens and encryption
SECRET_KEY=your_very_secure_secret_key_here

# Generate a secure key:
# python -c "import secrets; print(secrets.token_urlsafe(32))"

Web Search & Research

# Tavily API - Advanced web search and research
TAVILY_API_KEY=your_tavily_api_key_here

# Serper API - Google search results
SERPER_API_KEY=your_serper_api_key_here

# Metaphor API - Content discovery
METAPHOR_API_KEY=your_metaphor_api_key_here

# Firecrawl API - Web scraping and content extraction
FIRECRAWL_API_KEY=your_firecrawl_api_key_here

SEO & Analytics

# Google Search Console integration
GSC_CLIENT_ID=your_gsc_client_id_here
GSC_CLIENT_SECRET=your_gsc_client_secret_here

# Google Analytics (if needed)
GA_TRACKING_ID=your_ga_tracking_id_here

Content Generation

# Stability AI - Image generation
STABILITY_API_KEY=your_stability_api_key_here

# Additional AI services
MISTRAL_API_KEY=your_mistral_api_key_here

Authentication & Integration

# Clerk Authentication
CLERK_SECRET_KEY=your_clerk_secret_key_here

# CopilotKit Integration
COPILOT_API_KEY=your_copilot_api_key_here

# Webhook URLs (for production)
WEBHOOK_URL=your_webhook_url_here

Frontend Configuration

Environment Variables

The frontend configuration is managed through environment variables in the .env file located in the frontend/ directory.

Core Settings

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

# For production:
# REACT_APP_API_URL=https://your-domain.com

# Environment
NODE_ENV=development

Authentication

# Clerk Authentication
REACT_APP_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key_here

# Google OAuth (if using)
REACT_APP_GOOGLE_CLIENT_ID=your_google_client_id_here

AI Integration

# CopilotKit
REACT_APP_COPILOT_API_KEY=your_copilot_api_key_here

# Additional AI services
REACT_APP_OPENAI_API_KEY=your_openai_api_key_here

SEO & Analytics

# Google Search Console
REACT_APP_GSC_CLIENT_ID=your_gsc_client_id_here

# Google Analytics
REACT_APP_GA_TRACKING_ID=your_ga_tracking_id_here

API Keys Setup

1. Google Gemini API

Purpose: Primary AI service for content generation and analysis

Setup Steps: 1. Visit Google AI Studio 2. Sign in with your Google account 3. Click "Create API Key" 4. Copy the generated key 5. Add to GEMINI_API_KEY in backend .env

Usage Limits: - Free tier: 15 requests per minute - Paid tier: Higher limits available

2. OpenAI API

Purpose: Alternative AI service for content generation

Setup Steps: 1. Visit OpenAI Platform 2. Sign in to your account 3. Click "Create new secret key" 4. Copy the generated key 5. Add to OPENAI_API_KEY in backend .env

Usage Limits: - Pay-per-use model - Rate limits based on your plan

3. Anthropic API

Purpose: Claude AI for advanced reasoning and analysis

Setup Steps: 1. Visit Anthropic Console 2. Sign in to your account 3. Navigate to API Keys 4. Create a new API key 5. Add to ANTHROPIC_API_KEY in backend .env

4. Tavily API

Purpose: Advanced web search and research capabilities

Setup Steps: 1. Visit Tavily 2. Sign up for an account 3. Navigate to API section 4. Generate API key 5. Add to TAVILY_API_KEY in backend .env

Benefits: - Real-time web search - Content summarization - Source verification

5. Serper API

Purpose: Google search results and SEO data

Setup Steps: 1. Visit Serper 2. Sign up for an account 3. Get your API key 4. Add to SERPER_API_KEY in backend .env

Benefits: - Google search results - SEO data and insights - Keyword research

6. Google Search Console

Purpose: SEO analysis and performance tracking

Setup Steps: 1. Visit Google Search Console 2. Add your website property 3. Go to Settings → Users and permissions 4. Create OAuth credentials 5. Add client ID and secret to .env

Benefits: - Real search performance data - Keyword insights - Technical SEO analysis

7. Clerk Authentication

Purpose: User authentication and management

Setup Steps: 1. Visit Clerk Dashboard 2. Create a new application 3. Get your publishable and secret keys 4. Add to frontend and backend .env files

Benefits: - Secure user authentication - Social login options - User management

8. CopilotKit

Purpose: AI chat interface and interactions

Setup Steps: 1. Visit CopilotKit 2. Sign up for an account 3. Get your API key 4. Add to COPILOT_API_KEY in both .env files

Benefits: - Interactive AI chat - Context-aware responses - Seamless user experience

Database Configuration

SQLite (Development)

Default Configuration: 

DATABASE_URL=sqlite:///./alwrity.db

Benefits: - No additional setup required - Perfect for development - File-based storage

PostgreSQL (Production)

Setup Steps: 1. Install PostgreSQL 2. Create database and user 3. Update environment variable:

DATABASE_URL=postgresql://username:password@localhost:5432/alwrity

Benefits: - Better performance - Concurrent access - Advanced features

Database Initialization

# Initialize database with default data
python scripts/init_alpha_subscription_tiers.py

# Or manually initialize
python -c "from services.database import initialize_database; initialize_database()"

Security Configuration

Secret Key Generation

# Generate a secure secret key
python -c "import secrets; print(secrets.token_urlsafe(32))"

Environment Security

Best Practices: - Never commit .env files to version control - Use different keys for development and production - Rotate API keys regularly - Monitor API usage and costs

CORS Configuration

The backend automatically configures CORS for development. For production, update the CORS settings in backend/app.py:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-domain.com"],  # Production domain
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Performance Configuration

Backend Optimization

# Worker processes (for production)
WORKERS=4

# Request timeout
REQUEST_TIMEOUT=30

# Database connection pool
DB_POOL_SIZE=10

Frontend Optimization

# Enable production optimizations
NODE_ENV=production

# Bundle analyzer
ANALYZE_BUNDLE=true

# Source maps (disable for production)
GENERATE_SOURCEMAP=false

Monitoring & Logging

Logging Configuration

# Log level
LOG_LEVEL=INFO

# Log file
LOG_FILE=logs/alwrity.log

# Enable request logging
ENABLE_REQUEST_LOGGING=true

Health Checks

# Backend health check
curl http://localhost:8000/health

# Database health check
curl http://localhost:8000/health/db

# API health check
curl http://localhost:8000/health/api

Configuration Validation

Test Configuration

# Test backend configuration
python -c "from services.api_key_manager import validate_api_keys; validate_api_keys()"

# Test database connection
python -c "from services.database import test_connection; test_connection()"

# Test API endpoints
curl http://localhost:8000/api/health

Configuration Checklist

  • All required API keys are set
  • Database is initialized
  • Backend server starts without errors
  • Frontend connects to backend
  • Authentication is working (if configured)
  • API endpoints are accessible
  • Health checks pass

Troubleshooting Configuration

Common Issues

API Key Errors: - Verify keys are correctly copied - Check for extra spaces or characters - Ensure keys have proper permissions

Database Connection Issues: - Verify database URL format - Check database server is running - Ensure proper permissions

CORS Errors: - Check frontend URL in CORS settings - Verify backend is running on correct port - Check for HTTPS/HTTP mismatch

Authentication Issues: - Verify Clerk keys are correct - Check domain configuration in Clerk - Ensure proper redirect URLs

Getting Help

If you encounter configuration issues:

  1. Check Logs: Review console output for error messages
  2. Validate Keys: Test API keys individually
  3. Verify URLs: Ensure all URLs are correct
  4. Check Permissions: Verify API key permissions
  5. Review Documentation: Check service-specific documentation

Next Steps

After successful configuration:

  1. First Steps - Create your first content strategy
  2. Quick Start - Get up and running quickly
  3. Troubleshooting Guide - Common issues and solutions
  4. API Reference - Complete API documentation

Configuration complete? Start creating content with your newly configured ALwrity platform!