The Apprenda Platform

(1)

The Apprenda Platform

Apprenda 3.5 Reviewer’s Guide

The Apprenda Platform is an Open Platform-as-a-Service (PaaS) stack that enables any Organization to transform their existing infrastructure or private cloud investments into a self-service cloud application platform. By decoupling applications from infrastructure and developers from IT, Apprenda empowers Organizations to achieve significant cost savings and massive productivity improvements that result in better business/IT alignment.

Published: June 2012

For full product documentation, see http://docs.apprenda.com

(2)

Activate Resource Utilization Tracking ... 12

Create Resource Policies/Storage Quotas ... 15

Enable Resource Throttling ... 18

Distribution Settings ... 18

Set Development Team Limits ... 19

For IT Pros: Onboard a Development Team ... 19

Open/Invitation Settings ... 19

Where a Dev Team Can Sign Up ... 21

For Developers: Write an Apprenda Application ... 21

Set Up the Developer Portal ... 22

Download a Sample Application ... 22

Install the SDK ... 23

Explore the Apprenda Solution Template ... 24

(3)

Develop and Test an Application Locally ... 27

Package an Application as an Apprenda Deployment Archive

... 29

For Developers: Configure and Deploy a Cloud Application for Testing ... 31

Create a New Application in the Developer Portal ... 31

Configure Application Settings ... 34

Upload a Deployment Archive ... 37

Edit Entitlements ... 38

Other Definition Options: Resource Policies... 45

Deploy in Sandbox ... 47

For Developers: Publish a Cloud Application ... 51

For Developers: Enable End User Access ... 54

Onboard End Users ... 54

Configure Permissions for End Users ... 61

For Developers: Update and Manage Cloud Applications ... 63

Update Your App and Create an Apprenda Archive for Patching ... 63

Create a New Version of the Application in the Developer Portal ... 64

Promote the New Version to the Sandbox Stage ... 67

Publish the Patched App ... 68

Scale Out Service Instances ... 69

(4)

Introduction

Platform as a Service (PaaS) is a software layer than can stitch together an arbitrary number of infrastructure resources (e.g. OS images, load balancers, etc.) into a single logical resource pool. That resource pool can then be offered to Developers as a self-service computing platform where applications are the primary citizen. Developers and their applications are abstracted away from the underlying details of the infrastructure, relying on the application itself and service requirements as the lingua franca. Developers simply upload apps to a PaaS and, in a few button clicks, deploy the application. The PaaS takes care of all of the mission-critical (but strategically unimportant) heavy lifting of allocating resources, configuring the app, and deploying it to the infrastructure. All management workflows are provided by the Platform and "wrapped" around guest applications. Additionally, a PaaS also offers platform services that an application can leverage to solve big architectural problems out of the box. A PaaS offering needs to provide applications with API access to things such as caching services, message brokering, or even application metering. The result is that Developers can achieve full productivity and not waste cycles on undifferentiated work.

Apprenda is a full-service PaaS stack for .NET. Specifically, Apprenda is a "PaaS engine" that can be layered atop any arbitrary Windows infrastructure, which is transformed into a web-accessible, self-service computing platform for .NET applications composed of any combination of web services, user interfaces, and databases. Apprenda is the best PaaS for .NET because it

1. provides a lock-in free model, ensuring that you have freedom of choice as to which infrastructure you can use.

2. beautifully supports existing application code with little to no code changes to run on the Apprenda PaaS.

3. has a plethora of APIs and frameworks to tap into high value platform services.

4. can be layered on existing infrastructure, allowing for a continued leveraging of existing investments.

5. provides high end features not found anywhere else, such as zero-effort multi-tenancy for your apps.

6. is the only mature solution that can, in 15 minutes, "plug and play" on existing infrastructure and transform it into a self-service platform for any internal or external developers.

As a PaaS, Apprenda embodies the conceptual PaaS better than any other technology on the market, meaning that Developers and IT Pros can achieve the level of full productivity promised by the description of PaaS without any compromises.

(5)

Challenges with Application Creation, Deployment and Updates: Life

Before Apprenda

In most enterprise environments, getting applications deployed and updated can be a frustrating process for all parties involved – IT, Developers and of course End Users. While virtualization has helped, most major challenges have yet to be addressed:

 Application deployment is still accompanied by server (physical or virtual) deployment.

 Dedicating physical or virtual machines for specific applications drastically increases management costs (VM sprawl) and results in poor overall utilization.

 There is too much “back and forth” between development and operations with respect to the configuration of servers and applications, i.e. setting up websites, databases, application settings, dependencies, etc.

 Application updates are often harder than initial deployments with even more bureaucracy since End Users must be transitioned to new versions without disruption.

 Cloud application constructs like elasticity, multi-tenancy and distributed execution are hard to architect and code correctly and consistently.

These factors result in overall loss of agility and time to market for Organizations since each deployment is effectively a custom operation. The public cloud offers a potential solution but may not always be a viable option for all types of applications (typically for security/compliance or technical reasons).

Apprenda offers Organizations the ability to run their own cloud application platform on the infrastructure of their choice. Apprenda provides a set of tools and capabilities for IT Pros to operate their own PaaS and provide a frictionless experience for Developers to deploy and update applications with complete isolation from the infrastructure details.

(6)

What’s New for Apprenda 3.5

Apprenda 3.5 introduces the following features and enhancements:

Application Workload Scaling API

Apprenda 3.5 enables retrieval and management of guest application component and Workload information through the API. This enables Developers to implement flexible and automated responses to production conditions that necessitate the addition or removal of web sites or web services for a guest Application, thereby allowing for a dynamically scalable application.

System Center Operations Manager Integration

In order to offer a “single pane of glass” option for Platform management, Apprenda 3.5 provides integration with Microsoft’s System Center Operations Manager (SCOM). The Apprenda SCOM management pack works in conjunction with SCOM support for SQL Server and IIS, thereby enabling seamless drill-down access to Platform infrastructure and Application Workloads. This allows IT staff to comprehensively monitor Platform health through SCOM, and provides diagnostics, recoveries and tasks to resolve common issues.

Resource Policy Assignment and Storage Quotas for Databases

