Quickstart

This guide will help you set up AuthentiVoice locally for development and testing. For production deployment, see our deployment guides.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18 or higher

node --version

Python

Version 3.10 or higher

python --version

Docker

For containerized deployment

docker --version

ffmpeg

Required for audio processing

ffmpeg -version

🚀 Quick Installation

Using Make (Recommended)
Manual Setup
Docker Compose

Clone and Setup

git clone https://github.com/authentivoice/authentivoice.git
cd authentivoice

# Copy environment templates
cp frontend/.env.example frontend/.env
cp backend/.env.example backend/.env

Configure Environment

Edit the environment files with your credentials:

Frontend Configuration

# frontend/.env
VITE_SUPABASE_URL=your-supabase-url
VITE_SUPABASE_ANON_KEY=your-supabase-anon-key
VITE_API_BASE_URL=http://localhost:8006
VITE_API_KEY=your-secure-api-key
VITE_DEMO_ENABLED=true
VITE_LOCAL_DEV=true

Backend Configuration

# backend/.env
# API Keys
GEMINI_API_KEY=your-gemini-api-key

# S3/MinIO Configuration
S3_ENDPOINT_URL=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET_NAME=authentivoice

# Supabase
SUPABASE_URL=your-supabase-url
SUPABASE_KEY=your-supabase-service-key

# Security
API_KEY=your-secure-api-key

Install Dependencies

# Install frontend dependencies
cd frontend && npm install && cd ..

# Install backend dependencies
cd backend && pip install uv && uv sync && cd ..

Start Services

# Start both frontend and backend
make run-frontend  # In terminal 1
make run-backend   # In terminal 2

Frontend will be available at http://localhost:5173 Backend API will be available at http://localhost:8006

Clone Repository

git clone https://github.com/authentivoice/authentivoice.git
cd authentivoice

Frontend Setup

cd frontend
npm install
cp .env.example .env
# Edit .env with your configuration
npm run dev

Backend Setup

cd backend
pip install uv
uv sync
cp .env.example .env
# Edit .env with your configuration
uv run uvicorn app.main:app --reload --port 8006

Clone and Configure

git clone https://github.com/authentivoice/authentivoice.git
cd authentivoice
cp .env.example .env

Start with Docker Compose

docker-compose up -d

This will start:

Frontend on port 3000
Backend API on port 8006
MinIO on port 9000
PostgreSQL on port 5432

🎯 First Steps After Installation

Access the Application

Open your browser and navigate to:

Frontend: http://localhost:5173
API Documentation: http://localhost:8006/docs

Create Your First User

Click “Sign Up” on the landing page
Enter your email and create a password
Verify your email (check spam folder)
Log in with your credentials

Set Up Your Organization

The first user to sign up becomes the Admin. Use this account to configure your organization.

Navigate to Settings → Organization
Configure your organization details
Set up user roles and permissions
Configure integrations (optional)

Upload and Analyze Your First Call

Go to the Dashboard
Click “Upload Audio”
Select an audio file (MP3, WAV, M4A supported)
Choose transcription engine (Whisper recommended for start)
Click “Analyze”
View results in real-time

🔧 Essential Configuration

Database Setup

Supabase (Recommended)
Local PostgreSQL

Create a free account at supabase.com
Create a new project
Copy your project URL and keys
Run migrations:

cd frontend
npm run supabase:migrate
npm run supabase:types

Install PostgreSQL 14+
Create database:

CREATE DATABASE authentivoice;

Update connection strings in .env files

Storage Configuration

MinIO (Local)
AWS S3

# Start MinIO
docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"

# Create bucket
mc alias set local http://localhost:9000 minioadmin minioadmin
mc mb local/authentivoice

Update backend/.env:

S3_ENDPOINT_URL=https://s3.amazonaws.com
S3_ACCESS_KEY=your-aws-access-key
S3_SECRET_KEY=your-aws-secret-key
S3_BUCKET_NAME=your-bucket-name
AWS_REGION=us-east-1

AI Configuration

You need at least one AI provider configured for fraud analysis to work.

Google Gemini (Recommended)
OpenAI

Get API key from Google AI Studio
Add to backend/.env:

GEMINI_API_KEY=your-gemini-api-key

Get API key from OpenAI Platform
Add to backend/.env:

OPENAI_API_KEY=your-openai-api-key

🧪 Test Your Installation

curl http://localhost:5173/health

🎉 What’s Next?

User Guide

Learn how to use all features effectively

Admin Setup

Configure users, roles, and integrations

API Integration

Integrate AuthentiVoice with your systems

Production Deploy

Deploy to production environments

🆘 Troubleshooting

Frontend won't start

Check Node.js version (18+)
Verify all environment variables are set
Clear npm cache: npm cache clean --force
Delete node_modules and reinstall: rm -rf node_modules && npm install

Backend connection errors

Verify Python version (3.10+)
Check API key matches in both .env files
Ensure backend is running on port 8006
Check CORS settings if accessing from different domain

Database connection failed

Verify Supabase URL and keys are correct
Check network connectivity
Ensure migrations have been run
Try regenerating Supabase keys

Audio processing errors

Ensure ffmpeg is installed: ffmpeg -version
Check file size limits (max 100MB by default)
Verify supported formats (MP3, WAV, M4A)
Check storage permissions

📚 Additional Resources

Architecture Overview - Understand the system design
Development Guide - Set up your development environment
API Documentation - Complete API reference
Video Tutorials - Step-by-step walkthroughs

Get Started

User Guide

Features

Architecture

Deployment

Prerequisites

Node.js

Python

Docker

ffmpeg

🚀 Quick Installation

🎯 First Steps After Installation

🔧 Essential Configuration

Database Setup

Storage Configuration

AI Configuration

🧪 Test Your Installation

🎉 What’s Next?

User Guide

Admin Setup

API Integration

Production Deploy

🆘 Troubleshooting

📚 Additional Resources

Get Started

User Guide

Features

Architecture

Deployment

​Prerequisites

Node.js

Python

Docker

ffmpeg

​🚀 Quick Installation

​🎯 First Steps After Installation

​🔧 Essential Configuration

​Database Setup

​Storage Configuration

​AI Configuration

​🧪 Test Your Installation

​🎉 What’s Next?

User Guide

Admin Setup

API Integration

Production Deploy

​🆘 Troubleshooting

​📚 Additional Resources

Prerequisites

🚀 Quick Installation

🎯 First Steps After Installation

🔧 Essential Configuration

Database Setup

Storage Configuration

AI Configuration

🧪 Test Your Installation

🎉 What’s Next?

🆘 Troubleshooting

📚 Additional Resources