Development Setup - GB App - Power BI Report Manager

Prerequisites

Before setting up GB App for development, ensure you have the following installed:

Docker

Docker Desktop 4.0+ with Docker Compose

Git

Git 2.30+ for version control

Node.js

Node.js 18.16 LTS or higher

Composer

Composer 2.0+ (if not using Docker)

Quick Start with Docker

The fastest way to get started is using Docker:

Clone the repository

git clone https://github.com/xDanielDC/Reportes-Senco.git
cd Reportes-Senco

Copy environment file

cp .env.example .env

Edit .env to configure your local database and Power BI credentials. See Environment Configuration for details.

Build Docker containers

docker compose build

This builds the application container with PHP 8.2, Nginx, Supervisor, and Node.js.

Start containers

docker compose up -d

Starts the application and database containers in detached mode.

Set file permissions

docker compose exec app chmod -R 775 storage bootstrap/cache
docker compose exec app chown -R www-data:www-data storage bootstrap/cache

Ensures Laravel can write to required directories.

Install PHP dependencies

docker compose exec app composer install

Install Node.js dependencies

docker compose exec app npm install

Generate application key

docker compose exec app php artisan key:generate

Run migrations and seeders

docker compose exec app php artisan migrate --seed

The seeder creates a super admin user with default credentials displayed in the console.

Build frontend assets

For development with hot reload:

docker compose exec app npm run dev

Or build for production:

docker compose exec app npm run build

Access the application

Open your browser to http://localhost (or the port configured in docker-compose.yml).

Native Development Setup

If you prefer to run without Docker:

System Requirements

PHP 8.1 or higher
MySQL 8.0 or SQL Server
Node.js 18.16 LTS
Composer 2.0+
Nginx or Apache

Clone repository

git clone https://github.com/xDanielDC/Reportes-Senco.git
cd Reportes-Senco

Install dependencies

composer install
npm install

Configure environment

cp .env.example .env
php artisan key:generate

Edit .env with your database credentials:

.env

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=gbapp
DB_USERNAME=root
DB_PASSWORD=your_password

Create database

CREATE DATABASE gbapp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Run migrations

php artisan migrate --seed

Start development servers

In separate terminal windows:

# Laravel development server
php artisan serve

# Vite development server (hot reload)
npm run dev

Access application

Navigate to http://localhost:8000

Development Tools

Laravel Debugbar

For development debugging, install Laravel Debugbar:

composer require barryvdh/laravel-debugbar --dev

It automatically displays debug information in development mode.

Laravel Telescope

For advanced debugging and monitoring:

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

Access at http://localhost/telescope

Vue DevTools

Install the Vue.js DevTools browser extension:

IDE Configuration

VS Code Extensions

Recommended extensions for development:

.vscode/extensions.json

{
  "recommendations": [
    "bmewburn.vscode-intelephense-client",
    "vue.volar",
    "bradlc.vscode-tailwindcss",
    "mikestead.dotenv",
    "editorconfig.editorconfig"
  ]
}

PHPStorm Configuration

Enable Laravel plugin
Configure Laravel Idea plugin for enhanced autocomplete
Set up PHP interpreter to match project version (8.1+)
Enable Vue.js plugin for .vue file support

Running Tests

PHPUnit Tests

Run the test suite:

# All tests
php artisan test

# Specific test file
php artisan test tests/Feature/UserControllerTest.php

# With coverage
php artisan test --coverage

Test Database

Configure a separate test database in phpunit.xml:

phpunit.xml

<php>
    <env name="DB_CONNECTION" value="mysql"/>
    <env name="DB_DATABASE" value="gbapp_test"/>
</php>

Code Quality Tools

Laravel Pint (Code Style)

Format PHP code according to Laravel standards:

# Check code style
./vendor/bin/pint --test

# Fix code style
./vendor/bin/pint

ESLint (JavaScript)

Add ESLint for Vue.js code quality:

npm install --save-dev eslint @vue/eslint-config-prettier
npx eslint resources/js/**/*.vue

