In this short guide, we will describe the process of setting up eFront on a Windows 2012 R2 server, using IIS 8.5. For the sake of the guide, we will start off with a brand new Windows 2012 R2 Datacenter installation on the Azure Cloud.

Note! If you will be using Internet Explorer, then the first thing to do is to turn off IE’s Enhanced Security Configuration, from the server manager → local server.

IE_Enhanced_Security.png

  1. Launch the Server Manager and click on “Add Roles and Features” to start the wizard.

  2. Click on next, accepting defaults, until you reach the “Select server roles” page.

  3. Select “Web server (IIS)” from the list of check-boxes. A popup will prompt you to add additional features. Click on “Add Features” and then “Next”.

  4. Click on Next accepting defaults for the rest of the pages, until you reach the “Confirm installation selections” page. Click on “Install” and wait for the installation to complete, then click “Close”.

  5. From the “Tools” section of the server manager, launch the IIS Manager.

  6. Click on the small arrow next to the server name to expand it. You will be prompted to get started with Microsoft Web Platform (WebPl). Click “Yes” and a new web page will launch.

    Alternatively, you can launch this at any time by clicking on the “Get new Web Platform Components” link at the right.

  7. Click on “Free download” and accept to Run the file.

  8. The platform installer will launch and present a list of items. Search for “PHP” (in the search bar on the top-right corner) and select PHP 5.6.24 (or the latest version) and Windows Cache Extension 1.3 for PHP 5.6. Click on “Install” and “I Accept” on the terms popup that will appear.

  9. After the installation is complete, a results page will appear. Disregard the PHP Manager was not installed message – we won’t be needing it. Click on Finish and Exit the WebPI.

  10. For PHP 5.6, Download and install the x86 version of Visual C++ Redistributable for Visual Studio 2012 Update 4, from https://www.microsoft.com/en-us/download/details.aspx?id=30679 . Click on Next button, ignore potential warning about the file and accept to run it.

  11. Close the IIS Manager and open it again. This is important so that newly installed options may appear (such as the URL Rewrite).

  12. Expand the server name in the left pane and right click on the Default web site. Select “Remove”.

  13. Download and extract eFront inside the folder c:\inetpub\efront. We need to give proper write permissions, so right click on the eFront folder and click on Properties and then on the “Security” tab.

  14. Click on “Edit” then “Add” and type “IUSR” in the field “Enter the object names to select”. Click on “Check names” to verify that this user actually exists. Then click on “OK”.

  15. Click on the “Modify” option in the “Allow” column and click on “Apply”. The system will apply the selected permissions across all eFront files and folders.

    Warning: These are generic permissions that are suitable for a development/staging environment. For production environments, write access should be granted only on the folders described in the installation guide.

  16. On the IIS manager, right click on the Sites entry and select “Add Website”.

  17. On the website’s properties, enter “efront” for the name and “C:\inetpub\efront\www” as the physical path and click on “OK”.

  18. Back to the IIS properties, select the “eFront” site and double click on “URL Rewrite”.

  19. On the right pane, there is an option to “Import rules”. Click on it to bring up the “Import mod_rewrite rules” option.

  20. Under the “Configuration file”, click on the dots to navigate to the file: C:\inetpub\efront\www\.htaccess and then click on Import. The “Rewrite rules” and “Converted Rules” areas will be filled.

  21. On the “Converted rules” area, scroll to the bottom. You’ll notice that one rule generates an error – it’s because it’s not compatible with IIS, so we can safely remove it from the “Rewrite rules” page. Remove also subdomains part because it may cause installation issues.
    # Subdomain-specific rules:
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{HTTP_HOST} ^(?!www\.)([^.]+)\. [NC]
    RewriteRule !^subdomains/ subdomains/%1/www%{REQUEST_URI} [QSA,L]

    To continue, please make sure that under ‘Rewrite rules:’ window you have the following:

    RewriteEngine On

    # Normal setup:
    RewriteCond %{REQUEST_URI} !=/server-status
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [QSA,L]

    Note: If you want to enable the rest API feature you must also import the .htaccess file that is located in the /www/API directory. From the IIS Manager you must specifically select the API folder on the left and then add the rewrite rules.

    We remove the following lines from the .htaccess for it to work properly.
    RewriteRule ^ Index.php [QSA,L]

    # HTTP Basic Auth (f-cgi workaround):
    RewriteRule .* – [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

    The final .htaccess should look like this:

    RewriteEngine On

    # API:
    RewriteCond %{REQUEST_URI} !(v[1-9]mobile)
    RewriteCond %{REQUEST_FILENAME} !-f

    RewriteCond %{REQUEST_URI} (v[1-9]mobile)
    RewriteRule ^ ../index.php [QSA,L]

    Screen_Shot_2018-03-01_at_13.21.02.png

  22. As soon as the Rewrite rules are correct, you will notice that the “Apply” option, on the top-right, is enabled. Click on it to apply the rules and proceed.

  23. Next, we need to install the database server. You can do so from the MySQL website here: https://dev.mysql.com/downloads/windows/installer/5.7.html and download the Mysql 5.7 installer package (the small one should do).

  24. Click on “no thanks, just take me to the download page” if you don’t want to signup or login, and click on “run” for the downloaded package.

  25. Once the installer runs, accept the license agreement and perform a “Custom” installation.

  26. Expand the Mysql Servers option until you reach the MysqlServer X64 option, and add it to the “features to be installed” list.

  27. Execute the installation and wait for it to finish.

  28. Once it’s completed, click next to reach the configuration options. Select “Server Machine” for the Config Type.

  29. Enter a root password.

  30. Accept defaults in the following pages and click on Execute.

  31. Installation is now completed, click on Finish to close the installer. You can verify that everything is setup properly by locating the “Mysql Command line tool” program available in the Installed programs.

  32. This will launch the command-line interface for MySQL, which you can access by using your root password.


    Note: if you download and install MySQL 8, it by default uses `auth_soket` as an authentication system and not `password`. In this case, you will need to change the authentication as follows:

    1. Open Command Prompt (CMD) and access MySQL root `mysql -u root -pabc123`

    2. Run query: ` ALTER USER ‘root’@’localhost’ IDENTIFIED WITH mysl_native_password BY ‘password’;`, where ‘password’ is the password set in step 29.

  33. Open your browser and visit http://localhost. You should see eFront installation starting page.

  34. Click on Next and fill in the required information.

  35. Installation is successful! You are now signed in as administrator. You should fill in your license key.

  36. You can now start using the system. Click on the “Maintenance” section and then on “Information” to verify that all required and recommended components are in place (such as caching).

  37. In order IIS to work as expected with non English characters (umlaut etc) you have to run the following from command line (and restart IIS afterward):
    reg add HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\w3svc\Parameters /v FastCGIUtf8ServerVariables /t REG_MULTI_SZ /d REQUEST_URI\0PATH_INFO

Installing WinCache on IIS 

To drastically improve the performance of any high-traffic PHP website running under IIS you can consider installing one of the free caching PHP extension tools available: in this post we’ll cover the Microsoft one, namely WinCache, which is included in all the base PHP installation packages for Windows since version 5.2.

Installing WinCache is fairly easy. The first thing you need to do is to check whether the php_wincache.dll file is included in your PHP installation or not. This file is located in the /ext/ subfolder of your PHP installation folder. If it’s not there, you can download it manually from the WinCache official website (just be sure to pick the file matching your PHP version), unpack it and copy the .dll file to the aforementioned folder.

Then you need to enable the WinCache extension to your PHP installation by adding the following two lines to your php.ini file, which is usually located in your PHP installation folder OR in the Windows root folder:

reg[PHP_WINCACHE]
extension=php_wincache.dll

Note: Before you do that you might want to check if the extension is already enabled by doing a quick text search for “php_wincache.dll” inside the file.

If you’re using PHP Manager for IIS (which you really should) you could also install the WinCache extension directly from the PHP Manager GUI.

If you’re NOT using PHP Manager for IIS and/or you have no idea of where your php.ini file actually is, you can easily track it by executing the phpinfo() command on your server (if you don’t know how, just click here to download a sample script, put it on your server and execute it): as soon as you did that you can review your whole PHP configuration, which contains the full path of the currently Loaded Configuration File:

phpinfo.loaded.configuration.file_.jpg

That same phpinfo() command can be also used to check whether the WinCache extension has been properly installed or not. If that’s the case you will be able to see something like that by scrolling down a little:

phpinfo.wincache.jpg

In most cases, like the screenshot above, the system will tell you that all the caches are currently disabled: this is perfectly normal, since we didn’t activate any of them yet.

In order to do so, we need to add some additional configuration settings to our php.ini file:

 [WinCache]
; Full reference: http://php.net/manual/en/wincache.configuration.php
wincache.fcenabled = 1
wincache.ocenabled = 1
wincache.ucenabled = 0
wincache.fcachesize = 64
wincache.fcndetect = 1
wincache.maxfilesize = 256
wincache.chkinterval = 10
wincache.enablecli = 1
wincache.ucachesize = 8
wincache.scachesize = 8

These settings are generally OK for most production environments. You can fine-tune them by taking a look to the WinCache reference guide, where you will find a detailed description of any possible configuration setting to adapt WinCache to your needs.

When you think you’re done, save the php.ini file and restart IIS: you’ll be able to check the results of your hard work by executing the phpinfo() command again:

phpinfo.wincache.enabled.jpg

After completing setting up WinCache, you may access the WinCache panel from your eFront system, when logged in as administrator, visit Maintenance > Information > Cache.

Selection_009.png

Edit web.config file for increasing limits #

In case you face any issues that seems to be related with time or request limits although corresponding options for php are already set, you may have to set them for IIS too. Follow steps below:

1) Open <wwwrootDir>/<Web Service>/web.config

