INSTALLATION TROUBLESHOOTING

By the time you have arrived at this chapter you have probably already successfully installed Umbraco, perhaps even multiple times. Then comes the time when your Umbraco installation fails. What to do? A methodical approach to identifying the issue goes a long way toward a quick solution.

Unless the issue is very obvious, perhaps an error message that states the problem, review the following checklist to help identify the cause:

• Are file permissions set correctly?
• Is Umbraco configured in a virtual directory?
• Does the IIS application pool .NET Runtime version match the Umbraco .NET runtime version?
• Are all of the files present?

Each item of this checklist is examined in greater detail in the following sections.

Are File Permissions Set Correctly?

File permissions are by far the most common issue with Umbraco installations. The identity of the IIS application pool must have sufficient permissions to be able to read, write, and modify certain files in your Umbraco instance. For local and development installations, granting the IIS application pool identity read, write, and modify rights to all files located in your instance is sufficient. For production sites, best practice is to grant the IIS application pool identity more granular rights because not all files should have these permissions applied.

You can locate the identity of an IIS application pool by viewing the Advanced Settings of the application pool from IIS Manager (see Figure 14-1). On most IIS installations, the IIS Application Pool identity will be set to ApplicationPoolIdentity or Network Service. In the case of ApplicationPoolIdentity, IIS will dynamically create the account when an application pool is started, and therefore this account provides the most security for your applications.

FIGURE 14-1

If you use the Microsoft Web Platform Installer to install Umbraco, these settings will be configured appropriately by the tool and you will not need to adjust the settings.

Is Umbraco Configured in a Virtual Directory?

Umbraco is not intended to be run from a virtual directory. From IIS Manager a virtual directory is easily identified as a subfolder under an IIS site. Although Umbraco may mostly function when configured in a virtual directory, you may encounter unexpected behavior with this configuration. You can remove the virtual directory from beneath an IIS site and create a new IIS site with the Umbraco installation location as the home directory.

Does the IIS Application Pool .NET Runtime Version Match the Umbraco .NET Runtime Version?

With the various versions of the .NET Runtime (1.1, 2.0, 3.5, 4.0) and the various .NET Runtime versions targeted by Umbraco (2.0/3.5, 4.0) it's no wonder some confusion surrounds this issue. A common symptom of this issue is a very generic error displayed in the browser, “Service Unavailable.” The solution to this issue is very simple. Check the Umbraco version you have, which is clearly indicated by the name of the Umbraco Installation Package, and make sure it matches the .NET Runtime version. Typically the .NET Runtime version is indicated as the last part of the name, “Umbraco 4.5.2 for .NET 4.” You can find the .NET Runtime version for the IIS application pool from the Basic Settings dialog of the application pool's settings (see Figure 14-2).

FIGURE 14-2

Are All the Files Present?

If you installed Umbraco with the Microsoft Web Platform Installer, then not having all the files is very unlikely. However, if you installed Umbraco from a downloaded installation package that you extracted to a local directory on your web server, this issue is very common. Some recent versions of Microsoft Windows with specific User Access Control settings restrict the type of files that can be extracted from a .ZIP file from an unknown source, such as a website. Although this behavior is designed to protect operating systems from malicious files, it also protects some operating systems from files you want, such as Umbraco installation files.

A common symptom is that the Umbraco user interface will load, but it will be missing some of the layout elements and not all items in the content tree will display. The solution is to simply unblock the Umbraco Installation package from the file properties dialog before extracting the files to the target location on the file system (see Figure 14-3).

FIGURE 14-3

Database-Related Installation Issues

Fortunately, database-related installation issues are some of the easiest to identify and fix. Generally, an error message indicates that Umbraco cannot connect to the specified database and the Umbraco Installation Wizard checks for a valid connection before completing the installation. Umbraco expects the database, usually a Microsoft SQL Server database, to allow SQL authentication. However, the default installation settings for Microsoft SQL Server have SQL authentication disabled.

To enable SQL authentication, simply update the setting for Server Authentication to SQL Server and Windows Authentication Mode from the Server Properties dialog for the Microsoft SQL Server instance you are using (see Figure 14-4). To access this property dialog, follow these steps:

FIGURE 14-4

1. Open SQL Server Management Studio and login as a Server Administrator (usually this is the built-in Windows user account or the SQL “sa” account).
2. Right-click the SQL instance you are using, select Properties from the menu, and then select the Security option from the Select a Page list.
3. Make updates as required.
4. When you're finished, click the OK button to update SQL Server with your changes.

Umbraco stores database connection information in the web.config file, under the appSettings key umbracoDbDSN. A typical connection string value for this key is:

<add key=“umbracoDbDSN” value=“server=./SQLEXPRESS;database=umbDB;
user id=umbDBUser;password=secretPassword” />

This key must contain valid connection information in order for Umbraco to be able to connect to your database. Using the values from the key and Microsoft SQL Server Management Studio, you can connect to the specified database. If you cannot, Umbraco cannot connect either. Carefully check the values to make sure they are valid.

When you are installing Umbraco in an environment where you may not have complete control of the database settings and users, you may not have access to the database administrator password. In this case the input fields in the Microsoft Web Platform, and other tools, for the database administrator name and password will not be applicable. In this case, you will need a SQL Server login account that has rights to create a new database. In addition, you'll need a SQL Server login account that has rights to create a new login. If you do not have a SQL Server login account with these rights, which you may not in a shared hosting scenario, you should ask the host's support team to create an empty database and assign a login to the database for your use. After you have this information, you can update the input fields and successfully connect to your Umbraco database.