Installation

This guide walks you through setting up Portfolio CMS on your local machine.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Portfolio CMS requires Node.js version 18.20.2+ or 20.9.0+.

# Check your Node.js version
node --version

If you need to install or update Node.js, we recommend using nvm:

# Install Node.js 20 (recommended)
nvm install 20
nvm use 20

Package Manager

We recommend pnpm for its speed and disk efficiency:

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version

TIP

pnpm version 9 or 10 is required. npm and yarn also work but pnpm is preferred.

Database

Portfolio CMS uses PostgreSQL as its database. You have several options:

Option 1: Local PostgreSQL

# macOS (Homebrew)
brew install postgresql@15
brew services start postgresql@15

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

Option 2: Docker

docker run --name portfolio-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=portfoliocms \
  -p 5432:5432 \
  -d postgres:15

Option 3: Cloud Database

• Neon (recommended, free tier available)
• Supabase
• Railway
• Vercel Postgres

Step-by-Step Installation

1. Extract the Downloaded Files

Unzip the downloaded zip file and open the extracted folder in your terminal:

cd portfoliocms

2. Install Dependencies

pnpm install

This will install all required packages including:

• Next.js 15
• Payload CMS 3
• TailwindCSS 4
• All UI components and utilities

3. Set Up Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env with your configuration:

# Database Connection
# For local PostgreSQL:
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/portfoliocms

# For Neon/Supabase/Cloud:
# DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require

# Payload CMS Secret (generate a random 32+ character string)
# You can use: openssl rand -base64 32
PAYLOAD_SECRET=your-super-secret-key-change-this-in-production

# Site URL (used for sitemap, OG images, CORS)
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# S3 Storage (for media uploads)
# You can use Cloudflare R2, AWS S3, or any S3-compatible storage
S3_BUCKET=your-bucket-name
S3_ACCOUNT_ID=your-account-id
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET=your-secret-key

# Email (optional, for contact form)
RESEND_API_KEY=your-resend-api-key
RESEND_FROM_EMAIL=your-from-email
RESEND_FROM_NAME=your-from-name

Important

Never commit your .env file to version control. The .gitignore file already excludes it.

4. Generate Types and Import Map

# Generate TypeScript types from your Payload schema
pnpm generate:types

# Generate the component import map
pnpm generate:importmap

5. Run Database Migrations

If you're setting up a fresh database:

pnpm payload migrate

6. Start the Development Server

pnpm dev

Your portfolio is now running at:

• Frontend: http://localhost:3000
• Admin Panel: http://localhost:3000/admin

First Login

When you first access the admin panel, you'll need to create an admin user:

1. Go to http://localhost:3000/admin
2. Enter your name, email and password
3. You're now logged in and can start adding content!

Troubleshooting Installation

Port Already in Use

If port 3000 is already in use:

# Find the process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or start on a different port
PORT=3001 pnpm dev

Database Connection Failed

# Check if PostgreSQL is running
pg_isready -h localhost -p 5432

# Check your connection string
psql "postgresql://postgres:postgres@localhost:5432/portfoliocms"

Permission Errors

# Fix node_modules permissions
sudo chown -R $(whoami) node_modules

# Clear cache and reinstall
rm -rf node_modules .next
pnpm install

Type Generation Errors

# Make sure Payload can connect to the database
pnpm payload --help

# If issues persist, try clearing the cache
rm -rf .next
pnpm generate:types

Available Scripts

Script	Description
pnpm dev	Start development server
pnpm build	Build for production
pnpm start	Start production server
pnpm generate:types	Generate TypeScript types
pnpm generate:importmap	Generate component import map
pnpm payload migrate	Run database migrations
pnpm lint	Run ESLint
pnpm format	Format code with Prettier
pnpm typecheck	Run TypeScript type checking
pnpm test	Run all tests