Installation

System Requirements

Software	Version	Required	Purpose
Bun	1.1.0+	Yes	JavaScript runtime and package manager
Redis	7.0+	Yes	Background job queues (BullMQ) and caching
Turso CLI	Latest	No	Cloud SQLite database management
Stripe CLI	Latest	No	Local webhook forwarding during development

Install Dependencies

Install Bun

curl -fsSL https://bun.sh/install | bash

Verify the installation:

bun --version
# Should print 1.1.0 or later

Install Redis

macOS
Ubuntu / Debian
Docker

brew install redis
brew services start redis

sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

docker run -d --name redis -p 6379:6379 redis:7-alpine

Verify Redis is running:

redis-cli ping
# Should return: PONG

Clone and install

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

This installs all workspace packages and automatically creates a .env file from .env.example with working defaults for local development:

Package	Path	Description
`@bunship/api`	`apps/api`	Main Elysia API application
`@bunship/database`	`packages/database`	Drizzle ORM schema and migrations
`@bunship/config`	`packages/config`	Shared configuration
`@bunship/emails`	`packages/emails`	React Email templates
`@bunship/eden`	`packages/eden`	Type-safe API client
`@bunship/utils`	`packages/utils`	Shared utilities

If .env already exists, it will not be overwritten. To start fresh, delete it and run bun install again.

Environment Configuration

Application Settings

These control the runtime mode and URL references used in CORS headers, email links, and OAuth redirects.

NODE_ENV=development
API_URL=http://localhost:3000
FRONTEND_URL=http://localhost:5173

Variable	Description	Default
`NODE_ENV`	`development`, `production`, or `test`	`development`
`API_URL`	Public URL of the API (used in email links and OAuth callbacks)	`http://localhost:3000`
`FRONTEND_URL`	Public URL of your frontend (used for CORS and redirect URLs)	`http://localhost:5173`

JWT Authentication

BunShip uses a dual-token JWT strategy: short-lived access tokens (default 15 minutes) and long-lived refresh tokens (default 7 days). Each token type is signed with its own secret so that compromising one does not compromise the other.

JWT_SECRET=<access-token-signing-secret>
JWT_REFRESH_SECRET=<refresh-token-signing-secret>

The auto-generated .env includes placeholder secrets that work for local development. Before deploying, replace them with cryptographically random values.

How to generate a JWT secret

Pick whichever tool you have available — the result is the same: a long, random string.

openssl (recommended)
Bun
Node.js

Available on macOS and most Linux distributions out of the box.

openssl rand -base64 48

Run it twice — once for JWT_SECRET, once for JWT_REFRESH_SECRET.

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

node -e "console.log(require('crypto').randomBytes(48).toString('base64'))"

Paste the output into your .env:

JWT_SECRET=aB3dE6gH9jK2mN5pQ8rS1uV4wX7yZ0bC3fG6hJ9kL2n
JWT_REFRESH_SECRET=xY7zW4vU1tS8rQ5pO2nM9lK6jH3gF0eD7cB4aZ1xW8v

Use different values for JWT_SECRET and JWT_REFRESH_SECRET. Both must be at least 32 characters. Never commit real secrets to version control — .env is already in .gitignore.

What happens if I skip this?

The placeholder secrets in .env.example work fine for local development. But if you deploy with the default values, anyone who reads the source code can forge authentication tokens for your API. Always generate unique secrets before deploying.

Database Setup

BunShip uses Drizzle ORM with Turso (libSQL/SQLite). For local development you can use a file-based SQLite database with zero external dependencies.

Local Development (File-Based)

The default .env.example is already configured for local file storage:

TURSO_DATABASE_URL=file:../../local.db

No additional setup is needed. The database file is created automatically when you run migrations.

Turso Cloud

For staging or production, connect to a Turso cloud database:

Install the Turso CLI

curl -sSfL https://get.tur.so/install.sh | bash

Authenticate

bash turso auth login

Create a database

bash turso db create bunship

Get connection credentials

# Database URL
turso db show bunship --url

# Auth token
turso db tokens create bunship

Update your .env

TURSO_DATABASE_URL=libsql://your-database-name.turso.io
TURSO_AUTH_TOKEN=your-turso-auth-token

Run Migrations and Seed

# Apply the schema
bun run db:migrate

# Optional: populate demo data
bun run db:seed

The seed creates:

Demo user — demo@bunship.com / demo123456
Demo organization with a Pro plan on trial
Sample projects attached to the organization

Other database commands

| Command | Description | |---------|-------------| | bun run db:generate | Generate a new migration after editing the Drizzle schema | | bun run db:push | Push schema directly to the database (development only) | | bun run db:studio | Open Drizzle Studio, a visual database browser | | bun run db:reset | Drop all tables and re-run migrations (destroys all data) |

Stripe Setup

