Getting started - installation and maintenance

From Sense/Net Wiki
Jump to: navigation, search
This guide let's you know everything about installing, configuring and maintaining your Sense/Net portal. If you are a developer who wants to set up a development environment and start implementing applications, or if you are a system operator who wants to install Sense/Net to a live server: this is the place where you should probably start reading. No development or portal builder skills are required, but you will have to be familiar with XML and some administrative features of your operating system.

Please note that some sections require you to have a basic knowledge of managing content in Sense/Net. If you are new to Sense/Net please read Getting started - using Sense/Net guide in case you are instructed to log into the portal and manage different content.

System architecture

To learn more about the physical architecture of Sense/Net ECM, please visit the following article that offers an overview of the main components of the product:

Installation

Installation
There are two types of packages you can install Sense/Net from: a webPI package (Web deployment tool) and a source package. The following guide shows you which platforms are currently supported and helps you install the portal under different versions of IIS:

The following link will be helpful when installing Sense/Net to a live production environment:

After installing the portal make sure to properly configure url and authentication settings - read on to learn how to do this!

Site url and authentication settings

Url and authentication settings
The default site of the portal is configured to accept requests to http://localhost with Anonymous authentication. Authentication and site url settings are always given in pairs. You can change the default settings or add new url-authentication settings for the default site by editing the /Root/Sites/Default_Site (http://localhost/Explore.html#/Root/Sites/Default_Site This link works only if you have a live demo install on your localhost! (Don't forget! Some feature needs authentication and/or admin rights!)) default site content. Change the url-authentication settings in the Url settings field. When finished save the content and go to the administrative surface of your IIS webserver and set your IIS website to be in accordance with the portal site's settings. Authentication settings can be mapped using the following guides:
  • Windows: in IIS it is Windows integrated authentication
  • Forms: in IIS it is Anonymous authentication

Here is a short demo presenting the above steps one-by-one:

If you create new sites the trick is the same: edit the site's Url settings field, save the site content, change IIS website settings accordingly and off you go. In case something goes wrong and you need to change the portal's site url-authentication settings, as being unable to log into the portal you can override these settings from the Web.config with the sensenet/urlList node. Refer to the following article on more information about working with sites:

Index Populator

IndexPopulator
The portal uses the Lucene search engine for indexing of the Content Repository and to provide a fast mechanism for returning query results. Lucene stores index information of the Repository in the file system: the LuceneIndex directory in the webfolder contains the index files. This is automatically created at install time with the IndexPopulator.exe console application (executed by InstallSenseNet.bat) which creates the index from the Content Repository and also creates a backup of the newly created index in the database to enable easy backup and restore mechanisms (see later). Usually you won't need to execute this tool manually, except when the index and the database gets out of sync because of unforeseen reasons. You can read more about this tool here:

Creating and restoring backups

Backup / Restore
When creating backups basically you need to backup the following:
  • the web folder (without the LuceneIndex folder)
  • the database.

The former will change rarely in practice (except for the index folder) but the latter will change every time something happens in the Content Repository. When creating backups of the webfolder make sure you don't create backup of the index (placed in the LuceneIndex folder) as it can be corrupt in the moment of copying and it is unnecessary anyway since the index is also stored in the database and it is automatically created when restoring a backup. You can create database backups of the database any time, you don't have to shut down the portal for that. The created database backup will include the last backup of the index folder. A backup of the index is created when the portal is installed for the first time and you can create index backups to the database any time when the portal is running. The system comes with a handy tool, that does all the job for you and can create backups of the index, the webfolder and the database:

When restoring a backup to an existing portal, make sure that the portal is stopped. Overwrite the webfolder, delete the LuceneIndex folder if exists and restore the database. When first launched, the portal will create the index folder from the database and will also synchronize any changes that has been committed to the database since the last backup of the index - so you don't have to worry about the restored portal's index and database being out of sync.

Importing and exporting the Content Repository

Import / Export
It is possible to export the content of your Content Repository to file system so that you can browse and manage the Repository offline just like you can manage your files. Looking at it from the other way around: you can import content into your Content Repository from file system - just like the whole install procedure leans back on this feature. The import/export features of Sense/Net
  • provide a way to manipulate and transfer the content independently of your portals thus enabling migration of content between portals;
  • and make it convenient for builders and developers to build up whole Content Repositories step-by-step from scratch using collaborative development tools (source control) without having to wait for each others' modifications.

To read more about these handy tools refer to the following articles:

Or read this next how-to on building portal Content Repositories as working in a team using Visual Studio TFS source control:

NLB configuration

