Upgrading to DotNetNuke 3.x

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. Download the software.

2. Unzip the package.

3. Create a database in SQL Server.

4. Create a database login.

5. Set file permissions.

6. Configure IIS (Internet Information Server).

7. Configure web.config for installation.

8. Install.

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.

Figure 2-1

Note 

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.

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.

Note 

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.

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.

Figure 2-3

Note 

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.

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).

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.

Figure 2-5

Important 

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.

Figure 2-6

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.

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

Note 

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 uncheck Use Simple File Sharing (Recommended).

• Click OK.

The minimum permissions for the folders are as follows:

• 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.

Figure 2-8

Note 

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.

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

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.

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 <appSettings> 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 <appSettings> Section

 <appSettings>     <add key="SiteSqlServer" value="Server=(local);Database=DotNetNuke;uid=;pwd=;" />     <add key="MachineValidationKey" value="F9D1A2D3E1D3E2F7B3D9F90FF3965ABDAC304902" />     <add key="MachineDecryptionKey" value="F9D1A2D3E1D3E2F7B3D9F90FF3965ABDAC304902F8D923AC" />     <add key="MachineValidationMode" value="SHA1" />     <add key="InstallTemplate" value="DotNetNuke.install.resources" />     <add key="AutoUpgrade" value="true" />     <add key="UseDnnConfig" value="true"/>     <add key="InstallMemberRole" value="true" />         <!-- Show missing translation keys (for development use) -->     <add key="ShowMissingKeys" value="false" />     <add key="EnableWebFarmSupport" value="false" />     <add key="EnableCachePersistence" value="false" /> </appSettings> 

Following is what you need to know about these settings:

• SiteSqlServer: This node contains the connection string to your database. Change the corresponding attributes to specify the server, name, username, and password of your database. Here's a sample connection string for SQL Server 2000:

   <add key="SiteSqlServer" value="Server=(local);Database=DotNetNuke;uid=  DotNetNukeUser;pwd=DotNetNukeUser;" /> 

• 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).

• 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

 <data defaultProvider="SqlDataProvider">   <providers>     <clear />     <add name="SqlDataProvider"        type="DotNetNuke.Data.SqlDataProvider, DotNetNuke.SqlDataProvider"        connectionStringName="SiteSqlServer"        upgradeConnectionString=""        providerPath="~\Providers\DataProviders\SqlDataProvider\"        objectQualifier=""        databaseOwner="dbo" />   </providers> </data> 

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)

Step 8: Perform the Installation

Verify that you have performed all seven of the preceding steps:

1. Obtained the latest source code from www.dotnetnuke.com.

2. Unzipped the latest source code to a local file directory.

3. Created a new database for the application.

4. Created a new database user to connect as.

5. Set file permissions on the local file directory.

6. Created a new virtual directory in IIS.

7. 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

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. The installer reports the version of the template being installed (Installing Version: 3.1.0).

2. The installer reports that the SQL installation scripts were executed:

   • DotNetNuke.Setup.SqlDataProvider

   • DotNetNuke.Schema.SqlDataProvider

   • DotNetNuke.Data.SqlDataProvider

3. The install reports that the SQL common scripts were executed:

   • InstallCommon.sql

   • InstallMembership.sql

   • InstallProfile.sql

   • InstallRoles.sql

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:

   • Host Settings

   • SuperUser

6. The modules are installed.

7. The portals are created.

8. 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.