Installation

General notes

I have tested Malevich on the following platforms:
  • Windows Server 2008, Windows Server 2008 R2, Windows Vista, and Windows 7, all with IIS 7.0
  • SQL Server 2008, Express, Standard, and Enterprise Editions
  • For mail notifications, an account on Exchange Server 2007, through Exchange Web Services and SMTP

Other people got Malevich to work on Server 2003 as well.

Full system requirements.

A very important note: the setup described here allows any authenticated user (for the most part, any user on the domain forrest) to create code reviews on your server, as well as view (and comment on) any open code review. If you want this changed, you will need to set up security model accordingly: after deploying the database connect to it using SQL Server Management Studio, you will need to reassociate CodeReviewUser in CodeReview database with the right login. See Changing Malevich security for instructions.

Server side installation

Prerequisites

First, you might want to create a dedicated email or domain account to use with Malevich.

Malevich has a feature that notifies the users of coming reviews over email. You can use a regular user account (your own) to run Malevich, but in this case email notifications will show you as a sender. If you will be the sole user for the installation (you are installing it on your own computer, and all or most change lists will be your own, even though other people might be reviewers), this could be fine. But if the installation would service a team, it is advisable to have a separate account. Otherwise the other users will have hard time differentiating regular mail from you from the (voluminous) mail from the review system.

Malevich can be used with both a full domain as well as a mailbox-only account. With the domain account, you will run Malevich installation and configuration from that account, and the email notifier will run under that account, and so the review mail will come from it. As long as the domain account has a mailbox, this is the simplest option to understand.

You can also create a mailbox-only account to use with Malevich. In this case Malevich email notifier will run under your account, but will use an alternative mailbox to send email. Your account will need to have "Send on behalf" privilege for this alternative mailbox account. Depending on security policies chosen by your company, a mailbox-only account can be easier to maintain because there is no password associated with it.

Creating a separate account (domain or mailbox) to use with Malevich email notification is not required, but is highly recommended.

