Quickstart Guide

This guide will help you set up and run Zyeta on your local machine for development and testing purposes.

​

Prerequisites

Before you begin, make sure you have the following installed:

• Python 3.10 or later (recommended)
• PostgreSQL 14+ (required for vector storage)
• Poetry (for dependency management)
• Docker (optional, for containerized setup)
• Git (for version control)

​

Clone the Repository

First, clone the repository from GitHub:

git clone https://github.com/zyeta-io/zyeta.backend.git
cd zyeta.backend

​

Python Environment Setup

We recommend using Poetry for dependency management:

# Install Poetry if you don't have it already
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

​

Pre-commit Setup

We use pre-commit hooks to ensure code quality:

pre-commit install

This will configure automatic linting and type checking before each commit.

​

Environment Configuration

1. Create your environment file by copying the example file:

cp .env.local .env

2. Configure the following essential environment variables in your .env file:

# Application
APP_NAME=zyeta-backend
ENVIRONMENT=dev

# Security
JWT_SECRET=your_secret_key_here
MASTER_API_KEY=your_master_api_key_here
JWT_EXPIRE_MINUTES=1400

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

# External APIs
OPENAI_API_KEY=your_openai_key_here
FRONTEND_URL=http://localhost:8000

​

Database Setup

​

Option 1: Local PostgreSQL with Docker (Recommended)

The easiest way to set up PostgreSQL is using Docker:

docker run --name zyeta-postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgres

​

Option 2: Using Supabase

If you prefer a cloud-based PostgreSQL service:

1. Create a Supabase account at supabase.com
2. Create a new project
3. Navigate to the Database settings in your Supabase dashboard
4. Copy the connection string from the “Connection Pooling” section

​

Database Migrations Setup

1. Copy the Alembic configuration template:

cp alembic.copy.ini alembic.ini

2. Edit alembic.ini and update the sqlalchemy.url to match your database URL:

# For local Docker PostgreSQL
sqlalchemy.url = postgresql+asyncpg://postgres:mysecretpassword@localhost:5432/postgres

3. Apply database migrations:

alembic upgrade head

​

Running the Application

Start the application in development mode:

# Using Python directly
python -m src.app --dev

# OR using FastAPI CLI (if installed)
fastapi dev src/app.py

The API will be available at:

• API Endpoints: http://localhost:8000/api/
• Swagger UI Documentation: http://localhost:8000/docs
• ReDoc Documentation: http://localhost:8000/redoc

​

Docker Deployment (Alternative)

For a fully containerized setup:

# Build and start services
docker-compose up -d

# View logs
docker-compose logs -f

​

Verification

To verify your setup is working:

1. Open http://localhost:8000/docs in your browser
2. Try creating a new user account via the /api/auth/signup endpoint
3. Login with the created account via /api/auth/login

​

Troubleshooting

​

What’s Next?

Now that you have Zyeta running, explore: