Onboarding of Deployed Applications

1.Deployed Applications #

In this section you will understand how to onboard deployed applications. Please make sure you read this section before you onboard your deployed application. Please note that onboarding of deployed and syndicated applications is not the same.

The onboarding process starts after creating a new “Product” in the Marketplace Catalog, as described here.

Cloudesire supports custom ZIP files to provide applications as a package, but we strongly recommend Docker to onboard a new deployed  application.

Cloudesire will provision on the cloud a new VM containing a running instance of the app for each customer.

2.Technical Onboarding #

Software vendors can specify for each product:

  • one or more “Packages” (namely Docker Images or ZIP Packages, containing the application source code)
  • one or more “Modules” (namely a composition of one or more Packages, which will be installed in a VM on the cloud)

For example, an application can be described specifying a Module (with specific cloud resources requirements) which is a composition of a back-end Package (e.g. a Java module exposing REST API plus a PostgreSQL database) and a front-end Package (e.g. a simple and “light” NodeJs application).

Packages

To access the list of the available Packages, click on the “Catalog” > “Packages” menu item on the left.

Vendors Control Panel: Packages

To create a new Package using the ZIP Packaging methodology click on the “New” button.

Vendors Control Panel: ZIP

For each Package, vendors must provide the following information:

  • Name: e.g. back-end
  • Stacks: PHP, Java, Ruby, etc. (also Docker…)
  • Database (optional): MySQL, PostgreSQL, MongoDB.
  • ZIP package: a ZIP package following the specifications provided in this section.
  • Version: whenever the vendor provides a new Package, Cloudesire assigns to it a new version number and stores the previous one. The older Application Packages versions can be used by the vendor in order to execute automatic downgrades of running applications.

When a Package is created, it can be linked to a specific Product Plan, simply selecting it from the list and clicking on the “Attach Package to Module” button. In this way a new Module will be created (if not existent) or the Package will be added to an already existent Module.

Vendors Control Panel: Packages-Modules Links

To simultaneously create one or more Package, corresponding to a composition of Docker images, click on the “New Docker Compose” button. More details on the Docker Packaging are available in this section.

Vendors Control Panel: Packages - Docker

In this case, a Docker Compose string must be provided, and the vendor can also directly link the Packages to a specific Product Plan (crating in this way a new Module, or adding all the Packages to an already existent Module).

Modules

The list of all available modules is provided in the “Catalog” > “Modules” section.

Vendors Control Panel: Modules

By selecting a specific Module and clicking on the “Edit” button on the top-right of the page, software vendors can specify some parameters.

Vendors Control Panel: Modules - VM Sizing

  • CPU Core(s) and RAM (in MB): a slider allows the vendor to choose the preferred configuration (e.g. 1 core + 1Gb, 2 cores + 4Gb, etc.)
  • Disk Space (in GB): a slider allows the vendor to select the quantity of space available for user data

 Advanced Setting for Modules

By clicking on a specific Package name attached to a certain Module, three buttons are shown on the top-right of the interface:

  • Promote to Stable“: to be used to declare the current Package as “stable” in the Module
  • Show Advanced“: to open the Advanced Settings pop-up (see below)
  • Unlink“: to unlink the Package from the Module

Vendors Control Panel: Modules - advanced setttings

The Advanced Settings pop-up provides the following sections:

  • Endpoints Patterns: one or more (custom) access URLs to the module of the product (e.g. /backend, or /stats, etc.); more info at this section
  • Application Metrics: specific application aspects that the vendor intends to monitor or bill to the customer leveraging the pay-per-use paradigm; more info in this section
  • Environment Variables:  environment variables to be injected in the deployed VM and accessed at runtime by the application. More info in this section.
  • Stack Parameters: some language-specific parameters to provide to the Deployer Module (e.g. fine tuning of interpreters or application server). More info in this section.

3.Data Persistence #

Cloudesire allows vendors and customers to perform upgrades and downgades tasks on running applications instances.

To avoid data loss, Cloudesire needs to know where the application data are before performing these tasks.