Database Management

Migrations

# Create new migration
php artisan make:migration create_example_table

# Run pending migrations
php artisan migrate

# Rollback last migration
php artisan migrate:rollback

# Reset database (WARNING: destroys all data)
php artisan migrate:fresh --seed

Seeders

# Create seeder
php artisan make:seeder ExampleSeeder

# Run specific seeder
php artisan db:seed --class=ExampleSeeder

# Run all seeders
php artisan db:seed

Tinker (REPL)

Interact with your application:

php artisan tinker

# Example: Create a user
>>> $user = User::create(['name' => 'Test', 'email' => '[email protected]', 'password' => Hash::make('password')]);
>>> $user->assignRole('admin');

Environment Configuration

Development .env

Key settings for development:

.env

APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

LOG_CHANNEL=stack
LOG_LEVEL=debug

# Use database sessions for debugging
SESSION_DRIVER=database

# Disable caching during development
CACHE_DRIVER=file
QUEUE_CONNECTION=sync

Power BI Development

For Power BI integration testing, you need:

Azure AD Application registration
Power BI workspace access
API credentials in .env

See Power BI API Configuration for setup.

Common Development Tasks

Clear All Caches

php artisan optimize:clear

This clears:

Application cache
Route cache
Configuration cache
View cache
Compiled classes

Generate IDE Helper Files

For better autocomplete:

composer require --dev barryvdh/laravel-ide-helper
php artisan ide-helper:generate
php artisan ide-helper:models
php artisan ide-helper:meta

Rebuild Frontend Assets

# Clean build directory
rm -rf public/build

# Rebuild
npm run build

Troubleshooting

Permission Errors

# Fix storage and cache permissions
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

Database Connection Failed

Verify MySQL is running: sudo service mysql status
Check credentials in .env
Test connection: php artisan tinker then DB::connection()->getPdo();

Vite Not Working

Clear Node modules: rm -rf node_modules package-lock.json
Reinstall: npm install
Restart dev server: npm run dev

Docker Container Won’t Start

# Check logs
docker compose logs app

# Rebuild containers
docker compose down
docker compose build --no-cache
docker compose up -d

Next Steps

Coding Standards

Learn the project’s coding conventions

Testing Guide

Write and run tests

Architecture

Understand the system architecture

API Reference

Explore the API endpoints

Architecture

Contributing

​Prerequisites

Docker

Git

Node.js

Composer

​Quick Start with Docker

​Native Development Setup

​System Requirements

​Development Tools

​Laravel Debugbar

​Laravel Telescope

​Vue DevTools

​IDE Configuration

​VS Code Extensions

​PHPStorm Configuration

​Running Tests

​PHPUnit Tests

​Test Database

​Code Quality Tools

​Laravel Pint (Code Style)

​ESLint (JavaScript)

​Database Management

​Migrations

​Seeders

​Tinker (REPL)

​Environment Configuration

​Development .env

​Power BI Development

​Common Development Tasks

​Clear All Caches

​Generate IDE Helper Files

​Rebuild Frontend Assets

​Troubleshooting

​Permission Errors

​Database Connection Failed

​Vite Not Working

​Docker Container Won’t Start

​Next Steps

Coding Standards

Testing Guide

Architecture

API Reference

Build docs developers (and LLMs) love

Prerequisites

Quick Start with Docker

Native Development Setup

System Requirements

Development Tools

Laravel Debugbar

Laravel Telescope

Vue DevTools

IDE Configuration

VS Code Extensions

PHPStorm Configuration

Running Tests

PHPUnit Tests

Test Database

Code Quality Tools

Laravel Pint (Code Style)

ESLint (JavaScript)

Database Management

Migrations

Seeders

Tinker (REPL)

Environment Configuration

Development .env

Power BI Development

Common Development Tasks

Clear All Caches

Generate IDE Helper Files

Rebuild Frontend Assets

Troubleshooting

Permission Errors

Database Connection Failed

Vite Not Working

Docker Container Won’t Start

Next Steps