Installation Guide

This guide covers detailed installation instructions for PC Fix, including manual setup without Docker, all dependencies, database configuration, and deployment options.

For a quick Docker-based setup, see the Quick Start Guide. This guide is for developers who need manual installation or want to understand the complete setup process.

Prerequisites

Required Software

Node.js 20+

Download from nodejs.orgVerify installation:

node --version  # Should be 20.x or higher
npm --version   # Should be 10.x or higher

PostgreSQL 15+

Download from postgresql.orgVerify installation:

psql --version  # Should be 15.x or higher

Git

Download from git-scm.comVerify installation:

git --version

Docker (Optional)

Download from docker.comOnly required for containerized deployment

System Requirements

OS: Linux, macOS, or Windows with WSL2
RAM: Minimum 4GB, recommended 8GB+
Disk Space: 2GB for dependencies and builds
Ports Available: 3001 (API), 4321 (Web), 5432 (PostgreSQL)

Installation Methods

Manual Setup (Recommended for Development)
Docker Compose (Quickest)

Best for: Active development, debugging, and customization

1. Clone the Repository

git clone https://github.com/martin-ratti/PCFIX-Baru.git
cd PCFIX-Baru

2. Install Dependencies

PC Fix uses NPM Workspaces for monorepo management. Install all dependencies from the root:

npm install

This installs dependencies for both packages/api and packages/web.

If you encounter peer dependency warnings, the project uses --legacy-peer-deps to resolve conflicts.

3. Set Up PostgreSQL Database

Option A: Local PostgreSQL Installation

Create a new database and user:

# Connect to PostgreSQL
psql -U postgres

# Create database and user
CREATE DATABASE pcfix_db;
CREATE USER pcfix_user WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE pcfix_db TO pcfix_user;

# Exit psql
\q

Option B: Docker PostgreSQL Only

Run just the database in Docker:

docker run -d \
  --name pcfix-postgres \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=password123 \
  -e POSTGRES_DB=pcfix_db \
  -p 5432:5432 \
  postgres:15-alpine

4. Configure API Environment Variables

Create packages/api/.env:

# Database Connection
DATABASE_URL="postgresql://pcfix_user:your_password@localhost:5432/pcfix_db?schema=public"

# Server Configuration
PORT=3001
NODE_ENV=development

# JWT Authentication
JWT_SECRET="generate-a-random-secret-key-here"
JWT_REFRESH_SECRET="generate-another-random-secret-key"
JWT_EXPIRES_IN="15m"
JWT_REFRESH_EXPIRES_IN="7d"

# CORS Configuration
CORS_ORIGIN="http://localhost:4321"

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

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

# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
GOOGLE_REDIRECT_URI="http://localhost:3001/api/auth/google/callback"

# Resend (Email Service)
RESEND_API_KEY="your-resend-api-key"
FROM_EMAIL="[email protected]"

# Sentry (Error Monitoring)
SENTRY_DSN="your-sentry-dsn"

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100

Never commit .env files to version control. Add them to .gitignore.

5. Configure Web Environment Variables

Create packages/web/.env:

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

# Google OAuth Client ID (for frontend)
PUBLIC_GOOGLE_CLIENT_ID="your-google-client-id"

# Sentry DSN (for frontend error tracking)
PUBLIC_SENTRY_DSN="your-sentry-dsn"

# Site Configuration
PUBLIC_SITE_URL="http://localhost:4321"

6. Run Database Migrations

Generate Prisma Client and run migrations:

cd packages/api
npx prisma generate
npx prisma migrate deploy

This creates all database tables according to the schema in prisma/schema.prisma.

7. Seed the Database (Optional)

Populate the database with sample data:

cd packages/api
npm run db:push  # Alternative to migrations for development
npx prisma db seed

This creates:

Product categories (Processors, Graphics Cards, Memory, etc.)
Sample brands (Intel, AMD, NVIDIA, etc.)
Demo products with images
Admin user account
Sample orders and customers

8. Start Development Servers

Open two terminal windows:Terminal 1 - API Server:

cd packages/api
npm run dev

The API will start at http://localhost:3001Terminal 2 - Web Server:

cd packages/web
npm run dev

The frontend will start at http://localhost:4321

9. Verify Installation

Visit http://localhost:4321 - Should show the PC Fix homepage
Visit http://localhost:3001/api/health - Should return {"status":"ok"}
Check database with Prisma Studio:
```
cd packages/api
npm run db:studio
```
Opens at http://localhost:5555

Best for: Quick setup, consistent environments, and demo deploymentsSee the Quick Start Guide for detailed Docker Compose instructions.Summary:

# Clone repository
git clone https://github.com/martin-ratti/PCFIX-Baru.git
cd PCFIX-Baru

# Create environment files (see Quickstart guide)
# Create packages/api/.env
# Create packages/web/.env

# Start all services
docker-compose up --build

Access:

