0.email

Quick setup guide to get Zero Email Client running in minutes with installation and configuration.

This guide covers installation, basic configuration, and initial setup of the Zero email client.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18 or higher)
pnpm (v8 or higher)
Git

Installation

Fork the Repository

Clone the Repository

Install Dependencies

Environment Setup

Database Setup

Start Development Server

1. Clone the Repository

Clone Repository

git clone https://github.com/your-username/zero.git
cd zero

2. Install Dependencies

Install Dependencies

pnpm install

3. Environment Setup

Copy the environment template and configure your settings:

Environment Setup

cp .env.example .env

Edit the .env file with your configuration:

.env Configuration

# Application URLs
VITE_PUBLIC_APP_URL=http://localhost:3000
VITE_PUBLIC_BACKEND_URL=http://localhost:8787

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/zerodotemail"

# Authentication
BETTER_AUTH_SECRET="your-super-secret-key-here"
BETTER_AUTH_URL=http://localhost:3000
COOKIE_DOMAIN="localhost"

# OAuth Configuration
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Redis/Valkey (for local development with Docker)
REDIS_URL="http://localhost:8079"
REDIS_TOKEN="upstash-local-token"

# Email Service (Optional)
RESEND_API_KEY="your-resend-api-key"

# AI Services (Optional)
OPENAI_API_KEY="your-openai-api-key"
PERPLEXITY_API_KEY="your-perplexity-api-key"
AI_SYSTEM_PROMPT=""

4. Database Setup

Zero uses Docker Compose for local development services (PostgreSQL, Redis/Valkey).

Database Setup

# Start Docker services (PostgreSQL + Redis/Valkey)
pnpm docker:db:up

# Generate and run migrations
pnpm db:generate
pnpm db:migrate

5. Start Development Servers

Zero runs two main services in development:

Start Development

# Quick start (starts database and all services)
pnpm go

# Or start services individually:
# Start all development servers
pnpm dev

# Start database services first
pnpm docker:db:up

# Then start individual services from their directories:
# cd apps/mail && pnpm dev     # Frontend (React Router + Vite)
# cd apps/server && pnpm dev   # Backend (Cloudflare Workers)

Frontend: http://localhost:3000
Backend API: http://localhost:8787
Database Studio: http://localhost:4983 (when running pnpm db:studio)

First Time Setup

Create Your Account

Connect Your Email

Customize Your Workspace

1. Create Your Account

Navigate to http://localhost:3000
Click "Sign Up" to create your account
Verify your email address
Complete the onboarding process

2. Connect Your Email

Zero uses OAuth to securely connect to your email providers.

Go to Settings > Connections
Add your email provider (currently supports Gmail via OAuth)
Authorize the connection through Google OAuth
Your emails will be accessible through the MCP service

3. Customize Your Workspace

Set up your preferred labels and folders
Configure notification settings
Customize the interface theme
Set up keyboard shortcuts

Development Commands

# Start all development servers
pnpm dev

# Start individual services (from root)
pnpm dev:docs    # Documentation
# Or run individual services from their directories:
# cd apps/mail && pnpm dev     # Frontend (React Router)
# cd apps/server && pnpm dev   # Backend (Cloudflare Workers)

# Alternatively, use the quick start command
pnpm go  # Starts database and development servers

# Lint code
pnpm lint

# Format code
pnpm format

# Check format
pnpm check

Build Commands

# Build all applications
pnpm build

# Build individual apps (from root)
pnpm build:docs        # Build documentation
pnpm build:frontend    # Build frontend (mail app)

# Deploy individual apps (from root)
pnpm deploy:frontend   # Deploy frontend
pnpm deploy:backend    # Deploy backend

# Start applications (from individual app directories)
# cd apps/mail && pnpm start    # Start frontend
# cd apps/server && pnpm start  # Start backend

Database Commands

# Start database services
pnpm docker:db:up
# Alternative: docker compose -f docker-compose.db.yaml up -d

# Stop database services
pnpm docker:db:stop

# Stop and remove database services
pnpm docker:db:down

# Clean database (remove volumes)
pnpm docker:db:clean

# Generate migrations
pnpm db:generate

# Run migrations
pnpm db:migrate

# Push schema changes (development)
pnpm db:push

# Open database studio
pnpm db:studio

Getting Started