Getting Started - NutriFit

Prerequisites

Before installing NutriFit, ensure your development environment meets these requirements:

Required Software

PHP 8.2+

Modern PHP version with required extensions

Composer 2.x

PHP dependency manager

Node.js 18+

JavaScript runtime for asset compilation

Git

Version control system

Required PHP Extensions

Verify you have these PHP extensions enabled:

php -m | grep -E '(pdo|mbstring|tokenizer|xml|ctype|json|bcmath|fileinfo)'

Required extensions:

pdo_sqlite (or pdo_mysql for production)
mbstring
tokenizer
xml
ctype
json
bcmath
fileinfo

If any required extensions are missing, install them via your system’s package manager before proceeding.

Optional Software

MySQL 8.0+: For production database (SQLite used in development)
Docker: For Laravel Sail containerized environment
Mailtrap Account: For testing email notifications (free)

Installation

Quick Start (Recommended)

The fastest way to get NutriFit running:

Clone the Repository

git clone https://github.com/Rubenpro19/NutriFit.git
cd Nutrifit

Run Automated Setup

composer run setup

This single command handles:

✅ PHP dependency installation
✅ Environment configuration
✅ Application key generation
✅ Database creation and migration
✅ Node.js dependency installation
✅ Frontend asset compilation

The setup script is defined in composer.json:47-53 and automates the entire installation process.

Seed the Database

php artisan db:seed

This step is required to create the administrator account. Without seeding, you won’t be able to log in.

Start the Application

composer run dev

This starts all required services in parallel:

🟦 Laravel server on http://localhost:8000
🟪 Queue worker for email notifications
🟧 Vite dev server with hot module replacement

See composer.json:55-58 for the dev script configuration.

Your application is now running at http://localhost:8000

Manual Installation (Step-by-Step)

If you prefer granular control over the installation process:

Clone Repository

git clone https://github.com/Rubenpro19/NutriFit.git
cd Nutrifit

Install PHP Dependencies

composer install

This installs Laravel 12, Livewire 3, Fortify, DomPDF, and all backend dependencies (see composer.json:11-20).

Configure Environment

cp .env.example .env

This creates your environment configuration file from the template.

Generate Application Key

php artisan key:generate

Laravel requires a unique encryption key for security.

Create Database

For SQLite (development):

touch database/database.sqlite

For MySQL (production), create the database manually:

mysql -u root -p -e "CREATE DATABASE nutrifit;"

Run Database Migrations

php artisan migrate

This creates all necessary database tables.

Seed Administrator Account

php artisan db:seed

Critical: This creates the administrator account needed for first login.

Install Node Dependencies

npm install

Installs Vite, Tailwind CSS 4, and frontend dependencies (see package.json:8-16).

Compile Frontend Assets

For development:

npm run dev

For production:

npm run build

Environment Configuration

Edit your .env file to customize the application:

Basic Configuration

APP_NAME="NutriFit"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000
APP_LOCALE=es
APP_FALLBACK_LOCALE=es

The application is built for Spanish-speaking markets. Change APP_LOCALE if needed.

Database Configuration

SQLite (Development - Default)

DB_CONNECTION=sqlite

SQLite requires no additional configuration and is perfect for development.

MySQL (Production)

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nutrifit
DB_USERNAME=root
DB_PASSWORD=your_secure_password

Queue Configuration

QUEUE_CONNECTION=database

NutriFit uses database-driven queues for email notifications. The queue worker must be running to send emails.

Email Configuration

Development (Mailtrap)

For testing without sending real emails:

MAIL_MAILER=smtp
MAIL_HOST=sandbox.smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_mailtrap_username
MAIL_PASSWORD=your_mailtrap_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Production (Real SMTP)

MAIL_MAILER=smtp
MAIL_HOST=smtp.your-provider.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Admin Password Configuration

ADMIN_PASSWORD=your_custom_password

If not set, the default password is NutriAdmin123.

Running the Application

Development Mode (All Services)

The easiest way to run all required services:

composer run dev

This command starts three processes in parallel (see composer.json:55-58):

Web Server

Laravel on port 8000

Queue Worker

Processes email notifications

Vite Server

Hot module replacement for frontend

Manual Multi-Terminal Setup

If you prefer separate terminal windows for each service:

Terminal 1: Web Server
Terminal 2: Queue Worker
Terminal 3: Vite (Dev)

php artisan serve

Access at: http://localhost:8000

php artisan queue:work

Required for email notifications

npm run dev

Hot module replacement for development

Production Mode

For production deployment:

Build Assets

npm run build

Compiles and optimizes frontend assets

Optimize Application

composer install --optimize-autoloader --no-dev
php artisan config:cache
php artisan route:cache
php artisan view:cache

Start Server

php artisan serve

Or configure Nginx/Apache as your web server

Run Queue Worker as Service

Configure Supervisor to keep queue worker running:

[program:nutrifit-worker]
command=php /path/to/nutrifit/artisan queue:work --timeout=120
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/nutrifit-worker.log

Administrator Access

After seeding the database, log in with the administrator account:

Administrator Credentials

Email: [email protected]
Password: NutriAdmin123 (or your custom ADMIN_PASSWORD from .env)

Navigate to Login

Open http://localhost:8000 and click “Login”

Enter Admin Credentials

Use the email and password shown above

Access Admin Dashboard

You’ll be redirected to /administrador/dashboard

Create Additional Users

Navigate to “Users” → “Create User” to add nutritionists and patients

