Installation - Gestión de Ventas

System Requirements

Before installing Gestión de Ventas, ensure your system meets these requirements:

Server Requirements

PHP 8.2 or higher
Composer 2.x
Node.js 18+ and npm
SQLite or MySQL/MariaDB

PHP Extensions

BCMath
Ctype
Fileinfo
JSON
Mbstring
OpenSSL
PDO
Tokenizer
XML

The system uses Laravel 12, which requires PHP 8.2 or higher. Make sure your PHP version is compatible before proceeding.

Installation Methods

Choose the installation method that best suits your workflow:

Automated Setup
Manual Setup

Quick Setup with Composer Script

The project includes an automated setup script that handles all installation steps:

Clone the Repository

git clone <repository-url> gestion-ventas
cd gestion-ventas

Run Automated Setup

composer setup

This single command performs:

Installs all PHP dependencies via Composer
Copies .env.example to .env (if not exists)
Generates application key
Runs database migrations
Installs Node.js dependencies
Builds frontend assets

Configure Environment

Edit the .env file to customize your installation:

nano .env

See Environment Configuration for details.

Run Seeders

Populate the database with initial data:

php artisan db:seed

This creates:

Default roles and permissions
System configuration
Geographic data (countries, states, municipalities)
Sample data (optional)

Step-by-Step Manual Installation

Clone and Navigate

git clone <repository-url> gestion-ventas
cd gestion-ventas

Install PHP Dependencies

composer install

Environment Configuration

Create and configure your environment file:

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

Database Setup

Configure your database in .env, then run migrations:

php artisan migrate

Seed Initial Data

php artisan db:seed

Install Frontend Dependencies

npm install

Build Assets

For production:

npm run build

For development:

npm run dev

Environment Configuration

The .env file controls all application settings. Here are the key configurations:

Application Settings

.env

APP_NAME="Gestión de Ventas"
APP_ENV=local
APP_KEY=base64:... # Generated by php artisan key:generate
APP_DEBUG=true
APP_URL=http://localhost:8000

APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

Set APP_DEBUG=false in production to prevent sensitive information leakage.

Database Configuration

The system supports both SQLite and MySQL:

DB_CONNECTION=sqlite
# SQLite uses database/database.sqlite file
# No additional configuration needed

SQLite is perfect for development and small deployments. For production environments with multiple concurrent users, MySQL/MariaDB is recommended.

Session and Cache

.env

SESSION_DRIVER=database
SESSION_LIFETIME=120

CACHE_STORE=database
QUEUE_CONNECTION=database

Mail Configuration

.env

MAIL_MAILER=log  # For development
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

For production, configure SMTP settings:

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls

Google Maps API (Optional)

.env

GOOGLE_MAPS_API_KEY=your_api_key_here

Database Setup

Running Migrations

Migrations create all required database tables:

php artisan migrate

Key tables created:

Core Tables

users - User accounts
roles and permissions - Access control (Spatie)
cache, sessions, jobs - System tables

Sales Module

sales - Sales transactions
sale_items - Individual sale line items
invoices - Generated invoices
ncf_types, ncf_logs - Fiscal numbering (Dominican Republic)

Inventory Module

warehouses - Storage locations
products - Product catalog
inventory_stocks - Current stock levels
inventory_movements - Stock movement history

Accounting Module

accounting_accounts - Chart of accounts
journal_entries - Financial transactions
journal_entry_items - Transaction line items
receivables - Accounts receivable
document_types - Document numbering sequences

Configuration

tipo_pagos - Payment methods
impuestos - Tax settings
estados_clientes - Client status categories
dias_semana - Days of week configuration

Seeding Initial Data

Seeders populate the database with required initial data:

php artisan db:seed

This creates:

Roles and Permissions: Admin, Manager, Cashier, etc.
Document Types: Invoice (FAC), Receipt (REC), etc.
Chart of Accounts: Basic accounting structure
Geographic Data: Countries, states, municipalities
Default Configuration: Tax rates, payment methods
Admin User: Default administrator account

The default admin credentials are typically:

Email: [email protected]
Password: password

Change these immediately after first login!

Frontend Asset Compilation

The system uses Vite for fast asset bundling:

Development Mode

Run the development server with hot module replacement:

npm run dev

This starts Vite’s development server and watches for file changes.

Production Build

Compile and minify assets for production:

npm run build

