Skip to main content

​
Prerequisites

Before installing Quail BI, ensure you have the following:

Node.js

Version 18.17.0 or higher

Package Manager

pnpm 10.10.0 (recommended), npm, or yarn

MongoDB

MongoDB instance for storing user data and configurations

Supabase

Supabase project for authentication
Quail is a discontinued project. This documentation is for self-hosting purposes.

​
Step 1: Clone the Repository

Clone the Quail repository from GitHub: 
git clone [email protected]:O1af/quail.git
cd quail

​
Step 2: Install Dependencies

Quail uses pnpm as its package manager: 
# Install pnpm globally if not already installed
npm install -g [email protected]

# Install dependencies
pnpm install
The project specifies Node.js ≥18.17.0 in package.json engines field. Using an older version may cause compatibility issues.

​
Step 3: Configure Environment Variables

Copy the example environment file: 
cp .env.example .env.local
Edit .env.local with your configuration. See Environment Variables for detailed explanations of each variable.

​
Required Variables

At minimum, you must configure:
.env.local
# Encryption (REQUIRED)
NEXT_PUBLIC_ENCRYPTION_KEY=your-32-character-key

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

# MongoDB (REQUIRED)
MONGODB_URI=mongodb+srv://user:[email protected]/quail
The NEXT_PUBLIC_ENCRYPTION_KEY must be exactly 32 characters when base64-decoded. Generate it with:
openssl rand -base64 32

​
Step 4: Set Up Database Services

Quail requires two database services:

​
MongoDB Setup

1

Create MongoDB Database

Create a MongoDB database using MongoDB Atlas, a local instance, or any MongoDB-compatible service.
2

Get Connection String

Obtain your connection string in the format:
mongodb+srv://username:[email protected]/database_name
3

Configure Environment

Add the connection string to MONGODB_URI in .env.local

​
Supabase Setup

1

Create Supabase Project

Sign up at supabase.com and create a new project.
2

Get API Keys

Navigate to Settings → API in your Supabase dashboard and copy:
  • Project URL
  • anon public key
  • service_role secret key
3

Configure Environment

Add these to your .env.local file
See Database Setup for detailed instructions.

​
Step 5: Run Development Server

Start the development server: 
pnpm dev
The application will start at http://localhost:3000.
Quail uses Turbopack for faster development builds via the --turbopack flag in the dev script.

​
Step 6: Build for Production

When you’re ready to deploy:
1

Build the Application

pnpm build
This creates an optimized production build in .next/
2

Start Production Server

pnpm start
The production server runs on port 3000 by default.

​
Standalone Build

The build script includes additional steps for standalone deployment:
package.json
"build": "next build && cp -r .next/static .next/standalone/.next/ && cp -r public .next/standalone/"
This creates a standalone build that includes all necessary files for deployment.

​
Deployment Options

1

Connect Repository

Import your Quail repository in the Vercel dashboard
2

Configure Environment Variables

Add all required environment variables in the Vercel project settings
3

Deploy

Vercel automatically builds and deploys your application
Vercel provides zero-config deployment for Next.js applications.

​
Docker

Create a Dockerfile:
Dockerfile
FROM node:18-alpine AS base

# Install dependencies
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json pnpm-lock.yaml ./
RUN npm install -g [email protected] && pnpm install --frozen-lockfile

# Build application
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED 1
RUN npm install -g [email protected] && pnpm build

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000
ENV HOSTNAME "0.0.0.0"

CMD ["node", "server.js"]
Build and run: 
docker build -t quail-bi .
docker run -p 3000:3000 --env-file .env.local quail-bi

​
Other Platforms

Deploy to AWS using:
  • Amplify: Connect GitHub repo for automatic deployments
  • Elastic Beanstalk: Upload standalone build
  • ECS: Use Docker container
  • Lambda: Use Serverless Next.js

​
Post-Installation

After installation:
1

Create Admin Account

Visit /signup to create your first user account
2

Configure Database Connections

Add your first database connection in the UI
3

Test Query

Run a test query to verify everything works

​
Troubleshooting

Ensure you’ve run pnpm install and all dependencies are installed:
rm -rf node_modules .next
pnpm install
pnpm build
Check that all required environment variables are set:
# Verify .env.local exists and contains required variables
cat .env.local | grep NEXT_PUBLIC_ENCRYPTION_KEY
Verify your MongoDB connection string:
  1. Check the URI format
  2. Ensure network access is allowed
  3. Verify username and password
  4. Test connection with MongoDB Compass
Verify Supabase configuration:
  1. Check that all three Supabase environment variables are set
  2. Verify the project URL is correct
  3. Ensure keys are from the same project
  4. Check that email authentication is enabled in Supabase dashboard
For more troubleshooting help, see Troubleshooting.

​
Next Steps

Environment Variables

Complete guide to all environment variables

Database Setup

Detailed MongoDB and Supabase configuration

Configuration

Customize Quail for your needs

Security

Secure your deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us