Dot Net Install

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 55

Installing DotNetNuke Traditionally, web applications are deployed via xcopy (the process of copying multiple files from one place to another) and the execution of structured query language (SQL) scripts to initialize and upgrade the appropriate database schema. Advanced web applications such as DotNetNuke contain powerful installers that automate this process, improving the user experience and reducing the risk of missing an install step. This chapter presents a step-by-step guide to using the automated installer packaged with DotNetNuke and provides guidance in selecting a version of the software that is suitable for your organization. The objective of the chapter is to provide you with a working installation of DotNetNuke. Specifically, this chapter covers the following areas: ❑

What version of DotNetNuke should you use?

❑

Installing DotNetNuke v3.x.

❑

Upgrading an existing installation to v3.x.

❑

Installing DotNetNuke v4.x.

❑

Upgrading an existing installation to v4.x.

Selecting a Version At the time of writing, there are two major versions of DotNetNuke, each targeting a different version of the .NET Framework: ❑

DotNetNuke v3.x, directed at ASP.NET 1.1

❑

DotNetNuke v4.x, aimed at ASP.NET 2.0

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 56

Chapter 2 Each is functionally identical and your choice of version is dependent on your infrastructure (version of .NET Framework) and chosen development environment (Visual Studio 2003 versus Visual Studio 2005). You can upgrade a v3.x to a v4.x installation at a later date. After you select a version, proceed to the corresponding installation section in this chapter.

Installing DotNetNuke v3.x Ensure that you have met all prerequisites before proceeding to the installation steps for DotNetNuke v3.x.

Prerequisites Table 2-1 lists the software prerequisites for DotNetNuke v3.x

Table 2-1: DotNetNuke v3.x Software Prerequisites Software

Description

Web Server

Microsoft Internet Information Server 5 or greater (contained in Windows 2000 Server, Windows XP Professional, and Windows 2003 Server)

Microsoft .NET Runtime

ASP.NET 1.1 or later

Database

Microsoft SQL Server 2000 or greater

DotNetNuke v3.x has an additional prerequisite not supported by all third-party web hosts: you must be able to at least specify Read, Write, and Modify permissions on the root installation folder. Before signing up for a third-party hosting plan, ensure that you will be able to do so.

Installation Steps To install DotNetNuke v3.x, follow these steps, which are fully explained in the subsequent sections:

1. 2. 3. 4. 5. 6. 7. 8. 56

Download the software. Unzip the package. Create a database in SQL Server. Create a database login. Set file permissions. Configure IIS (Internet Information Server). Configure web.config for installation. Install.

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 57

Installing DotNetNuke Step 1: Download the Software You can download the latest version of the DotNetNuke software from the official DotNetNuke web site (www.dotnetnuke.com), shown in Figure 2-1. You must be a registered user to reach the download page. Registering is easy — just select the Register link in the top-right portion of the screen and follow the directions.

Figure 2-1

Choose the DotNetNuke 3.x package that’s right for you: ❑

Install package (DotNetNuke_X.Y.Z_Install.zip): Contains only the files necessary to run the application. Use this package if you don’t expect to do any modifications to core files.

❑

Source package (DotNetNuke_X.Y.Z_Source.zip): Contains all the files related to the core DotNetNuke project, including all Visual Basic source files. Use this package if you expect to modify core files or want to view the associated source.

Step 2: Unzip the Package Extract the entire contents of the zip file to your chosen installation directory. On a local intranet installation, you can place your web site anywhere (for example, c:\websites\dotnetnuke\). On a remote hosting server, you need to upload the files to your web site following the procedures provided by your hosting provider. To extract a zip file, you can use either the built-in zip functionality of Windows XP or a third-party compression tool such as WinZip, which you can obtain from www.winzip.com.

57

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 58

Chapter 2 Step 3: Create a Database in SQL Server Create the database to contain your data for the DotNetNuke application. In a remote hosting environment, your hosting provider probably has configured a SQL Server database for you, and can provide you with instructions for connecting to the database. In a local intranet installation, you need to manually create a new database. To perform this for SQL Server 2000, you need to have Enterprise Manager and the Microsoft SQL Server Client Tools installed. If you do not have these, you can install them from your Microsoft SQL Server installation CD. Open Enterprise Manager and expand the database server you want to create your database. If it’s not listed, you will have to register your SQL Server instance with Enterprise Manager. To do this, refer to the Enterprise Manager help. Now that you have found your database server — in this case, it is a local machine known as (local) — create your database by right-clicking the Databases node under your server and selecting New Database, as shown in Figure 2-2.

Figure 2-2

A dialog box appears asking for a database name. Put in any name and click OK. This example uses the name DotNetNuke, as shown in Figure 2-3. Further configuration options are listed on the Data Files and Transaction Log dialog, but for this installation, just accept the defaults. For more information about these options, see the Help file that comes with Enterprise Manager.

58

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 59

Installing DotNetNuke

Figure 2-3

Step 4: Create a Database Login Strictly speaking, you have two options in creating a user account to access your database: ❑

Windows Security: Uses the account that your application is running under to access the database. (This is the more secure option, but it is not supported in all environments, particularly in shared hosting).

❑

SQL Server Security: Uses a username-and-password combination to access the database.

For the purposes of this book, SQL Server Security is used, but we encourage you to explore Windows Security, especially in intranet environments. Create a user account for the database in Enterprise Manager by first navigating to the Security node located at the top level of the server you are connecting to. Expand it and select the Logins node. A list of users who already have access to your database server appears in the right pane. Right-click the Logins node and select New Login (as shown in Figure 2-4).

59

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 60

Chapter 2

Figure 2-4

A dialog box appears that prompts you for details about the account. In this case, create a user called DotNetNukeUser, and use that name for the password as well. Make sure you select the SQL Server Authentication radio option (otherwise you’ll be creating an account for Windows Authentication), and set the example database DotNetNuke as the default for this login. Figure 2-5 shows the dialog box with the details filled in.

If you are unable to select the SQL Server authentication option, ensure that your database is running in Mixed Mode access, a setting that can be configured on the Properties dialog box of your database.

Before you click OK, there is one more step to perform. Although you selected DotNetNuke as the default database, you still need to grant the new user Read and Write access to it. To do this, select the Database Access tab and check the Permit check box next to the DotNetNuke database. In the Database Roles list at the bottom of the tab, check the Permit box for db_owner privileges, which the user must have to create and delete database objects. Figure 2-6 shows the correct settings. After you have them set, click OK, confirm the password as prompted, and click OK again. The new account should appear in the right task pane whenever you select the Logins node. You can come back here anytime to change details about this particular account.

60

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 61

Installing DotNetNuke

Figure 2-5

Figure 2-6

61

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 62

Chapter 2 Step 5: Set File Permissions The ASP.NET worker process requires NTFS (file) permissions to be set so that DotNetNuke can create directories and files for advanced functionality such as the file manager, multi-portal creation, and so on. The user account that must have additional permissions depends on the version of Windows you are running: ❑

Windows 2000/Windows XP Professional (IIS5): {Server}\ASPNET User Account

❑

Windows 2003 (IIS6): NT AUTHORITY\NETWORK SERVICE User Account

To set the correct file permissions, open File Explorer and navigate to your installation folder (C:\ websites\DotNetNuke\, for instance). Right-click the folder, select Properties, and choose the Security tab (see Figure 2-7).

Figure 2-7

If you are cannot see the Security tab, you must disable Simple File Sharing. Here’s how: ❑

Select Start ➪ My Computer ➪ Tools ➪ Folder Options ➪ View.

❑

Scroll to the bottom of the list of advanced settings and un-check Use Simple File Sharing (Recommended).

❑

Click OK.

The minimum permissions for the folders are as follows:

62

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 63

Installing DotNetNuke ❑

Root (and all child folders): Read and Write access

❑

/DesktopModules: Write and Modify access

❑

/Portals (and all child folders): Write and Modify access

An additional permission is required if you plan to create child portals or install additional language packs: ❑