BunShip includes subscription management with free, Pro, and Enterprise tiers. All Stripe integration works in test mode without processing real payments.

Create a Stripe account

Get your API keys

Navigate to Developers > API keys in the Stripe Dashboard and copy your Secret key (starts with sk_test_).

STRIPE_SECRET_KEY=sk_test_xxx

Create products and prices

Go to Products in the Stripe Dashboard and create your pricing tiers. You need price IDs for each plan and billing interval:

STRIPE_PRO_MONTHLY_PRICE_ID=price_xxx
STRIPE_PRO_YEARLY_PRICE_ID=price_xxx
STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=price_xxx
STRIPE_ENTERPRISE_YEARLY_PRICE_ID=price_xxx

Set up webhooks

Stripe sends events (subscription created, payment failed, etc.) to your API via webhooks.For local development, use the Stripe CLI:

# Install: https://stripe.com/docs/stripe-cli
stripe login
stripe listen --forward-to localhost:3000/webhooks/stripe

The CLI prints a webhook signing secret (whsec_...). Add it to your .env:

STRIPE_WEBHOOK_SECRET=whsec_xxx

For production, add a webhook endpoint in the Stripe Dashboard (Developers > Webhooks) pointing to https://your-domain.com/webhooks/stripe and subscribe to these events:

checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_failed

Stripe billing is optional for initial development. If STRIPE_SECRET_KEY is not set, billing endpoints return a configuration error but the rest of the API works normally.

S3 / R2 Storage Setup

File uploads use any S3-compatible object storage. Choose the tab matching your provider.

AWS S3
Cloudflare R2
MinIO (local)

S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET=your-bucket
S3_ACCESS_KEY_ID=AKIAxxxx
S3_SECRET_ACCESS_KEY=xxxx
S3_REGION=us-east-1

Create an S3 bucket in the AWS Console and an IAM user with s3:PutObject, s3:GetObject, and s3:DeleteObject permissions scoped to that bucket.

S3_ENDPOINT=https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
S3_BUCKET=your-bucket
S3_ACCESS_KEY_ID=xxxx
S3_SECRET_ACCESS_KEY=xxxx
S3_REGION=auto

Create an R2 bucket in the Cloudflare dashboard and generate an API token with Object Read & Write permissions.

Run MinIO locally for development:

docker run -d --name minio \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"

S3_ENDPOINT=http://localhost:9000
S3_BUCKET=bunship
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_REGION=us-east-1

Create the bucket at http://localhost:9001.

File storage is optional. If the S3 variables are not set, file upload endpoints return a configuration error but the rest of the API works normally.

Redis Setup

Redis powers two subsystems: BullMQ background job queues and a general-purpose caching layer.

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_URL=redis://localhost:6379

For environments that require authentication:

REDIS_URL=redis://:your-password@your-host:6379

Redis is required. BunShip will fail to start if it cannot connect to Redis because the BullMQ worker initialization runs at boot.

Email Setup (Optional)

BunShip sends transactional emails (verification, password reset, team invitations) through Resend.

RESEND_API_KEY=re_xxx
EMAIL_FROM="BunShip <hello@yourdomain.com>"

Create a Resend account

Verify your sending domain

In the Resend dashboard, go to Domains, add your domain, and configure the DNS records Resend provides (SPF, DKIM, DMARC).

Update .env

Set RESEND_API_KEY and change EMAIL_FROM to use your verified domain.

During development, Resend’s test mode sends to any email address without a verified domain. If RESEND_API_KEY is not set, emails are logged to the console instead of being sent.

OAuth Providers (Optional)

Google OAuth

Go to the Google Cloud Console.
Create a project (or select an existing one).
Enable the Google+ API.
Under Credentials, create an OAuth 2.0 Client ID.
Add the authorized redirect URI: http://localhost:3000/api/v1/auth/google/callback

GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxxx

GitHub OAuth

Go to GitHub Developer Settings.
Create a new OAuth App.
Set the callback URL to: http://localhost:3000/api/v1/auth/github/callback

GITHUB_CLIENT_ID=xxxx
GITHUB_CLIENT_SECRET=xxxx

Verifying the Installation

After completing the setup, start the development server and run through these checks.

bun dev

Health check

curl http://localhost:3000/health

Expected response:

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

API documentation

Open http://localhost:3000/docs in your browser. You should see the Scalar-powered OpenAPI documentation listing all available endpoints.

Test authentication

If you ran bun run db:seed:

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

A successful response includes accessToken and refreshToken fields.

Troubleshooting

"Cannot find module" errors

Clear the workspace and reinstall:

bun run clean
bun install

Database connection failed

File-based database: Ensure TURSO_DATABASE_URL=file:../../local.db is set in your apps/api/.env file.
Turso cloud: Verify the auth token is still valid:

turso db tokens validate YOUR_TOKEN

Redis connection refused

