Quick Start Guide

Get Refugio up and running in minutes with this step-by-step guide

Quick Start Guide

This guide will help you get Refugio running on your local machine in just a few minutes. Perfect for development, testing, or evaluation purposes.

This quick start uses PostgreSQL. For MySQL setup or production deployment, see the Installation Guide.

Prerequisites

Before you begin, ensure you have:

• PHP 7.4 or higher
• PostgreSQL 12+ (or MySQL 5.7+)
• Git (for cloning the repository)
• A terminal/command prompt

Installation Steps

1. Clone the Repository

   Clone the Refugio repository to your local machine:

   git clone https://github.com/yourusername/refugio.git
   cd refugio
   

   Replace the repository URL with your actual Refugio repository location.

2. Set Up the Database

   Create a new PostgreSQL database:

   Windows (PowerShell)

   psql -U postgres
   CREATE DATABASE refugio;
   \q
   

   Create the database schema. Refer to the Database Schema documentation for complete table definitions.

   # If you have the SQL file, import it:
   psql -U postgres -d refugio -f sql/refugio.sql
   
   # Otherwise, create tables manually using the schema documentation
   

   The schema includes sample data with test users ([e-mail]/admin123) and room configurations.

3. Configure Database Connection

   Create a conexion.php file in the project root (this file is gitignored for security):

   conexion.php

   <?php
   session_start();
   
   // PostgreSQL Configuration
   $host = 'localhost';
   $port = '5432';
   $dbname = 'refugio';
   $user = 'postgres';
   $password = 'your_postgres_password';
   
   try {
       $dsn = "pgsql:host=$host;port=$port;dbname=$dbname";
       $conexionPDO = new PDO($dsn, $user, $password, [
           PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
           PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
           PDO::ATTR_EMULATE_PREPARES => false,
       ]);
   } catch (PDOException $e) {
       die("Error de conexión: " . $e->getMessage());
   }
   ?>
   

   Replace your_postgres_password with your actual PostgreSQL password.

