Using and Contributing to VM Depot


What is VM Depot?

VM Depot is a community-driven catalog of pre-configured operating systems, applications, and development stacks that can easily be deployed on Windows Azure. Find your favorite software and deploy it in minutes, or join the community, build a virtual machine image, and share it with others.

VM Depot is of interest to those who wish to:

Microsoft Open Technologies, Inc does not screen images provided by the community members for security, compatibility or performance. Users should conduct their own evaluation before using these community images. Support for images are provided by the community and not by Microsoft Open Technologies, Inc. By using unsupported images, you might forfeit Windows Azure availability SLA.


Using VM Depot

This section of our documentation is for those who want to discover and deploy images published on VM Depot. In this section you will find the following content.


Using VM Depot to find the best Virtual Machine Images

Lets take a walk through of the VM Depot site with the aim of showing you how to discover the best Virtual Machine images for deployment to Windows Azure. On this page you will find the following sections.

VM Depot Home Page

The VM Depot home page is located at http://vmdepot.msopentech.com. When you first arrive at this page you will see an image something like that displayed in the screenshot below.There are three main areas on this screen, we will look at each in turn below:

The VM depot hme page shows a set of navigation menues, some text describing the purpose of VM Depot and a list of images.

Image List and Search Features

The image list provides an overview of the images that match your current search and sort parameters. By default the list presents a number of featured images, you can use the search and sorting features, discussed below, to adjust the contents of the feature list.

Each image displayed in the list has a title and descritpion, an icon and a list of packages that it includes and tags to assist in categorization. You are also able to see the average rating users have given that image.

The image list contains the title of the image, a description, an icon, the publisher and platform and a set of packages and tags.

Searching and Sorting Images

The search box allows you to type in search terms to filter the image list.

The search bar, located on the VM Depot home page allows you to filter the images displayed in the image list. When you enter a term here you will be searhing for that term in image titles, descriptions, package lists and tags.

The sort options allow the resulting image list to be sorted using various parameters as discussed below.

It is also possible to sort the results list by clicking on one of the "Sort By" options between the search box and the results list. Sorting options include:

  • Featured - display featured images first. Featured images are selected by MS Open Technologies, Inc. and updated on regularly
  • Date Added - display the most recently added features first
  • Name - sort by alphabetic order on the image name
  • Platform - sort by alphabetic order on the platform name (that is the operating system used)
  • Rating - sort with highest rated images appearing first

Action Bar

The action bar shows an icon for each of the actions available as discussed in the text below.

The ation bar gives quick access to the appropriate actions for the currently displayed page. The actions that may be available are:

  • Deployment Script - visible when viewing an image detail page. We will look at this later.
  • Publish - allows registered users to publish a new Virtual Machine Image to VM Depot
  • View - show a detail view of the currently selected image
  • Share - share a link to the current page on socialnetworking sites
  • Help - access to help documentation, such as this page

Deploying a Virtual Machine

There are a number of ways that a virtual machine can be deployed from an image in VM Depot. This page describes the two most commonly used, the Command Line Interface and the Windows Azure Management Portal. For either method you will need to create a free Windows Azure trial subscription (unless you already have a subscription of course). Once you have your subscription try one of the two methods below to deploy an image.

Deployment using the Command Line Interface

Preparation

The first thing you need to do, as noted above is create a free Windows Azure trial subscription (unless you already have a subscription of course). Once that is done you can proceed with installing the command line tools.

Our command line tools will work on any platform because they are written in Node.js. You will need to install Node.js and the command line tools module the first time you deploy a VM Depot image to Azure. This once-only process is described below.

