Environment Setup

Configure environment variables and external services for PC Fix

PC Fix requires several environment variables and external service integrations to function properly. This guide covers all configuration needed for both the frontend and backend.

Overview

The PC Fix monorepo has two main packages that require separate environment configuration:

• packages/api: Backend API with database, authentication, and integrations
• packages/web: Frontend application with Astro and React

Never commit .env files to version control. Add them to .gitignore and use .env.example as a template.

Backend Environment Variables

Create packages/api/.env with the following configuration:

Database Configuration

.env

# PostgreSQL Database
DATABASE_URL="postgresql://admin:password123@localhost:5432/pcfix_db?schema=public"

Database URL Format

The DATABASE_URL follows this format:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA

• USER: Database username (default: admin)
• PASSWORD: Database password (default: password123)
• HOST: Database host (localhost for local, postgres for Docker)
• PORT: Database port (default: 5432)
• DATABASE: Database name (default: pcfix_db)

Authentication & Security

.env

# JWT Configuration
JWT_SECRET="your-super-secret-jwt-key-change-this-in-production"
JWT_REFRESH_SECRET="your-refresh-token-secret-change-this-too"
JWT_EXPIRES_IN="7d"
JWT_REFRESH_EXPIRES_IN="30d"

# Google OAuth
GOOGLE_CLIENT_ID="your-google-oauth-client-id.apps.googleusercontent.com"

1. Generate JWT Secrets

   Generate secure random strings for JWT secrets:

   node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
   
2. Configure Google OAuth

   1. Go to Google Cloud Console
   2. Create a new project or select existing
   3. Enable Google+ API
   4. Create OAuth 2.0 credentials
   5. Add authorized redirect URIs
   6. Copy the Client ID to your .env

External Services

.env

# Cloudinary (Image CDN)
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"

# MercadoPago (Payment Gateway)
MERCADOPAGO_ACCESS_TOKEN="your-mercadopago-access-token"

# Resend (Email Service)
RESEND_API_KEY="re_your_api_key_here"
EMAIL_FROM="[e-mail]"

# Sentry (Error Monitoring)
SENTRY_DSN="https://[e-mail]/project-id"

Server Configuration

.env

# Server
PORT=3002
NODE_ENV="development"
API_URL="http://localhost:3002"

# Frontend URL (for CORS)
FRONTEND_URL="http://localhost:4321"

Frontend Environment Variables

Create packages/web/.env with the following configuration:

API Connection

.env

# Public API URL (for client-side requests)
PUBLIC_API_URL="http://localhost:3002/api"

# SSR API URL (for server-side requests in Docker)
SSR_API_URL="http://localhost:3002/api"

In Docker environments, use SSR_API_URL="http://api:3002/api" to leverage Docker’s internal networking.

Google OAuth (Frontend)

.env

# Google OAuth Client ID (same as backend)
PUBLIC_GOOGLE_CLIENT_ID="your-google-oauth-client-id.apps.googleusercontent.com"

Sentry (Frontend)

.env

# Sentry DSN for frontend monitoring
PUBLIC_SENTRY_DSN="https://[e-mail]/project-id"

External Services Setup

Cloudinary Setup

1. Sign up at cloudinary.com
2. Navigate to Dashboard
3. Copy Cloud Name, API Key, and API Secret
4. Add credentials to packages/api/.env

Used for:

• Product image uploads
• Payment receipt uploads
• CDN delivery

MercadoPago Setup

1. Create account at mercadopago.com
2. Go to Your integrations
3. Create a new application
4. Copy the Access Token (use Test credentials for development)
5. Configure webhook URL: https://your-api-url.com/api/sales/mp-webhook

Test cards for development:

• Approved: 4509 9535 6623 3704 (any future date, any CVV)
• Rejected: 4017 1410 1414 1234

Resend Setup

1. Sign up at resend.com
2. Verify your domain or use their test domain
3. Generate an API key
4. Add to packages/api/.env

Emails sent:

• Order confirmations
• Payment receipts
• Password reset links
• Abandoned cart reminders
• Stock alerts

Sentry Setup

1. Sign up at sentry.io
2. Create two projects:
   • PC Fix API (Node.js)
   • PC Fix Web (Astro/Browser)
3. Copy both DSN values
4. Add to respective .env files

Monitoring:

• Backend: Server errors, unhandled exceptions
• Frontend: JavaScript errors, failed requests

Environment Templates

Create .env.example files in both packages for team reference:

API .env.example

packages/api/.env.example

# Database
DATABASE_URL="postgresql://admin:password123@localhost:5432/pcfix_db?schema=public"

# JWT
JWT_SECRET="change-this-secret"
JWT_REFRESH_SECRET="change-this-too"
JWT_EXPIRES_IN="7d"
JWT_REFRESH_EXPIRES_IN="30d"

# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"

# Cloudinary
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"

# MercadoPago
MERCADOPAGO_ACCESS_TOKEN="your-access-token"

# Resend
RESEND_API_KEY="re_your_api_key"
EMAIL_FROM="[e-mail]"

# Sentry
SENTRY_DSN="https://[e-mail]/id"

# Server
PORT=3002
NODE_ENV="development"
API_URL="http://localhost:3002"
FRONTEND_URL="http://localhost:4321"

Web .env.example

packages/web/.env.example

# API URLs
PUBLIC_API_URL="http://localhost:3002/api"
SSR_API_URL="http://localhost:3002/api"

# Google OAuth
PUBLIC_GOOGLE_CLIENT_ID="your-google-client-id"

# Sentry
PUBLIC_SENTRY_DSN="https://[e-mail]/id"

Validation

Verify your configuration is correct:

1. Test Database Connection

   cd packages/api
   npm run db:studio
   

   Should open Prisma Studio at http://localhost:5555

2. Test API Server

   cd packages/api
   npm run dev
   

   Visit http://localhost:3002/health - should return JSON with {"success": true}

3. Test Frontend

   cd packages/web
   npm run dev
   

   Visit http://localhost:4321 - should load the home page

Troubleshooting

Database connection failed

• Verify PostgreSQL is running: pg_isready
• Check DATABASE_URL format and credentials
• Ensure database pcfix_db exists
• For Docker: use host postgres instead of localhost

JWT errors

• Ensure JWT_SECRET is set and not empty
• Regenerate secrets if you suspect compromise
• Check token expiration times are valid

CORS errors

• Verify FRONTEND_URL matches your frontend’s actual URL
• Include protocol (http:// or https://)
• For Docker, add both localhost and container URLs to whitelist

External service errors

• Test API keys in service dashboards first
• Check for typos in credentials
• Verify services are not rate-limited
• Check service status pages for outages

Next Steps

Docker Deployment

Deploy PC Fix with Docker Compose

Database Migrations

Manage database schema changes

Testing

Run unit and E2E tests

Integrations

Configure payment providers