Check that Redis is running and reachable:

redis-cli ping
# Expected: PONG

If you are using Docker, confirm the container is up:

docker ps --filter name=redis

Port 3000 already in use

Find and stop the process occupying the port:

lsof -i :3000
kill -9 <PID>

Or start BunShip on a different port:

PORT=3001 bun dev

JWT errors (token invalid / signature mismatch)

Ensure both secrets are set and at least 32 characters long:

echo $JWT_SECRET | wc -c
# Should print 33 or more (32 chars + newline)

Stripe webhook signature invalid

Make sure STRIPE_WEBHOOK_SECRET matches the secret shown by the Stripe CLI or the Stripe Dashboard. For local development, always use the Stripe CLI:

stripe listen --forward-to localhost:3000/webhooks/stripe

The CLI prints a new signing secret each time it starts. Copy it into your .env.

Complete .env Reference

Below is the full list of environment variables from .env.example:

Variable	Required	Default	Description
`NODE_ENV`	Yes	`development`	Runtime environment
`API_URL`	Yes	`http://localhost:3000`	Public API URL
`FRONTEND_URL`	Yes	`http://localhost:5173`	Public frontend URL
`DATABASE_URL`	Yes	`file:./local.db`	Turso/SQLite connection string
`DATABASE_AUTH_TOKEN`	No	—	Turso cloud auth token
`REDIS_HOST`	Yes	`localhost`	Redis hostname
`REDIS_PORT`	Yes	`6379`	Redis port
`REDIS_URL`	Yes	`redis://localhost:6379`	Redis connection URL
`JWT_SECRET`	Yes	—	Access token signing secret (32+ chars)
`JWT_REFRESH_SECRET`	Yes	—	Refresh token signing secret (32+ chars)
`STRIPE_SECRET_KEY`	No	—	Stripe API secret key
`STRIPE_WEBHOOK_SECRET`	No	—	Stripe webhook signing secret
`STRIPE_PRO_MONTHLY_PRICE_ID`	No	—	Stripe price ID for Pro monthly
`STRIPE_PRO_YEARLY_PRICE_ID`	No	—	Stripe price ID for Pro yearly
`STRIPE_ENTERPRISE_MONTHLY_PRICE_ID`	No	—	Stripe price ID for Enterprise monthly
`STRIPE_ENTERPRISE_YEARLY_PRICE_ID`	No	—	Stripe price ID for Enterprise yearly
`RESEND_API_KEY`	No	—	Resend email API key
`EMAIL_FROM`	No	—	Sender address for transactional emails
`S3_ENDPOINT`	No	—	S3-compatible storage endpoint URL
`S3_BUCKET`	No	—	Storage bucket name
`S3_ACCESS_KEY_ID`	No	—	S3 access key
`S3_SECRET_ACCESS_KEY`	No	—	S3 secret key
`S3_REGION`	No	`us-east-1`	S3 region
`GOOGLE_CLIENT_ID`	No	—	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	No	—	Google OAuth client secret
`GITHUB_CLIENT_ID`	No	—	GitHub OAuth client ID
`GITHUB_CLIENT_SECRET`	No	—	GitHub OAuth client secret
`TOTP_ISSUER`	No	`BunShip`	Name shown in authenticator apps
`DEMO_MODE`	No	`false`	Restricts destructive actions for demo environments
`CRON_SECRET`	No	—	Shared secret for cron job endpoints

Getting Started

Core Concepts

Features

Customization

Deployment

System Requirements

Install Dependencies

Environment Configuration

Application Settings

JWT Authentication

How to generate a JWT secret

Database Setup

Local Development (File-Based)

Turso Cloud

Run Migrations and Seed

Stripe Setup

S3 / R2 Storage Setup

Redis Setup

Email Setup (Optional)

OAuth Providers (Optional)

Google OAuth

GitHub OAuth

Verifying the Installation

Troubleshooting

Complete .env Reference

​System Requirements

​Install Dependencies

​Environment Configuration

​Application Settings

​JWT Authentication

​How to generate a JWT secret

​Database Setup

​Local Development (File-Based)

​Turso Cloud

​Run Migrations and Seed

​Stripe Setup

​S3 / R2 Storage Setup

​Redis Setup

​Email Setup (Optional)

​OAuth Providers (Optional)

​Google OAuth

​GitHub OAuth

​Verifying the Installation

​Troubleshooting

​Complete .env Reference

System Requirements

Install Dependencies

Environment Configuration

Application Settings

JWT Authentication

How to generate a JWT secret

Database Setup

Local Development (File-Based)

Turso Cloud

Run Migrations and Seed

Stripe Setup

S3 / R2 Storage Setup

Redis Setup

Email Setup (Optional)

OAuth Providers (Optional)

Google OAuth

GitHub OAuth

Verifying the Installation

Troubleshooting

Complete .env Reference