Creating Test Users

From the admin dashboard, create test users for each role:

Create Nutritionist
Create Patient

Go to /administrador/users/create
Fill in user details
Select role: Nutricionista
Set initial password
User receives welcome email

Go to /administrador/users/create
Fill in user details
Select role: Paciente
Set temporary password
Patient must change password on first login (routes/web.php:132-133)

Role-Based Dashboards

Each role has a dedicated dashboard:

Role	Dashboard URL	Features
Administrator	`/administrador/dashboard`	User management, system oversight, analytics
Nutritionist	`/nutricionista/dashboard`	Schedule management, patient records, appointments
Patient	`/paciente/dashboard`	Appointment booking, history viewing, profile management

Verification & Testing

Verify Installation

Check Web Server

Visit http://localhost:8000 - you should see the landing page

Test Login

Check Queue Worker

Look for “Processing: …” messages in the queue worker terminal

Test Notifications

Create a test user - check Mailtrap for welcome email

Run Test Suite

NutriFit includes Pest tests (composer.json:28):

# Run all tests
composer test

# Run with coverage report
php artisan test --coverage

# Run specific test file
php artisan test --filter=UserTest

Common Issues

Database Connection Error

Problem: Can’t connect to databaseSolutions:

For SQLite: Ensure database/database.sqlite file exists and is writable
For MySQL: Verify credentials in .env and database exists
Run: php artisan config:clear to clear cached config

Queue Not Processing

Problem: Emails not sendingSolutions:

Ensure queue worker is running: php artisan queue:work
Check QUEUE_CONNECTION=database in .env
View failed jobs: php artisan queue:failed
Retry failed jobs: php artisan queue:retry all

Assets Not Loading

Problem: Styles or JavaScript not workingSolutions:

Ensure Vite dev server is running: npm run dev
For production: Run npm run build first
Clear browser cache
Check public/build directory exists and contains files

Fortify Routes Not Found

Problem: Login/register routes give 404Solutions:

Clear route cache: php artisan route:clear
Verify Fortify is installed: composer show laravel/fortify
Check config/fortify.php exists
Run: php artisan optimize:clear

Next Steps

Now that NutriFit is running:

Explore Features

Learn about all available capabilities

Configure Schedules

Set up nutritionist availability schedules

Customize Settings

Configure system settings and branding

Deploy to Production

See deployment guides for going live

Development Workflow

Daily Development

Your typical development session:

# Start all services
composer run dev

# Make changes to code
# Browser automatically reloads via Vite HMR

# Run tests before committing
composer test

# Fix code style
./vendor/bin/pint

Adding Features

Create Migration

php artisan make:migration create_your_table
php artisan migrate

Create Model

php artisan make:model YourModel

Create Livewire Component

php artisan make:livewire YourComponent

Add Routes

Edit routes/web.php to add your routes

Write Tests

php artisan make:test YourFeatureTest
composer test

Scheduled Tasks

NutriFit includes a command for appointment reminders:

# Send 24-hour reminders manually
php artisan appointments:send-reminders

To automate, add to crontab:

* * * * * cd /path/to/nutrifit && php artisan schedule:run >> /dev/null 2>&1

The scheduler automatically runs the reminder command daily at the configured time.

Additional Resources

Laravel Documentation

Official Laravel 12 documentation

Livewire Documentation

Learn about Livewire components

Tailwind CSS

Tailwind CSS utility reference

Fortify Documentation

Authentication features

Need Help? Check the project’s GitHub repository for issues and discussions: NutriFit on GitHub

Overview

Installation

Core Features

User Guides

Architecture

​Prerequisites

​Required Software

PHP 8.2+

Composer 2.x

Node.js 18+

Git

​Required PHP Extensions

​Optional Software

​Installation

​Quick Start (Recommended)

​Manual Installation (Step-by-Step)

​Environment Configuration

​Basic Configuration

​Database Configuration

​SQLite (Development - Default)

​MySQL (Production)

​Queue Configuration

​Email Configuration

​Development (Mailtrap)

​Production (Real SMTP)

​Admin Password Configuration

​Running the Application

​Development Mode (All Services)

Web Server

Queue Worker

Vite Server

​Manual Multi-Terminal Setup

​Production Mode

​First Login

​Administrator Access

Administrator Credentials

​Creating Test Users

​Role-Based Dashboards

​Verification & Testing

​Verify Installation

​Run Test Suite

​Common Issues

​Next Steps

Explore Features

Configure Schedules

Customize Settings

Deploy to Production

​Development Workflow

​Daily Development

​Adding Features

​Scheduled Tasks

​Additional Resources

Laravel Documentation

Livewire Documentation

Tailwind CSS

Fortify Documentation

Build docs developers (and LLMs) love

Prerequisites

Required Software

Required PHP Extensions

Optional Software

Installation

Quick Start (Recommended)

Manual Installation (Step-by-Step)

Environment Configuration

Basic Configuration

Database Configuration

SQLite (Development - Default)

MySQL (Production)

Queue Configuration

Email Configuration

Development (Mailtrap)

Production (Real SMTP)

Admin Password Configuration

Running the Application

Development Mode (All Services)

Manual Multi-Terminal Setup

Production Mode

First Login

Administrator Access

Creating Test Users

Role-Based Dashboards

Verification & Testing

Verify Installation

Run Test Suite

Common Issues

Next Steps

Development Workflow

Daily Development

Adding Features

Scheduled Tasks

Additional Resources