2) Add line for maxRequestLength and executionTimeout

<configuration>
    <system.web>
        <httpRuntime maxRequestLength="524288" executionTimeout="600" />
    </system.web>
</configuration>

For IIS7 and above, you also need to add the lines below:

 <system.webServer>
   <security>
      <requestFiltering>
         <requestLimits maxAllowedContentLength="524288000" />
      </requestFiltering>
   </security>
 </system.webServer>

3) Restart IIS

Note: Regular API and mobile API might have issues working with the default configurations. You might need to re-arrange the orders of change the IIS rules. The attached web.config has the appropriate rules and rules order.

 

Installing an SSL certificate on IIS from Let’s encrypt

Let’s encrypt is a service that offers free SSL certificates. Below we describe the process of installing a certificate from Let’s encrypt using a command line utility.

This utility tool runs from the command line and has a few very easy to understand options. Basically you pick a site from the list of active Web sites using host headers on your server and the utility goes out and creates a certificate for you, creates an https binding and attaches the certificate. If there’s already a certificate there the certificate is replaced with the new one.

You can install the latest version from their GitHub Releases page and simply unzip the zip file into a folder.

To run it, simply run the executable letsencrypt.exe.

 

Screen_Shot_2018-03-14_at_11.13.01.png

Once you run letsencrypt.exe you will be presented with the following screen:

Screen_Shot_2018-03-14_at_11.14.04.png

Press ‘N’ to create or update your SSL certificate

In the next screen, in the prompt “Which kind of certificate would you like to create?”, input the number ‘4’ (Manually input host names).

Once you have selected the above, enter your app host name (localhost, actual-domain.com etc) (do not prepend the hostname/s with http or https).

Screen_Shot_2018-03-14_at_11.16.22.png

If everything is correct, the LetsEncrypt script will detect your app/site installation referred by the hostnames you entered .

Enter the number of the site/app you wish to generate the SSL certificate for.

Screen_Shot_2018-03-14_at_11.17.36.png

The SSL certificate has now been installed.

To verify the certificate has been installed, open your IIS manager and head over to “Server Certificates”.

Screen_Shot_2018-03-14_at_11.18.05.png

You should see your certificate listed:

Screen_Shot_2018-03-14_at_11.18.11.png

Note: if you encounter difficulties uploading files after performing the above configuration, please check and change the upload_tmp_dir entry in your php.ini file.