Platform Administrators may now create a variety of Resource Policies and Storage Quotas for database instances. Resource Policies govern the maximum amount of CPU and Memory that a guest application may use on the system; Storage Quotas govern the maximum amount of Storage that a guest application may use. Resource Policies and Storage Quotas can both be leveraged to enforce CPU, Memory, and Storage limits for individual Development Teams. It is now also possible to configure the total CPU, Memory, and Storage on a database instance that is available for guest application use.

Recoverability and High Availability Improvements

Apprenda 3.5 introduces a number of improvements through which Platform Administrators can offer a highly available and resilient environment. These include support for database Failover Clustering, which ensures high availability of core database and application database access, as well as enhanced robustness of Platform Coordination mechanisms, which drastically reduces single-point dependencies.

Support for Leveraging Existing User Stores*

One of the most exciting additions for Apprenda 3.5 is support for leveraging existing user stores. Platform Administrators can configure an existing centralized external user store (such as Microsoft Active Directory or LDAP) as the primary system of record of Apprenda Users. Apprenda continues to support using its native user store.

(7)

Getting Started

The Apprenda Platform is available for evaluation purposes via the methods below.

Apprenda Express

Apprenda Express is a free, downloadable version of the Apprenda Platform that can be installed directly onto machines that meet our hardware and software requirements.

Installation tips, minimum installation requirements and download links for Apprenda Express can be found in the Apprenda online documentation’s Installation Guide.

Apprenda Express Pre-Configured Virtual Machine

In order to make Apprenda Express more widely available, we have developed pre-configured virtual machines with the Apprenda Express installer and trial versions of the software necessary to set up and evaluate the Apprenda Platform (minimum hardware requirements still apply).

Apprenda Express Virtual Machine downloads and installation instructions for both Hyper-V and VMware can be found at Apprenda.com.

(8)

Apprenda Platform Use Scenarios

Below you will find a short glossary of Apprenda-specific terms. The sections that follow demonstrate some of the workflows through which IT Pros configure the Apprenda Platform and make it available to Development Teams. We then walk you through scenarios that showcase how a Development Team can seamlessly develop, publish, and update their apps through the Apprenda Platform.

Key Terms

Here is an overview of key terms used in this Guide:

 An End User is an organizational group that subscribes to applications through the Apprenda Platform. Each End User can have multiple individual Users.

 Development Teams can publish applications on the Apprenda Platform for End Users to access. Development Teams are granted access to the Developer Portal via a Development Team Account by the Platform Administrator, who controls the Apprenda installation. Separate Development Team Accounts may be maintained because multiple applications built by multiple Development Teams can co-habit within an Apprenda Platform instance.

 An account is the means through which an Organization and its individual members access much of the Apprenda Platform’s functionality. An End User Account provisions and grants access to the Account Portal; this type of account is used to create and manage Users for applications that take advantage of Apprenda’s authorization or multi-tenancy capabilities. Individual User access to subscribed applications is tied to their Organization’s End User Account. A Development Team Account provisions and grants access to the Account Portal, and also to the Developer Portal, which is used to configure and publish applications on the Platform. For a Development Team Account, the two portals are linked, and both can be accessed with the same login credentials.

 An Account Administratoris the Apprenda User created when an End User or Development Team Account is provisioned. This account can then be used to create or import additional Users, as well as add security permission for other Users. Once other Users are created, it is possible to transfer this designation to another Apprenda User within the same account.

 A Platform Administrator is the person (or people) with permission to configure an instance of the Apprenda Platform. Certain Platform-wide settings, such as those pertaining to Resource Policies or the types of Application Settings and Presentation Models available for selection by Developers, are configured by the Platform Administrator.

 For an application deployed with Apprenda’s multi-tenancy capabilities, subscriptions are the primary access control mechanism for an application. Users cannot access an application without a subscription to it. The subscription also can designate what Features of an application are available to Users.

 Features are small, uniquely labeled blocks of application code that are intended to be metered and/or monetized; they are sections of code that perform a transaction that requires access control based on the defined subscription owned by the current runtime User.

(9)

 Securables are pieces of code that a Development Team has marked as governed by the Apprenda Platform’s access control system. Users in the Apprenda Platform can belong to a variety of Roles defined by the Administrator of the End User Account that owns their User profile. Through the Account Portal, an account Administrator can map defined Roles to published Securables for each application the account subscribes to.

 Entitlement Definitions are Developer-defined collections of plans for how an application will be made available to End Users. They must be configured for applications with Authorization and Multi-tenancy, and can be used to determine access to certain functions of an application. Entitlement Definitions consist of plans, which are combinations of application Features and non-application components that can either be included in a plan for a set price or optioned on to a base plan.

 The Apprenda Platform optionally enables multi-tenancy for hosted applications. To do this, Apprenda automatically transforms certain parts of a hosted application at deploy time to give the application’s architecture a single-instance, multi-End User dimension. For other parts of the application, the Platform relies on runtime instrumentation to accomplish its tasks.

 Runtime Binaries represent the code that will be deployed when an application is promoted to Sandbox or Published status. This application version will be based on an uploaded Deployment Archive file, which will contain the components of the application including user interfaces, services, a database creation script, and an onboarding script.

Use Scenarios Explained

If you have installed Apprenda Express and are reading this Guide, you are presumably running the Apprenda Platform on a trial basis, and you wish to familiarize yourself with the ways that different kinds of users at all levels of your Organization would interact with the Platform. In order to test the different use scenarios, you will most likely have to play each of these roles yourself. To lend context to the testing experience, this Guide proposes that you imagine you are part of a Banking Organization that has its own in-house Development Team and several Banking Branches that will be accessing their banking software through the Apprenda Platform. Initially, you will play the role of IT Pro and Platform Administrator

when you install and configure the Platform. Next, you will play the role of a Developer who, as part of the Banking Organization’s Development Team, develops, tests, and publishes an Apprenda Application to be accessed by employees at the various Banking Branches. After that, you will need to play the role of

End User Account Administrator in order to subscribe to the Apprenda Application and distribute and configure individual Users access. In this scenario, each Banking Branch would possess a unique End User Account, run by an Account Administrator (in this case, the Branch Manager), and the employees of each Branch would be hosted as Users in their Branch’s End User Account. Finally, you can play the role of an individual User (in this case, a Branch employee) accessing an Apprenda Application through the Platform UI. By playing each of these roles, you will be able to interact with the Apprenda Platform at every level, from Platform-wide configuration and app development to account management and individual User access.

(10)

