Installation - BeanQuick

Installation Guide

This guide covers detailed installation steps for BeanQuick, including production deployment considerations, environment configuration, and troubleshooting.

Looking for a quick setup? Check out the Quickstart Guide for rapid local development setup.

System Requirements

Before installing BeanQuick, ensure your system meets these requirements:

Backend Requirements

PHP

Version 8.2 or higherRequired extensions:

OpenSSL
PDO
Mbstring
Tokenizer
XML
Ctype
JSON
BCMath
Fileinfo
GD or Imagick

Composer

Version 2.0 or higherDependency manager for PHP

Database

MySQL 8.0+ or MariaDB 10.3+For data persistence

Web Server

Apache 2.4+ or Nginx 1.18+For production deployment

Frontend Requirements

Node.js

Version 16.0 or higherJavaScript runtime

npm

Version 7.0 or higherPackage manager (included with Node.js)

Installation Steps

Step 1: Clone the Repository

Clone BeanQuick from your repository:

git clone <repository-url> BeanQuick
cd BeanQuick

The repository contains both back-end and front-end directories. You’ll configure each separately.

Step 2: Backend Installation

Install PHP Dependencies

Navigate to the backend directory and install Composer dependencies:

cd back-end
composer install --optimize-autoloader --no-dev

For development environments, omit the --no-dev flag to include development dependencies like PHPUnit and Laravel Pint.

Environment Configuration

Create your environment file from the example:

cp .env.example .env

Edit .env with your configuration:

# Application
APP_NAME="BeanQuick"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Locale
APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

Important: Never commit your .env file to version control. It contains sensitive credentials.

Generate Application Key

Generate a unique application key for encryption:

php artisan key:generate

This updates the APP_KEY in your .env file.

Database Setup

Create the database:

# Using MySQL CLI
mysql -u root -p

CREATE DATABASE back_end CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;

Run migrations to create all tables:

php artisan migrate --force

Database Schema Overview

BeanQuick creates the following tables:

users - User accounts (customers, businesses, admins)
empresas - Business profiles and information
productos - Product catalog
categorias - Product categories
carritos - Shopping carts
carrito_productos - Cart items
pedidos - Customer orders
pedido_productos - Order items
calificaciones - Product reviews and ratings
solicitud_empresas - Business registration requests
jobs - Queue jobs
cache - Cache entries

Storage Configuration

Create the symbolic link for public file access:

php artisan storage:link

Set proper permissions:

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

Replace www-data with your web server user (e.g., nginx for Nginx).

Step 3: Frontend Installation

Navigate to the frontend directory:

cd ../front-end

Install Node Dependencies

npm install

Configure API Endpoint

Update the API base URL in your React components. Open src/App.jsx and update the axios base URL:

src/App.jsx

// Find and update API calls from:
http://127.0.0.1:8000/api

// To your production URL:
https://api.yourdomain.com/api

Better Approach: Create an environment variable in front-end/.env:

.env

VITE_API_URL=https://api.yourdomain.com

Then use import.meta.env.VITE_API_URL in your components.

Build for Production

Compile and optimize the frontend:

npm run build

This creates a dist directory with optimized static files ready for deployment.

Mercado Pago Configuration

BeanQuick uses Mercado Pago for payment processing. Configure your credentials:

Create Mercado Pago Account

Get API Credentials

Navigate to your application and copy:

Access Token
Public Key

Add to Environment

Update back-end/.env:

.env

MERCADOPAGO_ACCESS_TOKEN=your_access_token_here
MERCADOPAGO_PUBLIC_KEY=your_public_key_here

Configure Webhook

Set up the webhook URL in Mercado Pago dashboard:

https://yourdomain.com/api/webhook/mercadopago

This endpoint handles payment notifications.

Use sandbox credentials for testing and production credentials only when going live.

Web Server Configuration

Apache Configuration

Create a virtual host for the backend:

/etc/apache2/sites-available/beanquick-api.conf

<VirtualHost *:80>
    ServerName api.yourdomain.com
    DocumentRoot /var/www/beanquick/back-end/public

    <Directory /var/www/beanquick/back-end/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/beanquick-error.log
    CustomLog ${APACHE_LOG_DIR}/beanquick-access.log combined
</VirtualHost>

Enable the site and required modules:

sudo a2enmod rewrite
sudo a2ensite beanquick-api.conf
sudo systemctl reload apache2

Nginx Configuration

Create a server block for the backend:

/etc/nginx/sites-available/beanquick-api

