Setup & Configuration

Get the portfolio running on your local machine with this comprehensive setup guide.

📋 Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Installation
Node.js	20+	nodejs.org
pnpm	10.7.1+	`npm install -g pnpm`
Git	Latest	git-scm.com

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/thejokers69/my-portfolio.git
cd my-portfolio

2. Install Dependencies

pnpm install

This will install all required dependencies from package.json.

3. Configure Environment Variables

Create a .env.local file in the root directory:

cp .env.example .env.local

Edit .env.local with your configuration:

# GitHub Integration
NEXT_PUBLIC_GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

# Vercel (Optional for local dev)
VERCEL_TOKEN=xxxxxxxxxxxxx
VERCEL_ORG_ID=team_xxxxxxxxxxxxx
VERCEL_PROJECT_ID=prj_xxxxxxxxxxxxx

# Supabase (Optional)
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx

4. Start Development Server

pnpm dev

The application will be available at http://localhost:3000

🔑 Environment Variables

Required Variables

GitHub Token

Purpose: Fetch GitHub statistics and repository data.

How to get:

Go to GitHub Settings > Developer settings > Personal access tokens
Click "Generate new token (classic)"
Select scopes:
- public_repo - Access public repositories
- read:user - Read user profile data
Copy the token and add to .env.local

NEXT_PUBLIC_GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

Note: Prefix with NEXT_PUBLIC_ to make it available in the browser.

Optional Variables

Vercel Deployment

Purpose: Automated deployments and analytics.

VERCEL_TOKEN=xxxxxxxxxxxxx
VERCEL_ORG_ID=team_xxxxxxxxxxxxx
VERCEL_PROJECT_ID=prj_xxxxxxxxxxxxx

How to get:

Install Vercel CLI: pnpm install -g vercel
Run vercel login
Run vercel link in your project
Credentials will be in .vercel/project.json

Supabase (Backend)

Purpose: Authentication and database functionality.

NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx
SUPABASE_SERVICE_ROLE_KEY=xxx  # Server-side only

How to get:

Create account at supabase.com
Create a new project
Go to Settings > API
Copy URL and keys

⚠️ Security: Never expose SUPABASE_SERVICE_ROLE_KEY in client-side code!

PostHog Analytics

NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxxx
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

📦 Package Management

Using pnpm

This project uses pnpm for faster, more efficient package management.

Key commands:

# Install dependencies
pnpm install

# Add a package
pnpm add <package-name>

# Add dev dependency
pnpm add -D <package-name>

# Update packages
pnpm update

# Remove a package
pnpm remove <package-name>

Package.json Scripts

{
  "scripts": {
    "dev": "next dev",                    // Development server
    "build": "next build",                // Production build
    "start": "next start",                // Production server
    "lint": "eslint .",                   // Run ESLint
    "lint:fix": "eslint . --fix",         // Fix linting issues
    "test": "cypress run",                // Run E2E tests
    "test:unit": "jest",                  // Run unit tests
    "test:e2e": "cypress open --e2e",     // Open Cypress UI
    "test:coverage": "jest --coverage",   // Coverage report
    "format": "prettier --write .",       // Format code
    "validate": "pnpm lint && pnpm test:e2e:ci && pnpm build"
  }
}

🛠️ Development Commands

Development Server

# Start dev server (default port 3000)
pnpm dev

# Start on custom port
pnpm dev -- -p 3001

Building

# Create production build
pnpm build

# Build and analyze bundle
pnpm build && pnpm analyze

Testing

# Run all tests
pnpm test

# Unit tests
pnpm test:unit

# Unit tests with coverage
pnpm test:coverage

# E2E tests (headless)
pnpm test:e2e:ci

# E2E tests (interactive)
pnpm test:e2e

# Component tests
pnpm test:component

Code Quality

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Format code with Prettier
pnpm format

# Check formatting
pnpm format:check

Full Validation

# Run complete CI pipeline
pnpm validate

This runs: linting, type checking, tests, and build.

🐳 Docker Setup

Docker Compose (Recommended)

The easiest way to run the portfolio with Docker:

# Start all services
docker-compose up

# Start in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Access at http://localhost:3000

Docker Wake-Up System

Smart container management that auto-starts/stops:

# Start wake-up system
./scripts/start-wake.sh

# With local monitoring
./scripts/start-wake.sh --monitor

Features:

✅ Instant start on access
✅ Auto-stops after 30 min inactivity
✅ Auto-restarts when needed
✅ NGINX proxy for seamless transitions

Manual Docker Build

# Build image
docker build -t my-portfolio:latest .

# Run container
docker run -p 3000:3000 \
  --env-file .env.local \
  my-portfolio:latest

🔧 IDE Configuration

VS Code (Recommended)

Extensions:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-vscode.vscode-typescript-next"
  ]
}

Settings: .vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "typescript.tsdk": "node_modules/typescript/lib"
}

🧪 Testing Setup

Cypress Configuration

// cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    supportFile: 'cypress/support/e2e.ts',
    specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
  },
  component: {
    devServer: {
      framework: 'next',
      bundler: 'webpack',
    },
    supportFile: 'cypress/support/component.ts',
    specPattern: 'src/**/*.cy.{js,jsx,ts,tsx}',
  },
});

Jest Configuration

// jest.config.cjs
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
  },
  collectCoverageFrom: [
    'src/**/*.{js,jsx,ts,tsx}',
    '!src/**/*.d.ts',
    '!src/**/*.stories.tsx',
  ],
};

🔍 Troubleshooting

Common Issues

Port Already in Use

# Find process using port 3000
lsof -ti:3000

# Kill process
kill -9 $(lsof -ti:3000)

# Or use different port
pnpm dev -- -p 3001

Module Not Found

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

TypeScript Errors

# Restart TypeScript server (VS Code)
# Cmd+Shift+P > "TypeScript: Restart TS Server"

# Or rebuild
pnpm build

Environment Variables Not Working

Ensure .env.local exists
Restart dev server after changes
Use NEXT_PUBLIC_ prefix for client-side variables
Check for typos in variable names

GitHub API Rate Limiting

# Check rate limit status
curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/rate_limit

If limited:

Wait for reset (shown in response)
Use a personal access token with higher limits
Implement caching (already included)

📚 Next Steps

🆘 Getting Help

If you encounter issues:

Check the troubleshooting section
Search GitHub Issues
Create a new issue with:
- Error message
- Steps to reproduce
- Environment details (OS, Node version, etc.)

Happy coding! 🚀

On this page