Quick Start

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

Local Development

Initialize the project

Clone the shipsaas-life source code:

git clone git@github.com:shipsaasnet/shipsaas-life 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

Install dependencies

Install dependencies with:

pnpm install

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.

Preview the project

Open the preview URL. The first screen should look like this:

If you want to use AI to bootstrap the project faster, see "Use Agent Skills to initialize the project".

Configure environment variables

Create a config file

Copy the example env file for local development:

cp .env.example .env.development

Edit environment variables

Update the values based on your project:

# app
NEXT_PUBLIC_APP_URL = "http://localhost:3000"
NEXT_PUBLIC_APP_NAME = "shipsaas.net"

# database
DATABASE_URL = ""

# auth secret
# openssl rand -base64 32
AUTH_SECRET = ""

Required:

• NEXT_PUBLIC_APP_URL: your site URL. Use the local preview URL.
• NEXT_PUBLIC_APP_NAME: your app name.

Optional:

• DATABASE_URL: database connection string. Required for auth/admin features.
• AUTH_SECRET: auth secret. Required if you enable user login.

Generate a random secret with:

openssl rand -base64 32

Configure the database

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

Create a database

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 environment variables

Set the database URL in DATABASE_URL:

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

Run migrations

Run migrations with:

pnpm db:generate
pnpm db:migrate

These commands read the DATABASE_URL from .env.development.

If pnpm db:migrate times out, verify the database connection:

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

If the connection fails, check your database address and network settings (firewalls, proxies, etc.).

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

For local development, you can keep DATABASE_URL pointing to a local database. Before deploying, switch it to the production database, run migrations, then switch back. In .env.development, you can toggle 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 secret in .env.development:

AUTH_SECRET = "your-secret-key"

With 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: .env.development and .env.production Update: app name and deployment 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