Root (and all child folders): Read, Write, and Modify access

Step 6: Configure IIS (Internet Information Server) The next step in the process is to create a new web site pointing at the DotNetNuke installation files. To configure your web server, use the IIS management console. To run the management console, select Start ➪ Run, type inetmgr, and click OK. Alternatively, you can access the console via the Windows Control Panel by selecting Administrative Tools ➪ Internet Information Services. The administration console for IIS appears, showing a node with the local computer’s name. Expand this item to reveal the list of web sites on the local computer. Expand the Default Web Site node. Figure 2-8 shows the default web site that is automatically configured when IIS is installed. If your IIS is not hosted on the local computer, you can remotely administer IIS by right-clicking the Internet Information Services node, selecting Connect, and following the on-screen prompts to connect to the remote computer.

Figure 2-8

63

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 64

Chapter 2 Right-click Default Web Site and select New ➪ Virtual Directory. The Virtual Directory Creation Wizard appears as shown in Figure 2-9.

Figure 2-9

Click Next to proceed. Enter the name of your virtual directory (DotNetNuke, for example) as shown in Figure 2-10, and then click Next.

Figure 2-10

64

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 65

Installing DotNetNuke Select the installation directory chosen earlier (for example, C:\Websites\DotNetNuke), as shown in Figure 2-11.

Figure 2-11

Click Next. The last step is to specify the permissions applicable for the virtual directory. Keep the defaults of Read and Run Scripts, click Next, and then click Finish. Figure 2-12 shows the correct list of access permissions.

Figure 2-12

You have now completed configuration of IIS, so close the management console.

65

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 66

Chapter 2 Step 7: Configure web.config for Installation All ASP.NET applications require a central configuration file called web.config. This file is used to store application-specific settings such as database connection and encryption strings. By default, DotNetNuke does not come with this configuration file. Instead, it contains release.config and development.config files, which are optimized for different environments, production or development, respectively. For the purposes of this installation, use the release.config file by renaming it web.config. Once you have renamed the file, open it in your favorite text editor. The web.config file contains a number of settings, some of which you will need to adjust. There are five settings in the section that control the installation or upgrade. Listing 2-1 shows the section with the settings that control installation in bold.

Listing 2-1: The Section

Following is what you need to know about these settings: ❑

SiteSqlServer: This node contains the connection string to your database. Change the corre-

sponding attributes to specify the server, name, username, and password of your database. Here’s a sample connection string for SQL Server 2000:

❑

InstallTemplate: This setting points to an XML file that allows additional control over the installation process. By customizing this file, an administrator can modify the default security accounts, host settings, and portals to be created. Unless you are an advanced user, leave this file in the default configuration.

❑

AutoUpgrade: This setting determines whether the installation or upgrade process automatically runs when a difference in version is detected. If it is set to true, anytime DotNetNuke

