The steps are as follows:
- Visit the Perforce Helix download site
- Choose the product, the Helix Versioning Engine
- Choose the operating system, Windows x64
- Complete the registration form
- Locate the downloaded executable, helix-versioning-engine-x64.exe, and run it
The setup process asks a few things, so we'll go over them here one at a time. The first question prompts which components to install. Only the server and command-line client are necessary for our purposes, so the defaults seen in the following screenshot serve nicely.
The next page asks for the port to be used by client applications and offers the opportunity to choose a different location for the installation. The defaults again serve nicely for our purposes, as the traditional port (1666) isn't used by anything else on a default Windows installation. Your defaults should look as the following illustration.
The final page of configuration information for the setup is shown below. It includes the port to be used by the server, the application to be used as a text editor, and the desired default user name. To be clear, this doesn't actually create that user, but rather sets the name for subsequent use by clients.
We can quickly test and see that our server is running properly by launching a shell and executing an info command. Starting the default shell (CMD.EXE in the case of Windows) and executing the following command interrogates the server and shows the resulting data.
To explain the command and its arguments, P4 (really P4.EXE) is the name of the Perforce Helix Command-line Interface or CLI. The "-p localhost:1666" argument specifies the server to which to connect, in this case our virtual machine. Finally, "info" is the name of the command we want the CLI to execute against the server. It returns a fair bit of information, but the important point is that the Helix Versioning Engine is up and running.
Let's install the Helix Visual Client next.
The steps are as follows:
- Visit the Perforce Helix download site
- Scroll to "Helix Desktop & Web Apps" and find Helix P4V: Visual Client
- Choose Windows (x64)
- Complete the registration form
- Locate the downloaded executable, p4vinst64.exe, and run it
As with the server, we'll be asked for some configuration information by the installer. The first page prompts the selection of the components to install. The following defaults are fine. The administration and visual merge tools are useful for configuring your Helix installation and reviewing code changes respectively. The command-line client isn't strictly necessary, given that it is included in the server setup, but it doesn't hurt anything to have it installed.
The next page asks for the port to use when connecting to the server, the application to use as a text editor, and the default user name. These values were already set by the server installation on our single VM, but in most cases you'd typically be setting up the client on a machine distinct from the server. So again we accept the following defaults.
That's all there is to it. Now we have both the Helix Versioning Engine and the Helix Visual Client installed and working on our VM.
Before we move on, let's tend to some configuration housekeeping. None of these are strictly necessary to use the Helix Versioning Engine from our simple VM, but they're worth mentioning for use beyond the scope of our example.
The first thing we want to tweak is the Windows firewall. The info command we executed earlier showed that the Perforce Helix server was up and running, but the command was executed from the local host. Any attempt to access the server more generally (i.e., from other systems) would presently result in failure. That's because Windows doesn't open the port we specified at setup (viz., 1666) by default for sake of security.
So let's see about creating inbound and outbound rules for the firewall. You can do this from the command line, but most users seem to prefer using the Windows Firewall with Advanced Security utility. Launch that tool, navigate to the list of inbound rules (which appears by default), and click the option to create a new rule. Then choose the port option as shown in the following screenshot.
Click the button to proceed to the next step and specify our preferred port number (1666) as shown in the following screenshot.
On the next page, choose to Allow the connection.
The page after that requires a bit more thought, depending on your concern for security. If you're setting up your own system for evaluation, you might want to enable the rule only for domain or private networks. In our particular case, however, let's accept the defaults because this is just an example.
Finally, give your new rule a helpful name and description. This is probably overkill for sake of our example, but in any real setup you'll thank yourself later.
Once you're done with the inbound, it's good practice to create a similar rule for the outbound traffic. We won't go through step-by-step as it's basically the same process we just went through, only adding a new rule to the outbound list instead. That should completely open up the port for two-way external communication, which can easily be verified by issuing that same info command from another system.
Before you try executing commands from elsewhere, however, the second thing you may want to tweak is the list of allowed users and/or groups. The info command is pretty neutral and works right out of the box, thanks to the default security configuration, but other commands won't necessarily work.
This is because by default a new installation of the Helix Versioning Engine is very open and accessible, but you'll need administrative privileges to do certain things. So let's launch the administration tool, P4Admin, which we previously installed with the Helix Visual Client. It offers super-user privileges to the first user to connect with it. Carefully look at the popup dialog that appears:
Continuing means you'll have to create the other accounts and set up permissions as desired. Once you're into the utility, it's generally a good idea to create an "Administrators" group (or something like that) and carefully maintain its members. For a brief list of security best practices, see this blog article entitled, Securing Your Perforce Helix Server (P4D).
For the purposes of our system, we've created an "Administrators" group and added both the original super-user (Perforce) and a user account for myself as well to that group. We've also given the group super permissions on the default depot as seen in the following, partial screen shot.
The top section shows how the "Administrators" group has two members, while down below we see the protections table, which shows that any user has write permissions, but only the "Administrators" group has super permissions. This lets members of that group do administrative things, which will prove rather handy in just a moment.
The third and final item we want to tweak is useful for Helix' advanced distributed version control system (DVCS) features. Developers who like the distributed nature of tools like Git and Mercurial (often abbreviated Hg) probably prefer to use Helix' DVCS features, and they are not enabled by default on a new server installation. This lets existing Helix system admins upgrade older server installations safely without tackling the security implications of DVCS features until they're ready.
New users might wonder: how can we tell if the DVCS features are enabled? The Helix server offers a simple command to query what "configurables" are set, but it will only work properly if you have the right permissions. That's why we adjusted the users and groups previously. Said command is shown in the following screenshot.
As before, the "-p localhost:1666" argument specifies the server to which to connect, but this time we're using the "configure" command with the "show" argument to request a list of settings. Don't worry if you don't understand any of the output that follows. The important thing is that there are three values essential for DVCS operations that do not appear. We can set all three configurables to their most permissive values with the following commands:
By setting "server.allowfetch" and "server.allowpush" to a value of three, we're enabling fetch and push both from and to this server and other servers. By setting "server.allowrewrite" to a value of one, we're enabling the re-writing of history, an advanced DVCS feature that you can read more about in this blog article.
What matters for our purposes is that DVCS features are now fully enabled on our new server, a fact of which we'll take full advantage in developing our sample application. Helix' DVCS features makes it so much easier to juggle multiple, lightweight in-place branches, clean up history before submitting, and generally makes development much more pleasant for those who prefer the distributed way.
Installing the community edition of Visual Studio 2015 (VS2015) is straightforward. The steps are as follows:
- Visit the Visual Studio Community home page
- Click the big "Download Community 2015" button
- Locate the downloaded executable, the file name of which begins with vs_community in this case (and ends with some horrible string of characters), and run it
That installer takes care of all the details pretty easily. It gives you a progress window during the process, a snippet of which is shown below.
It can take a while, depending largely upon the speed of your Internet connection. Verify this by bringing up the start menu and searching for "Visual Studio 2015", the name of the integrated development environment (IDE). Running the application should show you something like the following:
This is the main "start page" for the IDE. It shows your recent projects on the left (none as we just installed it), the solution explorer on the right (empty because we haven't yet created any), and then some useful content in the center. The topics, videos, etc. which appear there change as Microsoft updates their content, so it's not a bad idea to check it out from time to time.
As with the other Helix tools, installing the P4VS plugin is simple. The steps are as follows:
- Close VS2015 if it's still running
- Visit the Perforce Helix download site
- Scroll down to "Plugins & Integrations" and find "P4VS: Plug-In for Visual Studio"
- Choose the version (P4VS 2016.1 in our case for VS2015)
- Sign up for the free trial (if prompted)
- Locate the downloaded file, p4vs11.vsix, and run it
The setup process completes so quickly that one may wonder if the plugin is installed. To check that it has, select it as your desired source-control plugin in the VS2015 IDE.
After closing the installer, relaunch VS2015 and choose the "Tools / Options…" menu item. Expand "Source Control" on the left and select "Plug-in Selection". You should see an entry labelled "P4VS - Perforce Plugin for Visual Studio" as shown in the screenshot below.
Clicking the "OK" button confirms your choice. When we start working on our new project, we'll provide details on how to connect to the server.
To begin, let's start with the Server Manager, which is the application that starts every time you log into the server. See the screenshot below.
This is the Server Manager dashboard to be more precise. The numbered items near the top list things Microsoft recommends when you set up a new server, which can be helpful for new admins. In our case we're interested in adding a new role to the server, so click the "Add roles and features" link. Doing so kicks off the wizard seen in the screenshot below.
The wizard is helpful for novices. Please note that you can do all of this from the command line as well. Click the "Next" button . Choose the option for a "Role-based or feature-based installation" as seen in the screenshot below.
After clicking the "Next" button, you will be asked which server to configure. The Server Manager is capable of managing multiple machines, but in our case we have only the one server, so we simply leave it selected (as shown below) and advance to the next step.
The next step in the wizard is for "Server Roles". Scroll down to find and select the "Web Server (IIS)" role Click the "Next" button.
A pop-up appears with the following message:
Click the "Add Features" button and know that "Web Server (IIS)" is now checked.
The next step in the wizard is to select features., To understand Microsoft's nomenclature: a role describes a complicated thing you want your server to do, whereas features are the underlying options and capabilities required to fulfill that role. That's not a strict definition, but it should hopefully convey the general idea.
The features you need depend greatly upon what you're trying to do. If you're developing a static web site for viewing by all, you won't need much of anything. If you're trying to build the next big social media site, you're going to want some more advanced tools.
In our case, we're going to want to make sure the .NET framework is installed, as it is rather hard to build an MVC application based on .NET without it. Below we can see that several of the relevant features are installed. Windows Communication Foundation (WCF) services aren't entirely in our kit, but leave it as is. If your application requires complicated messaging and perhaps remoting, then you may want to check the other boxes seen below.
Having selected your desired features, continuing to the next page will give you an explanatory page about web server role services. Click the "Next" button.
Doing so will take you to the "Role Services" step under "Web Server Role (IIS)" in the wizard. Consider the following–as seen below–the HTTP Redirection option is a great choice for the reader who likes to keep URLs pretty.
And consider picking all of the security options. It's not so important for our sample project, but if you're going to administer a real instance of IIS you're going to want to know what all of those mean and what they do.
We also need some of the application development options. The "WebSocket Protocol" is only needed if your application is doing anything with messaging or notifications.
Click the "Next" button and that's about it. The wizard takes a while to configure, but when it's done you should have a working IIS instance. You can check by opening a browser and navigating to "localhost" as seen below.
The resulting page may look a bit different, depending upon your browser and version of Windows. You want to see a welcome screen from IIS and not some an error about how the site isn't available. With IIS installed, we're all set to install (even deploy!) other web applications to our server.
To install Jenkins the steps are as follows:
- Navigate to the Jenkins web page and click the "Download Jenkins" button
- Under the Long Term Support (LTS) release, click the little down-arrow to choose Windows
- This will download a zip file, jenkins-2.7.2.zip
- Unzip to find the actual installer file (MSI)
- Run the MSI file with the default location, and let it run
After encountering typical installation dialogs, the process to "Unlock Jenkins" and choose plugins needs clarification. When Jenkins installs, it creates an initial administration password in a particular file. We need to get this password and enter it into the resulting dialog. When the Jenkins install finishes, the first thing it does is navigate to the Jenkins site, which is on port 8080 on your localhost by default. And the first thing that site does is notice that Jenkins needs to be unlocked and confronts you with the following sort of screenshot:
This can throw new users for a loop. If you read the actual text, you'll see that it gives you the location of the file containing the initial admin password. Navigating there using Windows Explorer, you should find a file just like the one shown below.
Open that file in your favorite text editor, copy its contents to your clipboard, and save it somewhere for future use. Paste it into the browser and complete the initial unlock process. That presents you with the options shown below.
The default option is to install suggested plugins, but we're going to want to make a few changes. Click the option to "Select plugins to install"–this is important when configuring a Jenkins project to pull source code from Perforce Helix.
In the resulting plugin-selection interface, there are a few things we want. First, scroll down to build tools and make sure that the MSBuild plugin is selected. It isn't entirely necessary, given the build scripting we're going to create, but it's usually a good idea to include on any Windows instance of Jenkins to be used for building Microsoft .NET applications via regular projects. You'll see it highlighted in the screenshot below.
Scroll down a bit further to the section on build analysis and reporting, and make sure you also check the HTML Publisher plugin as well as the xUnit plugin–these are useful for collecting/displaying general HTML-formatted output as well as our unit test results. If you can't find something you want or aren't sure what else to choose; you can always manage plugins from the Jenkins interface after the fact.
Finally, scroll down to the section on "Source Code Management" and de-select everything save for the "P4 Plugin" option—unless you plan on using a different version control system.
Click the "Install" button. This may take a while. You'll know it's done when you see a dialog like the following to create your first admin user. Go ahead and provide your desired details and "Save and Finish". Some generic values are entered for our use as seen below.
That's all there is to it. You'll next get a confirmation dialog that Jenkins has finished its setup, and then (if all goes well) another web page will open showing you the Jenkins dashboard, like the following.
The dashboard is empty because we haven't yet created any projects. But we'll get to that soon enough. The important point is that Jenkins is up and running. We have a CI tool ready to automate work for us.