Quick Start

Before you begin, make sure you have access to ShipSaaS and the shipsaas repository, and that you have completed the prerequisites.

Local Development

Step 1: Clone the project

Clone the shipsaas source code:

git clone git@github.com:shipsaasnet/shipsaas my-shipsaas-project

By default, this pulls the main branch based on Next.js 16, which can be deployed to Vercel or via VPS + Dokploy.

After cloning, enter the project root. All commands below are run from the project root.

cd my-shipsaas-project

Step 2: Install dependencies

Install dependencies with:

pnpm install

Step 3: Copy environment variables to .env

Copy the local development env template:

cp .env.example .env

ShipSaaS currently reads the root .env file during local development, so do not copy it to .env.development.

Step 4: Edit .env

Update at least the following fields based on your project:

# app
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_APP_NAME="My ShipSaaS App"

# database
DATABASE_URL="postgres://postgres:postgres@localhost:5432/my_shipsaas_project"

# better auth
BETTER_AUTH_SECRET="replace-with-strong-secret-32+chars"
BETTER_AUTH_BASE_URL="http://localhost:3000"

Required:

• NEXT_PUBLIC_APP_URL: your site URL. For local development this is usually http://localhost:3000
• NEXT_PUBLIC_APP_NAME: your app name
• DATABASE_URL: your database connection string. Required if you need login, payments, or admin features
• BETTER_AUTH_SECRET: Better Auth secret. Required when enabling user login
• BETTER_AUTH_BASE_URL: the site URL used by Better Auth. For local development this should usually match NEXT_PUBLIC_APP_URL

Generate a random secret with:

openssl rand -base64 32

Step 5: Start the dev server

Start the development server:

pnpm dev

Open the Local URL in your browser, for example: http://localhost:3000.

The dev server listens on port 3000 by default. To use a different port:

pnpm dev --port 8080

The new preview URL will be: http://localhost:8080.

Configure the database

If your project needs login, payments, or admin features, follow these steps.

Step 1: Confirm the database connection string

You can create a database on Supabase, Neon, or another cloud provider and get a connection string like:

postgresql://postgres.xxx:xxxxxx@aws-0-ap-southeast-1.pooler.supabase.com:6543/postgres

Or use a self-hosted PostgreSQL database:

postgresql://user:password@127.0.0.1:5432/my_shipsaas_project

For local development, a self-hosted PostgreSQL database is recommended. For production, use Supabase/Neon or another PostgreSQL-compatible provider.

For common database setup details, see the Database docs.

Set the connection string in DATABASE_URL inside .env:

DATABASE_URL="postgresql://user:password@127.0.0.1:5432/my_shipsaas_project"

Step 2: Create a new database

If you are using local PostgreSQL and the target database does not exist yet, run:

pnpm run db:init

This command reads DATABASE_URL from .env, connects to the postgres default database on the same PostgreSQL instance, and creates the target database automatically.

Before running it, confirm:

• the database name in DATABASE_URL is already set to the name you want to create, for example my_shipsaas_project
• your PostgreSQL user has CREATE DATABASE privileges

If you are using Supabase, Neon, or another hosted database platform, the database is usually already created for you, so you can skip this step.

Step 3: Run migrations

Run migrations with:

pnpm db:generate
pnpm db:migrate

These commands read the DATABASE_URL value from .env.

Step 4: Troubleshoot database connectivity

If pnpm db:migrate times out or hangs for a long time, first verify the database connection:

psql "postgresql://user:password@address:port/database" # YOUR-DATABASE-URL

If the connection fails, check the connection string and network settings such as firewalls or proxies.

After a successful migration, you can re-run the command above to verify that the tables were created.

Step 5: Switch between local and production databases

During local development, you can keep DATABASE_URL pointed at your local database. Before deployment, switch it to the production database, run migrations, then switch it back.

In .env, you can toggle the active database with comments:

# local database
DATABASE_URL="postgresql://user:password@127.0.0.1:5432/my_shipsaas_project"
# remote database
# DATABASE_URL="postgresql://postgres.xxx:xxxxxx@aws-0-ap-southeast-1.pooler.supabase.com:6543/postgres"

Configure authentication

ShipSaaS uses Better Auth for user authentication.

If your site only uses the landing page, you can skip auth setup. For login, payments, or admin features, auth is required.

Generate an auth secret

Generate a random auth secret:

openssl rand -base64 32

Set environment variables

Set the generated secret in .env under BETTER_AUTH_SECRET, and also set BETTER_AUTH_BASE_URL:

BETTER_AUTH_SECRET="your-secret-key"
BETTER_AUTH_BASE_URL="http://localhost:3000"

With BETTER_AUTH_SECRET set, email login is enabled by default and the site will call /api/auth/get-session to check auth status. Without it, auth checks are disabled.

Customize your project

Use the steps below to customize your project.

Update project info

Files: use .env for local development, and .env.production or deployment platform variables for production Update: app name, deployment URL, and auth base URL Reference: App basics

Update app icons

Files: public/logo.png and public/favicon.ico Update: replace with your own logo and favicon Reference: App icons

Update sitemap

File: public/sitemap.xml Update: list your site's pages Reference: Sitemap

Update legal pages

Files: content/pages/privacy-policy.mdx and content/pages/terms-of-service.mdx Update: replace with your own policies Reference: Legal pages

Update common UI text

File: src/config/locale/messages/{locale}/common.json Update: common UI text Reference: Common content

Update landing page content

File: src/config/locale/messages/{locale}/landing.json Update: landing page content Reference: Landing content

Update theme styles

File: src/config/style/theme.css Update: your theme styles Reference: Theme styles

Update language settings

File: src/config/locale/index.ts