determines that the current running code is a higher version than the database, an install or an upgrade will automatically take place. If it is set to false, DotNetNuke will report the differences and then stop. The default setting is true. Set it to false only when you want to manually initiate the install process by navigating to (http://{siteURL}/Install/Install.aspx).

66

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 67

Installing DotNetNuke ❑

UseDnnConfig: This setting is tied to the check that DotNetNuke performs when comparing the version of the assembly and the version of the database during the installation or upgrade process. To prevent multiple database hits, a file called dnn.config is cached in the install folder; it contains the current version number of the database’s schema. This setting determines whether DotNetNuke examines this file or queries the database directly. The default is true and, for performance reasons, that works best in most cases.

❑

InstallMemberRole: This setting enables you to control the installation of the member role

scripts that are packaged with DotNetNuke. These scripts initialize tables and stored procedures used to centrally store user and role information. They require a higher level of permission in your database (database owner) and may need to be initialized through another security account (pre-installation). The default setting is true. Use false only when you want to manually install those scripts. A data provider section (see Listing 2-2) is defined further down the web.config file. There are two options in the default SQL Server provider that you may want to customize. Those options are bold in the listing.

Listing 2-2: The Data Provider Section <providers>

Here’s what you need to know about these settings: ❑

objectQualifier: This setting enables you to set a prefix to any of the objects created within your database. For example, if you specify an object qualifier of dnn_, the users table will be created as dnn_users. It is recommended that you specify this setting if multiple applications might need to use the same database.

❑

databaseOwner: This setting identifies the database user that owns the objects DotNetNuke will create in the database. By default, it is set to the database owner role (dbo) and in most

cases should be left at this setting. However, in some situations, the owner of the database might not grant you database owner (db_owner) privileges to the database (for example, third-party hosting). In these cases, set the databaseOwner attribute to the identity of your user. If the user is not a database owner, the user must have at least the following permissions: ❑

db_datareader (necessary for DotNetNuke)

❑

db_datawriter (necessary for DotNetNuke)

❑

db_ddladmin (necessary for MemberRoles)

❑

db_securityadmin (necessary during installation of MemberRoles)

67

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 68

Chapter 2 Step 8: Perform the Installation Verify that you have performed all seven of the preceding steps:

1. 2. 3. 4. 5. 6. 7.

Obtained the latest source code from www.dotnetnuke.com. Unzipped the latest source code to a local file directory. Created a new database for the application. Created a new database user to connect as. Set file permissions on the local file directory. Created a new virtual directory in IIS. Configured web.config with your application-specific settings (for example, database connection, and so on).

If you have completed all of these steps, open your web browser and navigate to http://localhost/ dotnetnuke/ for a local install or to http://www.mydomain.com/ for a remote install. The AutoUpgrade function (discussed in step 7) detects if the database is empty. If the AutoUpgrade setting is false, a “Site Unavailable” page (see Figure 2-13) appears. The administrator can then trigger the install by navigating to one of the following URLs: ❑

Local install: http://localhost/dotnetnuke/Install/Install.aspx?mode=Install

❑

Remote install: http://www.mydomain.com/Install/Install.aspx?mode=Install

Figure 2-13

68

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 69

Installing DotNetNuke If the AutoUpgrade is set to true, the installation process begins automatically, as shown in Figure 2-14.

Figure 2-14

The installation process logs significant events on the page. Take a look at the steps performed:

1. 2.

3.

The installer reports the version of the template being installed (Installing Version: 3.1.0). The installer reports that the SQL installation scripts were executed: ❑

DotNetNuke.Setup.SqlDataProvider

❑

DotNetNuke.Schema.SqlDataProvider

❑

DotNetNuke.Data.SqlDataProvider

The install reports that the SQL common scripts were executed: ❑

InstallCommon.sql

❑

InstallMembership.sql

❑

InstallProfile.sql

❑

InstallRoles.sql

69

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 70

Chapter 2 4.

The install reports that the incremental upgrade SQL scripts were executed (Upgrading to version: 3.1.1, Upgrading to version: 3.2.0, and so on).

5.

The sections of the Install template are parsed:

6. 7. 8.

❑

Host Settings

❑

SuperUser

The modules are installed. The portals are created. Optional resources, such as additional skins, containers, and so on, are installed.

After the install is completed, follow the Click Here To Access Your Portal link to visit your new DotNetNuke site.

Upgrading to DotNetNuke 3.x The upgrade process for DotNetNuke is very similar to the installation process. It contains an automated process but with fewer steps because the infrastructure is already in place. Here’s what to do:

1.

Back up your site. Before upgrading a site, it is recommended that you back up your entire site. This includes a backup of all site files and a full database backup. At a minimum, you must back up your web.config file.

2.

Download the software. As described earlier in this chapter, obtain the latest release of the software from the official DotNetNuke site (www.dotnetnuke.com). Refer to the “Select a Version” section earlier in this chapter for information about which package to choose.

3.

Unzip the package. After you have backed up your web.config file, you can extract the new version of DotNetNuke over your existing version.

4.

Configure web.config for upgrade. As mentioned earlier, the installation package no longer includes a copy of web.config. The package does not contain this file because it contains password hash keys used for database encryption. If these keys had been changed in your existing install and were to be accidentally replaced, your users would no longer be able to log in to your site. The hash keys are found in the web.config file as shown in Listing 2-3.

Listing 2-3: Password Hash Keys

The exact steps for configuring your upgraded site are as follows:

70

1.

Make a backup copy of your existing web.config file (for example, web.config.resources).

2.

Rename release.config to web.config.

3.

Replace the values for the following in your new web.config, with the values in your backup:

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 71

Installing DotNetNuke SiteSqlServer MachineValidationKey MachineDecryptionKey

InstallationDate (This may not be present in web.config, so add the key that is in web.backup.resources to web.config.) web.backup.resources is the recommended name for a backup of web.config. 4.

5.

Make any other changes to web.config that you made to support additional providers, and so on.

Perform the upgrade. First, verify that you have done the following: ❑

Backed up your entire site and database (or at least your web.config file).

❑

Obtained the most suitable package from www.dotnetnuke.com.

❑

Unzipped the package over the top of your existing installation.

❑

Renamed your web.config file (for example, to web.config.resources).

❑

Renamed release.config to web.config.

❑

Copied the password hash keys (and any other setting you customized) from your old web.config file to your new web.config file.

When you have completed all of those steps, open your web browser and navigate to http:// localhost/dotnetnuke/ for a local upgrade or http://www.mydomain.com/ for a remote upgrade. The AutoUpgrade function detects if the database requires an upgrade. If the AutoUpgrade setting (discussed earlier) is set to false, a “Site Unavailable” page like the one you saw in Figure 2-13 will appear. The administrator can then trigger the install by navigating to one of the following URLs: ❑

Local install: http://localhost/dotnetnuke/Install/Install.aspx? mode=Install

❑

Remote install: http://www.mydomain.com/Install/Install.aspx? mode=Install

If the AutoUpgrade is set to true, the installation process begins automatically as shown in Figure 2-15. The upgrade process logs significant events on the page. Take a look at the steps performed:

1. 2. 3.

The installer reports the new version of DotNetNuke to be installed (Version: 3.2.2).

4. 5.

The installer reports that general upgrades were performed.

The installer reports the current version of DotNetNuke installed (Version 3.2.0). The installer reports that the incremental-version upgrade SQL scripts were executed (Upgrading to version: 3.2.1, Upgrading to version: 3.2.2, and so on).

The installer reports all modules that are installed as part of the package (these may be upgrades of existing modules).

71

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 72

Chapter 2

Figure 2-15

When the upgrade is complete, follow the Click Here To Access Your Portal link to visit your upgraded DotNetNuke site.

Installing DotNetNuke 4.x DotNetNuke 4.0 is the first version of DotNetNuke to be targeted at ASP.NET 2.0. (Version 3.2 will run on ASP.NET 2, but it requires Visual Studio 2003 and .NET 1.1 for any development work.) To further support ASP.NET 2.0, a new installation package — the DotNetNuke Starter Kit — has been added for DotNetNuke 4.0. A starter kit is a new project type for Visual Studio 2005 and Visual Web Developer Express. Essentially, it adds a new project type to your selected development environment and enables you to choose New DotNetNuke Site from the New Project menu.

Prerequisites Table 2-2 lists the software prerequisites for DotNetNuke v4.x.

72

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 73

Installing DotNetNuke Table 2-2: DotNetNuke v4.x Software Prerequisites Software

Description

Web Server

Microsoft Internet Information Server 5 or greater (contained in Windows 2000 Server, Windows XP Professional, and Windows 2003 Server)

Microsoft .NET Runtime

ASP.NET 2.0 or later

Database

Microsoft SQL Server 2000 or greater

Development Environment

Optional: If you plan to use the Starter Kit (not mandatory), you need either Visual Studio 2005 or Visual Web Developer.

DotNetNuke 4.x has an additional prerequisite that is not supported by all third-party web hosts: you must be able to specify at least Read, Write, and Modify permissions on the root installation folder. Before signing up for a third-party hosting plan, ensure that you will be able to assign these permissions.

Downloading the Software The first step in the installation process is to obtain the DotNetNuke software. The latest version of the software can be downloaded at the official DotNetNuke web site, www.dotnetnuke.com. As noted earlier, you must be a registered user to reach the download page. DotNetNuke 4.x is available in Source, Install, or Starter Kit packages: ❑

Starter Kit package (DotNetNuke_X.Y.Z_StarterKit.vsi): Contains a Project Template (based on the Install package), a Module Item Template (in both Visual Basic.NET and C#), and a Skin Item Template. The supporting class libraries, providers, and HttpModules are provided as precompiled assemblies (DLLs).

❑

Install package (DotNetNuke_X.Y.Z_Install.zip): Contains only the files necessary to run the application. Use this package if you don’t expect to do any modifications to core files.

❑

Source package (DotNetNuke_X.Y.Z_Source.zip): Contains all the files related to the core DotNetNuke project, including all Visual Basic source files. Use this package if you expect to modify core files or want to view the associated source.

In deciding which package to use, determine what your development environment will be because Visual Web Developer Express (VWD) does not support any project type other than web sites. If you expect to do most of your development in VWD rather than Visual Studio 2005 (VS2005), you will not be able to use the Source package. Visual Web Developer is an alternative, low-cost development environment available from http:// msdn.microsoft.com/vstudio/express/vwd.

The following sections cover the installation of the new Starter Kit and the differences in the installation procedure for the Source/Install version. If you need more information on the Source/Install version, refer to the relevant section in the v3.x procedure.

73

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 74

Chapter 2

Installing the Starter Kit To install the Starter Kit, follow these steps:

1.

Double-click the MSI file in Windows Explorer. The Visual Studio Content Installer, shown in Figure 2-16, launches.

Figure 2-16

74

2. 3.

Select the templates you would like to install (by default, all are selected). Click Next.

4.

The installer is ready to install the items you selected (see Figure 2-18). Click Finish.

The packages are not signed with a Digital Certificate, so you will get the warning shown in Figure 2-17. Select Yes.

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 75

Installing DotNetNuke

Figure 2-17

Figure 2-18

5.

As Figure 2-19 shows, the installer lets you know when it has successfully completed its job. Click Close.

75

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 76

Chapter 2

Figure 2-19

You can now create a new DotNetNuke project. In Visual Studio 2005 or Visual Web Developer Express, select File ➪ New Web Site. The New Web Site dialog box opens, as shown in Figure 2-20.

Figure 2-20

76

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 77

Installing DotNetNuke In the My Templates section, choose the DotNetNuke Web Application Framework template. At the bottom of the dialog box, specify a location and a language, and click OK. A web site is created in the folder you specified, and the Welcome.html file (see Figure 2-21) automatically opens in the internal browser.

Figure 2-21

Welcome.html provides further instructions on how to complete the installation on your local machine.

Installing the Install/Source Package This section focuses only on the differences between the v3.x and v4.x Install/Source installations. For more detailed instructions, see the appropriate section in the v3.x installation instructions. You’ve already downloaded the software, so we’ll start with step 2.

Step 2: Unzip the Package Like the v3.x installation, you have to extract your chosen installation package to a physical location on your computer.

77

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 78

Chapter 2 Due to changes in the web project model for Visual Studio 2005, it is recommended that you extract the package as follows:

1. 2.

3.

Create a directory where the application will reside (c:\websites\dotnetnuke, for example). If you are using the Install package, do the following: ❑

Create a subdirectory called website (such as c:\websites\dotnetnuke\website).

❑

Extract the Install package into the website subdirectory you just created.

If you are using the Source package, extract the entire package to the original folder you created (c:\websites\dotnetnuke, for instance). The subfolders will be created automatically.

Steps 3–5: Set Up the Database, Login, and Permissions Create the database to contain your data for the DotNetNuke application, create a user account to access your database, and set NTFS permissions. To do this, follow the relevant instructions in the “Install DotNetNuke v3.x” section at the beginning of the chapter.

Step 6: Configure IIS (Internet Information Server) The next step in the process is to create a new web site pointing at the DotNetNuke installation files. Create a virtual directory in IIS called DotNetNuke (or whatever you choose) that points to the appropriate physical file directory. The appropriate directory depends on how you extracted your chosen package. If you are using the Install package, point IIS to the folder you extracted the files to. If you are using the Source package, point IIS to the \website folder. Ensure that your virtual directory is running ASP.NET 2.0 by right-clicking it and selecting Properties. The ASP.NET tab of the DotNetNuke Properties dialog box displays the version number (see Figure 2-22). You need version 2.0 or higher.

Step 7: Configure web.config for Installation Although the web.config file for DotNetNuke v4.x differs quite a bit from that used in DotNetNuke v3.x, most of the disparity is due to .NET2. As with v3.x, before doing anything else, rename release.config to web.config. Three major differences exist between the v3.x web.config and the v4.x web.config: ❑

Version 4.x needs the SiteSqlServer setting in just as v3.x does, but v4.x also requires the same connection string to be set in the section (see Listing 2-4). In other words, v4.x requires the connectionStrings setting in two sections, not just one.

Listing 2-4: Section
78

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 79

Installing DotNetNuke connectionString=”Server=(local);Database=DotNetNuke;uid=DotNetNukeUser; pwd=DotNetNukeUser;” providerName=”System.Data.SqlClient” / rel="nofollow">

❑

The machine key settings in the v3.x section — MachineValidationKey, MachineDecryptionKey, and MachineValidationMode — are in v4.x’s <machineKey> section (see Listing 2-5) located in the <system.web> section.

Listing 2-5: <machineKey> Section <machineKey validationKey=”F9D1A2D3E1D3E2F7B3D9F90FF3965ABDAC304902” decryptionKey=”F9D1A2D3E1D3E2F7B3D9F90FF3965ABDAC304902F8D923AC” decryption=”3DES” validation=”SHA1”/>

Step 8: Perform the Installation The v4.x installation process is identical to v3.x’s. Open your web browser and navigate to http:// localhost/dotnetnuke/ for a local install or http://www.mydomain.com/ for a remote install. When the installation completes, follow the Click Here To Access Your Portal hyperlink to access your new DotNetNuke 4.0 site.

Version number

Figure 2-22

79

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 80

Chapter 2

Upgrading to DotNetNuke 4.x The upgrade process for DotNetNuke is very similar to the installation procedure. It contains an automated process with fewer steps because the infrastructure is already in place. This section focuses on the differences between the upgrades of v3.x sites and v4.x sites. Here are the steps:

1.

Back up your site. As always, it is recommended that you back up your entire site before upgrading. This includes backing up all site files and your complete database. At a minimum, you must back up your web.config file.

2.

Download the software. As described earlier in this chapter, obtain the latest release of the software from the official DotNetNuke site (www.dotnetnuke.com). Refer to the “Select a Version” section near the beginning of this chapter for information about which package to select.

3.

Unzip the package. If you read the earlier section about installing a v4.x site, you know that the new web project model forced DotNetNuke to change its folder structure for the source version. This adds a level of complication for anyone upgrading from the v3.x source to the v4.x source. ❑

Upgrading v3.x to v4.x install only: If you are not worried about the source projects, you can upgrade your site in the following way by downloading the latest Starter Kit or install package: For the Starter Kit, create a new project in Visual Studio 2005 or Visual Web Developer Express (as described earlier in the chapter). Specify the location of your existing site. You are prompted with a warning that a site already exists at the location. Select the Create a New Web Site in the Existing Location option and press Enter. For the install package, extract the contents on to your existing site. When you are finished upgrading for install only, proceed to the “Configure web.config for Upgrade” section.

❑

Upgrading v3.x to v4.x source only: The situation is a little trickier if you want to upgrade to the Source version of DotNetNuke v4.0. Therefore, it’s recommended that you follow the instructions earlier in this chapter on how to install a DotNetNuke v4.x site, rather than overwriting in some way your old site. Then move any custom content — such as Modules, Skins, and Portal content — you have on your old site, as well as your web.config file, to the new site. In IIS, re-point the virtual directory to the website folder of the DotNetNuke v4.x site. This is the safest and simplest way to move your development from v3.x to v4.x. After you have completed this process, you are ready to configure your web.config file.

4.

Configure web.config for upgrade. As discussed earlier, the installation package no longer includes a copy of web.config. The exact steps for configuring your upgraded site are as follows: 1.

Make a backup copy of your existing web.config file (named web.config.resources, for instance).

2.

Rename release.config to web.config.

3.

Replace the following keys in your new web.config with the values in your backup: SiteSqlServer MachineValidationKey

80

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 81

Installing DotNetNuke MachineDecryptionKey InstallationDate (This may not be present in the new web.config, so add the key that is in web.backup.resources to web.config.)

web.backup.resources is the recommended name for a backup of web.config. 4.

Set to the same values as you just copied from your old web.config. This copies your database configuration to the new configuration file. Listing 2-6 shows the section.

Listing 2-6: Section

5.

Set the values of the machineKey element to the values that used to be in the appSettings node, as shown in Listing 2-7.

Listing 2-7: Password Hash Keys <machineKey validationKey=”F9D1A2D3E1D3E2F7B3D9F90FF3965ABDAC304902” decryptionKey=”F9D1A2D3E1D3E2F7B3D9F90FF3965ABDAC304902F8D923AC” decryption=”3DES” validation=”SHA1”/>

6.

5.

Make any other changes to web.config that you made to support additional providers, and so on.

Perform the upgrade. First, verify that you have done the following: ❑

Backed up your entire site and database (or at least your web.config file).

❑

Obtained the most suitable package from www.dotnetnuke.com.

❑

Installed the latest Starter Kit or unzipped the install package over the top of your existing installation.

❑

Renamed your web.config file (for example, to web.config.resources).

❑

Renamed release.config to web.config.

❑

Copied the password hash keys (and any other setting you customized) from your old web.config file to your new web.config file.

When you have completed all of those steps, open your web browser and navigate to http:// localhost/dotnetnuke/ for a local upgrade or http://www.mydomain.com/ for a remote upgrade. Alternatively, if you are using the Starter Kit, you will need to run your site by pressing Shift + F5. When you browse to your site, you get a report similar to the one shown in the v3.x upgrade section earlier in this chapter.

81

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 82

Chapter 2

Installation Issues The DotNetNuke Core Team has provided screens to assist in diagnosing problems associated with the installer. This section describes a couple of the more common error messages. If you cannot resolve your particular issue with this information, try the online support forums at www.dotnetnuke.com. ❑

Invalid Connection String. If you get the error message “Invalid Connection String,” your connection string is invalid in the web.config file. Confirm that the connection string is correct, the database has been created, and the user has access to the database.

❑

Insufficient File Permissions. An “Insufficient File Permissions” error could mean that you have not granted the correct access to the root of the folder, or that you specified a different account than the account currently running the ASP.NET request. See the “Set File Permissions” section earlier in the installation section for more information. Figure 2-23 shows the error page DotNetNuke displays if it doesn’t have the correct file permissions set.

Figure 2-23

82

06_788163 ch02.qxp

6/13/06

6:12 PM

Page 83

Installing DotNetNuke For the most current information about the installation process, refer to the “DotNetNuke Installation Guide” in the DotNetNuke documentation.

Summar y Installation for DotNetNuke comes in a variety of packages. Each package is targeted at a particular version of DotNetNuke (either v3.x or v4.x) and comes in a variety of flavors, as follows: ❑

Install package: Contains only the files necessary to run your portal. This package is recommended for non-developers.

❑

Source package: Contains all of the source code for DotNetNuke, allowing developers to modify and recompile their application.

❑

Starter Kit: Provides an additional project type for developers using Visual Web Developer Express or Visual Studio 2005. It enables them to easily create new DotNetNuke applications at the click of a button (v4.x only).

This chapter guided you through all of the necessary installation steps, including running an automated installer that provides guidance through the installation process.

83