Installation

This guide covers everything you need to install and configure ShipFree for development and production.

Prerequisites

Before installing ShipFree, make sure you have the following installed on your system:

Required

Bun

Version: 1.2.20 or higherBun is a fast JavaScript runtime and package manager.

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

Verify installation:

bun --version

PostgreSQL

Version: 14 or higherPostgreSQL is the database used by ShipFree.macOS:

brew install postgresql@16
brew services start postgresql@16

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib

Windows: Download from postgresql.org

Optional

Git: For cloning the repository
OpenSSL: For generating secure secrets
Docker: For containerized development (alternative to local PostgreSQL)

Step-by-step setup

Clone the repository

Start by cloning the ShipFree repository:

git clone https://github.com/revokshq/shipfree.git
cd shipfree

You can also download the ZIP file from GitHub if you prefer not to use Git.

Install dependencies

Install all required packages using Bun:

bun install

This will install all dependencies listed in package.json, including:

Next.js 16.1 framework
Better-Auth for authentication
Drizzle ORM for database operations
TailwindCSS 4 for styling
And many more packages

Bun automatically uses the exact version specified in package.json (bun@1.2.20).

Configure environment variables

Create your environment file from the example:

cp .env.example .env

Core configuration

Edit .env and set these required variables:

# Database connection
DATABASE_URL=postgres://postgres:postgres@localhost:5432/shipfree
PROD_DATABASE_URL=postgres://postgres:postgres@localhost:5432/shipfree

# App URL (change in production)
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Environment
NEXT_PUBLIC_ENV=development

# Better-Auth configuration
BETTER_AUTH_SECRET=your-secret-key-here
BETTER_AUTH_URL=http://localhost:3000

# Email provider (use 'log' for development)
EMAIL_PROVIDER=log

Generate a secure auth secret

Use OpenSSL to generate a secure random secret:

openssl rand -base64 32

Copy the output and paste it as your BETTER_AUTH_SECRET value.

Never commit your .env file to version control. The .env.example file is for reference only.

Set up PostgreSQL database

Create a new database for ShipFree:

Using psql

createdb shipfree

Using PostgreSQL CLI

psql -U postgres

Then in the PostgreSQL prompt:

CREATE DATABASE shipfree;
\q

Using Docker (alternative)

If you prefer using Docker for PostgreSQL:

docker run --name shipfree-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=shipfree \
  -p 5432:5432 \
  -d postgres:16

Verify database connection

Test your database connection:

psql postgres://postgres:postgres@localhost:5432/shipfree -c "SELECT version();"

Run database migrations

Apply the database schema using Drizzle:

bun run migrate:local

This command:

Connects to your database using DATABASE_URL
Runs all migrations from the migrations/ folder
Creates all required tables (users, sessions, accounts, etc.)

The migration script is located at scripts/migrate.ts and uses Drizzle’s migration runner.

Available migration commands

bun run migrate:local

Start development server

Launch the Next.js development server:

bun dev

The application will start at http://localhost:3000You should see output similar to:

▲ Next.js 16.1.1
- Local:        http://localhost:3000
- Ready in 1.2s

The dev server includes hot module replacement (HMR) for instant updates as you code.

Environment configuration details

Here’s a comprehensive overview of all environment variables:

Database

# Local development database
DATABASE_URL=postgres://postgres:postgres@localhost:5432/shipfree

# Production database (used by migrate:prod command)
PROD_DATABASE_URL=postgres://user:password@host:5432/database

Application

# Public URL of your application
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Environment indicator
NEXT_PUBLIC_ENV=development

Authentication

# Secret for encrypting sessions (required)
BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32

# Base URL for auth callbacks (required)
BETTER_AUTH_URL=http://localhost:3000

OAuth providers (optional)

Google OAuth

Get credentials from Google Cloud Console

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

GitHub OAuth

Get credentials from GitHub Developer Settings

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Microsoft OAuth

Get credentials from Azure Portal

MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_TENANT_ID=common

Facebook OAuth

Get credentials from Facebook Developers

FACEBOOK_CLIENT_ID=your-facebook-client-id
FACEBOOK_CLIENT_SECRET=your-facebook-client-secret

Email providers (optional)

# Choose: resend, postmark, plunk, nodemailer, or log
EMAIL_PROVIDER=log

# Resend (recommended for production)
RESEND_API_KEY=re_123456789
RESEND_DOMAIN=mail.yourdomain.com

# Postmark
POSTMARK_API_TOKEN=your-postmark-token

# Plunk
PLUNK_API_KEY=your-plunk-api-key

# Nodemailer (SMTP)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
SMTP_SECURE=false

# Email defaults
DEFAULT_FROM_EMAIL=noreply@yourdomain.com
DEFAULT_FROM_NAME=Your App Name

Payment providers (optional)

Stripe

Get credentials from Stripe Dashboard

PAYMENT_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID=price_...

# Public price IDs
NEXT_PUBLIC_STRIPE_PRICE_STARTER_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_STARTER_YEARLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_PRO_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_PRO_YEARLY=price_...

Polar

Get credentials from Polar Settings

