Installation Guide

This guide walks you through setting up the Pet Service Management System on your local development environment.

Prerequisites: Node.js 18+, PostgreSQL 12+, Git

Quick Start

1. Clone the Repository

git clone <repository-url>
cd pet-service

2. Install Dependencies

Backend
Frontend

cd backend
npm install

cd frontend
npm install

Backend Setup

Step 1: Environment Configuration

Create a .env file in the backend/ directory:

.env

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/petservice

# Application
NODE_ENV=development
PORT=3001

# Better Auth Configuration
BETTER_AUTH_URL=http://localhost:3001/api/auth
BETTER_AUTH_SECRET=your-better-auth-secret-here-min-32-chars
SESSION_SECRET=your-session-secret-here-min-32-chars
JWT_SECRET=your-jwt-secret-here-min-32-chars

# CORS
FRONTEND_URL=http://localhost:3000

# Email (Optional for development)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASS=your-email-password

Security: Use strong, unique secrets for production. Generate with:

openssl rand -base64 32

Step 2: Database Setup

Create PostgreSQL Database

# Using psql
psql -U postgres
CREATE DATABASE petservice;
\q

Generate Prisma Client

cd backend
npm run prisma:generate

Apply Database Schema

npm run prisma:db:push

This creates all tables, indexes, and constraints defined in prisma/schema.prisma.

Verify Database

npm run prisma:studio

Opens Prisma Studio at http://localhost:5555 to inspect your database.

Step 3: Seed Database (Optional)

Seeding creates sample data for development and testing.

cd backend
npm run prisma:db:seed

Seed Data Includes:

Admin user (email: admin@example.com, password: admin123)
Manager user (email: manager@example.com, password: manager123)
Staff user (email: staff@example.com, password: staff123)
Customer users
6 service categories (Boarding, Grooming, Veterinary, Training, Daycare, Transport)
Sample pets
Sample bookings

Step 4: Start Backend Server

cd backend
npm run start:dev

Backend running at http://localhost:3001

Verify Backend:

curl http://localhost:3001/health
# Expected: {"status":"ok","timestamp":"..."}

Frontend Setup

Step 1: Environment Configuration

Create a .env.local file in the frontend/ directory:

.env.local

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3001

# Application URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Better Auth (if using OAuth)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Step 2: Start Frontend Server

cd frontend
npm run dev

Frontend running at http://localhost:3000

Test the Application:

Open http://localhost:3000 in your browser
Navigate to /en or /vi for localized content
Try logging in with seeded credentials

Database Management

Common Commands

cd backend
npm run prisma:generate

npm run prisma:db:push

npm run prisma:migrate dev --name migration_name

npm run prisma:migrate reset
# ⚠️ Warning: This deletes all data

npm run prisma:studio
# Opens at http://localhost:5555

npm run prisma:db:seed

Database Schema

The database includes the following main entities:

User & Authentication

User: Core user accounts with roles (ADMIN, MANAGER, STAFF, CUSTOMER)
Session: Active user sessions
Account: OAuth provider accounts
Verification: Email verification tokens

Booking System

Booking: Main booking records with status tracking
BookingPet: Junction table linking bookings to pets
BookingService: Junction table linking bookings to services with pricing

Pet Management

Pet: Pet profiles with medical history, vaccinations, allergies
Supports multiple images
JSON-based vaccination records

Service & Staff

Service: Service catalog with JSONB multi-language fields
Staff: Employee profiles with working hours and specializations
StaffService: Junction table with proficiency levels

System

Setting: Key-value configuration store with JSONB values
AuditLog: Complete audit trail of user actions

Environment Variables Reference

Backend Environment Variables

Variable	Required	Description	Example
`DATABASE_URL`	✅	PostgreSQL connection string	`postgresql://user:pass@localhost:5432/db`
`NODE_ENV`	✅	Environment mode	`development`, `production`
`PORT`	✅	Backend server port	`3001`
`BETTER_AUTH_URL`	✅	Better Auth endpoint	`http://localhost:3001/api/auth`
`BETTER_AUTH_SECRET`	✅	Better Auth secret (32+ chars)	Generated string
`SESSION_SECRET`	✅	Session encryption secret	Generated string
`JWT_SECRET`	✅	JWT signing secret	Generated string
`FRONTEND_URL`	✅	Frontend URL for CORS	`http://localhost:3000`
`SMTP_HOST`	❌	Email server host	`smtp.gmail.com`
`SMTP_PORT`	❌	Email server port	`587`
`SMTP_USER`	❌	Email username	`noreply@example.com`
`SMTP_PASS`	❌	Email password	Your password

Frontend Environment Variables

Variable	Required	Description	Example
`NEXT_PUBLIC_API_URL`	✅	Backend API URL	`http://localhost:3001`
`NEXT_PUBLIC_APP_URL`	✅	Frontend app URL	`http://localhost:3000`
`GOOGLE_CLIENT_ID`	❌	Google OAuth client ID	From Google Console
`GOOGLE_CLIENT_SECRET`	❌	Google OAuth secret	From Google Console
`GITHUB_CLIENT_ID`	❌	GitHub OAuth client ID	From GitHub Settings
`GITHUB_CLIENT_SECRET`	❌	GitHub OAuth secret	From GitHub Settings

Code Quality & Testing

Linting & Formatting

cd backend
npm run lint          # ESLint check
npm run format        # Prettier format

cd frontend
npm run lint          # ESLint check

Type Checking

# Backend
cd backend
tsc --noEmit

# Frontend
cd frontend
tsc --noEmit

Running Tests

Backend
Frontend

cd backend

# Unit tests
npm run test

# Watch mode
npm run test:watch

# Coverage report
npm run test:cov

# E2E tests
npm run test:e2e

cd frontend

# Lint check
npm run lint

Troubleshooting

Database Connection Error

Problem: connect ECONNREFUSED 127.0.0.1:5432Solution:

Ensure PostgreSQL is running: brew services start postgresql (macOS)
Check DATABASE_URL in .env
Verify credentials: psql -U postgres
Check PostgreSQL logs: tail -f /usr/local/var/log/postgres.log

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::3000Solution:

# Kill process on port (macOS/Linux)
lsof -ti:3000 | xargs kill -9

# Or use different port
PORT=3002 npm run dev

Missing Environment Variables

Problem: Application crashes with undefined env variablesSolution:

Copy example env files to .env / .env.local
Ensure all required variables are set
Restart development server

Prisma Client Not Generated

Problem: PrismaClient not foundSolution:

cd backend
npm run prisma:generate

Module Not Found

Problem: Cannot find module 'xxx'Solution:

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Next Steps

Architecture Overview

Understand system design and data flow

Deployment Guide

Deploy to production with Docker or Railway

API Reference

Explore REST API endpoints

Back to Home

Return to homepage

Need Help? Check Troubleshooting or reach out to support@petservice.example.com

​Installation Guide

​Quick Start

​1. Clone the Repository

​2. Install Dependencies

​Backend Setup

​Step 1: Environment Configuration

​Step 2: Database Setup

​Step 3: Seed Database (Optional)

​Step 4: Start Backend Server

​Frontend Setup

​Step 1: Environment Configuration

​Step 2: Start Frontend Server

​Database Management

​Common Commands

​Database Schema

​Environment Variables Reference

​Backend Environment Variables

​Frontend Environment Variables

​Code Quality & Testing

​Linting & Formatting

​Type Checking

​Running Tests

​Troubleshooting

​Next Steps

Architecture Overview

Deployment Guide

API Reference

Back to Home

Installation Guide

Quick Start

1. Clone the Repository

2. Install Dependencies

Backend Setup

Step 1: Environment Configuration

Step 2: Database Setup

Step 3: Seed Database (Optional)

Step 4: Start Backend Server

Frontend Setup

Step 1: Environment Configuration

Step 2: Start Frontend Server

Database Management

Common Commands

Database Schema

Environment Variables Reference

Backend Environment Variables

Frontend Environment Variables

Code Quality & Testing

Linting & Formatting

Type Checking

Running Tests

Troubleshooting

Next Steps