Howto: Install Laravel 5.5 on shared hosting

(updated 31st August 2017)

There are a few guides on the interwebs concerning installing Laravel on shared hosting, but they're either incomplete or out of date. Recently we updated one of our client sites to Laravel 5.5; the site needed to go live on a cpanel-type shared hosting (LAMP). The good news is that it's easy. Even better news is that I created a PHP script to do everything necessary to prepare your Laravel application for deployment. So what's involved? Let's dive in!

Backups

I'll keep this brief. You're a webdev and you're about to push your locally tested and working L5.x site live? Back up your existing site source, configuration and data. If it all goes wrong, roll back. If it's a production site receiving high-volume traffic, employ a strategy to test your live site via a local DNS redirect and switch the DNS live when happy. You know the drill.

Caveats

It's unlikely that your shared hosting provider will give you the necessary permissions, command line access or freedom to deploy your app in a state where it can be remotely developed. So we're going to assume that command line access to tools like node npm composer and php artisan ... are unavailable on a shared hosting account. This means that substantial development will occur locally, and the live install will be a snapshot of the current local development state. You'll have the ability to FTP in and make edits to PHP source, blade templates etc., but you won't be able to compile your client-side assets or install composer packages. You probably know this anyway, but it's worth spelling out: shared hosting is a restricted but low-cost option for hosting small-scale applications or prototypes. Expect some limitations.

Begin Here

Let's assume you're working on a Linux or Mac local server running apache, with your working Laravel app available under but the following procedure should be similar running on a local Windows LAMP stack. We're going to work with a copy of our ready-to-live L5.5 application as we'll need to reaarrange folders and files, and make some minor adjustments to the code.

So your working Laravel development resides in /var/www/mylaravelapp.local in its original folder structure, as installed originally through laravel new [appname] or something like composer create-project --prefer-dist laravel/laravel [appname]. Start by performing some general housekeeping on your laravel app. From laravelapp.local, issue the following commands:

php artisan cache:clean
php artisan view:clear
rm ./storage/sessions
...

You probably have and know about the .env file, which from L5.2 provides a tidy way to configure Laravel with things like database, REDIS and SMTP credentials. Create a second one of these, .env.production, with the former containing your config for local development and the latter the config for your live (shared) hosted version.

1. Take a copy

Copy the entire mylaravelapp.local branch to another folder, say ~/deploy/mylaravelapp. Exclude the node_modules folder from the copy, we don't need it (see above) and it's huge. The tool rsync can be your friend here, as it allows exclude patterns from the copy. We'll leave the rest in although if you want a really clean install there's more that could be removed including composer.json, webpack.mix.js, yarn.lock, composer.lock, gulpfile.js etc. etc..

2. Rearrange folders

cd ~/deploy/mylaravelapp and create a new directory (say) laravel in there. Move everything except the public directory into it. At this point an ls command should show just two directories, laravel and public.

3. Switch Laravel .env to production

Earlier we created .env.production, which should be modified to reflect the necessary configuration of Laravel on your live shared hosting. Let's make this the default environment for our deployable Laravel app:

Still in ~/deploy/mylaravelapp:

cd laravel
rm .env
mv .env.production .env

4. Modify Laravel paths

It's worth mentioning at this point that our shared hosting setup will involve Laravel's public directory being the visible public directory on the shared hosting account. The public directory will therefore need to be renamed to www or public_html, or whatever the default directory name is for your shared hosting provider - we'll do that later. The rest of the laravel app directory branch will be hidden to the outside world and is contained within the laravel directory as described in step 2. With that in mind, we need to modify Laravel's paths and public_path() helper. Let's do that.

In ~/deploy/mylaravelapp/public, edit the file index.php and make the following adjustments:

Change:
require __DIR__.'/../bootstrap/autoload.php';
to:
require __DIR__.'/../laravel/bootstrap/autoload.php';

Change:
$app = require_once __DIR__.'/../bootstrap/app.php';
to:
$app = require_once __DIR__.'/../laravel/bootstrap/app.php';

The public_path() helper will likely point to the wrong place with this directory reconfiguration, so we need to fix that. Directly under the comment 'Run The Application' and above the line $kernel = $app->make(Illuminate\Contracts\Http\Kernel::class); insert the following:

// rebind public_path()
$app->bind('path.public', function() {
  return __DIR__;
});

5. Rename public folder

As described in step 4, we need our public directory to match the name of the shared hosting's default public directory, typically www or public_html. In ~/deploy/mylaravelapp:

mv ./public ./public_html

6. Zip or tar for deployment

Finally we need to take our modified and restructured Laravel app codebase and package it up to deploy on shared hosting. In ~/deploy/mylaravelapp:

tar czf mylaravelapp.tar.gz .

7. Upload and deploy!

Most likely your cpanel file manager or ftp access to your shared hosting will drop you into the root directory for your hosting account, under which your publicly visible web-root public_html or www reside. Ensure your public_html (or web-root) directory is empty. Then, using cpanel or your favourite FTP tool, upload mylaravelapp.tar.gz to your hosting's root directory. Using cpanel's file manager or another tool, extract mylaravelapp.tar.gz in there. Doing so will overwrite the hosting's web-root with that contained in your tarfile, and will create the new 'laravel' directory with the rest of the Laravel app.

8. Final steps

If your Laravel app uses a database, use phpMyAdmin or MySQL locally to take an SQL dump of your database, then use the same tool on your live hosting to import the database into the hosting's MySQL. Ensure your production .env file has the correct configuration/credentials for accessing MySQL on the hosting server.

Point your browser at www.mylaravelapp.com and, all being well, your Laravel site/application will appear!

...to be continued!