Skip to main content

​
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:
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: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-postgresPort: 5432Credentials:
  • User: admin
  • Password: password123
  • Database: pcfix_db
Persistent volume: postgres_data

Express API

Container: pcfix-apiPort: 3001Features:
  • Hot reload with nodemon
  • Auto-runs migrations on start
  • Volume-mounted source code

Astro Web Frontend

Container: pcfix-webPort: 4321Features:
  • 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_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_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!
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)
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

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
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
Rebuild the containers to reinstall dependencies:
docker-compose down
docker-compose up --build
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

Build docs developers (and LLMs) love

Get started for freeTalk to us