Frontend: http://localhost:4321
API: http://localhost:3001
Database: localhost:5432

Database Configuration

Prisma Schema Overview

PC Fix uses Prisma ORM with PostgreSQL. The schema includes:

User & Authentication Models

User: User accounts with role-based access
RefreshToken: JWT refresh token management
Cliente: Extended customer profiles with addresses
Localidad & Provincia: Location data for Argentina

Product Models

Producto: Product catalog with inventory tracking
Categoria: Product categories (hierarchical)
Marca: Brand management
ImagenProducto: Multiple images per product
Favorite: User wishlists

Shopping & Orders

Cart & CartItem: Shopping cart management
Venta: Orders and sales
ItemVenta: Order line items
Pago: Payment tracking with multiple methods

Services & Support

ConsultaTecnica: Technical consultation requests
Servicio: Service offerings
ServicioPersonalizado: Custom service pricing

Content & Marketing

Banner: Homepage banners and promotions
Settings: Site configuration

Common Prisma Commands

# Generate Prisma Client (after schema changes)
npx prisma generate

# Create a new migration
npx prisma migrate dev --name your_migration_name

# Apply migrations to production
npx prisma migrate deploy

# Push schema changes without migrations (dev only)
npx prisma db push

# Open Prisma Studio (database GUI)
npx prisma studio

# Reset database (WARNING: deletes all data)
npx prisma migrate reset

# Seed database
npx prisma db seed

External Services Configuration

Cloudinary (Image CDN)

Create Account

Get Credentials

Find your credentials in Dashboard → Account Details:

Cloud Name
API Key
API Secret

Add to .env

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

MercadoPago (Payment Gateway)

Create Account

Get API Credentials

Navigate to Developers → Credentials:

Access Token (for backend)
Public Key (for frontend)

Add to .env

# Backend (.env)
MERCADOPAGO_ACCESS_TOKEN="your-access-token"

Google OAuth

Create Project

Go to Google Cloud Console

Enable OAuth

APIs & Services → Credentials → Create OAuth Client ID

Application type: Web application
Authorized redirect URIs: http://localhost:3001/api/auth/google/callback

Add Credentials

# Backend
GOOGLE_CLIENT_ID="your-client-id"
GOOGLE_CLIENT_SECRET="your-client-secret"

# Frontend
PUBLIC_GOOGLE_CLIENT_ID="your-client-id"

Resend (Email Service)

Create Account

Generate API Key

Dashboard → API Keys → Create API Key

Verify Domain (Production)

Add your domain for production email sending

Add to .env

RESEND_API_KEY="re_your_api_key"
FROM_EMAIL="[email protected]"

Sentry (Error Monitoring)

Create Project

Get DSN

Project Settings → Client Keys (DSN)

Add to Both .env Files

# Backend
SENTRY_DSN="your-backend-dsn"

# Frontend
PUBLIC_SENTRY_DSN="your-frontend-dsn"

NPM Scripts Reference

Root Level Commands

# Run web development server
npm run dev

# Run tests across all packages
npm run test

API Package (`packages/api`)

# Development
npm run dev              # Start with nodemon (hot reload)
npm run build            # Build TypeScript to dist/
npm start                # Run production build

# Database
npm run db:push          # Push schema changes (dev)
npm run db:studio        # Open Prisma Studio
npx prisma migrate dev   # Create migration
npx prisma migrate deploy # Apply migrations

# Testing
npm test                 # Run Vitest unit tests
npm run test:watch       # Run tests in watch mode
npm run test:coverage    # Generate coverage report

Web Package (`packages/web`)

# Development
npm run dev              # Start Astro dev server
npm run build            # Build for production
npm run preview          # Preview production build

# Testing
npm test                 # Run Vitest unit tests
npm run e2e              # Run Playwright E2E tests
npm run test:coverage    # Generate coverage report

# Type Checking
npm run astro check      # Check Astro files

Troubleshooting

PostgreSQL Connection Errors

Error: Error: P1001: Can't reach database serverSolutions:

Verify PostgreSQL is running:

# macOS
brew services list

# Linux
sudo systemctl status postgresql

# Windows
services.msc (look for PostgreSQL)

Check DATABASE_URL format:

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

Test connection directly:

psql -U pcfix_user -d pcfix_db -h localhost

Prisma Client Generation Issues

Error: Cannot find module '@prisma/client'Solution:

cd packages/api
npx prisma generate

After schema changes, always regenerate the client.

Port Already in Use

Error: Port 3001 (or 4321) is already in useSolutions:

Find and kill the process:

# macOS/Linux
lsof -ti:3001 | xargs kill -9

# Windows
netstat -ano | findstr :3001
taskkill /PID <PID> /F

Change port in .env:

# API
PORT=3002

# Web (in astro.config.mjs)
server: { port: 4322 }

Module Not Found Errors

Error: Various “Cannot find module” errorsSolution:

