Run Locally with AI Integrations

This guide covers how to run the AiKit application locally with AI integrations. It includes steps for setting up the environment, starting the application without Docker, and accessing the application.

Starting the application directly without Docker is useful for development and debugging purposes. The only dependency is a PostgreSQL database, which can be run using standalone Docker container or by installing PostgreSQL directly on your machine. We recommend using a dockerized PostgreSQL instance for simplicity. The Dev Kit includes a Makefile with commands to help you run the application locally.

Apart from running the application, this guide also covers how to set up AI providers and file storage for local development.

Run Backend and Frontend Locally

Database Setup

The first step is to set up a PostgreSQL database. You can either install PostgreSQL directly on your machine or use Docker to run it.

For local development, you can use Docker for PostgreSQL.

To start the database service:

make db-only

This command will start a PostgreSQL database container using the configuration defined in the docker-compose.yml file.

Backend Setup

1. Navigate to the backend directory:

cd backend

2. Create and activate a virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

4. Run database migrations:

alembic upgrade head

5. Start the FastAPI server:

uvicorn main:app --reload --port 8000

Frontend Setup

1. Navigate to the frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

Configuration

AI Provider Setup

Replicate

1. Sign up at Replicate
2. Get your API token from the dashboard
3. Add it to your .env file as REPLICATE_API_TOKEN

OpenAI

1. Sign up at OpenAI
2. Get your API key from the dashboard
3. Add it to your .env file as OPENAI_API_KEY

File Storage Setup

Local Development (MinIO)

MinIO is included in the Docker Compose setup. Access the console at http://localhost:9001 with credentials admin/password123.

Production (AWS S3)

1. Create an S3 bucket
2. Create IAM credentials with S3 access
3. Update the .env file with your AWS credentials

Authentication Setup

Local Development

The application includes a basic authentication system for local development.

Production (Supabase)

1. Create a project at Supabase
2. Get your project URL and API keys
3. Update the .env file with your Supabase credentials

Development Workflow

Common Commands

Use the included Makefile for common tasks:

# Start only the database service
make db-only

# Show logs
make show-logs

# Stop the database service
make db-stop

Making Changes

1. Backend changes: The FastAPI server will auto-reload when you save files
2. Frontend changes: The Next.js development server will hot-reload
3. Database changes: Create new Alembic migrations:

   cd backend
   alembic revision --autogenerate -m "Description of changes"
   alembic upgrade head

Troubleshooting

Common Issues

Port already in use

# Find and kill the process using the port
lsof -ti:8000 | xargs kill -9

Database connection issues

# Check if PostgreSQL is running
docker ps | grep postgres

# Reset the database
docker-compose down -v
docker-compose up -d

Node modules issues

# Clean install
rm -rf node_modules package-lock.json
npm install

Python dependencies issues

# Recreate virtual environment
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt