Aexy
Get Started

Getting Started

Quick start guide

Prerequisites#

Before you begin, ensure you have the following installed:

  • Python 3.13: Backend runtime
  • Node.js 18+: Frontend runtime
  • PostgreSQL 18: Database
  • Redis 7: Cache and rate limiting
  • Temporal: Workflow engine (bundled via docker-compose)
  • Git: Version control

The easiest way to get all of these — including Temporal, PostgreSQL, Redis, and RustFS — is docker-compose up -d. The native-install steps below are for backend/frontend contributors who already have those services running.

Quick Start#

1. Clone the Repository#

git clone https://github.com/your-org/aexy.git
cd aexy

2. Set Up Environment Variables#

Create a .env file in the root directory:

# Database
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/aexy

# Redis
REDIS_URL=redis://localhost:6379/0

# GitHub App (create at github.com/settings/apps)
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
GITHUB_WEBHOOK_SECRET=your_webhook_secret

# LLM Provider
LLM_PROVIDER=ollama  # Use ollama for local development
OLLAMA_BASE_URL=http://localhost:11434

# Or use Claude
# LLM_PROVIDER=claude
# ANTHROPIC_API_KEY=your_api_key

# JWT
JWT_SECRET_KEY=your-secret-key-at-least-32-chars
JWT_ALGORITHM=HS256

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000/api

3. Set Up the Backend#

cd backend

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

# Install dependencies
pip install -e ".[dev]"

# Create database
createdb aexy

# Run migrations (custom SQL migration system, not Alembic)
python scripts/run_migrations.py

# Start the server
uvicorn aexy.main:app --reload --host 0.0.0.0 --port 8000

4. Set Up the Frontend#

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

5. Access the Application#

Setting Up GitHub App#

  1. Go to https://github.com/settings/apps

  2. Click "New GitHub App"

  3. Fill in the details:

  4. After creation, note down:

    • App ID
    • Client ID
    • Client Secret (generate one)
    • Webhook Secret (set one)

Setting Up LLM Provider#

Option A: Ollama (Recommended for Development)#

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.2
# or
ollama pull codellama

# Ollama runs automatically on port 11434

Option B: Claude (Production)#

  1. Get an API key from https://console.anthropic.com
  2. Set in .env: 
    LLM_PROVIDER=claude
ANTHROPIC_API_KEY=your_api_key

Running Background Workers#

Background jobs and periodic schedules run on Temporal (Celery + Celery Beat + APScheduler from older iterations are gone).

Start the Temporal worker:

cd backend
python -m aexy.temporal.worker

The worker pulls every registered queue by default; pass --queues ANALYSIS,SYNC to scope it. Periodic schedules in aexy/temporal/schedules.py register themselves with the Temporal server on worker startup — you don't run a separate "beat" process.

Inspect workflows, activities, and schedules in the Temporal UI at http://localhost:8080.

Development Workflow#

Running Tests#

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

Code Quality#

# Backend linting
cd backend
ruff check src/
ruff format src/

# Frontend linting
cd frontend
npm run lint

Database Migrations#

Aexy uses a custom SQL migration system tracked in the schema_migrations table.

cd backend

# Create a new migration: drop a SQL file into scripts/migrate_*.sql
# Filenames sort alphabetically and run in that order.

# Preview pending migrations
python scripts/run_migrations.py --dry-run

# Apply all pending
python scripts/run_migrations.py

# Apply a specific file (useful for testing)
python scripts/run_migrations.py --file migrate_feature.sql

Alembic is installed as a transitive dependency only — do not create Alembic migrations.

Using Docker (Alternative)#

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f backend

# Stop services
docker-compose down

Next Steps#

  1. Connect GitHub: Log in with GitHub OAuth to connect your repositories
  2. Import Developers: Use the admin API to import team members
  3. Configure Teams: Create teams and assign developers
  4. Explore Analytics: View team skills, productivity, and insights
  5. Set Up Integrations: Connect Slack, CLI, or VS Code extension

Troubleshooting#

Common Issues#

Database Connection Failed

# Check PostgreSQL is running
pg_isready -h localhost -p 5432

# Create database if missing
createdb aexy

Redis Connection Failed

# Check Redis is running
redis-cli ping

LLM Not Responding

# Check Ollama is running
curl http://localhost:11434/api/tags

# Or test Claude
curl -H "x-api-key: $ANTHROPIC_API_KEY" https://api.anthropic.com/v1/messages

Frontend Build Errors

# Clear cache and reinstall
rm -rf node_modules .next
npm install
npm run dev

Getting Help#

PreviousTracker ingest APINextDeployment