Skip to main content

Installation Guide

Complete step-by-step installation instructions for AI content reporpuser.

Table of Contents​

System Requirements​

Backend Requirements​

  • Node.js: 18.x or higher (Download)
  • npm: 9.x or higher (comes with Node.js)
  • OpenAI API Key (required): Get API Key
  • Git: For cloning repository
  • Text Editor: VS Code recommended

Frontend Requirements​

  • Flutter SDK: 3.10 or higher (Install Guide)
  • Platform Tools:
    • Linux: libgtk-3-dev, libblkid-dev, liblzma-dev
    • macOS: Xcode Command Line Tools
    • Windows: Visual Studio 2022 with C++ tools
    • Mobile: Android Studio or Xcode

Optional Requirements​

Backend Installation​

Use the provided scripts for a fast, consistent setup.

One-command Backend Setup​

cd scripts
./setup-backend.sh

What it does:

  • Installs backend dependencies (npm install)
  • Creates backend/.env if missing (with required keys)
  • Builds the backend (npm run build)

After it completes, open backend/.env and set your real OpenAI API key (required).

# in backend/.env
OPENAI_API_KEY=sk-...your-real-key...

If you prefer manual steps, see Manual Backend Setup below.

If you see a permission error when running scripts, make them executable:

cd scripts
chmod +x *.sh

Frontend Installation​

One-command Frontend Setup​

cd scripts
./setup-frontend.sh

What it does:

  • Verifies Flutter is installed (flutter --version, flutter doctor)
  • Fetches dependencies (flutter pub get)
  • Enables desktop support for your platform

The frontend defaults to http://localhost:3000 for the backend API. You can change this later in app settings.

If you prefer manual steps, see Manual Frontend Setup below.

Build for Your Platform (optional)​

Linux Desktop​

flutter build linux

macOS Desktop​

flutter build macos

Windows Desktop​

flutter build windows

Android​

flutter build apk
# or
flutter build appbundle

iOS​

flutter build ios

Run the Application (manual alternative)​

For development without scripts:

flutter run -d linux  # or macos, windows, etc.

Or run the built binary directly:

# Linux
./build/linux/x64/release/bundle/ai_content_repurposer

# macOS
open build/macos/Build/Products/Release/ai_content_repurposer.app

# Windows
.\build\windows\runner\Release\ai_content_repurposer.exe

Firebase Setup (Optional)​

Firebase provides data persistence for generation history, settings, and analytics.

Step 1: Create Firebase Project​

  1. Go to Firebase Console
  2. Click "Add Project"
  3. Enter project name
  4. Follow the setup wizard

Step 2: Enable Firestore Database​

  1. In Firebase Console, go to "Firestore Database"
  2. Click "Create database"
  3. Choose "Start in production mode" or "test mode"
  4. Select a location

Step 3: Generate Service Account Key​

  1. Go to Project Settings → Service Accounts
  2. Click "Generate new private key"
  3. Save the JSON file as serviceAccountKey.json
  4. Move it to backend/ directory
mv ~/Downloads/your-project-xxxxx.json backend/serviceAccountKey.json

Step 4: Update Environment Variables​

In backend/.env:

FIREBASE_SERVICE_ACCOUNT_PATH=serviceAccountKey.json
FIREBASE_DATABASE_URL=https://your-project-id.firebaseio.com
FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com

Step 5: Security Rules (Production)​

In Firebase Console → Firestore → Rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Allow server-side access only
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

Since we're using Firebase Admin SDK (server-side), we don't need public client access.

Use the dev starter to run backend and frontend together with logging and health checks.

cd scripts
./start-dev.sh

Logs are written to logs/backend.log and logs/frontend.log. Press Ctrl+C to stop both.

Verification​

Backend Health Check​

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2025-12-18T..."
}

Backend Config Check​

curl http://localhost:3000/api/v1/config

Should return provider info without errors.

Frontend Connection Test​

  1. Open the app
  2. Go to Settings
  3. Click "Test Connection"
  4. Should show "Active" status with provider info

Manual Setup (optional)​

If you can’t use the scripts, here are the equivalent manual steps.

Manual Backend Setup​

cd backend
npm install
cp .env.example .env || true
# edit .env and set OPENAI_API_KEY
npm run build
npm start

Manual Frontend Setup​

cd frontend
flutter --version && flutter doctor
flutter pub get
flutter run -d linux  # or your platform

Troubleshooting Installation​

Backend Issues​

Problem: npm install fails

# Clear npm cache
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Problem: TypeScript build errors

# Reinstall TypeScript
npm install -D typescript
npm run build

Problem: Port 3000 already in use

# Change port in .env
PORT=3001

Frontend Issues​

Problem: Flutter not found

# Add Flutter to PATH
export PATH="$PATH:`pwd`/flutter/bin"

Problem: Build fails on Linux

# Install required libraries
sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev

Problem: Dependencies conflict

flutter clean
flutter pub get

Firebase Issues​

Problem: Service account not found

  • Verify serviceAccountKey.json is in backend/ directory
  • Check file permissions: chmod 600 serviceAccountKey.json
  • Verify path in .env is correct

Problem: Permission denied

  • Check Firebase Security Rules
  • Verify service account has required permissions

Next Steps​

Need Help? Check the Troubleshooting Guide