# Clear and reinstall dependencies
rm -rf node_modules package-lock.json
rm -rf packages/*/node_modules
npm install

CORS Errors in Browser

Error: Access to fetch has been blocked by CORS policySolution: Ensure API .env has correct CORS_ORIGIN:

CORS_ORIGIN="http://localhost:4321"

For multiple origins:

CORS_ORIGIN="http://localhost:4321,http://localhost:3000"

JWT Token Issues

Error: JsonWebTokenError: invalid signatureSolutions:

Ensure JWT secrets are set in .env
Clear browser cookies and local storage
Restart the API server after changing JWT secrets

TypeScript Build Errors

Solution:

cd packages/api  # or packages/web
npx tsc --noEmit  # Check for type errors

Common fixes:

Update @types/* packages
Check tsconfig.json settings
Regenerate Prisma client

Production Deployment

Environment Preparation

Update Environment Variables

Change all secrets (JWT, database passwords)
Update CORS_ORIGIN to production domain
Configure production database URL
Set NODE_ENV=production

Build Applications

# API
cd packages/api
npm run build

# Web
cd packages/web
npm run build

Run Database Migrations

cd packages/api
npx prisma migrate deploy

Deployment Options

Vercel (Frontend)

Best for: Astro frontend deployment

Connect GitHub repository
Set root directory: packages/web
Add environment variables
Deploy automatically on push

Railway (Backend + DB)

Best for: Express API and PostgreSQL

Create new project
Add PostgreSQL database
Deploy API from GitHub
Configure environment variables

Docker Production

Best for: Self-hosted deployments

docker-compose -f docker-compose.yml \
  -f docker-compose.prod.yml up -d

VPS (DigitalOcean, AWS)

Best for: Full control deployments

Set up Node.js 20+
Install PostgreSQL
Clone repository
Configure PM2 or systemd
Set up Nginx reverse proxy

Testing

Run Tests

# Unit tests (API)
cd packages/api
npm test

# Unit tests (Web)
cd packages/web
npm test

# E2E tests (Web)
cd packages/web
npm run e2e

# Coverage reports
npm run test:coverage

Test Configuration

Vitest: Unit testing for both packages
Playwright: E2E testing for critical user flows
Supertest: API endpoint testing

Next Steps

Explore the Codebase

API structure: packages/api/src/modules/
Frontend components: packages/web/src/components/
Database schema: packages/api/prisma/schema.prisma

Configure Admin Account

Create admin user via Prisma Studio or seed script to access admin dashboard

Customize Branding

Update logo: packages/web/public/logo.png
Modify colors: packages/web/tailwind.config.mjs
Edit site metadata: packages/web/src/layouts/Layout.astro

Set Up External Services

Configure Cloudinary, MercadoPago, and email services for full functionality

Get Started

Architecture

Features

Guides

​Installation Guide

​Prerequisites

​Required Software

Node.js 20+

PostgreSQL 15+

Git

Docker (Optional)

​System Requirements

​Installation Methods

​1. Clone the Repository

​2. Install Dependencies

​3. Set Up PostgreSQL Database

​Option A: Local PostgreSQL Installation

​Option B: Docker PostgreSQL Only

​4. Configure API Environment Variables

​5. Configure Web Environment Variables

​6. Run Database Migrations

​7. Seed the Database (Optional)

​8. Start Development Servers

​9. Verify Installation

​Database Configuration

​Prisma Schema Overview

​Common Prisma Commands

​External Services Configuration

​Cloudinary (Image CDN)

​MercadoPago (Payment Gateway)

​Google OAuth

​Resend (Email Service)

​Sentry (Error Monitoring)

​NPM Scripts Reference

​Root Level Commands

​API Package (packages/api)

​Web Package (packages/web)

​Troubleshooting

​Production Deployment

​Environment Preparation

​Deployment Options

Vercel (Frontend)

Railway (Backend + DB)

Docker Production

VPS (DigitalOcean, AWS)

​Testing

​Run Tests

​Test Configuration

​Next Steps

Explore the Codebase

Configure Admin Account

Customize Branding

Set Up External Services

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Required Software

System Requirements

Installation Methods

1. Clone the Repository

2. Install Dependencies

3. Set Up PostgreSQL Database

Option A: Local PostgreSQL Installation

Option B: Docker PostgreSQL Only

4. Configure API Environment Variables

5. Configure Web Environment Variables

6. Run Database Migrations

7. Seed the Database (Optional)

8. Start Development Servers

9. Verify Installation

Database Configuration

Prisma Schema Overview

Common Prisma Commands

External Services Configuration

Cloudinary (Image CDN)

MercadoPago (Payment Gateway)

Google OAuth

Resend (Email Service)

Sentry (Error Monitoring)

NPM Scripts Reference

Root Level Commands

API Package (`packages/api`)

Web Package (`packages/web`)

Troubleshooting

Production Deployment

Environment Preparation

Deployment Options

Testing

Run Tests

Test Configuration

Next Steps