Installation Guide
This comprehensive guide covers all the ways you can install and deploy Openfront, from local development to production environments.System Requirements
Before you begin, ensure your system meets these requirements:- Node.js: Version 20.0.0 or higher
- PostgreSQL: Version 12 or higher
- npm/yarn/pnpm/bun: Latest version of your preferred package manager
- Storage: At least 1GB free disk space
- Memory: Minimum 2GB RAM (4GB recommended)
Openfront uses Next.js 16 with the App Router and requires Node.js 20+. Make sure to update your Node.js installation if you’re using an older version.
Local Development Setup
This is the recommended setup for development and testing. macOS
Ubuntu/Debian
Windows
Download and install from postgresql.orgOr use WSL2 with the Ubuntu instructions.
Docker
Run PostgreSQL in a container:
# Connect to PostgreSQL
psql -U postgres
# Create database
CREATE DATABASE openfront;
# Create user (optional)
CREATE USER openfront_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE openfront TO openfront_user;
# Exit psql
\q
# Database Connection
DATABASE_URL="postgresql://openfront_user:your_password@localhost:5432/openfront"
# Session Secret (generate with: openssl rand -base64 32)
SESSION_SECRET="your-secure-random-string-at-least-32-characters-long"
# Optional: Shadow database for migrations
SHADOW_DATABASE_URL="postgresql://openfront_user:your_password@localhost:5432/openfront_shadow"
Security: Never commit your
.env file to version control. Always use strong, randomly generated values for SESSION_SECRET.Navigate to http://localhost:3000/dashboard/init to create your first admin user.
Deploy to Vercel
Vercel provides the easiest path to production deployment with automatic PostgreSQL setup.Deploy to Railway
Railway provides a complete deployment platform with managed PostgreSQL included.
DATABASE_URL environment variableDocker Deployment
Deploy Openfront using Docker and Docker Compose.version: '3.8'
services:
postgres:
image: postgres:15
environment:
POSTGRES_DB: openfront
POSTGRES_USER: openfront
POSTGRES_PASSWORD: your_secure_password
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U openfront"]
interval: 10s
timeout: 5s
retries: 5
openfront:
build: .
environment:
DATABASE_URL: postgresql://openfront:your_secure_password@postgres:5432/openfront
SESSION_SECRET: your-secure-random-string-at-least-32-characters
NODE_ENV: production
ports:
- "3000:3000"
depends_on:
postgres:
condition: service_healthy
command: sh -c "npm run migrate && npm start"
volumes:
postgres_data:
FROM node:20-alpine AS base
# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package*.json ./
RUN npm ci
# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
# Production image
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
ENV PORT 3000
CMD ["node", "server.js"]
Access your store at http://localhost:3000
Self-Hosted Production
Deploy to your own server or VPS.# Update system
sudo apt update && sudo apt upgrade -y
# Install Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Install PostgreSQL
sudo apt install -y postgresql postgresql-contrib
# Install PM2 for process management
sudo npm install -g pm2
DATABASE_URL="postgresql://openfront:password@localhost:5432/openfront"
SESSION_SECRET="your-production-secret-at-least-32-characters"
NODE_ENV="production"
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
sudo ln -s /etc/nginx/sites-available/openfront /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
Environment Configuration
After installation, configure your environment variables. See the Environment Variables guide for a complete reference.Required Variables
Optional Integrations
Payment Providers
Configure Stripe or PayPal for payment processing
Shipping Providers
Set up Shippo or ShipEngine for shipping
File Storage
Configure S3-compatible storage
Email Service
Set up SMTP for transactional emails
Post-Installation
After installation, complete these steps:Troubleshooting
Build fails with migration errors
Build fails with migration errors
If you encounter migration errors during build:
Port already in use
Port already in use
Change the port in your environment:
Database connection timeout
Database connection timeout
Check your database is running and connection string is correct:
Build runs out of memory
Build runs out of memory
Increase Node.js memory limit:
Image uploads not working
Image uploads not working
Configure S3-compatible storage in your environment variables. See Environment Variables for S3 configuration.
Next Steps
Configure Environment
Set up payment providers, shipping, and integrations
API Reference
Explore the GraphQL API
Customize Storefront
Tailor the look and feel of your store
Platform Docs
Deep dive into Openfront’s architecture