Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed and configured:

Node.js

Version 18.17.0 or higher

pnpm

Version 10.10.0 (package manager)

MongoDB

A MongoDB instance for storing metadata

Supabase

A Supabase account for authentication
Quail is a discontinued project. This guide is provided for educational purposes and self-hosting.

​
Installation

1

Clone the Repository

Start by cloning the Quail repository from GitHub:
git clone https://github.com/O1af/quail.git
cd quail
2

Install Dependencies

Install all required packages using pnpm:
pnpm install
The installation process may take a few minutes as it downloads all dependencies.
3

Configure Environment Variables

Copy the example environment file and configure your settings:
cp .env.example .env.local
Open .env.local and configure the required variables.

​
Environment Configuration

​
Required Variables

These environment variables are required for Quail to function: 
# Encryption Key (REQUIRED)
# Generate with: openssl rand -base64 32
NEXT_PUBLIC_ENCRYPTION_KEY=your-32-character-encryption-key

# Supabase Configuration (REQUIRED)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

# MongoDB Configuration (REQUIRED)
MONGODB_URI=mongodb+srv://username:[email protected]/quail

# Application URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

​
Generate Encryption Key

The encryption key is used to secure database credentials. Generate a secure key using OpenSSL: 
openssl rand -base64 32
Store your encryption key securely. If you lose it, you won’t be able to decrypt existing database connections.

​
Supabase Setup

  1. Create a new project at supabase.com
  2. Navigate to Settings → API
  3. Copy your Project URL to NEXT_PUBLIC_SUPABASE_URL
  4. Copy the anon/public key to NEXT_PUBLIC_SUPABASE_ANON_KEY
  5. Copy the service_role key to SUPABASE_SERVICE_ROLE_KEY
Supabase provides authentication, user management, and secure session handling for Quail.

​
MongoDB Setup

Quail uses MongoDB to store:
  • User profiles and settings
  • Dashboard configurations
  • Chart definitions
  • Chat history
  • Saved queries
You can use:
  • MongoDB Atlas (cloud-hosted, free tier available)
  • Local MongoDB instance
  • Docker container
# MongoDB Atlas connection string format
mongodb+srv://<username>:<password>@<cluster-url>/<database>?retryWrites=true&w=majority

# Local MongoDB connection string format
mongodb://localhost:27017/quail

​
Optional Variables

# Azure AI Configuration (for AI features)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-azure-openai-key
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4

# Stripe Configuration (for billing)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Default Database Connection (optional demo database)
NEXT_PUBLIC_DEFAULT_DB_CONNECTION_STRING=postgres://demo:password@localhost:5432/demo
Azure AI configuration is required for AI-powered SQL generation and chart recommendations. Without it, these features will not function.

​
Running Quail

1

Start Development Server

Launch the development server with hot reloading:
pnpm dev
The application will be available at http://localhost:3000
2

Create Your Account

  1. Navigate to http://localhost:3000
  2. Click Sign Up
  3. Enter your email and password
  4. Verify your email address (check Supabase email settings)
3

Complete Initial Setup

After logging in, you’ll see the onboarding flow. Complete these steps:
  • Configure your profile settings
  • Review the feature tour
  • Explore the interface

​
Connecting Your First Database

1

Navigate to Connections

Click on Connections in the sidebar to access the database connection manager.
2

Add New Connection

Click the Add Connection button in the top-right corner.
3

Enter Database Details

Fill in the connection form with your database information:
Connection Name: My Production DB
Database Type: PostgreSQL
Host: localhost
Port: 5432
Database: mydb
Username: readonly_user
Password: ••••••••••
Use read-only database credentials for security. Quail only executes SELECT queries, but using read-only credentials adds an extra layer of protection.
4

Test Connection

Click Test Connection to verify that Quail can connect to your database.If the test fails:
  • Verify your credentials are correct
  • Check that your database allows connections from your IP
  • Ensure the database server is running
  • Verify firewall rules allow the connection
5

Save Connection

Once the test succeeds, click Save to store the connection.
Your credentials are encrypted using AES-256 encryption before being stored in MongoDB.
6

Explore Schema

After saving, click on your connection to view the database schema:
  • Browse tables and views
  • Inspect column types
  • View indexes and constraints
  • Explore relationships

​
Running Your First Query

1

Open the Editor

Navigate to the Editor page from the sidebar.
2

Select Your Database

Choose your connected database from the dropdown in the header.
3

Ask a Natural Language Question

In the chat input at the bottom, type a question about your data:
What were our total sales by month for the last year?
4

Review Generated SQL

Quail’s AI will:
  1. Analyze your question
  2. Examine your database schema
  3. Generate an optimized SQL query
  4. Display the query in the SQL editor
SELECT 
  DATE_TRUNC('month', order_date) as month,
  SUM(total_amount) as total_sales
FROM orders
WHERE order_date >= CURRENT_DATE - INTERVAL '1 year'
GROUP BY DATE_TRUNC('month', order_date)
ORDER BY month;
5

Execute and Visualize

Click the Run button to execute the query.Quail will:
  1. Execute the SQL query
  2. Display results in a table
  3. Automatically generate appropriate visualizations
  4. Provide insights about the data
6

Save Your Chart

If you’re happy with the visualization:
  1. Click Save Chart in the header
  2. Give it a descriptive name
  3. Add it to a dashboard (optional)
  4. Share with team members (optional)

​
Creating Your First Dashboard

1

Navigate to Dashboards

Click Dashboards in the sidebar.
2

Create New Dashboard

Click Create Dashboard button and enter:
  • Title: Q1 2024 Sales Analysis
  • Description: Overview of sales performance and trends
3

Add Charts

In the dashboard editor:
  1. Click Add Chart
  2. Select from your saved charts
  3. Drag and resize to arrange
  4. Customize colors and styles
4

Configure Refresh

Set up automatic data refresh:
  • Real-time (WebSocket)
  • Every 5 minutes
  • Every hour
  • Manual only
5

Share Your Dashboard

Click the Share button to:
  • Generate a shareable link
  • Invite team members by email
  • Set view/edit permissions
  • Export as PDF

​
Production Deployment

For production deployment, build the application: 
pnpm build
pnpm start
The build process:
  1. Compiles TypeScript to JavaScript
  2. Optimizes React components
  3. Generates static pages where possible
  4. Creates a standalone deployment package
The build output is located in .next/standalone and includes all necessary files for deployment.

​
Next Steps

Explore Features

Learn about all the powerful features Quail offers

Configure Speed Mode

Optimize AI response times with different speed modes

Set Up Team Access

Configure permissions and share dashboards with your team

Export Data

Learn how to export data in CSV, Excel, and PDF formats

​
Troubleshooting

​
Application Won’t Start

Check that all required environment variables are set. Missing NEXT_PUBLIC_ENCRYPTION_KEY will cause startup failure.

​
Database Connection Fails

  • Verify credentials are correct
  • Check firewall rules
  • Ensure database server is accessible
  • Test connection with a database client first

​
AI Features Not Working

  • Verify Azure OpenAI credentials are configured
  • Check API quota and usage limits
  • Ensure deployment name matches your Azure configuration

​
Charts Not Rendering

  • Check browser console for errors
  • Verify data format is compatible with chart type
  • Try a different chart type
  • Clear browser cache and reload

Build docs developers (and LLMs) love

Get started for freeTalk to us