Installing Laravel 5.x on Windows with IIS

I have had to piece together bits and pieces of this install from various other tutorials and stack overflow posts. So for my own documentation I am recording this here as well. I am writing this documentation after my 2nd or 3rd install so parts I am doing from memory. I apologize if I don't reference the original post that I learned something from because now it's just ingrained, but I'll try to reference them correctly.

These instructions work on both Windows 2012 and Windows 8.1. I have not tried them on earlier versions of Windows or on Windows 10 yet.

Pre-Requisite Server Roles

Before you can get started you need to go into the "Add Roles and Features Wizard" and turn on the "Web Server (IIS)" role. Checking the box in the wizard will pop up a clarification asking you to "Add Features" or "Cancel". Be sure to select the "Include management tools" checkbox. When you get to the part of the wizard that asks for "Role Services" I include the following that are not on by default, and accept the popup that tells me what other dependencies will be installed.

• Server Roles
  • .NET Framework 3.5 Features
    • .NET Framework 3.5
    • HTTP Activiation
  • Web Server
    • Web Server
      • Common HTTP Features
        • HTTP Redirection
      • Health and Diagnostics
        • Tracing
      • Security
        • Basic Authentication (for adding basic authentication to APIs)
      • Application Development
        • ISAPI Extensions
        • ISAPI Filters

Step 1: Web Platform Installer, PHP, and URL Rewrite

The first thing you want do is make sure that IIS' Web Platform Installer is installed. The first time you expand the server in IIS manager it asks you if you want to install this so getting to it should be easy. If you can't find it it's at http://www.microsoft.com/web/downloads/platform.aspx

After you get Web Platform Installer use it to install PHP 5.6 and URL Rewrite 2.0. This should automatically include the SQLServer php libraries and PHP Manager.

Restart IIS and you should see PHP Manager now. Go into PHP Manager and view the PHPInfo page. Also, now you can use the PHP Manager to look at the extensions you have installed.

Step 1.5: Double check PHP is in %PATH% and Microsoft Redistributable Packages are Installed

I have found that the WPI doesn't always add PHP to your path. Open a command terminal and do `php -v` or `echo %PATH%` (or both) and make sure that PHP is in your path. If it's not, add it manually.

When running php -v you may get a message that "MSVCR110.dll is missing from your computer." That can be downloaded at http://www.microsoft.com/en-us/download/details.aspx?id=30679. Be sure to install the X86 version even if you're on a 64 bit architecture.

Step 2: Composer

You'll also want Composer, PHP's package manager. I use the Windows installer to get it done as it also sets up your paths for you.

Step 2.5: Double check composer works

Open a new command shell (the one from Step 1.5 will not work if you still have it open) and just double check that composer works by doing a `composer --version`. If not, you have a path issue that needs to be resolved.

Step 3: Install Laravel or Laravel Based Project and Run Composer Install

Option A: Move an Existing Project onto the Server

I am always installing an existing Laravel site that I have developed elsewhere at this step. If you are using source control correctly you probably have a zip archive you can move to the correct folder and then run composer install to have it install whatever your composer.lock is setup with.

If you are copy/pasting or moving around zip files from server to server, you should run `php artisan cache:clear` to clear caches. Poke around your storage folder and make sure you didn't copy over any log or cache files when you brought your Laravel site over to windows. Permissions issues can cause white screens or 500 errors and having a log file that couldn't be written to has bitten me more than once. Permissions are covered in Step 6 below.

Option B: Creating a Fresh Laravel Install

Another option is to folow the instructions in the Laravel documentation. I always use the "composer create-project" method. I suggest reading the whole page because the permissions instructions are easy to gloss over. Permissions are covered in Step 6 below.

Step 4: Basic IIS Setup

Note: I am adding this step while going through the install myself following my own instructions. I left out this step the first time.

In IIS Manager you can either modify the Default Site or create a new one by right-clicking on the Sites foloder and doing "Add Website". In my case I just modify the default site because this is the only thing running on the machine. Click on the site and use the "Basic Settings" link on the far right to open up the "Edit Site" window. In this window change the Physical Path to the "public" folder under your laravel install. I always hit the "Test Connection" button here and Authentication always passes but Authorization never does. That doesn't seem to change anything later though.

Step 5: Importing the Laravel .htaccess into URL Rewrite

At this point your default view may work, but all your other routes will not. You should be able to get to your index.php and robots.txt files just fine, but test another route you have setup and you'll probably get a 404.

You need to use the URL Rewrite module and import your .htaccess. This will create a web.config file in your public directory.

Step 6: Permissions

You will also want to make sure that the IUSR and IIS_IUSRS accounts have read/execute access to the folder where your laravel app lives and it will need write permissions to the laravel/storage folder. Note that the IIS_IUSRS user is probably a local machine account so if you can't find it be sure you're not looking on the domain. The bootstrap/cache folder will also need write permissions for these users.

I have had some issues with certain security policies that have led me to give EVERYONE full control of the laravel/storage directory. There is probably a better way of handling those, but that has worked for me.

There is also a "Read Only" attribute in the general properties of the folders I un-check if it is checked.

Step 7: Configure your .env file

If you are doing a fresh install be sure to setup your .env file. The APP_DEBUG and APP_KEY settings are crucial.

Further Debugging: Don't Use IE.

If you are using IE because it's the only thing installed on the server. Go ahead and install a decent browser and text editor. You'll need them for additional debugging. IE will often hide real responses with it's own fancy page making debugging a pain in the ass. And if you have to get down into the weeds of why something isn't working you're going to appreciate something better than notepad.

Optional: Enable Additional PHP Extensions

In some of my apps I have to go into the PHP Manager and enable additional extensions if they didn't come standard with the PHP install. Examples are turning on SQLLite if I was using it, or the SOAP module.

Optional: Basic Authentication

I am often building API's that require HTTP Basic Authentication. In IIS there is an Authenticatoin module. You can set this up per site or globally. I do it per site. When you enter the Authentication module you should see Basic Authentication as an option. If you don't see it you probably skipped adding Basic Authentication back in the Server Roles/Features setup. I turn off Anonymous Authentication and turn on Basic Authentication. You may get a warning about passwords being exposed if you don't use SSL.

Windows uses local accounts to handle authentication so you'll need to go into the "Local Users and Groups" and go create a local user. I set them to up to not be able to change the password and the password never expires.

Optional: SSL

The easy way to do SSL is to use a self-signed certificate. This is done at the server level (not the site level) in IIS Manager. There will be a "Server Certificates" module you can go into and use the "Create Self-Signed Certificate" to add a certificate.

If you have been provided certificates by a third party you need to add them in Microsoft Management Console (MMC). Better instructions than I can write can be found at https://www.digicert.com/ssl-support/pfx-import-export-iis-8.htm under the "Importing From a .pfx File" section. You may need to install multiple certs including root and intermediate certs from the provider.

After the certs have been added through MMC, restart IIS Manager and go into the website and click on Bindings. Add the SSL binding and choose the cert you just added (or your self-signed one). I leave the host name blank and make sure "Require Server Name Indication" to be off because older API integrations don't always support SNI.

Help Me Expand These Instructions

If you are a performance/security guru and see something wrong with these instructions please leave a comment below. I'll gladly add your notes so I don't steer people in the wrong direction.

Likewise, if you have a scenario that isn't covered here and know the solution, let me know and I'll add it.