server {
    listen 80;
    server_name api.yourdomain.com;
    root /var/www/beanquick/back-end/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/beanquick-api /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Frontend Deployment

For the React frontend, serve the built files:

/etc/nginx/sites-available/beanquick-frontend

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/beanquick/front-end/dist;

    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

SSL Configuration

Secure your application with Let’s Encrypt:

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Obtain SSL certificates
sudo certbot --nginx -d yourdomain.com -d api.yourdomain.com

# Auto-renewal is configured automatically
sudo certbot renew --dry-run

Queue Worker Setup

BeanQuick uses queues for background processing (emails, notifications).

Using Supervisor (Recommended)

Install Supervisor:

sudo apt install supervisor

Create a configuration file:

/etc/supervisor/conf.d/beanquick-worker.conf

[program:beanquick-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/beanquick/back-end/artisan queue:work database --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/beanquick/back-end/storage/logs/worker.log
stopwaitsecs=3600

Start the worker:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start beanquick-worker:*

Scheduled Tasks

BeanQuick may need to run scheduled tasks. Add to crontab:

crontab -e

Add the Laravel scheduler:

* * * * * cd /var/www/beanquick/back-end && php artisan schedule:run >> /dev/null 2>&1

Production Optimization

Cache Configuration

cd back-end

# Cache configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

After changing .env or config files, clear the cache:

php artisan config:clear
php artisan route:clear
php artisan view:clear

Optimize Composer Autoloader

composer install --optimize-autoloader --no-dev
composer dump-autoload --optimize

Security Checklist

Environment Security

Set APP_DEBUG=false in production
Set APP_ENV=production
Use strong, unique APP_KEY
Never commit .env to version control
Restrict .env file permissions: chmod 600 .env

Database Security

Use strong database passwords
Create dedicated database user with limited privileges
Enable SSL for database connections if remote
Regular database backups
Keep database software updated

Server Security

Use HTTPS/SSL for all connections
Configure firewall (UFW, iptables)
Disable directory listing
Keep PHP and web server updated
Set proper file permissions
Configure fail2ban for brute force protection

Application Security

Use CSRF protection (enabled by default)
Validate all user inputs
Use prepared statements (Eloquent ORM)
Implement rate limiting on API endpoints
Regular security audits with composer audit

Verification

Verify your installation:

Test Backend

curl https://api.yourdomain.com/api/productos/destacados

Should return JSON response with featured products.

Test Frontend

Open https://yourdomain.com in your browser.You should see the BeanQuick homepage.

Test Authentication

Try registering a new user account through the frontend.

Test File Uploads

Troubleshooting

500 Internal Server Error

Check Laravel logs:

tail -f back-end/storage/logs/laravel.log

Common causes:

Incorrect file permissions
Missing .env configuration
Database connection issues
Missing PHP extensions

CORS Issues

If the frontend can’t connect to the API:Install Laravel CORS package:

composer require fruitcake/laravel-cors

Configure in config/cors.php:

'paths' => ['api/*'],
'allowed_origins' => ['https://yourdomain.com'],

File Upload Errors

Check upload limits in php.ini:

upload_max_filesize = 10M
post_max_size = 10M

Verify storage permissions:

chmod -R 775 back-end/storage

Queue Not Processing

Check supervisor status:

sudo supervisorctl status

View worker logs:

tail -f back-end/storage/logs/worker.log

Restart workers:

sudo supervisorctl restart beanquick-worker:*

Backup Strategy

Database Backups

#!/bin/bash
# backup.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/var/backups/beanquick"
DB_NAME="back_end"

mkdir -p $BACKUP_DIR

mysqldump -u root -p$DB_PASSWORD $DB_NAME | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# Keep only last 30 days
find $BACKUP_DIR -name "db_*.sql.gz" -mtime +30 -delete

File Backups

# Backup uploaded files
tar -czf storage_backup_$(date +%Y%m%d).tar.gz back-end/storage/app/public

Monitoring

Laravel Telescope (Development)

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

Access at: https://api.yourdomain.com/telescope

Error Tracking

Consider integrating services like:

Sentry
Bugsnag
Rollbar

Performance Optimization

Enable OPcache

Configure in php.ini:

opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000

Use Redis

For caching and sessions:

composer require predis/predis

Update .env:

CACHE_DRIVER=redis
SESSION_DRIVER=redis

CDN Integration

Serve static assets from a CDN for better performance globally.

Database Optimization

Add indexes to frequently queried columns
Use eager loading to prevent N+1 queries
Implement database query caching

Next Steps

Quickstart Guide

Get started with BeanQuick quickly

API Documentation

Explore all available API endpoints

Business Guide

Learn how to manage your business on BeanQuick

Customer Guide

Learn how to order from businesses

Congratulations! Your BeanQuick installation is complete and production-ready.

Get Started

Core Concepts

Features

User Guides

​Installation Guide

​System Requirements

​Backend Requirements

PHP

Composer

Database

Web Server

​Frontend Requirements

Node.js

npm

​Installation Steps

​Step 1: Clone the Repository

​Step 2: Backend Installation

​Install PHP Dependencies

​Environment Configuration

​Generate Application Key

​Database Setup

​Storage Configuration

​Step 3: Frontend Installation

​Install Node Dependencies

​Configure API Endpoint

​Build for Production

​Mercado Pago Configuration

​Web Server Configuration

​Apache Configuration

​Nginx Configuration

​Frontend Deployment

​SSL Configuration

​Queue Worker Setup

​Using Supervisor (Recommended)

​Scheduled Tasks

​Production Optimization

​Cache Configuration

​Optimize Composer Autoloader

​Security Checklist

​Verification

​Troubleshooting

​Backup Strategy

​Database Backups

​File Backups

​Monitoring

​Laravel Telescope (Development)

​Error Tracking

​Performance Optimization

Enable OPcache

Use Redis

CDN Integration

Database Optimization

​Next Steps

Quickstart Guide

API Documentation

Business Guide

Customer Guide

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Backend Requirements

Frontend Requirements

Installation Steps

Step 1: Clone the Repository

Step 2: Backend Installation

Install PHP Dependencies

Environment Configuration

Generate Application Key

Database Setup

Storage Configuration

Step 3: Frontend Installation

Install Node Dependencies

Configure API Endpoint

Build for Production

Mercado Pago Configuration

Web Server Configuration

Apache Configuration

Nginx Configuration

Frontend Deployment

SSL Configuration

Queue Worker Setup

Using Supervisor (Recommended)

Scheduled Tasks

Production Optimization

Cache Configuration

Optimize Composer Autoloader

Security Checklist

Verification

Troubleshooting

Backup Strategy

Database Backups

File Backups

Monitoring

Laravel Telescope (Development)

Error Tracking

Performance Optimization

Next Steps