Optimized assets are generated in the public/build directory.

Running the Application

Development Server

Laravel includes a built-in development server:

php artisan serve

The application will be available at http://localhost:8000.

Development with All Services

For a complete development environment with queue workers and logs:

composer dev

This command runs concurrently:

php artisan serve - Web server on port 8000
php artisan queue:listen - Background job processing
php artisan pail - Real-time log viewer
npm run dev - Frontend asset compilation

The composer dev command requires the concurrently npm package (already included in package.json).

Production Deployment

For production servers, use a proper web server like Nginx or Apache:

Configure Web Server

Point the document root to the public directory.

Set Permissions

chmod -R 755 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Optimize Application

php artisan config:cache
php artisan route:cache
php artisan view:cache

Set up Queue Worker

Configure a supervisor process for queue:work:

php artisan queue:work --daemon

Verification

Verify your installation is working correctly:

Access the Application

Navigate to http://localhost:8000 in your browser.

Test Login

Check Dashboard

Verify you can access the dashboard at /dashboard.

Test Permissions

Check that the permission system is working by accessing restricted areas.

Troubleshooting Common Issues

Application Key Missing

Error: No application encryption key has been specifiedSolution:

php artisan key:generate

Database Connection Failed

Error: SQLSTATE[HY000] [1045] Access deniedSolution: Verify database credentials in .env file match your database setup.

Storage Permission Denied

Error: The stream or file could not be openedSolution:

chmod -R 755 storage
chmod -R 755 bootstrap/cache

Vite Manifest Not Found

Error: Vite manifest not foundSolution: Build the frontend assets:

npm install
npm run build

Composer Dependencies Error

Error: Your requirements could not be resolvedSolution: Make sure you’re running PHP 8.2 or higher:

php -v
composer install

Post-Installation Configuration

After installation, configure these essential settings:

1. Create Initial Users

Create user accounts for your team:

php artisan tinker

$user = App\Models\User::create([
    'name' => 'John Doe',
    'email' => '[email protected]',
    'password' => bcrypt('password'),
]);

$user->assignRole('Cashier');

2. Configure Payment Methods

Set up available payment methods in the Configuration module:

Cash
Credit Card
Debit Card
Bank Transfer
Check

3. Set Up Warehouses

Create warehouse locations for inventory tracking.

4. Configure Chart of Accounts

Customize the accounting structure for your business needs.

5. Set Tax Rates

Configure applicable tax rates (ITBIS for Dominican Republic).

Next Steps

Quickstart Guide

Learn how to process your first sale and explore core features.

Architecture Overview

Understand the system architecture and design patterns.

Getting Help

If you encounter issues during installation:

Check the Laravel logs in storage/logs/laravel.log
Enable debug mode: APP_DEBUG=true in .env
Review the Laravel documentation
Check PHP error logs for server-side issues

Remember to disable debug mode (APP_DEBUG=false) before deploying to production.

Get Started

Core Concepts

Modules

Features

Development

​System Requirements

Server Requirements

PHP Extensions

​Installation Methods

​Quick Setup with Composer Script

​Step-by-Step Manual Installation

​Environment Configuration

​Application Settings

​Database Configuration

​Session and Cache

​Mail Configuration

​Google Maps API (Optional)

​Database Setup

​Running Migrations

​Seeding Initial Data

​Frontend Asset Compilation

​Development Mode

​Production Build

​Running the Application

​Development Server

​Development with All Services

​Production Deployment

​Verification

​Troubleshooting Common Issues

​Post-Installation Configuration

​1. Create Initial Users

​2. Configure Payment Methods

​3. Set Up Warehouses

​4. Configure Chart of Accounts

​5. Set Tax Rates

​Next Steps

Quickstart Guide

Architecture Overview

​Getting Help

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Quick Setup with Composer Script

Step-by-Step Manual Installation

Environment Configuration

Application Settings

Database Configuration

Session and Cache

Mail Configuration

Google Maps API (Optional)

Database Setup

Running Migrations

Seeding Initial Data

Frontend Asset Compilation

Development Mode

Production Build

Running the Application

Development Server

Development with All Services

Production Deployment

Verification

Troubleshooting Common Issues

Post-Installation Configuration

1. Create Initial Users

2. Configure Payment Methods

3. Set Up Warehouses

4. Configure Chart of Accounts

5. Set Tax Rates

Next Steps

Getting Help