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 will provision on the cloud a new VM containing a running instance of the app for each customer.
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).
To access the list of the available Packages, click on the “Catalog” > “Packages” menu item on the left.
To create a new Package using the ZIP Packaging methodology click on the “New” button.
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.
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.
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).
The list of all available modules is provided in the “Catalog” > “Modules” section.
By selecting a specific Module and clicking on the “Edit” button on the top-right of the page, software vendors can specify some parameters.
- 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
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.
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
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 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.
There are predefined environment variables set at runtime by the platform and that you could use:
Database access environment variables:
CLOUDESIRE_DB_USERusername to connect to the database;
CLOUDESIRE_DB_PASSpassword to connect to the database;
CLOUDESIRE_DB_NAMEname of the available database;
CLOUDESIRE_DB_HOSThostname of the database;
CLOUDESIRE_VHOSTthe hostname automatically generated for a running application instance (e.g.: example-123.apps.cloudesire.com)
Customer information environment variables:
CD_USER_BILLING_COMPANY_NAMEbilling company name of the customer;
CD_USER_BILLING_TAX_CODEbilling tax code of the customer;
CD_USER_EMAILemail address of the customer;
CD_USER_ENVIRONMENTmarketplace identification string of the customer;
CD_USER_NAMEname of the customer;
CD_USER_LANGUAGElanguage of the customer;
CD_USER_PHONE_NUMBERphone number of the customer;
CD_USER_SURNAMEsurname of the customer;
CD_USER_USER_NAMEusername 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:
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)
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
- restart application servers using
- inspect application logs in
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.
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.
- How-to package .NET applications
- How-to package CGI applications
- How-to package Django applications
- How-to package Java applications
- How-to package NodeJS applications
- How-to package PHP applications
- How-to package Ruby applications
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.
- How-to package applications using MongoDB
- How-to package applications using MySQL
- How-to package applications using PostgreSQL
- How-to package applications using MSSQL Server
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.
For a complete list of environment variables take a look in the available environment variables section.
Here you can find a selection of ready-to-use demo apps, written in several application stacks:
- PHP5 + MySQL
- PHP5 + MongoDB
- Ruby on Rails + PostgreSQL
- Django + PostgreSQL
- Java6 + MySQL
- NodeJS + MongoDB
- ASP.NET + SQL Server Express
- CGI-BIN + PostgreSQL
And this is a collection of the most famous open-source applications, already available on the marketplace:
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.
Writing a Dockerfile to build an image
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
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.
Remember to define volumes in your container to persist data across launches.
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.
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.
For a complete list of environment variables take a look in the available environment variables section.
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.
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:
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
|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.
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