Although the steps mentioned in the wiki are easy to follow and you can easily configure your solution. But this is not the case always. Sometimes there are lot of other issues raises when you are actually installing and configuring your solution. Here in this article we would cover those unexpected issues (and their troubleshooting) that might be raised when you are trying to install and configure sitecore Habitat solution especially in corporate environment where you have certain level of restriction and have limited permission set.

Prerequisites

Important!: Always run your Visual Studio or Command Line with elevated privileges or As Administrator

These are the tools and practices currently used by the development team in Habitat:

Sitecore does not endorse any particular third-party tool. The tools in the current release were chosen because of a number of reasons including popularity and ease of licensing. This does not preclude using other tools in Habitat or changing any third-party tool for another depending on feedback from the Sitecore community.

Installing required Tools

  • Visual Studio 2015 and .NET 4.6: Download and install Visual Studio from below URL.

https://www.visualstudio.com/downloads/

Make sure, Windows SDK 8.1 is installed on your machine. The Win 8.1 SDK is not included in VS 2015 Update, please install it separately.

https://developer.microsoft.com/en-us/windows/downloads/windows-8-1-sdk

  • Node js: Download the latest node.js from below URL and install it.

https://nodejs.org/en/download/

  • Sitecore Experience Platform: Download mentioned version of sitecore experience platform by following Getting Started guide for Habitat project.

https://github.com/Sitecore/Habitat/wiki/01-Getting-Started

For the current version of Habitat, we need “Sitecore Experience Platform 8.2 Update 1“. That can be download with below URL.

https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/82/Sitecore_Experience_Platform_82_Update1.aspx

Note: Make sure, you have the same version of Sitecore XP, required for Habitat project, else you would get exceptions during project installation.

  • Sitecore Instance Manager (SIM): Download SIM and install it.

http://dl.sitecore.net/updater/sim/

Note: Make sure that all settings of SIM tool are correct and targeting to actual location.

To install Habitat:

Please note that the project assumes the following settings:

Source location: C:\projects\Habitat\
Website location: C:\websites\Habitat.dev.local\
Website URL: http://habitat.dev.local/

  1. Clonethis repository to your local file system.

https://github.com/Sitecore/Habitat/

Note: There are other repositories also available for the different purpose with the example of Dependency Injection in Habitat and use of GlassMapper. You can download those repositories to get the idea, how you can use these concepts in Helix based project.

  1. (optional) Configure your settings if you are using settings other than the defaults:
    • The default settings for Habitat are
    • To change the standard location of the source files, website files and website URL, modify the following files:
      • Please be aware to include or omit trailing slashes – as per the default
      • /src/Project/Habitat/code/App_Config/Include/Project/z.Habitat.DevSettings.config
      • /gulp-config.js
      • /publishsettings.targets
  1. Set up a clean Sitecore install with the settings from the previous step
    • We recommend using Sitecore Instance Manager for the install.
    • Please note that the Sitecore executable installer does not support periods in the domain name and therefore if you are installing using this, please change the default domain (see step 2).
    • Habitat requires:

Run the Sitecore instance manager click on “Install Instance” Button from toolbar. Required settings should be as follows.

Click on Next button and add Sitecore Web Forms for Marketers 8.2 rev. 161129 for the current instance.

If you forgot to install this module during sitecore installation, you can install it using sitecore desktop.

Or install it from Sitecore desktop mode

Upload the package and install the module.

  1. Restore Node.js modules: In an elevated privileges command prompt (started with Run as administrator), run ‘npm install’ in the root of repository. Notes:
    • Make sure you have version 4+ of node.js Download here
    • You may want to use the JS command promptinstead of the regular command prompt so that paths to Note.JS and other concerns are already set

Goto the Habitat source location and execute ‘npm install” command.

Till this step, everything should be fine and there should not be any error and exception. When you execute “npm Install” on Node.js console, you might get few exceptions.

Exception:  Can’t find Python executable “Pyton”

If you get these types of issues, it means you don’t have requred tools intalled on your development environment.

In this case, you just need to execute below command on command prompt.

 

Exception:  npm ERR! network connect ETIMEDOUT

For those who are behind a corporate web proxy, setting up Node.js and using npm can be a real pain. I thought that the web proxy settings would be like the rest of the unix world and require me to set the HTTP_PROXY and HTTPS_PROXY environment variables.

If you are also facing proxy related issue, you can set it with below command.

Exception:  Failed to locate “CL.exe”

This exception generally raised when you don’t have VC++ installed on your system. Which is required to successfully configure Habitat solution.

Run Visual Studio Installation setup again and Install VC++ from available options. After installation, rerun the “npm install” command on Node.js command prompt.

  1. Build and publish the solution using either:
    • Open an command window with elevated privileges and run ‘gulp’in the root of repository.

Exception:  “gulp” is not recognized as an internal or external command.

If you see “gulp” is not recognized as an internal or external command than install the gulp by executing “npm install –global gulp-cli” command at node.js console.

Exception:  could not load file or assembly Unicorn\MicroCHAP.dll.

If you are getting this exception, make sure that MidroCHAP.dll is not blocked by windows.

Right click on C:\Projects\Habitat\scripts\Unicorn\MicroCHAP.dll and click on Unblock button.

After unblocking this dll, re-execute the gulp command.

  • Use Visual Studio:
    • Open Visual Studio 2015 in administrator mode by right-clicking on its icon and selecting Run as administrator.
    • Open the Habitat solution.
    • Open the Visual Studio 2015 Task Runner Explorer pane (View | Other Windows | Task Runner Explorer).
    • Switch to “Solution ‘Habitat'”
    • Run the “default” task

       

Gulp

The project is configured to run Gulp through the command line or using the Task Runner Explorer pane in Visual Studio 2015.

In the initial installation running the default task will execute all the configuration and building tasks for the solution. If for some reason setup fails, it is possible to run the install tasks one by one:

  • 01-Copy-Sitecore-Lib will copy the assemblies from the Sitecore website to the solution
  • 02-Nuget-Restore restores the nuGet packages used by all projects in the solution
  • 03-Publish-All-Projects builds and publishes all the Visual Studio projects to the Sitecore website in the right order
  • 04-Apply-Xml-Transform makes the needed changes to the web.config in the Sitecore website
  • 05-Sync-Unicorn runs a complete synchronization of Unicorn for all projects in the right order

If all tasks are successfully executed, we get below..

Helper tasks

  • The Auto-Publish-[…] tasks help by automatically publishing files when they are changed.
    • The Auto-Publish-Css automatically publishes .css files when changed (Configure Sass compilation in Visual Studio)
    • The Auto-Publish-Assemblies task publishes assemblies as they are built using the standard Visual Studio build process
    • The Auto-Publish-Views task publishes .cshtml files when they are changed.
  • The Publish-[…] tasks helps you by manually publishing different types of files or project types to your website.

SMTP Settings:

Habitat project uses the default Sitecore helpers to send emails. For this to work, you need to set the SMTP settings in Sitecore.config.

NOTE: If you are planning to use secure connections with your SMTP server you need to add following section to your web.config

When you access the URL http://habitat.dev.local/ you should see this page.