HCL VersionVault Express on the Azure Cloud Platform

Introduction

Learn  how to get an instance of the HCL VersionVault Express virtual machine up and running in a public or private cloud on the Azure Cloud Platform.

Getting started

To get started, you need an Azure account connected to the Azure Cloud Platform. Although you can use the Azure Cloud Console with your browser to work with virtual machines, you might also consider downloading and installing the Azure CLI to get command-line tools (see https://docs.microsoft.com/en-us/cli/azure/install-azure-cli). For the purposes of this article, we assume that you have the Azure CLI and can use the command-line tools. You need to know your Azure zone, region, VPC, and subnet as you proceed. Go ahead and log in to your Azure account.

az login

If you have multiple subscriptions, you can specify the correct subscription ID during login and set the account subscription.

az login –tenant <tenant_ID>

az account set –subscription <subscription_ID>

Resource group

In Azure, a resource group is required to hold all your resources. If you do not have one already defined, create a new one, like so:

az group create –name myVVExpressRG –location eastus

Generating or getting the VHD file

VersionVault Express is delivered as a virtual machine in the form of an OVA file (assumed to be copied to the /my_pathdirectory). Before you can use the OVA file in the Azure Cloud Platform it must be converted to a VHD disk image, which is what Azure uses.

Alternatively, you can use the provided VHD image if it is available for your version.

Using the OVA file to extract and convert to VHD

A way to do the conversion is to use the free VirtualBox tool VBoxManage (see https://www.virtualbox.org/wiki/Downloads). First, extract the contents of the OVA file:

tar -xvf /my_path/vvexpress.ova

The extracted files include a disk image in VMDK format with a name like versionvault-disk001.vmdk. Use that file with the VboxManage tool to generate the VHD file:

VBoxManage clonehd –format VHD \
/my_path/versionvault-disk001.vmdk \
/my_path/versionvault-disk001-dyn.vhd

Converting VHD to fixed size

Azure only supports fixed-size VHD disk images. Therefore, you must convert the VHD you just generated to be fixed size (not dynamic). You can use the VBoxManage utility to create a fixed VHD:

VBoxManage clonehd \

/my_path/versionvault-disk001-dyn.vhd \

/my_path/versionvault-disk001.vhd \

–variant Fixed

Using a provided VHD

A ready-to-use VHD might be available for your version. In this case, you can use this VHD directly.

Uploading and Importing the VHD

Creating a storage account and container

Create an Azure storage account so that you can upload the VHD file as a blob and then use that blob to create an OS disk image that can be used by a VM. Note, the storage account name must be lowercase letters and numbers and must be unique in all of Azure.

az storage account create \
–resource-group myVVExpressRG \
–name foobarvvestg \
–allow-shared-key-access

Now create a container in your account to hold the uploaded blob (the VHD file).

az storage container create \
–account-name foobarvvestg \
–name vvevhds

Uploading the VHD and creating the disk

Now you can upload the VHD as a blob in the container you just created:

az storage azcopy blob upload \
–account-name foobarvvestg \
–container vvevhds \
–source “/my_path/versionvault-disk001.vhd” \
–destination “versionvault-disk001.vhd”

The blobname (destination) can be whatever you want. Then, use the following commands to find the URL for this blob to use later to create the OS disk:

az storage account show-connection-string \
–resource-group myVVExpressRG \
–name foobarvvestg

az storage blob url \
–connection-string “<from above>” \
–container-name vvevhds \
–name versionvault-disk001.vhd

Create an Azure disk to hold the uploaded VHD disk image so that a VM can use it. The source comes from the blob URL above.

az disk create \
–resource-group myVVExpressRG \
–name myVVEdiskOS \
–sku standard_lrs \
–source https://foobarvvestg.blob.core.windows.net/vvevhds/versionvault-disk001.vhd

Tip! If you get an error about an unsupported dynamic disk, you need to go back and convert your VHD file to a fixed one, as explained earlier.

Creating a Network Security Group

VersionVault Express uses up to four ports. You can choose to expose all of them or some of them, but you need at least one port exposed. To expose ports, create a network security group with the right rules that can be used by the VMs you create below.

The ports you might choose to expose are:

• The VersionVault Express browser interface/REST APIs, which is configurable but is on port 443 by default
• The VersionVault Express appliance setup console on port 8443
• The server that the VersionVault client connects to on port 8080
• The SSH interface to the virtual machine on port 22.

Additional ports might be needed based on your configuration and features introduced in different versions. Consult the release note for a full list.

Create the network security group and add a rule to open all the ports:

az network nsg create \
–resource-group myVVExpressRG \
–name myVVEnsg

az network nsg rule create \
–resource-group myVVExpressRG \
–nsg-name myVVEnsg \
–name myVVEnsgrule \
–priority 100 \
–access Allow –direction Inbound \
–destination-address-prefixes ‘*’ \
–destination-port-ranges 22 443 8443 8080 \
–source-address-prefixes ‘*’\
–source-port-ranges ‘*’

Tip! You need to expose the VersionVault Express appliance setup console to configure your source virtual machine, but you should disable ports 8443 and 22 when you put your machine image instances in production.

Creating a VM instance

Now that the OVA file has been uploaded (as a VHD disk image) and you have a network security group, you can start a VM instance running based on the disk image. Be sure to check the latest VersionVault Express system requirements to get the recommended memory and CPU count for your VM. Then check the Azure documentation to find suitable values to match the recommendations for the VM size (for example, https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/) and disk SKU values (for example, https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#disk-type-comparison and https://docs.microsoft.com/en-us/cli/azure/disk?view=azure-cli-latest#az_disk_create). Also, the VersionVault Express virtual machine is designed such that your data (VOBs, views, and other instance-specific data) require their own disk. Decide on an appropriate size for the second disk. Your commands should look something like this:

az disk create \
–resource-group myVVExpressRG \
–name myVVEDiskVOB \
–location eastus \
–size-gb 100 \
–sku standard_lrs

az vm create \
–resource-group myVVExpressRG \
–name myVVEVM \
–public-ip-sku Standard \
–nsg myVVEnsg \
–attach-os-disk  myVVEdiskOS \
–os-type linux \
–size Standard_B2ms \

–location eastus \
–attach-data-disks  myVVEDiskVOB \
–boot-diagnostics-storage “foobarvvestg”

When VersionVault Express launches for the first time, it performs two checks. The first is to check that you have mounted a disk for your VOBs. If you have been following along, you have done this. The second check is to see if the networking has been configured. VersionVault Express presents a default network configuration that you can accept or make changes. The default configuration should be fine with the Azure Cloud Platform. If you were sitting in front of the VM, you can press any key to let VersionVault Express continue booting. However, if you are launching the VM for the first time in the Azure Cloud. you might not be able to see the prompt, and, therefore, not press any keys. After 10 minutes VersionVault Express times out and you get the default network configuration.

Configuring the VM

By now, the VersionVault Express VM should be running, but you cannot log in. One reason for this is that you have not created any users yet. Also, most of the VersionVault Express processes have not started yet. The one process that you do need will have started —- the appliance setup console.

The VersionVault Express system administrator uses the appliance setup console to configure VersionVault Express and to manage VersionVault Express users. The appliance setup console runs on port 8443 (remember that network security group?) and provides a browser interface and a REST API.

You must configure at least the bare minimum to proceed.

Local administrator

The first thing you must do is create your system administrator user. The first user who tries to log in is granted local administrator rights.

Important! Do not forget or lose this account.

Either point your browser at https://myVVEVM IP:8443 and choose a username and a password, or use the REST API (which is described at https://myVVEVM IP:8443/setup/swagger-ui.html) to post to the createInitialAdminUser() API. Note that myVVEVM IP is the IP address of the VM created by the az vm create command above.

Hostname

You might consider changing the host name for your virtual machine to something resolvable in DNS if you intend to use email notifications or webhooks.

Port, certificate, and SSH keys

You must set a port or accept the default port, which is 443. Remember to expose your port in your network security group. If you have SSL certificates or SSH keys, add them now.

Licensing

You might need to enter your license information. If you do not, HCL assumes this VersionVault Express instance is running a limited-time free trial.

LDAP server

VersionVault Express can either manage its own users (the default configuration) or bind to an external LDAP server. Now is the time to decide which of those is for you.

If you choose to manage your own users, you might want to create at least one user now. This can be done using either the appliance setup console or the REST APIs. To use the setup console, enter the email address of the new user, and click the Add user button. If you configured an SMTP server, the user will receive an email inviting them to create an account. If not, toggle the Temporarily disable SMTP switch and then click the mail icon in the table of users. This launchs your default mail client and allows you to send the invitation from there.

Validating configuration

Verify all entries (most of the section have some “check” or “validate” button) then save your configuration and launch VersionVault Express.

If you created a user, have them follow the link in the email they received to sign up and log in.

Final test

By this point, you should have a VersionVault Express instance running and at least one user who can log in. Test it by opening a browser and connecting to your port on your IP address (or hostname if you have DNS configured). There are no projects or VOBs yet.

Your VM is ready for production now.

Using VersionVault Express

Now you are ready to start using VersionVault Express. Log in using one of the pre-configured user(s) and create your first project. If your system allows it, invite more users to join your project. If not, ask your system administrator to invite new users for you.

Additional information

Stop a VM instance

You can stop the VM using the Azure CLI like this:

az vm stop \
–resource-group myVVExpressRG \
–name myVVEVM

az vm deallocate \
–resource-group myVVExpressRG \
–name myVVEVM

Creating more VM instances

You might choose to give each project team their own instance, or perhaps allocate instances to different business units within your organization. To create a new instance, use the following steps:

• Create a new OS disk (called myVVEdiskOS above) from your uploaded blob.
• Create a new VOB disk (called myVVEdiskVOB above).
• Create the new VM instance using the new disks (called myVVEVM above) and configure it. You can use the same network security group that you created before (called myVVEnsg above).

Using multiple resources group

Your IT environment might have predefined resource groups that you can use, or you might want to use multiple ones to separate the various configuration (subnet, nsg, disk, and so on). In such cases, when working from the command-line, you must provide the full resource path for each one you use because this is a requirement in the Azure command-line, If not, it will try to resolve all resources to the “default” resource group and will fail if not accessible. Example for creating a new VM:

az vm create

–resource-group <RESOURCE_GROUP_1> \

–name <VM_NAME> \

–subnet /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/ <RESOURCE_GROUP_2>/providers/Microsoft.Network/virtualNetworks/<VNET>/subnets/<SUBNET> \

–public-ip-address “” \

–nsg /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_2>/providers/Microsoft.Network/networkSecurityGroups/<NSG> \

–attach-os-disk /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_3>/providers/Microsoft.Compute/disks/<VIRTUAL_OS_DISK> \

–os-type linux \

–size Standard_B2ms \

–location <REGION> \

–attach-data-disks /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_3>/providers/Microsoft.Compute/disks/<VIRTUAL_DATA_DISK>