Local Development

This guide walks you through setting up a fully working Open Sky Commerce instance on your local machine — from extracting the code to browsing the storefront and logging into the admin panel.

Option A — Bootstrap Script (Recommended)

The included script automates the entire local setup process. From the project root, run:

bash scripts/bootstrap-local.sh

The script will:

Check for required tools (Node.js, npm, PostgreSQL) and prompt to install any that are missing
Create a .env file from .env.example
Generate NEXTAUTH_SECRET and APP_ENCRYPTION_KEY automatically
Create a local PostgreSQL database and verify the connection
Run prisma generate and prisma migrate deploy
Optionally import the demo seed data

After the script completes, open .env and fill in any optional services you want to enable (SendGrid, DigitalOcean Spaces, etc.), then start the dev server:

npm run dev

The app will be available at http://localhost:3000. Navigate to /admin/dashboard and sign in with the credentials from seed-data/User.json. Change the default password immediately.

Option B — Manual Setup

Follow these steps if you prefer full control over each part of the setup, or if the bootstrap script can't run in your environment.

Prerequisites

Before you begin, make sure you have the following installed:

Node.js 18 or later — nodejs.org
npm (included with Node.js), or yarn / pnpm if you prefer
PostgreSQL 14 or later — postgresql.org or via Homebrew on macOS: brew install postgresql@16
Git — for managing your own version of the code after setup

Step 1 — Extract the Code

If you have not already done so, download and extract the archive as described in Getting the Code.

unzip open-sky-commerce-vX.X.X.zip
cd open-sky-commerce

Step 2 — Install Dependencies

npm install

Step 3 — Create Your Environment File

cp .env.example .env

Open .env in your editor. At minimum, set these values to get the app running locally:

DATABASE_URL="postgresql://postgres:password@localhost:5432/openskycommerce"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="any-random-string-at-least-32-chars"
NEXT_PUBLIC_SITE_URL="http://localhost:3000"
APP_ENCRYPTION_KEY="64-char-hex-string"  # generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ADMIN_EMAILS="[email protected]"  # comma-separated list of emails that get ADMIN role on sign-up

For a complete reference of every variable, see Environment Variables. You can add optional service keys (SendGrid, DigitalOcean Spaces, etc.) later — the app will start without them.

Step 4 — Create the Local Database

createdb openskycommerce

If createdb is not in your path, ensure the PostgreSQL bin directory is on your PATH, or use pgAdmin to create it graphically.

Step 5 — Run Database Migrations

npx prisma migrate dev --name init

This creates all tables in your local database. You should see output ending with Your database is now in sync with your schema.

Step 6 — Seed Demo Data (Recommended)

npm run import-demo-data

Imports sample products, categories, blog posts, hero banners, users, and settings. Safe to run multiple times.

Step 7 — Start the Development Server

npm run dev

The app starts at http://localhost:3000. Changes to source files are reflected immediately.

Step 8 — Access the Admin Panel

Navigate to /admin/dashboard. The demo seed data includes a default admin account — check seed-data/User.json for the credentials. Change the password immediately after first login.

See Admin Overview for a tour of all available admin sections.

Verify the Setup

After setup (either path) you should be able to:

Browse the storefront at http://localhost:3000
View products, categories, and blog posts populated from demo data
Log into the admin panel at /admin/dashboard
See the Setup Assistant dialog on the dashboard — it will highlight any remaining configuration (payment processor, shipping settings, business info, etc.)

Checkout will not process payments until you configure a payment processor. See Payment Processors and Testing Payments.

Building for Production (Local Test)

npm run build
npm start

npm run build runs prisma generate, builds the Next.js app, then generates the sitemap. If the build succeeds locally it will succeed on your deployment platform.

Troubleshooting

Prisma can't connect to the database

# macOS (Homebrew)
brew services start postgresql@16

# Verify connection
psql "postgresql://postgres:password@localhost:5432/openskycommerce" -c "SELECT 1"

Port 3000 already in use

npm run dev -- -p 3001

Update NEXTAUTH_URL and NEXT_PUBLIC_SITE_URL in .env to match.

Prisma client is out of date

Run npx prisma generate any time you change prisma/schema.prisma.