Installation & Setup

Learn more about Mintlify

Enter your email to receive updates about new features and product releases.

Prerequisites
Required Software
PHP Extensions
Installation Steps
Essential Configuration
Post-Installation Configuration
Queue Worker
Task Scheduling
File Permissions
Development Tools
Code Quality
Testing
Database Management
Production Deployment
Optimization
Security Considerations
Troubleshooting
Common Issues
Useful Commands Reference
Next Steps
Additional Resources

Prerequisites

Before installing Core Projects, ensure your environment meets these requirements:

Required Software

PHP 8.2+

Modern PHP version with required extensions

Composer 2.0+

PHP dependency manager

Node.js 18+

JavaScript runtime for frontend tooling

Database

SQLite (default), MySQL 5.7+, or PostgreSQL 12+

PHP Extensions

Ensure these PHP extensions are enabled:

# Required extensions
php -m | grep -E 'PDO|pdo_sqlite|mbstring|openssl|tokenizer|xml|ctype|json|bcmath'

Core Projects is configured to use SQLite by default for easy setup. You can switch to MySQL or PostgreSQL in production.

Installation Steps

Clone or Download the Repository

Get the Core Projects source code:

# If using Git
git clone <repository-url> core-projects
cd core-projects

# Or extract from downloaded archive
unzip core-projects.zip
cd core-projects

Install Dependencies

Install both PHP and JavaScript dependencies:

# Install PHP dependencies
composer install

# Install JavaScript dependencies
npm install

The project is configured to use pnpm as the preferred package manager (package.json:29). Both npm and pnpm will work.

Configure Environment Variables

Create and configure your .env file:

# Copy the example environment file
cp .env.example .env

Essential Configuration

Edit .env to configure your application:

# From .env.example:1-5
APP_NAME="Core Projects"
APP_ENV=local
APP_KEY=                    # Generated automatically
APP_DEBUG=true              # Set to false in production
APP_URL=http://localhost:8000

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

Generate Application Key

Generate a unique encryption key for your application:

php artisan key:generate

This updates the APP_KEY value in your .env file.

This step is automatically included in composer run setup.

Create Database

Set up your database:

# Create the database file
touch database/database.sqlite

# Verify it exists
ls -lh database/database.sqlite

Run Database Migrations

Create all necessary database tables:

php artisan migrate

This creates tables for:

Employees and authentication
Projects, towers, floors, and properties
Clients and sales
Payment plans and transactions
System configuration

If you need to reset the database, use php artisan migrate:fresh (warning: destroys all data).

Seed Initial Data (Optional)

Populate the database with initial configuration data:

# Run database seeders
php artisan db:seed

This typically creates:

Default user roles and permissions
Sample client types and document types
Payment method options
Status configurations

Check your seeders before running to understand what data will be created.

Build Frontend Assets

Compile JavaScript and CSS assets:

# Build optimized assets for production
npm run build

# Or with pnpm
pnpm run build

The build process:

Compiles Vue 3 components
Processes Tailwind CSS
Bundles JavaScript with Vite
Optimizes assets for production

Build Configuration (from package.json:5-8):

{
  "scripts": {
    "build": "vite build",
    "dev": "vite"
  }
}

Start the Development Server

Launch the application in development mode:

# Start Laravel development server
php artisan serve

# Application available at http://localhost:8000

The composer run dev command provides the best development experience with hot module reloading and live logs.

Open your browser and navigate to:

http://localhost:8000

You should see the Core Projects login page.

Create Your First Admin User

Create an administrative user to access the system:

# Use tinker to create a user
php artisan tinker

Then in the tinker console:

// Create dependencies first
$dependencia = App\Models\Dependencia::create([
    'nombre_dependencia' => 'Administración'
]);

$cargo = App\Models\Cargo::create([
    'nombre_cargo' => 'Administrador',
    'id_dependencia' => $dependencia->id_dependencia
]);

// Create admin user (from app/Models/Empleado.php)
$admin = App\Models\Empleado::create([
    'nombre' => 'Admin',
    'apellido' => 'User',
    'email' => '[email protected]',
    'telefono' => '1234567890',
    'id_cargo' => $cargo->id_cargo,
    'id_dependencia' => $dependencia->id_dependencia,
    'estado' => true,
    'password' => bcrypt('password')
]);

// Exit tinker
exit

Important: Change the default password immediately after first login.

You can now log in with:

Email: [email protected]
Password: password

Post-Installation Configuration

Queue Worker

Core Projects uses database queues for background jobs. In production, run a queue worker:

# Start queue worker
php artisan queue:work --tries=3

# Or use supervisor for automatic restart
sudo supervisorctl start core-projects-worker

Task Scheduling

Set up Laravel’s task scheduler for automated jobs:

# Add to crontab (crontab -e)
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

This enables:

Automatic separation expiration
Payment reminders
Report generation
Data cleanup

File Permissions

Ensure proper permissions for Laravel:

# Set ownership
sudo chown -R www-data:www-data /path-to-your-project

# Set directory permissions
find /path-to-your-project -type d -exec chmod 755 {} \;

# Set file permissions
find /path-to-your-project -type f -exec chmod 644 {} \;

# Make storage and cache writable
chmod -R 775 storage bootstrap/cache

Development Tools

Code Quality

# Format PHP code with Laravel Pint (composer.json:75-77)
composer run lint:php

