Laravel Suitcase

Laravel Suitcase helps you package your Laravel app for deployment on shared hosting, handling environment setup, file structure, and more.

Quick Start

1. Install Laravel Suitcase:

   composer require sameoldnick/laravel-suitcase
   

2. Publish the config and environment files:

   php artisan vendor:publish --tag=suitcase-config
   php artisan vendor:publish --tag=suitcase-env
   

3. Generate an application key for shared hosting:

   php artisan --env=shared key:generate
   

4. Edit .env.shared with your database and mail settings.
5. Prepare your app for production (update dependencies, build assets, run migrations).
6. Package your app:

   php artisan suitcase:pack
   

7. Deploy the generated ZIP to your shared hosting and follow the INSTALL.txt instructions inside.

Table of Contents

• Limitations
• Requirements
• Detailed Setup
  • Environment File
    • Database Configuration
    • Mail Configuration
    • Additional Configuration
  • Preparation
  • Package the Laravel App

Limitations

Shared hosting does not support some features of Laravel, such as:

• Asynchronous queues
• Broadcasting and WebSockets
• Artisan commands

If your Laravel app requires these features, you will need a VPS or dedicated server.

Requirements

• PHP v8.1 or higher
• Laravel 10.x, 11.x, or 12.x

Required PHP extensions:

• pdo
• pdo_mysql (or pdo_sqlite, pdo_pgsql, etc. for your DB)
• zip

Detailed Setup

1. Install the Package

Install Laravel Suitcase using Composer. This will add it to your Laravel project's dependencies.

composer require sameoldnick/laravel-suitcase

2. Publish the Config and Environment Files

Publish the configuration file to config/suitcase.php and the shared environment file to your project root. You can customize these as needed.

php artisan vendor:publish --tag=suitcase-config
php artisan vendor:publish --tag=suitcase-env

3. Generate the Application Key

Generate a unique application key for your shared hosting environment. This is important for security—do not reuse keys across installations.

php artisan --env=shared key:generate

Important: Use a different key for each installation of your Laravel app. Do not use the same key for every installation.

4. Edit the Environment File

Edit the .env.shared file to configure your environment variables for the shared hosting environment.

Database Configuration

If you haven't already, create a database in your shared hosting account. Set the database credentials in the .env.shared file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=username_db
DB_USERNAME=username_user
DB_PASSWORD=secret

Mail Configuration

Set the mail configuration in the .env.shared file. If you have an email account with your hosting provider, you can use SMTP:

MAIL_MAILER=smtp
MAIL_SCHEME=smtps
MAIL_HOST=127.0.0.1
MAIL_PORT=465
MAIL_USERNAME="username@yourdomain.com"
MAIL_PASSWORD=secret
MAIL_FROM_ADDRESS="username@yourdomain.com"
MAIL_FROM_NAME="${APP_NAME}"

Or use sendmail:

MAIL_MAILER=sendmail

Additional Configuration

The SHARED_HOSTING variable needs to be set so the Laravel app can run properly in a shared hosting environment:

SHARED_HOSTING=true

Ensure that the correct environment variables are set. You can reference the .env file used for local development to see what variables should be set.

5. Prepare Your App for Production

Before packaging your Laravel app, make sure it is production-ready. Laravel Suitcase does not run database migrations or build frontend assets; it copies what is available. Be sure to:

• Update Composer dependencies: composer update
• Update NodeJS packages: npm i
• Build frontend assets: npm run build
• Run database migrations: php artisan migrate

6. Package the Laravel App

When you're ready, package the Laravel app by running:

php artisan suitcase:pack

Packaging may take several minutes. A ZIP file will be created in the root folder of your Laravel app. Follow the instructions in the INSTALL.txt file (inside the ZIP) to deploy to shared hosting.