Skip to main content

​
Quickstart Guide

Get your Openfront e-commerce store up and running in under 5 minutes. This guide will walk you through the fastest path to a working instance.
This quickstart focuses on getting you up and running quickly. For detailed configuration options, see the Installation Guide.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 20+ installed on your machine
  • PostgreSQL database (local or hosted)
  • A terminal and text editor
1
Clone the Repository
2
Start by cloning the Openfront repository and installing dependencies:
3
git clone https://github.com/openshiporg/openfront.git
cd openfront
npm install
4
You can also use yarn, pnpm, or bun as your package manager.
5
Set Up Environment Variables
6
Create your environment configuration file:
7
cp .env.example .env
8
Open .env in your text editor and configure the required variables:
9
# Required - Database Connection
DATABASE_URL="postgresql://username:password@localhost:5432/openfront"

# Required - Session Security (min 32 characters)
SESSION_SECRET="your-very-long-session-secret-key-minimum-32-characters"
10
Important: Replace username, password, and localhost:5432 with your actual PostgreSQL credentials. The SESSION_SECRET must be at least 32 characters long.
11
Start the Development Server
12
Run the development server to build the schema, run migrations, and start Next.js:
13
npm run dev
14
This command will:
15
  • Build the KeystoneJS schema
  • Run database migrations
  • Start the Next.js development server with Turbopack
    • 16
    You should see output indicating the server is running:
    17
    ✓ Ready on http://localhost:3000
    18
    Create Your Admin Account
    19
    Open your browser and navigate to the admin initialization page:
    20
    http://localhost:3000/dashboard/init
    21
    You’ll be prompted to create your first admin user. Fill in:
    22
  • Name: Your full name
  • Email: Your email address
  • Password: A secure password
    • 23
    This first user is automatically created with full admin permissions, including access to all features and settings.
    24
    Complete Store Onboarding
    25
    After creating your admin account, you’ll be redirected to the onboarding flow. This will help you:
    26
  • Set up your store details (name, currency, region)
  • Configure payment providers (optional)
  • Import sample data to explore features
  • Set up shipping options
    • 27
    We recommend completing the onboarding with sample data. This gives you a fully functional demo store to explore before adding your own products.
    28
    Access Your Store
    29
    You now have three main endpoints available:
    30

    Storefront

    http://localhost:3000Customer-facing store where shoppers browse and purchase

    Admin Dashboard

    http://localhost:3000/dashboardManagement interface for orders, products, and settings

    GraphQL API

    http://localhost:3000/api/graphqlInteractive API explorer and documentation

    ​
    What’s Next?

    Now that you have a working Openfront instance, here’s what you can do:

    ​
    Explore the Admin Dashboard

    Log in to /dashboard and explore:
    • Analytics: View real-time store performance
    • Orders: Process and fulfill customer orders
    • Products: Add and manage your product catalog
    • Customers: View and manage customer accounts
    • Settings: Configure regions, payments, and shipping

    ​
    Customize Your Storefront

    The storefront is fully customizable:
    • Modify components in features/storefront/
    • Update styling with Tailwind CSS
    • Add custom pages in app/(storefront)/

    ​
    Add Your Products

    Create your first product through the dashboard:
    1. Navigate to Products → New Product
    2. Add product details (title, description, price)
    3. Upload product images
    4. Configure variants (sizes, colors, etc.)
    5. Set inventory levels
    6. Publish when ready

    ​
    Configure Payment Processing

    Set up payment providers to accept real payments:
    Add Stripe credentials to your .env file:
    STRIPE_SECRET_KEY="sk_test_51..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_KEY="pk_test_51..."
    Then enable Stripe in Settings → Payment Providers

    ​
    Set Up Shipping

    Configure shipping providers for automated rate calculation and label generation: 
    SHIPPO_API_KEY="shippo_test_..."

    ​
    Quick Deploy Options

    Want to deploy to production? Use one of these one-click deploy options:

    Deploy to Vercel

    One-click deployment to Vercel with automatic PostgreSQL setup

    Deploy to Railway

    Deploy to Railway with managed database included

    ​
    Development Commands

    Here are the essential commands you’ll use during development: 
    # Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Generate and apply new migrations
npm run migrate:gen

# Deploy existing migrations
npm run migrate

# Run linter
npm run lint

    ​
    Common Issues

    Make sure your PostgreSQL server is running and the DATABASE_URL in your .env file is correct.Test your connection:
    psql postgresql://username:password@localhost:5432/openfront
    The SESSION_SECRET must be at least 32 characters long. Generate a secure secret:
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
    Another application is using port 3000. Either stop that application or specify a different port:
    PORT=3001 npm run dev
    If you encounter migration errors, you can reset your database:
    # WARNING: This will delete all data
npx prisma migrate reset

    ​
    Learn More

    Now that you have a working store, dive deeper into specific topics:

    Installation Guide

    Detailed setup for all deployment scenarios

    Environment Variables

    Complete reference of all configuration options

    API Reference

    Explore the GraphQL API and data models

    Platform Documentation

    Deep dive into Openfront’s architecture
    Need help? Join our community on GitHub Discussions or check out the live demo to see Openfront in action.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us