Quickstart Guide

Get Zarna up and running in under 10 minutes

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18+ and npm
• Python 3.8+
• Git
• A Supabase account (free tier works)
• API keys for:
  • Anthropic Claude (for AI features)
  • OpenAI (optional, for additional AI capabilities)
  • Composio (for OAuth integrations)

Step 1: Clone the Repository

cd ~/your-projects-folder
git clone <your-zarna-repo-url>
cd zarna

The repository has a monorepo structure:

zarna/
├── zarna-frontend/    # React application
├── zarna-backend/     # FastAPI application
├── docs/              # Documentation (you are here!)
└── zarna-website/     # Marketing website

Step 2: Set Up Backend

Install Python Dependencies

cd zarna-backend
pip install -r requirements.txt

Tip: Consider using a virtual environment to isolate dependencies:

python -m venv zarna_env
source zarna_env/bin/activate  # On Windows: zarna_env\Scripts\activate

Configure Environment Variables

Create a .env file in the zarna-backend directory:

cd zarna-backend
touch .env

Add the following configuration:

# Server Configuration
PORT=8000
HOST=0.0.0.0

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key

# AI Services
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key

# OAuth Integrations (Composio)
COMPOSIO_API_KEY=your-composio-key
COMPOSIO_GMAIL_AUTH_CONFIG_ID=your-gmail-config-id
COMPOSIO_OUTLOOK_AUTH_CONFIG_ID=your-outlook-config-id

# API Base URL (for OAuth callbacks)
API_BASE_URL=http://localhost:8000

Security: Never commit your .env file to version control. It’s already in .gitignore.

Start the Backend Server

cd api
python run.py

You should see:

[STARTUP] 🚀 Starting Zarna API with Agent Pool Manager...
[STARTUP] ✅ Agent Pool Manager started successfully
[STARTUP] ✅ Zarna API startup complete
INFO:     Uvicorn running on http://0.0.0.0:8000

Verify: Navigate to http://localhost:8000/docs to see the interactive API documentation.

Step 3: Set Up Frontend

Open a new terminal window/tab.

Install Node Dependencies

cd zarna-frontend
npm install

Configure Environment Variables

Create a .env.local file in the zarna-frontend directory:

touch .env.local

Add the backend API URL:

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Start the Frontend Server

npm run dev

You should see:

  VITE v6.2.0  ready in 1234 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose

Verify: Navigate to http://localhost:3000 to see the Zarna application.

Step 4: Set Up Supabase Database

Create Database Tables

Zarna requires several database tables for CRM, files, users, and integrations.

1. Go to your Supabase project dashboard
2. Navigate to SQL Editor
3. Run the initialization scripts located in /zarna-backend/supabase/migrations/

The backend will automatically create some tables on first run, but it’s recommended to run the migration scripts for a complete setup.

Enable Row Level Security (RLS)

For production deployments, enable RLS policies on your tables:

-- Example: Enable RLS on companies table
ALTER TABLE companies ENABLE ROW LEVEL SECURITY;

-- Create policy for authenticated users
CREATE POLICY "Users can view their firm's companies"
  ON companies FOR SELECT
  USING (firm_id IN (
    SELECT firm_id FROM users WHERE id = auth.uid()
  ));

Step 5: Verify Installation

Test Backend Health

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy"
}

Test Frontend Connection

1. Open http://localhost:3000
2. You should see the login page
3. Create an account or log in
4. You should be redirected to the dashboard

Test API Integration

From the frontend, try:

• Creating a new company
• Uploading a document
• Running a search query

If all operations work, your installation is complete!

Next Steps

Explore Features

Learn about CRM, reports, and sourcing features

Set Up Integrations

Connect Gmail, Drive, SharePoint, and other services

API Reference

Explore the complete API documentation

Architecture Guide

Understand how Zarna works under the hood

Common Issues

Port 8000 already in use

Change the PORT in your .env file:

PORT=8001

Don’t forget to update NEXT_PUBLIC_API_URL in the frontend!

Missing Python packages

Ensure you’re in the correct directory and virtual environment:

cd zarna-backend
source zarna_env/bin/activate
pip install -r requirements.txt

Supabase connection error

Verify your SUPABASE_URL and SUPABASE_KEY are correct. The key should be the service role key, not the anon key.

npm install fails

Try deleting node_modules and package-lock.json:

rm -rf node_modules package-lock.json
npm install

API calls fail with CORS error

Ensure the backend is running on localhost:8000 and the frontend on localhost:3000. The backend CORS configuration allows these origins.

Development Workflow

Now that you’re set up, here’s the typical development workflow:

1. Start backend: cd zarna-backend/api && python run.py
2. Start frontend: cd zarna-frontend && npm run dev
3. Make changes: Edit code in your IDE
4. Hot reload: Both servers auto-reload on changes
5. Test: Use the frontend UI or API docs at /docs

Pro tip: Use separate terminal tabs/panes for backend and frontend so you can see logs from both simultaneously.

Ready to Build?

Your Zarna development environment is ready! Start building amazing features for private equity workflows.

Need help?

Contact our team if you encounter any issues.