Second, install IIS.
  1. On Windows 7 and Vista, go to Control Panel/Programs, click on "Turn Windows features on or off", and click on "Internet Information Services" in the list. This will enable the feature in its base configuration (the checkbox will be filled with solid blue indicating that the feature is partially installed. Then drill down into the item, expand "World Wide Web Services", open "Application Development Features", and select ASP.NET. Then, also under "World Wide Web Services" expand "Security" and check Windows Authentication. After the installation - on Vista only - create a firewall exception for "World Wide Web Services (HTTP)" using "Allow a program through Windows Firewall" entry in the Control Panel.
  2. On Windows Server 2008 and Windows Server 2008 R2, add an IIS role. When the page that allows you to select role features appears, add Windows Authentication and ASP.NET.

Third, install SQL Server 2008. If you use a domain account other than your own for the email notifier (see above), the easiest thing is to run SQL installation from that account.
  1. Any version from Express to Enterprise would do.
  2. On the feature selection page check Database Engine Services and Management Tools - Basic (you can then uncheck the Management Tools - Complete).
  3. You can use either default or a named instance.
  4. When you get to choose the accounts on Server Configuration page, set all accounts that you can edit to Network Service, and make all services where you can configure the startup type to start automatically.
  5. On Database Engine Configuration page make sure that Windows Authentication is selected (the default), and click on Add Current User to make your account a SQL Server admin.
  6. Finally, on Windows Server 2008 and Windows 7 you must apply a service pack immediately after installing SQL Server.

Finally, you need to get information about your email server.

If you have Exchange 2007 with Exchange Web Services configured, you need a URL for the web service. This is typically the same server that is used by Outlook HTTP proxy. In outlook 2007 open Tools->Account, double-click on your Exchange account, click "More Settings", then select "Connection" tab in the dialog box that opens. Click on "Exchange Proxy Settings" button, and observe the server name (e.g. mine is mail.microsoft.com). Prepend "https://" and append "/EWS/Exchange.asmx" to it. This would get you a EWS 2007 web service URL. Again, for example, mine is "https://mail.microsoft.com/EWS/Exchange.asmx".

If you don't have EWS 2007 deployed, but do have access to SMTP server that would route your mail, you can use that as well.

Using MSI distributable

Download MSI from the Downloads section of this web site and run it. It will unpack the files to a location in Program Files and create a shortcut to an installation program on the desktop called "Configure Malevich". The installation program behind this icon, when run, manages Malevich instance which is created and run in a directory that you specify when you run this program for the first time. Always use "Configure Malevich" shortcut for installing, uninstalling, and upgrading Malevich - MSI just unpacks the files from which a running instance of Malevich can be created, but does not either create this instance, nor remove it on uninstallation.

If you use a domain account other than your own for the email notifier (see above), the easiest thing is to run Malevich configuration from that account.

After the MSI is installed, double-click on "Configure Malevich" icon. The program first checks the environment to make sure the computer configuration is supported and all dependencies (IIS, SQL Server, etc) are installed. It then attempts to locate an existing version of Malevich installation. If such a version is found, it would offer to uninstall or upgrade it. If not, it offers to create a new installation.

See Upgrading Malevich for details on how to upgrade your existing installation.

For a fresh install, the installer collects user input, then creates a running instance of Malevich. The user selects a root directory where the running instance would live, the name of the web root for Malevich web site, and whether or not the installer should configure email notifier.

Installing from Visual Studio environment

Building

To build, I use Visual Studio 2008, SP1. VS2008 is required - do not try to downgrade to 2005. I use Team System 2008, SP1, but it is entirely possible that a lesser version will work fine. If you want to try building it using the free Express Edition and it works, please let me know.

You will also need to install the following VS 2008 expansion packs before building:

Deploying the database

From Visual Studio, open the Malevich solution, right-click on Database project in Solution Explorer, choose Properties. In the property pane, chose the Deploy tab. In the tab, configure connection to the server (you obviously need to be an admin on SQL Server 2008) and select the deploy action 'Create a deployment script (.sql) and deploy to the database'. I think prior to deploying, you have to create the (empty) database 'CodeReview' (it MUST be called CodeReview) in SQL Server Management Studio, and chose it as a database to connect to. Then right-click on Database project again, and select Deploy.

Deploying the web site

Prerequisite: Malevich uses Unix diff program to compute file differences. This has to be installed on the web server. I use unxutils build available here http://sourceforge.net/project/showfiles.php?group_id=9328&package_id=9393. Grab it, unzip it, and if you stick the contents into c:\bin on your server, you wouldn't even have to update the path in the web.config file (see below). Note - I mean the whole contents of the zip file into c:\bin, so there will be c:\bin\bin and c:\bin\usr. Other diff programs will probably work, too, as long as they have the same command syntax.

The next stage is deploying the web site, but before that you need to edit web.config file to set up its data connection. Edit DataConnectionString in web.config in the Website project, and change the server to point to yours (both the server and instance). Ensure that diffExe entry in appSettings points to the diff utility compatible with unix diff(3). If you want to tweak the maximums on various line length, these are also in appSettings. Do keep everything else intact. Then right-click on the website project, and select Publish. Enter the directory on the server, and have it copied there.

Then, on the web server itself, you need to add the directory where you published your website (local path to it, of course) as an application - you can use IIS control panel for this: on Windows Server 2008, Computer->Manage; Roles->Web Server (IIS); Your server name->Sites->Default Web Site (right-click) 'Add Application'. Use Malevich as a virtual path and the code review system will be at http://yourserver/malevich. After adding the application, click on it under the Default Web Site (expand it), then double-click Authentication. Disable Anonymous Authentication, then enable Windows Authentication, and ASP.NET Impersonation.

Client application

The last step is to get review.exe deployed on the computers which you/your team use for development.

If you are building it in Visual Studio, grab everything in review\bin\x86\Release directory. If you are using MSI installer, the review client will be shared from a server machine as \\server\reviewclient. Copy it to a directory on a machine that has enlistment the changes from which you will be reviewing, and add this directory to path.

Then set the environment variable
    set REVIEW_DATABASE=yourSQLserver\yourSQLserverinstance.


review.exe uses command line flags and environment variables to get information about the source control system it will be working with. Type
    review help

for detailed information about configuring source control connection as well as other usage details.

Perforce

p4.exe MUST be in the path. review.exe recognizes P4CONFIG environment variable and will open the file to read P4PORT, P4CLIENT, P4USER, and P4PASSWD variables from this file. Alternatively, these variables can be set in the environment.

TFS

tf.exe DOES NOT have to be in the path, but Team Foundation Explorer must be installed on the computer. review.exe relies on the following environment to specify connection parameters to TFS: TFSUSER, TFSPASSWORD, TFSSERVER, TFSWORKSPACE. TFSUSER can contain domain and user name as is customary on Windows: DOMAIN\username. If TFSUSER and TFSPASSWORD are omitted, Windows authentication with the currently logged account is attempted. If this fails, review.exe may show standard TFS logon dialog box. If TFSWORKSPACE and TFSSERVER are omitted, review.exe tries to detect them from the current directory.

If TFS integration in review.exe does not work (this usually happens if you have pre-release version of the next version of Visual Studio installed), you may need to have the following DLLs from Team Explorer 2008 (found in \Program Files (x86)\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies, or just \Program Files\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies if you're on 32-bit machine) copied to the same directory where review.exe lives:
  • Microsoft.TeamFoundation.Common.dll
  • Microsoft.TeamFoundation.Common.Library.dll
  • Microsoft.TeamFoundation.dll
  • Microsoft.TeamFoundation.Client.dll
  • Microsoft.TeamFoundation.VersionControl.Common.dll
  • Microsoft.TeamFoundation.VersionControl.Client.dll

TFS 2010
Malevich was compiled against TFS 2008. It can, however, work with TFS 2010 server, but additional configuration steps need to be performed.

If the server is TFS 2010 but the client is Visual Studio 2008 (or Team Explorer 2008), they can be made work with the TFS 2010 server by installing a forward compatibility pack from here: http://www.microsoft.com/downloads/en/details.aspx?FamilyID=cf13ea45-d17b-4edc-8e6c-6c5b208ec54d&displaylang=en

If the client is Visual Studio 2010 (or Team Explorer 2010), you need to add the following file to the directory where review.exe is located. The file must be called review.exe.config, and the contents must be the following:
<?xml version ="1.0"?> 
<configuration> 
<runtime>

        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">

                <dependentAssembly> 
                        <assemblyIdentity name="Microsoft.TeamFoundation.Client" culture="" publicKeyToken="b03f5f7f11d50a3a"/> 
                        <bindingRedirect oldVersion="9.0.0.0" newVersion="10.0.0.0"/>
                </dependentAssembly> 
                <dependentAssembly> 
                        <assemblyIdentity name="Microsoft.TeamFoundation.Common" culture="" publicKeyToken="b03f5f7f11d50a3a"/> 
                        <bindingRedirect oldVersion="9.0.0.0" newVersion="10.0.0.0"/>
                </dependentAssembly> 
                <dependentAssembly> 
                        <assemblyIdentity name="Microsoft.TeamFoundation.VersionControl.Client" culture="" publicKeyToken="b03f5f7f11d50a3a"/> 
                        <bindingRedirect oldVersion="9.0.0.0" newVersion="10.0.0.0"/>
                </dependentAssembly> 
                <dependentAssembly> 
                        <assemblyIdentity name="Microsoft.TeamFoundation.VersionControl.Common" culture="" publicKeyToken="b03f5f7f11d50a3a"/> 
                        <bindingRedirect oldVersion="9.0.0.0" newVersion="10.0.0.0"/>
                </dependentAssembly> 
        </assemblyBinding>

</runtime> 
</configuration>


See also the attached file here: http://download.codeplex.com/download?ProjectName=Malevich&DownloadId=157648

Additional TFS configuration
TFS support in review.exe has two modes. By default, it uses the shelf set as simply the list of files, but harvests the file data from the local hard drive. So, for example, if you created the shelf set, then updated some of the files, and then submitted the review, the review contents will be the updated files - not the ones in the shelf set. This is very similar to how it works in Perforce and SourceDepot - both of which lack the ability to upload the unsubmitted change list files to the server.

To have review.exe get the files from the self set itself, which is more consistent with the spirit of TFS, add the following to the environment variables:
    set TFSDIFFSOURCE=shelf

Source Depot

sd.exe MUST be in the path. SDCLIENT and SDPORT can be defined either in the environment or in sd.ini file. Windows authentication is always used for connection to source depot.

Configuring email notification for pending reviews

Malevich includes a program that will send notifications about pending code reviews as well as reviewer comments. The notifier program runs as a scheduled task, and supports both Exchange 2007 web service, and SMTP server to send mail.

If you are building yourself, copy notifier (all files from notifier\bin\Release) to a directory on a server from where you will be running it, in the simplest installation it would be the server where web site and database reside. If you are installing from MSI, this has already been done, and if you allowed the notification program to set it up, you can skip this section unless you need to reconfigure it.

Notifier is a scheduled task. It stores all the configuration in registry under the same account which is used to configure it, so it MUST be set to run under the same account. It does have an installation option that will create the scheduled task, but if you want to create the scheduled task on your own, you MUST ensure three things:
  • The account used for the scheduled task must be the same account that was used to configure it (see below),
  • The task should run whether the user is logged on or not, and
  • The task must store the password.

Note that if you are using the Exchange option, you must supply your password as a configuration parameter. The password will be stored in registry, encrypted with the current account key. It is as secure (or not secure) as the password that is used to create the service, which is managed by Windows.

SMTP mode does not require the password.

If you configure notifier to run under your own account, the email will be sent from your name by default. It is possible to use Exchange's mailbox-only account as a source of notification mail, if you have "send on behalf of" privilege to the mailbox-only account. If you do have an alternative mailbox-only account, specify it in place of "alt.account" below.

To configure notifier in SMTP mode (preferred):
    ReviewNotifier smtp smtphost companydomain
    ReviewNotifier credentials username [password domain] [alt.account]
    ReviewNotifier webserver webservername
    ReviewNotifier database SQL_server_instance
    ReviewNotifier schedule numberofminutedbetweenruns


All user names above should not contain domain name, e.g. alice, not alice@microsoft.com, and not REDMOND\alice. Web server name is a host name, e.g. alicebox. companydomain is the email domain, e.g. microsoft.com. If a user name is alice and companydomain is microsoft.com, alice@microsoft.com MUST be a valid email address.

Password and domain are optional. If they are not supplied, the credentials of the current user are used. One can also specify an alternative account that would be used as a source of notification email - it will appear to come from that account. If your SMTP server is secure (as it should be), your account must have permission to send mail on behalf of this alternative account. If the alternative account is not specified, the 'from' field of the mail will come from the username.

For example:
    ReviewNotifier smtp smtphost.redmond.corp.microsoft.com microsoft.com
    ReviewNotifier credentials alice reviewlog
    ReviewNotifier webserver alicebox
    ReviewNotifier database alicebox\alice
    ReviewNotifier schedule 10


To configure notifier in Exchange mode:
    ReviewNotifier exchange webserviceurl companydomain
    ReviewNotifier credentials username password domain [alt.account]
    ReviewNotifier webserver webservername
    ReviewNotifier database SQL_server_instance
    ReviewNotifier schedule numberofminutedbetweenruns


Password and user domain are required for the Exchange server. The web service url should point to Exchange Web Server 2007. The format of the string should look like this: https://mail.microsoft.com/EWS/Exchange.asmx, except, of course, with your own company's domain name.

Here's an example:
    ReviewNotifier exchange https://mail.microsoft.com/EWS/Exchange.asmx microsoft.com
    ReviewNotifier credentials alice 1!ecila!2 REDMOND reviewlog
    ReviewNotifier webserver alicebox
    ReviewNotifier database alicebox\alice
    ReviewNotifier schedule 10


CONGRATULATIONS! YOU ARE DONE!

It is highly recommended that you go through a few tests as outlined in Testing Malevich setup now, to make sure that your installation works.

Last edited Oct 15, 2010 at 1:55 AM by SergeySolyanik, version 21

Comments

jayongg Mar 24, 2010 at 6:26 AM 
FYI - I have worked on Malevich successfully using VS2008 Professional SP1. The limitation is that I can't open/build the .dbproj project.