For this reason, vendors need to specify the file-system path containing the application data (e.g. files/upload) using the common_directories Stack Parameter

4.Endpoints #

For each installed application, Cloudesire provides a default Endpoint to allow end-users ( customers) to access the application.
Furthermore, vendors can specify one or more custom access URLs that will be linked to each specific Module of a given Product (e.g. /backend, or /stats, etc.).

To add a new Endpoint, you need to access to the “Modules” section (more details here), select a specific Module and Package (more details here) and then click on the “Show Advanced” button on the top-right of the page. Furthermore, by accessing to the “Endpoint Patterns” tab it’s possible to fill all the required fields (a Description, a Category and a Value) and click on the “Add” button to finish.

Vendors Control Panel - Endpoints

5.Environment Variables #

Vendors can inject Environment Variables for each application, so feel free to use them to define variables that could be accessed at runtime from your applications.

You can even choose to permit the end-user to the edit some of those variables.

To add a new Environment Variable, vendors need to access to the “Modules” section (more details here), select a specific Module and Package (more details here) and then click on the “Show Advanced” button on the top-right of the page. By accessing to the “Environment Variables” tab vendors can fill all the required fields (the Name and the Value) and click on the “Add” button to finish.

Vendors Control Panel - Environment Variables

There are predefined environment variables set at runtime by the platform and that you could use:

Database access environment variables:

  • CLOUDESIRE_DB_USER username to connect to the database;
  • CLOUDESIRE_DB_PASS password to connect to the database;
  • CLOUDESIRE_DB_NAME name of the available database;
  • CLOUDESIRE_DB_HOST hostname of the database;
  • CLOUDESIRE_VHOST the hostname automatically generated for a running application instance (e.g.: example-123.apps.cloudesire.com)

Customer information environment variables:

  • CD_USER_BILLING_COMPANY_NAME billing company name of the customer;
  • CD_USER_BILLING_TAX_CODE billing tax code of the customer;
  • CD_USER_EMAIL email address of the customer;
  • CD_USER_ENVIRONMENT marketplace identification string of the customer;
  • CD_USER_NAME name of the customer;
  • CD_USER_LANGUAGE language of the customer;
  • CD_USER_PHONE_NUMBER phone number of the customer;
  • CD_USER_SURNAME surname of the customer;
  • CD_USER_USER_NAME username of the customer;

VirtualHost placeholder in environment variables:

It is possible to declare a variable with a placeholder vavlue that will be replaced with the VirtualHost at runtime.

  • %VIRTUAL_HOST% will be replaced with the virtual host (e.g.: example-123.apps.cloudesire.com)

It is also accepted: http://%VIRTUAL_HOST%/ that will be replaced in http://example-123.apps.cloudesire.com/

For stacks-specific environment variables, look in their specific sections:

6.Filesystem Browsing #

Cloudesire allows  vendors to enable a file-system browsing module for each deployed applications instances.

In this way, customers (and vendors) can browse the file-system of the VM containing a running application, upload new files on it, and perform live-editing for textual files (e.g. in order to modify some configuration files).

To enable this feature, it is necessary to specify the common_directories Stack Parameter with a valid file-system path (e.g. files/upload)

7.SSH Access #

Basic SSH access is enabled by default for all vendors, with the unique prerequisite that at least one SSH public key is provided within the vendor profile, before launching a new instance.

Access is available via a default user named app, that is an unprivileged user that can only:

  • access applications data under /srv
  • restart application servers using sudo service command
  • inspect application logs in /var/log

For Docker applications, access to Docker API is restricted for security reasons, but access can be granted if asked for vendors in good standing that have been in activity for at least 6 months.

8.ZIP Packaging #

Before you start onboarding  an application to the marketplace, please take a look to our integration facilities. We provide a staging marketplace where you can register your company, log-in and on-board your application via ZIP package without any worry (also simulating the purchase of your product using demo credit cards). We strongly recommend to upload and test applications on the staging marketplace before publishing them on the public marketplace.