For the impatient
  • Install Node.js
  • Install Azure CLI using
    npm install azure-cli -g
  • Configure the subscription credentials for your Windows Azure subscription
  • If you understand (or don't care about) what you just did then proceed to the instructions on deploying a VM
The Full Details

The command line tools are written in Node.js and are threrefore cross platform. However, you will first need to install the appropriate version of Node.js for your opeating system. This is easily done by visting http://www.nodejs.org and following the instructions you can find there.

Once you have Node.js installed you need to run the following command to download and install the Windows Azure Command Line (CLI) tools:

npm install azure-cli -g

Assuming you are connected to the Internet this command will download the latest version of the CLI tools.

In order to work with the command line tools you need to configure the subscription credentials to use. To do this you first need to download the credentials from Windows Azure:

azure account download

This will open your web browser and prompt you to download a file containing your credentials (if you are not logged into Windows Azure you will need to do so first). Save the file in a convenient location and then run the following command:

azure account import [PATH_TO_FILE]

The command line tools will be configured to use the provided credentials. You can run this command at any time if you need to change the credentials to be used.

You can update your installation at any time by running the following command:

npm update azure-cli --global

This document explains enough of the features of the command line tools to enable you to deploy your first virtual machine from a VM Depot image. However, the tools go much further than simply enabling you to deploy Virtual Machines. Full documentation for the CLI is available.

Deploying an Image from the Command Line

Once you have installed Node.js and the command line tools and you have selected an image to deploy you are ready to deploy your first image.

The Vm Depot website will generate a script template for you to use in the command line. Select the image you want and you will notice that the Deployment Script button is enabled. After you click the deployment script icon (and you have agreed to the terms and conditions) you will be prompted for a region for deployment. Once selected the appropriate script template will be generated and displayed.

If the image has defined any endpoints that should be opened on the virtual machine there will be an additional command presented in the deployment script, this commend will create the necessary endpoints. The defined endpoints will also be displayed in the image details. For example:

Screenshot showing Endpoints in image description and deployment script

Execute the commands provided, being careful to replace capitalized values in the template marked with square brackets. Note the the DNS_PREFIX will be part of the URL, consequently it can only contain alphanumeric characters.If you provide a password then it must be at least 8 characters in length. Other items in square brackets, such as '--ssh' (which ensures the SSH port is opened on your deployed VM) are optional. See the command line documentation for more information about the options available.


Deployment using the Windows Azure Management Portal

This method uses the web based Windows Azure management portal. In order to access it you need to ensure you have a free Windows Azure trial subscription (unless you already have a subscription of course)ccount.

For images that use one of the Windows Azure-Endorsed Linux Distributions it is possible to deploy virtual machines using the Windows Azure management portal. This section of the documentation describes how to do this.

When you login to the management portal you will see a page that looks something like this:

In order to create a virtual machine you must first copy the VM Depot Image into your Azure subscription. To do this you must select "Virtual Machines" from the menu on the right, then select "Images" in the tabs at the top of the resulting page. Finally, select "Browse VM Depot" at the bottom of the page. The screenshot below shows each of these items:

After clicking "Browse VM Depot" you will be presented with a dialog which gives access to a list of al the images available via the portal. Find the image you want and select it and click the arrow to move to the next step.

In the next page of the dialog you need to select the storage subscription you want (a new one can be created if necessary). In the screenshot below we are using Northern Europe and creating a new storage subscription. Click the tick to close the dialog and create the image in your gallery.

It takes a little while to generate the image, your progress is shown in the management portal. You can leave this page and continue with other tasks, the notification in the toolbar at the bottom of all portal screens will tell you when creation is complete (the animation stops and the notification bar will appear). You can click on the notification icon to see a summary of the job and then on the Details icon to see full progress information. Once complete you should go back to the "Virtual Machine", "Images" tab. On this screen you will see your image is present with a status of "Pending registration", as shown below.

You now need to register this image so that you can create virtual machines from it. Ensure your image is selected (if you have more than one) and click "Register". You will be asked to provide a name and a VHD URL. Both will be auto filled for you. You shouldn't change the URL (unless you know what you are doing) but feel free to change the name. Then click the tick to complete the registration which will take a few moments.

Now you are ready to create a virtual machine from your copy of the image. Select the "Virtual Machines Instances" tab and click the "New" action button at the bottom of the page. This will bring up a dialog within which you can create your Virtual Machine, like the one below. You should select "Virtual Machine" and then "From Gallery".

In the gallery you will find your new image under the "My Images" tab. Ensure it is selected, as shown in the screenshot below, and click the arrow to continue.

In the resulting dialog page, give your virtual machine a name, root user and password. Select the size of image you want. You should really upload your SSH keys too, although this is optional. Click the arrow to proceed. On the next page we set up the machine connectivity. In this example we are creating a standalone Virtual Machine so we'll give the machine a DNS name and click the arrow to proceed past the next screen which allows you to connect your new machine to a pre-existing one in order to provide load balancing.

Next up we are given the chance to connect this VM to an availability set, or to create a new availability set. An availability set is a group of VMs that are deployed across fault domains and update domains to ensure your application does not have as single point of failure. Since this is just a simple tutorial there is no need to create an availability set. So go ahead and click the tick to complete the action. Creating the VM takes a short while. As before you can get on with other things and will be notified when your VM is ready.

Once complete your VM will be running and the SSH port will be open. The SSH port number will be randomly generated. You can find the port that used through the portal interface. Go to the Virtual Machines page and click on the image you created, this will take you to the image detail page where you can find the SSH port. You can now log into the machine as well as connect to any other services the image provides.


Contributing to VM Depot

This section is targeted at those who wish to create and publish Virtual Machine images, it contains the following content:

Publishing an Image

The VM Depot community portal will allow you to share a virtual machine image you have created with other Windows Azure users, and allow you to search and find images others have submitted. This step-by-step guide shows how easy it is to share a virtual machine image with the community.

Prerequisites:

  1. You will need one of these: a Windows Live, Google or Yahoo account.
  2. A VHD (Virtual Hard Drive) file containing a virtual machine image. See this page for information on creating a VHD file from an existing Linux Installation.
  3. The URL to the Windows Azure blob which is the VHD file (the virtual machine image) you wish to submit. This .vhd file must be a public blob in your Windows Azure subscription in order to be accessible to VM Depot. See this page for information on referencing blobs and this page on how to make containers in your Windows Azure storage subscription public. Once your image has been uploaded to the portal you may safely delete it from your storage subscription.

Logging in and registering:

Start by navigating to the VM Depot page at http://VMDepot.msopentech.com/. You will see a list of the currently available Virtual Machine Images. At the top of the page, click the "publish" icon.

If you have not yet logged in, you will be presented with a login screen with the option for using a Windows Live, Yahoo or Google ID. It is recommended that this account be the same as your Windows Azure subscription. If you have not previously logged in with your chosen account, you will be presented with a short registration page which will ask you to create your user profile. You will need to provide a name (Yours or your organizations) and an email address. You will also be required to accept the terms and conditions. Once you have completed the form, click "Save."

Submission Details:

Once you have navigated to the "Publish an Image" page you will see a short form where you will enter the details of your submission.

Screenshot of the image publishing form.

Upload thumbnail - optional - Allows you to associate an image with your submission. The maximum image file size is 200k and we recommend your image be a 256p square.

Image name - required - The name you want to give to your image

Image Legal Terms URL - optional - The URL to a description of the legal terms. Defaults to VM Depot's default Terms of Use if left blank.

Description - optional - Give your submission details. What's included in your installation? Any configuration details? Let others know why they should use your submission.

URL of the VHD file to publish - required - The URL to the .vhd file in a public Windows Azure blob storage image (important note - the vhd file must reside in a public windows Azure Blob). See this page on how to make containers in your Windows Azure storage subscription public.

Regions - required - Allows you to specify which regions can access your submission. By default publishing occurs to all regions and should not be changed unless you need to specifically limit distribution of your submission e.g. your submission cannot be published to Asia for legal reasons. Users in omitted regions will not be able to access your submission.

Platform - required - Select what platform your submission is based on.

EndPoints - optional - You can add EndPoint mappings here. Click the "Add New Endpoint" link to open up a public port and map it to a local port.

Packages - optional - Installed packages included in the image (e.g. apache, mysql, php, tomcat). This field features an auto complete functionality. Simply start typing and a list of packages starting with the prefix you supply will appear. Although this field is not required, it is highly recommended you complete this field as it will help others search and find your submission.

Tags - optional - Any additional descriptive tags you want to give your submission (e.g. CMS, blog, forum, appserver).

Accept the terms of use - required - click the box to accept the terms of use.

Click "Publish"

After submission - The Publishing Process

Once you have successfully submitted your image, you will be directed to a page titled "My Image Publish Status." This page will allow you to see your pending image operations and the status of replication to all regions, as shown in in this image:

Once replication to a region has completed your submission will be immediately available in that region.

As soon as publishing to the first region has completed (Highlighted blue in the "Locations" column) you can click "my images" in the left side navigation to see images already available as well as the details and any community feedback for your submission:

Working with Published Images

You can edit, delete, or publish an upgraded version of your published images by selecting the image from "my images" in the left side navigation. Once you select an image, the menu displays the following options:

Deployment Script generates the deployment script for the image as outlined previously in this document.

Publish starts a new publishing process.

Publish Upgrade creates a new version of the same image. See below for more details on this process.

Edit allows changes to everything except the image URL. To make a change to the URL, click the publish icon to publish a new image.

Delete removes all replicas of the currently selected image form VM Depot. The original file outside of VM Depot is retained in its original location in its original public Azure Blob unless it is deleted separately.

Publishing a new version of an Existing Image

Once an image is created, you can easily create a new version of that image. Select the image from "my images" in the left side navigation then select "Publish Upgrade":

Image name - For upgrades, the image must be based on the same name, so Image name is not editable.

Image Legal Terms URL - optional - The URL to a description of the legal terms. Defaults to VM Depot's default Terms of Use if left blank.

Image Description - optional - The original image description is retained. Add any new details to the image description below.

Image Version description - optional - Describe the version of your submission and what's changed.

URL of the VHD file to publish - required - The URL to the .vhd file in a public Windows Azure blob storage image (important note - the vhd file must reside in a public windows Azure Blob). See this page on how to make containers in your Windows Azure storage subscription public.

Regions - required - Allows you to specify which regions can access your submission. By default publishing occurs to all regions and should not be changed unless you need to specifically limit distribution of your submission i.e. your submission cannot be published to Asia for legal reasons. Users in omitted regions will not be able to access your submission.

Platform - For upgrades, the image must be based on the same platform, so it is not editable.

Packages - optional - Installed packages included in the image (e.g. apache, mysql, php, tomcat). This field features an auto complete functionality. Simply start typing and a list of packages starting with the prefix you supply will appear. Although this field is not required, it is highly recommended you complete this field as it will help others search and find your submission.

Tags - optional - Any additional descriptive tags you want to give your submission (e.g. CMS, blog, forum, appserver).

Accept the terms of use - required - click the box to accept the terms of use.

Click "Publish Upgrade"

After submission - The Publish Upgrade Process

As with publishing for the first time, you will be directed to a page titled "My Image Publish Status." This page will allow you to see the upgraded image publication status and the status of replication to all regions, as shown here:

When the publishing of an upgrade has completed (Highlighted blue in the "Locations" column) you can click "my images" in the left side navigation and select the image entry to see details of the upgraded image. When upgrades are published, an update to the existing entry is made showing the latest upgrade as the main version, with the Image Upgrade Description below the original description. Older versions are available at the bottom of the entry, via the link in the time stamp for the older version, as shown here:

Rate and Comment

Once you have logged into the VM Depot you will be able to rate and comment on images. To do this, click on the submission for which you want to give feedback from the "Browse Images" tab to display the submission details. Underneath the details on the page there will be a link that says "Comment/Rate this Submission."

Clicking this link will display a comment box and a rating option. You may leave a comment, select a rating or both. Once you have finished your feedback click submit. Your feedback will be instantly available to the community.

To view feedback on your own submissions you can either find and select it from the "Browse Images" tab, or click on the "My Account" tab and find it under your submissions. Click on the submission to show the details including any community feedback.

You may also review any feedback you have given others by clicking on the "My Account" tab and looking under the "Reviews" heading.

Helpful Links:

Contact us | Privacy & Cookies | Terms of use | © 2013 Microsoft Open Technologies, Inc.