Quickstart

Get ShipFree up and running in under 5 minutes with this quick start guide.

Quickstart

Get your ShipFree application running locally in just a few steps. This guide will take you from zero to a working application.

This quickstart assumes you have Bun and PostgreSQL already installed. If not, check out the Installation guide for detailed setup instructions.

1. Clone the repository

   Clone the ShipFree repository to your local machine:

   git clone https://github.com/revokshq/shipfree.git
   cd shipfree
   
2. Install dependencies

   ShipFree uses Bun as its package manager. Install all dependencies with:

   bun install
   

   Bun is significantly faster than npm or yarn. If you don’t have it installed yet, visit bun.sh for installation instructions.

3. Set up environment variables

   Copy the example environment file and configure your settings:

   cp .env.example .env
   

   Open .env and configure the required variables:

   # Database connection
   DATABASE_URL=postgres://postgres:postgres@localhost:5432/shipfree
   
   # App URL
   NEXT_PUBLIC_APP_URL=http://localhost:3000
   
   # Better-Auth secret (generate with: openssl rand -base64 32)
   BETTER_AUTH_SECRET=your-secret-key-here
   BETTER_AUTH_URL=http://localhost:3000
   
   # Email provider (set to 'log' for development)
   EMAIL_PROVIDER=log
   
   # Environment
   NEXT_PUBLIC_ENV=development
   

   Make sure to generate a secure BETTER_AUTH_SECRET using openssl rand -base64 32. Never use the example value in production.

4. Set up the database

   Create a PostgreSQL database for your application:

   # Using psql
   createdb shipfree
   
   # Or using PostgreSQL CLI
   psql -U postgres -c "CREATE DATABASE shipfree;"
   

   Make sure your DATABASE_URL in .env matches your database credentials.

5. Run database migrations

   Apply the database schema using Drizzle migrations:

   bun run migrate:local
   

   This command runs the migration script at scripts/migrate.ts and sets up all required tables.

6. Start the development server

   Launch the Next.js development server:

   bun dev
   

   Your application will be available at http://localhost:3000

   The development server supports hot reloading, so changes you make will be reflected instantly.

Verify your setup

Once the development server is running, you should be able to:

1. Visit the homepage at http://localhost:3000
2. Navigate to the sign-up page
3. Create a test account
4. Access the dashboard

With EMAIL_PROVIDER=log, authentication emails will be printed to your console instead of being sent. This is perfect for development.

Available commands

Here are the key commands you’ll use during development:

Development

bun dev

Next steps

Now that your application is running, here’s what to do next:

Configure authentication

Set up OAuth providers like Google, GitHub, and Microsoft

Set up payments

Configure Stripe, Polar, or other payment providers

Configure emails

Set up Resend, Postmark, or your preferred email service

Customize branding

Update colors, logo, and brand settings

Add translations

Add support for additional languages

Deploy your app

Deploy to Vercel, Railway, or your preferred platform

Common issues

Database connection error

If you see a database connection error, verify that:

• PostgreSQL is running
• Your DATABASE_URL is correct
• The database exists (createdb shipfree)
• Your PostgreSQL user has the correct permissions

Bun command not found

Make sure Bun is installed and in your PATH:

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

Then restart your terminal.

Port 3000 already in use

If port 3000 is already in use, you can specify a different port:

PORT=3001 bun dev

Migration errors

If migrations fail, try:

1. Checking your database connection
2. Ensuring the database is empty for a fresh install
3. Running bun run generate-migration to regenerate migrations

For more detailed troubleshooting, see the Installation guide or join our community for support.