In order to deploy automatically an Application, a ZIP package is required, containing:

  • the web application’s source code or the packaged artifacts;
  • the database data that the application needs to be fully functional (end-users should not do any installation wizard requiring technical skills).

The ZIP package structure must meet the following general criteria:

  • a sql folder if using MySQL, Postgres or ASPNET;
  • a mongodb folder if using MongoDB;
  • a folder with the web application’s code, depending on the language and/or stack used (follow the links below for your application stack).

Before going forward in this documentation, please take a look to the data persistence section in order to avoid data loss in your application.

Application Stacks-specific requirements

We support several application stack, but each application stack has specific aspects that should be kept in consideration.

Database-specific requirements

An application could automatically initialize the database schema at the first run, otherwise it’s possible to insert a database dump into the zip. We adopted the flyway database migration tool, that supports schema versioning by simply creating multiple .sql file starting with the version number. For example:

V1__initial_schema.sql
V2__added_field.sql
V3__added_index.sql

For more information, refer directly to the flyway documentation.

Post-deploy script

It’s possible to automatically execute custom commands on the last stage of the deploy, just in case you need some special hook before the application is ready.

Just put in the application folder a file named cloudesire.build, starting with a standard shebang, e.g.:

#!/bin/bash
echo 'Build completed' > log.txt

This script will run at the end of the deploy process. Keep in mind that if the script return a non-zero value, a failure is returned, and the deploy will be marked as failed.

Environment Variables

For a complete list of environment variables take a look in the available environment variables section.

Example Applications

Here you can find a selection of ready-to-use demo apps, written in several application stacks:

And this is a collection of the most famous open-source applications, already available on the marketplace:

9.Docker Packaging #

Before getting hands dirty, take a look at the understanding Docker page.

When you’re ready, take a look to our integration facilities: we provide a staging marketplace where you can register your company, log-in and on-board your application via Docker Image(s) without any worry (also simulating the purchase of your product using demo credit cards).

The first step is to install the Docker command-line tool on your development machine:

You can find a lot of easy to read documentation on the official Docker User Guide.

Before going forward in this documentation, please take a look to the data persistence section to avoid data loss in your application.

Once a Docker image is created, the only think you need to do to on-board your application in Cloudesire is to create a Package (linked to your application), then select “Docker” in the “Stacks” input-box, and finally type the Docker image URL in the related input-box, as shown in the following screenshot and more detailed described in this section.

Vendors Control Panel - Docker Image

Writing a Dockerfile to build an image

A Dockerfile is required to generate a Docker image for your application.

A lot of useful information about writing a Dockerfile is available at Best practices for writing Dockerfiles.

A simple example of a Dockerfile follows:

FROM    centos:centos6

# Enable EPEL for Node.js
RUN     rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
# Install Node.js and npm
RUN     yum install -y npm

# Bundle app source
COPY . /src
# Install app dependencies
RUN cd /src; npm install

EXPOSE  8080
CMD ["node", "/src/index.js"]

You need to choose a good base image to start from (FROM keyword) on Docker Hub.

There are base images of the most common GNU/Linux distributions:

There are also base images with application stacks preinstalled, along with a onbuild variant, that will ease the packaging of new applications:

A lot of widely used Open-Source software are available too:

To build an image from a Dockerfile in the current directory, use:

docker build -t yourapp:latest .

Then, you can run a container from this image with:

docker run --rm -ti yourapp:latest

Requirements and Suggestions

There are some things to keep in mind to use Docker efficiently with Cloudesire.

Data volumes

Remember to define volumes in your container to persist data across launches.

Container composition

It is highly recommended to use multiple images for each component of your application, instead of a single container running everything.

A tool named Composer assists you in running multiple containers together within your machine, to test that everything is working.

Network

Cloudesire runs containers in the same network, meaning that all the running containers can directly talk to each other. A container on the network can be reached through its name.

Environment variables

For a complete list of environment variables take a look in the available environment variables section.

SSL support

