This is documentation for Apprenda 7 and 8.
Documentation for older versions are also available.

The Apprenda Cloud Shell

The Apprenda Cloud Shell (ACS) is a command-line interface for Developers. The ACS works primarily against the Apprenda Developer Portal application to facilitate Developer workflows, as well as open up the Developer Portal to automation and integration with external systems.

The ACS allows you to store multiple cloud URLs and access them by alias in the future in order to connect to an instance of the Apprenda Platform with your Developer account credentials. Once connected to a particular Cloud, an entire Visual Studio solution can be compiled, packaged, uploaded and published using a single command. The output of these commands can be piped to logs if desired (part of a build/package/deploy nightly process for which you'd like to review logs).

Also see ACS Help for more information about the commands for this tool.

Prerequisites for ACS Usage and Automated Application Deployment

The following are required to use most ACS functionality:

  • a Developer account on an instance of the Apprenda Platform
  • an affiliated User* with the required Account and/or Developer Portal securable permissions to perform the desired actions
  • a Cloud URL for your Platform; information on finding this can be found here
  • the Apprenda Archive Builder and ACS require Microsoft Build Tools 2015 which is included in Visual Studio 2015 or available for download here: https://www.microsoft.com/en-us/download/details.aspx?id=48159

*If the User has been created using Federated Identity, he or she will need to establish a Platform password by clicking the "Forgot Your Password?" link found on the login page for the Apprenda instance. The newly established password and affiliated e-mail address can then be used to establish a connection through the ACS.

The following Platform capabilities support fully-automated application creation and patching through the Apprenda Cloud Shell:

  • Most deployment information (some of which is required before an application can be promoted to the Sandbox or Published stage) for the initial version of an application, including Resource Policies, Application Services, and Entitlement Definitions, can be configured through a Deployment Manifest included inside your application's archive file or Visual Studio solution.
  • Information for patched versions of an application can be specified via the application archive structure.  For example, database patching can be accomplished by providing a collection of SQL scripts in a patch archive and including instructions on how to run them directly within the archive's Deployment Manifest.  This means that an entire application patch (UIs, services, databases, etc.) can be packaged into a single archive file and the app can be patched via the ACS.

Hint: You will be able to automate publication of applications with Authorization or Multi-tenancy only if the necessary Entitlement Definitions have been configured through a Deployment Manifest.

Common ACS Workflows

The following outlines some of the more common workflows enabled through the ACS and examples of their corresponding commands.  A full list of ACS commands and required/optional parameters can be found on the ACS Help page or by executing the ReadHelp command.

Manage connections to an instance of the Apprenda Platform

Register an Apprenda instance:

acs RegisterCloud -url http://apps.myprivatecloud.com -alias mycloud

List current connection and registered clouds:

acs ReadStatus

Connect to an Apprenda instance (if you belong to more than one Development Team on the Platform, be prepared to specify the alias of the Development Team under which you would like to connect):

acs ConnectCloud -cloudAlias mycloud -user myemail@mycompany.com -password mypassword -DevTeamAlias devteam1 -remember

Disconnect from an Apprenda instance:

acs DisconnectCloud

Create a new User for your Development Team account

Required Account Portal Securables:

  • for User creation: Manage Users, Manage Subscriptions
  • to add Users to Roles: Manage Roles      
acs NewUser -emailAddress jdoe@mycompany.com -firstName Jane -lastName Doe -password janespassword -roles developer,tester   

Package a Visual Studio solution as an Apprenda Archive

acs NewPackage -O "C:\MyApplicationArchive.zip" -Sln "c:\MyProjects\PathTo\MyNewApplication.sln" -b

Note: the '-b' option will build the VS solution.  For a full list of options for packaging an archive, run 'acs NewPackage /?'

Create a new application using an Apprenda Archive or Visual Studio solution

Required Developer Portal Securables:

  • to create an application: Manage Applications
  • to upload an archive/packaged solution: Develop Application Versions
  • to promote the application to the Sandbox stage: Promote to Sandbox
  • to Publish the application: Promote to Published

The following command will create and Publish a new application based on a pre-packaged Apprenda Archive, and will create 2 UI instances and 3 instances of each .NET service:

acs NewApplication -appAlias myalias -appName "My New Application" -package "c:\MyApplicationArchive.zip" -stage Published -UiInstances 2 -ServiceInstances 3
The following command will create a new application based on an unbuilt Visual Studio solution and promote it to the Sandbox stage; it also specifies the primary UI:
acs NewApplication -appAlias myalias -appName "My New Application" -path "c:\MyProjects\PathTo\MyNewApplication.sln" -b -stage Sandbox -PrivateRoot MyPrimaryUserInterface

Hint: A valid Apprenda Archive that contains UIs must designate the primary UI as "root".  If your primary UI project is not called "root," you must specify it through the '-PrivateRoot' option when building your archive from a Visual Studion solution through the NewPackage, NewApplication, or NewVersion commands in the ACS.

 

Create a patched version of an application using an Apprenda Archive or Visual Studio solution

Required Developer Portal Securables:

  • to create a new version of the application and upload an archive/packaged solution for a patched version: Develop Application Versions
  • to promote the application to the Sandbox stage: Promote to Sandbox
  • to Publish the application: Promote to Published

The following command will create a new application version based on a pre-packaged Apprenda Patch Archive, and will constructively apply the patch archive (otherwise, destructive patching is the default):

acs NewVersion -appAlias myalias -versionAlias v2 -package "c:\MyPatchedApplicationArchive.zip" -constructive

The following command will create a new application based on an unbuilt Visual Studio solution suitable for patching and promote it to the Sandbox stage:

acs NewVersion -appAlias myalias -versionAlias v2 -path "c:\MyProjects\PathTo\MyPatchedApplication.sln" -b -stage Sandbox 

Upload an archive for an existing application or application version

Required Developer Portal securables: Develop Application Versions

The following command will upload a prepared archive for Version 1 of an existing application while it is in the Definition stage:

acs SetArchive -appAlias myalias -versionAlias v1 -package "c:\MyApplicationArchive.zip"

The following command will package and upload an unbuilt Visual Studio solution suitable for patching for an existing patched version of an application while it is in in the Definition stage:

acs SetArchive -appAlias myalias -versionAlias v2 -path "c:\MyProjects\PathTo\MyPatchedApplication.sln" -b 

Promote an application version

Required Developer Portal Securables:

  • to promote the application to the Sandbox stage: Promote to Sandbox
  • to Publish the application: Promote to Published

Promote an application version to the next stage:

acs PromoteVersion -appAlias myalias -versionAlias v2

Promote an application version specifically to the Sandbox stage:

acs PromoteVersion -appAlias myalias -versionAlias v2 -stage Sandbox 

Promote an application version specifically to the Published stage and suppress all prompts:

acs PromoteVersion -appAlias myalias -versionAlias v2 -stage Published -y 

Patch and promote an application version (available for Apprenda Platform version 4.5.4 and later)

Required Developer Portal Securables:

  • to create a new version of the application and upload an archive/packaged solution for a patched version: Develop Application Versions
  • to promote the application to the Sandbox stage: Promote to Sandbox
  • to Publish the application: Promote to Published

The following command will upload a pre-packaged Apprenda Patch Archive for Version 1 of an existing application in the Definition stage, and then promote that application version to Published (destructive patching is defaulted to since the "-constructive' parameter is excluded):

acs PatchVersion -appAlias myalias -versionAlias v1 -package "c:\MyPatchedApplicationArchive.zip" -stage Published

The following command will create Version 2 of an application based on an Apprenda Patch Archive (constructively applying the patch archive), and will promote Version 2 to the Sandbox stage:

acs PatchVersion -appAlias myalias -versionAlias v1 -newVersionAlias v2 -newVersionName "Version 2" -package "c:\MyPatchedApplicationArchive.zip" -stage Sandbox -constructive

Demote an applicaton version

Required Developer Portal Securables: Promote to Sandbox

Demote an application version from the Sandbox to the Definition stage:

acs DemoteVersion -appAlias myalias -versionAlias v2 -y

Delete an application version

Required Developer Portal Securables: Manage Applications or Develop Application Versions

acs RemoveVersion -appAlias myalias -versionAlias v2 

Delete an entire application

Required Developer Portal Securables: Manage Applications or Develop Application Versions

acs RemoveApplication -appAlias myalias 

Set instance counts for .NET services, Windows Services, Java Web Applications, and user interfaces

Required Developer Portal securable: Develop Application Versions

Scale the instance count for a specific .NET service to a specified number (use the "GetStatistics" command to view specific component naming): 

acs SetInstanceCount -AppAlias myalias -VersionAlias v2 -Component wcfsvc-AwesomeWCFService 2 

Scale the instance count for a specific Java Web App up or down by a specified number:

acs SetInstanceCount -AppAlias myalias -VersionAlias v2 -Component war-AwesomeJavaWebApp +|-1

Scale the instance count for UIs to a specified number:

acs SetInstanceCount -AppAlias myalias -VersionAlias v2 -Component ui-UserInterface 1

Set the Minimum Instance Count for a .NET service, Windows Service, Java Web Application, or user interface

Required Developer Portal securable: Develop Application Versions

Set the Minimum Instance Count for an app component to a specified number (use the "GetStatistics" command to view specific component naming):

acs SetInstanceMinimum -AppAlias myalias -VersionAlias v2 -Component ui-UserInterface -MinCount 3 -Enforced true

View available Add-Ons and provisioned instances

Required Developer Portal securable: Manage Add-Ons

View all available Add-Ons on your Apprenda environment (including any required or optional parameters): 

acs GetAddOns 

View a list of Add-On instances currently provisioned for your Development Team, as well as connection data that guest applications can use to call each instance:

acs GetDeployedAddOns

Provision or de-provision an Add-On instance

Required Developer Portal securable: Manage Add-Ons

Provision an instance of an Add-On: 

acs ProvisionAddOn -Alias addonalias -InstanceAlias myinstance -Params -param1 value 1 -param2 value2

De-provision an instance of an Add-On:

acs DeProvisionAddOn -Alias addonalias -InstanceAlias myinstance -Y