# Or directly
vendor/bin/pint

Testing

Run the test suite:

# Run all tests (composer.json:53-56)
composer run test

# Or directly with PHPUnit
php artisan test

# Run specific test
php artisan test --filter=ProjectTest

Database Management

# Create new migration
php artisan make:migration create_table_name

# Run migrations
php artisan migrate

# Rollback last migration
php artisan migrate:rollback

# Reset database
php artisan migrate:fresh

# Reset and seed
php artisan migrate:fresh --seed

Production Deployment

Optimization

Before deploying to production:

Update Environment

# Set production environment
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

Optimize Application

# Cache configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

# Optimize autoloader
composer install --optimize-autoloader --no-dev

Build Production Assets

# Build optimized frontend
npm run build
# or
pnpm run build

Configure Web Server

Apache (.htaccess):

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

Nginx:

server {
    listen 80;
    server_name your-domain.com;
    root /path-to-your-project/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;
    }
}

Set Up SSL

# Using Certbot for Let's Encrypt
sudo certbot --nginx -d your-domain.com

Configure Queue & Scheduler

Set up Supervisor for queue workers and cron for scheduler (see above).

Security Considerations

Ensure these security measures before going live:

Troubleshooting

Common Issues

500 Internal Server Error

Cause: Missing or incorrect .env file, permissions issues, or missing dependencies.Solution:

# Check logs
tail -f storage/logs/laravel.log

# Clear all caches
php artisan config:clear
php artisan cache:clear
php artisan view:clear

# Fix permissions
chmod -R 775 storage bootstrap/cache

Database Connection Errors

Cause: Incorrect database credentials or database server not running.Solution:

# Verify database connection
php artisan tinker
DB::connection()->getPdo();

# Check .env settings
cat .env | grep DB_

# For SQLite, ensure file exists
touch database/database.sqlite

Vite/Asset Build Errors

Cause: Node modules not installed or version mismatch.Solution:

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

# Or with pnpm
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Rebuild
npm run build

Cause: Missing admin user or incorrect credentials.Solution:

# Check if user exists
php artisan tinker
App\Models\Empleado::where('email', '[email protected]')->first();

# Reset password
$user = App\Models\Empleado::where('email', '[email protected]')->first();
$user->password = bcrypt('new-password');
$user->save();

File Upload Errors

Cause: Insufficient permissions on storage directory.Solution:

# Fix storage permissions
chmod -R 775 storage
chown -R www-data:www-data storage

# Create symbolic link
php artisan storage:link

Useful Commands Reference

# Application
php artisan serve              # Start dev server
php artisan tinker             # Interactive shell
php artisan down               # Maintenance mode
php artisan up                 # Exit maintenance mode

# Database
php artisan migrate            # Run migrations
php artisan migrate:fresh      # Drop and recreate
php artisan db:seed            # Run seeders

# Cache
php artisan cache:clear        # Clear app cache
php artisan config:clear       # Clear config cache
php artisan route:clear        # Clear route cache
php artisan view:clear         # Clear view cache

# Optimization
php artisan config:cache       # Cache config
php artisan route:cache        # Cache routes
php artisan view:cache         # Cache views

# Queue
php artisan queue:work         # Process jobs
php artisan queue:listen       # Listen for jobs
php artisan queue:restart      # Restart workers

# Development
php artisan pail               # Enhanced log viewing

Next Steps

After successful installation:

Quickstart Guide

Learn how to use Core Projects with our step-by-step guide

Configure First Project

Set up your first construction project and property inventory

User Management

Create employee accounts and configure roles

System Configuration

Configure system-wide settings and preferences

Additional Resources

Laravel Documentation: https://laravel.com/docs/12.x
Vue 3 Documentation: https://vuejs.org/guide/
Inertia.js Documentation: https://inertiajs.com/
Tailwind CSS Documentation: https://tailwindcss.com/docs

Quickstart Guide

System Architecture

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Get Started

Core Concepts

Features

User Guides

Prerequisites

Required Software

PHP 8.2+

Composer 2.0+

Node.js 18+

Database

PHP Extensions

Installation Steps

Essential Configuration

Post-Installation Configuration

Queue Worker

Task Scheduling

File Permissions

Development Tools

Code Quality

Testing

Database Management

Production Deployment

Optimization

Security Considerations

Troubleshooting

Common Issues

Useful Commands Reference

Next Steps

Quickstart Guide

Configure First Project

User Management

System Configuration

Additional Resources

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

User Guides

​Prerequisites

​Required Software

PHP 8.2+

Composer 2.0+

Node.js 18+

Database

​PHP Extensions

​Installation Steps

​Essential Configuration

​Post-Installation Configuration

​Queue Worker

​Task Scheduling

​File Permissions

​Development Tools

​Code Quality

​Testing

​Database Management

​Production Deployment

​Optimization

​Security Considerations

​Troubleshooting

​Common Issues

​Useful Commands Reference

​Next Steps

Quickstart Guide

Configure First Project

User Management

System Configuration

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Required Software

PHP Extensions

Installation Steps

Essential Configuration

Post-Installation Configuration

Queue Worker

Task Scheduling

File Permissions

Development Tools

Code Quality

Testing

Database Management

Production Deployment

Optimization

Security Considerations

Troubleshooting

Common Issues

Useful Commands Reference

Next Steps

Additional Resources