For IT Pros: Configure the Platform

In the hypothetical use scenario explained in the previous section, your Banking Organization has chosen to use the Apprenda Platform to make its software available for access by its Banking Branches. The first role you need to play is that of the Platform Administrator, who is part of the IT staff, and who must configure the Apprenda Platform settings before your Development Team can be granted access and its applications hosted.

A PaaS like Apprenda is useful only in the context of getting Developers to deploy apps to it. A first step in evaluating the Apprenda PaaS is granting Development Teams access to it. Before granting Development Teams access to the Apprenda Platform, however, you will need to configure the Platform in order to govern how available resources will be used. To do this, you will want to familiarize yourself with the System Operation Center. The System Operation Center, or SOC, is the infrastructure management portal for the Apprenda Platform, and, therefore, an essential feature for IT staff. Practically speaking, the Apprenda Platform is operated directly through this portal.

The SOC Dashboard can be accessed via the following URL:

http(s)://apps.[your root url here]/soc/

While the Dashboard for a bustling Platform with numerous applications and Users will display important at-a-glance event and usage information, after a fresh install the most pertinent feature of the SOC Dashboard is the menu bar at the top of the screen:

The different sections of the SOC represented in the menu bar allow IT personnel access to a range of Platform information, such as server details in the Infrastructure section, guest application info through the Applications section, and server events in the Event Logs section.

Although all Platform and guest application components are, of course, housed on the same server on a single-node installation of the Platform (such as your trial installation), for a multi-node Platform instance the Infrastructure page provides important information regarding which servers constituting the Platform can host different types of application components:

(11)

Clicking on the Infrastructure link will initially direct you to the Servers tab, which lists all Platform servers that can host services (as indicated by the icon) and user interfaces (as indicated by the icon), as well as basic information about the server. You can click on the server name for more detailed information, including which specific services and user interfaces are hosted there. The Core Components listing to the left indicates where key Platform components such as Platform Coordination and the Repository are housed, and may include Platform servers that do not host services or UIs.

The SQL Nodes tab will direct you to a similar listing for all Database Instances, which can house database components:

The Core Components section to the left will indicate key information, such as which instance houses the Core Apprenda Database. Additional SQL instances can be added to the Platform via the Add New SQL Node button. As with the Servers tab, you can click on the instance name for more detailed information, including which specific databases are housed on the instance:

(12)

Additionally, the CPU, Memory and Storage allocated for database use on the instance (which would initially have been configured during installation) can be updated from this screen.

Activate Resource Utilization Tracking

Resource management and tracking is a priority for many IT departments. The Apprenda Platform enables IT staff to track CPU and Memory use for guest applications through its Resource Utilization Tracking capabilities.

By default, Resource Utilization Tracking is turned off on a newly installed Platform; however, this, along with most other initial and continued Platform configuration can be conducted primarily through the various options under the System Configurationsection:

In order to activate Resource Utilization Tracking, you should select the Platform Registry menu option, which will take you to a list of currently configured Platform Registry Settings:

(13)

From this page, a search can be performed for the PhysicalHost.TrackUtilization setting, which should already be extant in the Registry Setting with a value of False:

To change the setting, click on its name in the list of search results. This will bring up a screen that will allow you to type in a new value of True and then click on the Save button to update the setting value:

Once the setting is updated, Resource Utilization Tracking will be activated and Apprenda will display CPU and Memory usage data in the SOC. IT Staff can access guest and Platform application usage statistics by navigating to the Applications page. You may notice that the Guest Applications list is already populated at this point with the Account Portal and the Developer Portal, among other Apprenda Platform components. This is because, in addition to any subsequently-created applications, the Platform hosts itself as a PaaS. You can manage Platform components in the same way that you would any other tenant application.

(14)

An Apprenda Application is comprised of three components: the user interface component, through which Users interact with the application, the service component, which performs the application’s operations, and the database component, which houses Application data. The database component is passive and does not need to be deployed, but service and UI components are actively deployed by the Platform so that Users may access and interact with the application. The latter two components also take up additional system resources for each deployed instance, which is why Platform Administrators have the ability to deploy or undeploy instances as needed.

When an instance of an application component is deployed through the Platform, that instance is considered a Workload. On the Applications page, selecting the appropriate application version will link to a list of currently deployed application component Workloads with corresponding usage data:

As needed, the buttons to the right of each Workload can be used to perform actions such as stopping, moving, or undeploying services and UIs. The Components tab on this page allows for deployment of additional application service instances and UI partitions.

(15)

Create Resource Policies/Storage Quotas

Resource Throttling on the Apprenda Platform is designed to give Platform Administrators the ability to limit the resources a given guest application can consume. To manage Resource Policies and Storage Quotas for guest applications, navigate to the Resource Policy Management page in the SOC (via the System Configuration link in the top menu bar).

The CPU and RAM consumption that an application’s service and UI components are limited to is goverened by the Resource Policies you set, and database components’ consumption of MB of storage is similarly goverened by the Storage Quotas you set. If any active, deployable Resource Policies have already been configured for your Platform, you will see them listed on the right side of the screen in the Compute Policies tab. Initially, the Apprenda Platform is installed with an unlimited default Resource Policy. You may use this if you wish, or configure your own policies for guest applications.

To configure a new Resource Policy,click on the New Policy button at the top of the page. This will open a Resource Policy Definition window:

(16)

When creating a policy, you can make it available for Application Services, Application User Interfaces, and Application Databases by selecting the appropriate check-boxes; this allows you create separate resource limits for different application component types. Input a Name for the Policy and, optionally, a Description. You can then check the appropriate boxes to mark the policy as Active and Deployable:

 When a Resource Policy is Active, it is available for Development Teams to assign to application components. When Resource Throttling is enabled, an application’s service, UI and database components must have Active Resource Policies assigned; otherwise, the application cannot be promoted to the Sandbox or Published stages, and components cannot be deployed through the Cloud Control panel of the Developer Portal. Since a Resource Policy might become obsolete, or if it becomes desirable that the Policy be phased out, this setting can be changed to Inactive. In that case, any application components which had been assigned the now-Inactive Resource Policy will retain the ability to be deployed when the application they belong to is launched, and a Platform Administrator can still deploy the application’s UI or service components through the SOC. However, Inactive Resource Policies can’t be newly assigned to application components.  When a Resource Policy is Deployable, components tied to it can be deployed by launching the

