Quickstart Guide
Get up and running with Zyeta in minutes
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:
Python Environment Setup
We recommend using Poetry for dependency management:
Make sure you’re using Python 3.10 or later. You can check your version with python --version
.
Pre-commit Setup
We use pre-commit hooks to ensure code quality:
This will configure automatic linting and type checking before each commit.
Environment Configuration
- Create your environment file by copying the example file:
- Configure the following essential environment variables in your
.env
file:
Generate secure random strings for JWT_SECRET
and MASTER_API_KEY
. You can use Python’s secrets
module: python -c "import secrets; print(secrets.token_hex(32))"
.
Database Setup
Option 1: Local PostgreSQL with Docker (Recommended)
The easiest way to set up PostgreSQL is using Docker:
Option 2: Using Supabase
If you prefer a cloud-based PostgreSQL service:
- Create a Supabase account at supabase.com
- Create a new project
- Navigate to the Database settings in your Supabase dashboard
- Copy the connection string from the “Connection Pooling” section
Supabase Connection Types
Supabase Connection Types
Supabase offers different connection string formats for different network setups:
-
Direct Connection:
- Format:
postgresql://postgres:[YOUR-PASSWORD]@db.xxxxxxxxxxx.supabase.co:5432/postgres
- Best for persistent connections
- Format:
-
Session Pooler:
- Format:
postgresql://postgres.xxxxxxxxxxx:[YOUR-PASSWORD]@...
- Recommended if you’re on an IPv4 network and have connection issues
- Format:
-
Transaction Pooler:
- Similar to Session Pooler but optimized for short-lived connections
- Good for stateless applications
If you experience connection issues, try the Session Pooler connection string.
Database Migrations Setup
- Copy the Alembic configuration template:
- Edit
alembic.ini
and update thesqlalchemy.url
to match your database URL:
If your database password contains special characters like @
, remember to URL-encode them in your .env
file, but in the alembic.ini
file, you need to escape %
by doubling it: %%
.
- Apply database migrations:
Running the Application
Start the application in development mode:
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:
Verification
To verify your setup is working:
- Open
http://localhost:8000/docs
in your browser - Try creating a new user account via the
/api/auth/signup
endpoint - Login with the created account via
/api/auth/login
Troubleshooting
Database Connection Issues
Database Connection Issues
If you’re having trouble connecting to your database:
- Check if PostgreSQL is running:
pg_isready
- Verify your connection string format
- Ensure your firewall allows connections to port 5432
- Try connecting with
psql
to verify credentials
Poetry Dependency Issues
Poetry Dependency Issues
If you encounter issues with Poetry:
Migration Errors
Migration Errors
If migrations fail:
IPv4/IPv6 Connectivity Issues
IPv4/IPv6 Connectivity Issues
If using Supabase and experiencing connection problems:
- Try the Session Pooler connection string instead of Direct Connection
- Check if your network primarily uses IPv4 (common in many environments)
- Supabase proxies Session and Transaction pooler connections for IPv4 networks
What’s Next?
Now that you have Zyeta running, explore: