Quick Start Guide

Get PaparcApp running locally in 5 minutes with this step-by-step guide

Quick Start Guide

Get PaparcApp up and running on your local machine in just a few minutes. This guide walks you through cloning the repository, installing dependencies, configuring the database, and starting the development server.

Prerequisites: Make sure you have Node.js 18+ and PostgreSQL 14+ installed before proceeding.

Step-by-Step Setup

1. Clone the Repository

   Clone the PaparcApp source code to your local machine:

   git clone https://github.com/rafakata/PaparcApp.git
   cd PaparcApp/proyecto
   

   The main application code is located in the proyecto/ directory.

2. Install Dependencies

   Install all required npm packages:

   npm install
   

   This will install:

   • express (4.21.2) - Web framework
   • pg (8.17.2) - PostgreSQL driver
   • bcrypt (6.0.0) - Password hashing
   • ejs (3.1.10) - Template engine
   • express-session (1.18.2) - Session management
   • firebase (12.9.0) - Social authentication
   • axios (1.13.4) - HTTP client for notifications
   • And more…

   View all dependencies

   package.json dependencies

   {
     "axios": "^1.13.4",
     "bcrypt": "^6.0.0",
     "cookie-parser": "~1.4.4",
     "debug": "~2.6.9",
     "dotenv": "^17.2.3",
     "ejs": "^3.1.10",
     "express": "^4.21.2",
     "express-session": "^1.18.2",
     "firebase": "^12.9.0",
     "http-errors": "~1.6.3",
     "morgan": "^1.10.1",
     "pg": "^8.17.2"
   }
   
3. Configure Environment Variables

   Create a .env file from the example template:

   cp .env.example .env
   

   Edit the .env file with your local configuration:

   .env

   # Server Configuration
   PORT=3000
   NODE_ENV=development
   
   # Session Secret (generate a secure random string)
   SESSION_SECRET=your_secure_random_string_here
   
   # PostgreSQL Local Connection
   DB_USER=postgres
   DB_PASSWORD=your_postgres_password
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=paparcapp_db
   

   Security: Never commit your .env file to version control. The .env.example is provided as a template only.

   Generate a secure SESSION_SECRET

   You can generate a secure random string using Node.js:

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   

   Or use any password generator with at least 32 characters.

4. Set Up the Database

   Create the PostgreSQL database and load the schema:

   Create Database

   # Connect to PostgreSQL
   psql -U postgres
   
   # Create the database
   CREATE DATABASE paparcapp_db;
   
   # Exit psql
   \q
   

   What each file does:

   File	Purpose
   01_tables.sql	Creates all 13 tables (customer, vehicle, reservation, etc.)
   02_constraints.sql	Adds foreign keys and CHECK constraints (business rules)
   03_indexes.sql	Creates 9 performance indexes for common queries
   04_initial_data.sql	Loads initial data: pricing tiers, services, test customers

   The initial data includes a complete test scenario with sample customers, vehicles, reservations, and the full pricing catalog.

5. Start the Development Server

   Launch the application with hot-reload enabled:

   npm run dev
   

   You should see output similar to:

   [nodemon] starting `node ./bin/www`
   ✓ Pricing cache initialized successfully
   Server listening on port 3000
   

   If you see “Error initializing pricing cache”, check that:

   • Your database connection settings are correct
   • The initial data script ran successfully
   • PostgreSQL is running
6. Access the Application

   Open your browser and navigate to:

   Local URL: http://localhost:3000

   You should see the PaparcApp landing page with:

   • Hero section with booking date selectors
   • Three service tiers (ECO, TRANSFER, MEET)
   • FAQ accordion
   • Navigation to services, pricing, and login pages

Testing the Application

Once the server is running, try these workflows:

Public Booking Flow

1. Navigate to Booking

   Click “Book Now” or go to http://localhost:3000/booking

2. Select Dates

   Choose entry and exit dates (must be future dates)

3. Enter Vehicle Details

   • License plate: TEST1234
   • Brand: Toyota
   • Model: Corolla
   • Color: Blue
   • Type: TURISMO (car)
4. Enter Personal Info

   • Name: Test Customer
   • Phone: [phone]
   • Email: [e-mail]
5. Choose Services

   • Select a main service (ECO recommended for testing)
   • Optionally add additional services
   • Watch the price update in real-time
6. Confirm Booking

   Review the summary and click “Confirm Reservation”

Admin Dashboard Access

1. Navigate to Login

   Go to http://localhost:3000/users/login

2. Switch to Worker Mode

   Click the “Trabajador” (Worker) tab at the top of the login form

3. Use Test Admin Credentials

   Check your 04_initial_data.sql file for admin credentials, or create an admin user:

   INSERT INTO customer (full_name, email, phone, password_hash, type, is_active)
   VALUES (
     'Admin User',
     '[e-mail]',
     '[phone]',
     '$2b$10$YourBcryptHashHere',  -- Use bcrypt to hash 'admin123'
     'ADMIN',
     true
   );
   

   Generate bcrypt hash for password

   const bcrypt = require('bcrypt');
   bcrypt.hash('admin123', 10, (err, hash) => {
     console.log(hash);
   });
   
4. Explore Dashboard

   Once logged in, you’ll see:

   • Calendar with color-coded reservations
   • Daily entries and exits tables
   • Statistics (total entries/exits)
   • Quick access to reservation details

Available NPM Scripts

Script	Command	Description
Production	npm start	Starts server with Node.js (no hot-reload)
Development	npm run dev	Starts with Nodemon (auto-restart on changes)
Tests	npm test	Runs Jest test suite for pricing service

Production Mode

npm start
# Use this for production deployments

Verify Installation

To confirm everything is working correctly:

Check Database Connection

psql -U postgres -d paparcapp_db -c "SELECT COUNT(*) FROM customer;"

Should return the number of customers loaded from initial data.

Check Pricing Cache

When you start the server, look for:

✓ Pricing cache initialized successfully

This means the pricing service loaded all vehicle coefficients and service rates into memory.

Test API Endpoint

curl -X POST http://localhost:3000/api/pricing/dynamic \
  -H "Content-Type: application/json" \
  -d '{
    "entry_date": "2026-04-01T10:00:00",
    "exit_date": "2026-04-08T10:00:00",
    "vehicle_type": "TURISMO",
    "id_main_service": 1,
    "id_additional_services": []
  }'

Expected response:

{
  "success": true,
  "data": {
    "total_price": 56.00
  }
}

Run Test Suite

npm test

All tests should pass:

PASS  tests/pricingService.test.js
  ✓ Calculates same-day booking (1 day minimum)
  ✓ Applies correct tier for multi-day stay
  ✓ Multiplies by vehicle coefficient
  ✓ Adds additional services to total
  ✓ Handles invalid vehicle type
  ✓ Respects 2-hour courtesy period
  ✓ Charges extra day after courtesy period

Troubleshooting

Error: connect ECONNREFUSED

Problem: Cannot connect to PostgreSQL database.

Solutions:

• Check PostgreSQL is running: sudo service postgresql status
• Verify connection settings in .env match your PostgreSQL config
• Test connection: psql -U postgres -d paparcapp_db -c "SELECT 1;"

Error: Pricing cache initialization failed

Problem: Cannot load pricing data from database.

Solutions:

• Ensure 04_initial_data.sql was executed successfully
• Check tables exist: psql -U postgres -d paparcapp_db -c "\dt"
• Verify data loaded: SELECT * FROM vehicle_coefficient;
• Restart the server after fixing database issues

Port 3000 already in use

Problem: Another process is using port 3000.

Solutions:

• Change the port in .env: PORT=3001
• Kill the process: lsof -ti:3000 | xargs kill
• Use a different port temporarily: PORT=3001 npm run dev

Session not persisting

Problem: Login doesn’t work or session expires immediately.

Solutions:

• Check SESSION_SECRET is set in .env
• Clear browser cookies and try again
• Verify express-session is installed: npm ls express-session

Next Steps

Detailed Installation

Learn about prerequisites, environment configuration, and deployment options

API Reference

Explore the REST API endpoints for pricing and reservations

Database Schema

Understand the 13-table architecture and relationships

Architecture Guide

Deep dive into the MVC pattern and service layers

---

Need Help? Check the detailed Installation Guide for more configuration options and troubleshooting tips.