Configuration Reference

Complete reference for environment variables, configuration files, and secrets used in Portfolio OS

Overview

Complete reference for environment variables, configuration files, and secrets used in Portfolio OS

This document provides a comprehensive reference for all configuration options in Portfolio OS, including environment variables, configuration files, and secrets management.

Configuration Overview

Portfolio OS uses a layered configuration approach:

  1. Environment Variables - Runtime configuration for apps and services
  2. Configuration Files - JSON/JS files for system behavior
  3. GitHub Secrets - Sensitive data for CI/CD pipelines
  4. Turbo Configuration - Monorepo build and cache settings

Environment Variables

File Locations

FilePurposeUsed By
.env.local (root)Monorepo-wide variablesBuild tools, scripts
apps/site/.env.localSite-specific variablesMain portfolio site
apps/dashboard/.env.localDashboard-specific variablesAdmin dashboard
env.template (root)Environment templateDevelopment reference

Note:

Never commit .env.local files! They contain sensitive credentials and are automatically ignored by .gitignore.

Quick Setup

# Copy environment templates (if they exist)
cp env.template .env.local
cp apps/site/env.template apps/site/.env.local
cp apps/dashboard/env.template apps/dashboard/.env.local

# Edit files with your actual values
# Restart dev servers after changes
pnpm dev

Site App Environment Variables

Configuration for apps/site/.env.local

Required Variables

Hashnode Integration

# Hashnode GraphQL API endpoint
NEXT_PUBLIC_HASHNODE_GQL_ENDPOINT=https://gql.hashnode.com/

# Your Hashnode publication hostname
NEXT_PUBLIC_HASHNODE_PUBLICATION_HOST=yourusername.hashnode.dev

Where to find:

  • Publication host: Your Hashnode publication URL
  • GQL endpoint: Standard Hashnode GraphQL endpoint

Used for:

  • Fetching blog posts from Hashnode
  • Displaying blog content on portfolio site

Database Configuration

# PostgreSQL database connection string
DATABASE_URL="postgresql://user:password@host:port/database"

# Direct database URL (for migrations)
DIRECT_URL="postgresql://user:password@host:port/database"

Format:

postgresql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]?schema=public

Where to find:

  • Local: Your PostgreSQL server credentials
  • Production: Vercel Postgres or similar service

Used for:

  • Prisma ORM database connections
  • User authentication data
  • Dashboard content storage

Authentication

# NextAuth secret for session encryption
NEXTAUTH_SECRET=your-32-character-random-string

# NextAuth URL (base URL of your site)
NEXTAUTH_URL=http://localhost:3000

How to generate secret:

openssl rand -base64 32

Production value:

NEXTAUTH_URL=https://yourdomain.com

Used for:

  • Session management
  • JWT token encryption
  • OAuth callback URLs

Optional - AI Features

OpenAI Integration

# OpenAI API key for chatbot
OPENAI_API_KEY=sk-your-openai-api-key-here

# Model configuration (optional)
OPENAI_ROUTER_MODEL_SMALL=gpt-4o-mini
OPENAI_ROUTER_MODEL_RESPONSES=gpt-4o-mini

Where to find:

Used for:

  • AI chatbot responses
  • Content generation features

Cost warning: OpenAI API usage incurs charges. Monitor usage in OpenAI dashboard.

Optional - Google Services

Google Calendar Integration

# Google Calendar ID for scheduling
GOOGLE_CALENDAR_ID=your-email@gmail.com

# Google Service Account credentials
GOOGLE_TYPE=service_account
GOOGLE_PROJECT_ID=your-project-id
GOOGLE_PRIVATE_KEY_ID=your-private-key-id
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
GOOGLE_CLIENT_EMAIL=your-service-account@your-project.iam.gserviceaccount.com
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_AUTH_URI=https://accounts.google.com/o/oauth2/auth
GOOGLE_TOKEN_URI=https://oauth2.googleapis.com/token
GOOGLE_AUTH_PROVIDER_X509_CERT_URL=https://www.googleapis.com/oauth2/v1/certs
GOOGLE_CLIENT_X509_CERT_URL=https://www.googleapis.com/robot/v1/metadata/x509/your-service-account
GOOGLE_UNIVERSE_DOMAIN=googleapis.com

