Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:
RequirementMinimum VersionInstallation
Bun1.1.0+bun.sh
Redis7.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

1

Clone the repository

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

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
3

Configure environment variables

Copy the example environment file and generate JWT secrets:
cp .env.example .env
Open .env and set at minimum these two values to secure random strings:
JWT_SECRET=<generate-a-32-char-random-string>
JWT_REFRESH_SECRET=<generate-a-different-32-char-random-string>
Generate a secret with:
bun -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
The remaining defaults (local SQLite database, localhost Redis) work out of the box for development. See the Installation guide for a full breakdown of every environment variable.
4

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:    [email protected]
Password: demo123456
5

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: 
curl http://localhost:3000/health
Expected response:
{ "status": "ok", "timestamp": "2025-01-28T..." }

​
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

CommandDescription
bun devStart the API in development mode with file watching
bun dev:allStart all apps (API + docs) via Turborepo
bun run db:generateGenerate a migration from schema changes
bun run db:migrateApply pending migrations
bun run db:seedSeed demo data
bun run db:studioOpen Drizzle Studio (visual database browser)
bun testRun all tests
bun run buildBuild 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