Skip to main content

​
Quick Start Guide

This guide will get you up and running with BeanQuick in just a few minutes. We’ll use the automated setup script to handle all configuration.
Prerequisites: Make sure you have PHP 8.2+, Composer, Node.js 16+, and MySQL installed on your system.

​
Setup in 3 Steps

1

Clone the Repository

Clone BeanQuick to your local machine:
git clone <repository-url>
cd BeanQuick
2

Configure Database

Create a MySQL database and update your environment file:
# Create database (MySQL)
mysql -u root -p -e "CREATE DATABASE back_end"

# Copy environment file
cd back-end
cp .env.example .env
Edit back-end/.env and update database credentials:
.env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=back_end
DB_USERNAME=root
DB_PASSWORD=your_password
3

Run Setup Script

BeanQuick includes an automated setup command that handles everything:
composer setup
This single command will:
  • Install all PHP dependencies
  • Copy .env.example to .env (if not exists)
  • Generate application key
  • Run database migrations
  • Install Node.js dependencies
  • Build frontend assets
Setup Complete! BeanQuick is now installed and ready to run.

​
Launch the Application

BeanQuick provides a convenient command to start all services simultaneously: 
composer dev
This starts three concurrent processes:
  • Laravel Server - Backend API on http://127.0.0.1:8000
  • Queue Worker - Background job processing
  • Vite Dev Server - Frontend with HMR on http://localhost:5173
BeanQuick development servers running
The composer dev command uses concurrently to run all services in one terminal window with color-coded output for easy monitoring.

​
Access the Application

Once the development servers are running:

Frontend Application

http://localhost:5173Main user interface for customers and businesses

Backend API

http://127.0.0.1:8000/apiRESTful API endpoints for all platform operations

​
Create Your First User

​
Register as a Customer

1

Navigate to Registration

Open your browser to http://localhost:5173/register
2

Fill Registration Form

Enter your details:
  • Name
  • Email
  • Password
  • Confirm Password
3

Login

After registration, login at http://localhost:5173/login

​
Register a Coffee Business

1

Submit Business Application

Navigate to http://localhost:5173/solicitud-empresa and fill out:
  • Business name
  • NIT (Tax ID)
  • Contact information
  • Business description
2

Admin Approval Required

Business registrations require admin approval. You’ll need an admin account first.
-- Create admin user directly in database
INSERT INTO users (name, email, password, rol, created_at, updated_at)
VALUES (
  'Admin User',
  '[email protected]',
  '$2y$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMESaQYb3WewHC6Jv/f2z0QKym', -- password: password
  'admin',
  NOW(),
  NOW()
);
3

Approve Business

Login as admin and navigate to:http://localhost:5173/admin/solicitudesReview and approve the business application.
4

Activate Business Account

Check the activation link in the application logs or database:
SELECT token FROM solicitud_empresas WHERE estado = 'aprobado';
Navigate to: http://localhost:5173/empresa/activar/{token}Complete the activation process to set up your business account.

​
Test Key Features

​
As a Customer

# Navigate to dashboard
open http://localhost:5173/cliente/dashboard

# View available coffee shops
# Click on a shop to see their products

​
As a Business

# Navigate to business panel
open http://localhost:5173/empresa/panel

# Go to Products > Add New
# Upload product image
# Set price and description
# Select category

​
API Testing

Test the API directly using curl or tools like Postman: 
curl -X POST http://127.0.0.1:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password"
  }'

​
Development Commands

Useful commands for development: 
# Run migrations
php artisan migrate

# Rollback migrations
php artisan migrate:rollback

# Clear cache
php artisan cache:clear
php artisan config:clear

# Run tests
composer test

# Code formatting
./vendor/bin/pint

# Generate IDE helper files
php artisan ide-helper:generate

cd front-end

# Start dev server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Run linter
npm run lint

# Access MySQL console
mysql -u root -p back_end

# Run seeders
php artisan db:seed

# Fresh migration with seeding
php artisan migrate:fresh --seed

# Check database status
php artisan migrate:status

​
Troubleshooting

If port 8000 or 5173 is already in use:
# Kill process on port 8000 (Linux/Mac)
lsof -ti:8000 | xargs kill -9

# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

# Or specify different ports
php artisan serve --port=8001
npm run dev -- --port 5174
Verify your database credentials:
# Test MySQL connection
mysql -u root -p

# Check if database exists
SHOW DATABASES;

# Create database if missing
CREATE DATABASE back_end;
Update back-end/.env with correct credentials.
Laravel needs write permissions for storage:
cd back-end
chmod -R 775 storage bootstrap/cache

# Create storage link for public files
php artisan storage:link
If composer install fails:
# Update Composer
composer self-update

# Clear Composer cache
composer clear-cache

# Install with verbose output
composer install -vvv
If npm has issues:
cd front-end

# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

​
Next Steps

Now that BeanQuick is running, explore these topics:

Detailed Installation

Learn about production deployment and advanced configuration

Configuration

Configure payment gateways, email, and environment variables

API Documentation

Explore all API endpoints and authentication methods

User Roles

Learn about the architecture and different user roles
Development Environment Only: The quickstart configuration is optimized for local development. For production deployment, follow the Installation Guide for security best practices.
Pro Tip: Use the composer dev command in a dedicated terminal window and keep it running during development. It provides live reload for both frontend and backend changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us