How to set up:

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable Google Calendar API
  4. Create Service Account
  5. Download JSON credentials
  6. Share your calendar with service account email

Important notes:

  • GOOGLE_PRIVATE_KEY must use \n for newlines (not literal newlines)
  • Service account needs calendar access
  • Calendar ID is typically your email address

Used for:

  • Booking appointments through chatbot
  • Scheduling meetings
  • Calendar availability checks

Google OAuth (Alternative to Service Account)

# Google OAuth credentials
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/google/oauth/callback

How to set up:

  1. Go to Google Cloud Console
  2. Navigate to Credentials
  3. Create OAuth 2.0 Client ID
  4. Add authorized redirect URIs

Used for:

  • User authentication via Google
  • Alternative to NextAuth providers

Feature Flags (Public)

# Enable/disable features on the frontend
NEXT_PUBLIC_FEATURE_SCHEDULING=true
NEXT_PUBLIC_FEATURE_CASE_STUDY=true
NEXT_PUBLIC_FEATURE_CLIENT_INTAKE=true
NEXT_PUBLIC_FEATURE_CHATBOT=true

Note: Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

Used for:

  • Toggling features in production
  • A/B testing
  • Gradual feature rollouts

Feature Flags (Server-side)

# Enable/disable features on the backend
FEATURE_SCHEDULING=true
FEATURE_EMAIL_NOTIFICATIONS=true
FEATURE_ANALYTICS=true

Used for:

  • Server-side feature toggles
  • API endpoint enabling/disabling
  • Background job configuration

Email Configuration

# Resend API key for transactional emails
RESEND_API_KEY=re_your_resend_api_key

# Email sender configuration
EMAIL_FROM=noreply@yourdomain.com
EMAIL_FROM_NAME=Your Name

Where to find:

  • Create account at Resend
  • Generate API key in dashboard
  • Verify domain for sending

Used for:

  • Contact form submissions
  • Transactional emails
  • Notification emails

Analytics & Monitoring

# Vercel Analytics
NEXT_PUBLIC_VERCEL_ANALYTICS_ID=your-analytics-id

# Optional: Custom analytics
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

Used for:

  • Page view tracking
  • Performance monitoring
  • User behavior analytics

Dashboard App Environment Variables

Configuration for apps/dashboard/.env.local

Required Variables

# Database (same as site)
DATABASE_URL="postgresql://user:password@host:port/database"
DIRECT_URL="postgresql://user:password@host:port/database"

# Authentication (same as site)
NEXTAUTH_SECRET=your-32-character-random-string
NEXTAUTH_URL=http://localhost:3001

# Hashnode Integration
NEXT_PUBLIC_HASHNODE_GQL_ENDPOINT=https://gql.hashnode.com/
NEXT_PUBLIC_HASHNODE_PUBLICATION_HOST=yourusername.hashnode.dev

Admin Configuration

# Admin user email (for initial setup)
ADMIN_EMAIL=admin@yourdomain.com

# Dashboard-specific settings
DASHBOARD_PORT=3001

Root-Level Environment Variables

Configuration for .env.local in repository root

Build & Development

# Node environment
NODE_ENV=development  # or production

# Turbo cache configuration (optional)
TURBO_TOKEN=your-vercel-turbo-token
TURBO_TEAM=your-team-name

Turbo tokens:

Automation & Scripts

# GitHub Personal Access Token
GITHUB_TOKEN=ghp_your-github-personal-access-token

# GitHub Configuration
GITHUB_OWNER=your-github-username
GITHUB_REPO=portfolio-os
GITHUB_PROJECT_ID=PVT_kwHOAEnMVc4BCu-c

GitHub Token Scopes Required:

  • repo - Full control of private repositories
  • project - Full control of projects
  • workflow - Update GitHub Action workflows
  • admin:org - If using organization projects

