Environment Configuration

Configure API keys, secrets, and environment variables for Portfolio OS

Overview

Configure API keys, secrets, and environment variables for Portfolio OS

Portfolio OS uses environment variables to configure API keys, database connections, and feature flags across different environments.

Environment Files Overview

The monorepo uses separate environment files for each app:

File LocationPurposeWhen to Use
apps/site/.env.localSite app secretsDevelopment & Production
apps/dashboard/.env.localDashboard app secretsDevelopment & Production
apps/site/.env.exampleSite environment templateReference for required variables
apps/dashboard/.env.exampleDashboard environment templateReference for required variables

Note:

Never commit .env.local files to Git! They are automatically ignored via .gitignore to protect sensitive credentials.

Quick Setup

1

Copy Environment Templates

# From the repository root
cp apps/site/.env.example apps/site/.env.local
cp apps/dashboard/.env.example apps/dashboard/.env.local
2

Edit Environment Files

Open each .env.local file and fill in your API keys and configuration values.

Start with the required variables (marked below), then add optional ones as needed.

3

Restart Development Servers

# Stop the dev servers (Ctrl+C) and restart
pnpm dev

Environment variables are loaded at build time for Next.js.

Site App Environment Variables

Configuration for apps/site/.env.local:

Required Variables

Hashnode Content Integration

Portfolio OS can source blog content from Hashnode via their GraphQL API.

NEXT_PUBLIC_HASHNODE_PUBLICATION_HOST=yourblog.hashnode.dev

How to get this:

  1. Sign up at hashnode.com
  2. Create a publication
  3. Use your publication's domain (e.g., mindware.hashnode.dev)

Note:

This variable is public (prefixed with NEXT_PUBLIC_) and will be exposed to the browser.

Optional Variables

# Base URL for absolute URLs (useful for OG images, sitemaps)
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Environment mode
NEXT_PUBLIC_MODE=development

# Feature flags
NEXT_PUBLIC_ENABLE_ANALYTICS=false
NEXT_PUBLIC_ENABLE_COMMENTS=false

Dashboard App Environment Variables

Configuration for apps/dashboard/.env.local:

Required Variables

Database URL (SQLite for Development)

DATABASE_URL=file:./dev.db

Note:

The dashboard uses Prisma with SQLite for local development. In production, you can switch to PostgreSQL or another database.

Blob Storage (Vercel Blob)

BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...

How to get this:

  1. Create a Vercel account
  2. Enable Blob Storage for your project
  3. Copy the read/write token

Optional Variables

# Admin authentication
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD_HASH=your-bcrypt-hash

# Analytics
NEXT_PUBLIC_VERCEL_ANALYTICS_ID=your-analytics-id

Complete Environment File Examples

apps/site/.env.local

# Hashnode Content
NEXT_PUBLIC_HASHNODE_PUBLICATION_HOST=mindware.hashnode.dev

# AI Features
OPENAI_API_KEY=sk-proj-your-key-here

# Email
RESEND_API_KEY=re_your-key-here
RESEND_FROM_EMAIL=noreply@yourdomain.com
RESEND_TO_EMAIL=your-email@example.com

# Caching
UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token-here

# Optional Configuration
NEXT_PUBLIC_BASE_URL=http://localhost:3000
NEXT_PUBLIC_MODE=development

apps/dashboard/.env.local

# Database
DATABASE_URL=file:./dev.db

# Storage
BLOB_READ_WRITE_TOKEN=vercel_blob_rw_your-token-here

# Optional
ADMIN_EMAIL=admin@example.com

Environment Variable Loading

Next.js automatically loads environment variables in this order:

  1. .env.local (highest priority, gitignored)
  2. .env.development or .env.production (based on NODE_ENV)
  3. .env (lowest priority)

Note:

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser and baked into the JavaScript bundle at build time.

Production Deployment

When deploying to Vercel, Railway, or other platforms:

1

Add Environment Variables to Platform

Navigate to your project settings and add all required environment variables.

For Vercel:

  • Go to Project Settings → Environment Variables
  • Add each variable individually
  • Select which environments they apply to (Production, Preview, Development)
2

Update Production-Specific Values

# Change these for production
NEXT_PUBLIC_BASE_URL=https://yourdomain.com
NEXT_PUBLIC_MODE=production
DATABASE_URL=postgresql://user:password@host:5432/dbname
3

Redeploy Application

Changes to environment variables require a new deployment to take effect.

Security Best Practices

Note:

Critical Security Guidelines:

  1. Never commit .env.local files to version control
  2. Don't expose server-side API keys in NEXT_PUBLIC_ variables
  3. Rotate API keys if they're accidentally exposed
  4. Use different API keys for development and production
  5. Enable rate limiting on production API keys

Checking for Exposed Secrets

# Scan repository for accidentally committed secrets
git log --all --full-history -- "**/.env.local"

# If found, rotate all exposed credentials immediately

Troubleshooting

Environment Variables Not Loading

Problem: Variables are undefined in your app

Solutions:

  1. Ensure .env.local file exists in the correct app directory
  2. Restart development server after adding/changing variables
  3. Check variable names are spelled correctly
  4. For client-side access, ensure variable is prefixed with NEXT_PUBLIC_

Build Errors Due to Missing Variables

Problem: Build fails with "Required environment variable X is not set"

Solutions:

  1. Check that all required variables are present in .env.local
  2. Ensure variables are set in your deployment platform
  3. Verify no typos in variable names

Variables Work Locally But Not in Production

Problem: App works in development but fails in production

Solutions:

  1. Add environment variables to your hosting platform (Vercel, Railway, etc.)
  2. Ensure production database URL is correct
  3. Check that NEXT_PUBLIC_BASE_URL matches your production domain

Next Steps

With your environment configured:

  1. First Steps Tutorial - Build your first feature
  2. Setup Guides - Configure database and storage
  3. API Reference - Explore available APIs

Note:

For production deployment configuration, see the Deployment Runbook.