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
This also creates a .env file from .env.example with working defaults for local development.
3

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:
# Generate JWT_SECRET
openssl rand -base64 48

# Generate JWT_REFRESH_SECRET (run the same command again for a different value)
openssl rand -base64 48
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.
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:    demo@bunship.com
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