How to create:

  1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens
  2. Generate new token (classic)
  3. Select required scopes
  4. Copy token immediately (shown only once)

Used for:

  • PowerShell automation scripts
  • PR management automation
  • Issue management automation
  • GitHub API interactions

Configuration Files

Agent Assignment Configuration

Location: scripts/configuration/agent-assignment-config.json

Purpose: Configure multi-agent development system

{
  "version": "1.0.0",
  "description": "Agent Assignment Configuration",
  "humanAgents": {
    "agent-name": {
      "name": "Agent Display Name",
      "gitHubUsername": "github-username",
      "agentType": "agent-frontend | agent-backend",
      "workTreeId": "agent-1-name",
      "assignedAreas": ["Frontend", "Backend", "API"],
      "assignedApps": ["Portfolio Site", "Dashboard"],
      "issueRanges": [100, 120],
      "branchPrefix": "feat/frontend",
      "skills": ["React", "TypeScript", "Node.js"],
      "maxConcurrentIssues": 3,
      "priority": "P1",
      "autoAssignment": true,
      "workTreePath": "worktrees/agent-1-name"
    }
  },
  "assignmentRules": {
    "autoSwitchWorkTree": true,
    "preventConflicts": true,
    "requireApproval": false,
    "syncInterval": 300,
    "conflictResolution": "assign-to-optimal-agent"
  }
}

Fields:

FieldTypeDescription
namestringHuman-readable agent name
gitHubUsernamestringGitHub username for assignments
agentTypestringAgent specialization
workTreeIdstringUnique worktree identifier
assignedAreasarrayTechnical areas of responsibility
assignedAppsarrayApps this agent works on
issueRangesarrayIssue number ranges
branchPrefixstringGit branch prefix
skillsarrayTechnical skills
maxConcurrentIssuesnumberMax simultaneous issues
prioritystringDefault priority (P0-P3)
autoAssignmentbooleanEnable auto-assignment
workTreePathstringPath to worktree directory

Used by:

  • scripts/agent-management/assign-agent-enhanced.ps1
  • scripts/agent-management/manage-multi-agent-system.ps1
  • Multi-agent coordination scripts

Worktree State Configuration

Location: scripts/configuration/worktree-state.json

Purpose: Track state of git worktrees for multi-agent system

{
  "version": "1.0.0",
  "lastUpdated": "2025-10-06T00:36:00Z",
  "agents": {
    "agent-1-name": {
      "name": "Agent Name",
      "description": "Agent description",
      "type": "agent-frontend",
      "status": "active | inactive | busy",
      "workTreePath": "worktrees/agent-1-name",
      "currentBranch": "feat/frontend/feature-name",
      "currentIssue": 123,
      "lockedIssues": [123, 124],
      "lastActivity": "2025-10-06T00:36:00Z",
      "assignedIssues": [123, 124, 125],
      "maxConcurrent": 3,
      "skills": ["React", "TypeScript"]
    }
  },
  "system": {
    "totalWorkTrees": 2,
    "activeWorkTrees": 2,
    "lastSync": "2025-10-06T00:36:00Z",
    "conflictPrevention": {
      "enabled": true,
      "lockTimeout": 3600,
      "maxRetries": 3
    }
  }
}

Fields:

FieldTypeDescription
statusstringCurrent agent status
currentBranchstringActive git branch
currentIssuenumberIssue being worked on
lockedIssuesarrayIssues locked by this agent
lastActivitystringISO 8601 timestamp

Updated by:

  • Worktree management scripts
  • Agent coordination scripts
  • Automated on git operations

Turbo Configuration

Location: turbo.json

Purpose: Configure Turborepo build system

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [
    "**/.env*",
    "**/package.json"
  ],
  "remoteCache": {
    "enabled": true,
    "signature": true
  },
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"],
      "env": ["NODE_ENV", "NEXT_PUBLIC_*"]
    }
  }
}

Key Settings:

SettingPurpose
globalDependenciesFiles that invalidate all caches
remoteCache.enabledEnable Vercel remote caching
tasks.build.outputsCache build artifacts
tasks.build.envEnvironment variables for builds