NLB
Sense/Net can be configured to be up and running on two or more web nodes to allow Network Load Balancing and minimize the risk of your site becoming unavailable in case of an unexpected hardware failure. This is done by setting up 2 or more IIS sites with 2 or more identical web folders. The web nodes communicate with each other via MSMQ and use the same single SQL server as the database for the Content Repository. After installing the portal on a single node you can create another node by following these steps:
  • copy the webfolder without the LuceneIndex folder and setup an IIS site pointing to the created webfolder
  • configure NLB

When the first request arrives to the second node it will automatically restore the index from the database, synchronize it, and starts sending and recieving events via MSMQ. To see the above steps in details refer to the following:

MSMQ settings

MSMQ
MSMQ plays an important role when your live site is configured in NLB, and also when external tools are being executed while the portal is running. Basically, any application that uses the same Content Repository is handled as a separate application domain with its own index and own cache memory, so when they are running simultaneously they need to inform each other about the changes made to the Content Repository by any application domain. Communication is done via MSMQ, a message queue service integrated into Windows operating systems. If not installed correctly, the portal will send an error message to the debug trace at startup time indicating that it will not be able to communicate with other nodes. To correctly configure the MSMQ service you will have to create a private or a public channel (depending on whether the nodes will be running on the same or different servers as the MSMQ server) and set the appropriate permissions for the accounts running the nodes' application domain so they can read and write data into the channel. The address of the created channel is to be set in the application configuration of the nodes (the Web.config in case of the portal). Read the following guide to learn the details:

Logging

Logging
Sense/Net uses the Microsoft Enterprise Library logging features to format and log information in response to portal or application events. Events can be logged to different locations - primarily into file system and database tables as well. The portal default logging settings include the following:
  • Audit log is logged into database
  • AdSync is logged into file
  • Critical, Error, Warning and Information events are logged into event log
  • Verbose is logged onto debug trace

The above settings will be adequate in most cases, but if you need to change these settings or configure custom log settings read the following article on how the logging system can be configured:

External tools

Console application
When executing external tools (console applications) or setting them up as scheduled tasks you will have to follow the steps below to make sure they work properly:
  • check the connectionstring settings in the application configuration: they should be the same as the ones set in the portal's Web.config
  • make sure that MSMQ is correctly configured and that the application configuration of the external tool refers to the same channel as the portal's Web.config
  • execute the tool using the proper account that has permissions to the database, the MSMQ and all other possible services the application uses
  • make sure that the referenced portal dll's are available for the external tool (the best choice is to place the tool in the webfolder)
  • set the used index directory of the application to a unique one that is only used by this tool and make sure that no other tool or web node will have access to the index folder while the tool is running. It's okay if no such folder exists, the tool will create it itself.

Setting up an external tool is very similar to setting up a new web node in NLB - the external tool is regarded as a second (or third) application domain or running node. The following how-to will help you carry out the above steps:

Mass import

Console application
It is a usual scenario to import large amount of data into a Sense/Net ECM Content Repository. This can be done several ways. One way is to create a console application that when executed works like the import tool and imports thousands/millions of content. An other way is to set up a REST handler on the ECMS and send data using a console application instead of importing it directly to the database - just like we did it with our Benchmark Tool. Whichever way you prefer you may have to change some configuration settings for optimal performance of the mass import. See our description of what we changed during benchmarking Sense/Net:

Also, check out the following article about our caching mechanisms and how to configure caching as caching can have large effect on both memory consumption and import performance:

Active Directory synchronization

Active Directory
Active Directory synchronization to the portal from the AD and vice versa is handled by two console applications: SyncAD2Portal.exe and SyncPortal2AD.exe for the two directions, respectively. So setting up AD sync on one hand requires to go through all the steps of configuring these as external tools. On the other hand, synchronization settings can be configured by editing either of the two XML files corresponding to the two directions located in /Root/System/SystemPlugins/Tools/DirectoryServices folder in the Content Repository. You can configure which users to synchronize and also which Fields of the users to map to which properties in AD. You can read more about Active Directory synchronization here:

The following articles will help you configure AD sync in either directions:

The next how-to shows you how to set up a local AD server on a virtual machine and use it for testing AD sync:

Web.config settings

Web.config
When it comes to configuring your portal the basic settings can be adjusted through the Web.config file. Most obvious settings include the connectionStrings, MSMQ settings, index folder and authentication settings. Beside these and some important namespace settings or type bindings there are quite a couple of things you can fine-adjust. There is not enough room to enlist all available configuration settings here in this section, so read through this article - it let's you know everything about the Web.config:

Upgrading a portal to a newer version

Upgrade portal