PAYMENT_PROVIDER=polar
POLAR_ACCESS_TOKEN=your-polar-access-token
POLAR_WEBHOOK_SECRET=your-webhook-secret
POLAR_ORGANIZATION_ID=your-org-id
POLAR_PRODUCT_ID=your-product-id
POLAR_ENVIRONMENT=production

Lemon Squeezy

Get credentials from Lemon Squeezy Settings

PAYMENT_PROVIDER=lemonsqueezy
LEMONSQUEEZY_API_KEY=your-api-key
LEMONSQUEEZY_STORE_ID=your-store-id
LEMONSQUEEZY_WEBHOOK_SECRET=your-webhook-secret

Cloudflare R2 storage (optional)

CLOUDFLARE_ACCOUNT_ID=your-account-id
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key
R2_BUCKET_URL=https://your-bucket.r2.dev
R2_STORAGE_BASE_URL=https://your-storage-domain.com
R2_PUBLIC_BUCKET=your-public-bucket-name
R2_PRIVATE_BUCKET=your-private-bucket-name

Sentry monitoring (optional)

SENTRY_AUTH_TOKEN=your_sentry_auth_token
NEXT_PUBLIC_SENTRY_DSN=your_sentry_dsn

Troubleshooting

Bun installation issues

Problem: bun: command not foundSolution:

Install Bun using the official installer:

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

Restart your terminal
Verify with bun --version

Problem: Wrong Bun versionSolution:

bun upgrade

PostgreSQL connection errors

Problem: Connection refused or ECONNREFUSEDSolution:

Check if PostgreSQL is running:

# macOS
brew services list

# Linux
sudo systemctl status postgresql

Start PostgreSQL if it’s not running:

# macOS
brew services start postgresql@16

# Linux
sudo systemctl start postgresql

Verify your DATABASE_URL credentials

Problem: database "shipfree" does not existSolution:

createdb shipfree

Migration errors

Problem: Migration fails with table already existsSolution: For a fresh start, drop and recreate the database:

dropdb shipfree
createdb shipfree
bun run migrate:local

Problem: Permission denied errorsSolution: Ensure your PostgreSQL user has proper permissions:

GRANT ALL PRIVILEGES ON DATABASE shipfree TO postgres;

Port conflicts

Problem: Port 3000 is already in useSolution: Use a different port:

PORT=3001 bun dev

Or kill the process using port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Environment variable issues

Problem: Environment variables not loadingSolution:

Ensure .env file exists in the root directory
Restart the development server after changing .env
Check that variables are properly formatted (no spaces around =)
For client-side variables, ensure they start with NEXT_PUBLIC_

Problem: BETTER_AUTH_SECRET validation errorSolution: Generate a new secret:

openssl rand -base64 32

TypeScript errors

Problem: Type errors in the editorSolution:

Restart your TypeScript server in VS Code (Cmd+Shift+P > “Restart TS Server”)
Run type check:
```
bun run typecheck
```
Ensure you have the latest dependencies:
```
bun install
```

Next steps

Now that ShipFree is installed, you can:

Configure authentication

Set up OAuth providers and customize the auth flow

Set up payments

Configure your payment provider and pricing plans

Customize branding

Update your app’s colors, logo, and brand identity

Deploy to production

Learn how to deploy your application

Join the ShipFree community for support, updates, and to share what you’re building!

Getting Started

Core Features

Payment Providers

Email Providers

Configuration

Deployment

Installation

Installation

Prerequisites

Required

Bun

PostgreSQL

Optional

Step-by-step setup

Core configuration

Generate a secure auth secret

Using psql

Using PostgreSQL CLI

Using Docker (alternative)

Verify database connection

Available migration commands

Environment configuration details

Database

Application

Authentication

OAuth providers (optional)

Email providers (optional)

Payment providers (optional)

Cloudflare R2 storage (optional)

Sentry monitoring (optional)

Troubleshooting

Next steps

Configure authentication

Set up payments

Customize branding

Deploy to production

Build docs developers (and LLMs) love

Getting Started

Core Features

Payment Providers

Email Providers

Configuration

Deployment

Documentation Index

​Installation

​Prerequisites

​Required

Bun

PostgreSQL

​Optional

​Step-by-step setup

​Core configuration

​Generate a secure auth secret

​Using psql

​Using PostgreSQL CLI

​Using Docker (alternative)

​Verify database connection

​Available migration commands

​Environment configuration details

​Database

​Application

​Authentication

​OAuth providers (optional)

​Email providers (optional)

​Payment providers (optional)

​Cloudflare R2 storage (optional)

​Sentry monitoring (optional)

​Troubleshooting

​Next steps

Configure authentication

Set up payments

Customize branding

Deploy to production

Build docs developers (and LLMs) love

Installation

Prerequisites

Required

Optional

Step-by-step setup

Core configuration

Generate a secure auth secret

Using psql

Using PostgreSQL CLI

Using Docker (alternative)

Verify database connection

Available migration commands

Environment configuration details

Database

Application

Authentication

OAuth providers (optional)

Email providers (optional)

Payment providers (optional)

Cloudflare R2 storage (optional)

Sentry monitoring (optional)

Troubleshooting

Next steps