Used for:

  • Monorepo build orchestration
  • Dependency management
  • Build caching
  • Parallel task execution

GitHub Actions Secrets

Required Secrets

Configure in GitHub: Repository → Settings → Secrets and Variables → Actions

GITHUB_TOKEN

Description: Automatically provided by GitHub Actions
Scope: Repository access
Setup: None required (auto-provided)
Used for: PR operations, issue management, workflow permissions

Database Secrets (Production)

# Production database URL
DATABASE_URL=postgresql://...

# Direct database URL
DIRECT_URL=postgresql://...

Setup: Add in repository secrets
Used for: Production deployments, CI database access

OpenAI Secrets (Optional)

OPENAI_API_KEY=sk-...

Setup: Add if using AI features
Used for: Chatbot testing in CI, content generation

Vercel Deployment (Optional)

VERCEL_TOKEN=...
VERCEL_ORG_ID=...
VERCEL_PROJECT_ID=...

Setup: Get from Vercel dashboard
Used for: Automated deployments from CI

Secret Management Best Practices

✅ DO:

  • Use GitHub Secrets for all sensitive data
  • Rotate secrets regularly
  • Use different secrets for dev/prod
  • Limit secret access to necessary workflows
  • Use environment-specific secrets

❌ DON'T:

  • Commit secrets to repository
  • Log secret values in CI
  • Share secrets in issues/PRs
  • Use same secrets across projects
  • Store secrets in code comments

Environment Variable Validation

Validation Script

Create a validation script to check required variables:

# scripts/validate-env.sh
#!/bin/bash

required_vars=(
  "DATABASE_URL"
  "NEXTAUTH_SECRET"
  "NEXT_PUBLIC_HASHNODE_GQL_ENDPOINT"
)

missing=()
for var in "${required_vars[@]}"; do
  if [ -z "${!var}" ]; then
    missing+=("$var")
  fi
done

if [ ${#missing[@]} -gt 0 ]; then
  echo "❌ Missing required environment variables:"
  printf '%s\n' "${missing[@]}"
  exit 1
else
  echo "✅ All required environment variables are set"
fi

Runtime Validation

Add to next.config.js:

// Validate required environment variables at build time
const requiredEnvVars = [
  'DATABASE_URL',
  'NEXTAUTH_SECRET',
  'NEXT_PUBLIC_HASHNODE_GQL_ENDPOINT',
];

requiredEnvVars.forEach((envVar) => {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
});

Troubleshooting

Common Issues

Environment Variables Not Loading

# Verify file exists
ls -la apps/site/.env.local

# Check file permissions
chmod 600 apps/site/.env.local

# Restart dev server
pnpm dev

Database Connection Errors

# Test database connection
psql $DATABASE_URL

# Verify connection string format
echo $DATABASE_URL

OpenAI API Errors

# Check API key format
echo $OPENAI_API_KEY | head -c 10

# Verify key is active in OpenAI dashboard
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

GitHub Token Permissions

# Check token scopes
gh auth status

# Verify token with GitHub API
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user

Migration & Updates

Updating Environment Variables

When adding new variables:

  1. Update env.template files
  2. Update this documentation
  3. Update validation scripts
  4. Notify team members
  5. Update CI/CD secrets if needed

Version Control

# Track changes to configuration files
git add turbo.json
git add scripts/configuration/*.json

# Never commit .env.local files
git status  # Should show .env.local as ignored

Security Best Practices

Secret Rotation

Rotate secrets every:

  • 90 days - API keys
  • 180 days - Database passwords
  • 365 days - GitHub tokens
  • Immediately - If compromised

Access Control

  • Use environment-specific secrets
  • Limit GitHub Actions secret access
  • Use Vercel environment variables for production
  • Never log secret values

Monitoring

  • Enable GitHub secret scanning
  • Monitor API usage (OpenAI, etc.)
  • Track database connection attempts
  • Review GitHub Actions logs regularly

Additional Resources

Internal Documentation

External Resources

Need Help? If you encounter configuration issues, check the Troubleshooting Guide or create an issue in the repository.