application, even if the policy is Inactive. When a Policy is completely phased out, however, it can be marked as Undeployable in order to ensure that it can’t be used at all. Applications with Undeployable components cannot be launched; an application with UI components assigned to Undeployable Resource Policies cannot be promoted to the Sandbox or Published stages. To set the resource limits, slide the CPU Speed, Number of Cores, and Maximum RAM bars to the desired limits (it is possible to set an unlimited amount of CPU speed and/or memory), and click Save.

(17)

Entering “unlimited” will cause components tied to that Resource Policy not to be throttled based on that resource type.

The minimum and maximum limits available, as well as the increments in between, are configurable by changing the following Platform Registry Settings:

Name Explanation Values

ResourcePolicies.MaxCpuCores Maximum CPU cores available for resource policies Number of cores ResourcePolicies.MaxCpuSpeed Maximum CPU speed available for resource policies In MHz

ResourcePolicies.MaxMemory Maximum RAM available for resource policies In MB

ResourcePolicies.MinCpuCores Minimum CPU cores available for resource policies Number of cores ResourcePolicies.MinCpuSpeed Minimum CPU speed available for resource policies In MHz

ResourcePolicies.MinMemory Minimum RAM available for resource policies In MB ResourcePolicies.StepCpuCores Increment between CPU cores when creating resource

policies

Integer > 0 representing a number of cores

ResourcePolicies.StepCpuSpeed Increment between CPU speeds when creating resource policies

Integer > 0 representing MHz ResourcePolicies.StepMemory Increment between RAM allocations when creating

resource policies

Integer > 0 representing MB

Once you have configured Resource Policies, click on the Storage Quotas tab at the top of the Resource Policy Management page to set Storage Quota options for guest applications. You will see a list of existing Quotas, including the Default Storage Quota which has been pre-installed. Click the New Quota

(18)

Input a Name for the Quota, and, optionally, a Description. Similarly to creating Resource Policies, you can choose to make the Quota Active and Deployable. Guest applications are assigned storage capacity in block units, so you can input the Block Size to set the MB size of these blocks, and you can also set a

Max Blocks limit for the maximum number of blocks that an application is allowed to consume.

Once you have created the custom Resource Policies and Storage Quotas you wish to make available, you need to configure how they will be applied to guest applications. On the left side of the Resource Policy Management screen is a Defaults box, which allows you to configure whether, and how, the Apprenda Platform automatically assigns Policies and Quotas to guest applications. Choose which Resource Policy to apply to each application Component by selecting from the corresponding pull-down menu. Check the Automatic Policy Assignment box to automatically assign the selected Policies and Quotas to guest application components whenever an application is Defined in the Apprenda Platform, or leave the box unchecked to require

Development Teams to manually assign Policies and Quotas. Once you are done, click the Save Changes button at the bottom.

Enable Resource Throttling

Once you have configured active, deployable Resource Policies for guest applications, you can enable Resource Throttling, which puts the defined Resource Policies into effect. To do this, simply click on the

Enable Throttling button on the upper left side of the of the Resource Policy Management page. Once enabled, a Disable Throttling button will appear that will allow you to disable Resource Throttling. For more details on how Resource Throttling works, and how to configure advanced options, see the online documentation.

Distribution Settings

Once Resource Throttling is enabled, you can configure how the Apprenda Platform deploys guest application UI and service components among the server types that can support them. At the bottom left of the Resource Policy Management page, you will see the Distribution Strategies section, which includes a pull-down menu each for Service and UI deployments:

For each of these, you can decide to determine future component deployment according to either RAM or CPU

usage. You then must select a Balanced or

(19)

attempt to distribute component deployment evenly among the available servers for that component type. If Compressed is selected, the Platform will attempt to fill up a server before it begins to deploy to a different server. Once you’ve configured the Distribution Strategies to your liking, click the Save Changes

button at the bottom.

Set Development Team Limits

In addition to throttling resources for guest applications, a you can set resource limits per Development Team, thus ensuring that no one Dev Team monopolizes resources on the Platform. Before Resource Limits can be set for Development Teams (where a "Development Team" is defined by Apprenda Platform Development Team Account), at least one active Resource Policy must be configured and Resource Throttling must be enabled. This is because Development Team limits are enforced on an application component deployment basis as determined by the Resource Policies attached to a Dev Team's applications. This means that the Apprenda Platform determines when a Dev Team has met its limit by adding up all of the resource slots that are "reserved" by the Team's deployed applications, and these "reserved" resource slots are determined by guest application Resource Polices.

The total resource allocation for a Development Team will not take into account any application components deployed under an "Unlimited" Resource Policy. Once a Dev Team has met its limit, no further service, UI or database deployments are allowed from that Dev Team's applications. The Team may, however, choose to undeploy instances in order to free up space in their allocation.

Resource limits for Development Teams can be configured through the following Platform Registry Settings:

Name Explanation Values

PhysicalHost.ResourceAllocation. MaxDeveloperCpuAllocation

Sets the total amount, in MHz, of CPU that a given developer's applications can collectively use on the platform

-1 signifies no limit; otherwise any positive integer

PhysicalHost.ResourceAllocation. MaxDeveloperMemoryAllocation

Sets the total amount, in MB, of Memory that a given developer's applications can collectively use on the platform

PhysicalHost.ResourceAllocation.

MaxDeveloperStorageAllocation Sets the total amount, in MB, of Storage that a given developer's applications can collectively use on the platform

For IT Pros: Onboard a Development Team

Open/Invitation Settings

