Quickstart

Prerequisites

Before you begin, make sure you have the following installed:

Requirement	Minimum Version	Installation
Bun	1.1.0+	bun.sh
Redis	7.0+	redis.io/docs/install

You will also need accounts for these services (free tiers available):

Stripe - Payment processing (test mode works without a paid account)
Turso - Cloud database (optional for local development)

For local development, BunShip uses a file-based SQLite database by default. You only need Turso for cloud/production deployments.

Setup

Clone the repository

git clone https://github.com/bunship/bunship.git my-saas
cd my-saas

Install dependencies

BunShip is a monorepo managed with Bun workspaces and Turborepo. A single install pulls in all packages: the API, database layer, email templates, config, utilities, and the Eden type-safe client.

bun install

This also creates a .env file from .env.example with working defaults for local development.

Generate JWT secrets (recommended)

The auto-generated .env includes placeholder secrets that work for development, but you should replace them with random values — especially before deploying anywhere.Generate two separate secrets and paste them into your .env:

openssl
Bun

# Generate JWT_SECRET
openssl rand -base64 48

# Generate JWT_REFRESH_SECRET (run the same command again for a different value)
openssl rand -base64 48

bun -e "console.log(crypto.randomUUID() + crypto.randomUUID())"

Open .env and replace the placeholder values:

JWT_SECRET=<paste-first-secret-here>
JWT_REFRESH_SECRET=<paste-second-secret-here>

Use different values for each secret. Both must be at least 32 characters. Never commit your .env file to version control.

See the Installation guide for a full breakdown of every environment variable.

Set up the database

Run migrations to create all tables, then optionally seed demo data:

bun run db:migrate
bun run db:seed   # optional - creates a demo user and organization

If you ran the seed command, you can log in with:

Email:    demo@bunship.com
Password: demo123456

Start the development server

bun dev

The API is now running at http://localhost:3000.

Verify It Works

Once the server is running, confirm everything is healthy:

Health check
API documentation
Test login

curl http://localhost:3000/health

Expected response:

{ "status": "ok", "timestamp": "2025-01-28T..." }

If you ran db:seed, test authentication with:

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@bunship.com","password":"demo123456"}'

You should receive a JSON response containing accessToken and refreshToken.

Project Structure

Here is how the monorepo is organized:

bunship/
├── apps/
│   ├── api/                 # Main Elysia API
│   │   ├── src/
│   │   │   ├── index.ts     # Entry point
│   │   │   ├── routes/      # API endpoint handlers
│   │   │   ├── middleware/   # Auth, org, permission middleware
│   │   │   ├── services/    # Business logic
│   │   │   └── jobs/        # Background job workers
│   └── docs/                # This documentation (Mintlify)
├── packages/
│   ├── config/              # Shared configuration
│   ├── database/            # Drizzle schema & migrations
│   ├── emails/              # Email templates (React Email)
│   ├── eden/                # Type-safe API client
│   └── utils/               # Shared utilities
├── docker/                  # Docker configuration
├── .env.example             # Environment variable template
├── package.json             # Workspace root
└── turbo.json               # Turborepo configuration

Common Scripts

Command	Description
`bun dev`	Start the API in development mode with file watching
`bun dev:all`	Start all apps (API + docs) via Turborepo
`bun run db:generate`	Generate a migration from schema changes
`bun run db:migrate`	Apply pending migrations
`bun run db:seed`	Seed demo data
`bun run db:studio`	Open Drizzle Studio (visual database browser)
`bun test`	Run all tests
`bun run build`	Build all packages for production

What’s Next

Installation

Full environment configuration including Stripe, email, S3 storage, and OAuth providers

Architecture

Understand how BunShip organizes routes, services, and middleware

Authentication

JWT tokens, 2FA, magic links, and OAuth flows

API Reference

Interactive documentation for every endpoint

Getting Started

Core Concepts

Features

Customization

Deployment

Prerequisites

Setup

Verify It Works

Project Structure

Common Scripts

What’s Next

Installation

Architecture

Authentication

API Reference

​Prerequisites

​Setup

​Verify It Works

​Project Structure

​Common Scripts

​What’s Next

Installation

Architecture

Authentication

API Reference

Prerequisites

Setup

Verify It Works

Project Structure

Common Scripts

What’s Next