Enterprise customers should install our regularly released patches instead (see the Changelog article for details) using the SnAdmin tool.

Upgrading portals is a manual process that goes the following way:

  1. Reference the dlls of the new version and see if your custom applications still build! Compile errors will guide you where to update your code but also read the changlog of the new version to see where you have to change anything to build your applications.
  2. Use the export tool to create an importable snapshot of your Content Repository! The export tool will export all the information that is needed to upgrade the content. Export all content from current repository to file system.
  3. Prepare the installation of the most recent version - best to use the source package. You'll need the Root structure of the new version.
  4. Merge the exported and the new root structures: the base should be the new structure, into which you copy all content from the exported root that were created as new. If a modification happened to a content that is present on both places you'll have to individually compare the two .content files and merge them accordingly.
  5. Take extra caution with merging CTDs: these are frequently modified in custom solutions and in new product versions as well. Merge your changes, but make sure you only extend the new ctds with your custom fields or define new ctds and don't change anything else in ctds of the new version, otherwise the system will not be able to boot up.
  6. If the two structures are merged, you can install the new version with this merged Root structure. Don't forget to copy your custom dlls - if there are any - to the installation / web folder. Your upgraded portal should be up and running after the import.
  7. Test the newly installed site and correct any merge errors (css errors are common that can be fixed easily).

Troubleshooting

In the following sections, we'll provide solutions for the most common errors you may encounter during the installation process. Don't let these intimidate you - all of these obstacles can be easily tackled!

Cannot connect to SNCR

Check the web.config file: look for the SQL connection string and see what user name and password was added there during the install process (it should not be the 'sa' user but a custom account like 'sensenet6'). This user should have access to the database that is also added to the connection string. Here's a forum topic that might be helpful: http://forum.sensenet.com/viewtopic.php?f=3&t=7279&p=10803&hilit=404&sid=c79596c733ccd9b721b9566ecbe71faf#p10803>

404 error after a successful installation

First of all, check the port number: it should be set to '80'.

It is? In this case, the most common cause is that there is something wrong with your .NET framework. Please try reinstalling it.

Still get the error? In some cases, it turns our that the order in which you install the .NET framework and IIS is relevant. You will probably need to register IIS. You can either do it with running the following command:

%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i

If running a 32 bit system, it should look like the following:

%windir%\Microsoft.NET\Framework\v4.0.21006\aspnet_regiis.exe -i

or you can download an exe from Microsoft to do it for you http://msdn.microsoft.com/en-us/library/vstudio/k6h9cz8h(v=vs.100).aspx

Blank page on Default.aspx after installation

Your application development features might not be turned on in Windows. To resolve:

1. Press Windows key 2. Type "Turn windows features on or off" 3. in the features window, click "Internet Information Services" 4. Click: "World Wide Web Services" 5. Click: "Application Development Features" 6. Click to enable features (ASP and CGI are not needed for SenseNet).

Error 500 - Internal server error

Error 500 after a successful installation usually means a problem with aspnet+iis binding. The best way to figure it out is to show the error message itself, by editing the web.config and setting the following: - uncomment and set customErrors mode to off - comment out the full httpErrors section

This way you will receive a more detailed error message and will have a better understanding of what you are looking at.

A common error is that ASP.Net is not completely installed with IIS, even though you checked that box in the "Add Feature" dialog. To fix this, simply run the following command at the command prompt

%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i

If running a 32 bit system, it should look like the following:

%windir%\Microsoft.NET\Framework\v4.0.21006\aspnet_regiis.exe

Error: Unable to load one or more of the requested types. Retrieve the LoaderExceptions property for more information

Do you get the above error message after a successful install? Please make sure if all dlls are present in the bin folder, especially these:

• Microsoft.AspNet.SignalR.Client.dll • Microsoft.Owin.Security.dll • Microsoft.Web.Infrastucture.dll

• System.Web.Mvc.dll • System.Web.Razor.dll • Systems.Web.WebPages.Deployment.dll • Systems.Web.WebPages.dll • Systems.Web.WebPages.Razor.dll

If you cannot find any one of these, download the source package and copy the mannually from the 'References' folder.

Differences between a development and a production environment

Web.config

There are several aspects of the system where the development and the production environment differs in configuration settings. The following article displays a couple of recommendations that you may consider when setting up your Sense/Net ECM installations.

Congratulations! You have finished the Getting started guide on installation and maintenance of Sense/Net portals! You are now able to install portals to localhost or live server environments and configure the portal so that users can access it as optimized to your and their needs. You can check out the How-tos page to see more tutorials or you can return to the Main Page and check out other Getting started guides to get acquainted with other areas of Sense/Net!