Cloudesire manages automatically a reverse proxy in front of your application, so you don’t need to include HTTPS support in the container, and we also support the great CloudFlare.

Private Repository

ClouDesire offers a private repository where vendors can privately push their images. This service is free while in BETA.

First, login with your user credentials on the Docker cli:

docker login docker.<marketplace-hostname>

Images should be tagged with a pattern like:

docker.<marketplace-hostname>/<company-indentifier>/<image-name>:<version>

Note: check your company-indentifier in the edit profile section of the control panel.

Tag could be assigned to an existing image with:

docker tag <existing-image>:<version> docker.<marketplace-hostname>/<company-indentifier>/<image-name>:<version>

or a new image can be built with:

docker build -t docker.<marketplace-hostname>/<company-indentifier>/<image-name>:<version> .

If successful, the image can be pushed to the private repository:

docker push docker.<marketplace-hostname>/<company-indentifier>/<image-name>:<version>

Example of commands to push an image to the appshop.cloud marketplace

docker login docker.appshop.cloud
docker build -t myimage:1.0 .
docker tag myimage:1.0 docker.appshop.cloud/mycompany/myimage:1.0
docker push docker.appshop.cloud/mycompany/myimage:1.0

At this point, an application can be configured using

docker.<marketplace-hostname>/<company-indentifier>/<image-name>:<version>

in the Cloudesire onboarding interfaces, simply creating a Package (linked to your application) and selecting “Docker” in the “Stacks” input-box, as described in this section.

10.Stack Parameters #

When defining a Docker or ZIP module in Cloudesire, you can specify some parameters:

Name Usage Cardinality Type Example Description
expose Docker N int 8080 Generates env vars as if it is linked
privileged Docker 1 bool true If container requires high privileges
common_directories Docker / ZIP N string files/upload A path to data, relative to /
open_ports Docker N int 9000 A port that should be open on the firewall
web_port Docker 1 int 8000 The port of the webapp that should be proxied

How to add Stack Parameters

To add a new Stack Parameter, you need to access to the “Modules” section (more details here), select a specific Module and Package (more details here) and then click on the “Show Advanced” button on the top-right of the page. Furthermore, by accessing to the “Stack Parameters Values” tab it’s possible to select a specific parameter specifying a value for it.  When you’re done, click on the “Add” button to finish.

Vendors Control Panel - Stack Parameters

11.Sandboxing #

Once finished the technical onboarding of your deployed app, it’s time to test its self-provisioning on the cloud!

Let’s start by selecting a plan, and by clicking on the corresponding “Sandbox” button in the “Actions” column; then select one of the supported cloud providers on which you want to start the testing deploy of your app.

The provisioning process will start immediately; it will require few minutes, depending on the cloud provider performances, the “weight” of your app, and other factors.

You’ll be redirected on another view, where you can follow the provisioning steps; at the end of the deployment, the platform will provide the following interface:

The following elements are available:

  • General Info: the name of the product, its logo, the name of the vendor, the current deployment status
  • Subscription Details: the subscription type (which is Sandbox in this case, but will be Normal for the real purchased instances of the application), the creation / expiration date, the customer name (which is “dummy” for Sandbox orders)  and 2 separate sections for allowing to access the related invoices and/or orders
  • VM Details: the sizing (CPU, RAM) and the public IP address of the virtual instance hosting the running application
  • Resource usage: 2 gauges for highlighting the current Disk Space and Bandwidth usage
  • Application Endpoints: the actual values of the application endpoints previously defined by the vendor
  • Deployment Log: shows the deployment steps, updated in real-time
  • Debug: provides the real-time application and/or system logs, collected from the virtual machines
  • Charts: a series of real-time monitoring charts, grouped into Disk / Network / System sections

 

12.Video Tutorials #

Onboarding of Deployed Applications

Custom Metrics for Deployed Applications

How to Enable Cloud Providers during the Onboarding of Deployed Applications

Real-Time Monitoring of Deployed Applications & IAAS Resources

Help Guide Powered by Documentor
Suggest Edit