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.

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

This installs all Node.js dependencies listed in package.json.

Step 3 — Create Your Environment File

cp .env.example .env

Open .env in your editor. At minimum, set these four 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"

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

Step 4 — Create the Local Database

# Create the database (adjust the name if needed)
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 by applying every migration in prisma/migrations/. It also runs prisma generate automatically.

You should see output ending with Your database is now in sync with your schema.

Step 6 — Seed Demo Data (Recommended)

The seed script imports sample products, categories, blog posts, hero banners, users, and settings so you have something to look at right away.

npm run import-demo-data

This reads JSON files from seed-data/ and inserts them into your database. It is safe to run multiple times — duplicate checks are in place for most records.

Step 7 — Copy Demo Media (Optional)

If you have DigitalOcean Spaces configured, copy the demo images into your bucket:

node scripts/copy-spaces-folder.mjs

If you do not have Spaces set up yet, the demo data will still load — product images will simply show as broken until you configure media storage. See Media Storage.

Step 8 — Start the Development Server

npm run dev

The app starts at http://localhost:3000. The development server supports hot reloading — changes to source files are reflected immediately without restarting.

Step 9 — Access the Admin Panel

Navigate to http://localhost:3000/admin/dashboard. You will be redirected to sign in.

The demo seed data includes a default admin account. Check seed-data/User.json for the email and default password. Change this password immediately — both in the admin panel and in the seed file if you plan to re-seed.

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

Verify the Setup

At this point 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
Create a customer account and add items to cart

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

Building for Production (Local Test)

To test a production build locally before deploying:

npm run build
npm start

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

Troubleshooting

Prisma can't connect to the database

Check that your DATABASE_URL is correct and that PostgreSQL is running:

# macOS (Homebrew)
brew services start postgresql@16

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

Port 3000 already in use

npm run dev -- -p 3001

Remember to 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.