VMware AppCatalyst Technical Preview June 2015 TECHNICAL WHITE PAPER
VMware AppCatalyst is an API and Command Line Interface (CLI)-driven Mac hypervisor that is purpose-built for developers, with the goal of bringing the data center to the desktop. Currently a technology preview, VMware AppCatalyst offers developers a fast and easy way to replicate a private cloud locally on their desktop for building and testing containerized and microservices-based applications. The tool features Project Photon, an open source minimal Linux container host, Docker Machine and integration with Vagrant. To download the latest build, seek assistance, and provide feedback, please visit the AppCatalyst community site. We d love to hear from you especially if you re trying to integrate your tools with AppCatalyst, or if you ve got cool ideas about what you think it should do next. Minimum Requirements OS X : Mavericks - 10.9.4 OS X : Yosemite - 10.10 Getting Started By the end of this section you ll have a working installation of AppCatalyst on your Mac. Please note that Fusion shouldn t be running at the time of your interaction with. 1. Download the dmg file and launch the installer. 2. Locate the downloaded VMware-AppCatalyst-Technical-Preview-June2015.dmg that is in your Downloads folder. 3. Install by stepping through the wizard, and if you agree with the conditions of the EULA, click Continue TECHNICAL WHITE PAPER / 2
4. When the installation completes, you will NOT see AppCatalyst appear under your /Applications Folder. Please use the Terminal to navigate to /opt/vmware/appcatalyst. 5. An instance of Project Photon is provided for you in the photonvm template directory in: /opt/vmware/appcatalyst 6. Set your PATH to include: /opt/vmware/appcatalyst/bin 7. Run appcatalyst to get a list of commands available for your use. Your output should be similar to: Build #2836636 Copyright (C) 2015 VMware Inc. All Rights Reserved Usage: appcatalyst <domain> <command>... If your output is significantly different, please check on your prior steps. Conventions Across AppCatalyst <id> refers to a friendly name of a specific environment - container host run-time VM that you will be interacting with. Deploy a Project Photon Linux Container Host By following the steps below, you will create/clone a Photon instance from the template provided, generate a list of all named VMs available to the logged in user, start the Photon instance, get its IP, ssh to the instance and launch a sample container. 1. Create a new Virtual Machine that we can use. Pick a name for your VM and refer to it by <id>. For this step we re using photon as that name. $ appcatalyst vm create <id> NOTE: This will make a copy of the Photon VM template, and place it into the default directory ~/Documents/AppCatalyst/ under the <id> you specified Your directory structure be resemble: ~/Documents/AppCatalyst photon photon-disk1-cl2.vmdk photon.nvram photon.vmsd photon.vmx photon.vmxf 1 directory, 5 files 2. List all named VMs available to you: $ appcatalyst vm list TECHNICAL WHITE PAPER / 3
3. Start your VM: $ appcatalyst vmpower on <id> NOTE: The command will return rapidly, but depending on your machine it will take a few seconds to start the VM. Other vmpower options include: on off shutdown suspend pause unpause 4. Get the IP address of the VM: $ appcatalyst guest getip <id> 5. SSH to the VM: $ ssh -i /opt/vmware/appcatalyst/etc/appcatalyst_insecure_ssh_key photon@<ipaddress> 6. From here, containers can be securely launched with the help of Project Photon: $ sudo docker run -d -it -p 80:80 vmwarecna/nginx > NOTE: Since this the first time running the nginx container, it will be retrieved from the online Docker Hub repository. TECHNICAL WHITE PAPER / 4
1. Once complete, use your web browser to navigate to the <ipaddress> you retreived in a prior step. Congratulations! You have deployed your first Project Photon container host, running the nginx service as a Docker container. Notes Default Configuration The settings for AppCatalyst reside in the home directory of the active user: ~/.appcatalyst.conf Includes definitions for > DEFAULT_VM_PATH DEFAULT_PARENT DEFAULT_LOG_PATH PORT Logs Available at /Users/<your_username>/Library/Logs/VMware TECHNICAL WHITE PAPER / 5
REST-API The AppCatalyst REST API is documented using the Swagger API framework. To get started: 1. First run the daemon appcatalyst-daemon in /opt/vmware/appcatalyst/bin/ 2. Open your browser, and navigate to http://localhost:8080 - which will always have the latest API definitions for the installed build of AppCatalyst 3. A sample is included below Method Route POST DELETE PATCH PATCH POST DELETE PATCH /vms /vms /vms/{id} /vms/{id} /vms/power/{id} /vms/power/{id} /vms/{id}/folders /vms/{id}/folders /vms/{id}/folders /vms/{id}/folders/{folderid} /vms/{id}/folders/{folderid} /vms/{id}/folders/{folderid} /vms/{id}/ipaddress Example 1 - Retrieve the IP Once appcatalyst-daemon is running, navigate to the following address, substituting <id> for your VM name: http://localhost:8080/api/vms/<id>/ipaddress The browser will respond with the IP of that VM TECHNICAL WHITE PAPER / 6
Example 2 - Powering on the VM with Swagger In this example we will power on a VM via the REST API, directly through the Swagger API Portal. 1. Navigate to the Swagger address: http://localhost:8080/ 2. Expand the PATCH method for /vms/power/{id}. Now fill out the form: > <id> = photon op = on click Try it out! appcatalyst_swagger_example 3. A few seconds later, when the operation completes, you will be presented with a Response below. appcatalyst_swagger_example_response TECHNICAL WHITE PAPER / 7
Known Issues In this Tech-Preview of June 2015 release, the following limitations exist: 1. VMware Fusion should be fully shutdown prior to launching AppCatalyst. 2. Virtual hardware version 11 or later 3. No USB or Sound devices 4. VGA only, set in the.vmx file: svga.vgaonly = TRUE 5. Only Linux virtual machines are supported. TECHNICAL WHITE PAPER / 8
VMware, Inc. 3401 Hillview Avenue Palo Alto CA 94304 USA Tel 877-486-9273 Fax 650-427-5001 www.vmware.com Copyright 2015 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies. Item No: VMW8326-WP-APPCATALYST-TECH-PREVIEW-USLET-101 07/15