LogoZero
Getting Started

Installation Guide

Comprehensive installation instructions for Zero Email Client across different platforms and environments.

This guide provides comprehensive installation instructions for Zero across different platforms and deployment scenarios.

System Requirements

Minimum Requirements

  • OS: macOS 10.15+, Windows 10+, or Linux (Ubuntu 18.04+)
  • Node.js: v18.0.0 or higher
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 2GB free space

Recommended Requirements

  • Node.js: v20.0.0 or higher
  • RAM: 16GB or more
  • Storage: 10GB free space (for development)
  • CPU: Multi-core processor

Package Manager Setup

pnpm is recommended for better performance and disk space efficiency.

Install pnpm
# Via npm
npm install -g pnpm

# Via Homebrew (macOS)
brew install pnpm

# Via curl
curl -fsSL https://get.pnpm.io/install.sh | sh
Using npm
npm install
Using Yarn
yarn install

Installation Methods

Fork the Zero repository Recommended method for development and contributions.

Clone Repository
  # Clone the Forked Repo with HTTPS
  git clone https://github.com/your-username/zero.git

  # Clone with SSH
  git clone [email protected]:your-username/zero.git

  # Clone specific branch
  git clone -b develop https://github.com/your-username/zero.git
Fork the Zero repository
Visit the GitHub repository
Click "Code" → "Download ZIP"
Extract the ZIP file
Navigate to the extracted folder
Using Degit
npx degit Mail-0/Zero my-zero-app
cd my-zero-app

Environment Configuration

1. Environment Variables

Create and configure your environment file:

Copy .env.example
cp .env.example .env

2. Required Environment Variables

Required .env Variables
# 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 Configuration
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=""

# Development Environment
NODE_ENV="development"

# Security (Optional)
AUTUMN_SECRET_KEY="your-autumn-secret-key"

# SMS/Voice Services (Optional)
TWILIO_ACCOUNT_SID="your-twilio-sid"
TWILIO_AUTH_TOKEN="your-twilio-token"
TWILIO_PHONE_NUMBER="your-twilio-phone"

3. Database Setup Options

Docker Database Setup
# Start PostgreSQL database with Docker Compose
pnpm docker:db:up

This is the recommended setup as it includes PostgreSQL, Redis/Valkey, and other required services.

Option B: Local PostgreSQL

PostgreSQL Setup
# Install PostgreSQL
brew install postgresql  # macOS
sudo apt install postgresql postgresql-contrib  # Ubuntu

# Start PostgreSQL service
brew services start postgresql  # macOS
sudo systemctl start postgresql  # Ubuntu

# Create database
createdb zero_dev

Option C: Local Development (Docker - Recommended)

Docker Development Setup
# Start PostgreSQL, Redis/Valkey, and proxy services
pnpm docker:db:up

# This starts:
# - PostgreSQL on port 5432
# - Valkey (Redis-compatible) on port 6379  
# - Upstash Redis HTTP proxy on port 8079

This is the recommended setup for local development as it matches the production environment and includes all necessary services.

Installation Steps

1. Install Dependencies

Install Dependencies
cd zero
pnpm install

2. Generate Database Schema

Generate DB Schema
pnpm db:generate

3. Run Database Migrations

Run DB Migrations
pnpm db:migrate

4. Start Development Server

Start Development Server
# Quick start (starts database + dev servers)
pnpm go

# Or start manually
pnpm docker:db:up  # Start database first
pnpm dev           # Then start dev servers

Quick Start: Use pnpm go to automatically start the database and development servers in one command.

nizzy CLI Tool

Zero Email Client includes a powerful CLI tool called nizzy for project management and synchronization.

Installation

The nizzy CLI is included as part of the project dependencies and is available after running pnpm install.

Usage

nizzy CLI Commands
# Synchronize environment and types
pnpm nizzy sync

# Fix environment variable issues
pnpm nizzy fix-env

# Reinstall node modules cleanly
pnpm nizzy reinstall-node-modules

# Show help and available commands
pnpm nizzy --help
Typical Workflow
# After cloning the repository
pnpm install
pnpm nizzy sync  # Automatically runs after install

# When environment issues occur
pnpm nizzy fix-env

# When dependencies are corrupted
pnpm nizzy reinstall-node-modules
Interactive CLI
# Run without arguments for interactive mode
pnpm nizzy

# Select from available options:
# - Sync your environment variables and types
# - Fix environment variable issues  
# - Reinstall node modules cleanly

The nizzy CLI tool is essential for keeping your development environment synchronized and up-to-date.

Platform-Specific Instructions

macOS

macOS Installation
# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js via Homebrew
brew install node

# Install pnpm
brew install pnpm

# Continue with standard installation

Windows

Windows Installation
# Install Node.js from nodejs.org or via Chocolatey
choco install nodejs

# Install pnpm
npm install -g pnpm

# Continue with standard installation

Linux (Ubuntu/Debian)

Linux Installation
# Install Node.js via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm
curl -fsSL https://get.pnpm.io/install.sh | sh

Docker Installation

Terminal
# Development environment
docker-compose up -d

# Production environment
docker-compose -f docker-compose.prod.yaml up -d

Manual Docker Setup

Terminal
# Build the image
docker build -t zero-email .

# Run the container
docker run -p 3000:3000 -e NODE_ENV=production zero-email

Verification

1. Check Installation

Terminal
# Verify Node.js version
node --version

# Verify pnpm version
pnpm --version

# Check if all dependencies are installed
pnpm list

2. Run Health Check

Terminal
# Start the application
pnpm dev

# Open browser to http://localhost:3000
# You should see the Zero Email Client interface

3. Test Database Connection

Terminal
# Open database studio
pnpm db:studio

# Check database with studio interface
# Studio will open at http://localhost:4983

Troubleshooting

Common Installation Issues

Node.js version mismatch

Terminal
# Use Node Version Manager (nvm)
nvm install 20
nvm use 20

Permission errors on Linux/macOS

Terminal
# Fix npm permissions
sudo chown -R $(whoami) ~/.npm

Port already in use

.env
PORT=3001

Database connection errors

  • Verify DATABASE_URL in .env
  • Ensure database server is running
  • Check firewall settings

nizzy CLI issues

Terminal
# Reinstall CLI dependencies
pnpm install --force

# Check nizzy is available
pnpm nizzy --help

# Clear nizzy cache
pnpm nizzy clean

Docker services not starting

Terminal
# Check Docker service status
pnpm docker:db:up

# View service logs
docker compose -f docker-compose.db.yaml logs

# Restart services
pnpm docker:db:down && pnpm docker:db:up

Port conflicts

Check which process is using a port
# macOS/Linux
lsof -i :3000
lsof -i :8787

# Windows
netstat -ano | findstr :3000

Build errors

Terminal
# Clear all caches and reinstall
rm -rf node_modules
rm -rf .next
rm pnpm-lock.yaml
pnpm install

# Check turbo cache
pnpm turbo clean

Still having issues? Check the GitHub Issues for similar problems or create a new issue with your error details.

Configuration Guide

Complete configuration reference covering all options from basic setup to advanced customization.