Micro Cloud VM¶

By default, the Stackato VM starts as a single node "micro cloud" with a base set of roles already running and ready to use. This can be used as a test bed for pushing applications still in development. If your program deploys successfully to a Stackato micro cloud, it will deploy to any Stackato PaaS of the same version. The application hosting environment is the same in all aspects except scale.

This section describes running the Stackato VM as a micro cloud. To get started building a cluster, see the Cluster Setup section.

Download the VM¶

Download a Stackato VM in the hypervisor format of your choice or get access to an image hosted on Amazon EC2 or HP Cloud Services.

Host system requirements:

x86_64 processor with VT-x enabled (x86 virtualization).
3GB+ memory
20GB+ disk space

Note

The Stackato VM uses 2GB of memory by default. Ensure that there is sufficient memory remaining on the host system to run the host operating system and any other applications you require.

Import the VM¶

The steps for importing and starting the Stackato VM will vary depending on which hypervisor and OS you are using. Follow the steps in the relevant guide below, then continue with Initial Configuration:

Start the VM¶

On first boot, the Stackato VM generates a hostname in the form stackato-xxxx.local which is displayed on the hypervisor console. It receives its IP address via DHCP and broadcasts the generated hostname on the local subnet via multicast DNS.

You will use this hostname to connect to open the Management Console in a browser or connect with the Stackato CLI client.

Note

The default password for the stackato system user is stackato. This password is changed automatically when you set up the first administrative user in the Management Console. Once you've set up the primary Stackato admin account, use that account's password when logging in at the command line.

NAT vs. Bridged Networking¶

The VMware and VirtualBox start virtual machines with NAT networking enabled by default.

If you are using VirtualBox to run the Stackato VM, configuring "Bridged" networking before starting the VM is the simplest way to set it up. If you need to run in "NAT" mode, configure port forwarding as per the VirtualBox documentation.

Bridged networking exposes the VM through the hypervisor host system to your local network. This makes it easier to connect with Stackato servers running on other hosts, but should only be done on trusted networks.

NAT networking exposes the VM only to the host system (unless routing through the host is configured). This is a preferable configuration if you are operating on an untrusted network.

Note

Multiple hosts broadcasting the same name via mDNS on the same network can cause confusion and network problems. If you plan on running multiple Stackato micro clouds on one network:

Make sure the MAC address of each virtual machine is unique.

Change the hostname if not already unique, or

use NAT networking, or

configure DNS manually.

DNS vs. mDNS¶

By default, the Stackato VM broadcasts its generated hostname via multicast DNS. This mDNS/DNS-SD broadcast address (e.g. stackato-xxxx.local) is intended for micro clouds running on a local machine or subnet. To use the VM on a remote subnet, the server may need one or more of the following:

See the Detailed Configuration section for instructions on setting up the Stackato VM in these situations.

Note

Windows does not properly support mDNS hostname resolution. You will need to use the xip.io service, update the Windows hosts file, or create a DNS record in order to target the API endpoint, push applications, and resolve the deployed applications.

Management Console¶

The Management Console is Stackato's web interface.

When the Stackato server finishes the start-up process, the hypervisor's tty console will display the URL of the Management Console. Enter this URL into your web browser.

Note

The SSL certificate for the Stackato Management Console is self-signed. You will need to manually accept this certificate in your browser. See the HTTPS section of the Admin Guide for information on using your own certificate.

The Management Console will load, and you will be prompted to create the first administrative user (and the first organization) for the system. Use these account credentials to push applications, create additional users, and configure the system.

Note

The password you set here will become the new password for the stackato system user for access via SSH or the hypervisor console.

Adding Organizations¶

Stackato will automatically create an organization when the first admin user is set up, but you may wish to add more. Do this on in the Organizations view in the Management Console.

Not that each organization has an assigned quota definition, which should be changed or edited to reflect the resources available on the VM/cluster.

Adding Spaces¶

Before members of an organization can deploy applications, one or more spaces must be added to the organization. The Managment Console will prompt for creation of the first space, and subsequent spaces can be created by clicking the + Add Space button in the Organization view (or the stackato create-space command).

Adding Users¶

The easiest way to add additional users is in the Users section of the Management Console (or the stackato add-user command):

$ stackato add-user username [--passwd password]

Enabling Services¶

In order to leave as much memory as possible available for user applications, the micro cloud starts with a number of services disabled by default:

Memcached
Redis
RabbitMQ
MongoDB

You can enable them individually in the Management Console under Admin > Cluster > Node Settings (cog icon button), or use kato role add.

Using Stackato¶

An administrator's view of the Management Console provides access to most commonly configured system settings, control over the roles that are running on the VM, and views of the system log streams and other metrics.

End users of the system without admin privileges have a more limited view, showing only information for their user or group accounts. Deploying applications and consuming system services is covered in the Stackato User Guide.

Resolving VM Hostname Without mDNS¶

Using xip.io¶

The quickest way to set up wildcard DNS resolution is to use the xip.io (or similar) service. This service provides wildcard DNS resolution for addresses with the format: <IP address>.xip.io

To change the hostname of the Stackato VM, log in to the VM via SSH or the hypervisor console (username: 'stackato', default password: 'stackato'), then run kato node rename ... with external IP address and the 'xip.io' domain appended. For example:

$ kato node rename 10.9.8.7.xip.io

This will change the system hostname and reconfigure some internal Stackato settings. The xip.io DNS servers will resolve the domain '10.9.8.7.xip.io' and all sub-domains to '10.9.8.7'. This works for private subnets as well as public IP addresses.

Updating the Windows Hosts File¶

If you are running Windows, multicast DNS discovery of a locally running Stackato micro cloud will not generally work. One solution is to manually set the mapping for the API endpoint and for each application in the Windows hosts file.

Note

Using xip.io for hostname resolution is the easiest way to set up a Stackato micro cloud VM if mDNS is not an option. Try this method before modifying the hosts file.

To modify the hosts file open:

%SystemRoot%\System32\drivers\etc\hosts

The hosts file typically has some comments and one or two entries. Add your new entries to the bottom of the file on their own lines.

You'll need to add an entry for the API endpoint and for each application, along with their corresponding IP addresses. To determine the IP address of the Stackato server, open the server window and enter the command:

$ ifconfig

Then, if for example your IP address is 192.168.68.54, the API endpoint is api.stackato-xxxx.local, the AOK (authentication) endpoint is aok.stackato-xxxx.local, and you have an app called myapp.stackato-xxxx.local, you would enter the following lines:

192.168.68.54 api.stackato-xxxx.local
192.168.68.54 aok.stackato-xxxx.local
192.168.68.54 myapp.stackato-xxxx.local

Uninstalling the VM¶

Using the Stackato VM makes no changes to the underlying host operating system.

If you wish to remove it, simply select the VM in your hypervisor and select Remove... or Delete... as appropriate.