Laravel Deployment & Usage Guide

1. Prerequisites

Before installing Laravel, ensure your system meets the following requirements:

Runtime Requirements

PHP >= 8.1 with the following extensions:
- ctype, curl, dom, fileinfo, filter, hash, mbstring, openssl, pcre, pdo, session, tokenizer, xml, zip
- Database driver: pdo_mysql (MySQL), pdo_pgsql (PostgreSQL), or pdo_sqlite (SQLite)
Composer (latest stable version)
Node.js >= 18.x and NPM >= 9.x (for frontend asset compilation)
Database Server: MySQL 5.7+ / MariaDB 10.3+, PostgreSQL 10+, or SQLite 3

Optional Tools

Redis (for queues, caching, and sessions)
Git (for version control)
Mailpit or Mailtrap (for local email testing)

2. Installation

Create New Project

# Via Composer create-project
composer create-project laravel/laravel example-app

# Or clone the repository
git clone https://github.com/laravel/laravel.git example-app
cd example-app
composer install

Install Frontend Dependencies

npm install

Environment Setup

# Copy environment file
cp .env.example .env

# Generate application encryption key
php artisan key:generate

Database Setup

# Create database (MySQL/PostgreSQL)
mysql -u root -p -e "CREATE DATABASE laravel_app;"

# Run migrations and seeders
php artisan migrate --seed

3. Configuration

Environment Variables (.env)

Configure your .env file with essential settings:

APP_NAME="Your Application"
APP_ENV=local
APP_KEY=base64:xxxxx... (auto-generated)
APP_DEBUG=true
APP_URL=http://localhost

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=root
DB_PASSWORD=your_password

# Mail (for notifications/password resets)
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_FROM_ADDRESS="hello@example.com"

# Queue & Cache (optional)
QUEUE_CONNECTION=redis
CACHE_STORE=redis
SESSION_DRIVER=redis

Directory Permissions

Ensure the web server can write to these directories:

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache  # On Ubuntu/Debian

Storage Linking

Create symbolic link for public file storage:

php artisan storage:link

4. Build & Run

Development Mode

Start the development server and Vite HMR:

# Terminal 1: Start Laravel development server
php artisan serve

# Terminal 2: Start Vite development server (hot module replacement)
npm run dev

Access the application at http://localhost:8000

Production Build

# Compile and optimize frontend assets
npm run build

# Optimize Laravel for production
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

# Run queue worker (if using queues)
php artisan queue:work --daemon

Running Tests

php artisan test
# or
./vendor/bin/phpunit

5. Deployment

Option A: Laravel Forge (Recommended)

The official server management tool for Laravel:

Connect your server provider (DigitalOcean, AWS, etc.)
Create a server and site in Forge
Configure deployment script:

cd /home/forge/example.com
git pull origin main
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart

Option B: Laravel Vapor (Serverless)

For AWS serverless deployment:

composer require laravel/vapor-cli
vapor deploy production

Option C: Traditional VPS (Nginx)

Example Nginx server block:

server {
    listen 80;
    server_name example.com;
    root /var/www/html/public;
    
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Option D: Docker (Sail)

# Install Laravel Sail
php artisan sail:install

# Start containers
./vendor/bin/sail up -d

# Run commands inside container
./vendor/bin/sail artisan migrate
./vendor/bin/sail npm run dev

6. Troubleshooting

Permission Denied Errors

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

"No application encryption key has been specified"

php artisan key:generate

500 Error with Debug Off

Check logs at storage/logs/laravel.log:

tail -f storage/logs/laravel.log

Database Connection Refused

Verify database server is running: sudo systemctl status mysql
Check credentials in .env
For SQLite: ensure database/database.sqlite exists: touch database/database.sqlite

Missing Vite Manifest Error (Production)

Ensure assets are built before deployment:

npm run build

Queue Jobs Not Processing

Ensure queue worker is running:

php artisan queue:work
# Or use Supervisor for production monitoring

Class/Config Not Found After Changes

composer dump-autoload
php artisan config:clear
php artisan cache:clear

How to Deploy & Use laravel/laravel