Now that you’ve set up some rules for how resources will be consumed, you are ready to let Development Teams access the Platform. By default, Development Team access is set to Open Signup. With this setting, any Dev Team may navigate to the login page (by default this is http(s)://[your root url here]/) in order to self-provision a Development Team Account without any required permissions. To change this

(20)

setting, choose Platform Access from the top menu bar of the SOC. From the menu that appears, select

Development Teams:

This will bring up a page containing a list of any Existing Development Teams, as well as the current configuration settings concerning Development Team signup. To change this setting from Open Signup to Invite Only Signup, click the blue Switch to Invite Only Signup button at the bottom of the page:

This will generate two new buttons at the bottom of the page: the Generate Invite Code button and the Switch to Open Signup button. To switch back to Open Signup, simply click the latter button. With Invite Only Signup set, however, any Dev Team will now need a single-use Invite Code in order to create an account. To generate such a code, click the Generate Invite Code button, and a window containing the code will pop up:

(21)

You will want to generate one such code and pass it on to each Dev Team that desires to sign up for an account when the Invite Only Signup setting is enabled. Since you will shortly be creating a Development Team Account, if you have selected Invite Only Signup, make a note of this code now for the signup process.

Where a Dev Team Can Sign Up

In the hypothetical use scenario this Guide is taking you through, you are inhabiting the roles of both Platform Administrator and Development Team, but this won’t be the case if your Organization performs a full Apprenda Platform install. In an Organization running the full version of the Platform, the Platform Administrator will need to assist Dev Teams in creating Development Team Accounts. The Platform Administrator should instruct any Development Team that wants to provision an account to navigate to the Apprenda login page (by default this is http(s)://[your root url here]/) and click on the Create a Development Team Account button below the login field. Since in the next section of this Guide you will need to play the role of Developer, you should create an account now. After you click that button, you will then be prompted to enter some basic information in order to create an account, and, if you have enabled Invite Only Signup, the signup process will also ask for a Signup Token (the invitation code that you made a note of previously) in order to finalize the account creation. Each code will become invalid after it has been used once.

Once a Development Team Account has been created, since you are the User who initially created the account, you will be able to configure the Developer Portal and grant Dev Team Account access to additional team members.

For Developers: Write an Apprenda Application

In this section, you will now play the role of a Developer on your Banking Organization’s Development Team, and you will be introduced to the Developer Portal and how to set up additional team member access to the Apprenda Platform. You will also walk through the process of deploying an application on the Apprenda Platform, which includes the following:

 downloading or creating a sample application

 exploring some of the benefits of using the Apprenda API  compiling and packaging an application for Platform usage  configuring multi-tenancy and User permissions

(22)

Set Up the Developer Portal

During Development Team Account creation, information about your Development Team and its Account Administrator (you, since you created the account) is captured. The onboarding process establishes Account and Developer Portals for your Dev Team and configures the Account Administrator using the e-mail address and password supplied during signup; a subscription to both Portals is granted automatically to the Account Administrator. The Developer Portal is the portal through which Development Teams deploy and manage their applications, while the Account Portal is the portal through which the Users of those applications (should the applications require authentication) are managed. Following the initial onboarding process, the Account Administrator is the onlymember of your Dev Team that can log in to your Account and Developer Portals. For more information on how to add and assign account privileges to other Dev Team members, please refer to Apprenda’s full documentation of the process of setting up the Developer Portal. In addition, the Apprenda Cloud Shell can be used to streamline this process through its NewUser command.

Download a Sample Application

You (and any Dev Team member who has been assigned a Platform User account and Developer Portal subscription) will be directed to the Developer Portal Dashboard upon Platform login:

(23)

Under the Start Here heading, you will see the Download & Dissect the Taskr Sample App link. Taskr

is a very simple "to-do list" application that illustrates a number of valuable Apprenda constructs such as application organization, metering hooks, and Role security.

Click on the Download & Dissect the Taskr Sample App link to download this sample. Once the download is finished, find the Taskr With LINQ.zip file and unzip it. Inside you will find a complete Visual Studio solution for Taskr with LINQ (we will cover this in greater depth below). Also included is a pre-packaged Archive.zip file that you may use to upload and deploy Taskr to the Apprenda Platform.

Install the SDK

The Apprenda SDK can be downloaded through the Download & Install the SDK and Developer Tools

link on the Developer Portal Dashboard (this is the page to which Dev Team members will be directed after logging in from the root URL of the Platform). The SDK installer will offer the choice of a complete or custom install; should you choose a custom install, be sure to select at a minimum the SDK, Tools, and Apprenda Cloud Shell to optimize local development and packaging of .NET apps for deployment on the Apprenda Platform:

Please note: you must have Visual Studio installed in order to install the Apprenda SDK and work through the Taskr with LINQ solution. If you do not have Visual Studio, please feel free to skip ahead to the section For Developers: Configure and Deploy a Cloud Application for Testing, where you can walk through .NET application deployment to the Apprenda Platform using the pre-packaged Archive.zip for Taskr as your Deployment Archive.

(24)

The complete installation of the Apprenda SDK includes the following:

 Visual Studio templates and APIs to help you build or configure applications to run on Apprenda  The Archive Builder, which will package a completed solution so that it can be deployed on

Apprenda

 The Apprenda Mocker, which can be used to mimic a live Apprenda environment when deploying apps locally

 The Apprenda Cloud Shell

 Documentation resources and code snippets

Developer tools, such as the Apprenda Mocker and Archive Builder, can be accessed through the Apprenda folder that was installed in your Start Menu; the Apprenda Cloud Shell is a command-line tool. Explore the Apprenda Solution Template

Once the SDK is installed, you will be able to access Visual Studio templates that can be used to build or adapt applications for deployment on the Apprenda Platform:

The Apprenda solution template sets up a “best practices” environment that covers a fairly standard Apprenda Application architecture. It should be noted that this is simply a convenience, and that a solution need not be structured exactly this way; however, it is worth looking into the template’s overall structure and some of the Apprenda-specific artifacts that are included:

1. Overall structure: The structure of an optimally scalable Apprenda solution is a 3-tier structure with a shell for an ASP.NET user interface, a WCF service as a class library (Apprenda provides a hosting

(25)

container for your WCF service when you deploy), and a “Database Scripts” solution folder as a convenient location to store your SQL Server database scripts (see the Working with Data section of our documentation for information on how to supply Apprenda with your database provisioning scripts).

2. Apprenda.mock.xml: Apprenda provides rich API behavior for a variety of application functions such as Role access control and demarcating metered points in the code. When running on Apprenda, your API calls interact with live services provided by Apprenda itself; for local development, the Apprenda SDK provides a “local” implementation of all live services backing the API that mocks the “live” behavior. The Apprenda.mock.xml file allows you to provide mock data and contextual scenarios (that the “local” implementation consumes) to determine local behavior while developing. Although you can hand-edit this file, installing the SDK provides the Apprenda Mocker, a frontend for easily manipulating scenarios in both a static and local testing context.

3. DeploymentManifest.xml: This file allows Apprenda to discover and pre-configure some basic application setup required for deployment to the Platform. The settings that can be configured via this file include Features, Securables, Entitlement Definitions and select application settings.

4. App.config/Web.config: Looking at the ‘Service’ and ‘root’ (ASP.NET) project, you’ll find standard .NET config files. These files are pre-populated with WCF service and client behaviors that are critical for local development. These behaviors automatically provide contextual information regarding the current Tenant and User (among other things) that are used to reconcile API calls and manage other systems level requests. Default configuration provided in these config files allows your local development experience to emulate this behavior; contextual information defined in the Apprenda.mock.xml file is “flowed” from UIs to services, allowing for consistent contextual expectations across the whole call path. The

configuration is predominantly focused on instrumenting WCF client and service behaviors, along with some toggles regarding local Apprenda.mock.xml usage. Any new WCF clients or services must be configured in the same way as the defaults if local API expectations are to be met.

Leverage Apprenda’s Capabilities to Optimize your Application

The benefits of deploying your application on the Apprenda Platform extend far beyond lightning-fast deployment and effortless multi-tenancy. Even without using Apprenda’s API, you can count on inherent Platform features such as High Availability and elasticity to ensure the continued accessibility and optimization of your deployed applications. By leveraging the Apprenda API you can build cloud

(26)

applications faster, as Apprenda’s support for publish/subscribe, caching, messaging and broadcast routing help accelerate application development.

Furthermore, when strategizing how your applications can best fulfill business needs, you should take into account how Apprenda brings to the table truly transformative functionality that makes entitlement and security configuration headaches a thing of the past. This is done in part through Features and

Securables.

In Apprenda, Features are small, uniquely labeled blocks of application code that are intended to be metered, monetized or otherwise entitlement-restricted. They are sections of code that perform some type of transaction that requires access control based on the defined subscription owned by the current runtime User. Apprenda supports four types of Features:

 Toggle: these Features are those that are considered “on” if a User is subscribed to use the Feature or “off” if they are not. This is the simplest Feature type in Apprenda. Example: a Toggle Feature might grant or disallow the ability to say “Hello” to other users within an app.

 Boundary: a Boundary Feature requires that some upper or lower boundary of measurement be adhered to during execution. Example: a Boundary Feature would limit file uploads in an app to under 10MB.

 Limiter: some applications require the ability to track a rolling count that can be compared to some upper maximum. If the rolling count is less than the upper maximum, a certain action is allowed. If the maximum is reached, the action is blocked. Example: a Limiter Feature would limit a User to 10 open projects at a time.

 Block: block Features allow an application to support pre-set quantities of some action where an End User can “stockpile” a quantity of that action and deduct from it as it performs the action. Example: a Block Feature would limit a User to 10 customer service calls a month.

Apprenda allows Developers to identify application functionality that needs to be metered or entitlement-controlled and designate it as such in the application code (see the Features page of our documentation for information on how to do incorporate Features into application code). Details such as meter quantities or how these Features should be grouped together and made available to Users can then be configured—and updated—when the application is deployed to Apprenda.

The Taskr application you downloaded earlier is a simple “to-do list” app through which users can create, tag, and prioritize tasks; it provides an excellent demonstration of two types of Features and how they can be designated in Taskr’s code and then configured through Apprenda.

Priority Management is a simple Toggle Feature that dictates whether or not a task can be assigned a priority of “Low,” “Medium,” or “High.” The Number of Tasks feature is a Limiter Feature that dictates the total number of tasks a given user or group can have open at any one time. The actions of setting priority and creating tasks are determined within Taskr’s code. Once Taskr has been packaged and uploaded to Apprenda, it is then necessary to convey to Apprenda that these actions should be defined as Features;

(27)

this can be done either by manually configuring them through the Developer Portal UI or by indicating these actions as Features in a DeploymentManifest.xml file included with the packaged app.

It is at this point that deployment details, such as how Priority Management should be made available to Users or the Number of Tasks allocated to each User, can be configured. In this way the particulars of who is entitled to perform the actions of creating and prioritizing tasks—as well as the number of tasks that can be created—can be configured through Apprenda rather than through specialized sections of Taskr’s code.

Securables are pieces of code that a Developer has marked as governed by Apprenda’s access control system (see the Security page of our documentation for information on how to do this). A Securable is noted by name, allowing multiple pieces of code to be controlled by a Securable of the same name. Generally, Securables are mapped by name to real-life verbs, such as “Save Invoice” or “Generate Report”. As with Features, Developers can designate Securables in an application’s code, and then the specifics of who is granted access to each Securable can be configured once the application is deployed. Apprenda Platform Users can belong to a variety of Roles defined by the particular End User Account associated with their User profile. Through the Account Portal, defined Roles can be mapped to published Securables for certain types of authorization-restricted applications.

The Taskr application you downloaded earlier, which allows Users to create, prioritize and tag tasks, contains three actions that have been designated as Securables. Delete Tasks grants permission to delete tasks that have already been created. Change Priority determines whether or not a User can modify a task’s prioritization once it has been set. Modify Tags grants permission to create and update the tags that can be associated with tasks.

As with Features, these actions are determined within Taskr’s code. Once Taskr has been packaged and uploaded to Apprenda, it is then necessary to convey to Apprenda that these actions should be defined as Securables; this can be done either by manually configuring them through the Developer Portal UI or by indicating these actions as Securables in a DeploymentManifest.xml file included with the packaged app. Once Taskr has been Published and is subscribed to by End Users, it is then up the End User Account Administrators to determine which individual Users are given permission to perform these actions. This is done by creating Roles that are granted permission to secured actions and then assigning individual Users to the appropriate Roles. In this way the particulars of who is has permission to Delete Tasks, Change Priority, or Modify Tasks can be configured through Apprenda by Taskr’s subscribed End Users, and does not need to be determined in Taskr’s code.

Develop and Test an Application Locally

The For Developers section of our documentation provides useful tutorials that walk through Apprenda-specific application configuration, as well as a variety of topics related to developing your application for the Apprenda Platform.

(28)

Once the initial development phase is complete, you are now ready to execute your application locally. If your application has a persistence layer, executing it locally requires that you provision a database that is used for local development, update the application configuration to point to this database, and configure Visual Studio to start up the services and interface in the correct order. The following outlines these processes for the Taskr with LINQ sample; you will need access to a supported version of SQL Server in order to conduct these steps.

Database Setup: A setup file called ApplicationProvisioning_Script.sql is included at the base of the downloaded sample’s archive. It is also available in Visual Studio under the Database Scripts solution folder.

Create a new database on a supported version of SQL Server, and execute the entire contents of the ApplicationProvisioning_Script.sql script against it to create the database.

Application Configuration: You’ll need to change the database connection string that is used to permit your Taskr services to contact the database that has just been configured in the previous step.

For the Taskr with LINQ sample y,ou’ll need to change the <connectionStrings> section to point to the appropriate database in the App.config files of each service project: Taskr.Admin.Service and

Taskr.Core.Service.

Configure Startup Projects: To run the solution locally, it is necessary to configure Visual Studio to start both services (Taskr.Admin.Service and Taskr.Core.Service) as well as launch the user interface by following these steps:

 Open the solution if necessary.

 Right-click on the Solution node (the top-most tree node) inside of the Solution Explorer pane, and choose Set Startup Projects…

 Choose the Multiple startup projects radio button.

 Change the action to Start and adjust the order for the following projects (see screenshot): 1. Taskr.Admin.Service

2. Taskr.Core.Service 3. Root

(29)

You should now be able to launch the Taskr sample by pressing F5 or choosing Start Debugging from the Debug menu.

Package an Application as an Apprenda Deployment Archive

Once local development of an application is complete, it must be packaged as an Apprenda Deployment Archive before it can be uploaded to and deployed on the Apprenda Platform.

A Deployment Archive is simply a ZIP file with a specific directory structure containing your application components (information on the specific structure of a Deployment Archive, including steps to create it manually, can be found in our online documentation). For now, we will use the Apprenda Cloud Shell tool, which you installed with the Apprenda SDK, to package your Visual Studio solution as a Deployment Archive.

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 to open up the Developer Portal to automation and integration with external systems. Part of this automation includes the ability to package a Visual Studio solution as a Deployment Archive.

Actions performed through the ACS are done through a command-line prompt or Powershell window. Simply typing “acs” and hitting return will generate a list of all available ACS commands (this list, as well as further details on usage and options for all commands, can be found in our online documentation):

(30)

To see usage and option information for the NewPackage command—which you will use to create your Deployment Archive—execute the following: acs Readhelp NewPackage

This will retrieve a list of all required and optional arguments for this command. For our purposes, we will use only the first three arguments:

Apprenda Cloud Shell

Basic usage: acs [command] [options] Available commands:

ConnectCloud Connect to a registered Apprenda cloud DemoteVersion (*) Demotes an application version

DisconnectCloud (*) Disconnect from the Apprenda cloud GetStatistics (*) Get application statistics

NewApplication (*) Create a new Apprenda application NewPackage Create an Apprenda archive

NewUser (*) Creates a new user

NewVersion (*) Create an Apprenda application version PromoteVersion (*) Promotes an application version

ReadHelp Display help

ReadStatus Read connection status

RegisterCloud Register an Apprenda cloud instance RemoveApplication (*) Removes an Apprenda application

RemoveVersion (*) Removes an Apprenda application version SetArchive (*) Sets the archive for a version

SetInstanceCount (*) Scales application components

* Indicates a connection is required to perform the function Additional options:

--NonInteractive When not used, acs will prompt for input of required parameters that were not provided

--Output When followed by an output file, all output will be written both to the console window and the specified file

(31)

The value for –O (“c:\MyArchive.zip” below) can be any filename and location you choose.

The value for –Sln (“c:\PathTo\MyNewApplication.sln” below) must match the path and filename of your Visual Studio solution exactly, including the “.sln” extension.

Include the –b argument to build your solution; you may omit this if your solution has already been built. Altogether, your command should look as follows:

acs NewPackage -O "c:\MyArchive.zip" -Sln "c:\PathTo\MyNewApplication.sln" –b Once this has been successfully run, your Apprenda Deployment Archive can be found in the location you specified.

For Developers: Configure and Deploy a Cloud Application for Testing

This section walks through the process of configuring and deploying a .NET application packaged as a Deployment Archive. While the specific workflows and screenshots depict the sample Taskr application deployed as a multi-tenant, non-billing application, you should feel free to deploy your own properly-packaged .NET application and try out some of the other deployment configurations supported by the Platform. It should also be noted that many configuration decisions described below do not apply to apps deployed as single-tenant applications (and therefore the option to configure them will not appear); furthermore, a number of these configuration decisions are optional even for applications deployed with multi-tenancy.

Create a New Application in the Developer Portal

Now that your Deployment Archive is ready, the application your Dev Team developed (or the sample Taskr app you downloaded) needs to be configured in and deployed through the Apprenda Platform. To begin, click on the Applications option from the menu bar at the top of the screen in the Developer

Create an Apprenda archive: Creates an Apprenda archive from a Visual Studio solution

Basic usage: acs NewPackage [options] Required arguments:

-O (1) The full path and file name (use .zip extension) where the package should be written.

-Sln (1) The solution file to base the package on. Optional arguments:

-B When specified, the solution will be rebuilt before being packaged.

(32)

Portal. This will take you to your Applications page, where you will see a New Application box on the left side of the page:

1. Enter your Application Name and Description as you would like them to appear to End Users. You can edit these later if you choose.

2. Enter an Application Alias, which represents a unique application identifier and will appear as part of the application URL unless a custom URL is specified later. An Application Alias cannot be changed once the application is created.

3. If you wish to go directly to the Application overview for your newly added Application, check the check box as indicated; otherwise you will remain on the Applications page after creation, where you will see your application appear in the list to the right.

4. Click on the Create Application button.

If you did not select the Go to Application overview after creation? option when creating your application, click on the application’s name in the Application List box on the right side of your Application page, which will take you to the Application Overview page:

(33)

When an application is created, the Apprenda Platform automatically creates Version 1 of the application, which will be listed in the Other Versions box on the right side of the page. All newly created versions of an application begin in the Definition stage.

From the Application Overview page, you can edit the name or description of your application by clicking on the Edit Application button on the lower left side of the page. This will generate editable fields that will allow you to make and save your desired changes. As noted above, you cannot change an application’s alias once the application has been created.

Although the Apprenda Platform automatically creates and names Version 1 of your application, you can edit the version name and provide a version-specific description. To do this, you must first click on the Version 1 link in the Other Versions box, which will take you to the Version 1 Overview page for the application:

(34)

Click on the Definition icon in the upper right corner, which will take you to the Definition page. Click on the Edit Information button in the General Information box on the left. This will generate editable fields that will allow you to change the version name and create notes for its changelog. You will also be able to edit the Version Alias (which will become part of the URL through which Users might directly access the Application) as long as the version is still in the Definition stage:

Configure Application Settings

The Application Settings section allows you to modify crucial characteristics of your application, such as tenancy, database handling, and UI deployment. To access Application Settings for an application, navigate to the Application Overview page, where you can click on the Application Settings icon listed on the top right menu. This will take you to the Application Settings page:

(35)

Application Services are enhancements to the way your application is deployed. They build on each other in that higher-level Application Services such as Multi-tenancy require lower-level Application Services such as Authentication and Authorization. Below is a brief description of how your application will be deployed based on the highest-level Application Service selected:

 No Application Services: the application will be deployed as a single-tenant application with no Apprenda-regulated restrictions. For instance, if the application's website is publicly accessible, anyone will be able to launch the application; if it is restricted to an internal network, anyone with network permissions to access the site can launch the application.

 Authentication: the application will be deployed as a single-tenant application, and Apprenda will restrict access to Platform Users. This means that all registered Users on a given Apprenda Platform will be able to launch the application.

 Authorization: the application will be deployed as a single-tenant application, and the Apprenda Platform will restrict access to Platform Users who have been granted explicit access rights to the application. The Development Team that deploys the application controls which Platform Users can launch and access different parts of the application through controls in the Developer Portal.  Multi-tenancy: the application will be deployed as a multi-tenant application, and Apprenda will

restrict access to Platform Users who have been granted explicit access rights to the application. User access is controlled through subscriptions configured through the Account Portal, and can be either configured by the Development Team that deploys the application or can be left for potential User groups to self-provision.

The selection made for some Application Settings will limit the choices available for other Application Settings as described here. For example, enabling all of the Application Services through Multi-tenancy will cause this range of settings to become visible in the Application Settings window:

(36)

In order to test out the full range of Apprenda Platform capabilities, you should check the Multi-tenancy

box under the Application Services heading. By checking this, you are telling the Platform to enable your application to honor and exhibit characteristics of a multi-tenant cloud application even though there is nothing in Taskr’s code that deals with tenancy, Users, or data isolation. In this way Apprenda allows you to focus on application-specific functionality while developing your code and then make the deploy-time decision to publish it with multi-tenancy.

While it’s not necessary to change any of the other settings from their defaults in order to continue with application deployment, you should feel free to try them out. The following is a breakdown of some of the specific Application Settings sections and how they will affect how your application is deployed:

 Data Model: this setting determines how End User data is stored. For applications with multi-tenancy, you can choose either a Commingled data model, which stores data from multiple End Users in the same database and conserves resources because the number of End Users does not determine the number of databases, or an Isolated Database data model, which creates a physical database for each End User.

 User Interface: This setting determines how User Interfaces are deployed and accessed. For applications with multi-tenancy, you can choose either a Commingled UI deployment model, which will map all End Users to one website, or an Isolated UI deployment model, which will create a unique website for each End User. Managed Pipeline Mode is necessarily set to Integrated when Multi-tenancy is enabled.

(37)

 Login Page Stylesheet: End Users who access the Application URL prior to login will be prompted to enter their Apprenda login username and password before they are granted access to their subscribed applications. If desired, a custom stylesheet can be referenced here to customize the look of the Login page that will appear when Users access their applications through this method. For more information, download the Custom Login Style Guide which is linked to in this section of Application Settings.

Upload a Deployment Archive

After adjusting the Application Settings to suit your application, it’s time to upload the Deployment Archive you were working with earlier. Navigate to the recently-created application’s Version 1 Definition page and click on the Runtime Binaries link in the upper right corner, which will take you to the Runtime Binaries page:

In the Definition Snapshot box, click on the View and Define Runtime Binaries link. This will allow you to navigate to and select the ZIP file containing the Deployment Archive for your application. In the screen that appears, click on the Choose File button and browse for and select your Deployment Archive, then click the Upload Version Archive button to start the upload.

The uploading process may take a few minutes and will generate an “Uploading Your Archive” message that includes an updated timer for the upload:

(38)

You will then see either a message that indicates that the archive was uploaded successfully, or a list of errors incurred in the attempted upload. Indicated errors must be resolved before the archive can be successfully uploaded. If no errors occurred, a successful status update will appear:

Edit Entitlements

Since your application now has multi-tenancy enabled, you will need to create an Entitlement Definition that will set the rules by which application Features can be accessed by Users. To do this, navigate to the Application Overview page and click on the Version 1 link. On the Application Version Overview page that appears, click the Set an Active Entitlement Definition link that has now appeared on the right:

After you click the link, the Entitlements page will open. Entitlement Definitions are Developer-defined collections of plans that determine how an application will be accessed by Users. The purpose of plans is to authorize User access to an application and its Features; different plans can be configured in order to authorize different Users to access different Feature configurations. An Entitlement Definition must be published for every multi-tenant application before it can progress in its Lifecycle. For the initial version of an application, the Apprenda Platform automatically creates one blank Entitlement Definition and names it “Standard;” this Entitlement Definition initially appears in the Entitlement Definition List on the

(39)

right side of the page. You can begin to edit the Entitlement Definitions for your application by clicking on the Standard definition in the Entitlement Definitions box on the right:

This will bring up the Standard Entitlement Definition page, through which you can change the Appearance of the Entitlement Definitions (how they are displayed to End Users) as well as the Entitlement Definitions themselves. Click on the User-based Entitlement Definition link in the Entitlement Definitions to the right (it has a red X denoting “Incomplete” next to it):

This will bring up a screen asking you to create an initial plan to be included in your application’s Entitlement Definition. Begin by filling out the Plan Name and Description; you can also limit the number of subscriptions that an End User can add for this plan by checking the appropriate box and entering the desired limit. Next, click the Create Plan button:

(40)

The plan you created will now appear in an Entitlement Definition matrix on the User-based Entitlements screen. However, the plan is still incomplete. Click on the Define Cycle button in the column underneath your plan:

A Define Entitlement Cycle window pops up, and you can choose how often (if at all) t

The Apprenda Platform