4. Start the Development Server

   Start PHP’s built-in web server:

   php -S localhost:8000
   

   You should see output similar to:

   PHP 7.4.33 Development Server (http://localhost:8000) started
   
5. Access the Application

   Open your web browser and navigate to:

   http://localhost:8000
   

   You’ll be redirected to the login page automatically.

First Login

Use one of the default test accounts to log in:

Admin Account

Login with administrator privileges:

• Email: [e-mail]
• Password: admin123

As an admin, you can:

• Manage users (create, edit, delete)
• Approve or reject reservations
• View all bookings and statistics
• Configure rooms and beds

User Account

Login as a regular member:

• Email: [e-mail]
• Password: user123

As a user, you can:

• View the availability calendar
• Make new reservations
• Add companions to bookings
• View and cancel your reservations

Important: Change these default passwords immediately! Use the admin panel to update passwords or see the security section below.

Exploring the Admin Panel

After logging in as admin, you’ll see the dashboard (viewAdmin.php):

Dashboard Overview

The admin dashboard displays:

• Statistics Cards: Total users, pending reservations, occupancy rates
• Navigation Tabs:
  • Dashboard - Overview and metrics
  • Users - User management (CRUD operations)
  • Reservations - Pending approval queue
  • Rooms - Room and bed status

Managing Users

Navigate to the Users tab to:

Create User Example (viewAdmin.php:27)

case 'crear_usuario':
    $datos = [
        'num_socio' => sanitize_input($_POST['num_socio']),
        'dni'       => sanitize_input($_POST['dni']),
        'telf'      => sanitize_input($_POST['telf']),
        'email'     => sanitize_input($_POST['email']),
        'nombre'    => sanitize_input($_POST['nombre']),
        'apellido1' => sanitize_input($_POST['apellido1']),
        'apellido2' => sanitize_input($_POST['apellido2']),
        'password'  => $_POST['password'],
        'rol'       => sanitize_input($_POST['rol']),
    ];

    if (crear_usuario($conexionPDO, $datos)) {
        $mensaje = "Usuario creado exitosamente";
    }

1. Click “Add New User”
2. Fill in the user details (name, email, member number, etc.)
3. Assign a role (admin or user)
4. Set initial password
5. Save the user

Approving Reservations

Reservations require admin approval:

1. Go to the Reservations tab
2. Review pending reservations
3. Click “Approve” or “Reject”
4. Users are notified of the status change

Exploring the User Panel

Log in as a user to see the member interface (viewSocio.php):

Making a Reservation

1. Select Dates

   Use the interactive calendar to:

   • View available beds per day
   • See color-coded availability indicators
   • Click on a date range for booking
2. Choose Room and Beds

   Select your room and number of beds:

   Dynamic Bed Selection (viewSocio.php:50)

   $datos_reserva = [
       'id_usuario'    => $_SESSION['userId'],
       'id_habitacion' => isset($_POST['id_habitacion']) ? (int) $_POST['id_habitacion'] : 0,
       'numero_camas'  => $numero_camas,
       'fecha_inicio'  => $_POST['fecha_inicio'] ?? '',
       'fecha_fin'     => $_POST['fecha_fin'] ?? '',
   ];
   
   $id_reserva = crear_reserva($conexionPDO, $datos_reserva);
   

   The system dynamically shows available beds for your selected dates.

3. Add Companions (Optional)

   If booking multiple beds, add companion information:

   • Member number (if companion is a member)
   • Full name
   • ID/DNI number
   • Mark if they’re a club member

   Companion Management (viewSocio.php:63)

   foreach ($acompanantes as $acomp) {
       if (!empty($acomp['dni'])) {
           $datos_acomp = [
               'num_socio' => $acomp['num_socio'] ?? null,
               'es_socio'  => isset($acomp['es_socio']) && $acomp['es_socio'] === 'si',
               'dni'       => $acomp['dni'] ?? '',
               'nombre'    => $acomp['nombre'] ?? '',
               'apellido1' => $acomp['apellido1'] ?? '',
               'apellido2' => $acomp['apellido2'] ?? null,
               'actividad' => $_POST['actividad'] ?? null,
           ];
           agregar_acompanante($conexionPDO, $id_reserva, $datos_acomp);
       }
   }
   
4. Submit for Approval

   Submit your reservation:

   • Add activity description (optional)
   • Include any special comments
   • Submit for admin approval

   You’ll receive a confirmation message. Check “My Reservations” to track status.

Verification

To verify your installation is working correctly:

Using the Verification Script

Run the included verification script:

php verificar_mysql.php

This checks:

• Database connectivity
• Table structure
• Test data presence
• PDO functionality

Manual Verification

Check Database Tables

Connect to your database and verify tables exist:

\c refugio
\dt

You should see:

• usuarios
• habitaciones
• camas
• reservas
• acompanantes

Test User Authentication

The login system uses secure password verification:

Login Authentication (login.php:16)

$user = comprobar_username($conexionPDO, $email);

if ($user && password_verify($password, $user['password'])) {
    session_regenerate_id(true);
    $_SESSION['userId'] = $user['id'];
    $_SESSION['user']   = htmlspecialchars($user['nombre'] . ' ' . $user['apellido1']);
    $_SESSION['email']  = htmlspecialchars($email);
    $_SESSION['rol']    = $user['rol'];

    // Redirect based on role
    if ($user['rol'] === 'user') {
        header('Location: viewSocio.php');
    } else if ($user['rol'] === 'admin') {
        header('Location: viewAdmin.php');
    }
    exit;
}

Common Quick Start Issues

Database Connection Failed

Error: SQLSTATE[08006] Connection failed

Solution:

• Verify PostgreSQL is running: pg_isready
• Check credentials in conexion.php
• Ensure database refugio exists
• Verify PostgreSQL is listening on localhost:5432

Login Fails with Correct Credentials

Error: Credentials invalid message

Solution:

• Ensure database was imported correctly
• Check if password hashing is working
• Verify PHP PDO extension is enabled
• Run: php -m | grep pdo

Session/Cookie Warnings

Error: Headers already sent warnings

Solution:

• Ensure no output before session_start() in conexion.php
• Check for BOM in PHP files
• Verify no whitespace before <?php tags

Port 8000 Already in Use

Error: Address already in use

Solution: Use a different port:

php -S localhost:8080

Then access at http://localhost:8080

Security Checklist

Before using in production:

Change all default passwords

Update conexion.php with strong database credentials

Enable HTTPS (required for production)

Review and update session cookie settings

Set appropriate file permissions (644 for PHP files)

Remove or secure verificar_mysql.php

Configure error logging (disable display_errors)

Next Steps

Now that you have Refugio running:

Production Installation

Deploy Refugio to a production server with proper security

Configuration Guide

Customize settings, email notifications, and more

API Reference

Learn about the available functions and endpoints

Troubleshooting

Solutions to common issues and error messages

---

Congratulations! Your Refugio installation is ready. Start exploring the features and customize it for your mountain refuge. 🏔️