Step 1: Clone Repository

git clone https://github.com/zephverse/zephyr.git
cd zephyr

This clones the repository and changes into the project directory.

Step 2: Install Dependencies

bun install

This installs all dependencies for apps and packages in the monorepo.

What happens:

1. Bun reads workspaces from package.json
2. Installs dependencies for all apps/* and packages/*
3. Runs postinstall script → Generates Prisma client

Duration: 1-3 minutes on first install

Step 3: Configure Environment

Copy example environment files:

bun run env:dev

What this does:

• Copies apps/web/.env.example → apps/web/.env
• Copies apps/auth/.env.example → apps/auth/.env

These files contain:

• Database connection strings
• Redis URL
• MinIO credentials and endpoint
• Resend API key (email service)
• Better Auth secret
• Other required configuration

Required Environment Variables

The .env.example files include required variables that have no defaults:

apps/web/.env:

• DATABASE_URL - PostgreSQL connection
• POSTGRES_PRISMA_URL - Pooled connection
• POSTGRES_URL_NON_POOLING - Direct connection
• REDIS_URL - Redis connection
• MINIO_ENDPOINT - MinIO S3 endpoint

apps/auth/.env:

• Same database URLs
• RESEND_API_KEY - Email service API key
• BETTER_AUTH_SECRET - Auth encryption secret

Optional: Add OAuth Credentials

If you want social login, edit the .env files to add:

# In apps/auth/.env
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"
# ... etc

See Environment Configuration for complete details.

Step 4: Start Infrastructure

Docker (Recommended)

Start all infrastructure services with one command:

bun run docker:dev

What this starts:

• PostgreSQL database
• Redis cache
• MinIO object storage
• Meilisearch search engine
• RabbitMQ message queue
• TimescaleDB analytics database
• Prisma Studio (database GUI)
• RedisInsight (Redis GUI)

Duration:

• First time: 5-10 minutes (downloads images)
• Subsequent: 30 seconds

Verify services are running:

docker ps
 
# You should see 8 containers running

Step 5: Initialize Database

Push the Prisma schema to your database:

bun run db:up

What this does:

1. Generates Prisma client (bunx prisma generate)
2. Pushes schema to PostgreSQL (bunx prisma db push)
3. Creates all tables, relations, and indexes

Output should show:

✔ Generated Prisma Client
🚀 Your database is now in sync with your Prisma schema.

Step 6: Run Applications

Start all apps in development mode:

bun run dev

What this does:

• Starts all apps using Turbo (turbo dev)
• Runs apps/web, apps/auth, and apps/docs in parallel
• Enables hot module replacement (HMR) with Turbopack
• Watches for file changes

Output:

• Packages in scope: @zephyr/web, @zephyr/auth, @zephyr/docs
• Running dev in 3 packages
• Remote caching disabled

@zephyr/web:dev: ready - started server on 0.0.0.0:3000
@zephyr/auth:dev: ready - started server on 0.0.0.0:3001
@zephyr/docs:dev: ready - started server on 0.0.0.0:3002

Step 7: Verify Installation

Check Web App

Open http://localhost:3000  - you should see the Zephyr login page.

Check Auth Service

Open http://localhost:3001  - you should see the authentication admin panel.

Check Docs

Open http://localhost:3002  - you should see this documentation site.

Check Database (Prisma Studio)

Open http://localhost:5555  - browse your PostgreSQL data.

Check Redis (RedisInsight)

Open http://localhost:5540  - inspect Redis keys and data.

Check MinIO Console

Open http://localhost:9001  - manage uploaded files.

• Username: minioadmin
• Password: minioadmin

Installation Complete! 🎉

Your development environment is ready. All services are running and properly configured.

Next: Create Your First Account

1. Open http://localhost:3000/signup 
2. Create a test account (requires valid email for verification)
3. Check your email for the verification link (sent via Resend)
4. Log in and start using Zephyr

Optional: Initialize Search

After creating an account, populate the Meilisearch index:

bun run search:init

This imports all users into the search engine for the user discovery features.

Start Developing

• Explore the codebase in your editor
• Make changes and see them hot-reload instantly
• Check out the Development section for workflow guides
• Browse the Architecture to understand the codebase

Alternative: Full Docker Setup

If you want to run apps in Docker too (not recommended for development):

# Start infrastructure
bun run docker:dev
 
# Build and start apps
bun run docker:apps

This builds Docker images for web, auth, and docs apps, which takes longer and doesn’t support HMR.

Post-Installation Tips

VS Code Integration

If using VS Code, install recommended extensions:

1. Open VS Code in the project: code .
2. Click “Install” when prompted for workspace recommendations
3. Extensions: Biome, Prisma, MDX, Tailwind CSS

Git Hooks

Husky git hooks are automatically set up to:

• Run linting before commits
• Check types before push

Scripts Reference

Next Steps

• Environment Configuration - Configure environment variables
• Verification Guide - Test all features work
• Troubleshooting - Fix common issues