Quick Start

Get PC Fix running locally in under 5 minutes using Docker Compose

Quick Start Guide

Get PC Fix up and running on your local machine in under 5 minutes using Docker Compose. This guide will have you running the complete stack - frontend, backend, and database.

This quickstart uses Docker Compose to orchestrate all services. If you prefer manual setup or need to customize your installation, see the Installation Guide.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 20+: Download here
• Docker Desktop: Download here
• Git: Download here

Docker Desktop must be running before executing the docker-compose commands.

Step-by-Step Setup

1. Clone the Repository

   Clone the PC Fix repository to your local machine:

   git clone https://github.com/martin-ratti/PCFIX-Baru.git
   cd PCFIX-Baru
   
2. Configure Environment Variables

   PC Fix requires environment variables for the API and Web packages. Create the following files:

   API Environment (packages/api/.env)

   Create packages/api/.env with these variables:

   # Database
   DATABASE_URL="postgresql://admin:password123@postgres:5432/pcfix_db?schema=public"
   
   # Server
   PORT=3001
   NODE_ENV=development
   
   # Authentication
   JWT_SECRET="your-super-secret-jwt-key-change-in-production"
   JWT_REFRESH_SECRET="your-super-secret-refresh-key-change-in-production"
   JWT_EXPIRES_IN="15m"
   JWT_REFRESH_EXPIRES_IN="7d"
   
   # CORS
   CORS_ORIGIN="http://localhost:4321"
   
   # Optional: External Services (for full functionality)
   # CLOUDINARY_CLOUD_NAME="your-cloudinary-name"
   # CLOUDINARY_API_KEY="your-api-key"
   # CLOUDINARY_API_SECRET="your-api-secret"
   # MERCADOPAGO_ACCESS_TOKEN="your-mercadopago-token"
   # GOOGLE_CLIENT_ID="your-google-client-id"
   # GOOGLE_CLIENT_SECRET="your-google-client-secret"
   # RESEND_API_KEY="your-resend-api-key"
   # SENTRY_DSN="your-sentry-dsn"
   

   Web Environment (packages/web/.env)

   Create packages/web/.env with these variables:

   # API URLs
   PUBLIC_API_URL="http://localhost:3001/api"
   SSR_API_URL="http://api:3001/api"
   
   # Google OAuth (optional)
   # PUBLIC_GOOGLE_CLIENT_ID="your-google-client-id"
   
   # Sentry (optional)
   # PUBLIC_SENTRY_DSN="your-sentry-dsn"
   

   The database URL uses postgres as the hostname because Docker Compose creates an internal network where services reference each other by service name.

3. Start Docker Compose

   Launch all services with a single command:

   docker-compose up --build
   

   This command will:

   • Build the API and Web Docker images
   • Start a PostgreSQL 15 database container
   • Run Prisma migrations to set up the database schema
   • Start the Express API server on port 3001
   • Start the Astro development server on port 4321

   The first build may take 5-10 minutes as it downloads base images and installs dependencies.

4. Verify Services are Running

   Once Docker Compose finishes starting, verify all services are accessible:

   • Frontend: http://localhost:4321
   • API: http://localhost:3001/api/health
   • Prisma Studio (optional): Run docker exec -it pcfix-api npx prisma studio to access the database GUI at http://localhost:5555

   You should see the PC Fix homepage at localhost:4321 and a JSON health response from the API.

5. Seed the Database (Optional)

   To populate the database with sample products and data:

   docker exec -it pcfix-api npm run db:seed
   

   This will create:

   • Sample product categories and brands
   • Demo products with images
   • Test user accounts
   • Sample orders and transactions

What’s Running?

Your Docker Compose setup includes three services:

PostgreSQL Database

Container: pcfix-postgres

Port: 5432

Credentials:

• User: admin
• Password: password123
• Database: pcfix_db

Persistent volume: postgres_data

Express API

Container: pcfix-api

Port: 3001

Features:

• Hot reload with nodemon
• Auto-runs migrations on start
• Volume-mounted source code

Astro Web Frontend

Container: pcfix-web

Port: 4321

Features:

• Hot reload on file changes
• SSR with React islands
• Volume-mounted source code

Common Docker Commands

# View logs from all services
docker-compose logs -f

# View logs from a specific service
docker-compose logs -f api
docker-compose logs -f web

# Stop all services
docker-compose down

# Stop and remove volumes (clears database)
docker-compose down -v

# Restart a specific service
docker-compose restart api

# Execute commands in a running container
docker exec -it pcfix-api npm run db:studio

# Rebuild after code changes
docker-compose up --build

Accessing the Admin Dashboard

1. Create an Admin User

   Connect to the API container and create an admin user:

   docker exec -it pcfix-api npx prisma studio
   

   Navigate to the User model and create a user with role: ADMIN.

2. Login to Admin Panel

   Visit http://localhost:4321/admin and login with your admin credentials.

Development Workflow

With Docker Compose running, you can edit files locally and see changes immediately:

1. Frontend changes: Edit files in packages/web/src/ - Astro will hot reload
2. Backend changes: Edit files in packages/api/src/ - Nodemon will restart the server
3. Database schema changes: Edit packages/api/prisma/schema.prisma then run:

docker exec -it pcfix-api npx prisma migrate dev --name your_migration_name

Environment Variables Explained

Database Connection

DATABASE_URL="postgresql://admin:password123@postgres:5432/pcfix_db?schema=public"

• Uses postgres hostname (Docker service name)
• Default credentials match docker-compose.yml
• schema=public specifies Prisma schema

JWT Configuration

JWT_SECRET="your-secret-key"
JWT_REFRESH_SECRET="your-refresh-secret"
JWT_EXPIRES_IN="15m"
JWT_REFRESH_EXPIRES_IN="7d"

• Access tokens expire in 15 minutes
• Refresh tokens last 7 days
• Change secrets in production!

API URLs (Web Package)

PUBLIC_API_URL="http://localhost:3001/api"  # Client-side
SSR_API_URL="http://api:3001/api"          # Server-side (SSR)

• PUBLIC_API_URL: Used by client-side React components
• SSR_API_URL: Used by Astro SSR pages (uses Docker network)

Optional External Services

For full functionality, configure these optional services:

• Cloudinary: Image upload and CDN
• MercadoPago: Payment processing
• Google OAuth: Social login
• Resend: Transactional emails
• Sentry: Error monitoring

The app will work without these, but some features will be disabled.

Troubleshooting

Port already in use

If you see errors about ports 3001, 4321, or 5432 being in use:

# Find what's using the port
lsof -i :3001

# Kill the process or change ports in docker-compose.yml

Database connection errors

Ensure PostgreSQL container is healthy:

docker-compose ps
docker-compose logs postgres

If needed, reset the database:

docker-compose down -v
docker-compose up --build

Module not found errors

Rebuild the containers to reinstall dependencies:

docker-compose down
docker-compose up --build

Prisma migration errors

Reset Prisma migrations:

docker exec -it pcfix-api npx prisma migrate reset
docker exec -it pcfix-api npx prisma migrate deploy

Next Steps

Now that you have PC Fix running locally:

Explore the Codebase

• Frontend: packages/web/src/
• Backend: packages/api/src/
• Database: packages/api/prisma/schema.prisma

Read Full Installation Guide

Learn about manual setup without Docker and advanced configuration

Configure External Services

Set up Cloudinary, MercadoPago, and other integrations

Run Tests

docker exec -it pcfix-api npm test
docker exec -it pcfix-web npm test