- Installing Umbraco 7 (Part 3) - Setting up IIS & File Permissions
Installing Umbraco 7 (Part 3) - Setting up IIS & File Permissions
For the first part in this series of blog posts, which details the process that I followed to manually install Umbraco CMS version 7.3.0, I documented the steps to successfully set up a new empty project in Visual Studio 2013 and how to download and install the Umbraco CMS package to your solution using NuGet package manager. In the second part, I detailed the process I followed to successfully create a new database/user in Microsoft SQL Server 2008R2 and update the applications connection string so that we can communicate with our new database.
For part three I am going to provide the steps I followed to allow us to host our Umbraco CMS application locally using Internet Information Services (IIS) 7.5. This will include
- Creating a new website and application pool in IIS
- Adding an entry to the windows hosts file
- Configuring the folder/file permissions to ensure that IIS has sufficient access to our application files
Polite Notice: With regards to working with Umbraco, I am still very much learning the ropes myself, but I continue to research and ask questions to help enhance my existing knowledge so that I can keep applying what I believe are the best practices.
With this in mind, the information that I have made available is purely based on my experiences. Therefore, if you are reading my posts and there happens to be a better way to complete a certain process, or you feel that I have explained something wrong, please get in touch with me so that I can make the necessary updates to provide more accurate information to help others.
The primary aim of producing this series of blog posts and making them available online is to hopefully provide a helping hand to anyone who is just starting out with Umbraco and trying to get up and running quickly. Using my experiences, I know that I would have benefited from something similar when I first started out, so hopefully my posts will help someone.
Let’s Get Started!
Adding a new website in IIS to host our Umbraco application locally
Step 26 – Launch IIS, in the left hand CONNECTIONS pane expand your connection to reveal APPLICATION POOLS and the SITES folder. Right click the sites folder and select the ADD WEB SITE… option from the context menu.
Step 27 – In the ADD WEBSITE dialog complete the following tasks
- Choose a SITE NAME for your new website – Again to remain consistent I tend to use a convention where I call my sites in IIS the same name as my visual studio project but start each one with LOCAL. So my website name in IIS would be LOCAL. INSTALLINGUMBRACODEMO.
Application Pool Brief Overview
In IIS 7.5 there is a security feature called the APPLICATION POOL IDENTITY which allows you to run an APPLICATION POOL under a unique account. When an application pool is created in IIS, by default the IDENTITY property of the new application pool will be set to APPLICATIONPOOLIDENTITY.
Also when a new application pool is created, by default the IIS ADMIN PROCESS (WAS) will create a new virtual account (which will have the same name as the application pool) and run the application pool's worker processes (W3WP.EXE) under this account.
Whenever a new application pool is created, the IIS management process creates a SECURITY IDENTIFIER (SID) that represents the name of the application pool itself. For example, for my application pool, which is named LOCAL.INSTALLINGUMBRACODEMO, a security identifier with the name LOCAL.INSTALLINGUMBRACODEMO is dynamically created in the Windows Security system. From this point on, resources can be secured by using this identity.
It’s important to note that the identity (local.installingumbracodemo) is not a real user account meaning it will not show up as a user in the Windows User Management Console.
When there are issues with your code you can attach to the worker process running within an application pool which will allow you to step through, inspect and debug the code.
Use the ellipse button, update the PHYSICAL PATH to be the application's root directory (see second image below). If you have been following everything that I have been doing in this tutorial then this location is likely to be where the visual studio creates your new projects.
In the BINDING section, leave all the default settings as they are, they should be set to something like the following
- BINDING TYPE: HTTP
- IP ADDRESS: All Unassigned
- PORT: 80
- When defining the HOSTNAME I use my naming convention which is to enter a name that corresponds to the new website name. So, in my case, this value will be local.installingUmbracoDemo.
Step 28 – When you have selected ‘OK’ to complete creating your new website, if you expand the SITES node in the CONNECTIONS pane you should notice that a new website has been created.
Step 29 - In the CONNECTIONS pane select the APPLICATION POOLS node which will display all the application pools that you have defined in IIS. From the list, find your application pool (mine is called local.installingUmbracoDemo), right click and select ADVANCED SETTINGS…
Step 30 – In the ADVANCED SETTINGS dialog, ensure that the following settings are configured
- .NET FRAMEWORK VERSION: v4.0
- MANAGED PIPLINE MODE: Integrated
- IDENTITY: ApplicationPoolIdentity
Step 31 – With the basics for configuring a new website in IIS completed, the next step is to add a new entry into the windows HOSTS file. To do this, right click Notepad (or any other text editor) and choose RUN AS ADMINISTRATOR from the context menu (we need administrator privileges to be able to edit the hosts file).
Step 32 – With your text editor running with administrator privileges go to FILE > OPEN and navigate to C:\WINDOWS\SYSTEM32\DRIVERS\ETC and choose to open the HOSTS file. If the hosts file is not showing, please ensure you have selected ALL FILES from the drop-down option.
Step 33 – Add a new entry (whatever you entered as the host name in step 27) to the HOSTS file. Please refer back to step 27 and ensure that you enter the same host name as you chose when setting up your new website in IIS. Choose to save and close the file. For my installation my hosts file entry would be
Configuring File and folder permissions
With a new website correctly configured in IIS and a new entry added to your windows hosts file you should be able to browse to your new local website. Open a web browser and browse to your local site (e.g. local.installingUmbracoDemo). You may be presented with an error which is similar to the following
As highlighted, this error is telling you that there are insufficient permissions configured to allow the application pool (configured in IIS) to access to the application files (e.g. unable to read the web.config file) that are located within the windows file system.
When attempting to install Umbraco, FILE PERMISSIONS are a common issue that many users face. Unfortunately, ensuring that you have the correct permissions defined may vary based on the version of Umbraco you are working with.
The main point to understand is that the IIS Application Pool Identity (e.g. local.installingUmbracoDemo) requires sufficient permissions to be able to MODIFY, READ and WRITE certain files in your Umbraco installation instance.
For local development (which is what we are doing) I always assign FULL CONTROL to the IUSR & IIS_IUSRS User Groups so that they have permission to MODIFY, READ & EXECUTE, LIST FOLDER CONTENTS, READ & WRITE. Using this approach helps to overcome any permission related issues during the installation process of Umbraco.
Once I have fully completed installing Umbraco I always revisit the permissions process and re-assign them based on what has been specified in the official documentation. This typically includes granting the IIS application pool identity more granular rights because not all files within the Umbraco installation should full control permissions applied. In a production environment its very important to be secure.
Note: Rather than adding the IIS_IUSRS user group (which is what all application pools running under ApplicationPoolIdentity are added to) to the file ACCESS CONTROL LIST (ACL), it’s even more secure to add just the Application Pools Identity instead. To do this, when you are selecting Users or Groups (see step 36), you would search for IIS AppPool\’NameOfApplicationPoolInIIS’.
Now that you have configured your new website in IIS and have added a new entry to your hosts file if you open a web browser and browse to your local site (e.g. local.installingUmbracoDemo) you may see something like the following server error
Lets Get those permissions configured!
Step 34 – Next, you need to ensure that the correct permissions are defined on the folder where your Umbarco application files reside. As my application files are located in DOCUMENTS\VISUAL STUDIO 2013\PROJECTS\INSTALLINGUMBRACODEMO\INSTALLINGUMBRACODEMO, I will set the permissions on the INSTALLINGUMBRACODEMO root folder. To do this, navigate to the folder, right click and select PROPERTIES from the context menu. Once inside the INSTALLINGUMBRACODEMO PROPERTIES dialog, select the SECURITY TAB and select EDIT….
Step 35 – Once in the PERMISSIONS FOR INSTALLINGUMBRACODEMO dialog select the ADD… button to enter the dialog where it allows you to add new Users or Groups.
Step 36 – In the SELECT USERS OR GROUPS dialog, you first need to enter the object name IIS_IUSRS (which is group type) and select the CHECK NAMES button to find this user group (if you can't find it, then try other locations). When you check for the name of this group if it is found, it will become underlined, and your computer name will be inserted before the group name e.g. YOURCOMPUTERNAME\IIS_IUSRS. Select OK once you have correctly found the group.
Note: It is at this point that you may want to just assign the permissions to the Application Pools Identity (IIS AppPool\local.installingUmbracoDemo) user rather than the entire IIS_IUSRS user group. In this demo, I will add and configure the permissions for the IIS_IUSRS User Group.
Step 37 – Once the IIS_IUSRS User Group has been added, the final step would be to define the sufficient permissions to ensure that this group can access the necessary application files e.g. read/write to the web.config file.
Now that your websites IIS Application pool has the necessary permission to access your application files, if you open a web browser and browse to your local site (e.g. local.installingUmbracoDemo), you may see something like the following server error. This server error typically means that there are also insufficient permissions assigned, and it’s likely that the install folder cannot be accessed.
Step 38 – To ensure that you don't experience the error above, you need to repeat steps 34-37 and grant the IUSR User Group permissions to access the application files (the install folder). By default, ANONYMOUS USERS are added to the IUSR User Group, and because Umbraco needs to access the internet during installation, you have to grant this user group permission to successfully complete the installation.
Note: It is advised to remove the install folder once you have completed installing Umbraco and reconfigure your permissions to ensure everything is secure. It’s important to note that in a production environment, configuring permissions incorrectly may cause some potential security risks, so please make sure that you educate yourself about permissions and configure them appropriately to stay as protected.
Allowing FULL CONTROL permissions for the IUSR user group will ensure that there are sufficient permissions for the installation to be completed locally.
At this point, you should have all the necessary permissions correctly configured to allow you to complete the final part of installing Umbraco manually.