Creating a Build.vNext agent on Linux

In the past few months Microsoft has made it very clear that they are no longer a Windows-only company. Things like Xamarin integration, the new multi-platform ASP.Net 5 and the cross-platform .Net CLR are all results of that new strategy. This opens up all sorts of new possibilities for developers who were previously tied to a single platform. Exciting times are coming!

The new build agent for the Build vNext system is another example of this cross-platform strategy. The new build agent is actually based on Node.js which means it should run on any platform that supports Node.js. This includes Linux. So, I decided to give that a try. And guess what? It works! Running a Microsoft build agent on Linux, I think that’s pretty cool!

And, the new build agent is fully open-source! You can have a look at the code on the VSO agent GitHub page.

Create a build agent pool

While technically it’s not required, I think it’s nice to create a separate build agent pool for Linux build servers. Log in to your VSO account and click the gear icon in the top right to get to the settings page. Then go to the “Agent pools” tab and click “New Pool”.

Provide a name for your new pool and make sure you leave the “Auto-Provision” checkbox on. This will make sure your new pool will be available to your Team Project Collection.

Your new pool will be created. Of course, there are no agents in there yet.

Set permissions

We’ll need to set some permissions before we can add and run our new agent. Ideally, you would create a new (service) account for your agents. Unfortunately, I don’t have one available so I’m going to use my personal account. First, we need to enable alternate credentials for the account. Log in to VSO using your account and open your profile settings.

Then, go to the “Credentials” tab and enable your alternate credentials there.

Now, go back to the “Agent pools” administration page and click the little triangle in front of your newly created pool.

There are two security groups there. We’ll need to add our account to both.

• Agent Pool Administrators:  allows adding agent to pool
• Agent Pool Service Accounts: allows the agent to listen to the build queue

Create a server

Next, we need a server! The easiest way to get one is to create on in Azure. I decided to go for the newest Ubuntu version currently available.

For now, I chose to use password authentication. If you want, you can create a key file and use that. It’ll take a few minutes before the server is ready. To log in we’ll need an SSH client. A great one for Windows is PuTTY. Go ahead and download that if you didn’t already. Start PuTTY, and type the hostname for your server. Then, click “Open” to connect.

You’ll get a message asking you if you trust the computer you’re connecting to. Click “Yes” and you’ll be presented with a login prompt. Login using the credentials you provided when creating the virtual machine.

Voilà, you’re logged into your brand new Linux server!

Installing prequisites

We’ll need to install some prerequisites on our new server.  We’ll need to install Node.js and npm. Type “sudo apt-get install nodejs npm” to get things going.

Once you hit Enter, apt-get will take care of resolving dependencies. As you’ll notice, there are quite a lot… Type “Y” to start the installation.

Now be patient as everything gets installed…

Because of a naming conflict with another program called “Node”, the default installation in Ubuntu installs Node.js as “nodejs”. However, the build agent script expects to find a “node” executable… To overcome this problem, the “nodejs-legacy” package was created. Install it by typing “sudo apt-get install nodejs-legacy”.

Now check the installed versions of Node.js and npm by typing “node –v && npm –v”.

For the build agent to work you’ll need Node.js >= v0.10 and npm >= 1.4. In my case all is good!

Install the agent

Next order of business is to install the agent. As with TFS, the total process is split up in two parts: first we install the software bits, and then we run the configuration. To install the software bits we can use npm. Type “sudo npm install vsoagent-installer –g” and hit enter. That will pull the latest version of the installer from the repository.

Configure agent

We’re almost there… The only thing left to do is configure our agent. The agent installer allows us to easily create multiple agents on a single server. Each agent will run inside its own folder. So, first we need to create a folder. Type “mkdir linuxagent1” to create one and then cd into it with “cd linuxagent1”.

Now, install the agent into this folder by typing “vsoagent-installer”.

This installs the agent into the directory you just created.  Now we can start it up and connect to VSO! Type “node agent/vsoagent” to start the configuration. Enter your credentials (these are your alternate credentials!), your VSO URL, an agent name (optional) and your pool name (“Linux” in my case) and the agent should start up!

Note: the agent is now running in interactive mode. This means that when you close your session, the agent will terminate. While this is fine for testing and demonstration, it’s not so nice for production. Currently, the agent doesn’t support running as a service on Linux. The development team is working on that. In the meantime, you can use this trick to run the agent in the background: after starting the agent, hit “Ctrl+z”. This will stop the process and display a job number (1 in my case). Then, type “disown –h %1” (where 1 is the job number). This ensures the job is not stopped when you log out. Finally, type “bg 1” (again, 1 is the job number). This will start the process again, this time running in the background.

You can now safely log out and the agent will continue running. Of course, you have to repeat these steps if you restart the server.

Verify

You can check your new agent by going to the “Agent pools” administration page on VSO and checking your queue there. Your new agent should show up there. And, it’ll identify itself as a Linux server!

Next steps

In this post, I’ve shown you how to run a Build vNext agent on Linux and connect it to VSO. While we haven’t actually done anything useful with it yet, it does demonstrate the true multi-platform direction that Microsoft is headed in. In theory this should allow us to build a Java application on Linux for example. While I’m thinking about this my fingers are itching to give that a try… More on that in a later post!

Happy building!